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 :

https://yourserver:10000/virtual-server/remote.cgi?program=create-alias&domain=foo.com&from=sales&to=joe@foo.com

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.

====== 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 ======

<code php|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;
?>
</code>

<code perl|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";
</code>

<code perl|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;
</code>