vws script is main workhorse of the first stage of project.

It allows to send commands to the vm

Starting and stopping

vws start [--no-gui] [--cdrom isofile] [--snapshot] [ --args "more args" ] vmname

Starts machine. By default, immediately after machine starts, launches spice client (remote-viewer) to connect it. If no DISPLAY environment variable is set or if --no-gui is specified, doesn't launch GUI. If --cdrom is specified, connects specified ISO to machine CDROM and boots it from it.

If --snapshot is specified, starts qemu in snapshot mode. In this mode all disk images are read only and all changes in the fs are written into temporary file which is removed upon shutting machine down.

If --args* is specified, its argument is added to the QEMU command line.

If machine is running in the background, just launches gui, unless not asked to. If machine is running and gui is not needed, just exits immedieately with zero exit code. In this case --args and --snapshot would be ignored with warning and --cdrom is interpreted as if vws cdrom command was issued.

If machine is not running and saved state exists, load saved state.

Semantic: "make this machine running*

vws stop vmname [--hard]

Sends system_shutdown command to machine. With --hard powers virtual machine off unconditionally and immediatelty. Without it, sends ACPI shutdown request.

vws save vmname

Saves machine state and terminates emulation.

vws reset vmname

Sends system_reset command to machine

Removable devices management

vws cdrom machine [id] [iso-file|--eject]

Connects given iso file (CDROM special device) to the machine or disconnects one. If there is more than one cdrom drive in the virtual machine, id should be specified.

vws usb insert machine [pattern|--address=bus:device]

Connects USB device which matches pattern or have specifed address

vws usb list 

List host devices available to connect to the machine

vws usb machine remove [pattern|id]

Removes device which matches pattern. Pattern is reqular expression which is matches against lsusb output, so vendorid:productid is perfectly valid pattern.

If there is more than one device which matches pattern, complains vws usb complans and exits with non-zero code.

Snapshots

vws snapshot machine snapshot_id

Creates a snapshot of machine. Works only if machine is powered off

vws revert machine

Reverts machine to previous snapshot, deleting current and creating new. Works only if machine is powered off.

vws commit machine

Commits snapshot into its backing file. If machine is running in snapshot mode, commits temporary changes. If machine is not running, commits and removes alast snapshot.

vws snapshots machine

List existing snapshots.

Screenshots and recording

vws screenshot machine filename.ppm

Makes a screenshot.

vws record machine filename.wav

Start recording of machine sound output

vws stoprecord machine

Stop recording

Creating a virtual machine

 vws create [ --no-usb] [--size size] [--arch cputype] [--no-sound]
           [--sound cardtype] [--vga cardtype] [--net NET] [--mem size]
           [--diskif interface-type] [--shared] [--image filename]
           [--install filename.iso]
           machine

Creates new virtual machine. By default - private one, if --shared specified - shared one.

--net can be either user (default) or name of existing bridge interface. To use bridge you must have qemu-bridge-helper(8) setuid root.

--size sets virtual size of first drive image. Not needed if --image is used. Acceptable syntax nnM or nnG

--mem size of memory - same syntax as --size

--vga allows to specify type of emulated graphic card instead of default qxl. May be needed for some older OS.

--diskif allows to specify disk interface (ide or scsi) insteado of default virtio (required for non-linux guests).

--image specifies preexisting image in the format, understandable by qemu-img(1) to use as disk of newly created VM. Image would be copied into VM directory and converted to qcow2 format.

--install specifies, that ISO image with OS distribution should be connected and newly created VM started, booting from it.

Miscellaneous

vws monitor machine

Connects to monitor socket and send there commands, read from stdin and writes results to stdout. Provides way to interact with QEMU respecting locking

vws spiceurl machine

Outputs to stdout spice url needed to connect machine, if machine is running and exits with non-zero exit code if machine is not running.

vws version

Reports a version

Operation on multiple machines

vws list [--state] [--address] [--usb] [-l]

List all machines set up via these tools. Option --state shows whether machine is running or not, --address - shows mac address -l is equevalent of both --state and --address

vws autostart

Starts all machines in the authostart directory. (not implemented in version 0.2)

vws autostop

Tries to shutdown correctly all running machines. (not implemented in version 0.2)