Virtualmin comes with several programs that can be run from the Unix command line to perform actions that are usually done from the web interface. In fact, almost all actions that can be done in a browser can also be done from the command line, or from shell scripts. This allows virtual server, user and alias creation and management to be done in a more automated function, such as from programs or scripts of your own creation.

All of these commands can be found in the directory /usr/libexec/webmin/virtual-server . They must all be run as the root Unix user, as they need access to system configuration files to create users, set up web sites and so on. If you want to create servers, users and aliases programatically as a different user (such as from your own CGI scripts), see the documentation on the Virtualmin Remote API instead.

All of the programs that make changes to the system output messages indicating their success or failure. Their exit status can also be checked to determine success - an exit status of 0 indicates that everything went OK, while a non-zero status indicates some problem.

All programs can be called with the –help command-line parameter to have them output details of the required and allowed parameters. Most require one or more parameters, to specify such things as the domain name of the virtual server to create, or the name for a new user. All parameters need to have – before the option name, such as –domain foo.com .

Probably the most important programs are those for creating, listing, modifying and deleting virtual servers. Because these actions may involve several steps, all of these programs output messages as the proceed, showing the success or failure of each step. These programs and their options are documented below.

This program can be used to create a new top-level, child or alias virtual server. It is typically called with parameters something like :

create-domain.pl --domain foo.com --pass smeg --desc "The server for foo" --unix --dir --webmin --web --dns --mail --quota 102400 --uquota 102400

This would create a server called foo.com , with the Unix login, home directory, Webmin login, website, DNS domain and email features enabled, and a disk quota of 100 MB. If you run this program with the –help option, you can see all of the other command-line options that it supports. The most commonly used are those for enabling features for the new server, such as –mysql and –logrotate.

To create a virtual server with a private IP address, you can use the –ip option to specify it explicitly. If your Virtualmin is configured to automatically allocate IP addresses, use the –allocate-ip option instead, to have a free address chosen from the allocation ranges. If you want to use a virtual IP that is already active on the system, you must add the –ip-already command-line option.

To create a server that is owned by an existing user, use the –parent option, followed by the name of the virtual server to create under. In this case, the –pass , –unix , –webmin and –quota options are not needed, as a user for the new server already exists.

To create an alias of an existing virtual server, use the –alias option, followed by the domain name of the target server. For alias servers, the –pass , –unix , –webmin , –dir and –quota options are not needed.

You can specify limits on the number of aliases, sub-servers, mailboxes and databases for the new domain owner using the –max-aliases, –max-doms, –max-mailboxes and –max-dbs options. Alternately, you can choose to have all limits (including quotas) set based on the template using the –limits-from-template command line flag.

This program does not modify the system, but instead simply outputs a list of all existing virtual servers. By default, the list is a reader-friendly format, but the –multiline option can be used to display more details for each server, in a format suitable for parsing by other programs. The –domain option can be used to specify a single virtual server to list, in cases where you know exactly which server you are interested in.

To delete a server (and all of its sub-servers and alias domains) from the system, use this program. Its only required parameter is –domain , which must be followed by the domain name of the server to remove. The –only option can be used to not actually delete the server, but instead simply remove it from the control of Virtualmin.

Be careful with this program, as unlike the server deletion function in the Virtualmin web interface, it will NOT prompt for confirmation!

When a server is disabled, it will become temporarily unavailable without being completely deleted. This program can be used to disable one server, specified with the –domain option. The exact features that will be disabled for the server are set on the module configuration page.

This program reverses the disable process done by disable-domain.pl , or in the Virtualmin web interface. It will restore the server to the state it was in before being disabled.

This command can be used to modify various settings for an existing virtual server from the command line. The only mandatory parameter is –domain , which must be followed by the domain name of the server to update. The actual changes to make are specified by the other optional parameters, such as –pass to set a new password, –desc to change the server description, and –quota and –uquota to change the password.

To add a private IP address to a virtual server that currently does not have one, the –ip or –allocate-ip options can be used, as described in the section on create-domain.pl.

To change a server's domain name, the –newdomain option can be used. It must be followed by a new domain name, which of course cannot be used by any existing virtual server. When changing the domain name, you may also want to use the –user option to update the administration username for the server. Both of these options will effect sub-servers as well, where appropriate.

