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