1.\" $OpenBSD: vm.conf.5,v 1.63 2023/05/12 00:06:53 kn Exp $ 2.\" 3.\" Copyright (c) 2015 Mike Larkin <mlarkin@openbsd.org> 4.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: May 12 2023 $ 19.Dt VM.CONF 5 20.Os 21.Sh NAME 22.Nm vm.conf 23.Nd virtual machine configuration 24.Sh DESCRIPTION 25.Nm 26is the configuration file to configure the virtual machine monitor 27(VMM) subsystem. 28A VMM manages virtual machines (VMs) on a host. 29The VMM subsystem is responsible for creating, destroying, and 30executing VMs. 31.Pp 32.Nm 33is divided into the following main sections: 34.Bl -tag -width xxxx 35.It Sy Macros 36User-defined variables may be defined and used later, simplifying the 37configuration file. 38.It Sy Global Configuration 39Global settings for 40.Xr vmd 8 . 41.It Sy VM Configuration 42Configuration for each individual virtual machine. 43.It Sy Switch Configuration 44Configuration for virtual switches. 45.El 46.Pp 47Within the sections, the 48.Ar bytes 49argument can be specified with a human-readable scale, 50using the format described in 51.Xr scan_scaled 3 . 52.Pp 53The current line can be extended over multiple lines using a backslash 54.Pq Sq \e . 55Comments can be put anywhere in the file using a hash mark 56.Pq Sq # , 57and extend to the end of the current line. 58Care should be taken when commenting out multi-line text: 59the comment is effective until the end of the entire block. 60.Pp 61Argument names not beginning with a letter, digit, underscore, or slash 62must be quoted. 63.Pp 64Additional configuration files can be included with the 65.Ic include 66keyword, for example: 67.Bd -literal -offset indent 68include "/etc/vm1.example.com.conf" 69.Ed 70.Sh MACROS 71Macros can be defined that will later be expanded in context. 72Macro names must start with a letter, digit, or underscore, 73and may contain any of those characters. 74Macro names may not be reserved words (for example, 75.Ic vm , 76.Ic memory , 77or 78.Ic disk ) . 79Macros are not expanded inside quotes. 80.Pp 81For example: 82.Bd -literal -offset indent 83ramdisk="/bsd.rd" 84vm "vm1.example.com" { 85 memory 512M 86 boot $ramdisk 87} 88.Ed 89.Sh GLOBAL CONFIGURATION 90The following setting can be configured globally: 91.Bl -tag -width Ds 92.It Ic agentx Oo Ic context Ar context Oc Op Ic path Ar path 93Export vm metrics via an AgentX compatible 94.Pq snmp 95daemon by connecting to 96.Ar path . 97Metrics can be found under the vmMIB subtree 98.Pq mib-2.236 . 99If 100.Ar path 101is omitted it will default to 102.Pa /var/agentx/master . 103.Ar context 104is the SNMPv3 context and can usually be omitted. 105.It Ic local prefix Ar address Ns / Ns Ar prefix 106Set the network prefix that is used to allocate subnets for 107local interfaces, see 108.Ic local interface 109in the 110.Sx VM CONFIGURATION 111section below. 112The default is 100.64.0.0/10. 113.It Ic local inet6 Op Ic prefix Ar address Ns / Ns Ar prefix 114Enable IPv6 on local interfaces and allocate routable subnets. 115If the prefix is not specified, 116a random prefix from the 117.Dq unique local 118network range fd00::/8 will be generated on startup. 119The specified prefix length must be /64 or smaller. 120.It Ic socket owner Ar user : Ns Ar group 121Set the control socket owner to the specified 122.Ar user 123and 124.Ar group . 125Users with access to the control socket will be allowed to use 126.Xr vmctl 8 127for restricted access to 128.Xr vmd 8 . 129If only 130.Ar user 131is given, 132only the user is set. 133If only 134.Pf : Ar group 135is given, 136only the group is set. 137The default is root:wheel. 138.It Ic staggered start parallel Ar parallelism Ic delay Ar seconds 139Start all configured VMs in a staggered fashion with 140.Ar parallelism 141instances in parallel every 142.Ar delay 143seconds. 144Defaults to 145.Ar parallelism 146equal to number of online CPUs and a 147.Ar delay 148of 30 seconds. 149.El 150.Sh VM CONFIGURATION 151Each 152.Ic vm 153section starts with a declaration of the virtual machine 154.Ar name : 155.Bl -tag -width Ds 156.It Ic vm Ar name Brq ... 157The 158.Ar name 159can only consist of alphanumeric characters, as well as '.', '-', and '_', 160and must start with a letter. 161Typically this is a hostname. 162.El 163.Pp 164Followed by a block of parameters that is enclosed in curly brackets: 165.Bl -tag -width Ds 166.It Ic allow instance Brq ... 167Set the permissions to create VM instances. 168See 169.Sx VM INSTANCES . 170.It Ic boot Ar path 171Kernel or BIOS image to load when booting the VM. 172If not specified, the default is to boot using the BIOS image in 173.Pa /etc/firmware/vmm-bios . 174.It Ic boot device Ar device 175Force VM to boot from 176.Ar device . 177Valid values are: 178.Bl -tag -width "cdrom" 179.It Cm cdrom 180Boot the ISO image file specified using the 181.Ic cdrom 182parameter. 183.It Cm disk 184Boot from the disk image file specified using the 185.Ic disk 186parameter. 187.It Cm net 188Boot the kernel specified using the 189.Ic boot 190parameter as if the VM was network booted. 191In addition, the DHCP lease will advertise 192.Dq auto_install 193in the bootfile option making it suitable for use with 194.Xr autoinstall 8 . 195Note, this is not to be confused with 196.Xr pxeboot 8 197but rather a simulated network boot. 198.El 199.Pp 200Currently 201.Cm disk 202and 203.Cm cdrom 204only work with VMs booted using BIOS. 205.It Ic cdrom Ar path 206ISO image file. 207.It Ic enable 208Automatically start the VM. 209This is the default if neither 210.Ic enable 211nor 212.Ic disable 213is specified. 214.It Ic disable 215Do not start this VM. 216.It Ic disk Ar path Op Ic format Ar fmt 217Disk image file (may be specified multiple times to add multiple disk images). 218The format may be specified as either 219.Cm qcow2 220(a sparse file format which reduces storage) or 221.Cm raw . 222If left unspecified, the format defaults to 223.Cm raw 224if it cannot be derived automatically. 225.It Oo Ic local Oc Ic interface Oo Ar name Oc Op Brq ... 226Network interface to add to the VM. 227The optional 228.Ar name 229can be either 230.Cm tap 231to select the next available 232.Xr tap 4 233interface on the VM host side (the default) or 234.Cm tap Ns Ar N 235to select a specific one. 236.Pp 237Valid options are: 238.Bl -tag -width Ds 239.It Ic group Ar group-name 240Assign the interface to a specific interface 241.Dq group . 242For example, this can be used to write 243.Xr pf.conf 5 244rules for several VM interfaces in the same group. 245The 246.Ar group-name 247must not be longer than 15 characters or end with a digit, 248as described in 249.Xr ifconfig 8 . 250.It Oo Ic locked Oc Ic lladdr Op Ar etheraddr 251Change the link layer address (MAC address) of the interface on the 252VM guest side. 253If not specified, a randomized address will be assigned by 254.Xr vmd 8 . 255If the 256.Ic locked 257keyword is specified, 258.Xr vmd 8 259will drop packets from the VM with altered source addresses. 260.It Cm rdomain Ar rdomainid 261Attach the interface to the routing domain with the specified 262.Ar rdomainid . 263If attaching to a switch that also has an 264.Ar rdomainid 265set, the 266.Ar rdomainid 267configured for the interface takes precedence. 268.It Ic switch Ar name 269Set the virtual switch by 270.Ar name . 271See the 272.Sx SWITCH CONFIGURATION 273section about virtual switches. 274This option is ignored if a switch with a matching name cannot be found. 275.It Ic up 276Start the interface forwarding packets. 277This is the default. 278.It Ic down 279Stop the interface from forwarding packets. 280.El 281.Pp 282A 283.Ic local 284interface will auto-generate an IPv4 subnet for the interface, 285configure a gateway address on the VM host side, 286and run a simple DHCP/BOOTP server for the VM. 287This option can be used for layer 3 mode without configuring a switch. 288.Pp 289If the global 290.Ic local inet6 291option is enabled, a routable IPv6 gateway address will be generated 292on the host side. 293Unlike the IPv4 option, 294.Xr vmd 8 295does not respond to DHCPv6 or router solicitation messages itself. 296Use 297.Xr rad 8 298listening on the interface group, e.g.\& 299.Ic interface Cm tap 300for auto-configuring the VMs accordingly. 301.It Ic interfaces Ar count 302Optional minimum number of network interfaces to add to the VM. 303If the 304.Ar count 305is greater than the number of 306.Ic interface 307statements, additional default interfaces will be added. 308.It Ic memory Ar bytes 309Memory size of the VM, in bytes, rounded to megabytes. 310The default is 512M. 311.It Ic owner Ar user : Ns Ar group 312Set the owner of the VM to the specified 313.Ar user 314and 315.Ar group . 316The owner will be allowed to start or stop the VM, pause or unpause the VM, 317and open the VM's console. 318If only 319.Ar user 320is given, 321only the user is set. 322If only 323.Pf : Ar group 324is given, 325only the group is set. 326.El 327.Sh VM INSTANCES 328It is possible to use configured or running VMs as a template for 329additional instances of the VM. 330An instance is just like a normal 331.Ic vm 332and is configured with the following declaration of the virtual machine 333.Ar name : 334.Bl -tag -width Ds 335.It Ic vm Ar parent Ic instance Ar name Brq ... 336A virtual machine can be created as an instance of any other configured VM. 337.El 338.Pp 339The new instance will inherit settings from the VM 340.Ar parent , 341except for exclusive options such as 342.Ic disk , 343.Ic interface lladdr , 344or 345.Ic interface Ar name . 346The configuration options are identical to the 347.Sx VM CONFIGURATION , 348but restricted to the allowed instance options. 349.Pp 350The allowed instance options are configured in the 351.Ar parent 352VM: 353.Bl -tag -width Ds 354.It Ic allow instance Brq ... 355Allow users to use this VM as a template for VM instances. 356By default, the root user can always create instances without 357restrictions and users or non-root owners cannot create instances. 358An instance will inherit the configuration from the VM and the user, 359if permitted, will be allowed to configure individual VM options. 360.El 361.Pp 362Valid options are: 363.Bl -tag -width Ds 364.It Ic boot 365Allow user to configure the kernel or BIOS image. 366The user needs read access to the image. 367.It Ic cdrom 368Allow user to configure the ISO file. 369The user needs read access to the file. 370.It Ic disk 371Allow user to configure the disk images. 372The user needs read and write access to image and instances are not 373allowed to reuse disks from the parent VM. 374.It Ic instance 375Allow user to create additional instances from the instances. 376.It Ic interface 377Allow user to change network interface settings. 378.It Ic memory 379Allow user to configure the memory size. 380.It Ic owner Ar user Ns Op : Ns Ar group 381Allow the specified user or group to create the instances. 382The owner will be allowed to create VM instances, start or stop the 383instances, pause or unpause the instances, and open the instances' 384consoles. 385.It Ic owner Pf : Ar group 386Set the owner to the specified group. 387.El 388.Sh SWITCH CONFIGURATION 389A virtual switch allows VMs to communicate with other network interfaces on the 390host system via either 391.Xr bridge 4 392or 393.Xr veb 4 . 394The network interface for each virtual switch defined in 395.Nm 396is pre-configured using 397.Xr hostname.if 5 398or 399.Xr ifconfig 8 400(see the BRIDGE and VEB sections in 401.Xr ifconfig 8 402accordingly). 403When a VM is started, virtual network interfaces which are assigned to a 404virtual switch have their 405.Xr tap 4 406interface automatically added into the corresponding 407.Xr bridge 4 408or 409.Xr veb 4 410interface underlying the virtual switch. 411.Pp 412Virtual switches can be configured at any point in the configuration file. 413Each 414.Ic switch 415section starts with a declaration of the virtual switch: 416.Bl -tag -width Ds 417.It Ic switch Ar name Brq ... 418This name can be any string, and is typically a network name. 419.El 420.Pp 421Followed by a block of parameters that is enclosed in curly brackets: 422.Bl -tag -width Ds 423.It Ic enable 424Automatically configure the switch. 425This is the default if neither 426.Ic enable 427nor 428.Ic disable 429is specified. 430.It Ic locked lladdr 431If this option is specified, 432.Xr vmd 8 433will drop packets with altered source addresses that do not match the 434link layer addresses (MAC addresses) of the VM interfaces in this switch. 435.It Ic disable 436Do not configure this switch. 437.It Ic group Ar group-name 438Assign each interface to a specific interface 439.Dq group . 440For example, this can be used to write 441.Xr pf.conf 5 442rules for several VM interfaces in the same group. 443The 444.Ar group-name 445must not be longer than 15 characters or end with a digit, 446as described in 447.Xr ifconfig 8 . 448.It Ic interface Ar name 449Set the 450.Xr bridge 4 451or 452.Xr veb 4 453network interface of this switch. 454.It Ic rdomain Ar rdomainid 455Set the routing domain of the switch and all of its VM interfaces to 456.Ar rdomainid . 457.It Ic up 458Start the switch forwarding packets. 459This is the default. 460.It Ic down 461Stop the switch from forwarding packets. 462.El 463.Sh FILES 464.Bl -tag -width /etc/examples/vm.conf -compact 465.It Pa /etc/vm.conf 466.It Pa /etc/examples/vm.conf 467.El 468.Sh EXAMPLES 469Create a new VM with 1GB memory, 1 network interface connected to 470.Dq uplink , 471with one disk image 472.Pa /home/joe/vm2-disk.img , 473owned by user 474.Sq joe : 475.Bd -literal -offset indent 476vm "vm2.example.com" { 477 memory 1G 478 disk "/home/joe/vm2-disk.img" 479 interface { switch "uplink" } 480 owner joe 481} 482.Ed 483.Pp 484Create a new VM as an instance from 485.Sq vm2.example.com : 486.Bd -literal -offset indent 487vm "vm2.example.com" instance "vm3.example.com" { 488 disk "/home/joe/vm3-disk.img" 489} 490.Ed 491.Pp 492Create the switch "uplink" with an additional physical network interface: 493.Bd -literal -offset indent 494switch "uplink" { 495 interface bridge0 496} 497.Ed 498.Sh SEE ALSO 499.Xr vmm 4 , 500.Xr MAKEDEV 8 , 501.Xr vmctl 8 , 502.Xr vmd 8 503.Sh HISTORY 504The 505.Nm 506file format first appeared in 507.Ox 5.9 . 508.Sh AUTHORS 509.An -nosplit 510.An Mike Larkin Aq Mt mlarkin@openbsd.org 511and 512.An Reyk Floeter Aq Mt reyk@openbsd.org . 513.Sh CAVEATS 514Each guest requires one 515.Xr tap 4 516device per assigned interface and one 517.Xr pty 4 518device. 519Administrators may need to create additional devices using 520.Xr MAKEDEV 8 . 521