Installatron Control Panel Integration

Siapa tahu bisa berbagi...............

Installatron Control Panel Integration
API Specification, version 1.1.0 (2008-12-31)


1 Introduction
1.1 API Purpose
1.1.1 What is a Control Panel?
1.2 Requirements

2 Overview
2.1 Installing Installatron
2.2 The Control Panel API Files
2.3 Adding Installatron to the Control Panel GUI

3 frontend.php in Detail
3.1 getUrlApp()
3.2 getUrlImg()
3.3 mergeHttpGetInput()
3.4 mergeHttpPostInput()

4 backend.php in Detail
4.1 __construct()
4.2 getUser()
4.3 getUsers()
4.4 getPackages()
4.5 getUsage()
4.6 getDomains()
4.7 getSubDomainsOf()
4.8 getDBs()
4.9 getVersion()
4.10 isHttpRequest()
4.11 getInstallPath()
4.12 getHomeDirectories()
4.13 getDataDirectories()
4.14 createDB()
4.15 removeDB()
4.16 initSession()
4.17 setEffectiveUser()

5 Glossary of Terms

Spoiler:

1 Introduction

1.1 API Purpose

The Installatron Control Panel Integration API allows Installatron to be integrated into any web server control panel software. This document describes how to add Installatron to your control panel.
1.1.1 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 storage device.

The control panel should treat Installatron like any other tool within its GUI. So just as a user can only access their "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 the Installatron core (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 a web server that is running the standard software associated with web hosting, such as Apache and MySQL, and you require one Installatron license for each server that you wish to use Installatron on. You will likely also have a control panel (or GUI) running on the server.

PHP must fill the $_GET and $_POST system variables.

Your system must have a permanent internet connection for licensing purposes.

2 Overview

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 theme/GUI. These tasks are discussed in this section.

2.1 Installing Installatron

Follow the install steps documented here to add Installatron to your server:

http://installatron.com/install_custom

That completes a "custom control panel" installation. The Installatron core will be installed here:

/usr/local/installatron/

And the data files will be installed here:

/var/installatron/

2.2 The Control Panel API Files

The control panel API uses two PHP object files; one file to help integrate Installatron into your control panel environment, and a second file to tell Installatron how to interact with the control panel, 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.* This template contains the required methods for a "user-orientated" control panel environment. 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. * This template contains the required methods for a "user-orientated" control panel environment. 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 domains owned by a user then it calls getDomains() in custom.php, which, by whatever method works best for your control panel, should return an array of domain names owned by the specified user. If your control panel has a plugin API then getDomains() might make an call to the panel API and request the domain list, or alternatively it could parse a flat text file for the domain list. The method is up to you, and this applies to all the methods in backend.php.

Note that all methods run as root, so you can use any approach you like to fetch the required values. This also means that you must be careful.

See section 4 below for a closer look at each method in the backend.php file.
2.3 Adding Installatron to the Control Panel GUI

The control panel is a GUI 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 Linux 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 the Installatron core.

If your control panel has a plugin system, then you just need to create the the plugin directory and 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 Theme

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

/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 theme/GUI. 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 theme 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, either by a plugin system (if it has one) or a manual edit, so that clicking the http://yourdomain:port/installatron links in your control panel GUI 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";
}

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 "/frontend/".itron::$panel->theme."/installatron/index.php";
}

3.2 getUrlImg()

