% 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 ]

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

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

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 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 ]

Lists available virtual machines. If --state option is given, prints out state (running or stoped) type (private or shared) and spice URI (if machine is running).

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.

One vws sendkey command sends only one key combination

See KEY SPECS below about format of key specification.

KEY SPECS

Following key names are avalable:

shift shift_r alti alt_r altgr altgr_r ctrl ctrl_r menu

esc 1 2 3 4 5 6 7 8 9 0 minus equal backspace tab q w e r t y u i o p ret a s d f g h j k l z x c v b n m comma dot slash asterisk spc caps_lock f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 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 < f11 f12
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.

NB autostart is planned for version 0.3

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

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