Installatron Server API and Setup Guide

API Specification, version 4.0.5 (2015-10-08)

2. Self-hosting Installatron Server
2.1. Prerequisites
2.2. Generate a License Key
2.3. Download and Install
2.4. Complete

3. Interfacing with Installatron Server
3.1. Request Header
3.2. List available applications and application meta data
3.3. Installing an application
3.4. Import/migrate an existing installed application
3.5. List installed applications
3.6. List installed application backups
3.7. View/sync an installed application
3.8. Edit an installed application
3.9. Backup an installed application
3.10. Update an installed application
3.11. Clone an installed application
3.12. Restore an installed application backup
3.13. Delete an installed application backup
3.14. Import an installed application backup
3.15. Uninstall an installed application
3.16. List currently executing and recently completed tasks
3.17. Transferring a user into the Installatron Server GUI
3.17.1. Accessing the GUI as a website owner
3.17.2. Accessing the GUI as an administrative user or a reseller
3.17.3. Database management within the GUI
3.18. Advanced
3.18.1. Define a website path on demand
3.18.2. Improve FTP file operation performance
3.18.3. Create/edit user data within the Installatron Server database
3.18.4. Remove user data from the Installatron Server database
3.18.5. High Availability and Installatron Server Clusters

4. Maintaining Installatron Server
4.1. How app updates work
4.2. Settings.ini values
4.3. Command-line tools
4.4. API Changelog

1. Introduction

Please reference the "What is Installatron Server?" page for an overview of what Installatron Server is: What is Installatron Server?

As outlined, there are two hosting options for Installatron Server:

Self-hosted
Hosted as a service

And three integration interfaces for Installatron Server:

HTTP API
Command-line API
Installatron Server GUI

In this document each Installatron Server integration interface will be explained in detail. The interfaces do not differ between self-hosted and hosted as a service instances.

2. Self-hosting Installatron Server

Follow these instructions to install an instance of Installatron Server on a local server.

2.1. Prerequisites

At least one server with a permanent internet connection is required for licensing and updating purposes.

For small-to-medimum production deployments we recommend starting with these system specifications:

4GB or more system memory
60GB or more disk space
4 or more CPU cores

Next, we recommend provisioning the server with a minimal install of CentOS 7, RHEL 7, Debian 9 or Amazon Linux.

Note: Instead of using a dedicated server just for Installatron Server, it's possible to install Installatron Server on the same server that an existing web hosting control panel is installed on. Please contact Installatron Support to learn more about this installation procedure.

2.2. Generate a License Key

Generate an Installatron Server License Key through your Installatron.com account portal. If you haven't already, you'll need to create an Installatron.com account. The provided License Key can be used on any number of servers. Generate License Key

2.3. Download and Install

Execute these commands from the SSH root command prompt (replace YOUR_LICENSE_KEY with your Installatron Server License Key):

curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
yum -y remove httpd
./installatron-server.sh -f --key YOUR_LICENSE_KEY

yum -y remove httpd php
yum -y install gcc zlib-devel libpng-devel libjpeg-devel
mkdir -p /usr/local/installatron
cd /usr/local/installatron
curl -O http://php.net/distributions/php-5.6.31.tar.gz
tar xzf php-5.6.31.tar.gz
cd php-5.6.31
./configure --prefix=/usr/local/installatron/php --disable-libxml --disable-dom --disable-simplexml --disable-xml --disable-xmlreader --disable-xmlwriter --enable-posix --enable-mbstring --enable-ftp --enable-sockets --enable-fpm --without-pear --without-iconv --with-zlib --with-gd --with-jpeg-dir --with-png-dir --with-mysql=mysqlnd --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-gettext
make
make install
cd ..
rm -fr php-5.6.31 php-5.6.31.tar.gz /usr/local/installatron/bin/php
ln -s /etc/php-fpm.conf /usr/local/installatron/php/etc/php-fpm.conf
curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
./installatron-server.sh -f --key YOUR_LICENSE_KEY

apt-get update
apt-get -y dist-upgrade
apt-get -y install curl
curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
./installatron-server.sh -f --key YOUR_LICENSE_KEY

Note: To setup Installatron Server using a remote database, or to add an additional Installatron Server node to a cluster, add these arguments to the install command:

--db-host=sql.yourhost.com --db-user=youruser --db-pass=yourpass --db-name=itron

The installation process will take a couple minutes to install system services and dependencies for Installatron Server.

Core files and programs will be installed here:

/usr/local/installatron/

And the data files will be installed here:

/var/installatron/

2.4. Complete

That's it! Record the administrative login and password provided in the install output, and then continue to the section 3 Interfacing with Installatron Server below to begin the integration process.

3. Interfacing with Installatron Server

Input to the Installatron Server API can be formatted in JSON or simple URL encoded values.

Skip directly to the 3.17. Transferring a user into the Installatron Server GUI section to learn how to interface with the Installatron Server GUI.

3.1. Request Header

The request header informs Installatron Server about a user. Every request to Installatron Server must include a header, including requests to transfer a user into the Installatron Server GUI.

List of header arguments

