Explains how to manage Virtualmin servers, users, databases and other features remotely from other programs.
Introduction
Even though a command-line API exists for managing Virtualmin objects such as servers, users and databases, 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 Virtualmin, 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 Virtualmin 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 Virtualmin Command Line Programs documentation, even if you never use those commands directly.
The Remote API
All remote calls must be made through the CGI /virtual-server/remote.cgi . The full URL for this will be https://yourserver:10000/virtual-server/remote.cgi , where 'yourserver' is the full hostname or IP address of the system running Virtualmin.
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/virtual-server/remote.cgi?program=list-domains
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 :
To specify a parameter that does not have anything after it, just add a CGI parameter with no value. For example, to list databases in detailed form, you could call :
https://yourserver:10000/virtual-server/remote.cgi?program=list-databases&domain=foo.com&multiline=
Both GET and POST format HTTP requests can be used. If your Virtualmin 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. Make sure you also add the multiline= parameter to any list-* API calls, or else conversion to JSON or XML will not happen.
Authentication
Because the remote API is part of the Virtualmin web interface, it is password-protected using the same authentication system as you would normally use to login via a web browser. Only the master administrator can access the remote API though, as it can be used to perform almost any action in Virtualmin, and thus would be unsafe for server owners or resellers to use.
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 Virtualmin server with a command like :
wget --http-user=root --http-passwd=smeg 'https://yourserver:10000/virtual-server/remote.cgi?program=list-domains'
Example Usage
PHP Example
<?php $result = shell_exec("wget -O - --quiet --http-user=root --http-passwd=pass --no-check-certificate 'https://localhost:10000/virtual-server/remote.cgi?program=list-domains'"); echo $result; ?>
Perl Example
#!/usr/bin/perl -w $result = `wget -O - --quiet --http-user=root --http-passwd=pass --no-check-certificate 'https://localhost:10000/virtual-server/remote.cgi?program=list-domains'`; print "$result\n";
Perl LWP Example
#!/usr/bin/perl -w
use strict;
use LWP;
my $browser = LWP::UserAgent->new( );
$browser->credentials("localhost:10000", "Webmin Server", "root" => "pass");
my $result = $browser->get( "https://localhost:10000/virtual-server/remote.cgi?program=list-domains" );
print $result->content;