NAME
vmctl
—
control the virtual machine
daemon
SYNOPSIS
vmctl |
command [arg ...] |
DESCRIPTION
The vmctl
utility is used to control the
virtual machine monitor (VMM) subsystem. A VMM manages virtual machines
(VMs) on a host. The VMM subsystem is responsible for creating, destroying,
and executing VMs.
Within the commands, the size argument can be specified with a human-readable scale, using the format described in scan_scaled(3). The id argument can be either a numeric, non-zero identifier or alternatively the name of a virtual machine.
The commands are as follows:
console
id- Using cu(1) connect to the console of the VM with the specified id.
create
path-s
size- Creates a VM disk image file with the specified path and size, rounded to megabytes.
load
filename- Load additional configuration from the specified file.
log brief
- Disable verbose debug logging.
log verbose
- Enable verbose debug logging.
reload
- Remove all stopped VMs and reload the configuration from the default configuration file.
reset
[all
]- Reset the running state.
reset switches
- Reset the configured switches.
reset vms
- Reset and terminate all VMs.
start
name [-b
path] [-c
] [-d
path] [-i
count] [-m
size] [-n
switch]- Starts a VM defined by the specified name and parameters:
-b
path- Boot the VM with the specified kernel or BIOS image. If not specified, the default is to boot using the BIOS image in /etc/firmware/vmm-bios.
-c
- Automatically connect to the VM console.
-d
path- Disk image file (may be specified multiple times to add multiple disk images).
-i
count- Number of network interfaces to add to the VM.
-m
size- Memory size of the VM, rounded to megabytes. The default is 512M.
-n
switch- Add a network interface that is attached to the specified virtual switch. See SWITCH CONFIGURATION in vm.conf(5) for more information.
status
[id]- Lists VMs running on the host, optionally listing just the selected VM id.
stop
id- Stops (terminates) a VM defined by the specified VM id. A graceful shutdown will be attempted if the VM supports the vmmci(4) device. Once stopped, if the VM was not defined in a configuration file, then it is removed.
If the -i
option is specified during VM
startup, a corresponding number of host-side
tap(4) interfaces will be allocated and mapped to the
vio(4) interfaces inside the guest VM. This tap/vio interface mapping
allows guest network traffic to be manipulated by the host. Any valid
host-side interface configuration may be performed on these tap interfaces,
such as bridging (via
bridge(4)), or using
pf(4)
nat-to rules to create private or host-side NATed networks, as desired.
FILES
- /etc/vm.conf
- Default configuration file.
- /var/run/vmd.sock
- UNIX-domain socket used for communication with vmd(8).
EXIT STATUS
The vmctl
utility exits 0 on
success, and >0 if an error occurs. vmctl
may fail due to one of the following reasons:
- The VMM subsystem could not be enabled or disabled as requested.
- A requested VM-based operation could not be completed.
EXAMPLES
Create a 4.5 Gigabyte disk image, disk.img:
$ vmctl create disk.img -s 4.5G
Create a new VM with 1GB memory, one network interface, one disk image ('disk.img') and boot from kernel '/bsd':
# vmctl start "myvm" -m 1G -i 1 -d disk.img
vmd(8) will create a new tap(4) network interface on the host side and set the description to indicate the VM by ID, interface number, and name:
# ifconfig tap0 tap0: flags=8842<BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 lladdr fe:e1:ba:d8:50:d1 description: vm1-if0-myvm index 15 priority 0 llprio 3 groups: tap status: active
Terminate VM number 1:
# vmctl stop 1
SEE ALSO
bridge(4), pf(4), tap(4), vio(4), vmm(4), vm.conf(5), rc.conf(8), vmd(8)
HISTORY
The vmctl
command first appeared in
OpenBSD 5.9.
AUTHORS
Mike Larkin <mlarkin@openbsd.org> and Reyk Floeter <reyk@openbsd.org>.