1.\" $OpenBSD: vmctl.8,v 1.14 2016/09/12 06:20:18 jmc Exp $ 2.\" 3.\" Copyright (c) 2015 Mike Larkin <mlarkin@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 12 2016 $ 18.Dt VMCTL 8 19.Os 20.Sh NAME 21.Nm vmctl 22.Nd control the virtual machine daemon 23.Sh SYNOPSIS 24.Nm 25.Ar command 26.Op Ar arg ... 27.Sh DESCRIPTION 28The 29.Nm 30utility is used to control the virtual machine monitor (VMM) subsystem. 31A VMM manages virtual machines (VMs) on a host. 32The VMM subsystem is responsible for creating, destroying, and executing 33VMs. 34.Pp 35Within the commands, 36the 37.Ar size 38argument can be specified with a human-readable scale, 39using the format described in 40.Xr scan_scaled 3 . 41The 42.Ar id 43argument can be either a numeric, non-zero identifier or alternatively 44the name of a virtual machine. 45.Pp 46The commands are as follows: 47.Bl -tag -width Ds 48.It Cm console Ar id 49Using 50.Xr cu 1 51connect to the console of the VM with the specified 52.Ar id . 53.It Cm create Ar path Fl s Ar size 54Creates a VM disk image file with the specified 55.Ar path 56and 57.Ar size , 58rounded to megabytes. 59.It Cm load Op Ar filename 60Load the configuration from the specified file. 61.It Cm reload Op Ar filename 62Reload the configuration from the default configuration file. 63.It Xo Cm start Op Ar name 64.Op Fl c 65.Fl k Ar path 66.Fl m Ar size 67.Op Fl d Ar path 68.Op Fl i Ar count 69.Xc 70Starts a VM defined by the specified name and parameters: 71.Bl -tag -width "-i count" 72.It Fl c 73Automatically connect to the VM console. 74.It Fl d Ar path 75Disk image file (may be specified multiple times to add multiple disk images). 76.It Fl i Ar count 77Number of network interfaces to add to the VM. 78.It Fl k Ar path 79Kernel to load when booting the VM. 80.It Fl m Ar size 81Memory 82.Ar size 83of the VM, rounded to megabytes. 84.El 85.It Cm status Op Ar id 86Lists VMs running on the host, optionally listing just the selected VM 87.Ar id . 88.It Cm stop Ar id 89Stops (terminates) a VM defined by the specified VM 90.Ar id . 91.El 92.Pp 93If the 94.Fl i 95option is specified during VM startup, a corresponding number 96of host-side 97.Xr tap 4 98interfaces will be allocated and mapped to the 99.Xr vio 4 100interfaces inside the guest VM. 101This tap/vio interface mapping 102allows guest network traffic to be manipulated by the host. 103Any valid host-side interface configuration may be performed on these 104tap interfaces, such as bridging (via 105.Xr bridge 4 ) , 106or using 107.Xr pf 4 108nat-to rules to create private or host-side NATed networks, as desired. 109.Sh FILES 110.Bl -tag -width "/etc/var/run/vmd.sockXX" -compact 111.It Pa /etc/vm.conf 112Default configuration file. 113.It Pa /var/run/vmd.sock 114.Ux Ns -domain 115socket used for communication with 116.Xr vmd 8 . 117.El 118.Sh EXIT STATUS 119.Ex -std vmctl 120.Nm 121may fail due to one of the following reasons: 122.Pp 123.Bl -bullet -compact 124.It 125The VMM subsystem could not be enabled or disabled as requested. 126.It 127A requested VM-based operation could not be completed. 128.El 129.Sh EXAMPLES 130Create a 4.5 Gigabyte disk image, disk.img: 131.Dl $ vmctl create disk.img -s 4.5G 132.Pp 133Create a new VM with 512MB memory, one network interface, one disk image 134('disk.img') and boot from kernel '/bsd': 135.Bd -literal -offset indent 136$ vmctl start "myvm" -m 512M -i 1 -d disk.img -k /bsd 137.Ed 138.Pp 139Terminate VM number 1: 140.Dl $ vmctl stop 1 141.Sh SEE ALSO 142.Xr bridge 4 , 143.Xr pf 4 , 144.Xr tap 4 , 145.Xr vio 4 , 146.Xr vmm 4 , 147.Xr vm.conf 5 , 148.Xr rc.conf 8 , 149.Xr vmd 8 150.Sh HISTORY 151The 152.Nm 153command first appeared in 154.Ox 5.9 . 155.Sh AUTHORS 156.An -nosplit 157.An Mike Larkin Aq Mt mlarkin@openbsd.org 158and 159.An Reyk Floeter Aq Mt reyk@openbsd.org . 160