To enable features for one or more servers from the command line, use this program. The features to enable can be specified in the same way as the create-domain.pl program, such as –web , –dns and –virtualmin-svn . The servers to effect can either individually specified with the –domain option (which can occur multiple times), or with –all-domains to update all virtual server.

When updating multiple servers, this program may take some time to run due to the amount of work it needs to do. However, the progress of each server and step will be shown as it runs.

When a server is disabled, it will become temporarily unavailable without being completely deleted. This program can be used to disable one server, specified with the –domain option. The exact features that will be disabled for the server are set on the module configuration page.

To enable features for one or more servers from the command line, use this program. The features to enable can be specified in the same way as the create-domain.pl program, such as –web , –dns and –virtualmin-svn . The servers to effect can either individually specified with the –domain option (which can occur multiple times), or with –all-domains to update all virtual server.

When updating multiple servers, this program may take some time to run due to the amount of work it needs to do. However, the progress of each server and step will be shown as it runs.

disable-feature.pl - Turn off some features for a virtual server This program is very similar to enable-feature.pl, and takes the same command line parameters, but disables the specified features instead. Be careful when using it, as it will not prompt for confirmation before disabling features that may result in the loss of configuration files and other data.

migrate-domain.pl - Imports a virtual server from some other product Virtualmin has the capability to import servers from other hosting programs, such as cPanel. This program can perform an import from the command line, which will create a new server in Virtualmin with all the same settings and content as the original server.

The –source parameter must be followed by the name of the backup or export file to migrate from. The –type parameter must be followed by the short name of the product that originally created the backup, such as 'cpanel'. The –domain parameter must be used to specify the name of the server to import, as it cannot always be automatically determined from the backup file.

The mandatory –user option must be followed by the name of the original administration username, which will also be the name of the user for the new virtual server. The –pass parameter specifies the password to give to the new server, as this cannot usually be determined from the backup.

To migrate a server under the ownership of an existing Virtualmin user, use the –parent parameter to specify the name of the parent domain. The optional –webmin parameter will cause a Webmin login to be created for the migrated server, which is typically what you want unless using –parent.

If the original server had a private IP address, either the –ip or –allocate-ip parameter should be used to create an IP for the new virtual server. Failure to do this may cause the migration attempt to be rejected, or for features of the migrated server to not work properly (such as its SSL virtual website). If you want to use a virtual IP that is already active on the system, you must add the –ip-already command-line option.

This command can be used to move a sub-server from one parent domain to another, thus changing the administrator who is responsible for it. It can also be used to convert a parent server into a sub-server under some existing owner.

The command takes only two parameters : –domain followed by the domain name to move, and –parent followed by the domain name of the new parent server. Naturally the new parent must be different from the old one, and a server cannot be moved under itself.

This command should be used with care when moving a parent server, as information that is specific to it such as the password, quotas and bandwidth limit will be lost. Instead, the settings from the new parent will apply.

This command can be used to change the location than email tagged as spam or virus-laden is delivered to for one or more virtual servers. The servers to act on can be either specified with the –domain parameter, or all domains with spam filtering enabled can be selected with –all-domains.

The following parameters control what happens to messages identified as spam :

• –spam-delete Delete all spam mail.
• –spam-deliver Deliver to user's mailbox normally.
• –spam-normal Write to user's ~/mail/spam file in mbox format.
• –spam-maildir Write to user's ~/Maildir/.spam file in Maildir format.
• –spam-file Write to the file following this parameter, which must be relative to the user's home directory.
• –spam-email Forward to the email address following this parameter.
• –spam-dest Write to the absolute file following the parameter.

A similar set of options exist for virus filtering, but starting with –virus instead of –spam.

This command can also select if spamassassin or spamc is used to scan the select domains' email. This is done with the –use-spamc or –use-spamassassin parameters.

This script can update the PHP and web forwarding settings for one or more virtual servers. Like other scripts, the servers to change are selecting using the –domain or –all-domains parameters.

The –cgi and –mod_php parameters select if the domains execute PHP scripts using CGI (as the domain owner) or Apache's PHP module (as the apache user), respectively.

