API Documentation

Aventurin{e} now has an API for remote provisioning of OpenVZ VPS's, for suspending or deleting VPS's, for password changes and status checks. It was designed especially with WHMCS in mind.

A WHMCS module to manage Aventurin{e} servers is available free of charge here.

Installation:

The API can be optionally installed on any Aventurin{e} 6108R node. It is available via YUM. To install the API, run the command "yum install base-api*". This will install both the GUI modules for Aventurin{e} and also the OS templates that the API module supports. 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 Aventurin{e} server and go to "Server Management" / "Maintenance" / "API":

There are four configurable options:

  • Enable API (default: off)
  • Force HTTPS (default: on)
  • API Host(s) (default: empty)
  • Usable VPS IP'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.

Lastly: Each VPS needs a dedicated IP address. Under "Usable VPS IP's" you need to specify which IP addresses WHMCS may use to create VPS's. Whenever WHMCS creates a VPS, it will check if at least one of the IP addresses listed here is still free. If so, it will use the first free IP address for the creation of the VPS. Once a VPS is terminated and removed, the IP address it previously occupied can be used for the creation of the next WHMCS provisioned VPS. You can only create as many VPS's via WHMCS as you have usable IP addresses listed here.

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 Aventurin{e} GUI. The API URLs are:

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

The API URL will only perform actions on POST requests which match certain criteria. If you access the URL without a POST request, the API will just respond with "Aventurin{e} 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 Aventurin{e} 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 "Aventurine6108r":

This covers Aventurin{e} 6108R.

Once you have added your Aventurin{e} server to WHMCS, you can start to provision services and users like shown here:

Supported WHMCS functionality:

  • Accounts of type "Dedicated/VPS Server" only.
  • Creation, suspension and management of VPS's
  • Enabling/disabling of various VPS options
  • Suspend
  • Unsuspend
  • Terminate (i.e.: delete VPS)
  • Creation of a user account on Aventurin{e} which the client can use for status checks and backup/restore.
  • Change hosting package (adjust RAM, Swap, Diskspace etc.)
  • Change password
  • Reboot VPS
  • Shutdown VPS
  • Automatic inclusion of the provisioned VPS's in the Aventurin{e} backups.
  • 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 an Aventurin{e} 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 VPS features can be managed on an Aventurin{e}:

  • OS Template
  • Amount of RAM
  • Amount of Swap
  • Amount of available disk space
  • Disk type (Simfs/Ploop)
  • Auto-Start
  • Netfilter/IPtables access
  • CPU-Units

Available OS templates for provisioning through the Aventurin{e} 6108R WHMCS module:

  • BlueOnyx 5207R
  • BlueOnyx 5208R
  • BlueOnyx 5209R
  • CentOS 6 i686 Minimal
  • CentOS 6 x86_64 Minimal
  • CentOS 7 x86_64 Minimal

If you have multiple hosting packages for Aventurin{e}, you or the WHMCS client can upgrade and/or downgrade their packages. During such transactions the new settings will be pushed out to the Aventurin{e} server to modify the account in question. Please note: The used OS Template and disk type (Simfs/Ploop) cannot be changed during a package change. But any other parameters can be changed.

Client experience:

When a client uses your WHMCS to order an Aventurin{e} 6108R VPS and logs into your WHMCS webpage to check the provision service, he will see something like this:

He can see which IP address the VPS is running on and he has management actions at his disposal to shutdown or reboot the VPS. He can also change the password of the "root" account via the "Change Password" menu. Additionally at the bottom of this page is a button labled "Login to Control Panel". When the client clicks on this, then he is automatically redirected and logged in into the Aventurin{e} GUI:

In the Aventurin{e} GUI he can see all VPS's that he has provisioned through WHMCS. This allows him to check their status, traffic graphs and certain configuration items, which are mostly read only. The only "real" transactions he can do are limited to:

  • Password change of his Aventurin{e} account
  • Password change of his owned VPS(s)
  • Killing processes in his VPS(s)
  • VPS stop, start, reboot
  • VPS restore from local or remote backup

Please note: VPS restore from local or remote backup are only available if the Aventurin{e} backup itself is configured and active on the Aventurin{e} 6108R node.

Server Status:

In the WHMCS list of servers any Aventurin{e} 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) 
Previous page: License Next page: Get Aventurin{e}