NAME
====
*vws* - manage Virtual Workstations
SYNOPSIS
========
**vws create** *name* [ **--install** *isoimage* ]
**vws list** [**--state**] [**--usb** ]
**vws start** *name* [**--no-gui**] [**--cdrom** *iso-image*]
**vws stop** *name* [**--hard**]
**vws save** *name*
**vws reset** *name*
**vws cdrom** [ **--id** *id* ] [ *iso-image* | **--eject *]
**vws usb insert** *name* *pattern*
**vws usb remove** *name* *pattern*
**vws usb attached** *name*
**vws usb list**
**vws snapshot** *name* [ *id* ]
**vws revert** *name* [ *id* ]
**vws commit** *name*
**vws snapshots** *name*
**vws screenshot** *name* *filename.ppm*
**vws record** *name* *filename.wav*
**vws stoprecord** *name*
**vws monitor** *name*
**vws spiceuri** *name*
**vws version**
DESCRIPTION
===========
**vws** is thin scripting layer around **qemu-system**(1), which aims to
simplify common tasks for some usage scenarios. Note that **qemu** command
line is so complicated for good purpose, so any attempt to simplify it
would make some functionality unavailable.
**vws** is intended for software developers, who need to manually test
software on various systems, read documentation on them and experiment.
So, it is Virtual WorkStation system, not virtual servers or application
container.
It aims to allow user play with virtual machines directly, bypassing
vws. User is allowed to alter **qemu** parameters directly in the
**vws**-generated startup scripts and connect to monitor typing monitor
commands by hand. Copying virtual workstation from one host to another
is just a matter of transferring several files.
It is designed to be friendly with traditional unix behavior. Virtual
machines are started with normal user rights, there is no daemon running
to control them. Instead, there is UNIX sockets in the file system,
which allows to control machines.
Spice protocol is used for GUI. It allows seamless desktop integration
(i.e. mouse moving in and out VW window) and clipboard sharing.
By default, our VWs are accessible from localhost only, but it is easy
to set up password which lets to connect them via network.
It is allowed to redirect USB devices either via SPICE (i.e. from the
user workplace), or from host where VW is running. ISO images can be
mounted as CDROMs only from host.
VW CREATION
-----------
**vws create** command creates basic layout of the virtual machine -
virtual disk image and startup script and optionally starts installation
process connecting specified ISO-image to virtual CD-ROM drive.
It is also possible to create new machine with copy of existing virtual
drive.
Options of **create** commands allow to alter hardware configuration
(memory and disk size, disk interface, sound hardware, video card
disable sound and usb altogether).
What is hardcoded into **vws** system is that
1. Use unix domain socket in the same directory as startup script for
monitor. vws script rely of the existence of this script.
2. Use of **qcow2** image format. Without it, snapshots and saving VM
state would not work
3. Use spice as GUI protocol. It is only protocol which allows to share
clipboard of quest with clipboard of host, and redirect USB devices via
network.
Shared or personal VWs
----------------------
**vws** support creation of personal and shared VWs. Personal VWs is
created in the user home directory and accessible only for owner. Shared
VWs are created in some system wide directory and accessible for the
members of some group. By default it use **kvm** group, since only
members of this group have read-write access use kernel virtualisation
module, and it greatly improves performance of qemu for compatible
architectures.
VWs networking
--------------
**qemu** support various ways to connect virtual machine to network.
**vws** support only two of them - user mode network stack or bridged
network. By default VW is created with user mode network stack, which
basically means that it can establish outgoing TCP connections, but
there is no way to connect to it from outside world. (There is ways to
forward host ports to virtual machine in QEMU, but you'll have to hack
startup script manually to use it in the **vws** created machine).
Other way is bridged networking. I.e. each virtual machine would create
tun interface which would be connected to some bridge.
To use this mode, you have to perform following setup tasks
1. Make qemu-bridge-helper utility setuid root. (it is designed to run
setuid root, but Debian doesn't install it such way). It is required to
allow qemu, started from non-root user to add interface to bridge.
2. Create bridge interface to use. You can have several bridges and
specify which one would be used on VW creation. Really, by manual
editing of the startup script, you can add several network interfaces to
VW and connect them to the different bridges.
3. Setup you host system to forward packets from bridge network to
outside internet. You can either use NAT, or include your ethernet
interface into bridge.
4. Make sure DHCP server is running in the bridge network. If your
ethernet interface is part of the bridge, VWs would get their dynamic IP
from your network router. If you use NAT, you'll need to run DHCP
server, for instance **dnsmasq**(8) on your host and make it serve your bridge
interface. You can live without DHCP on bridge, but it would be your
problem to configure IP address on each VW manually. If you are planning
to deploy many VWs with different operating systems, it is better to
have DHCP running.
USAGE
=====
STARTING AND STOPPING
---------------------
**vws start** \[ **--cdrom** _iso-image_\] \[**--snapshot**\] \[ --no-gui \] *vw-name*
Starts virtual machine. Optionally, connects specified *iso-image* to
its CD-ROM drive. If **--no-gui** is not specified, starts spice client
(remote-viewer) to connect to this machine. If **--snapshot** is
specified, starts machine in the snapshot mode, i.e. nothing is written
into drive images. You need a lot of space in the */tmp* to run in
snapshot mode.
IF **--args** option is specfied, that its arguments are passed as
additional arguments to **qemu**.
If virtual machine is started already, and **--no-gui** is not
specified, than just starts remote viewer. Mnemonic *make machine
visible on your screen*. If **--cdrom** is specified, than it is
equivalent of **vws cdrom** described below. Snapshot mode and qemu args
cannot be changed on running machine.
**vws stop** [ **--hard** ] *machine*
Stops the virtual machine. If machine is running in the snapshot mode,
than it is stopped unconditionally, because nothing can be destroyed on
the disk images. Otherwise ACPI powerdown request is send to the guest
OS unless **--hard** is specified. With **--hard** machine is always
terminated immediately.
**vws save** *machine*
Saves virtual machine state into first disk image. Subsequent **start**
command would restore this state.
**vws reset** *machine*
Requests the reboot of guest OS via ACPI.
REMOVABLE DEVICE MANAGEMENT
---------------------------
**vws cdrom** *machine* [ **--eject** | *iso-image* ]
«Inserts» specified image into virtual machine's CD-ROM ejecting old one
if any. If **--eject** is specified instead of image, current image is
ejected.
**vws usb list**
Lists USB devices which can be attached to virtual machine.
**vws usb attached** *machine*
Lists USB devices which are currently attached
**vws usb insert** *machine* [ *pattern* | **--address** *bus.device* ]
Attach given devices to the virtual machine. *pattern* is some regexp
which device description output by **vws usb list** should match. Or,
optionally you can specify exact address as bus number and device number
on this bus.
**vws usb remove** *machine* [ *pattern* | **--address** *bus.device* ]
Detaches USB device.
SNAPSHOTS
---------
MISCELLANEA
-----------
**vws** allows to take virtual machine screenshot or record sound,
produced by virtual machine. One don't need to have GUI window open to
take screenshots.
**vws screenshot** *machine* *filename.ppm*
Makes a screenshot.
**vws record** *machine* *filename.wav*
Start recording of machine sound output
**vws stoprecord** *machine*
Stop recording sound.
**vws monitor** *machine*
Attaches to the machine monitor and allows user to send monitor commands
from the keyboard and see output. Uses lockin common to all **vws**
command, so you can use other **vws** command in parallel with
**monitor** command running.
**vws spiceuri** *machine*
Prints out URI you should feed into your spice viewer to access this
machine.
CONFIGURATION FILE
==================
Configuration file for [vws], which uses standard .ini format.
There are following sections
[directories]
[create options]
[tools]
Directories section
-------------------
Contain two parameters: **SharedVMs** and **AutostartVMs**. Both are directories where system-wide virtual machines are stored.
Shared VMs are VMs which are accessible for all members of **kvm** group, but must be started or stopped manually.
Autostart VMs are started automatically on boot of host.
If you are using more or less sensible disk layout, i.e. create separate partitions for /usr and /var, you probably want to tune this parameters, because you don't want to store your vms in the /var/cache.
It is recommended to have both these directories on the same partition, so moving VM from autostart to shared and vice versa would not involve physically copying of the files.
**NB** *autostart is planned for version 0.3*
Create options
--------------
This section list default values, used by **vws create** to create new virtual machines.
Following parameters can be used:
* **net=user** or **net=**_inteface name_ - network type by default. Can be either **user** or name of existing brige interface. If you have [set up bridge, you'll probably want to specify name of bridge interface here.
* **size=**_virtual disk size* - size of the disk image to create by default. 20G is probably big enough for most modern OS-es and small enough to fit on the modern disks. Note that we use **qcow2** format, so all disk space is not preallocated. You can use G or M suffixes to specify size.
* **mem=**_memory size_ - default memory size. Also can have M or G suffix.
* **diskif=**_interface_ where _interface_ can be **ide**, **scsi** or **virtio**. Disk interface. **virtio** offer best performance, but only if supported by quest operating system. **ide** offers best compatibilty. Windows vms must be created with ide, although it is possible to convert to virtio after installation.
* **arch=**_architecture_ In most cases your choice is limited between **i386** and **x86_64**. Although you probably have qemu binaries for many other architectures, and it is theoretically possible to use them, they would be emulated without hardware acceleration and require some queer QEMU parameters, which are not supported by **vws** now.
* **sound=**_list of sound cards) specify which sound cards are emulated in the virtual machine. In most cases **hda** is all you need. But qemu supports long list of sound cards which can be found out by typing:
qemu-system-i386 -soundhw help
You can specify several of them, separated by comma.
* **vga=**_type_ Type of emulated videoadapter **qxl** offers best performance with spice, but have mouse glitches with some old versions of X11. If you encounter such a problem, try to use some other type of videoadapter, listed on the manual page **qemu-system**(1).
TOOLS SECTION
-------------
Following programs can be specified via this section:
* **viewer=** Name of spice client to run. %s in the command line is replaced by spice URI. Default
remote-viewer %s
* **bridge_list=** command to run to list bridge interfaces. Default
brctl show
* **lsusb=** command to run to list host USB devices. Default lsusb.
LAYOUT OF VIRTUAL MACHINES
==========================
Even though virtual machines are completely independent, we need some conventions to simplify tools usage (to avoid specifying full path in the command line)
So, we adopt following convention:
1. All files related to each machine are stored in the one directory, named after the machine. See virtual machine directory.
2. There are three types of virtual machine - shared, autostarted and user.
shared and autostarted are stored in the some area, described in the global
configuration file /etc/vws.conf, user stored in ${HOME}/VWs.
Each virtual machine directory contains:
1. startup script, named **start**
2. monitor socket named **monitor**
3. pid file **pid**
4. One or more drive images. Each image can have several backing files (snapshots). All references to the drive images or to backing files within drive images use relative paths, so you can move directory around, and machine would still work.