The –proxy parameter can be used to have the website proxy all requests to another URL, which must follow –proxy. To disable this, the –no-proxy parameter must be given.

The –framefwd parameter similarly can be used to forward requests to the virtual server to another URL, using a hidden frame rather than proxying. To turn it off, using the –no-framefwd option. To specify a title for the forwarding frame page, use –frametitle.

This program updates DNS-related options for one or more servers, selected using the –domain or –all-domains flags.

To enable SPF for a domain, using –spf option, and to turn it off use –no-spf. By default, the SPF record will be created using the settings from the DNS section of the domain's server template.

To add allowed hostname, MX domains or IP addresses, use the –spf-add-a, –spf-add-mx and –spf-add-ip4 options respectively. Each of which must be followed by a single host, domain or IP address.

Similarly, the –spf-remove-a, –spf-remove-mx and –spf-remove-ip4 options will remove the following host, domain or IP address from the allowed list for the specified domains.

To control how SPF treats senders not in the allowed hosts list, use one of the –spf-all-disallow, –spf-all-discourage, –spf-all-neutral, –spf-all-allow or –spf-all-default parameters.

The program can be used to generate a report on selected features for selected virtual servers, to ensure that they are setup correctly. Validation is useful for detecting things such as manually removed Apache virtual hosts or BIND domains, wrong permissions and missing configuration files.

To specify the servers to check, you can either supply the –all-domains parameter, or –domain followed by the domain name. Similar, you can select features to check with the –feature parameter followed by a feature name (like web or dns), or the –all-features option. Both –domain and –feature can be given multiple times.

The command simply outputs a list of available templates for use when creating new virtual servers. For each the ID number and description are diplayed.

Virtualmin has the ability to backup and restore virtual servers either manually or on a set schedule, using the web interface. However, you can also use the command line programs listed below to make backups. This can be used for doing your own migration to other systems or products, or manually setting up custom backup schedules for different servers.

This program is analogous to the Backup Virtual Servers page in the Virtualmin web interface. It will create either a single backup file or multiple separate files containing the domains specified on the command line, either locally or on a remote SCP or FTP server.

The –dest option sets the backup destination, and can be a simple path like /backup/virtualmin.tgz , an FTP URL like ftp://user:pass@server:/backup/virtualmin.tgz , or an SCP URL like ssh://user:pass@server:/backup/virtualmin.tgz . When backing up to a single file, the path specifies a file that will be created. When creating one backup per domain, it specifies a directory instead.

The –domain and –all-domains options can be used to control which virtual servers are included in the backup. The –domain parameter followed by a domain name can be given multiple times, to select more than one server.

Typically the –all-features option will be used to include all virtual server features in the backup, but you can instead use the –feature option one or more times to control exactly what gets included. In this case, it is wise to use at least –feature dir to include each server's home directory.

The –separate option tells the backup program to create a separate file for each virtual server. The –newformat also causes multiple files to be created, but using the format supported by Virtualmin versions 2.86 and above which puts all information into each domain's home directory, and thus avoids the need to create a large file in /tmp during the backup process.

Using the –ignore-errors option means than any errors encountered backing up one feature or server will be reported and ignored, rather than terminating the whole backup as happens by default.

To include core Virtualmin settings in the backup, the –all-virtualmin option can be specified as well. Alternately, you can select exactly which settings to include with the –virtualmin parameter. For example, –virtualmin config would only backup the module configuration.

To restore a Virtualmin backup from the command line, you will need to use this program. It takes very similar parameters to backup-domain.pl , with the exceptions that –dest is replace with –source , and the –separate and –ignore-errors options are not used. The extra option –reuid can be specified to force the re-allocation of Unix UIDs and GIDs for virtual servers that are created by the restore process, which is usually a good idea as the IDs in the backup file may already be in use.

If a virtual server that does not currently exist is selected to be restored, it will be created as part of the restore process. Be careful using this program, as it will not prompt for confirmation before restoring, which will over-write the contents of restored directories, databases and configuration files.

To restore core Virtualmin settings (if included in the backup), the –all-virtualmin option can be specified as well. Alternately, you can select exactly which settings to include with the –virtualmin parameter. For example, –virtualmin config would only restore the module configuration.