NAME VALUE
key
required
The API authentication key. This is provided by Installatron when hosted as a service. Check the "key" value in /usr/local/installatron/etc/settings.ini for self-hosted instances.
user
optional but recommended
An alphanumeric value that the list of websites provided for the current session can be associated with. This argument will be used to index data and cannot change.
reseller
optional
An alphanumeric value that defines the hierarchical organization of the user provided.
websites
required
List of websites with each containing the below arguments. Note: Websites can only have one home directory so websites spread across multiple home directories will need separate website entries. See examples below.
NAME VALUE
id
required
An alphanumeric value that will uniquely identify this website. This argument will be used to index data for this website and cannot change.
label
optional
A value that will uniquely identify this website that can contain any characters. This argument can change.
email
required
The email address for the website (used as the default value for any application's email input)
path
optional*
The path or URI to the home directory of this account (without a trailing directory separator).

Important notes for URI values:
The entire URI is AES encrypted in Installatron Server's database.
To ensure correct URI syntax the username and password values should be URL-encoded.
The host portion of the URI is used to distinguish between web servers. It's considered a best practice to use a web server-referencing hostname (eg., server123.host.net) or an IP address for the host portion of the URI. If this is not possible, make sure to include the server argument as documented below.

Supported protocols:
The local filesystem (including NFS shares)
SSH^**
FTP
FTPS
SFTP^**

Note: Both password and private key authentication is supported for the SSH and SFTP filesystem protocols; to authenticate by private key, substitute the private key for the password.

Examples:
/home/user
ftp://user:pass@server123.host.net
ssh://user:pass@server123.host.net
ftp://user:pass@12.23.34.45/httpdocs

^*This value is required unless the instructions outlined in section 3.18.1 are followed to define paths on demand.
^**Both password and private key authentication is supported. To authenticate by private key, simply use the private key in place of the password within the URI.
vhosts
required
A set of key/value pairs that define each domain hosted by this website and its corresponding document root relative to path. The sample header sections below illustrate the correct formatting.

Example:
http://installatron.com => public_html
http://dev1.installatron.com => public_html/dev1
vhost_ip
optional, default is the IP address resolved via DNS
The IP address each domain listed in vhosts should resolve to, enabling Installatron Server to install to vhosts that might not resolve through DNS.
path_backups
optional, default is /application_backups/
A path relative to path where installed application backups will be saved, without a trailing directory separator.
server
optional, default is host portion of the path URI
The host portion of the path URI is used to distinguish between web servers by default. If for whatever reason this doesn't correctly distinguish web servers then a unique value for each web server should be set here.
uid
required if path is a local filesystem
The filesystem POSIX UID that files should be created as for this website. This value should only be included if path is a local filesystem path.
gid
required if path is a local filesystem
The filesystem POSIX GID that files should be created as for this website. This value should only be included if path is a local filesystem path.
mysql_host
optional, default is localhost
The default mysql server for this website. This value will be overridden if a different database host value is defined for an installed application.
language
optional, default is the systemwide default language or English
This website's default language. This is the language text strings and error messages will display in for requests involving this website. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations.
suspended
optional, default is "no"
Whether the website is suspended. Valid values are "yes" and "no".

Sample header 1 formatted in JSON

{
    "key": "8327b11a311aad5a8092d26d209c9e13",
    "websites": [
        {
            "id": "ws124",
            "path": "/var/www/vhosts/company.com",
            "vhosts": {
                "http://company.com": "httpdocs",
                "http://www.company.com": "httpdocs"
            },
            "email": "user@mail.com",
            "uid": 153,
            "gid": 153
        }
    ]
}

Sample header 2 formatted in JSON

{
    "key": "8327b11a311aad5a8092d26d209c9e13",
    "websites": [
        {
            "id": "ws124",
            "path": "ssh://user:pass@server120.host.com/var/www/vhosts/c/o/m/company.com",
            "vhosts": {
                "http://company.com": "public_html",
                "http://www.company.com": "public_html",
                "http://forum.company.com": "public_html/forum"
            },
            "email": "user@mail.com"
        }
    ]
}

3.2. List available applications and application meta data

List of arguments

NAME VALUE
cmd browser
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
application
optional
The ID of the application to list available versions of. This can be a single application or an array of multiple applications. By default the latest version of each application is listed. Listed versions are ordered correctly.
version
optional
If application is set to one application, set this to only list the specific version.
from-version
optional
If application is set to one application, set this to list all versions from specified version to the latest version. Each listed version includes a "upgrade_from" member which reveals whether an install at the specified version can upgraded to the listed version (values of "none" or "manual" mean it cannot). Listed versions are ordered correctly.
versions-available-from
optional
If application is set to one application, instead of the usual output this will return two lists, "versions-available" and "versions-available-minor", each listing the versions upgradable to from the specified value.
language
optional
The language application information should be returned in. For example, "en" for English or "zh_tw" for Chinese Traditional. If omitted, the defined website's default language or English is assumed. See: Available Installatron Translations.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Table of release meta data.
NAME VALUE
appid internal id of the app
version release version
branch release branch/channel
name display name of the app
category display category of the app (e.g., "Content Management")
type app type (e.g., "blog")
date date of release (YYYY-MM-DD format)
license app license type (e.g., "open source", "commercial")
tags list of release tags (e.g., "security", "minor", "major")
description Installatron-written description of the app
authordescription author-written description of the app (typically much longer)
changelog author-written log of changes from previous release
upgrade whether upgrading to this release is considered "minor" or "major", or "none" if upgrading is not possible
install whether installing this release is possible ("auto") or not ("none")
link_site link to app website
link_showcase link to app showcase
link_docs link to app documentation
link_faq link to app FAQ
link_support link to app support page
link_changelog link to app release changelog
requirements table of requirements. Common requirements include:
NAME VALUE
diskspace minimum disk space (e.g., "40M")
php PHP version ramge (e.g., "5.2.5-5.5.999,7.1-")
mysql MySQL version range (e.g., "5-")
mysql_table_prefix default MySQL table prefix (e.g., "wp_")
languages list of languages the release can be installed in
fields table of fields (see below sample output)
images list of release assets including images and screenshots (see below sample output)

Sample

curl https://installatron.com/apps \
	-d "api=json" \
	-d "cmd=browser" \
	-d "application=wordpress" \
	-d "version=4.9.7"

{
    "result": true,
    "message": "The task is complete.\n",
    "data": [
        {
            "id": "wordpress_4.9.7",
            "appid": "wordpress",
            "version": "4.9.7",
            "branch": "current",
            "name": "WordPress",
            "category": "Content Management",
            "type": "blog",
            "date": "2018-07-07",
            "license": "open source",
            "tags": [
                "security"
            ],
            "description": "WordPress is an open source blog application. WordPress forked from b2/cafelog in 2003, and WordPress Mu multiple website functionality has been integrated since 2010. Today WordPress is the most used blog application powering millions of blogs and being used by tens of millions of people every day.",
            "authordescription": "WordPress is a personal publishing platform and blogging application with a focus on aesthetics, web standards, and usability.\r\n\r\nFeatures:\r\n* Additional pages allow you to manage non-blog content easily, so for example you could have a static \"About Me\" page.\r\n* A full theme system enables designing everything from the simplest blog to the most complicated webzine a piece of cake.\r\n* Changes made to templates and entries are reflected immediately on your site, with no need for regenerating static pages, and all generated HTML is fully compliant with W3C standards.\r\n* Trackback and Pingback standards fully supported.\r\n* Visitors can post comments on your blog entries, and commenting can be disabled on a per-post basis.\r\n* Spam protection eliminates comment spam from your blog.\r\n* User registration enables visitors to register and maintain profiles and leave authenticated comments on your blog, if enabled.\r\n* Password Protected Posts enables you to give passwords to individual posts to hide them from the public.\r\n* A full XML-RPC interface enables you to extend WordPress and use clients designed for other platforms like Zempt.\r\n* User groups enables up to 10 levels of users, with different levels having different (and configurable) privileges with regard to publishing, editing, options, and other users.\r\n* Bookmarklets make it easy to publish to your blog or add links to your blogroll with a minimum of effort.\r\n* Ping-O-Matic is supported, which means maximum exposure for your blog to search engines.",
            "changelog": "WordPress 4.9.7 is a security and maintenance release.\r\n\r\nSecurity\r\n* Fixed a security problem where a user with the capability to edit and delete media files could potentially manipulate media metadata to attempt to delete files outside the uploads directory.\r\n\r\nHighlights\r\n* Taxonomy: Improve cache handling for term queries.\r\n* Posts, Post Types: Clear post password cookie when logging out.\r\n* Widgets: Allow basic HTML tags in sidebar descriptions on Widgets admin screen.\r\n* Community Events Dashboard: Always show the nearest WordCamp if one is coming up, even if there are multiple Meetups happening first.\r\n* Privacy: Make sure default privacy policy content does not cause a fatal error when flushing rewrite rules outside of the admin context.",
            "upgrade": "minor",
            "install": "auto",
            "link_site": "http://wordpress.org",
            "link_showcase": "http://wordpress.org/showcase",
            "link_docs": "http://codex.wordpress.org",
            "link_faq": "http://codex.wordpress.org/FAQ",
            "link_support": "http://wordpress.org/support",
            "link_changelog": "http://wordpress.org/news/2016/01/wordpress-4-4-1-security-and-maintenance-release/",
            "link_admin": "wp-admin",
            "link_installersupport": "https://installatron.com/tickets",
            "requirements": {
                "itron": "5.0.0-",
                "diskspace": "40M",
                "php": "5.2.4-",
                "mysql": "5-",
                "mysql_table_prefix": "wp_"
            },
            "languages": [
                "ar",
                "bg",
                "ca",
                "cs",
                "da",
                "de",
                "el",
                "en",
                "en_au",
                "en_ca",
                "en_uk",
                "es",
                "et",
                "fa",
                "fi",
                "fr",
                "gl",
                "he",
                "hr",
                "hu",
                "it",
                "is",
                "ja",
                "ko",
                "lt",
                "lv",
                "nl",
                "no",
                "pl",
                "pt",
                "pt_br",
                "ru",
                "ro",
                "sk",
                "sr",
                "sv",
                "th",
                "tr",
                "uk",
                "zh",
                "zh_tw"
            ],
            "fields": {
                "version": {
                    "gettable": true,
                    "settable": false,
                    "label": "Version",
                    "text": "Select the version of WordPress to install.",
                    "sort_order": 0
                },
                "language": {
                    "label": "Language",
                    "text": "select a language",
                    "type": "select",
                    "gettable": true,
                    "settable": true,
                    "options": {
                        "ar": "Arabic",
                        "bg": "Bulgarian",
                        "ca": "Catalan",
                        "cs": "\u010cesky (Czech)",
                        "da": "Dansk",
                        "de": "Deutsch",
                        "el": "\u0395\u03bb\u03bb\u03b7\u03bd\u03b9\u03ba\u03ac (Greek)",
                        "en": "English",
                        "en_au": "en_au",
                        "en_ca": "English (Canada)",
                        "en_uk": "English (United Kingdom)",
                        "es": "Espa\u00f1ol (Spanish)",
                        "et": "Estonian",
                        "fa": "Persian",
                        "fi": "Suomi",
                        "fr": "Fran\u00e7ais",
                        "gl": "Gaelg",
                        "he": "Hebrew",
                        "hr": "Croatian",
                        "hu": "Magyar (Hungarian)",
                        "it": "Italiano",
                        "is": "Icelandic",
                        "ja": "Japanese",
                        "ko": "Korean",
                        "lt": "Lietuvi\u0173 (Lithuanian)",
                        "lv": "Latvian",
                        "nl": "Nederlands (Dutch)",
                        "no": "Norwegian",
                        "pl": "Polski",
                        "pt": "Portugu\u00eas (Portuguese)",
                        "pt_br": "Portugu\u00eas do Brasil",
                        "ru": "Russian",
                        "ro": "Rom\u00e2n\u0103",
                        "sk": "Slovak (Slovakian)",
                        "sr": "Serbian",
                        "sv": "Swedish",
                        "th": "Thai",
                        "tr": "T\u00fcrk\u00e7e (Turkish)",
                        "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430 (Ukrainian)",
                        "zh": "\u4e2d\u6587 (Chinese Simplified)",
                        "zh_tw": "\u4e2d\u6587(\u53f0\u7063) (Chinese Traditional)"
                    },
                    "sort_order": 1
                },
                "login": {
                    "label": "Administrator Username",
                    "text": "enter a username for the administrator user",
                    "type": "text",
                    "default": "admin",
                    "gettable": true,
                    "settable": true,
                    "sort_order": 2
                },
                "passwd": {
                    "label": "Administrator Password",
                    "text": "enter a password for the administrator user",
                    "type": "password",
                    "gettable": false,
                    "settable": true,
                    "sort_order": 3
                },
                "email": {
                    "label": "Administrator Email",
                    "text": "enter your email address",
                    "type": "text",
                    "gettable": true,
                    "settable": true,
                    "sort_order": 4
                },
                "sitetitle": {
                    "label": "Website Title",
                    "text": "enter title for the website",
                    "type": "text",
                    "gettable": true,
                    "settable": true,
                    "sort_order": 5
                },
                "sitetagline": {
                    "label": "Website Tagline",
                    "text": "enter tagline for the website",
                    "type": "text",
                    "gettable": true,
                    "settable": true,
                    "sort_order": 6
                },
                "twofactor": {
                    "type": "radio",
                    "value": "clef",
                    "label": "Two-Factor Authentication",
                    "options": {
                        "clef": "Two-factor authentication with Clef. (Recommended)",
                        "no": "Do not enable two-factor authentication."
                    },
                    "gettable": true,
                    "settable": true,
                    "sort_order": 7
                },
                "limitloginattempts": {
                    "type": "radio",
                    "value": "yes",
                    "label": "Limit Login Attempts",
                    "options": {
                        "yes": "Yes, limit failed login attempts for increased security. (Recommended)",
                        "no": "No, do not limit failed login attempts."
                    },
                    "gettable": true,
                    "settable": true,
                    "sort_order": 8
                },
                "multisite": {
                    "type": "radio",
                    "value": "no",
                    "label": "Enable Multi-site",
                    "options": {
                        "no": "No, do not enable. Multi-site can be enabled later within WordPress. (Recommended)",
                        "yes": "Yes, enable multi-site support for sub-directories of the selected install location."
                    },
                    "gettable": false,
                    "settable": false,
                    "sort_order": 9
                }
            },
            "images": [
                "button_wordpress.gif",
                "icon_wordpress.png",
                "icon175_wordpress.png",
                "icon1752x_wordpress.png",
                "icon64_wordpress.png",
                "icon642x_wordpress.png",
                "logo_wordpress.png",
                "logo2x_wordpress.png",
                "sc1_wordpress.png",
                "sc10_wordpress.png",
                "sc11_wordpress.png",
                "sc12_wordpress.png",
                "sc13_wordpress.png",
                "sc14_wordpress.png",
                "sc2_wordpress.png",
                "sc3_wordpress.png",
                "sc4_wordpress.png",
                "sc5_wordpress.png",
                "sc6_wordpress.png",
                "sc7_wordpress.png",
                "sc8_wordpress.png",
                "sc9_wordpress.png",
                "ss1_wordpress.png",
                "ss2_wordpress.png",
                "ss3_wordpress.png",
                "ss4_wordpress.png",
                "ss5_wordpress.png",
                "x-ss2_wordpress.jpg"
            ]
        }
    ]
}

3.3. Installing an application

List of arguments

NAME VALUE
cmd install
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
application
required
The ID of the application to be installed. For example, "wordpress" or "magento". Use the browser API to get a list of available applications.
version
optional, default is the latest compatible version
The version of the application to be installed.
autoup
optional
Change automatic update configuration. Values: 0 = Off (default); 1 = Update to minor versions only; 2 = Update to any version.
autoup_backup
optional
Automatically create a backup and automatically restore the backup if the update fails. Values: 0 = Off; 1 = On (default).
url
required
The URL to where the application should be installed.
url_ip
optional, default is the IP address resolved via DNS
If the DNS will not resolve the provided url to the correct IP, use this argument to provide the correct IP.
db_host
required if the application requires a database, can be omitted if database automation is implemented
The database server.
db_name
required if the application requires a database, can be omitted if database automation is implemented
The pre-created database.
db_user
required if the application requires a database, can be omitted if database automation is implemented
The pre-created database username.
db_pass
required if the application requires a database, can be omitted if database automation is implemented
The pre-created database password.
db_prefix
optional, defaults to the prefix behavior configured at Installatron Admin > Features
The prefix applied to database tables.
db_host_ip
optional, typically omitted
If a different MySQL host value must be temporarily used to connect to the database, use this argument to provide the temporary address. Installed application files will be written with the "db_host" value, but Installatron will use "db_host_ip" while installing.
notification
optional
List of email notifications to send for the installed application (each separated with a comma). Set a value of "all" to send all notifications (limited by those that are enabled in administration » Emails), or define an empty string to send no notifications.

Available notifications:
install
install_error
clone
clone_error
backup
backup_error
restore
restore_error
update_available
update
update_error
plugin_update_available
plugin_update
plugin_update_error

A sample value could look like: "update_available,update,update_error"
background
optional
When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.

Optional automatic backup arguments:

NAME VALUE
autobk
optional
Change automatic backup configuration. Values: custom = A custom schedule; (id) = The schedule identified by (id).
autobk_daily
optional
The number of daily backups (for the "custom" option)
autobk_weekly
optional
The number of weekly backups (for the "custom" option)
autobk_monthly
optional
The number of monthly backups (for the "custom" option)

Optional remote backup arguments:

NAME VALUE
bkloc
optional
Set this to the URI to a backup location (which will be associated with the defined "user" for the session).

Supported filesystem protocols:
FTP
FTPS
SFTP
SSH
WebDAV (HTTP)
WebDAVS (HTTPS)

Examples:
ftp://user:pass@server
sftp://user:pass@server/backups
ftp://user:pass@server/backups
webdav://user:pass@server/backups

Further optional arguments that depend on the application (get a full list of fields available for a specific application/version using the browser API):

NAME VALUE
language
optional, default is the website's default language or English
The language of the application to be installed. For example, "en" for English or "zh_tw" for Chinese Traditional. Use the browser API to get a list of available languages for the installed application.
login
optional, default is randomly generated value
The username for the installed application's administrative account.
passwd
optional, default is randomly generated value
The password for the installed application's administrative account. If omitted, a randomized password is assumed.
sitetitle
optional, default is "My blog" or similar
The site title value for the installed application.
content
optional, default is "yes"
Set to "yes" for the sample/demo template.
Set to "no" for the blank install template.
Set to the ID of the template for a different template.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Table of installed application information.
task Table of task information if executed as a background process.

Sample

curl https://installatron.com/server/v1 \
	-d "key=8327b11a311aad5a8092d26d209c9e13" \
	-d "websites[0][id]=ws124" \
	-d "websites[0][email]=user@mail.com" \
	-d "websites[0][path]=ftp://website124:password@12.24.36.22" \
	-d "websites[0][vhosts][http://company.com]=httpdocs" \
	-d "websites[0][vhosts][http://www.company.com]=httpdocs" \
	-d "cmd=install" \
	-d "application=wordpress" \
	-d "url=http://company.com" \
	-d "db_name=db123" \
	-d "db_user=db123" \
	-d "db_pass=sdfsdf1" \
	-d "db_host=localhost"

{
    "result": true,
    "message": "",
    "data": {
        "id": "3reqf1iduigw0kogk8skgcsoc",
        "installer": "wordpress",
        "version": "3.6.1",
        "language": "en",
        "time": "1380560311",
        "agent": "4.0.0",
        "owner": "dev1",
        "path": "/home/dev1/public_html",
        "path-created": "1",
        "url": "http://company.com",
        "url-domain": "company.com",
        "db-host": "localhost",
        "db-type": "mysql",
        "db-name": "db123",
        "db-user": "db123",
        "db-pass": "sdfsdf1",
        "db-prefix": "wp_",
        "title": "My blog",
        "list-files": [
            "index.php",
            "license.txt",
            ".htaccess",
            "wp-activate.php",
            "wp-admin",
            "wp-app.php",
            "wp-itapi.php",
            "wp-blog-header.php",
            "wp-comments-post.php",
            "wp-config-sample.php",
            "wp-config.php",
            "wp-content",
            "wp-cron.php",
            "wp-includes",
            "wp-links-opml.php",
            "wp-load.php",
            "wp-login.php",
            "wp-mail.php",
            "wp-settings.php",
            "wp-signup.php",
            "wp-trackback.php",
            "xmlrpc.php"
        ],
        "list-tables": [
            "wp_commentmeta",
            "wp_comments",
            "wp_links",
            "wp_options",
            "wp_postmeta",
            "wp_posts",
            "wp_term_relationships",
            "wp_term_taxonomy",
            "wp_terms",
            "wp_usermeta",
            "wp_users"
        ],
        "autoup": "1",
        "bkloc": "local",
        "autobk": "0",
        "cf-login": "admin",
        "cf-email": "support@installatron.com",
        "cf-sitetitle": "My blog",
        "cf-sitetagline": "Just another WordPress site",
        "cf-limitloginattempts": "yes",
        "cache-tables": "87828",
        "link-admin": "wp-admin",
        "cache-files": "16105472",
        "cache-time": "1380560313",
        "cache-numbackups": "0"
    }
}

Additional Examples

Command-line inteface JSON input

echo '{
	"key": "8327b11a311aad5a8092d26d209c9e13",
	"websites":
	[{
		"id":"ws124",
		"path":"/var/www/vhosts/company.com",
		"vhosts":{
			"http://company.com":"httpdocs",
			"http://www.company.com":"httpdocs"
		},
		"email":"user@mail.com",
		"uid":153,
		"gid":153
	}],
	"cmd":"install",
	"application":"wordpress",
	"url":"http://company.com/blog",
	"db_name":"db123",
	"db_user":"db123",
	"db_pass":"sdfsdf1",
	"db_host":"localhost"
}' | /usr/local/installatron/installatron

