% 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

Use unix domain socket in the same directory as startup script for monitor. vws script rely of the existence of this script.
Use of qcow2 image format. Without it, snapshots and saving VM state would not work
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

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).
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.

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.
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:

All files related to each machine are stored in the one directory, named after the machine. See virtual machine directory.
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:

startup script, named start
monitor socket named monitor
pid file pid
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