Each Virtualmin virtual server can have users associated with it, each of which can be a mailbox, an FTP login, or a database user. Users can be created any managed from the command line, using the programs described below.

This program adds a new user to an existing virtual server. It is typically called with parameters like :

create-user.pl --domain foo.com --user jimmy --pass smeg --quota 1024 --real "Jimmy Smith"

This command would add a user to the server foo.com named jimmy with password 'smeg' and a disk quota of 1MB. The actual POP3 and FTP username may end up as jimmy.foo, depending on whether or not domain suffix are always appended to usernames, and what suffix format is used.

The –ftp option can be used to give the new user an FTP login as well - by default, he will only be given an email account. The –noemail option turns off the default email account, which is useful for creating FTP or database-only users.

Extra email addresses for the new user can be specified with the –extra option, followed by an email address within the virtual server. This option can be given multiple times if you wish.

The new user can be granted access to MySQL databases associated with the virtual server with the –mysql option, which must be followed by a database name. This option can occur multiple times in order to grant access to more than one database. Unfortunately, there is no way to grant access to PostgreSQL databases.

To get a list of users associated with some virtual server, this program can be used. The only required parameter is –domain , which must be followed by the domain name of the server to list users for. By default, it will output a reader-friendly table of users, but you can use the –multiline option to show more detail in a format that is suitable for reading by other programs.

By default the server owner is not included in the list of users, but if you add the –include-owner command line option, he will be. Also by default the size of each user's mail file is now shown in the multiline mode output, as computing it can be disk-intensive. To display the mail file / directory size, use the –mail-size option.

This command deletes one mail, FTP or database user from a virtual server, along with him home directory. It takes only two parameters, both mandatory : –domain followed by the domain name, and –user followed by the full or short username. Be careful with this program, as it does not prompt for confirmation before deleting.

After a user has been created from the command line or web interface, you can use this program to modify or rename him. The virtual server and user to change must be specified with the –domain and –user parameters, which are followed by the server domain name and username respectively.

To change the user's password, use the –pass parameter followed by the new password. To modify his real name, use the –real option followed by the new name (which must typically be quoted, in case it contains a space). If you want to change the user's login name, use the –newuser option, followed by the new short username (without a suffix).

A user can be temporarily disabled with the –disable option, or re-enabled with the –enable option. This will not effect his files or password, but will prevent FTP, IMAP and other logins.

To set the user's disk quota, the –quota option must be used, followed by the disk quota in 1 kB blocks. An unlimited quota can be set with the parameters –quota UNLIMITED instead (although of course the user will still be limited by total server quotas).

A user can be granted or denied FTP access with the –enable-ftp and –disable-ftp options respectively. Similarly, his primary email address can be turned on or off with the –enable-emaill and –disable-emaill options.

Extra email addresses can be added and removed with the –add-email and –remove-email options. Both of these must be followed by an address to add or remove, and both can occur multiple times on the command line.

Virtual servers with email enabled can have mail aliases associated with them, to forward email either to users within the server, or to addresses at some other domain. Aliases can also be set up to deliver mail to files, or feed them to programs as input. The programs in this section allow you to manage mail aliases from the command line.

This relatively simple command can be used to add a new email alias to a virtual server. It takes three mandatory parameters : –domain followed by the domain name, –from followed by the name of the alias within that domain, and –to followed by a destination address. For example, to create an alias for sales@foo.com that delivers mail to the user joe, you could run :

create-alias.pl --domain foo.com --from sales --to joe@foo.com

The –to option can be given multiple times, to create more than one destination for the alias. To create an alias for all addresses in the domain that are not matched by another alias or mail user, use the option –from "*" .

Aliases can have short descriptions associated with them, to explain what the alias is for. To set one when creating, you can use the –desc option followed by a one-line description.

This program displays a list of mail aliases that exist in the virtual server specified by the –domain command line option. The only other allowed parameter is –multiline , which switches the output to a format showing more details and more easily parsed by other programs.

If an alias has an associated description and multiline mode is enabled, it will be displayed after the alias's from address, separated by a # character.

