Like Virtualmin, everything that you can do via VM2’s web interface can also be done from the command line. In the directory server-manager under the Webmin root (usally /usr/libexec/webmin or /usr/share/webmin) are a set of Perl scripts that can be run as root either manually or from your own scripts, or perform operations such as rebooting systems, creating new instances and adding Virtualmin domains.

All of these scripts take command-line arguments that start with ‘–‘, and may be followed by a parameter. For example, to display the details of a single managed system, you might run :

cd /usr/libexec/webmin/server-manager
./list-systems.pl --host box1.xen.yourcompany.com --multiline

All of the scripts produce output showing either the progress of the actions they are taking, or a list of requested results. Scripts that perform some action (like creating a virtual system) exit with a non-zero status on failure, or zero on success. Scripts that display information all have an optional –multiline parameter to display their output in a complete and easily-parsable format. Without it, output is shown in a table that is easier for a human to read.

All of the commands accept the –help parameter, which will cause them to output a list of all accepted command-line parameters. Optional parameters are shown surrounded by [ ]. This same information will also be displayed if a command is called with an unknown or missing parameter, sometimes accompanied by a more detailed error message.

These commands can be used to find, update, reboot and shutdown virtual systems. Most of them take the following parameters to control which system or systems to operate on :

• –host hostname
  Can be given multiple times to specify systems by name.
• –group groupname
  Specifies systems that are members of the named group.
• –type code
  Matches systems of some virtualization type, which can be one of xen , vservers , zones or real
• –os code
  Matches systems known to be running some OS, specified by a code like centos , solaris , redhat or ubuntu.
• –all-hosts
  Always matches all registered systems.

When run with no parameters, this command outputs a table of all virtual systems known to VM2. You can limit the display to a subset of systems using the standard options above, or have it output all available information with the –multiline parameter.

./list-systems.pl --type xen
Hostname                       Type            Description
------------------------------ --------------- ------------------------------
xencentos.home                 Xen             CentOS 5 on Xen
xencentos4.home                Xen             Test system with CentOS 4
xengentoo.home                 Xen             Gentoo on Xen
xenrails.home                  Xen             Test server for Rails on Xen
xentemplatecentos.home         Xen             Xen Virtualmin template for Ce
xentemplatecentos4.home        Xen             Xen template for CentOS 4.4
xentemplatedebian.home         Xen             Xen Virtualmin template for De
xentemplatefc6.home            Xen             Xen Virtualmin template for Fe
xentemplateubuntu.home         Xen             Ubuntu on Xen

Forces VM2 to re-query the actual status of the specified systems. This is done in parallel so that many can be updated at once, and the status from each is displayed once it is retrieved. By default, Virtualmin status information like the amount of free RAM and available package updates is only fetched from the remote system’s cache, which is typically updated once every 5 minutes. To force a full status update, use the –regenerate command-line option - this will make the update take longer though.

./refresh-systems.pl --host xenrails.home
Refreshing status of 1 systems ..
xenrails.home: virt (Webmin and Virtualmin)

Triggers an immediate reboot of the specified systems. For virtual machines, VM2 will wait until they come back up before exiting, while for real systems it just runs the reboot command, which merely starts the reboot process in the background.

./reboot-system.pl --host xencentos.home
Rebooting Xen system xencentos.home ..
.. rebooted successfully

Shuts down the specified systems, as long as their virtualization type supports it. For virtual machines, VM2 will wait until they are completely shut down before this command exists, while for real systems it just runs the shutdown command, which merely starts the power-off process in the background.

./shutdown-system.pl --host xencentos.home
Shutting down Xen system xencentos.home ..
.. shutdown successfull

For virtual systems running under Xen, VServers or Zones, VM2 can start up existing instances using this command. The command will only exit when all the specified systems have been booted.

bash# ./startup-system.pl --host xencentos.home
Starting up Xen system xencentos.home ..
.. startup successfull

This command installs all available package updates on specified systems. This is only suppported on systems running Virtualmin, which has a module for finding new versions of packages that relate to virtual hosting, such as Apache, BIND, MySQL and of course the Virtualmin modules themselves. Updates are done in parallel across all systems, and the packages installed on each are displayed as they complete.

