API Documentation

BlueOnyx includes an API for remote provisioning of Vsites and Users, for suspending or deleting Vsites, for password changes and status checks. It was designed especially with WHMCS in mind.

A WHMCS module to manage BlueOnyx servers is available free of charge here. Please note that the Tarball includes three modules: One for BlueOnyx 5209R, one for BlueOnyx 5210R and one for BlueOnyx 5211R.

Differences between the two modules:

The only difference between the modules is in the handling of Shell and PHP access.

If you *do* allow Shell access in your product and use the 5209R WHMCS module to deploy to a 5210R or 5211R server, then the created account(s) will not receive full shell access (as they would get on a 5209R), but would receive "Chrooted (SFTP SCP RSYNC)" instead. Also note that 5211R only supports suPHP and PHP-FPM, whereas 5209R and 5211R also have DSO and mod_ruid2 options that 5211R no longer has.

Installation and Configuration:

BlueOnyx 5209R, 5210R and 5211R already ship with the API module (base-api-*) installed. By default the API itself is disabled for security reasons. If you want to use it, you need to enable it first in the GUI.

To enable the API login into the GUI of your BlueOnyx server and go to "Server Management" / "Maintenance" / "API".

 

There are only three configureable options:

  • Enable API (default: off)
  • Force HTTPS (default: on)
  • API Host(s) (default: empty)

Unless "Enable API" is ticked, the API will be disabled. If "Force HTTPS" is ticked, the API will only respond to HTTPS connections. Lastly, "API Host(s)" allows you to restrict access to the API, so that only certain IP addresses can access the API functionality. For security reasons you should both force HTTPs and restrict access via IP addresses. IPs added to the field "API Host(s)" are also excempt from the CSRF protection that usually protects the GUI against unsolicited POST requests.

Basic Usage Information:

The API runs on AdmServ (port 444 for HTTP and port 81 for HTTPS), as it needs to communicate with the CCE backend of the BlueOnyx GUI. The API URLs are:

BlueOnyx 5209R/5210R/5211R:

  • https://<server-ip>:81/api/index
  • http://<server-ip>:444/api/index

The API URL will only perform actions on POST requests which match certain criteria. Which will be outlined in the course of this document. If you access the URL without a POST request, the API will just respond with "BlueOnyx API: You're not doing this right.", regardless if the API is enabled, disabled, forced to HTTPS or limited to certain IP addresses. If incorrect POST requests are sent, it might respond with the same phrase, or might give some different messages in return.

All accesses to the API are logged to /var/log/admserv/adm_access and /var/log/admserv/adm_error. In /var/log/admserv/adm_error it will log the IP of the accessing host and the transaction that was attempted to be transformed. 

Best Usage Experience:

If you are using WHMCS, simply grab the BlueOnyx API server module from here and install it on your WHMCS server by extracting the contends of the tarball into the correct folders. The directory structure of the tarball should tell you where this goes.

Once that module is installed, click on "System Settings" and "Add Servers" to tie your BlueOnyx into WHMCS. See the clip below how that is done.

Once you have at least one BlueOnyx added to WHMCS, go to "Product/Services" in WHMCS and add a new "Shared Hosting" entry. In the "Module" pulldown you will see "Blueonyx5209r" and "Blueonyx5210r". Choose the module that matches with the BlueOnyx that you want to provision in WHMCS. The video below shows how to do this for BlueOnyx 5210R:

BlueOnyx 5209R, BlueOnyx 5210R and BlueOnyx 5211R each have their own API module, as the API is slightly different between those two. So please install the correct API module into WHMCS - depending on which type of BlueOnyx model you want to administer. You can also install all at the same time in case you want to manage BlueOnyx 5209R, 5210R and 5211R servers.

Once you have added your BlueOnyx server to WHMCS, you can start to provision sites and users on them. 

Supported WHMCS functionality:

  • Accounts of type "Hosting Account" only at this time.
  • Authentication via "admin" and the admin password
  • Creation of Vsites with a siteAdmin user
  • Enabling/disabling and configuration of various Vsite options
  • Suspend
  • Unsuspend
  • Terminate (i.e.: delete Vsite, User and all associated data)
  • Change hosting package
  • Change password
  • Status check of Active Monitor
  • Automatic login into the GUI for both clients and WHMCS admins

When you create a "Product" in WHMCS that uses a BlueOnyx server as backend, then you can configure various hosting packages which have different settings and features active. Below is a screenshot of the "Module Settings" of a sample hosting package realized via the BlueOnyx 5210R module:

