1.\" $OpenBSD: ldomctl.8,v 1.8 2014/09/29 10:53:53 stsp Exp $ 2.\" 3.\" Copyright (c) 2012 Mark Kettenis <kettenis@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 29 2014 $ 18.Dt LDOMCTL 8 sparc64 19.Os 20.Sh NAME 21.Nm ldomctl 22.Nd Logical Domain management interface 23.Sh SYNOPSIS 24.Nm ldomctl 25.Ar command 26.Op Ar argument ... 27.Sh DESCRIPTION 28The 29.Nm 30program is used to manage logical domains on sun4v systems. 31It can be used to assign resources to the primary and guest domains, 32start and stop guest domains from the primary domain, and to display 33information about domains running on the system. 34.Pp 35The following commands are available: 36.Bl -tag -width Ds 37.It Cm delete Ar configuration 38Delete the specified configuration from non-volatile storage. 39.It Cm download Ar directory 40Save a logical domain configuration to non-volatile storage on the 41service processor. 42The configuration will take effect after the primary domain is rebooted. 43The name of the configuration is taken from the name of the 44.Ar directory 45which must contain files created with the 46.Cm init-system 47command. 48The download is aborted if a configuration with the same name already exists. 49.It Cm dump Ar configuration 50Dump the specified configuration from non-volatile storage into the current 51working directory. 52.It Cm init-system Ar file 53Generates files describing a logical domain configuration. 54The generated files are written to the current working directory. 55The provided 56.Ar file 57describes resources assigned to logical domains in a plain text format 58with the following syntax: 59.Bl -tag -width Ds 60.It Ic domain Ar name Ic \&{ Ar resource ... Ic \&} 61Declares a scope for resources assigned to the specified domain. 62The scope must be opened and closed with curly braces and contains 63one or more of the following keywords, each on a separate line. 64A scope with 65.Ar name 66"primary" configures resources for the primary domain. 67If no configuration for the primary domain exists it is assigned 68all CPU and memory resources not used by any guest domains. 69.It Ic vcpu Ar number 70Declares the number of virtual CPUs assigned to a domain. 71.It Ic memory Ar number Ns Op Ar unit 72Declares the amount of memory assigned to a domain, in bytes. 73Optionally, the units 'K', 'M', or 'G', for kilo-, mega-, and gigabytes 74can be used. 75.It Ic vdisk Ar file 76The specified file is used to back a virtual disk of the guest 77domain. 78.Ar file 79can be a block device node or a disk image file created with 80.Xr dd 1 . 81This keyword can be used multiple times. 82.It Ic vnet Op Ic \&{ Ar keyword value ... Ic \&} 83Assign a 84.Xr vnet 4 85network interface to the guest domain. 86This keyword can be used multiple times. 87The curly braces are optional and can contain the following keywords: 88.Bl -tag -width Ds 89.It Ic mac-addr Ar address 90Configures the MAC address of the interface. 91.It Ic mtu Ar number 92Configures the MTU of the interface. 93.El 94.El 95.It Cm list 96List configurations stored in non-volatile storage. 97Indicate the currently running configuration, 98and the configuration which will be used next 99(after rebooting the primary domain) if it differs from the currently running one. 100.It Cm panic Ar domain 101Panic a guest domain. 102The exact behaviour of this command depends on the OS running in the domain. 103For 104.Ox 105the default behaviour is to enter 106.Xr ddb 4 . 107.It Cm start Ar domain 108Start a guest domain. 109.It Cm status Op Ar domain 110Display status information for 111.Ar domain , 112or for all domains running on the system. 113.It Cm stop Ar domain 114Stop a guest domain. 115.El 116.Sh EXAMPLES 117A system using factory defaults has a single "factory-default" configuration: 118.Bd -literal -offset indent 119# ldomctl list 120factory-default [current] 121.Ed 122.Pp 123Create a new configuration based on the defaults: 124.Bd -literal -offset indent 125# mkdir factory-default 126# cd factory-default 127# ldomctl dump 128# cd .. 129# cp -R factory-default openbsd 130# cd openbsd 131.Ed 132.Pp 133A file describing the desired configuration must be created: 134.Bd -literal -offset indent 135# cat ldom.conf 136domain puffy { 137 vcpu 12 138 memory 4G 139 vdisk "/home/puffy/vdisk0" 140 vdisk "/home/puffy/vdisk1" 141 vnet 142} 143 144domain salmah { 145 vcpu 8 146 memory 2G 147 vdisk "/home/salmah/vdisk0" 148 vdisk "/home/salmah/vdisk1" 149 vnet 150} 151.Ed 152.Pp 153Generate a set of configuration files and download to non-volatile storage. 154If a configuration with the same name already exists, it must be removed first: 155.Bd -literal -offset indent 156# ldomctl init-system ldom.conf 157# cd .. 158# ldomctl delete openbsd 159# ldomctl download openbsd 160# ldomctl list 161factory-default [current] 162openbsd [next] 163.Ed 164.Pp 165Create a virtual disk image for each guest domain: 166.Bd -literal -offset indent 167# dd if=/dev/zero of=/home/puffy/vdisk0 bs=1m count=8192 168# dd if=/dev/zero of=/home/salmah/vdisk0 bs=1m count=8192 169.Ed 170.Pp 171The minirootfs install media can be used to boot guest domains: 172.Bd -literal -offset indent 173# cp miniroot56.fs /home/puffy/vdisk1 174# cp miniroot56.fs /home/salmah/vdisk1 175.Ed 176.Pp 177Enable 178.Xr ldomd 8 179by adding the following 180to 181.Pa /etc/rc.conf.local : 182.Pp 183.Dl ldomd_flags= 184.Pp 185Halt the primary domain and reset the machine from ALOM: 186.Bd -literal -offset indent 187# halt 188sc> reset -c 189.Ed 190.Pp 191The machine will now reset and boot into the new configuration. 192The primary domain should have less CPUs and memory, since they 193are now assigned to the guest domains: 194.Bd -literal -offset indent 195# ldomctl status 196primary running OpenBSD running 1% 197puffy running OpenBoot Primary Boot Loader 8% 198salmah running OpenBoot Primary Boot Loader 12% 199.Ed 200.Pp 201Configure the 202.Xr vnet 4 203interfaces for the guest domains. 204This example bridges guest domains into the physical network: 205.Bd -literal -offset indent 206# ifconfig vnet0 -inet6 up 207# ifconfig vnet1 -inet6 up 208# ifconfig bridge0 create 209# ifconfig bridge0 add em0 add vnet0 add vnet1 up 210.Ed 211.Pp 212Access the console of the first domain and boot it: 213.Bd -literal -offset indent 214# cu -l ttyV0 215ok boot disk1 216.Ed 217.Sh SEE ALSO 218.Xr dd 1 , 219.Xr ddb 4 , 220.Xr vnet 4 , 221.Xr ldomd 8 222.Sh HISTORY 223The 224.Nm 225program first appeared in 226.Ox 5.3 . 227.Sh AUTHORS 228The 229.Nm 230program was written by 231.An Mark Kettenis Aq Mt kettenis@openbsd.org . 232