Installatron Core Integration API

API Specification, version 1.3 (2011-08-01)

1. Introduction
1.1. Purpose
      1.1.1. Stop! Read me first
      1.1.2. What is a "control panel"?
1.2. Requirements
1.3. Support and Licensing
1.4. API Changes


2. Getting Started
2.1. Download and install Installatron Server
2.2. The Integration API Files
2.3. Adding Installatron to the Control Panel UI


3. frontend.php in Detail
3.1. getUrlApp()
3.2. getUrlImg()
3.3. getUrlDatabaseManager(), getUrlFileManager(), and getUrlFileManagerFile()


4. backend.php in Detail
4.1. getName()
4.2. getVersion()
4.3. initSession()
4.4. getUser($u)
4.5. getDBs($type)
4.6. generateDB($type)
4.7. createDB($name, $user, $pass, $type, $host)
4.8. removeDB($name, $type)
4.9. (optional) getPackages()


5. Troubleshooting
5.1. .so warnings and errors


6. Tips
6.1. Passing values from index.php to backend.php


7. Glossary of Terms

1. Introduction

1.1. Purpose

The Installatron Core Integration API enables any web hosting system (aka "control panel") to integrate the Installatron application automation platform. This document describes the integration process in detail.

1.1.1. Stop! Read me first

This API is most commonly used to integrate support for additional control panels into Installatron Plugin. It's also used for advanced Installatron Server integrations that the standard Installatron Server API can't handle. For increased ease of use, we recommend the Installatron Server API over this API whenever possible.

1.1.2. What is a "control panel"?

A control panel, from Installatron's point of view, is a GUI system that allows "web hosting" users to login and customize their hosting. A user will have one or more domains and possibly sub-domains, and the files associated with those domains will be stored within a logical directory structure on the server (or networked) storage device.

The control panel should treat Installatron like any other tool within its GUI. So just as a user can only access their "Sub-domains" tool when they are logged in, the control panel should also block access to Installatron unless the user is logged in.

At its very simplest, the control panel could be little more than a HTTP request handler, one that simply redirects any Installatron URL to Installatron (see section 2.3.2 below). In this "simplest" approach, the user values, rather than being dynamically gathered in the methods of this API, could be hard-coded for a single faux "user". However, it is more likely that you will want to have the methods documented in this API gather real information about real users on your hosting service.

1.2. Requirements

You require at least one server with a permanent internet connection for licensing and updating purposes.

This can be the same server the existing control panel is deployed on, as is the case for control panels like DirectAdmin and cPanel, or in the case of a distributed deployment, Installatron can be on one server while applications are deployed over a FTP layer to one or more remote servers.

1.3. Support and Licensing

See the Installatron Server website for information on support and licensing for proprietary web hosting systems.

If your web hosting system is a public product that anyone can license and use, we may be able to include your integration into our Installatron Plugin product. We recommend contacting us to discuss options.

Open a ticket if you have any questions.

1.4. API Changes

• 1.3.1 (2011-08-23) - Removed reference to getDomains.
• 1.3.0 (2011-08-01) - getUser() and other methods revised to make integrations more intuitive. All changes are fully backwards compatible.
• 1.2.2 (2009-04-16) - Added support for "mysql_host" getUser() return value. This allows better support for distributed MySQL servers. This is supported as of Installatron 6.0.0.

2. Getting Started

Adding support to Installatron for your control panel involves installing Installatron, implementing the API files for your control panel, and adding Installatron to your control panel's user-interface. These tasks are discussed in this section.

2.1. Download and install Installatron Server

On Linux/FreBSD/UNIX servers these commands executed as the root user will install Installatron Server:

mkdir -p /var/installatron/custompanel
wget http://data1.installatron.com/installatron/installatron_setup.sh
chmod 755 installatron_setup.sh
./installatron_setup.sh -f --edge

On Windows, simply execute the installatron_setup.exe executable as an administrative user.

Installatron core files will be installed here:

/usr/local/installatron/

And the data files will be installed here:

/var/installatron/

On Windows these paths translate roughly to \Program Files\Installatron and \Program Files\Installatron\Data, respectively.