[root@fudu server-manager]# ./update-systems.pl --host xennoupdate.home
Updating packages on 1 systems ..
xennoupdate.home: spamassassin mod_perl

This command can be used to change the root password for SSH or Webmin on a managed system. The Unix password can be set with the –ssh-pass parameter, while the Webmin password can be changed with –webmin-pass. To configure Webmin to check the Unix password when root logs, use the –webmin-same parameter.

When the command is run, it will update /etc/shadow and /etc/webmin/miniserv.users on the selected machine to make the changes. VM2’s authentication information for the system will also be updated to match.

If you have created a virtual system for a customer, changing the root password when you are ready to hand it over is a good idea. Be aware that for Xen systems, if the password is changed on the system directly (perhaps using the passwd command), VM2 will be no longer able to login via SSH to change it, or even to check the system’s status.

Creation of virtual machines is one of the major features of VM2, and this too can be done from the command line.

This command takes different parameters depending on the type of virtual system being created, but the following are always required :

• –host hostname
  A short hostname for the system to create, which will also be used as the Xen or VServers instance name.
• –desc description
  A human-readable name for the system, which you will typically have to quote.
• –type code
  The virtualization type code, like xen , zones or vservers
• –ssh-pass password
  The initial root password for the new system.

For a virtual system, you will need to specify the host system to create it on, using the –xen-host , –vservers-host or –zones-host parameter. If the system is to be created from an image, you will need to select it with the –image parameter, followed by an image ID. To see the fill list of available and required options for a particular system type, run create-system.pl with the –type and –help flags.

If you are creating a system from an image that includes Virtualmin Pro, you will need to specify a license using either the –allocate-serial parameter, or –serial and –key. The former will select an available license from the pool of those registered with VM2, while the latter let you specify a serial number and key explicity. The Virtualmin Licenses page covers license management in more detail.

bash# ./create-system.pl --host xennoupdate --type xen --desc "Test without updates" --ssh-pass smeg  --no-update --xen-host sentosa.home --xen-memory 512 --image xen-centos5.0-virtualmin --allocate-serial
Copying system image files ..
 .. done
Starting creation of Xen system ..
.. creation started
Waiting for creation to complete ..
.. creation complete
Mounting new instance's filesystem ..
.. mounted on /mnt/xen-xennoupdate
Copying modules for kernel 2.6.18-8.1.4.el5xen to Xen filesystem ..
.. done
Setting root password ..
.. done
Updating configuration files with hostname and IP address ..
.. done
Updating network configuration files ..
.. done
Updating Virtualmin licence files ..
.. done
Allowing SSH logins by root ..
.. already allowed
Un-mounting instance's filesystem ..
.. done
Adding DNS entry xennoupdate.home. for IP address 193.9.101.245 ..
.. done
Starting up new Xen instance ..
.. done
Setting Webmin password ..
.. done
Waiting for Webmin to start ..
.. started OK
Refreshing status ..
.. done
Checking Virtualmin configuration ..
.. done
Enabling at hosting system boot ..
.. done
Creation of Xen system xennoupdate.home is complete

Virtual systems can also be deleted from the command line. This should be done with extreme care, as you will not get any confirmation before deletion happens, and all data on the system will be lost forever. The system to destroy is specified with the –host parameter.

./delete-system.pl --host xennoupdate.home
Deleting Xen system xennoupdate.home ..
.. deleted successfully

This command can change the details of an existing system, such as its hostname, description, OS or the passwords used by VM2 to login via SSH and Webmin. The system to change is specified using the –host parameter, which of course must be followed by a hostname. All other parameters are optional, and the most commonly used ones are :

• –desc “new description”
  Sets a new human-readable description for this system.
• –newhost hostname
  Changes the hostname used by VM2. This must resolve to the same IP address as the old name.
• –os code
  Changes the operating system code, to something like debian or centos.
• –ssh-pass password
  Changes the password VM2 will use to login, *not* the system’s actual root password.
• –boot or –no-boot
  Either enables the system at host boot time, or disables it.

