Cloudmin Remote HTTP API
Even though a command-line API exists for managing Cloudmin objects such as systems, domains and interfaces, this may not be appropriate or usable in all circumstances. Because the commands need to be run as root, they cannot be called from PHP or CGI scripts invoked by a web server, which typically run as a less-privileged Apache user. Also, they must be run on the server running VM2, which makes them difficult to call from another system.
For this reason, an alternate method exists for running these programs via HTTP requests. A special URL in the Cloudmin web interface exists to be called by other programs, and to then pass its parameters on to one of the command-line scripts. This URL can be requested from any system, and by processes running as any Unix user.
Before reading this documentation, you should be familiar with the Cloudmin Command Line API documentation, even if you never use those commands directly.
The Remote API
All remote calls must be made through the CGI /server-manager/remote.cgi . The full URL for this will be https://yourserver:10000/server-manager/remote.cgi , where 'yourserver' is the full hostname or IP address of the system running the VM2 master.
This URL must be provided with at least one parameter named 'program', whose value must be the name of the command-line program to invoke, without the .pl extension. So a possible URL to request would be :
https://yourserver:10000/server-manager/remote.cgi?program=list-systems
Because most command-line programs require additional parameters, these must be included in the URL. Every CGI parameter is converted to a command-line parameter, with the value of the parameter appended if given. For example, to create a mail alias, you could invoke the URL :
https://yourserver:10000/server-manager/remote.cgi?program=reboot-system&host=xencentos.home
To specify a parameter that does not have anything after it, just add a CGI parameter with no value. For example, to list systems in detailed form, you could call :
https://yourserver:10000/virtual-server/remote.cgi?program=list-systems&multiline=
Both GET and POST format HTTP requests can be used. If your VM2 master server is not running in SSL mode, use http:// instead of https:// in the URL.
Reading Output
The page returned by the remote.cgi URL will always be plain text, and will contain the output produced by the command-line program. One additional line will be appended though - the words 'Exit status:' followed by the numeric Unix exit status of the command. A status of 0 means that the program was successful, while a non-zero status indicates some error. The cause of the error can be determined from the command's output.
JSON and XML Output
If you would prefer JSON format output, add the json=1 parameter to the remote API call. Alternately, you can select XML format with the xml=1 parameter. Finally, Perl format can be selected with the perl=1 parameter.
Authentication
Because the remote API is part of the Cloudmin web interface, it is password-protected using the same authentication system as you would normally use to login via a web browser. Any Webmin user with access to the module can also access the API.
When calling the remote API from your own programs, the HTTP request must have the necessary HTTP authentication headers. All HTTP libraries and programs have options to set the username and password - for example, the wget command uses --http-user and --http-passwd , so you could fetch a list of domains from a remote VM2 server with a command like :
wget --http-user=root --http-passwd=smeg 'https://yourserver:10000/server-manager/remote.cgi?program=list-systems'