HTTP interface URL-encoded input

curl https://installatron.com/server/v1 \
	-d "key=8327b11a311aad5a8092d26d209c9e13" \
	-d "websites[0][id]=ws124" \
	-d "websites[0][email]=user@mail.com" \
	-d "websites[0][path]=ftp://website124:password@12.24.36.22" \
	-d "websites[0][vhosts][http://company.com]=httpdocs" \
	-d "websites[0][vhosts][http://www.company.com]=httpdocs" \
	-d "cmd=install" \
	-d "application=wordpress" \
	-d "url=http://company.com/blog" \
	-d "db_name=db123" \
	-d "db_user=db123" \
	-d "db_pass=sdfsdf1" \
	-d "db_host=localhost"

HTTP interface JSON input


<?php
$query = array(
    /* these values define the request header: */
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "websites" => array(
        array(
            "id" => "ws124",
            "path" => "ftp://".urlencode("website124").":".urlencode("password")."@12.24.36.22",
            "vhosts" => array(
                "http://company.com" => "httpdocs",
                "http://www.company.com" => "httpdocs",
                "https://company.com" => "httpsdocs",
                "https://www.company.com" => "httpsdocs",
            ),
            "email" => "user@mail.com",
        )
    ),
    /* these values define the request body: */
    "cmd" => "install",
    "application" => "wordpress",
    "url" => "http://company.com/blog",
    "db_name" => "db123",
    "db_user" => "db123",
    "db_pass" => "sdfsdf1",
    "db_host" => "localhost",
);