./modify-system.pl --host xencentos.home --desc "CentOS 5 on Xen"
xencentos.home modified successfully

VM2 can manage Virtualmin domains across all managed systems via both the web interface and from the command line. This can be particularly useful if you have multiple hosting systems, and need a single location from which domains can be setup, perhaps for use by a billing system.

This command creates a Virtualmin top-level domain on a specified managed system. You must specify the –host parameter, followed by the name of a host to create on (which of course must have Virtualmin installed). Other required parameters are –domain and –pass, followed by the domain name and password respectively. You also need to choose features, either with the –default-features option, or multiple uses of –feature followed by a feature code like web or dir.

The command may take a few seconds to run, and will output the messages from the Virtualmin create-domain.pl command run on the remote system. Even though it is effectively invoked remotely, you cannot use all of the same command-line flags that it supports.

./create-domain.pl --host xencentos.home --domain wibble.com --desc "Example domain" --pass foo --feature dir --feature unix --feature web --feature webmin
Creating Virtualmin domain wibble.com on xencentos.home ..
Beginning server creation ..

Creating home directory ..
.. done
Creating administration group wibble ..
.. done
Creating administration user wibble ..
.. done
Adding new virtual website ..
.. done
Adding Apache user apache to server's group ..
.. done
Creating Webmin user ..
.. done
Applying web server configuration ..
.. done
Re-loading Webmin ..
.. done
Saving server details ..
.. done
All done!

.. creation complete!

This command deletes a domain (specified with the –domain parameter) from which every VM2-managed system hosts it. This can be normally worked out automatically, but if the same domain exists on more than one machine, you will need to add –host followed by the correct hostname. Be careful using it, as it will not prompt for any confirmation before deletion.

When the command is run, it will display all of the output from the delete-domain.pl command on the remote system. More than one domain can be deleted by specifying the –domain parameter multiple times.

./delete-domains.pl --domain wibble.com
Deleting Virtualmin domain wibble.com from xencentos.home ..
Deleting virtual server wibble.com ..

Deleting mail aliases ..
.. done
Deleting Webmin login ..
.. done
Deleting virtual website ..
.. done
Deleting administration user ..
.. done
Deleting administration group ..
.. done
Deleting home directory ..
.. done
Deleting server details for wibble.com ..
.. done
Re-loading Webmin ..
.. done
Applying web server configuration ..
.. done

All done!.. deleted successfully

Refreshing status of changed systems ..
.. done

This command allows you to transfer one or more Virtualmin domains from their current host systems to another system managed by VM2. Like the web-based domain move feature, it operates by backing them up on the source and restoring on the destination - so it is recommended that you transfer only between similar systems where possible.

The domains to move are selected by the –domain parameter. If a domain exists on more than one host, you will also need to specify –host followed by the correct source hostname. The final system is selected by the –dest parameter.

To have VM2 delete the domains from the source, use the –delete parameter (this is recommended). Or to just disable them when moving, use –disable.

./move-domain.pl --domain wibble.com --dest xenrails.home --delete
Creating backup of wibble.com on xencentos.home ..
.. created backup of 32.53 kB.

Downloading backup of wibble.com in file wibble.com.tar.gz ..
.. download of 32.53 kB complete.

Uploading backup of wibble.com in file wibble.com.tar.gz to xenrails.home ..
.. upload of 32.53 kB complete.

Deleting wibble.com on xencentos.home ..
.. deletion complete.

Restoring backup of wibble.com on xenrails.home ..
.. restore of wibble.com complete. Domain move was successfull!

Refreshing status of 2 systems ..
.. done

Once a domain has been moved, you will almost certainly need to make DNS changes to reflect the new website or nameserver IP address.

VM2 system images are used to create new virtual systems, and can themselves be created from systems that you have prepared.

This command lists all images that are available for creating systems on the VM2 master. By default it will show all of them in a table, but you can use the –multiline parameter to display more details in a machine-readable format, or –type to limit the display to images for some virtualization type like xen or vservers .

