1.\" $OpenBSD: vm.conf.5,v 1.65 2024/09/16 22:30:01 bluhm 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: September 16 2024 $ 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.It Ic sev 327Enables AMD Secure Encrypted Virtualization for guest. 328.Xr vmd 8 329uses 330.Xr psp 4 331to configure the guest for SEV. 332.El 333.Sh VM INSTANCES 334It is possible to use configured or running VMs as a template for 335additional instances of the VM. 336An instance is just like a normal 337.Ic vm 338and is configured with the following declaration of the virtual machine 339.Ar name : 340.Bl -tag -width Ds 341.It Ic vm Ar parent Ic instance Ar name Brq ... 342A virtual machine can be created as an instance of any other configured VM. 343.El 344.Pp 345The new instance will inherit settings from the VM 346.Ar parent , 347except for exclusive options such as 348.Ic disk , 349.Ic interface lladdr , 350or 351.Ic interface Ar name . 352The configuration options are identical to the 353.Sx VM CONFIGURATION , 354but restricted to the allowed instance options. 355.Pp 356The allowed instance options are configured in the 357.Ar parent 358VM: 359.Bl -tag -width Ds 360.It Ic allow instance Brq ... 361Allow users to use this VM as a template for VM instances. 362By default, the root user can always create instances without 363restrictions and users or non-root owners cannot create instances. 364An instance will inherit the configuration from the VM and the user, 365if permitted, will be allowed to configure individual VM options. 366.El 367.Pp 368Valid options are: 369.Bl -tag -width Ds 370.It Ic boot 371Allow user to configure the kernel or BIOS image. 372The user needs read access to the image. 373.It Ic cdrom 374Allow user to configure the ISO file. 375The user needs read access to the file. 376.It Ic disk 377Allow user to configure the disk images. 378The user needs read and write access to image and instances are not 379allowed to reuse disks from the parent VM. 380.It Ic instance 381Allow user to create additional instances from the instances. 382.It Ic interface 383Allow user to change network interface settings. 384.It Ic memory 385Allow user to configure the memory size. 386.It Ic owner Ar user Ns Op : Ns Ar group 387Allow the specified user or group to create the instances. 388The owner will be allowed to create VM instances, start or stop the 389instances, pause or unpause the instances, and open the instances' 390consoles. 391.It Ic owner Pf : Ar group 392Set the owner to the specified group. 393.El 394.Sh SWITCH CONFIGURATION 395A virtual switch allows VMs to communicate with other network interfaces on the 396host system via either 397.Xr bridge 4 398or 399.Xr veb 4 . 400The network interface for each virtual switch defined in 401.Nm 402is pre-configured using 403.Xr hostname.if 5 404or 405.Xr ifconfig 8 406(see the BRIDGE and VEB sections in 407.Xr ifconfig 8 408accordingly). 409When a VM is started, virtual network interfaces which are assigned to a 410virtual switch have their 411.Xr tap 4 412interface automatically added into the corresponding 413.Xr bridge 4 414or 415.Xr veb 4 416interface underlying the virtual switch. 417.Pp 418Virtual switches can be configured at any point in the configuration file. 419Each 420.Ic switch 421section starts with a declaration of the virtual switch: 422.Bl -tag -width Ds 423.It Ic switch Ar name Brq ... 424This name can be any string, and is typically a network name. 425.El 426.Pp 427Followed by a block of parameters that is enclosed in curly brackets: 428.Bl -tag -width Ds 429.It Ic enable 430Automatically configure the switch. 431This is the default if neither 432.Ic enable 433nor 434.Ic disable 435is specified. 436.It Ic locked lladdr 437If this option is specified, 438.Xr vmd 8 439will drop packets with altered source addresses that do not match the 440link layer addresses (MAC addresses) of the VM interfaces in this switch. 441.It Ic disable 442Do not configure this switch. 443.It Ic group Ar group-name 444Assign each interface to a specific interface 445.Dq group . 446For example, this can be used to write 447.Xr pf.conf 5 448rules for several VM interfaces in the same group. 449The 450.Ar group-name 451must not be longer than 15 characters or end with a digit, 452as described in 453.Xr ifconfig 8 . 454.It Ic interface Ar name 455Set the 456.Xr bridge 4 457or 458.Xr veb 4 459network interface of this switch. 460.It Ic rdomain Ar rdomainid 461Set the routing domain of the switch and all of its VM interfaces to 462.Ar rdomainid . 463.It Ic up 464Start the switch forwarding packets. 465This is the default. 466.It Ic down 467Stop the switch from forwarding packets. 468.El 469.Sh FILES 470.Bl -tag -width /etc/examples/vm.conf -compact 471.It Pa /etc/vm.conf 472.It Pa /etc/examples/vm.conf 473.El 474.Sh EXAMPLES 475Create a new VM with 1GB memory, 1 network interface connected to 476.Dq uplink , 477with one disk image 478.Pa /home/joe/vm2-disk.img , 479owned by user 480.Sq joe : 481.Bd -literal -offset indent 482vm "vm2.example.com" { 483 memory 1G 484 disk "/home/joe/vm2-disk.img" 485 interface { switch "uplink" } 486 owner joe 487} 488.Ed 489.Pp 490Create a new VM as an instance from 491.Sq vm2.example.com : 492.Bd -literal -offset indent 493vm "vm2.example.com" instance "vm3.example.com" { 494 disk "/home/joe/vm3-disk.img" 495} 496.Ed 497.Pp 498Create the switch "uplink" with an additional physical network interface: 499.Bd -literal -offset indent 500switch "uplink" { 501 interface bridge0 502} 503.Ed 504.Sh SEE ALSO 505.Xr vmm 4 , 506.Xr MAKEDEV 8 , 507.Xr vmctl 8 , 508.Xr vmd 8 509.Sh HISTORY 510The 511.Nm 512file format first appeared in 513.Ox 5.9 . 514.Sh AUTHORS 515.An -nosplit 516.An Mike Larkin Aq Mt mlarkin@openbsd.org 517and 518.An Reyk Floeter Aq Mt reyk@openbsd.org . 519.Sh CAVEATS 520Each guest requires one 521.Xr tap 4 522device per assigned interface and one 523.Xr pty 4 524device. 525Administrators may need to create additional devices using 526.Xr MAKEDEV 8 . 527