$ch = curl_init("https://installatron.com/server/v1");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));

$reply = curl_exec($ch);

if ( $reply === false )
{
    echo "An error occurred: ".curl_error($ch);
    return;
}

$reply = json_decode($reply,true);

if ( $reply["result"] === false )
{
    echo "An error occurred: ".$reply["message"];
    return;
}

echo "Success! ".$reply["message"];

3.4. Import/migrate an existing installed application

Installed applications can be imported from hosted websites or migrated from remote web hosting servers. When migrating, include the source_url and source_ftu arguments.

As of Installatron Server 3.0, current database information for the installed application is always automatically detected.

List of arguments

NAME VALUE
cmd import
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
application
required
The ID of the application to be imported or migrated. For example, "wordpress" or "magento". See: List of applications.
version
optional, defaults to the automatically-detected version
The version of the application to be imported. If omitted, the version is automatically detected.
url
required
For a local Import this is the URL to where the application is current located. For a remote Import (a Migration) this is the destination URL where the copy of the source application will be constructed.
url_ip
optional, default is the IP address resolved via DNS
If DNS cannot resolve the provided url to the correct IP, use this argument to provide the correct IP.
source_url
required if migrating an installed application from a remote server
If migrating an installed application from a remote server, include this argument to provide the source installed application URL.

For example, "http://website.com/wordpress".
source_ftu
required if migrating an installed application from a remote server
If migrating an installed application from a remote server, include this argument to provide the source installed application account information.

Supported filesystem protocols:
FTP
FTPS
SFTP
SSH

Examples:
ftp://user:pass@website.com
sftp://user:pass@website.com/public_html
ftp://user:pass@website.com/public_html/wordpress
source_url_ip
optional, default is the IP address resolved via DNS
If migrating an installed application from a remote server, include this argument to provide Installatron the IP address that Installatron should use for the source server. Providing this value means that Installatron will not need to perform DNS lookup on the source domain.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Table of installed application information.

Sample return value

{
    "result": true,
    "message": "",
    "data": {
        "id": "3reqf1iduigw0kogk8skgcsoc",
        "installer": "wordpress",
        "version": "3.6.1",
        "language": "en",
        "time": "1380560311",
        "agent": "4.0.0",
        "owner": "dev1",
        "path": "/home/dev1/public_html/test",
        "path-created": "1",
        "url": "http://dev1.dev-is4.installatron.com/test",
        "url-domain": "dev1.dev-is4.installatron.com",
        "db-host": "localhost",
        "db-type": "mysql",
        "db-name": "dev1_wp1",
        "db-user": "dev1_wp1",
        "db-pass": "Y[|BrJ2PAy]@0",
        "db-prefix": "wp_",
        "title": "My blog",
        "list-files": [
            "index.php",
            "license.txt",
            ".htaccess",
            "wp-activate.php",
            "wp-admin",
            "wp-app.php",
            "wp-itapi.php",
            "wp-blog-header.php",
            "wp-comments-post.php",
            "wp-config-sample.php",
            "wp-config.php",
            "wp-content",
            "wp-cron.php",
            "wp-includes",
            "wp-links-opml.php",
            "wp-load.php",
            "wp-login.php",
            "wp-mail.php",
            "wp-settings.php",
            "wp-signup.php",
            "wp-trackback.php",
            "xmlrpc.php"
        ],
        "list-tables": [
            "wp_commentmeta",
            "wp_comments",
            "wp_links",
            "wp_options",
            "wp_postmeta",
            "wp_posts",
            "wp_term_relationships",
            "wp_term_taxonomy",
            "wp_terms",
            "wp_usermeta",
            "wp_users"
        ],
        "autoup": "1",
        "bkloc": "local",
        "autobk": "0",
        "cf-login": "admin",
        "cf-email": "support@installatron.com",
        "cf-sitetitle": "My blog",
        "cf-sitetagline": "Just another WordPress site",
        "cf-limitloginattempts": "yes",
        "cache-tables": "87828",
        "link-admin": "wp-admin",
        "cache-files": "16105472",
        "cache-time": "1380560313",
        "cache-numbackups": "0"
    }
}

3.5. List installed applications

List of arguments

NAME VALUE
cmd installs
key
required
part of the Request Header that must be included with all API requests
user
optional
View the installs of a specific user on the control panel. The default is the control panel administrator.
q
optional
Search installed application with a query. This searches the title, url, id, installer, and owner fields.
id
optional
Display a specific installed application by ID.
filter-version-available
optional
When set equal to "yes", only installed applications that have any new version upgrades available will be listed.
filter-version-available-minor
optional
When set equal to "yes", only installed applications that have new minor version upgrades available will be listed.
filter-ownedaccounts
optional
Add this parameter (as; filter-ownedaccounts=) if you wish to also see the installs of accounts owned by this user.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Detailed list of matched installed applications.

Sample return value