Some aliases managed by Virtualmin are not created by users directly, but are instead created as part of some other process, such as the addition of a mailing list. Such aliases are not displayed by default, as editing them can cause problems with the associated mailing list. To include these aliases in the list produced by list-aliases.pl, use the –plugins command line flag.

This program simply removes a single mail alias from a virtual server. It takes only two parameters, –domain to specify the server domain name, and –from to specify the part of the alias before the @. Be careful using it, as it does not prompt for confirmation before deleting.

No program exists for updating existing aliases, but the same thing can be achieved by using the delete-alias.pl and create-alias.pl commands to remove and re-create an alias with new settings.

If your Virtualmin install has been configured to allow additional custom fields to be stored for each virtual server, the programs listed in this section can also be used to manage those fields.

When this command is run with no parameters, it will display all custom fields set for all virtual servers. The –domain parameter can be used to limit the display to a single named server, while the –names parameter will switch the display to show field codes rather than their full descriptions.

This program updates the value of one or more fields for a single virtual server. The parameter –domain must be given, and must be followed by the domain name of the server to update. You must also supply the –set parameter at least once, which has to be followed by the code for the field to update and the new value.

All Virtualmin virtual servers with database features enabled can have zero or more MySQL and PostgreSQL databases associated with them. These can be created and deleted from the web interface, or using the following programs.

This command creates a new MySQL or PostgreSQL database, and associates it with an existing virtual server. You must supply the –domain parameter to specify the server, –name to set the database name, and –type followed by either mysql or postgres to choose the type. It would typically be run something like :

create-database.pl --domain foo.com --name foo_phpbb --type mysql

Some database types support additional creation-time options, specified using the –opt flag. At the time of writing, those available for MySQL are :

• –opt charset name - Sets the default character set (like latin2 or euc-jp) for the new database

This program simply displays a list of MySQL and PostgreSQL databases that are owned by one server. You must supply the –domain followed by the domain name of the server to list. By default the output is in a reader-friendly table, but the –multiline option can be used to switch to a format more suitable for reading by programs.

To remove a single database from a virtual server and delete all of its contents, you can use this command. It takes the exact same parameters as the create-database.pl program : –domain , –name and –type. Be careful using it, as the complete contents of the specified database will be removed without any prompting for confirmation.

All Virtualmin virtual servers can have additional administration accounts created, which are similar to the server administrator Webmin login, but possibly with limited capabilities. These extra admin accounts can be created and managed using the following programs.

This command creates a new administrator associated with an existing virtual server. You must supply the –domain parameter to specify the server and –name to set the admin login name. The –pass and –desc options should also be given, to specify the initial password and a description for the account respectively.

Basic permissions for the account can be added using the –create , –rename , –features and –modules parameters. These allow the admin to create new servers, rename servers, use Webmin modules for server features, and use other Webmin modules, respectively.

The extra admin's editing capabilities for virtual servers can be set using the –edit parameter, followed by a capability name (like users or aliases). This can be given multiple times, as in the command below :

create-admin.pl --domain foo.com --name fooadmin --pass smeg --desc "Extra administrator" --edit users --edit aliases

That command would create an extra administrator account who can only edit mail users and mail aliases in the virtual server foo.com and any sub-servers.

This program simply displays a list of extra administrators associated with one virtual server. You must supply the –domain followed by the domain name of the server to list. By default the output is in a reader-friendly table, but the –multiline option can be used to switch to a format more suitable for reading by programs.

This command removes one extra administrator from a virtual server. The required parameters are –domain followed by the domain name, and –name followed by the administrator account name.

This program can be used to change the details of an extra administrator. The required parameters are –domain followed by the domain name, and –name followed by the administrator account name, which specify the account to change.

You can then use the –pass parameter to set a new password, –desc to change the description, and –newname to change the login name. The admin can be allowed to denied the ability to create servers, rename domains, manage features and use other Webmin modules with the –can-create, –cannot-create, –can-rename, –cannot-rename, –can-features, –cannot-features, –can-modules and –cannot-modules options respectively.

Editing capabilities can be granted to the user with the –can-edit option followed by a capability name. Similarly, they can be taken away with the –cannot-edit option.