2.2. The Integration API Files

Two PHP object files are used; one file to help integrate Installatron into your control panel user interface, and a second file to tell Installatron how to interact with the control panel backend, its users, and the server environment it is running on.

2.2.1. frontend.php

Create a file named frontend.php in this location:

/var/installatron/custompanel/frontend.php

You can download a template for frontend.php here: http://data1.installatron.com/installatron/is_frontend.phps
This template contains the essential methods for a standard implementation. More methods are documented below.

The frontend.php file deals with URLs and user-interface integration.

See section 3 below for a closer look at each method in the frontend.php file.

2.2.2. backend.php

Create a file named backend.php in this location:

/var/installatron/custompanel/backend.php

You can download a template for backend.php here: http://data1.installatron.com/installatron/is_backend.phps
This template contains the essential methods for a standard implementation. More methods are documented below.

The backend.php file contains a set of methods/functions that interact with your control panel.

For example, if Installatron needs a list of virtual hosts owned by a user then it calls getUser() in backend.php, which, by whatever method works best for your control panel, should return an array of information for the specified user (see getUser documentation below). If your control panel has a plugin API then getUser() might make an call to the panel API and request the required information, or alternatively it could parse a flat text file for the user information. The method is up to you, and this applies to all the methods in backend.php.

See section 4 below for a closer look at each method in the backend.php file.

2.3. Adding Installatron to the Control Panel UI

The control panel is a UI system that your users log into to access Installatron, and that you log into to access Installatron's administration tools.

When Installatron is installed on a DirectAdmin, cPanel/WHM, or Plesk server, the installer adds Installatron to the control panel as a plugin. The plugin systems of those control panels automatically add Installatron's links to the control panel theme, allow access to Installatron only if a user is logged in, and redirect Installatron HTTP requests to Installatron.

If your control panel has a plugin system, then you just need to create the the necessary plugin files for Installatron. If your panel doesn't have a plugin system, you can get the same results with a couple of simple edits, as detailed in the rest of this section.

2.3.1. Adding Links to the Control Panel UI

Installatron requires the addition of two links to your control panel's UI. Firstly, a user-level link to Installatron:

/installatron

And also the admin-level and reseller-level links to Installatron's administration page:

/installatron/index.php#cmd=admin

These links can be added by your control panel's plugin system, if it has a plugin system, or by manually editing the UI. They simply give the user something to click in order to access Installatron. Installatron will give an error if a user tries to a page they don't have access to, though ideally your control panel will hide that links that the user can't use. In cPanel, for example, the admin link is only added to the WHM (administration) tool, and in DirectAdmin it is only seen at the admin level.

If your UI includes icons, you can use any of these for the Installatron links:



2.3.2. Redirect Control Panel Links to Installatron

You next need to modify your control panel's HTTP request handler so that clicking the http://yourdomain:port/installatron links in your control panel UI load here:

/var/installatron/frontend

When HTTP request handling is correctly set up, this URL:

http://yourdomain:port/installatron

-should load here:

/var/installatron/frontend/index.php

-and this URL:

http://yourdomain:port/installatron/images/

-should load here:

/var/installatron/frontend/images/

Once those are working, the control panel GUI modifications are complete.

2.3.3. Authenticating Users

Installatron itself has no login or authentication system. Instead, Installatron is designed to be called by a control panel UI that has already authenticated the user.

Installatron should only be allowed to load if the user is logged into your control panel. If the user is not logged in, they should be redirected to the control panel's login page, and only returned to /installatron once a login is established.

3. frontend.php in Detail

The frontend.php file deals with URLs and user-interface integration.

3.1. getUrlApp()

This method returns a path to Installatron, relative to the control panel's home URL. The value should begin with the a forward slash (/).

3.1.1. Example Code

If you have followed the setup described in section 2.3.2 above, this is all you will need:

/**
* URL path to Installatron.
*
* @return  string  Path to Installatron
*/
protected function getUrlApp()
{
    return "/installatron/index.php";
}

Some control panels communicate with plugins through a specific URL path, as shown in this example code which is taken from the cPanel/WHM API file:

/**
* URL path to Installatron.
*
* @return  string  Path to Installatron
*/
protected function getUrlApp()
{
    return "/3rdparty/installatron/index.php";
}

3.2. getUrlImg()

This method returns a path to Installatron's images directory, relative to the control panel's home URL. The value should end without a forward slash.

This is usually just the getUrlApp() directory (see section 3.1 above) with /images appended:

3.2.1. Example Code

If you have followed the setup described in section 2.3.2 above, this code will simply be:

/**
* URL path to Installatron's images.
*
* @return  string  Path to Installatron's images
*/
protected function getUrlImg()
{
    return "/installatron/images";
}

Some control panels, however, communicate with plugins through a specific URL path, as shown in this example code which is taken from the cPanel/WHM API file:

/**
* URL path to Installatron's images.
*
* @return  string  Path to Installatron's images
*/
protected function getUrlApp()
{
    return "/3rdparty/installatron/images";
}

3.2.2. Example Return Value

If you have followed the setup described in section 2.3.2 above, this value will simply be:

"/installatron/images"

3.3. getUrlDatabaseManager(), getUrlFileManager(), and getUrlFileManagerFile()

These methods returns a URL (as either a path relative to the control panel address, or a full URL) to external database/directory/file viewing tools.

Include these methods in your API to allow your users to click database/directory/files links in Installatron (eg. on the user's "My Applications" tab) to view the selected content. These are curtesy links, and are not related to the running of Installatron.

3.3.1. Example Code

/** URL to an external database viewing tool
*
* @param   string  Database name
* @return  string  Relative or full URL
*/
protected function getUrlDatabaseManager($database)
{
	return "/database/?show=".urlencode($database);
}

/** URL to an external directory viewing tool
*
* @param   string  Directory path
* @return  string  Relative or full URL
*/
protected function getUrlFileManager($directory)
{
	return "/filemanager/?dir=".urlencode($directory);
}

/** URL to an external file viewing tool
*
* @param   string  File path
* @return  string  Relative or full URL
*/
protected function getUrlFileManagerFile($file)
{
	return "/filemanager/?file=".urlencode($file);
}

4. backend.php in Detail

The backend.php file contains a set of methods/functions that interact with your hosting and server environments.

4.1. getName()

This method informs Installatron of your control panel name.

/**
 * The control panel name.
 *
 * @return  string   Control panel name
 */
public function getName()
{
	return "Control Panel Name";
}

The control panel name is used in the return to Control Panel Name link at the top/right of the Installatron page when Installatron is operating in un-embedded mode.

4.2. getVersion()

This method returns the current version of your control panel (as a string).

This is only used to keep a record of what version of the control panel the script was installed on.

4.9.1. Example Code

/**
* The control panel version.
*
* @return  string   Control panel version
*/
public function getVersion()
{
    return get_file_contents('/var/mycontrolpanel/datafiles/control_panel_version.inc');
}

4.9.2. Example Return Value

"3.4.4"

4.3. initSession()

This method initializes a session for the effective user. This is achieved by setting itron::$session["user"] with the username of the effective user.

Before initSession() is called, Installatron already has set itron::$session["user"] to the POSIX username of the system user that has invoked Installatron. If your control panel is system-user orientated (that is, each control panel user is also a system user and so Installatron was invoked with the correct user), then you can omit this method from your API and let the base class handle the task. However, if your control panel uses a single system-user for all actions (such as a "nobody" user), then you will need to include this method and include in it a way to determine the "effective user", and set itron::$session["user"] with that value.

After initSession() is called, Installatron will call getUser() for the user set.

Return true for success and false for failure.

4.3.1. Example Code

This example code is for the case where the control panel uses a single system-user for all actions, regardless of which user is logged in, and so we need to override the default value in itron::$session["user"]:

/**
 * Initialize a session for the effective user.
 *
 * @return  bool    true if successful; false otherwise
 */
public function initSession()
{
    // putenv("CURRENT_USER", "the effective user"); defines $_SERVER["CURRENT_USER"] in frontend/index.php.
    if (isset($_SERVER["CURRENT_USER"]))
    {
        itron::$session["user"] = $_SERVER["CURRENT_USER"];
        return true;
    }
    return false;
}

4.4. getUser($u)

This method returns an array of information about a user of your control panel.

Each user represents a single web hosting account. To link multiple users, for example to display a list of domains from multiple hosting accounts when installing an application, define the optional "sub_user" return value (see 4.4.2 example code below).

4.4.1. List of getUser() Return Values

value	description
type	user || reseller || admin (determines which Installatron administration features the user can access)
package	the group/package the user belongs to. Leave empty if there is no package.
parent	username of this user's creator/owner (omit this return value for the highest-level user)
email	user's email address (used for pre-configured install values and email notifications)
vhosts	an array containing a list of each domain hosted by this account and its corresponding directory on the filesystem relative to path_local
path_home	the local server's path to home directory of this account, without a trailing directory separator. For example: /home/user/domains/domain.com/httpdocs
path_remote (optional)	the address of path_home as seen by the FTP layer, without a trailing directory separator. Only define this if deploying applications over a FTP layer. For example: ftp://user:pass@remotehost
path_backups (optional)	the local server's path to a directory where installed application backups will be saved, without a trailing directory separator. This directory should be located inside path_home, and the default location is "{path_home}/installatron_backups/".
sub_users (optional)	an array containing a list of additional users that the user should inherit vhosts from
system_user (optional)	the POSIX UID for this website that should be used to CHOWN files and execute binaries like mysqldump. Only define this when path_remote is NOT defined.
system_group (optional)	he POSIX GID for this website that should be used to CHOWN files and execute binaries like mysqldump. Only define this when path_remote is NOT defined.
mysql_host (optional)	FQDN of mysql server for the user (defaults to the Mysql Host Global Administrative Setting or "localhost")
owner (optional)	the control panel user that owns this website directly. Only define this when the "effective" control panel user doesn't directly hold ownership. Plesk is a good example of this, where multiple control panel users can access the same set of websites, and each website itself is owned by a website-level control panel user.

Regarding the admin "type", note that the user will only gain full access to Installatron's administration panel if their username is set in /usr/local/installatron/etc/settings.ini. For example, if root is the name of the admin user, admin=root should be set in settings.ini.

4.4.2. Example Code

/**
* Information about a given control panel user.
*
* @param   string  Username
* @return  array   User information
*/
public function getUser($u)
{
    // if it's the admin user set in /usr/local/installatron/etc/settings.ini, just return.
    if ( $u === itron::$ini["admin"] )
    {
        return array(
            "type" => "admin",
            "email" => "admin@host.com"
        );
    }

    // client1234 is comprised of two hosting accounts, identified by domain344 and domain360.
    // To compile a list of installs for My Applications and a list of domains for each install,
    // Installatron will call getUser() for each of these hosting accounts.
    // Tip: In Plesk nomenclature, client1234 would be considered a "client" type login.
    else if ( $u === "client1234" )
    {
        return array(
            "type" => "user",
            "parent" => itron::$ini["admin"],
            "sub_users" => array(
                "domain344",
                "domain360"
            )
        );
    }

    // domain344 represents the hosting account at /var/www/vhosts/bob.com on server23.host.com.
    // Tip: In Plesk nomenclature, domain344 would be considered a "domain" type login.
    else if ( $u === "domain344" )
    {
        return array(
            "type" => "user",
            "parent" => "client1234",
            "path_home" => "/var/www/vhosts/bob.com",
            "path_remote" => "ftp://".urlencode("user").":".urlencode("pass word")."@server23.host.com",
            "package" => "bronze",
            "email" => "user@domain.com",
            "vhosts" => array(
                "http://bob.com" => "httpdocs",
                "http://www.bob.com" => "httpdocs",
                "http://sub.bob.com" => "sub/httpdocs",
                "http://host.com/~bob" => "httpdocs"
            )
        );
    }

    // Keep in mind defining "sub_users" is completely optional.
    // It's perfectly acceptable to set itron::$session["effective_user"] in initSession() directly to
    // a user that represents a hosting account.

}

4.5. getDBs($type)

This method returns an array of databases owned by the effective control panel user.

This is used during install when the user chooses to manage the database settings manually, rather than have Installatron automatically manage the database settings.

Note that at this time Installatron only supports MySQL databases.

4.5.1. Example Code

/**
* Databases owned by the effective user.
*
* @param   string  Database type (typically "mysql", can also be "mssql")
* @return  array   User's databases
*/
public function getDBs($type)
{
    $u = itron::$session["effective_user"];

    switch($type)
    {
    case "mysql":
        // example code for case where the control panel user information
        // is stored in an XML file, and where database names are prefixed
        // by the username and an underscore
        $xml = simplexml_load_file('/var/mycontrolpanel/datafiles/user_list.xml');
        $r = array();
        foreach ($xml->xpath("/users/user[user-name=\"$u\"]/databases/*") as $database)
        {
            $r[] = $u."_".$database;
        }
    }
    return $r;
}

4.5.2. Example Return Value

On a control panel where the database names are prefixed by the username and an underscore:

array(
    "bob_forum1",
    "bob_phpbbtest",
    "bob_ibC8Mjoom"
)

4.6. generateDB($type)

This method generates a database to be passed to the createDB method.

Note: It's possible to re-use databases by returning an existing database with a unique table prefix.

4.6.1. Example Code

/**
* Generate a database to be passed to createDB.
*
* @param   string  Database type (typically "mysql", can also be "mssql")
* @return  array   (Database name, database user, database password, database host, database table prefix)
*/
public function generateDB($type)
{
	$existingDbs = $this->getDBs($type);
	$prefix = itron::$session["effective_user"]."_";

	$len_less_prefix = $this->dbNameMaxLength-strlen($prefix);
	do
	{
		$db_table_prefix = strtolower(i_lib::randstr(1,true).i_lib::randstr(3));
		$db_name = $prefix.substr($db_table_prefix, 0, $len_less_prefix);
	}
	while ( in_array($db_name,$existingDbs) );

	$db_user = $db_name;
	$db_pass = null;//tell Installatron to create a randomized value.
	$db_host = null;//tell Installatron to use the mysql_host value returned by getUser()

	return array($db_name, $db_user, $db_pass, $db_host, $db_table_prefix);
}

4.7. createDB($name, $user, $pass, $type, $host)

This method creates a database using the passed values.

This is used when the user chooses to have Installatron automatically manage the database settings. Installatron will generate a database name and password using the generateDB method and then call this method to create the database.

Note that at this time Installatron only supports MySQL databases.

Return true for success and false for failure.

4.7.1. Incoming Variables

variable	description
$name	the Installatron-generated database name (see generateDB)
$user	the Installatron-generated database username (see generateDB)
$pass	the Installatron-generated database password (see generateDB)
$type	the database type (see generateDB)
$host	the Installatron-generated database server (see generateDB)

4.7.2. Example Code

/**
* Create a database
*
* @param   string  New database name. This is typically set by generateDB.
* @param   string  New database username. This is typically set by generateDB.
* @param   string  New database username's password. This is typically set by generateDB.
* @param   string  Database type (typically "mysql", can also be "mssql")
* @param   string  New database's server. This is typically set by generateDB.
* @return  bool    true if sucessful; false otherwise
*/
public function createDB($name, $user, $pass, $type, $host)
{
    switch($type)
    {
    case "mysql":
        // you can create the database here
        // Installatron's core control panel APIs all make use
        // of the control panel's plugin API to create databases
        return true;
    }
    return false;
}

4.8. removeDB($name, $type)

This method deletes a database named $name. If your control panel ties each database with a specific usernames, this method can also remove the corresponding username.

This is used when uninstalling a script.

Note that at this time Installatron only supports MySQL databases.

Return true for success and false for failure.

4.8.1. Example Code

/**
* Remove a database.
*
* If database usernamess are tied to database names,
* the database username can also be removed.
*
* @param   string  Name of database to be removed
* @param   string  Database type
* @return  bool    true if sucessful; false otherwise
*/
public function removeDB($name, $type)
{
    switch($type)
    {
    case "mysql":
        // you can delete the database here
        // this might be a call to your control panel's API,
        // or could be something like this:
        $db = mysql_connect("localhost", "root", "rootspass");
        mysql_query("DROP DATABASE ".mysql_real_escape_string($name, $db), $db);
        mysql_close($db);
        return true;
    }
    return false;
}

4.9. (optional) getPackages()

This method returns an array of "packages" that can be used by the effective user. This is called by Installatron Administration, so the effective user will be a reseller or the admin user.

In web hosting, packages are used to group users, allowing each group of users to receive different hosting features. Installatron can make use of packages/groups in the same way, allowing you to easily limit which scripts the different groups will be able to install (using the Access Groups tool). If your control panel doesn't use packages, or you don't want to support them in Installatron, don't define this method.

This method is only used by a reseller or the admin user.

4.9.1. Example Code

/**
* Usage information about a user.
*
* @return  array  List of packages
*/
public function getPackages()
{
    // example code for case where the control panel statistics information
    // is stored in an XML file; this could gather information from an INI
    // file, or a database, or via your control panel's plugin API
    $xml = simplexml_load_file('/var/mycontrolpanel/datafiles/packages.xml');
    $r = array();
    foreach ($xml->xpath("/packages/*") as $package)
    {
        $r[] = $package;
    }
    return $r;
}

4.9.2. Example Return Value

array(
    "platinum",
    "gold",
    "silver",
    "resellers"
)

5. Troubleshooting

5.1. .so warnings and errors

.so warnings and errors are not a problem, though you may need to let Installatron know about common modules (like mysql or ctype) by adding them to:

/usr/local/installatron/etc/php.ini

6. Tips

6.1. Passing values from index.php to backend.php

You can pass variables to the backend using the putenv PHP command. For example, you might add this to /var/installatron/frontend/index.php:

putenv("TEST", "abc");

And then in the backend API methods you could access "TEST" as:

$_SERVER["TEST"]

7. Glossary of Terms

admin - The admin is the single user with access to the full Installatron administration system. The admin user is identified by an admin= line in /usr/local/installatron/etc/settings.ini and also by the type session value set by the getUser() method (see section 4.2 above). Only if these two values match will the effective user be allowed access to administration. (see also: reseller and user)

backend - The portion of the API that interfaces between Installatron and your users, their files, and the server environment.

control panel - Software that automates the management of hosting users on an internet server (eg. DirectAdmin, Plesk, cPanel).

control panel user - A user of your control panel GUI. (see also: effective user and system user)

cpanel/whm - A web hosting control panel that is internally supported by Installatron. cPanel is the user-level control panel and WHM is the administration system.

directadmin - A web hosting control panel that is internally supported by Installatron. The base code of all methods in this API is for DirectAdmin.

domain-orientated - A type of control panel where login to the control panel is on a per-domain basis (eg. Plesk). Many of the optional methods in this API exist for Plesk, where some types of users have no files or home directory; they instead have a list of domains, and it is the domain logins that have the files and home directory, hence "domain-orientated".

effective user - The user that all current actions are being performed for. This is the same as the logged in user except when an administrator or reseller is performing a user-level action, such as upgrading a user's install. (see also: control panel user and system user)

frontend - The portion of the API that interfaces between Installatron and your control panel's GUI.

plesk - A web hosting control panel that is internally supported by Installatron, for both Linux and Windows.

reseller - A reseller is a user that owns other users. The admin user is technically also a reseller, however in the Installatron system a reseller is a user that owns other users but that isn't the admin. The reseller has access to an administration panel that allows them to customize Installatron for their users. A reseller is identified by the type session value set by the getUser() method (see section 4.2 above). (see also: admin and user)

system user - A user on the operating system. (see also: control panel user and effective user)

user - A user has access to only the user-level features of Installatron. A user is identified by the type session value set by the getUser() method (see section 4.2 above). (see also: admin and reseller)

user-orientated - A type of control panel where each control panel user is also a system-user (eg. DirectAdmin, cPanel). All the optional methods can be left out of the API if the control panel is user-orientated, as the base code for those methods should work.