{
    "result": true,
    "message": "",
    "data": [
        {
            "id": "3reqf1iduigw0kogk8skgcsoc",
            "installer": "wordpress",
            "version": "3.6.1",
            "language": "en",
            "time": "1380560311",
            "agent": "4.0.0",
            "owner": "dev1",
            "path": "/home/dev1/public_html/test",
            "path-created": "1",
            "url": "http://dev1.dev-is4.installatron.com/test",
            "url-domain": "dev1.dev-is4.installatron.com",
            "db-host": "localhost",
            "db-type": "mysql",
            "db-name": "dev1_wp1",
            "db-user": "dev1_wp1",
            "db-pass": "Y[|BrJ2PAy]@0",
            "db-prefix": "wp_",
            "title": "My blog",
            "list-files": [
                "index.php",
                "license.txt",
                ".htaccess",
                "wp-activate.php",
                "wp-admin",
                "wp-app.php",
                "wp-itapi.php",
                "wp-blog-header.php",
                "wp-comments-post.php",
                "wp-config-sample.php",
                "wp-config.php",
                "wp-content",
                "wp-cron.php",
                "wp-includes",
                "wp-links-opml.php",
                "wp-load.php",
                "wp-login.php",
                "wp-mail.php",
                "wp-settings.php",
                "wp-signup.php",
                "wp-trackback.php",
                "xmlrpc.php"
            ],
            "list-tables": [
                "wp_commentmeta",
                "wp_comments",
                "wp_links",
                "wp_options",
                "wp_postmeta",
                "wp_posts",
                "wp_term_relationships",
                "wp_term_taxonomy",
                "wp_terms",
                "wp_usermeta",
                "wp_users"
            ],
            "autoup": "1",
            "bkloc": "local",
            "autobk": "0",
            "cf-login": "admin",
            "cf-email": "support@installatron.com",
            "cf-sitetitle": "My blog",
            "cf-sitetagline": "Just another WordPress site",
            "cf-limitloginattempts": "yes",
            "cache-tables": "87828",
            "link-admin": "wp-admin",
            "cache-files": "16105472",
            "cache-time": "1380560313",
            "cache-numbackups": "0"
        },
        {
            "id": "gk8skgcsocreqf1d4uigwi0ko",
            "installer": "wordpress",
            "version": "3.6.1",
            "language": "en",
            "time": "1380560300",
            "agent": "4.0.0",
            "owner": "dev1",
            "path": "/home/dev1/public_html/test2",
            "path-created": "1",
            "url": "http://dev1.dev-is4.installatron.com/test2",
            "url-domain": "dev1.dev-is4.installatron.com",
            "db-host": "localhost",
            "db-type": "mysql",
            "db-name": "dev1_wp1",
            "db-user": "dev1_wp1",
            "db-pass": "c0BrJY[y]@2PA",
            "db-prefix": "wp_",
            "title": "My blog",
            "list-files": [
                "index.php",
                "license.txt",
                ".htaccess",
                "wp-activate.php",
                "wp-admin",
                "wp-app.php",
                "wp-itapi.php",
                "wp-blog-header.php",
                "wp-comments-post.php",
                "wp-config-sample.php",
                "wp-config.php",
                "wp-content",
                "wp-cron.php",
                "wp-includes",
                "wp-links-opml.php",
                "wp-load.php",
                "wp-login.php",
                "wp-mail.php",
                "wp-settings.php",
                "wp-signup.php",
                "wp-trackback.php",
                "xmlrpc.php"
            ],
            "list-tables": [
                "wp_commentmeta",
                "wp_comments",
                "wp_links",
                "wp_options",
                "wp_postmeta",
                "wp_posts",
                "wp_term_relationships",
                "wp_term_taxonomy",
                "wp_terms",
                "wp_usermeta",
                "wp_users"
            ],
            "autoup": "1",
            "bkloc": "local",
            "autobk": "0",
            "cf-login": "admin",
            "cf-email": "support@installatron.com",
            "cf-sitetitle": "My blog",
            "cf-sitetagline": "Just another WordPress site",
            "cf-limitloginattempts": "yes",
            "cache-tables": "87828",
            "link-admin": "wp-admin",
            "cache-files": "16105472",
            "cache-time": "1380560313",
            "cache-numbackups": "0"
        }
    ]
}

3.6. List installed application backups

List of arguments

NAME VALUE
cmd backups
key
required
part of the Request Header that must be included with all API requests
user
optional
View the backups of a specific user on the control panel. The default is the control panel administrator.
q
optional
Search installed application backups with a query. This searches the title, url, id, installer, and owner fields.
pid
optional
Display only installed application backups that belong to this installed application ID. This can be used in conjunction with the "q" argument. (added with version 4.1.5)
id
optional
Display a specific installed application backup by ID.
filter-ownedaccounts
optional
Add this parameter (as; filter-ownedaccounts=) if you wish to also see the backups of accounts owned by this user.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Detailed list of matched installed application backups.

Sample return value

{
    "result": true,
    "message": "",
    "data": [
        {
            "id": "aga40vngcy888kg44coogkgwk",
            "file": "/home/dev1/.appdata/backups/aga40vngcy888kg44coogkgwk",
            "installer": "zurmo",
            "version": "2.0.21",
            "language": "en",
            "time": "1376660774",
            "agent": "9.0.0",
            "owner": "dev1",
            "path": "/home/dev1/domains/dev1.dev-is4.installatron.com/public_html/crmtest02",
            "path-created": "1",
            "url": "http://dev1.dev-is4.installatron.com/crmtest02",
            "url-domain": "dev1.dev-is4.installatron.com",
            "db-host": "localhost",
            "db-type": "mysql",
            "db-name": "dev1_zurm41",
            "db-user": "dev1_zurm41",
            "db-pass": "S@qXksiex|^*3",
            "list-files": [
                "app/protected/config/perInstance.php",
                ".htaccess",
                "app",
                "documentation",
                "index.php",
                "License.txt",
                "redbean",
                "yii"
            ],
            "list-tables": [
                "account",
                "account_read",
                "activelanguage",
                "activity",
                "activity_item",
                "address",
                "auditevent",
                "autoresponder",
                "autoresponderitem",
                "autoresponderitemactivity",
                "basecustomfield",
                "bytimeworkflowinqueue",
                "calculatedderivedattributemetadata",
                "comment",
                "contact",
                "contactstate",
                "contact_opportunity",
                "contact_read",
                "conversation",
                "conversationparticipant",
                "conversation_item",
                "conversation_read",
                "currency",
                "currencyvalue",
                "customfield",
                "customfielddata",
                "dashboard",
                "derivedattributemetadata",
                "dropdowndependencyderivedattributemetadata",
                "email",
                "emailaccount",
                "emailbox",
                "emailfolder",
                "emailmessage",
                "emailmessagecontent",
                "emailmessageitemactivity",
                "emailmessagerecipient",
                "emailmessagesender",
                "emailmessagesenderror",
                "emailmessage_read",
                "emailsignature",
                "emailtemplate",
                "emailtemplate_read",
                "exportfilemodel",
                "exportitem",
                "filecontent",
                "filemodel",
                "gamebadge",
                "gamelevel",
                "gamenotification",
                "gamepoint",
                "gamepointtransaction",
                "gamescore",
                "globalmetadata",
                "import",
                "item",
                "jobinprocess",
                "joblog",
                "marketinglist",
                "marketinglistmember",
                "marketinglist_read",
                "meeting",
                "meeting_read",
                "messagesource",
                "messagetranslation",
                "mission",
                "mission_read",
                "namedsecurableitem",
                "note",
                "note_read",
                "notification",
                "notificationmessage",
                "opportunity",
                "opportunity_read",
                "ownedsecurableitem",
                "permission",
                "permitable",
                "person",
                "personwhohavenotreadlatest",
                "perusermetadata",
                "policy",
                "portlet",
                "role",
                "savedreport",
                "savedreport_read",
                "savedsearch",
                "savedworkflow",
                "securableitem",
                "socialitem",
                "socialitem_read",
                "task",
                "task_read",
                "workflowmessageinqueue",
                "_group",
                "_group__user",
                "_right",
                "_user",
                "__role_children_cache"
            ],
            "autoup": "1",
            "bkloc": "local",
            "autobk": "0",
            "title": "My Zurmo (3)",
            "cf-email": "admin@www1.installatron.com",
            "version-available": "2.2.1",
            "version-available-minor": "2.0.22",
            "version-autouped": "2.0.22",
            "version-notified": "2.0.22",
            "cf-login": "super",
            "cf-passwd": "",
            "backup-schedule": "1f9d83723e594ba1826adf517f869067",
            "backup-install": "ewr255xcvs0k0w0gwso80gck",
            "backup-location": "local",
            "backup-time": "1377427408",
            "backup-filename": "app_testing-installatron-com_My-Zurmo-3_2013-08-25_05-43-28.tar.gz",
            "cache-time": "1377427408",
            "cache-archive": "13836288"
        }
    ]
}

3.7. View/sync an installed application

List of arguments

NAME VALUE
cmd view
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
id
required
The ID of the installed application to be synced and displayed.
addons
optional
Set to a value of 1 to include a list of installed plugins and themes in the result. (WordPress only)

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Application details, similar to the "installs" API return value.

Sample return value