If your Virtualmin site uses resellers, they can also be managed using the command-line programs documented in this section. All of the reseller options that can be set through the web interface can also be controlled from the Unix shell prompt.

This command adds a single reseller account to your Virtualmin system. The required parameters are –name and –pass to specify the login name and password respectively, but you can also use other parameters to set limits on the reseller to control the number of servers and other resources he can use.

The following command would create a reseller called 'bob' who is allowed to create up to 5 servers and allocate 1 GB in disk quota space. He will also be granted access to a standard set of virtual server features :

create-reseller.pl –name bob –pass smeg –desc "Bob Smith" –max-doms 5 –max-quota 1000000 –allow dir –allow unix –allow webmin –allow web –allow dns –allow mysql

The –max-doms parameter sets the maximum number of servers that can be created by this reseller, and by the owners of any virtual servers that he manages. Similarly, the –max-dbs option sets a limit on the number of MySQL and PostgreSQL databases that can be created in servers that the reseller owns.

The –max-quota option sets the maximum disk quota that the reseller can allocate to virtual servers that he creates. The option –max-mailboxes sets a limit on the number of mail/FTP/database users that can be created in servers managed by the reseller.

The –allow option can be given multiple times, each instance of which must be followed by the short code for a feature to allow the reseller to use. Only allowed features can be selected when the reseller is creating a new virtual server.

When run with no parameters, this program simply displays a reader-friendly table of existing Virtualmin resellers. The only supported option is –multiline, which causes it to show more details about each reseller in a format suitable for reading by other programs.

This program deletes a single reseller account, specified by the –name parameter. It does not effect any of the virtual servers owned by the reseller, except to mark them as no longer owned by any reseller. It does not prompt for confirmation before deleting either.

This command can be used to change the details of a single reseller. Its only mandatory parameter is –name , which must be followed by the reseller's login name. The other parameters such as –pass , –desc and the –max options are the same as those for the create-reseller.pl program, documented above.

The –allow parameter can be given multiple times to grant access to additional features to the reseller. Similarly, the –disallow feature can be used to take away access to features. Each instance of –disallow must be followed by the short code for the feature to remove, such as 'web' or 'dns'.

Virtualmin allows scripts created by other developers to be easily installed into the virtual servers that it manages. These are typically programs like Wikis, Blogs and web-based mail readers, often written in PHP. Normally these are setup through the web interface, but they can be managed by the following command-line programs as well.

This command simply outputs a list of scripts that can potentially installed into Virtualmin servers. By default it displays a nicely formatted table, but if the –multiline option is given it will use a more machine-readable format which shows more information.

This program performs the actual upgrade or install of a script into a virtual server. The required parameters are –domain (followed by the domain name), –type (followed by the script's short name, like drupal or squirrelmail), and –version (followed by the version number). Don't use the script's longer description with the –type parameter - only the short name (as shown by list-available-scripts.pl –multiline) will work.

All scripts will also need the –path parameter, which must be followed by a URL path such as /drupal. This determines the directory where the script is installed. The directory can be overridden by the –force-dir option though, which must be followed by a full path. However, this is not recommended, and should only be used when you have a web server alias setup to map the path to the forced directory.

Those that use a database require the –db parameter, which must be followed by the database type and name, such as –db mysql foo. If this is missing and the script requires it, the install-script.pl command will fail with an error message. By default the database must already exist under the virtual server, but if the –newdb parameter is given it will be created as part of the script installation process.

If upgrading an existing script in this virtual server, you must supply the –upgrade parameter, followed by the install ID. This can be found from the list-scripts.pl program, documented below.

When the command is run it will display the progress of the installation process as the needed files are downloaded, validated and installed.

This command has only one required parameter, –domain , which must be followed by a valid domain name. It then displays a table of all scripts currently installed, including their install IDs and version numbers. The only other parameter is –multiline , which switches to a more computer friendly and detailed output format.

This program completely removes a third-party script from a server. It takes the usual –domain parameter to identifiy the server, and either –id followed by the install ID, or –type followed by the script's short name. The latter option is more convenient, but only works if there is only one instance of the script in the virtual server.

Be careful using this program, as it removes all data files, web pages and database tables for the script, without asking for confirmation.