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" : [
"193.9.101.104"
],
"password" : [
"*E474E7F197FAC1D7280FF181D07F1FA09566F5FC"
],
"databases" : [
"junk"
]
}
}
],
"command" : "list-provision-mysql-users"
}