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 attach name pattern

vws usb detach 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.

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

OPTIONS

INTERNALS

CONFIGURATION FILE

LAYOUT OF VIRTUAL MACHINES