VMM:Getting Started with 1.0

From FirstContact

Contents 1 Introduction 1.1 Archived Versions 2 Requirements 3 Downloading 4 Installing 4.1 Windows 4.2 Linux / OS X 5 Configuring 5.1 The VMM Properties File 5.1.1 Adding Your First Hypervisor 5.1.2 Adding Additional Hypervisors 5.2 Licensing 5.2.1 Installing a License 5.3 Logging 5.4 Additional Configuration 6 Starting 6.1 Windows 6.2 Linux / OS X 7 Using

Introduction

VMM is as easy to manage as it is to use, there are just a few simple steps to getting it up and running, and then only a few more to customize it for your environment.

Archived Versions

Archived versions of this guide can be found at:

• VMM:Getting Started with Beta 2.2

Requirements

VMM requires Java 5.

Downloading

• Get the latest copy of Hyper9 VMM from http://sourceforge.net/projects/hyper9-vmm/files/.

Installing

This section details how to install VMM. Because VMM is a Tomcat web application, the Tomcat documentation may also provide additional details.

Windows

1. Decompress the contents of the archive into a permanent location. C:\vmm is a good choice.
2. Open a command prompt and navigate to the new vmm directory.
3. Type bin\service install VMM to install VMM as a Windows service.

That's all there is to it! VMM is now installed in your services list as Apache Tomcat VMM. Now, before you start the new service, skip ahead to the section entitled Configuration to learn how to configure VMM for your environment.

Linux / OS X

1. Decompress the contents of the archive into a permanent location. /opt/vmm is a good choice.
2. On Linux you can set the VMM daemon to start automatically when the server boots by copying the included init.d control file, bin/init.d-vmm to your /etc/init.d directory and renaming it vmm (you need to set it as executable -- chmod +x /etc/init.d/vmm -- as well). Then simply use your distribution's built-in tool to configure the service. For Debian derivatives such as Ubuntu you would type update-rc.d vmm defaults.

And you're done. VMM is now installed. The next section explains how to configure VMM for your environment.

Configuring

This section details how to configure VMM.

Note: If you choose to install VMM on a Windows system, you will need a different text editor than Notepad to edit the configuration files. This is because the configuration files use the standard newline carriage return, and Windows uses a Microsoft version of it. The result is a file without apparent line breaks (they are in fact there). You can use Microsoft Write, jEdit, TextMate, or any free text editor. Notepad just doesn't do the job this time.

In future versions of VMM, a Windows installer will reformat the configuration files upon installation to use Microsoft-style line breaks to avoid this issue.

The VMM Properties File

The VMM properties file, vmm.properties file is located at conf/vmm.properties (on *Nix systems a global version of this file can be placed at /etc/vmm/vmm.properties and will override any local vmm.properties files). The properties file is a beast, but all you need know to get started is how to add your hypervisors to it.

Adding Your First Hypervisor

Open the vmm.properties file and find the lines:

# The server aliases. This property path's syntax is final and should not be 
# modified, although its value may be.
com.hyper9.vmm.serverAliases=myserver

# Define global properties about the configured servers. 

# The serverTypeAlias property path for a server may not include the 
# SERVER_TYPE_ALIAS field as it has not yet been discovered.
com.hyper9.vmm.myserver.serverTypeAlias=vmware
com.hyper9.vmm.myserver.displayName=My Server

The first property, com.hyper9.vmm.serverAliases, is a comma-delimited list of aliases that you define which reference your hypervisors. In the example text above there is a single server alias, myserver. Again, this does not have to be a valid DNS entry or network address. Just make it short and sweet as it will be used repeatedly in later property names.

The second two properties, com.hyper9.vmm.myserver.serverTypeAlias and com.hyper9.vmm.myserver.displayName specify the server type alias and display name of your server.

!!! Be sure to change the myserver alias in the property paths to the alias you specified for your server. !!!

The server type aliases are defined earlier in the file, but for inclusivness, here they are again:

• vmware - This server type alias works for VMware Server 2 servers, VI3.5, and vSphere servers.
• hyperv - This server type alias works for Microsoft Hyper-V servers.
• xen5 - This server type alias works for Citrix XenServer 5 servers.

The display name property should be set to whatever value you desire to be displayed to the end user in the web interfaces (both full and lite modes).

Next find the line:

com.hyper9.vmm.server.myserver.address=myserver.mydomain.com

Change the alias myserver in the property path to whatever you named your server's alias, and then change the actual value of the property to the IP address or fully-qualified domain name (FQDN) of your hypervisor.

You'll notice that the lines above this describe properties such as port numbers and SSL settings. You can customize these too -- either globally or specific to a server. To do this however it is recommended that you read the explanation of the property file's schema.

Adding Additional Hypervisors

Adding additional hypervisors is simple. Just repeat the steps above by first adding a new alias to the com.hyper9.vmm.serverAliases property and then re-creating all of the properties that were discussed above for the new server alias.

Licensing

VMM looks in two locations for its license file. The first location is the local license file at conf/vmm.lic. The second location is the global license file and is only valid on *Nix systems -- /etc/vmm/vmm.lic. On a *Nix system, if the global license file is present it will override the local license file.

VMM comes with a non-expiring license for 5 VMs which will work against any server you point VMM to (or multiple servers).

Installing a License

Installing a purchased VMM license is simple. Just open the purchased license file and copy its contents and paste them at the bottom of either the local or global license file. Restart VMM and the new license will take affect. Because licensing is cumulative, multiple, unique licenses will increase the total number of VMs you are allowed to manage with VMM.

Logging

The VMM logging settings are configured in conf/vmm.properties. VMM uses log4j to facilitate logging, and includes support for a console and file logger. To configure the file logger find the section in the properties file that begins with log4j.logger.com.lostcreations.vmm.server=INFO, vmmlog. You can adjust the verbosity of the log output by changing INFO to TRACE or DEBUG for more logging, or WARN, ERROR, or FATAL for less.

The step that must be taken is to change the location of the log file to a valid absolute path, for example, /opt/vmm/logs/vmm-server.log or c:\\vmm\\logs\\vmm-server.log (the double slashes are necessary on Windows). If you do not specify a valid location for the log file then the VMM application will not work.

Additional Configuration

There are additional steps you can take to further configure VMM, such as what port for it to use (8080 by default) and configuring SSL. These steps are common to Apache Tomcat and detailed explanations can be found at http://tomcat.apache.org/tomcat-6.0-doc/index.html.

Starting

Once VMM is installed and configured it is time to start her up!

Windows

To start VMM on Windows simply open the services control panel and start the service Apache Tomcat VMM (assuming you specified the name VMM when installing the service).

Linux / OS X

To start VMM on Linux / OS X or you use the startup.sh command in the bin sub-directory of where you placed VMM. Conversely, you use shutdown.sh to stop VMM.

You can also use the /etc/init.d/vmm daemon script if you installed it.

Using

VMM should now be up and running, so just open your web browser and point it at the server where you installed VMM. If VMM is not working properly please refer to the troubleshooting document.