[root@fudu server-manager]# ./list-images.pl --type xen
ID                             Description
------------------------------ ------------------------------------------------
xen-centos4.4-base             CentOS 4.4 Xen instance with base OS
xen-centos4.4-virtualmin       CentOS 4.4 Xen instance with Virtualmin Pro
xen-centos5.0-base             CentOS 5 Xen instance with base OS
xen-centos5.0-virtualmin       CentOS 5 Xen instance with Virtualmin Pro
xen-debian3.1-base             Debian 3.1 Xen instance with base OS
xen-fc6-base                   Fedora Core 6 Xen instance with base OS
xen-fc6-virtualmin             Fedora Core 6 Xen instance with Virtualmin Pro
xen-ubuntu6.10-base            Ubuntu 6.10 Xen instance with base OS
xen-ubuntu6.10-virtualmin      Ubuntu 6.10 Xen instance with Virtualmin Pro

This command simply removes one of the existing images on your VM2 master. The image ID is specified with the –id parameter.

./delete-image.pl --id xen-centos-test1
Image xen-centos-test1 successfully deleted.

This command performs the complex process of converting an existing virtual system into a VM2 machine image. It has three required parameters : –host followed by the hostname of the system to image, –desc followed by a description of the image, and –id followed by a new unique image ID. The ID is typically formatted like type-os-software , such as xen-centos6-virtualmin.

If the ID refers to an image that already exists and you want to replace it, add the –overwrite paramter to the command line. You should also use –version followed by a version number, to make it easier to keep track of different instances of the same image.

Creation takes several minutes, but the command will display each step in the process as it proceeds, and inform you of its final success or failure.

./create-image.pl --host xenrails.home --desc "Image with rails" --id xen-centos5.0-rails
Creating temporary directory for image files ..
.. done
Shutting down system ..
.. done
Mounting Xen instance filesystem ..
.. mounted on /mnt/xen-xenrails
Removing Virtualmin licence ..
.. done
Resetting root password ..
.. done
Removing authorized SSH keys ..
.. done
Un-mounting Xen instance filesystem ..
.. done
Compressing filesystem image ..
.. done
Fetching image files from host ..
.. fetched all files
Deleting compressed filesystem image ..
.. done
Mounting Xen instance filesystem ..
.. mounted on /mnt/xen-xenrails
Undoing licence and password changes ..
.. done
Un-mounting Xen instance filesystem ..
.. done
Starting up system ..
.. done
Refreshing system status ..
.. done

The commands in this section are specific to EC2 virtual system creation.

This command displays a table of all EC2 accounts registered with VM2. To see more details on each account, use the –multiline parameter. The most useful is the account number, which is needed when creating a virtual EC2 system using the create-system.pl command.

./list-ec2-accounts.pl
Account    Description                                     Access Key
---------- ----------------------------------------------- --------------------
5555555555 Jamie's EC2 account                             HJUGHJHGHHIUHIUHNIUH

This program displays all EC2 images (AMIs) available to some or all of your EC2 accounts. To restrict the account it shows them for, use the –account parameter. To show more details about each image, add –multiline to the command line.

./list-ec2-images.pl
Image ID   Location                                                Account
---------- ------------------------------------------------------- ----------
ami-20b653 ec2-public-images/fedora-core4-base.manifest.xml        5555555555
ami-22b653 ec2-public-images/fedora-core4-mysql.manifest.xml       5555555555
ami-23b653 ec2-public-images/fedora-core4-apache.manifest.xml      5555555555
ami-25b653 ec2-public-images/fedora-core4-apache-mysql.manifest.xm 5555555555
ami-268f6a rightscale-images/CentOS5V1.img.manifest.xml            5555555555
ami-26b653 ec2-public-images/developer-image.manifest.xml          5555555555
ami-2bb653 ec2-public-images/getting-started.manifest.xml          5555555555
ami-2c8f6a rightscale-images/FC6V2.img.manifest.xml                5555555555
ami-608b6e virtualmin-gpl/image.manifest.xml                       5555555555
ami-699673 virtualmin-pro/image.manifest.xml                       5555555555
ami-898560 feisty-image/feisty.manifest.xml                        5555555555
ami-bd9d78 ec2-public-images/demo-paid-AMI.manifest.xml            5555555555