{
    "result": true,
    "message": "The task is complete.\n",
    "data": {
        "id": "4yhfygnd10ws0wc8skck444s",
        "file": "/home/dev1/.appdata/current/4yhfygnd10ws0wc8skck444s",
        "installer": "wordpress",
        "version": "3.5.2",
        "language": "en",
        "time": "1378531720",
        "agent": "9.0.0",
        "owner": "itwww1su",
        "path": "/home/dev1/domains/dev1.dev-is4.installatron.com/public_html/pppoposdopsd3",
        "path-created": "1",
        "url": "http://dev1.dev-is4.installatron.com/pppoposdopsd3",
        "url-domain": "dev1.dev-is4.installatron.com",
        "db-host": "localhost",
        "db-type": "mysql",
        "db-name": "dev1_wp3",
        "db-user": "dev1_wp3",
        "db-pass": "K@C^l2eMn6##7",
        "db-prefix": "wp_",
        "title": "My blog (3)",
        "list-files": [
            "index.php",
            "license.txt",
            ".htaccess",
            "wp-activate.php",
            "wp-admin",
            "wp-app.php",
            "wp-blog-header.php",
            "wp-comments-post.php",
            "wp-config-sample.php",
            "wp-config.php",
            "wp-content",
            "wp-cron.php",
            "wp-includes",
            "wp-links-opml.php",
            "wp-load.php",
            "wp-login.php",
            "wp-mail.php",
            "wp-settings.php",
            "wp-signup.php",
            "wp-trackback.php",
            "xmlrpc.php"
        ],
        "list-tables": [
            "wp_commentmeta",
            "wp_comments",
            "wp_links",
            "wp_options",
            "wp_postmeta",
            "wp_posts",
            "wp_term_relationships",
            "wp_term_taxonomy",
            "wp_terms",
            "wp_usermeta",
            "wp_users"
        ],
        "autoup": "1",
        "bkloc": "local",
        "autobk": "0",
        "cf-login": "admin",
        "cf-email": "admin@www1.installatron.com",
        "cf-sitetitle": "My blog",
        "cf-sitetagline": "Just another WordPress site",
        "cache-tables": "606208",
        "link-admin": "wp-admin",
        "cache-files": "15630336",
        "cache-time": "1380090388",
        "cache-numbackups": "9",
        "cf-passwd": "",
        "version-autouped": "3.5.2",
        "version-notified": "3.6.1",
        "time-updated": "1378553088",
        "cf-limitloginattempts": "no",
        "plugin-updates-available": 1,
        "plugin-updates-notified": "a:1:{i:0;s:25:\"akismet/akismet.php-2.5.9\";}",
        "theme-updates-notified": "a:2:{i:0;s:16:\"twentyeleven-1.6\";i:1;s:16:\"twentytwelve-1.2\";}",
        "autoup-plugins": "0",
        "autoup-themes": "0",
        "backup-time": "1379379513",
        "version-available": "3.6.1",
        "list-notification": [
            "clone",
            "clone_error",
            "backup",
            "backup_error",
            "restore",
            "restore_error",
            "update_available",
            "update",
            "update_error"
        ],
        "cache-preview": "5061",
        "theme-updates-available": null,
        "list-plugins": {
            "akismet/akismet.php": {
                "Name": "Akismet",
                "PluginURI": "http://akismet.com/?return=true",
                "Version": "2.5.8",
                "Description": "Used by millions, Akismet is quite possibly the best way in the world to <strong>protect your blog from comment and trackback spam</strong>. It keeps your site protected from spam even while you sleep. To get started: 1) Click the \"Activate\" link to the left of this description, 2) <a href=\"http://akismet.com/get/?return=true\">Sign up for an Akismet API key</a>, and 3) Go to your Akismet configuration page, and save your API key.",
                "Author": "Automattic",
                "AuthorURI": "http://automattic.com/wordpress-plugins/",
                "TextDomain": "",
                "DomainPath": "",
                "Network": false,
                "Title": "Akismet",
                "AuthorName": "Automattic",
                "_ud": {
                    "id": "15",
                    "slug": "akismet",
                    "new_version": "2.5.9",
                    "url": "http://wordpress.org/plugins/akismet/",
                    "package": "http://downloads.wordpress.org/plugin/akismet.2.5.9.zip"
                }
            },
            "hello.php": {
                "Name": "Hello Dolly",
                "PluginURI": "http://wordpress.org/extend/plugins/hello-dolly/",
                "Version": "1.6",
                "Description": "This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.",
                "Author": "Matt Mullenweg",
                "AuthorURI": "http://ma.tt/",
                "TextDomain": "",
                "DomainPath": "",
                "Network": false,
                "Title": "Hello Dolly",
                "AuthorName": "Matt Mullenweg"
            }
        },
        "list-themes": {
            "twentyeleven": {
                "Name": "Twenty Eleven",
                "Title": "Twenty Eleven",
                "Version": "1.6",
                "Author": "the WordPress team",
                "Author URI": "http://wordpress.org/",
                "Template": "twentyeleven",
                "Stylesheet": "twentyeleven"
            },
            "twentytwelve": {
                "Name": "Twenty Twelve",
                "Title": "Twenty Twelve",
                "Version": "1.2",
                "Author": "the WordPress team",
                "Author URI": "http://wordpress.org/",
                "Template": "twentytwelve",
                "Stylesheet": "twentytwelve"
            }
        }
    }
}

3.8. Edit an installed application

Updates the specified installed application by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the language parameter, that becomes the install's active language.

List of arguments

NAME VALUE
cmd edit
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
id
required
The ID of the installed application to be edited.
url
optional, defaults to the existing value
The URL to the installed application.
autoup
optional, defaults to the existing value
Change automatic update configuration. Values: 0 = Off; 1 = Update to minor versions only; 2 = Update to any version.
autoup_backup
optional, defaults to the existing value
Automatically create a backup and automatically restore the backup if the update fails. Values: 0 = Off; 1 = On (default).
notification
optional, defaults to the existing value
List of email notifications to send for the installed application (each separated with a comma). Omit this argument to retain the current value, set a value of "all" to send all notifications (limited by those that are enabled in administration » Emails), or define an empty string to send no notifications.

Available notifications:
install
install_error
clone
clone_error
backup
backup_error
restore
restore_error
update_available
update
update_error
plugin_update_available
plugin_update
plugin_update_error

A sample value could look like: "update_available,update,update_error"
db_host
optional, defaults to the existing value
The server that hosts the installed application's database.
db_name
optional, defaults to the existing value
The name of the installed application's database.
db_user
optional, defaults to the existing value
The database username used to connect to the installed application's database.
db_pass
optional, defaults to the existing value
The database username password.
db_prefix
optional, defaults to the existing value
The prefix each database table begins with, including trailing underscore (if any).

Automatic backup arguments:

NAME VALUE
autobk
optional, defaults to the existing value
Change automatic backup configuration. Values: custom = A custom schedule; (id) = The schedule identified by (id).
autobk_daily
optional, defaults to the existing value
The number of daily backups (for the "custom" option)
autobk_weekly
optional, defaults to the existing value
The number of weekly backups (for the "custom" option)
autobk_monthly
optional, defaults to the existing value
The number of monthly backups (for the "custom" option)

Remote backup arguments:

NAME VALUE
bkloc
optional, defaults to the existing value
Set this to the URI to a backup location (which will be associated with the defined "user" for the session).

Supported filesystem protocols:
FTP
FTPS
SFTP
SSH
WebDAV (HTTP)
WebDAVS (HTTPS)

Examples:
ftp://user:pass@server
sftp://user:pass@server/backups
ftp://user:pass@server/backups
webdav://user:pass@server/backups

Further arguments that depend on the application (get a full list of fields available for a specific application/version using the browser API):

NAME VALUE
language
optional, defaults to the existing value
The language of the installed application. Use the browser API to get a list of available languages for the installed application.
login
optional, defaults to the existing value
The username of the installed application's administrative account.
passwd
optional, defaults to the existing value
The password of the installed application's administrative account.
email
optional, defaults to the existing value
The email of the installed application's administrative account.
sitetitle
optional, defaults to the existing value
The site title value of the installed application.

Remove any backups connected to this installed application from the database:

NAME VALUE
delete-backups
optional, defaults to null
Set to 'true' to delete any backups connected to the installed application from the Installatron database. The backup archives will be unaffected.

Remove the installed application from the database:

NAME VALUE
delete
optional, defaults to null
Set to 'true' to delete the installed application from the Installatron database only. The installed application files and tables will be unaffected.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Further details regarding the success or failure.

3.9. Backup an installed application

List of arguments

