Cloudmin Services API

Using the Services API

When a Virtualmin system requests the creation of a DNS zone or MySQL database, it makes an HTTP call to the Cloudmin master, using the request format documented on the Cloudmin remote API page. Even though this API was initially designed for internal use between Virtualmin products, it can also be called by other programs that want to create DNS zones or databases.

This allows the managed of a Cloudmin installation to offer services similar to Amazon's hosted DNS and MySQL products, and frees customers from having to run their own BIND or MySQL server.

Cloudmin Services API Access

The Cloudmin API requires a system owner login and password to access, which can be created as documented on the Cloudmin Services and system owners page. API caller must use the system owner login and password for HTTP authentication when making requests.

The system owner must also be granted permissions to make Cloudmin API calls, just as they would if services creation was going to be done from client systems by Virtualmin.

Calling the API

The Cloudmin Services client adds several new commands to the core API, which are documented on the services section of the API documentation.

For example, to create a new MySQL login and database from the Unix shell on another system, you could use the commands :

curl "http://owner:password@cloudminmaster:10000/server-manager/remote.cgi?program=provision-mysql-login&user=dblogin&pass=smeg&domain-owner="
curl "http://owner:password@cloudminmaster:10000/server-manager/remote.cgi?program=provision-mysql-database&database=junk&user=dblogin"

In these examples, owner is the system owner login, password is his password, cloudminmaster is the Cloudmin system, dblogin is the MySQL user, and junk is the MySQL database name.

When the first command is run, assuming it is successful it will return a line like :

OK: host=provisioningmachine

This tells the caller which MySQL host system the login and database have been created on. Any subsequent API calls to mange or remove the login or database must include a host URL parameter whose value is this hostname. For example, to delete the database you could use :

curl "http://owner:password@cloudminmaster:10000/server-manager/remote.cgi?program=unprovision-mysql-database&database=junk&host=provisioningmachine"

API Output

Cloudmin Services API commands that perform some action output a line that starts with OK on success, like :

OK: host=something

Or on failure, they will produce a line like :

ERROR: User dblogin is not a domain owner

If called with incorrect parameters, a summary of valid parameters is returned instead.

Some API commands return information, such as records in a DNS zone or users with access to a MySQL database. For example, the following command :

curl "http://owner:password@cloudminmaster:10000/server-manager/remote.cgi?program=list-provision-mysql-users&database=junk&host=provisioningmachine&multiline=&json="

This requests a list of users who can access the junk database. The multiline= parameter indicates that the command should provide machine-parseable output, and json= indicates that you want it in JSON format. Other formats can be selected with perl= or xml= . The output of this example would be :

"status" : "success",
"data" : [
"name" : "dblogin",
"values" : {
"hosts" : [
"password" : [
"databases" : [
"command" : "list-provision-mysql-users"