====== Using VM2 ======

===== Introduction to the User Interface =====

Once VM2 is installed, you can login to it by opening a web browser and going to the URL http://mastersystem:10000/ , where //mastersystem// is the hostname or IP address of the machine on which it is installed. This should bring up a web page with a menu on the left frame, and a display of information about the master system on the right.

The VM2 interface is in many ways similar to Virtualmin - managed systems can be selected from a drop-down menu on the left, below which is a list of links for performing various operations on those systems. Below this are menu categories labelled **Create System**, **Add System** and **VM2 Settings**. These contain further links for creating new virtual systems, bringing existing virtual or real systems under VM2's control, and editing settings that apply to all managed machines.

At the bottom is the **List Managed Systems** link, which opens a list of all systems under VM2's control, showing details such as their hostname, current status and virtualization system type. By default, the only registered system will be the machine you are running VM2 on. 

===== System Status =====

Every system managed by VM2 has a status, which is determined from either an automatic check (done every 5 minutes), or a manual check triggered by the **Refresh Status** link. The status can be seen on the left menu directly under the hostname. Possible statuses are :

  * **Down** The virtual system has been shut down, or a physical system is not responding to pings.
  * **Parent host is down** For a virtual system, the machine that hosts it is down.
  * **No SSH** The virtual system appears to be up, but SSH connections fail or timeout.
  * **SSH login failed** The system and SSH are running, but the <tt>root</tt> login credentials known to VM2 are incorrect.
  * **No Webmin** The system is up and running, but Webmin is not installed.
  * **Webmin Down** The system is up and Webmin is installed, but it is not running.
  * **Webmin Login Failed** The system is up and Webmin is running, but the credentials for it known to VM2 are incorrect.
  * **Webmin but no Virtualmin** The system is up and Webmin is installed and running, but the Virtualmin module is missing.
  * **Webmin and Virtualmin** The system is up, and both Webmin and Virtualmin are installed and available.

The master system will most likely have the status **Webmin but no Virtualmin**, unless you are also using it to host domains with Virtualmin.

===== Adding Systems =====

If you have several running physical systems on your network and want to control them using VM2, they can be added to its list of managed systems as follows :

  - On the left menu, open the **Add System** category and click on **Add physical system**.
  - In the form that appears, enter the DNS-resolvable hostname or IP address into the **Internet hostname** field.
  - In the **System description** field, enter a short description of the system, such as //Primary Virtualmin webserver//.
  - If the system has a ''root'' password and ''root'' logins via SSH are allowed, in the **Root login mode** section select **Using password** and enter the password into the adjacent textbox.
  - If Webmin is installed on the system to add, in the **Webmin login mode** field you can typically select **Login as root with same password as Unix**. If the Webmin login differs from the one you use for SSH, you will need to select **Login as** instead and enter a valid username and password.
  - If Webmin runs in SSL mode (meaning that at https: URL is needed to connect), select the **Use SSL to connect to Webmin** checkbox.
  - Finally, click the **Add System** button. If the system can be contacted and VM2 can login using the credentials you provided, you will be returned to the list of all managed systems.

Once a system has been added, it can be used to host Virtualmin domains, or virtual systems using Xen or VServers if it has the needed software installed.

===== Managing Systems =====

To view the full details of a managed system, click on the **Edit System** link below its hostname on the left menu. This will bring up a page showing the software versions it runs, current status and login details. If it runs Virtualmin, hosted domains and more detailed system status will also be shown in collapsed sections. If it is a virtual system that VM2 can manage network interfaces on, a section listing interfaces will also be available.

For systems that are currently up, you can use the **Reboot System** and **Shutdown System** links on the left menu to reboot or turn them off, respectively. Similarly, a virtual system that is down can be started up using the **Startup System** link. If a system has been rebooted or changed manually since the last VM2 automatic check, you can use the **Refresh Status** link to have VM2 fetch the current status.

===== Connecting to a Managed System =====

If a managed system has Webmin installed and running, you can connect to it using the **Open Webmin** link on the left menu. This will open a new browser window which will be automatically logged into the system, with all HTTP requests tunnelled through the VM2 master. This is a little slower that connecting directly (by opening the URL for Webmin on that system in your browser), but is more convenient and avoids any connectivity issues that may block access to the system.

Managed systems that are up and can be contacted via SSH can have commands executed on them via the VM2 interface by clicking on the **Run Commands** link on the left menu. This will open a page for entering a shell command, which will display the output from that command when it is run. However, only non-interactive programs can be run - you cannot invoke something like ''vi'' or ''yum'' which expects user input.

===== Changing Passwords =====

To update the ''root'' password for SSH or Webmin on a managed system, you can use the **Change Password** link on the left menu. This will open a form for entering one or both new passwords, which when submitted 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.

===== Updating Multiple Systems =====

Once you have several systems registered, it becomes convenient to perform operations on more than one at once. This can be done as follows :

  - On the left menu, click on the List Managed Systems link.
  - Select the checkboxes next to one or more hostnames.
  - Click on the buttons at the bottom of the list, such as **Startup**, **Shutdown** or **Refresh Status**. For virtual systems, you can use the **Delete** button to completely destroy them, which will result in any Virtualmin domains they host or other data on their filesystems being lost.
  - If any systems have package updates available, you can install those updates on all systems in parallel with the **Update Packages** button.