1.\" $OpenBSD: vmctl.8,v 1.78 2024/05/04 07:51:21 jmc Exp $ 2.\" 3.\" Copyright (c) 2015-2024 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: May 4 2024 $ 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.Op Fl v 26.Ar command 27.Op Ar arg ... 28.Sh DESCRIPTION 29The 30.Nm 31utility is used to control the virtual machine monitor (VMM) subsystem. 32A VMM manages virtual machines (VMs) on a host. 33The VMM subsystem is responsible for creating, destroying, and executing 34VMs. 35.Pp 36The 37.Fl v 38option enables verbose mode. 39Within the commands, 40the 41.Ar size 42argument can be specified with a human-readable scale, 43using the format described in 44.Xr scan_scaled 3 . 45The 46.Ar id 47argument can be either a numeric, non-zero identifier or alternatively 48the name of a virtual machine. 49.Pp 50The 51.Ar name 52argument can only consist of alphanumeric characters, as well as '.', '-', 53and '_', 54and must start with a letter. 55.Pp 56The 57.Ar disk 58argument is used by commands that take a path to a disk image file. 59It may be prefixed with a format prefix 60.Pf ( raw : Ns Ar disk 61or 62.Pf qcow2 : Ns Ar disk ) 63.Sm on 64in order to specify the disk image format. 65If left unspecified, the format defaults to 66.Sq raw 67if it cannot be derived automatically. 68.Pp 69The commands are as follows: 70.Bl -tag -width Ds 71.It Cm console Ar id 72Using 73.Xr cu 1 74connect to the console of the VM with the specified 75.Ar id . 76.It Cm create Oo Fl b Ar base | Fl i Ar disk Oc Oo Fl s Ar size Oc Ar disk 77Create a VM disk image file with the specified 78.Ar disk 79path. 80.Bl -tag -width "-i input" 81.It Fl b Ar base 82For 83.Sq qcow2 , 84a 85.Ar base 86image may be specified. 87The base image is not modified and the derived image contains only the 88changes written by the VM. 89.It Fl i Ar disk 90Copy and convert the input 91.Ar disk 92to the newly created disk. 93This option conflicts with 94.Fl b Ar base . 95.It Fl s Ar size 96Specify the 97.Ar size 98of the new disk image, rounded to megabytes. 99If the 100.Fl b 101option is specified, the size must match the size of the 102.Ar base 103image. 104For the 105.Fl i 106option, the size cannot be smaller than the input disk size. 107The size can be omitted with the 108.Fl b 109and 110.Fl i 111options and will be obtained from the base or input image respectively. 112.El 113.It Cm load Ar filename 114Load additional configuration from the specified file. 115.It Cm log brief | verbose 116Disable or enable verbose debug logging. 117.It Cm pause Ar id 118Pause a VM with the specified 119.Ar id . 120.It Cm receive Ar name 121Receive a VM from standard input and start it with the specified 122.Ar name . 123.It Cm reload 124Remove all stopped VMs and reload the configuration from the default 125configuration file. 126VMs that are currently running will not have their configuration reloaded. 127To reload configurations for currently running VMs, stop those VMs before 128issuing the reload command. 129.It Cm reset Op Cm all | switches | vms 130Reset the running state, 131reset 132.Cm switches , 133or reset and terminate all 134.Cm vms . 135.It Cm send Ar id 136Send a VM with the specified 137.Ar id 138to standard output and terminate it. 139The VM is paused during send processing. 140Data sent to standard output contains the VM parameters and its memory, 141not the disk image. 142.Pp 143In order to move a VM from one host to another, disk files must be 144synced between the send and the receive processes and must be located 145under the same path. 146.It Cm show Oo Fl r Oc Op Ar id 147An alias for the 148.Cm status 149command. 150.It Xo Cm start 151.Op Fl cL 152.Bk -words 153.Op Fl B Ar device 154.Op Fl b Ar path 155.Op Fl d Ar disk 156.Op Fl i Ar count 157.Op Fl m Ar size 158.Op Fl n Ar switch 159.Op Fl r Ar path 160.Op Fl t Ar name 161.Ar id | name 162.Ek 163.Xc 164Start a new VM 165.Ar name 166with the specified parameters. 167An existing VM may be started by referencing its 168.Ar id . 169.Bl -tag -width "-I parent" 170.It Fl B Ar device 171Force system to boot from the specified device for this boot. 172.Ar device 173can be set to: 174.Pp 175.Bl -tag -width "cdrom" -compact 176.It Ar cdrom 177Boot the CD-ROM image. 178.It Ar disk 179Boot from disk. 180.It Ar net 181Perform a PXE boot using the first network interface. 182.El 183.Pp 184Currently 185.Ar net 186is only supported when booting a kernel using the 187.Fl b 188flag while 189.Ar disk 190and 191.Ar cdrom 192only work with VMs booted using BIOS. 193.It Fl b Ar path 194Boot the VM with the specified 195.Ox 196kernel or custom BIOS image. 197If not specified, the default is to boot using the BIOS image in 198.Pa /etc/firmware/vmm-bios . 199If the VM is an existing VM, use the provided image for only the next boot. 200.It Fl c 201Automatically connect to the VM console. 202.It Fl d Ar disk 203Use a disk image at the specified 204.Ar disk 205path (may be specified multiple times to add multiple disk images). 206.It Fl i Ar count 207Number of network interfaces to add to the VM. 208.It Fl L 209Add a local network interface. 210.Xr vmd 8 211will auto-generate an IPv4 subnet for the interface, 212configure a gateway address on the VM host side, 213and run a simple DHCP/BOOTP server for the VM. 214See 215.Sx LOCAL INTERFACES 216below for more information on how addresses are calculated and assigned when 217using the 218.Fl L 219option. 220.It Fl m Ar size 221Memory 222.Ar size 223of the VM, rounded to megabytes. 224The default is 512M. 225The maximum amount of memory assignable to a VM is governed by the datasize 226parameter for the vmd user in 227.Pa /etc/login.conf . 228.It Fl n Ar switch 229Add a network interface that is attached to the specified virtual 230.Ar switch . 231See the SWITCH CONFIGURATION section in 232.Xr vm.conf 5 233for more information. 234.It Fl r Ar path 235ISO image file for virtual CD-ROM. 236This image file will be available in the 237selected VM as a SCSI CD-ROM device attached to a virtio SCSI adapter 238(e.g.\& 239.Xr vioscsi 4 ) . 240.It Fl t Ar name 241Use an existing VM with the specified 242.Ar name 243as a template to create a new VM instance. 244The instance will inherit settings from the parent VM, 245except for exclusive options such as disk, interface lladdr, and 246interface names. 247.El 248.It Cm status Oo Fl r Oc Op Ar id 249List VMs running on the host, optionally listing just the selected VM 250.Ar id . 251If the 252.Fl r 253flag is present, the output will only contain running VMs. 254.It Cm stop Oo Fl fw Oc Oo Fl a | Ar id Oc 255Stop (terminate) a VM defined by the specified VM 256.Ar id 257or all running VMs 258.Pq Fl a . 259By default, 260a graceful shutdown will be attempted if the VM supports the 261.Xr vmmci 4 262device. 263.Pp 264The following options can be specified when stopping a VM: 265.Bl -tag -width "-w" 266.It Fl f 267Forcefully stop the VM without attempting a graceful shutdown. 268.It Fl w 269Wait until the VM has been terminated. 270.El 271.It Cm unpause Ar id 272Unpause (resume from a paused state) a VM with the specified 273.Ar id . 274.It Cm wait Ar id 275Wait until the specified VM has stopped. 276.El 277.Pp 278If the 279.Fl i , 280.Fl L , 281or 282.Fl n 283options are specified during VM startup, a corresponding number 284of host-side 285.Xr tap 4 286interfaces will be allocated and mapped to the 287.Xr vio 4 288interfaces inside the guest VM. 289This tap/vio interface mapping 290allows guest network traffic to be manipulated by the host. 291Any valid host-side interface configuration may be performed on these 292tap interfaces, such as bridging (via 293.Xr veb 4 ) , 294or using 295.Xr pf 4 296nat-to rules to create private or host-side NATed networks, as desired. 297For each 298.Xr tap 4 299network interface on the host, 300.Xr vmd 8 301will set the interface's description to allow easy identification of 302the corresponding VM by ID, interface number, and name: 303.Bd -literal -offset indent 304# ifconfig tap0 305tap0: flags=8842<BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 306 lladdr fe:e1:ba:d8:50:d1 307 description: vm1-if0-myvm 308 index 15 priority 0 llprio 3 309 groups: tap 310 status: active 311.Ed 312.Sh LOCAL INTERFACES 313Local interfaces can be used to easily configure VM networking without 314needing to manually assign network addresses. 315A local interface is added 316to a VM using the -L option to the 'vmctl start' command and results in the 317addition of a 318.Xr vio 4 319interface inside the VM and a corresponding 320.Xr tap 4 321interface on the host. 322When using local interfaces, 323.Xr vmd 8 324will provide DHCP services to the guest VM and offer addresses selected 325from the 100.64.0.0/10 IPv4 range. 326From within the 100.64.0.0/10 327range, 328.Xr vmd 8 329allocates a pair of addresses for the guest-side 330.Xr vio 4 331and host-side 332.Xr tap 4 333interfaces as follows: 334.Pp 335For the first local interface: 336.Bl -bullet -compact 337.It 338The host (tapX) address is assigned 100.64.n.2, 339where 'n' is the numeric VM ID visible in the 'vmctl status' command 340.It 341The guest (vio0) address is assigned 100.64.n.3 342.El 343.Pp 344For the second and subsequent local interface(s): 345.Bl -bullet -compact 346.It 347The second local interface uses 100.64.n.4 and 100.64.n.5 for the 348host (tapX) and guest (vio1) interfaces, respectively. 349.It 350Subsequent local interfaces are numbered similarly, continuing with 100.64.n.6 351and 100.64.n.7, etc 352.El 353.Pp 354Multiple -L options can be provided to the 'vmctl start' command, if more than 355one interface is desired. 356Local interfaces are assigned to the VM before 357any other interfaces specified with the -i option (thus, local interfaces, 358if requested, are numbered starting at vio0 inside the guest VM). 359.Pp 360If NAT is desired, the 361.Va net.inet.ip.forwarding 362.Xr sysctl 8 363must also be set to 1. 364.Pp 365When using local interfaces, the DHCP configuration offered to the guest VM 366specifies the address of the corresponding host 367.Xr tap 4 368interface as both the default route and the (sole) nameserver. 369Guest VM traffic can optionally be NATed through the host 370with an entry in the host machine's 371.Pa /etc/pf.conf 372similar to the following: 373.Bd -literal -offset indent 374pass out on egress from 100.64.0.0/10 to any nat-to (egress) 375.Ed 376.Pp 377If desired, DNS queries originating from guest VMs can be redirected to a 378different DNS server with an entry in the host machine's 379.Pa /etc/pf.conf 380similar to the following: 381.Bd -literal -offset indent 382pass in proto { udp tcp } from 100.64.0.0/10 to any port domain \e 383 rdr-to $dns_server port domain 384.Ed 385.Sh FILES 386.Bl -tag -width "/etc/var/run/vmd.sockXX" -compact 387.It Pa /etc/vm.conf 388Default configuration file. 389.It Pa /var/run/vmd.sock 390.Ux Ns -domain 391socket used for communication with 392.Xr vmd 8 . 393.El 394.Sh EXIT STATUS 395.Ex -std vmctl 396.Nm 397may fail due to one of the following reasons: 398.Pp 399.Bl -bullet -compact 400.It 401The VMM subsystem could not be enabled or disabled as requested. 402.It 403A requested VM-based operation could not be completed. 404.El 405.Sh EXAMPLES 406Create a 4.5 Gigabyte disk image, disk.img: 407.Bd -literal -offset indent 408$ vmctl create -s 4.5G disk.img 409.Ed 410.Pp 411Convert a disk image from the 412.Sq raw 413format to 414.Sq qcow2 : 415.Bd -literal -offset indent 416$ vmctl create -i disk.img disk.qcow2 417.Ed 418.Pp 419Create a new VM with 1GB memory, one network interface, one disk image 420('disk.img') and boot from kernel '/bsd': 421.Bd -literal -offset indent 422# vmctl start -m 1G -i 1 -b /bsd -d disk.img "myvm" 423.Ed 424.Pp 425Start a new VM instance with the name 'myvm' from a pre-configured 426VM 'openbsd.4G': 427.Bd -literal -offset indent 428# vmctl start -t "openbsd.4G" -d mydisk.img "myvm" 429.Ed 430.Pp 431Terminate VM number 1: 432.Bd -literal -offset indent 433# vmctl stop 1 434.Ed 435.Sh SEE ALSO 436.Xr pf 4 , 437.Xr tap 4 , 438.Xr veb 4 , 439.Xr vio 4 , 440.Xr vmm 4 , 441.Xr vm.conf 5 , 442.Xr rc.conf 8 , 443.Xr sysctl 8 , 444.Xr vmd 8 445.Sh HISTORY 446The 447.Nm 448command first appeared in 449.Ox 5.9 . 450.Sh AUTHORS 451.An -nosplit 452.An Mike Larkin Aq Mt mlarkin@openbsd.org 453and 454.An Reyk Floeter Aq Mt reyk@openbsd.org . 455