As you can see, the following Vsite features can be managed on a BlueOnyx:

  • Disk space
  • Automatic DNS enabled / disabled
  • PHP (5209R/5210R: No, Yes, mod_ruid2, suPHP or FPM, BlueOnyx 5211R: No, suPHP or FPM)
  • PHP Version (if suPHP or FPM are used an the BlueOnyx has optional PHP PKGs installed)
  • MySQL and how many databases the user is allowed to use and manage.
  • User owned /web directories (enabled / disabled)
  • Shell Access (5209R: Yes/No, 5210R and 5211R: None, Chrooted (SFTP, SCP, RSYNC), Chrooted (Shell, SFTP, SCP, RSYNC), Full Shell Access)
  • Notes
  • Access GUI via SSL
  • Maxmimum number of Users
  • Java Servlet Pages (JSP) enabled / disabled
  • Server Side Includes (SSI)
  • Perl Scripts (CGI)
  • FTP for non siteAdmins allowed (enabled / disabled)
  • Enable automatic setup of email forwarding for the siteAdmin.
  • Sub Domains
  • Number of allowed Sub Domains

If you have multiple hosting packages for BlueOnyx, you or the WHMCS client can upgrade and/or downgrade their packages. During such transactions the new settings will be pushed out to the BlueOnyx server to modify the account in question.

When a client has a BlueOnyx based product assigned to him, then it looks like this in the WHMCS Client Profile in the admin GUI of WHMCS:

On a glance you can see all relevant details such as disk usage and enabled features. From here you can suspend, unsuspend or terminate the webhosting package. Or you can switch the client to a different BlueOnyx based package instead which may or may not have different features. A password change of the associated client admin account is also possible. The central (blue) "Login to Control Panel" button will directly log you into the GUI of the BlueOnyx where this package is hosted. The other "Login to Control Panel" button on the right is sadly not working as I couldn't figure that part out.

Special note for suPHP and FPM usage: If suPHP or FPM are enabled, then the auto-created siteAdmin will automatically be set as "Web Owner" of the /web folder of that Vsite. This saves some administrative hassles for you, as the user will immediately be able to upload web content by FTP. If suPHP or FPM are disabled later on due to hosting package changes, the web ownership will be corrected automatically by the API.

Server Status:

In the WHMCS list of servers any BlueOnyx server you have under management also reports its "Active Monitor" status to your WHMCS console:

The information is from the last Active Monitor run and is therefore up to 15 minutes old.

Possible AM-Status messages are:

  • OK  - (All monitored items in the green)
  • Fault - (One or more monitored items is in the yellow)
  • Problem - (One or more monitored items is in the red)
  • Unknown - (Unable to poll AM status due to network or API problems) 

Detailed API documentation:

Preface:

The API for BlueOnyx had been requested by Chris Gebhardt VIRTBIZ Internet Services and a substantial "bribe" later it was eventually implemented. The main intent of the API is to provide an easy interface to tie it into WHMCS for provisioning of shared hosting accounts via our WHMCS-BlueOnyx-5200R module for WHMCS

However: This API can also be used by other provisioning solutions, provided you pass the correct parameters to the API. You could even write your own "interface" to poll and manage your BlueOnyx servers via the API. This guide will explain how to do that without diving too deep into the PHP coding dungeon.

API location:

  • /usr/sausalito/ui/chorizo/ci/application/modules/base/api/controllers/apiindex.php (5209R)
  • /usr/sausalito/ui/chorizo/ci/application/modules/base/api/controllers/Apiindex.php (5210R)

If you're fluent in PHP, then I recommend to check the API PHP script directly.

If you're really fluent in PHP, then I could just say: "End of API documentation" or "read the source". But lets take closer look first.

Supported Request Types:

  • POST

If it's not a POST request you're sending to the API URL, then don't bother. You'll not get any meaningful reply. GET requests are not supported.

Supported Protocols:

  • HTTP via port 444
  • HTTPS via port 81

URLs:

BlueOnyx 5209R/5210R/5211R:

  • https://<server-ip>:81/base/api/index
  • http://<server-ip>:444/base/api/index

Authentication:

  • key: "login" - value: "admin"
  • key: "pass" - value: <admin password of the server>

It *may* be possible to use another serverAdmin account than "admin", although this is not really fully supported, as "serverAdmin" accounts generally have slightly less privileges than the usual "admin" account. In any case only "serverAdmin" users are allowed to use the API functionality. If a regular user or siteAdmin tries to use the API, they get redirected to the "forbidden" Error page of the BlueOnyx GUI.

API responses:

  • success
  • Various error messages

Generally the API is not very talkative. It's not entirely tight lipped either. But the responses are either "success" (in case the transaction went through without error. Or you get a very generic error message that does not take you by the hand to walk you through your faulty request and points out exactly where you have gone wrong. Sorry, but deal with it.

Supported API Calls:

The following API calls are supported and will be explained in more details:

  • create: Creates a Vsite and siteAdmin user
  • changepass: Changes the password of a siteAdmin user
  • suspend: Suspends a Vsite
  • unsuspend: Unsuspends a Vsite
  • destroy: Destroys and deletes a Vsite, all its users and associated data
  • modify: Modifies the settings of a Vsite and it's siteAdmin user
  • reboot: Reboot the server
  • shutdown: Shutdown the server
  • statusdetailed: Generate a detailed and fresh Active Monitor report
  • status: Very brief report of the last know Active Monitor status
  • vsitestatus: Polls a Vsite for a predefined set of parameters

