% VWS(1)
% Victor Wagner <vitus@wagner.pp.ru>
% December 2015
NAME
====
*vws* - manage Virtual Workstations
SYNOPSIS
========
**vws create** *name* [ **--install** *isoimage* ]
**vws list** \[**--state**\] \[**--usb**\] \[ *pattern* ... \]
**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 autostart**
**vws shutdown** \[**--wait**\] \[**--timeout** *sec*\]
**vws screenshot** *name* *filename.ppm*
**vws record** *name* *filename.wav*
**vws stoprecord** *name*
**vws sendkey** *name* *keyspec*...
**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.
USERS AND GROUPS
================
Most linux systems allow to run virtual machines to any user, who is
member of group **kvm**. **vws** makes same assumption. VMs are running
under rights of invoking user.
VWs, autostarted during system boot, however, need special user to run
under.
If you use bridge networking, QEMU would need administrative rights to
add its virtual interface to the bridge. QEMU includes special utility
**qemu-bridge-helper**, which is designed to run with elevated
privileges, and safely can be installed setuid root. It only allows
actions on bridge interface, which is listed in **allow** statement
in **/etc/qemu/bridge.conf**.
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.
(this is done automatically by postinst script in Debian package).
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.
You should assign some MAC address to the bridge interface used by
virtual machines.
If you ethernet interface is part of the bridge, it already have one.
Otherwise use command
ip link set dev *bridge_name* address XX:XX:XX:XX:XX:XX
or some distribution-specific configuration file.
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.
Options of **vws create** command
---------------------------------
Almost all options of create command can be omitted. In this case,
defaults from **/etc/vws.conf** or **${HOME}/.vwsrc** would be used.
Typically one needs just **--image** or **--install** option, unless he
wants to alter hardware configuration.
**--no-usb**
: disable USB controller and USB redirection.
**--no-sound**
: disable sound card.
**--sound** *cardtype*
: Use given soundcard model. Can be comma-separated list of card models. Use ``qemu-system -soundhw help`` for list of sound cards, supported on your system.
**--arch** *cputype*
: Emulated architecture. Note that emulation of foreign arch can be very slow.
**--vga** *cardtype*
: Video card type (cirrus,std,vmware,qxl). Use **qxl** unless you are sure that guest OS doesn't work with it.
**--mem** *size*
: Size of memory. Can have suffix **M** for megabytes and **G** for gigabytes
**--size** *size*
: Size of primary disk image to create. Not needed if **--image** is specified.
**--net** *ifname*
: Network interface name. Typically it is name of bridge interface which would be used to add network interface of virtual machine. Bridge interface must exist before issuing **create** command and preferable should run some DHCP server. Also word **user** can be used instead of bridge name, which means to use QEMU user mode networking.
**--diskif** *type*:
: Disk interface (virtio, scsi, ide). **virtio** interface is fastest, but some OSes do not support it out of the box. So, you may need to install OS using **ide** or **scsi** interface, then install virtio drivers and then change interface.
**--image** *filename*
: Existing disk image to import. If this option is specified, primary disk image would be created by importing given image, rather creating new one of specified **--size**. Import would always create a copy, not use original image. Image can have any format, supported by **qemu-img**(1), including VMware and VirtualBox images.
**--shared**
: Create shared VW instead of private one
**--install** *filename.iso*
: ISO image to install OS from. If this option is specified, virtual machine would be started immediately after creation and given image would be booted from.
USAGE
=====
STARTING AND STOPPING
---------------------
**vws start** \[ **--cdrom** _iso-image_\] \[**--snapshot**\] \[**--no-gui**\] \[**--args** *qemu-args*\] *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.
AUTOSTART AND SHUTDOWN
----------------------
Machines, placed into system wide directory specified in the
configuration (see **Configuration
File** below) would be automatically started at system startup (provided
that **vws** service is enabled). This is performed using
**vws autostart**
command, which starts all the VMs in autostart directory. It starts VMs
under special user, specified in the configuration file.
**vws shutdown** \[**--wait**\] \[**--timeout** *sec*\]
Does more than just stop autostarted VMs. Actually it tries to shut down
gracefully all the VMs, it found running. If **--wait** option is
specifed, it repeats scan for running VMs each ten second until
**--timeout** (default 90) seconds expired. When timeout expired, it
forcibly stops all remaining VMs.
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
---------
**vws snapshot** *machine* *name*
Creates named snapshot. This means that there would be additional image
file for each virtual disks. All writes would go to new file, and
previous file would be unchanged until commit operation. Note that
having long chain of snapshots significantly slower disk IO operations.
**vws** allows snapshots be made only when virtual machine is stopped.
**vws** **commit** *machine*
Writes changes in the current snapshot into previous one.
There would be one snapshot less for this machine after this operation.
If this operation is performed on stopped machine it operates on stack
of snapshots created by **vws** **snapshot** command.
If it is performed on running machine, this machine should run in the
snapshot mode (see **start** command for details) and changes made since
start in the snapshot mode are committed into permanent images.
**vws** **revert** *machine*
Discard changes made to disks since last **vms snapshot** command
and recreates snapshot. This command can be only performed
on stopped machine. Number of snapshots would be same after this
command.
**vws** **snapshots** *machine*
List named snapshots available for given machine. This command
can be used on running machine, despite of that machine must be shutdown
before snapshots could be committed or reverted.
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 locking common to all **vws**
command, so you can use other **vws** command in parallel with
**monitor** command running. Use **Ctrl-D** to exit monitor mode, because if
you send **quit** command it would quit virtual machine, not the
interaction with it.
**vws spiceuri** *machine*
Prints out URI you should feed into your spice viewer to access this
machine.
**vws list** [ **--state** ] \[ **--usb** \] \[ *pattern* .. \]
Lists available virtual machines. If **--state** option is given, prints
out state (running or stopped) type (private or shared) spice URI (if
machine is running), mac and IP address. Pattern is shell-style wildcard
which limits machines to be shown. Don't forget to quote pattern from shell. It
should be expanded. **--usb** option lists USB devices connected to the
virtual machine using **vws usb** command.
**vws sendkey** *machine* *keyspec*...
Allows to send some key combination to the virtual machine. For example
if windows screen is locked spice client is sometimes unable to deliver
key stroke to the virtual machine in order to get it out of sleep.
In this case **vws sendkey** *machine* **ctrl-alt-delete** helps.
Each key combination should be passed to **vws sendkey** as separate
argument. Not all ascii characters can be specified as arguments.
I.e. it is not possible to determine whether colon should be
send as shift-;
See **KEY SPECS** below about format of key specification.
Keys send via this command are subject of guest keyboard mapping.
So, you can switch keyboard layout by sending switching key sequence
and then send text on non-latin language.
KEY SPECS
=========
Following key names are avalable:
```
shift shift_r alt alt_r altgr altgr_r ctrl ctrl_r menu
esc f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
grave_accent 1 2 3 4 5 6 7 8 9 0 minus equal backslash backspace
tab q w e r t y u i o p bracket_left bracket_right ret
a s d f g h j k l semicolon apostrophe
z x c v b n m comma dot slash
asterisk spc caps_lock num_lock scroll_lock kp_divide kp_multiply
kp_subtract kp_add kp_enter kp_decimal sysrq kp_0 kp_1
kp_2 kp_3 kp_4 kp_5 kp_6 kp_7 kp_8 kp_9 less
print home pgup pgdn end left up
down right insert delete
```
Several key names can be joined together with '-' sign to form key with
modificators sequence.
CONFIGURATION FILE
==================
Configuration file for [vws], which uses standard .ini format.
There are following sections
[directories]
[permissions]
[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.
Permissions
-----------
Options of this section controls interaction with unix user names and
groups for shared and authostarted VMs.
* autostart_user - user name of user which should all autostart vms run
run as
* vm_group - group name which should own all shared VMs.
* setgid_vm - boolean, true if setgid attribute should be set on shared
VM directory
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 bridge interface. If you have set up bridge, you'll probably want to specify name of bridge interface here.
* **size=**_virtual disk sizex_ - 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
compatibility. 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 video adapter **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.
FILES
=====
**/etc/vws.conf**, _\${HOME}_**/.vwsrc**, _\${HOME}_**/VWs**,
**/etc/qemu/bridge.conf**
SEE ALSO
========
**find\_free\_port**(1), **qemu-system**(1), **brctl**(8)