This command can be used to convert an existing system running under EC2 into an Amazon Machine Image (AMI), which can then in turn be used to create new EC2 instances. Unlike images made with the create-image.pl command, they are not stored on your VM2 master system - instead, EC2 images are kept in your Amazon S3 account.

The command takes four mandatory parameters - –host followed by the name of the host to image, –bucket followed by an S3 bucket (directory) named to create the image in, –size followed by the image’s root filesystem size in MB, and –account followed by one of your EC2 account numbers. If you want the new image to be publicly available for anyone to launch, you can add the –public parameter to the command line.

Because an image can be several GB in size, creation may take 10 to 20 minutes, depending on the selected size and load on the source system.

bash# ./create-ec2-image.pl --host ec2-72-44-56-7.z-1.compute-1.amazonaws.com --bucket test-ami-three --size 2000 --account 555555555555
Creating EC2 image from ec2-72-44-56-7.z-1.compute-1.amazonaws.com ..
Removing Virtualmin licence files ..
.. done
Resetting root password ..
.. done
Creating image from filesystem ..
.. done
Uploading filesystem image to S3 ..
.. upload done
Registering new image ..
.. image ID is ami-5555555
Undoing licence and password changes ..
.. done
.. image creation was successful! It can now be used to create new Virtualmin systems using VM2.

Virtual systems running under Solaris Zones and Linux VServers cannot create their own network interfaces, unlike real systems or those running under Xen. However, VM2 can manage interfaces for systems of these types, both via the web interface and using the command-line programs described here.

This command outputs a list of virtual interfaces on some managed system, selected using the –host command-line parameter. By default they are shown in a table, but you can select a more machine-readable format with the optional –multiline parameter.

./list-interfaces.pl  --host vvirtualmin.home
Interface  Address         Netmask         Use
---------- --------------- --------------- -----------------------------------
eth0:0     193.9.101.224   255.255.255.0   Virtualmin shared address default
eth0:1     193.9.101.225   255.255.255.0   Virtualmin domain vservervirt.com
eth0:2     193.9.101.227   255.255.255.0   Virtualmin domain autoip.com

This program adds a virtual interface to some VM2-managed system. You must specify the system with the –host parameter, and the base interface with –name. The IP address can be either explitly set with –address, or VM2 can allocate a free IP from the range defined for the host system with –allocate.

Either way, the full inteface name and IP address will be displayed if the command completes successfully.

./create-interface.pl --host vvirtualmin.home --name eth0 --address 193.9.101.250
Created interface eth0:3 with address 193.9.101.250

This removes a virtual interface from some system. It takes two parameters : –host followed by the name of the system, and –address followed by the IP of the interface to remove. Be careful doing this though, as it may cut off access to a Virtualmin domain, or prevent SSH logins to the system altogether.

./delete-interface.pl --host vvirtualmin.home --address 193.9.101.250
Deleted interface eth0:3

VM2 has the ability to add and manage Virtualmin licenses, which are needed when creating new systems with Virtualmin installed. This category covers the license management commands.

This program displays a list of all licenses registered with VM2, in a table format. To show more details about each license, use the –multiline command-line argument.

./list-licences.pl
Serial     Key                  Domains    Systems    Used
---------- -------------------- ---------- ---------- ----------
5555555    3rfafsfdsfsfds       Unlimited  Unlimited  6
14433      HGHJJ7JJJ            250        1          0

This command adds a new license to the pool of those managed by VM2. It must have been already purchased from the Virtualmin website, and you must have the serial number and key. These are specified to the command using the –serial and –key parameters respectively, and will be validated before it is added to the license pool.

./add-licence.pl --serial 213323 --key fdsdsfdffdsff
The Virtualmin license with serial 213323 and key fdsdsfdffdsff has been added.

If you no longer want a license to be used when creating new Virtualmin systems, this command can remove it from the VM2 license pool. It will not effect any existing systems using the license though.

./delete-licence.pl --serial 55555
The Virtualmin license with serial 55555 has been removed.

