This page describes how to install, configure, and use the Snooze command-line interface (CLI). Note that for the time being the CLI installation tutorial is for Debian users only. Still as we also provide the CLI binary, with little efforts you should be able to run it on any distribution after following this tutorial.
1 Install the client
Get the latest client Debian package from the Download page and install it:
$ dpkg -i snoozeclient_X.X-X_all.deb
2 Configure the client
Open the client configuration package file /usr/share/snoozeclient/configs/snooze_client.cfg. It is split into two parts: general and statistics
general.bootstrapNodes = localhost:5000,192.168.0.2:5001 general.submissionPollingInterval = 6 general.numberOfMonitoringEntries = 5 general.dumpOutputFile = /tmp/snooze_tree.xml statistics.enabled = false statistics.output.format = gnuplot statistics.output.file = /tmp/snooze_results.dat
The client application requires at least one active bootstrap node in order to discover the current group leader (GL). Consequently it will contact one of the active servers specified in the general.bootstrapNodes list to do so.
The VM submission requests are processed asynchronously in Snooze. The client application submits the requests to the GL and periodically polls it for a reply. The polling interval can be specified using the general.submissionPollingInterval parameter.
The client application offers features to retrieve VM monitoring information as well as to visualize the system hierarchy. Therefore, it needs to send requests to the group manages (GMs). The parameter general.numberOfMonitoringEntries specifies the number of monitoring entries client requests from the GMs.
Finally the client application offers a feature to dump the hierarchy layout in the GraphML format to the disk. Therefore, the general.dumpOutputFile parameter specifies the output file name.
Once enabled (statistics.enabled) the client application will write statistics (e.g. submission time, number of failed submissions) to the disk. You can specify the statistics output format and the file name using the two parameters: statistics.output.format, statistics.output.file. Note that currently only GNUPlot output format is implemented.
3 Control VM life-cycle
On the shell execute the “snoozeclient” command. The following commands are currently supported:
Commands: define Define virtual cluster undefine Undefine virtual cluster add Add virtual machine to the cluster remove Remove virtual machine from the cluster start Start virtual cluster/machine suspend Suspend virtual cluster/machine resume Resume virtual cluster/machine shutdown Shutdown virtual cluster/machine destroy Destroy virtual cluster/machine info Shows virtual cluster/machine information list List virtual clusters visualize Visualize system hierarchy dump Dump system hierarchy
You can display a help for each command by executing “snoozeclient [command] –help“.
We use the notion of virtual cluster (VC) to group together virtual machines (VMs) prior submission on the client side. Consequently, in order to submit VMs you first need to define at least one VC and add some VMs to it. To define a VC execute the following command:
$ snoozeclient define -vcn myVC
Note that you can always undefine/remove the VC using the undefine command.
In order to add VMs to your newly created VC, first disk images and VM templates must be created. Thereby, disk images must be placed on a storage accessible to all the local controllers (LCs), otherwise they can not be located by the LCs during submission. For example, if you are using NFS and the QEMU Copy-on-Write (COW) mechanism you need to go through the following steps: (1) Copy backing file VM image to the mounted storage directory (e.g. /opt/cloud); (2) Create a COW file from the backing file image for each VM; (3) Create and modify the VM template to point to the COW image.
Please follow the How you can use qemu/kvm base images to be more productive tutorial now to create and install your backing file image (also known as base image).
Now that you have your base image installed, you must configure its networking in order to be reachable to the outside world after submission. Snooze automatically assigns IP addresses to VMs from the system administrator defined VM subnet (see networking settings in the Admin manual) during submission. This is currently done by encoding the assigned IP address into the VMs MAC address. When a VM boots it needs to decode this IP from its MAC address and configure the networking. We use an init script to accomplish these tasks. You can find it on the Download page. It was tested on the Debian as well as Ubuntu operating system. Please move it to your /etc/init.d/ directory and run the following command to update the init script links.
$ update-rc.d vmcontext defaults
Your base image should be now ready!
Assumed that the name of your backing file is debian-base.raw, you will need to execute the following command to create a COW image debian1.qcow2
$ qemu-img create -b debian-base.raw -f qcow2 debian1.qcow2
You can now prepare the VM template. Currently, the client accepts native libvirt templates. It is important that you choose different names and UUIDs for your VMs. Otherwise, subsequent submissions will fail due to naming conflicts. Moreover, disk image path and bridge name must be set correctly. An example libvirt VM template (debian1.xml) for the KVM hypervisor could look as follows:
<type arch='x86_64' machine='pc-0.12'>hvm</type>
<disk type='file' device='disk'>
<driver name='qemu' type='qcow2'/>
<target dev='vda' bus='virtio'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x05' function='0x0'/>
<controller type='ide' index='0'>
<address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x1'/>
<target type='serial' port='0'/>
<graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'/>
<input type='tablet' bus='usb'/>
<input type='mouse' bus='ps2'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x0'/>
Note that the bridge name virbr0 must correspond to the bridge configured on the LCs!
The VM can now be added to the VC. Therefore you need to specify the VC name and pass the VM template describing your VM environment. In addition networking capacity constraints can be specified. For example, Snooze can be instructed to cap the VMs network capacity requirements to 10MBit/sec. The following command adds a VM those network capacity is bounded to 10MBit. Note that in case of no network capacity restrictions are given the default value is 100MBit.
$ snoozeclient add -vcn myVC -vmt /home/user/vmtemplates/debian1.xml -rx 12800 -tx 12800
Note that you can always remove a VM by simply calling: snoozeclient remove -vcn myVC -vmn myVM
You can now either add more VMs and start all of them at once or trigger individual VMs submissions by executing one of the following commands:
$ snoozeclient start -vcn myVC (starts all VMs belonging to myVC) or $ snoozeclient start -vcn myVC -vmn myVM (starts myVM)
If everything went well you should see a similar output.
Name VM address GM address LC address Status -------------------------------------------------------------- debian1 192.168.122.5 10.0.0.2 10.0.0.2 RUNNING
Please see the FAQ for possible problem resolutions (e.g. ERRORs in submission). Otherwise use the user mailing list to ask questions.
Finally, the client offers a variety of commands to control the VM execution. For example, it is possible to suspend, resume, shutdown, or destroy VCs/VMs by simply calling:
$ snoozeclient suspend/resume/shutdown or destroy -vcn myVC (all VMs belonging to myVC) $ snoozeclient suspend/resume/shutdown or destroy -vcn myVC -vmn myVM (only myVM)
Last but not least, VM resource (i.e. CPU, memory, network Rx, network Tx) usage information can be displayed using the info command either for the entire VC or a single VM. You should see a similar output:
Name CPU Memory Rx/Tx VM GM LC Status usage usage usage address address address ---------------------------------------------------------------------------------- debian1 0.09 596992 0.12/0.1 192.168.122.5 10.0.0.2 10.0.0.2 RUNNING
Note that it takes some time to propagate the initial VM monitoring information data. During this time the client will display the “UNKNOWN” message in the usage fields.
4 System hierarchy visualization and dump
You can use the client to visualize the current hierarchy state (GL, GMs, LCs, VMs) or dump it in GraphML format to the disk. Visualization requires either a running XServer or X11 forwarding. You can activate visualization by using the appropriate client command:
$ snoozeclient visualize
If everything works out a GUI will appear in which you will be able to specify the polling interval and start/stop the visualization process. Moreover, you will be able to zoom in and out the hierarchy state. The polling interval specifies the time period in which the client will request system repository information and redraw the hierarchy. This allows to visualize the system self-organization and healing as well as VM live migrations (e.g. during relocation and consolidation). The following figure shows an example system visualization with one GL, 2 GMs, 4 LCs, and 2 VMs. Each components is represented by its own color (e.g. red for GL).
Use the dump command to write out the hierarchy state to disk. You will find the output in the previously specified general.dumpOutputFile file.