vm (1)

NAME

vm - simplistic, per-user VM management.

SYNOPSIS

vm creat | prepare | ls | slink | start | ports | iodir | attach | ssh | off | purge

When called without any parameters, vm prints all available commands. vm '<command>' '-h' prints help for '<command>'.

DESCRIPTION

vm is a command line tool for simplistic virtual machine management.

VMs will be run using qemu. By default, VMs are headless, backgrounded, and run in "immutable" ("snapshot") mode - all changes to the VM will be lost after it is shut down.

Access to and from the host system

Networking

When VMs run their network in 'hidden' mode (qemu’s "user mode networking") the guest networking is completely opaque to the host. Selected server ports of the guest may be forwarded so the host can connect - refer to vm creat and the Files and Directories section for more information. Ports forwarded by the VM are dynamically mapped to host ports when the VM is started. vm ports will show the mappings of an active VM.

Filesystem access and file transfer

The host’s root directory is made available read-only via plan9 with the ID 'hostroot'. The guest may mount it like e.g.

mount -t 9p -o trans=virtio,ro hostroot /<whereever> -oversion=9p2000.L,posixacl,cache=none

In order to export files from the guest a second directory with the ID 'io' is made available to the guest, but in read-write mode. It may be mounted in the guest like e.g.

mount -t 9p -o trans=virtio,rw io /<whereever> -oversion=9p2000.L,posixacl,cache=none

Since the host directory backing this guest mount needs to be writeable, an "IO dir" is maintained for each VM. The directory may be printed by issuing 'vm iodir <name>'.

The command vm prepare arranges for a mount on '/_host_root' and '/_io' respectively in the guest system’s fstab.

vm commands

The commands are:

vm ls

List virtual machines.

vm slink

Soft-link an existing VM to a new VM.

vm start

Start a virtual machine.

vm ports

Print the host port → VM port mapping of an active VM.

vm iodir

Print the IO directory (for transfering files).

vm attach

Attach to the serial console of an active VM.

vm ssh

Run an SSH command (or an interactive shell) on an active VM.

vm off

Power off an active VM.

Also (for VM creation and removal):

vm creat

Create a new VM.

vm prepare

Prepare a fresh VM to work well with vmscripts.

vm purge

Remove a VM, including all images and configurations.

For a detailed description of each command refer to the sections below.

vm ls

vm ls '[-a|--active]' '[-t|--tap]'

List all VMs known to vm. A flag will be added to the output for soft-linked or currently active.

The optional arguments are:

[-a|--active]

List only VMs which are currently active.

[-t|--tap]

List only VMs which use TAP networking.

Example output:

    user@host $ vm ls
             name       active            soft link         network   mode
             debian7   (active)                        172.16.10.0/24 hidden
            fedora21                                   172.16.10.0/24 hidden
         piler-build                     (->debian7)   172.16.10.0/24 hidden
       piler-install                     (->debian7)   172.16.10.0/24 hidden
                win8                                   172.16.10.0/24 hidden

vm slink

vm slink '<source>' '<destination>'

Soft-link VM '<source>' to new VM '<dest>'. The VMs will share the same image, so be aware that modifying the source VM image will affect all VMs soft-linked from that source.

vm start

vm start '<name>' '[optional arguments]' - Start virtual machine '<name>'.

<name>

Name of the virtual machine to start.

The optional arguments are:

[-f|--foreground]

Run in foreground. You’ll be connected to the VM’s serial line.

[-g|--graphics]

Enable graphics output.

[-w|--writeable]

Run in "mutable" mode. All changes to the VM will persist.

[-n|--no-root]

Never ask for root password. Instead, fail if root is required.

[-b|--boot-iso]

ISO image (CD/DVD) has boot priority.

vm ports

vm ports '<name>'

Print the host port → VM port mapping of active VM '<name>'.

vm iodir

vm iodir '<name>'

Print the IO directory mapping (host ⇒ guest) for VM '<name>'. For a discussion of the IO directory please refer to the section Filesystem access and file transfer above.

vm attach

vm attach '<name>'

Attach to the serial console of active VM '<name>'.

vm ssh

vm ssh '<name>' '[cmd]'

Run command '[cmd]' on active VM '<name>', or an interactive shell if '[cmd]' was omitted.

vm off

vm off '<name>'

Power off active VM '<name>'.

vm creat

vm creat '<name>' '[<optional arguments>]'

Create new VM '<name>'

Create a new VM.

<name>

unique identifier for this VM

Issuing vm creat -h will print the default values of optional arguments.

The optional arguments are:

-d|--disk '<path-to-image>'

Copy pre-existing harddisk image instead of creating a new empty volume.

-s|--disk-size '<size>'

Size of the harddisk volume (may be followed by K, M, G or T) to be created for the new VM.

-i|--iso '<path-to-iso-image>'

Path to an ISO image to use with the VM. The image will be copied.

-M|--move

Move source disk image and ISO instead of copying.

-m|--mem '<mem-size>'

Amount of memory (followed by M or G).

-c|--cpus '<nr-of-cpus>'

Virtual CPUs count.

-N|--net-mode '<hidden|tap>'

Networking mode:

--net-mode hidden

No host-visible network devices; VM ports need to be forwarded (see -p). This is the default.

--net-mode tap

VM uses a TAP device on the host. Starting the VM will require root privileges.

-n|--net '<internal-network>'

VM-internal network (IP/MASK).

-p|--ports '<forwarded-ports>'

List of ports forwarded to host ports in 'hidden' network mode, separated by comma (e.g. '22,80,554')

vm prepare

vm prepare '<name>'

Prepare VM '<name>' to play well with vmscripts.

This preparation should be done once after the VM was set up. It will generate SSH keys and add those to the VM’s root account, activate serial sonsole I/O for Linux and grub (so vm attach will work) and provides access to the exported host root inside the VM.

vm purge

vm purge '<name>'

Remove VM '<name>', including all images and configurations.

Files and Directories

vmscripts store all VM images (both disk and ISO) as well as the VM configuration in a per-VM sub-directory in '~/.vmscripts/'.

~/.vmscripts/<name>/<name>.raw

The VM disk image

~/.vmscripts/<name>/<name>.iso

The VM ISO (cdrom, dvd) image, if applicable.

~/.vmscripts/<name>/<name>.cfg

The VM configuration, including port mappings.

Structure of the VM configuration files

~/.vmscripts/<name>/<name>.cfg

is a bash-sourced 'variable="value"' configuration. Currently it supports the following variables:

net="<ip address + subnet mask>"
cpu="<number of CPUs>"
mem="<Amount of memory, followed by M or G>"
forward_ports="<list of forwarded ports separated by spaces>"
netmode="<hidden|tap>"

AUTHOR

vmscripts were written and are maintained by Thilo Alexander Fromm ([email protected]).

RESOURCES

Github project: https://github.com/t-lo/vmscripts

COPYING

Copyright (C) 2015 Thilo Alexander Fromm. Relased under the terms of the GNU GPL v3.