Sample "create" transaction:

Array(
    [action] => create
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(
                                    [producttype] => hostingaccount
                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [disk] => <Vsite Diskspace in MB, number, no unit>
                                    [users] => <Max num of users for Vsite>
                                    [auto_dns] => <0|1>
                                    [jsp] => <0|1>
                                    [php] => <No|Yes|suPHP|ModRUID|FPM>
                                    [mysql] => <Number of databases, 0 = off>
                                    [cgi] => <0|1>
                                    [ssi] => <0|1>
                                    [bwlimit] => <0|1>
                                    [bwlimitVal] => <Number in Kilobits, no unit>
                                    [ftp] => <0|1>
                                    [userwebs] => <0|1>
                                    [shell] => <0|1> (on 5209R) <0|1|2|3> (on 5210R)
                                    [subdomains] => <0|1>
                                    [subdomainsMax] => <Number of subdomains>
                                    [forwardemail] => <0|1>
                                    [comments] => <Text>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )
                                )
                           )
)

The "POST" transaction you submit should contain the Array as shown above. Both "payload" and "clientdetails" within that are JSON encoded Arrays.

Sample "changepass" transaction:

Array(
    [action] => changepass
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(

                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )

                           )
)

The "POST" transaction you submit should contain the Array as shown above. Again "payload" is a JSON encoded Array. 

Sample "suspend" transaction:

Array(
    [action] => suspend
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(
                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )
                                )
                           )
)

The "POST" transaction you submit should contain the Array as shown above.

Sample "unsuspend" transaction:

Array(
    [action] => unsuspend
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(
                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )
                                )
                           )
)

The "POST" transaction you submit should contain the Array as shown above.

Sample "destroy" transaction:

Array(
    [action] => destroy
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(
                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )
                                )
                           )
)

The "POST" transaction you submit should contain the Array as shown above.

Sample "modify" transaction:

Array(
    [action] => modify
    [login] => admin
    [pass] => <admin-pass>
    [payload] => json_encode(
                             Array(
                                    [producttype] => hostingaccount
                                    [ipaddr] => <IP-Address>
                                    [domain] => <FQDN or Hostname of Vsite>
                                    [username] => <siteAdmin-Username>
                                    [password] => <siteAdmin-Password>
                                    [disk] => <Vsite Diskspace in MB, number, no unit>
                                    [users] => <Max num of users for Vsite>
                                    [auto_dns] => <0|1>
                                    [jsp] => <0|1>
                                    [php] => <No|Yes|suPHP|ModRUID|FPM>
                                    [mysql] => <Number of databases, 0 = off>
                                    [cgi] => <0|1>
                                    [ssi] => <0|1>
                                    [bwlimit] => <0|1>
                                    [bwlimitVal] => <Number in Kilobits, no unit>
                                    [ftp] => <0|1>
                                    [userwebs] => <0|1>
                                    [shell] => <0|1> (on 5209R) <0|1|2|3> (on 5210R)
                                    [subdomains] => <0|1>
                                    [subdomainsMax] => <Number of subdomains>
                                    [forwardemail] => <0|1>
                                    [comments] => <Text>
                                    [clientsdetails] =>
                                              json_encode(
                                                          Array(
                                                                 [firstname] => <Text>
                                                                 [lastname] => <Text>
                                                                 [email] => <Email-Address>
                                                               )
                                                         )
                                )
                           )
)

The "POST" transaction you submit should contain the Array as shown above. This is essentialy the same data as with the "create" transaction, except for the different "action" type of "modify" instead of "create".

Sample "reboot" transaction:

Array(
    [action] => reboot
    [login] => admin
    [pass] => <admin-pass>
)

The "POST" transaction you submit should contain the Array as shown above. Payload or JSON encoding not needed.

Sample "shutdown" transaction:

Array(
    [action] => shutdown
    [login] => admin
    [pass] => <admin-pass>
)

The "POST" transaction you submit should contain the Array as shown above. Payload or JSON encoding not needed.

Sample "statusdetailed" transaction:

Array(
    [action] => statusdetailed
    [login] => admin
    [pass] => <admin-pass>
)

The "POST" transaction you submit should contain the Array as shown above. Payload or JSON encoding not needed. Instead of "success" or an error message it returns a freshly generated and detailed summary of the "Active Monitor" status of this server.

Sample "status" transaction:

Array(
    [action] => status
    [login] => admin
    [pass] => <admin-pass>
)

The "POST" transaction you submit should contain the Array as shown above. Payload or JSON encoding not needed. Instead of "success" or an error message it returns the most recent "Active Monitor" status in the form of either "G" (for "green", "Y" (for "yellow") or "R" (for "red").

Possible return values:

Except for "statusdetailed" and "status" all functions will return either "success" for a sucessful transaction, or an error message.

Previous page: Features Next page: News