Print this page

API Documentation

BlueOnyx now 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 there are two modules: One for BlueOnyx 5100R (covers 5106R, 5107R and 5108R) and one for BlueOnyx 5200R (which covers BlueOnyx 5207R, 5208R and 5209R).

Installation:

The API can be optionally installed on any BlueOnyx. It is available via YUM and in future releases it might get included in the standard installation of BlueOnyx. To install the API, run the command "yum install base-api*". After the installation has finished, the API itself is disabled for security reasons. If you want to use it, you need to enable it first in the GUI.

Configuration:

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.

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 5207R/5208R/5209R:

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

BlueOnyx 5106R/5107R/5108R:

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

The API URL will only perform actions on POST requests which match certain criterias. 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 "Product/Services" in WHMCS and add a new server. In the "Type" pulldown you will see "Blueonyx5100r":

This covers BlueOnyx 5106R, 5107R and 5108R. The new BlueOnyx 5207R, 5207R and BlueOnyx 5209Rhave their own API module, as the URL structure of the GUI is different. So please install the correct API module into WHMCS - depending on which type of BlueOnyx model you want to administer.

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 of various Vsite options
  • Suspend
  • Unsuspend
  • Terminate (i.e.: delete Vsite, User and all associated data)
  • Change hosting package
  • Change password
  • Reboot server
  • Shutdown server
  • 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 "Basic" hosting package:

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

  • Disk space
  • Maximum number of users for Vsite
  • Automatic DNS enabled / disabled
  • Java Servlet Pages (JSP) enabled / disabled
  • PHP (No, Yes or suPHP - also mod_ruid2 and FPM for 5209R)
  • Auto-creation of MySQL database & user
  • Bandwith limits (enabled / disabled) plus the actual limit itself
  • FTP for non siteAdmins allowed (enabled / disabled)
  • User owned /web directories (enabled / disabled)
  • Optional Shell access for user accounts (enabled / disabled)
  • Sub-Domains (enabled / disabled) and how many of them.
  • Enable automatic setup of email forwarding for the siteAdmin.

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.

Special note for suPHP usage: If suPHP is enabled, 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 is 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:

An API for BlueOnyx has been requested very early on, but priority wise I always put that on the backburner. However, thanks to suggestions from Chris Gebhardt from VIRTBIZ Internet Services (and a substantial "bribe" - not to forget that!) I hammered the API out in three days. It's not perfect yet and mainly centered on providing a backend that WHMCS can "talk" to for provisioning. However: This new 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/web/base/api/index.php (5106R, 5107R, 5108R)
  • /usr/sausalito/ui/chorizo/ci/application/modules/base/api/controllers/apiindex.php (5207R, 5208R, 5209R)

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 5207R/5208R/5209R:

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

BlueOnyx 5106R/5107R/5108R:

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

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

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>
                                    [mysql] => <0|1>
                                    [cgi] => <0|1>
                                    [ssi] => <0|1>
                                    [bwlimit] => <0|1>
                                    [bwlimitVal] => <Number in Kilobits, no unit>
                                    [ftp] => <0|1>
                                    [userwebs] => <0|1>
                                    [shell] => <0|1>
                                    [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>
                                    [mysql] => <0|1>
                                    [cgi] => <0|1>
                                    [ssi] => <0|1>
                                    [bwlimit] => <0|1>
                                    [bwlimitVal] => <Number in Kilobits, no unit>
                                    [ftp] => <0|1>
                                    [userwebs] => <0|1>
                                    [shell] => <0|1>
                                    [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