VM2 also comes with several commands that don’t really fall into any category.

This program displays a list of all SSH keys registered with VM2, in a table format. To show more details, use the –multiline command-line argument. It is most useful when creating a system that will use SSH authentication to login as root, such as an EC2 instance. In this case, the key ID must be passed to create-system.pl as a command-line argument.

./list-ssh-keys.pl
ID         Description
---------- -----------------------------------------------------------------
1176512463 Jamie's SSH 1 key. uploaded copy
1176512615 Jamie's SSH 2  key, in home directory
1176513526 Amazon EC2 SSH key
1176848976 EC2 generated key

This is the equivalent of the command shell in the VM2 web interface, but arguably more powerful. It can be used to run a command on one or several hosts managed by VM2, and display the output from all of them. Systems are selected by the standard optons (–host , –type and so on), and the command to run follows the other parameters.

./run-command.pl --host xencentos.home "df -h"
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda1             2.0G  1.2G  777M  60% /
none                  257M     0  257M   0% /dev/shm

When multiple systems are specified, the output from each is preceeded by the hostname.

./run-command.pl --host xencentos.home --host suntec.home uname
xencentos.home: Linux
suntec.home: SunOS

If you have a system without Virtualmin installed, this command can be used to perform a manual install on it using the Virtualmin standard install script. In general we do not recommend this - it is much simpler and more reliable to create virtual systems from an image that already includes the full Virtualmin software stack.

This command can install on multiple systems at once, specified using –host , –type and other standard system selection parameters. This install will be done in parallel, but can still take some time (10-20 minutes) as it will download required packages from your Linux distribution’s repository and the Virtualmin website.

All Virtualmin Pro installs require a license, which can be specified to this command using either the –allocate-serial parameter, or –serial and –key. The former selects a free serial for each system you are installing on from the license pool, while the latter lets you manually select a serial number and key to be used on all systems. The Virtualmin Licenses page covers license management in more detail.

For each system that the install completes successfully on, a line starting with the hostname followed OK will be output.

./install-virtualmin.pl --host xencentos.home
xencentos.home: Started
xencentos.home: OK

This command can be used to install Webmin on a real or virtual system that does not have it yet. On operating systems that support RPM packages (Fedora, CentOS and Redhat) it will download the latest version in .rpm format from www.webmin.com , while on Debian and Ubuntu systems it will use the latest .deb. On other platforms, the .tar.gz package of Webmin is used instead.

Installation is fully automatic, and where possible the initial Webmin login is set to match the system’s root password. If necessary, the wget and perl programs are automatically installed on the target system, as they are needed to fetch and run Webmin.

This command can install on multiple systems at once, specified using –host , –type and other standard system selection parameters. This install will be done in parallel, and for each system it completes successfully on the hostname followed by OK, the package type and download URL will be displayed.

./install-webmin.pl --host xenempty.home
Installing Webmin on 1 systems ..
xenempty.home: OK rpm http://www.webmin.com/download/rpm/webmin-current.rpm

This script can be used to fetch a single file from a VM2 managed system and either save it on the master, or print it to standard output. The system is selected with the –host parameter, and the source file with –source. To have the file saved on the master, add the –dest parameter followed by a filename. To have its contents output by the script, use the –stdout parameter instead.

./download-file.pl --host xencentos.home --source /etc/hosts --stdout
127.0.0.1 localhost
193.9.101.242 xencentos.home xencentos

This command can send a file from the VM2 master system to one or more managed hosts. The file is specified with the –source parameter, and the destination file or directory with –dest. Alternately, you can have it write input to the command to the destination with the –stdin parameter.

The destination systems are specified with the –host, –group and other standard system-selection parameters. When copying the file is transferred to all systems in parallel, and the success or failure of each is shown as the transfer completes.

./upload-file.pl --host xencentos.home --host xenrails.home --host fedora.home --source /etc/hosts --dest /tmp/hosts
Uploading file to 3 systems ..
xencentos.home: OK
xenrails.home: OK
fedora.home: ERROR: ssh: connect to host fedora.home port 22: No route to host lost connection