NAME VALUE
cmd backup
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
id
required
The ID of the installed application to be backed up.
background
optional
When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

Possible values include:
Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc..
A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.
expiry
optional, defaults to never
Possible values include:
"never": The created backup will never expire. This is the default value.
"auto": Automatically expire the backup based on the configured backup expiration rules (the default is 14 days)
Any number: The created backup will expire after the number of days identified by the provided number.

NAME VALUE
cmd uninstall
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
id
required
The ID of the installed application to be uninstalled.
background
optional
When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task.

Possible values include:
Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc..
A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.

List of return values

3.16. List currently executing and recently completed tasks

List of arguments

NAME VALUE
cmd tasks
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data Table of currently executing and recently completed tasks.

Sample return value

{
    "result": true,
    "message": "The task is complete.\n",
    "data": [
        {
            "id": "138207901722178300",
            "user": "dev1",
            "ws_label": "dev1",
            "url": "http://dev1.dev-is4.installatron.com/pppoposdopsd3",
            "title": "My blog (3)",
            "label": "_tasks_backuping",
            "status": "processing",
            "rate": 10150,
            "percentMin": 50,
            "percentMax": 99,
            "message": "_tasks_shared_copyingfiles",
            "cmd": "backup",
            "install": "4yhfygnd10ws0wc8skck444s",
            "time": 1382079023
        }
    ]
}

3.17. Transferring a user into the Installatron Server GUI

The Installatron Server GUI is designed to "piggyback" an existing user or web hosting panel GUI. This model enables Installatron Server to be integrated seamlessly with existing infrastructure.

3.17.1. Accessing the GUI as a website owner

A session must be created before a user can be redirected to the Installatron Server GUI. This is accomplished by issuing a guixfer request.

List of arguments

NAME VALUE
cmd guixfer
key
required
part of the Request Header that must be included with all API requests
websites
required
part of the Request Header that must be included with all API requests
user
optional but recommended
part of the Request Header that must be included with all API requests
reseller
optional
part of the Request Header that must be included with all API requests
language
optional, default is the systemwide default language or English
The language the user interface should display in. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations. If omitted, the default language or English is assumed.
email
optional, default is the per website email value (if defined) or an empty string
An email address to display within the GUI. This value can also be defined per website.
package
optional
Specify a value that enables sets of users to be assigned different applications. For example, this might be set to "no_mysql" or "wordpress_only". The applications assigned are configured within the Installatron Server Admin GUI.
reseller
optional, default is the main administrator
Assign ownership to a reseller instead of the main administrator.

Examples

This example written in PHP initializes an Installatron Sever session and then redirects to the Installatron Server GUI:


<?php
$query = array(
    /* these values define the request header: */
    // Note: "key" is the "key=" from /usr/local/installatron/etc/settings.ini
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "websites" => array(
        array(
            "id" => "website123",
            "label" => "website.com",
            "path" => "ftp://".urlencode("website123")."@12.24.35.11",
            "vhosts" => array(
                "http://website.com" => "httpdocs",//@note it's assumed "path" is prefixed.
                "http://www.website.com" => "httpdocs",
            ),
            "email" => "user@mail.com"
        ),
        array(
            "id" => "website124",
            "label" => "company.com",
            "path" => "ftp://".urlencode("website124")."@12.24.36.22",
            "vhosts" => array(
                "http://company.com" => "httpdocs",
                "http://www.company.com" => "httpdocs",
                "https://company.com" => "httpsdocs",
                "https://www.company.com" => "httpsdocs",
            ),
            "email" => "user@mail.com",
            // Because we are transferring the user into a GUI, we need some mechanism to
            //  handle databases. See section 3.14.3 for more information.
            "db_mode" => "manual",
            "databases" => array(
                array(
                    "type" => "mysql",
                    "host" => "localhost",
                    "name" => "db134",
                    "user" => "db134",
                    "pass" => "0sdhfldsafh"//Note: Providing a password is optional.
                ),
                array(
                    "type" => "mysql",
                    "host" => "localhost",
                    "name" => "db135",
                    "user" => "db135"
                )
            )
        )
    ),
    /* these values define the request body: */
    "cmd" => "guixfer",
    "language" => "en"
);

$ch = curl_init("http://installatron.yourhost.com/index.php");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($query));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$reply = curl_exec($ch);

if ( $reply === false )
{
    echo "An error occurred: ".curl_error($ch);
    return;
}
else if ( strpos($reply,"Error:") === 0 )
{
    echo "An error occurred: ".$reply;
    return;
}

$reply = json_decode($reply,true);

if ( $reply["result"] === false )
{
    echo "An error occurred: ".$reply["message"];
    return;
}

header("Location: http://installatron.yourhost.com/index.php?s=".$reply["session_id"]);

3.17.2. Accessing the GUI as an administrative user or a reseller

Using a similar guixfer request, sessions for administrator and reseller users can also be created. To create a GUI session for an administrator, define the user member to match the "admin=" value in /usr/local/installatron/etc/settings.ini as shown below (the value is usually "admin"). To create a GUI session for a reseller (or sub-reseller), define the user member to the name of the reseller.

Note: Administrators and resellers can access the Installatron Server directly from the login screen if an account is pre-configured. By default the main administrator account is pre-configured. To pre-configure additional accounts reference 3.17.3. Create/edit user data within the Installatron Server database.

List of arguments

NAME VALUE
cmd guixfer
key
required
part of the Request Header that must be included with all API requests
type reseller
user An alphanumeric value that will represent the reseller. This argument will be used to index data and cannot change.
reseller
optional, default is the main administrator
Assign ownership to a reseller instead of the main administrator.

Example:


<?php
$query = array(
    /* these values define the request header: */
    "key" => "8327b11a311aad5a8092d26d209c9e13",
    "user" => "reseller123",
    /* these values define the request body: */
    "type" => "reseller",
    "cmd" => "guixfer",
);

3.17.3. Database management within the GUI

When using the Installatron Server API databases are always created prior to invoking the API. However, this model degrades when applied to the GUI, as it's often desired to limit each database to one installed application. The Installatron Server GUI can solve this problem in two different ways:

The preferred solution is to implement a PHP class that Installatron Server then uses to list, create, and delete databases. Under the default configuration, this solution creates a separate database for each installed application.
A second, more simple solution is keep the API's model of pre-creating databases. Database information can be set per website in the "guixfer" API request. However, a warning: there are some applications (SugarCRM, Tiki Wiki) that don't support table prefixes, so attempting to install these applications will cause database table collisions. We recommend disabling these applications when this solution is used. See the above example (in section 3.14.2) to reference how to implement this solution.

To use the preferred solution, implement each of the below PHP methods into the /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:


<?php
class i_custom extends i_panel
{

/**
 * This method enables you to format the database name Installatron Server will expect to be created.
 *
 * @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)
{
    //@note
    // itron::$session is a PHP array referencing the selected website. If you define "_some_prefix"
    // when calling "guixfer" for the selected website it will be available in this array.
    // All custom variable names must begin with an underscore (_).
    $prefix = itron::$session["_some_prefix"]."_";

    // Maximum database name length, including prefix.
    $len_max = 16;
    $len_less_prefix = $len_max-strlen($prefix);

    //@note
    // This must generate a UNIQUE database name that can be passed to createDB to be created.
    // PHP's uniqid function uses the system microtime, and this is often good enough
    $db_name = $prefix.substr(uniqid(), 0, $len_less_prefix);

    $db_host = "localhost";
    $db_user = $db_name;//same as the db name
    
    $db_pass = null;//let Installatron create a randomized value.
    $db_table_prefix = null;//let Installatron manage table prefixes

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

/**
 * 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 successful; false otherwise
 */
public function createDB($name, $user, $pass, $type, $host)
{
    switch($type)
    {
    case "mysql":

        //@todo
        // create the database here

        return true;
    }
    return false;
}

/**
 * Remove a database.
 *
 * If database usernames 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 successful; false otherwise
 */
public function removeDB($name, $type)
{
    switch($type)
    {
    case "mysql":
   
           //@todo
        // 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;
}

}

Don't hesitate to contact Installatron Support with any questions.

3.18. Advanced

3.18.1. Define a website path on demand

Most commonly the path variable for each website is directly defined within the Request Header. This optional method allows the path variable to be omitted from the Request Header. This can provide a superior level of security since path authentication information can be activated or created only when needed.

The disablePathByWebsite method is called between 30 minutes and 4 hours after a session's last action.

To use this method, implement each of the below PHP methods into the /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:


<?php
class i_custom extends i_panel
{

/**
 * Return the path URI for the provided website. 
 *
 * @param   array   An array of website information as defined in the Installatron Server API Request Header.
 * @return  string  The URI for the website path, as it would have been defined for the Installatron Server Request Header.
 */
public function enablePathByWebsite($websiteInfo)
{
    return "ssh://".urlencode("user").":".urlencode("pass")."@11.42.62.82/domains";
}

/**
 * Disable the path, if necessary, when Installatron Server no longer requires access.
 *
 * @param   array   An array of website information as defined in the Installatron Server API Request Header.
 * @return  bool    true if successful; false otherwise
 */
public function disablePathByWebsite($websiteInfo)
{
    return true;
}

}

Contact Installatron Support with any questions.

3.18.2. Improve FTP file operation performance

Installatron Server uses the path defined within the Request Header to communicate with the destination web server. Due to the nature of the protocol, all FTP-based protocols (FTP, FTPS and SFTP) limit the speed at which file operations can be completed.

To improve performance when using a FTP-based protocol, a SSH connection can be activated on demand which enables Installatron Server to execute commands efficiently on the destination web server.

To use this option, implement each of the below PHP methods into the /usr/local/installatron/etc/panel.php PHP file. Here's sample code to get started:


<?php
class i_custom extends i_panel
{

/**
 * Return the path URI for the provided website. 
 *
 * @param   array   An array of website information as defined in the Installatron Server API Request Header.
 * @return  string  The URI for the website path, as it would have been defined for the Installatron Server Request Header.
 */
public function enableSecondaryPathByWebsite($websiteInfo)
{
    return "ssh://".urlencode("user").":".urlencode("pass")."@11.42.62.82/domains";
}

/**
 * Disable the path, if necessary, when Installatron Server no longer requires access.
 * This method is called immediately after the connection is no longer needed by Installatron Server.
 *
 * @param   array   An array of website information as defined in the Installatron Server API Request Header.
 * @return  bool    true if successful; false otherwise
 */
public function disableSecondaryPathByWebsite($websiteInfo)
{
    return true;
}

}

Contact Installatron Support with any questions.

3.18.3. Create/edit user data within the Installatron Server database

This optional method enables Installatron Server user and associated website data to be modified (or created if the user doesn't exist).

By default all users are owned by the main administrative user. Creating resellers and/or sub-resellers allows sets of users to be managed separately and assigned different branding, theming, and other settings.

Note: It is not necessary to create users prior to transferring them into the Installatron Server GUI. Please reference 3.16.1. Accessing the GUI as a website owner for more information.

List of arguments

NAME VALUE
cmd edituser
key
required
part of the Request Header that must be included with all API requests
user
required
The ID of the user to edit or create.
type
optional, default is the existing value or "user" for new users
The type of user. Valid values are "user" and "reseller".
websites
optional, default is the existing value or no websites for new users
List of websites for the user. Please reference 3.1. Request Header for arguments. Reseller-type users can have their own websites defined, however typically this argument is omitted for resellers.
language
optional, default is the existing value or the systemwide default language or English for new users
The language the user interface should display in. For example, "en" for English or "nl" for Dutch. See: Available Installatron Translations. If omitted, the default language or English is assumed.
email
optional, default is the existing value or the per website email value (if defined) or an empty string for new users
An email address for the user. This value can also be defined per website.
package
optional, default is the existing value or an empty string for new users
Specify a value that enables sets of users to be assigned different applications. For example, this might be set to "no_mysql" or "wordpress_only". The applications assigned are configured within the Installatron Server Admin GUI.
reseller
optional, default is the existing value or the main administrator for new users
Assign ownership to a reseller instead of the main administrator.
suspended
optional, default is the existing value or "no" for new users
Whether the user is suspended. Valid values are "yes" and "no".

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data List of deleted users.

3.18.4. Remove user data from the Installatron Server database

This optional method enables Installatron Server user and associated website data to be deleted, for example after an account is terminated.

List of arguments

NAME VALUE
cmd deleteuser
key
required
part of the Request Header that must be included with all API requests
user
required
The ID of the user to be deleted. All websites and associated installed app data will be removed from the Installatron Server database.

List of return values

NAME VALUE
result true on success, or false on failure.
message Success or failure message.
data List of deleted users.

3.18.5. High Availability and Installatron Server Clusters

Configure multiple Installatron Server nodes to share one central database. API and UI requests can then be executed on any Installatron Server node in the cluster.

To configure a cluster, first setup one Installatron Server node following the instructions at the top of this guide. The MySQL database can be hosted on this node or a remote database server.

Next, add additional Installatron Server nodes using the modified setup instructions below. Notice the --db-xxx arguments are added to point to the existing node's database.

curl -O https://data.installatron.com/installatron-server.sh
chmod +x installatron-server.sh
yum -y remove httpd
./installatron-server.sh -f --edge --key YOUR_LICENSE_KEY --db-host=sql.yourhost.com --db-user=youruser --db-pass=yourpass --db-name=itron

Note: These commands are intended for CentOS 7, RHEL 7 and Amazon Linux. If a different OS is desired, modify the commands based on the install commands at the top of this guide.

Warning: Copying /usr/local/installatron/etc/settings.ini between nodes is not recommended as it contains values specific to each node.

Contact Installatron Support with any questions.

4. Maintaining Installatron Server

This additional information can be helpful maintaining Installatron Server.

4.1. How app updates work

The settings at Installatron Admin > Settings control how frequently Installatron Server checks for new app updates by configuring the crontab process at /etc/cron.d/installatron. When this crontab process executes, Installatron Server checks every installation to determine whether an update is available, and if automatic update is enabled then Installatron Server will automatically queue the update task, otherwise an email notification will be sent to inform the customer that an update is available.

Installatron Server utilizes a task queue to prevent the system from overloading due to too many tasks. No more than the number of tasks configured at Installatron Admin > Settings can execute concurrently.

As of Installatron Server 4.1.15, a new setting at Installatron Admin > Features > Force Update After enables server administrators to configure Installatron Server to forcibly update installed apps after a set number of days have elapsed since the update became available. This feature can be useful to enforce an update policy.

4.2. Settings.ini values

The /usr/local/installatron/etc/settings.ini file is provisioned automatically during installation and generally doesn't require manual changes. Commonly modified values are documented here.

NAME VALUE
key
required
The product key.
noperl
optional, default is "no"
Installatron Server uses Perl .cgi files on the destination web server to speed up tasks. If Perl is not supported, this setting should be set to "yes" to avoid every task having to test Perl.
update
required, default is "release"
The update channel. Valid values include "edge", "release", "stable", or "never" to switch off automatic updates.
debug
optional, default is "no"
Set to "yes" to enable the debug log at /var/installatron/logs/debug_log which contains very verbose output which can be useful tracking down a multitude of issues.
db_type
required, default is "mysql"
The type of database server. Mysql and sqlite supported. This setting is configured automatically during installation to use MySQL.
db_host
required for mysql, default is configured automatically
The database server.
db_name
required for mysql, default is configured automatically
The database.
db_user
required for mysql, default is configured automatically
The database username.
db_pass
required for mysql, default is configured automatically
The database password.
num_cpu
optional, default is the number of CPU threads multiplied by two
The number of tasks allowed to execute concurrently systemwide.
num_cpu_perserver
optional, default is 5
The number of tasks allowed to execute concurrently per web server.
db_schema_update
optional, default is yes
Whether database schema updates should be automatically managed by Installatron (recommended: yes).

4.3. Command-line tools

Forcibly update/repair the entire system:

/usr/local/installatron/repair -f --quick

Reset administrative login:

/usr/local/installatron/installatron --repair --reset-admin

Forcibly check for customer app updates:

/usr/local/installatron/repair -f --quick
/usr/local/installatron/installatron --send-update-report --full

Forcibly check for customer app updates for user named bob:

/usr/local/installatron/repair -f --quick
/usr/local/installatron/installatron --send-update-report --full --user bob

4.4. API Changelog

4.0.6 (2016-01-11)

Added documentation for Debian 8 support.
Added documentation for remote database support.

4.0.5 (2015-10-08)

Added documentation for the new importbackup API.

4.0.4 (2015-09-23)

Added documentation to browser API for the field sort_order member.

4.0.3 (2015-09-18)

Added documentation to Request Header for the optional "suspended" argument.
Added documentation to edituser API for the optional "suspended" argument.
Added documentation to Settings.ini values for the "noperl" option.

4.0.2 (2015-06-30)

Added documentation to Request Header for the optional "server" argument.
Added documentation to How app updates work for the new Force Update After feature.

4.0.1 (2015-06-25)

Added documentation to Request Header for SFTP and SSH key-based authentication.