This method returns a path to Installatron's images directory, relative to the control panel's home URL.

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.
*
* @return string Path to Installatron
*/
protected function getUrlApp()
{
return "/frontend/".itron::$panel->theme."/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 mergeHttpGetInput()

This method adds the content of HTTP GET to $this->input.

You will only need to include this method in your backend.php if the base code doesn't work for your server. If it doesn't work you will see an empty content area when you load Installatron.
3.3.1 Example Code

This example code is from the method's base. You do not need to include this method if this base code works for your server:

/**
* Adds Http Get input to $this->input
*
* **Optionally overridable by inheritor**
*
*/
protected function mergeHttpGetInput()
{
//$this->input = $_GET;
parse_str($_SERVER["QUERY_STRING"],$this->input);
}

3.4 mergeHttpPostInput()

This method adds the content of HTTP POST to $this->input.

You will only need to include this method in your backend.php if the base code doesn't work for your server. If it doesn't work you will see an empty content area when you load Installatron.
3.4.1 Example Code

This example code is from the method's base. You do not need to include this method if this base code works for your server:

/**
* Adds Http Post input to $this->input
*
* **Optionally overridable by inheritor**
*
*/
protected function mergeHttpPostInput()
{
$this->input = array_merge($this->input,$_POST);

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 __construct()

This method informs Installatron about your control panel.

public function __construct()
{
$this->name = "Control Panel Name"; // display name for the control panel
$this->dbNameMaxLength = 16; // the maximum size of a database 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. The database length is used when generating database names, so that they're not longer than can be handed by the control panel.

4.2 Control Panel: getUser($u)

This method returns an array of information about a user of your control panel.
4.2.1 List of getUser() Return Values

value description
user username of the control panel user (this should be set to the incoming $user value)
system_user the operating system username (used to CHOWN files for this user and run binaries like mysqldump)
system_group the operating system group (used to CHOWN files for this user and run binaries like mysqldump)
path_home the server path to the user's home directory, with a trailing directory separator (used to set the root of file system manipulation for this user to this directory)
path_data the server path to the user's Installatron data directory, with a trailing directory separator (this is usually {path_home}.".installatron/")
path_pref the server path to the user's Installatron preferences directory, with a trailing directory separator (this is usually the same as path_data)
type user || reseller || admin (determines which Installatron administration features the user can access)
package the group/package the user belongs to (use en empty string ("") if your control panel has no packages system)
parent username of this user's creator/owner (use "!root" for the highest-level user)
email user's email address (used for pre-configured install values and email notifications)
mysql maximum number of mysql databases for the user (use "unlimited" for unlimited databases or to disable the database check)
quota account disk space available in megabytes (use "unlimited" for unlimited disk space or to disable the disk space check)

Regarding the admin "type", note that the user will only gain access to Installatron's full administration panel if they are both set to admin in this method, and their username is set in settings.ini (see step 3 of the custom-panel install process).
4.2.2 Example Code

/**
* Information about a user.
*
* @param string Username of user
* @return array User information array
*/
public function getUser($u)
{
// example code for case where the control panel user 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/user_list.xml');

// use POSIX to get user's home directory
// getSystemUser() is a custom implementation of posix_getpwnam()
// it accepts the same params and has the same return
$s = $this->getSystemUser($u);
if ( $s === false )
{
return false;
}

$r = array(
"user" => $u,
"system_user" => $u,
"system_group" => $u,
"type" => $xml->xpath("/users/user[user-name=\"$u\"]/type"),
"package" => $xml->xpath("/users/user[user-name=\"$u\"]/package"),
"parent" => $xml->xpath("/users/user[user-name=\"$u\"]/owner") != "" ? $xml->xpath("/users/user[user-name=\"$u\"]/owner") : "!root";
"email" => $xml->xpath("/users/user[user-name=\"$u\"]/email");
"mysql" => $xml->xpath("/users/user[user-name=\"$u\"]/database_limit"),
"quota" => $xml->xpath("/users/user[user-name=\"$u\"]/diskspace_limit")
);

$r["path_home"] = rtrim($s["dir"],DS).DS;
$r["path_pref"] = $r["path_data"] = $r["path_home"].".installatron".DS;

return $r;
}

4.2.3 Example Return Value

array(
"user" => "bob",
"system_user" => "bob",
"system_group" => "bob",
"path_home" => "/home/bob/",
"path_data" => "/home/bob/.installatron/",
"path_pref" => "/home/bob/.installatron/",
"type" => "user",
"package" => "bronze",
"parent" => "admin",
"email" => "bob@bobsdomain.com",
"type" => "user",
"mysql" => "unlimited",
"quota" => "2"
)

4.3 Control Panel: getUsers($u)

This method returns an array of users owned by a user of your control panel.

This is used to determine the installs that a reseller will see on their Install Overview page, and also which users will be affected by a reseller's settings. If none of your users are identified as resellers (see section 4.2 above), you do not need to include this method.

If the named user has no users of its own, return an empty array.
4.3.1 Example Code

/**
* Users owned by a reseller.
*
* @param mixed Reseller username
* @return array List of users
*/
public function getUsers($u)
{
// 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/user_statistics.xml');
$r = array();
foreach ($xml->xpath("/users/user[owner=\"$u\"]") as $user)
{
$r[] = $user->user_name;
}

// ensure that $u is not included in the $r list
$i = 0;
while (isset($r[$i]))
{
if ( $r[$i] == $u )
{
unset($r[$i]);
$r = array_values($r);
continue;
}
++$i;
}
return $r;
}

4.3.2 Example Return Value

array(
"aaron",
"bob",
"carl",
"habib"
);

4.4 Control Panel: 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.4.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.4.2 Example Return Value

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

4.5 Control Panel: getUsage()

This method returns an array of current usage information for the "effective" control panel user.

This is used before an install or upgrade to ensure that the install or upgrade can be performed.
4.5.1 List of Array Values

value description
mysql number of databases in current use (return "0" to disable the database check)
quota amount of disk space in current use in megabytes (return "0" to disable the disk space check)
4.5.2 Example Code

/**
* Usage information about the effective user.
*
* @return array User usage array
*/
public function getUsage()
{
$u = itron::$session["effective_user"];

// 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/user_statistics.xml');
return array(
"mysql" => $xml->xpath("/users/user[user-name=\"$u\"]/databases_used"),
"quota" => $xml->xpath("/users/user[user-name=\"$u\"]/diskspace_used")
);
}

4.5.3 Example Return Value

array(
"mysql" => "4",
"quota" => "1.855"
)

4.6 Control Panel: getDomains()

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

This is used when installing, to provide the user with a list of domains they are able to install on. It is also used for security, to ensure that tasks aren't performed outside the directories of the current user.

If the "effective" user has no domains, return an empty array.
4.6.1 Example Code

/**
* Domains owned by a user.
*
* @return array List of "effective" user's domains
*/
public function getDomains()
{
$u = itron::$session["effective_user"];

// example code for case where the control panel user 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/user_list.xml');
$r = array();
foreach ($xml->xpath("/users/user[user-name=\"$u\"]/domains/*") as $domain)
{
$r[] = $domain;
}
return $r;
}

4.6.2 Example Return Value

array(
"bobsdomain.com",
"bobsdomain.org",
"anotherdomain.com.au"
)

4.7 Control Panel: getSubDomainsOf($domain)

This method returns an array of sub-domains for a domain of the "effective" control panel user. The www sub-domain should not be included.

This is used when installing, to provide the user with a list of domains they are able to install on. It is also used for security, to ensure that tasks aren't performed outside the directories of the current user.
4.7.1 Example Return Value

/**
* Sub-domains of a domain owned by the the effective user.
*
* @param string Domain name
* @return array Domain's sub-domains
*/
public function getSubDomainsOf($domain)
{
$u = itron::$session["effective_user"];

// example code for case where the control panel user 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/user_list.xml');
$r = array();
foreach ($xml->xpath("/users/user[user-name=\"$u\"]/subdomains[domain=\"$domain\"]/*") as $subdomain)
{
$r[] = $subdomain;
}
return $r;
}

4.7.2 Example Return Value

array(
"forum",
"contact",
"third.level"
)

4.8 Control Panel: getDBs($type = "mysql")

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.8.1 Example Code

/**
* Databases owned by the effective user.
*
* @param string Database type (must be "mysql")
* @return array User's databases
*/
public function getDBs($type = "mysql")
{
$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.8.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.9 Control Panel: 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.10 System: isHttpRequest()

This method tells Installatron if it is currently running from shell or HTTP. Return true for HTTP and false for shell.

You will not need to include this method if your server correctly sets the shell environment variable when using PHP from a shell, and doesn't set it for HTTP.
4.10.1 Example Code

This example code is from the method's base. You do not need to include this method if this base code works for your server:

/**
* Installatron called from shell or HTTP?
*
* @return bool true if web/http; false if shell
*/
public function isHttpRequest()
{
return !isset($_SERVER["SHELL"]);
}

4.11 System: getInstallPath($httphttps, $domain, $path, $subdomain)

This method returns the "install location as a full path", without the trailing directory separator. This path can be constructed from a combination of the URL components passed to the method and the current session variables.

This is used when installing, to turn the selected install location into a server path that can be used for the install process.
4.11.1 Incoming and Useful Variables

variable description example
$httphttps the scheme portion of the URL http://sub.domain.com/path (or https)
$domain the domain portion of the URL http://sub.domain.com/path
$subdomain the sub-domain portion of the URL http://sub.domain.com/path
$path the path portion of the URL http://sub.domain.com/path
itron::$session["path_home"] the path to the home location of the "effective" user's account /home/bob/
4.11.2 Example Code

This example code is taken directly from the DirectAdmin API file, though your control panel will likely be different:

/**
* Install location as a server path.
*
* @param string "http" || "https"
* @param string Domain part of the install URL
* @param string Path part of the install URL
* @param string Sub-domain part of the install URL
* @return string Server path to the install location
*/
public function getInstallPath($httphttps, $domain, $path, $subdomain)
{
$installPath = itron::$session["path_home"]."domains".DS.$domain.DS
.( $httphttps == "http" ? "public_html" : "private_html" )
.(( $subdomain !== null && $subdomain != "www" )? DS.$subdomain : "" )
.$path;

return $installPath;
}

4.11.3 Example Return Value

This is an example of the path for a DirectAdmin server:

"/home/bob/domains/bobsdomain.com/public_html/installdirectory"

Or wherever the install location is physically located on your system.

4.12 System: getHomeDirectories($u)

This method returns an array of valid home directories for a given user, with each value ending with a directory separator.

If all the users of your control panel have a physical presence on the server, as is the case for the DirectAdmin and cPanel control panels, you can leave this method out of your API and let the base class control this task. If you control panel has a level of user that has no physical presence on the server, as is the case with Plesk where a user can have only a login and a list of owned domains, and it is the separate domain logins that have the directories, then this method should be included in your API.
4.12.1 Example Code

This example code is the user-orientated base code for this class:

/**
* List of locations for user's .installatron data directories.
*
* @param string Control panel user
* @return array List of paths
*/
public function getHomeDirectories($u)
{
if ( isset(itron::$session["path_home"]) && $u === itron::$session["effective_user"] )
{
return array(itron::$session["path_home"]);
}

if (( $userData = $this->getUser($u) )!== false )
{
return array($userData["path_home"]);
}

return array();
}

4.13 System: getDataDirectories($u)

This method returns an array of valid Installatron "data" directories for a given user, with each value ending with a directory separator.

If all the users of your control panel have a physical presence on the server, as is the case for the DirectAdmin and cPanel control panels, you can leave this method out of your API and let the base class control this task. If you control panel has a level of user that has no physical presence on the server, as is the case with Plesk where a user can have only a login and a list of owned domains, and it is the separate domain logins that have the directories, then this method should be included in your API.

This is used to locate, for creation and loading, the data files for the current user. Data files contain the details of a user's installed scripts.
4.13.1 Example Code

This example code is the user-orientated base code for this class:

* List of locations for user's .installatron data directories.
*
* @param string Control panel user
* @return array List of paths
*/public function getDataDirectories($u)
{
if ( isset(itron::$session["path_data"]) && $user === itron::$session["effective_user"] )
{
return array(itron::$session["path_data"]);
}

if (( $userData = $this->getUser($u) )!== false )
{
return array($userData["path_data"]);
}
return array();
}

4.14 System: createDB($name, $user, $pass, $type = "mysql")

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 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.14.1 Incoming Variables

variable description
$name the Installatron-generated database name
$user the Installatron-generated database username (will be the same as $name)
$pass the Installatron-generated database password
$type the database type
4.14.2 Example Code

/**
* Create a database
*
* + If your panel requires each database name and username
* start with the control panel user's username, note that the
* incoming $name value does not have the username prepended.
*
* @param string New database name +
* @param string New database username +
* @param string New database username's password
* @param string Database type (must be "mysql")
* @return bool true if sucessful; false otherwise
*/
public function createDB($name, $user, $pass, $type = "mysql")
{
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.15 System: removeDB($name, $type = "mysql")

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.15.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 = "mysql")
{
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.16 Session: initSession()

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

Before initSession() is called, Installatron will have already set itron::$session["user"] to the name of the system-user that has invoked Installatron (determined by checking the owner the current process). If your control panel is 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 might be able to leave this method out of your API and let the base class handle the task. If your control panel uses a single system-user for all actions, you will need to include this method and include in it a way to determine the "current user", and set itron::$session["user"] with that value.

Return true for success and false for failure.
4.16.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"]:

/**
* Initalize a session.
*
* @return bool true if sucessful; false otherwise
*/
public function initSession()
{
// example code for case where the control panel stores the current
// user's username in $_SERVER["CURRENT_USER"]
if (isset($_SERVER["CURRENT_USER"]))
{
itron::$session["user"] = $_SERVER["CURRENT_USER"];
return true;
}
return false;
}

5 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 current 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). Installatron is a plugin for control panels.

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.