1.\" $OpenBSD: ldomctl.8,v 1.29 2020/05/17 17:04:29 deraadt 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: May 17 2020 $ 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 create-vdisk Fl s Ar size file 38Create a virtual disk image with the specified 39.Ar file 40path and 41.Ar size , 42in bytes. 43.Ar size 44can be specified with a human-readable scale, using the format described in 45.Xr scan_scaled 3 , 46e.g. 512M. 47.It Cm console Ar domain 48Using 49.Xr cu 1 50connect to the console of the guest domain. 51.It Cm delete Ar configuration 52Delete the specified configuration from non-volatile storage. 53.It Cm download Ar directory 54Save a logical domain configuration to non-volatile storage on the 55service processor. 56The name of the configuration is taken from the name of the 57.Ar directory 58which must contain files created with the 59.Cm init-system 60command. 61The download is aborted if a configuration with the same name already exists. 62Depending on the firmware, the new configuration must be activated explicitly 63using the 64.Cm select 65command. 66.It Cm dump 67Dump the current configuration from non-volatile storage into the current 68working directory. 69.It Cm init-system Oo Fl n Oc Ar file 70Generate files in the current working directory for a logical domain 71configuration 72.Ar file 73as described in 74.Xr ldom.conf 5 . 75.Bl -tag -width 3n 76.It Fl n 77Configtest mode. 78Only check the configuration file for validity. 79.El 80.It Cm list 81List configurations stored in non-volatile storage. 82Indicate the currently running configuration, 83and the configuration which will be used next 84(after resetting the machine) if it differs from the currently running one. 85.It Cm list-io 86List available PCIe devices. 87.It Cm panic Oo Fl c Oc Ar domain 88Panic a guest domain. 89The exact behaviour of this command depends on the OS running in the domain. 90For 91.Ox 92the default behaviour is to enter 93.Xr ddb 4 . 94.Bl -tag -width 3n 95.It Fl c 96Automatically connect to the guest console. 97.El 98.It Cm select Ar configuration 99Select the next logical domain configuration to use 100(after resetting the machine). 101.It Cm start Oo Fl c Oc Ar domain 102Start a guest domain. 103.Bl -tag -width 3n 104.It Fl c 105Automatically connect to the guest console. 106.El 107.It Cm status Op Ar domain 108Display status information for 109.Ar domain , 110or for all domains running on the system. 111.It Cm stop Ar domain 112Stop a guest domain. 113.El 114.Sh EXAMPLES 115A system using factory defaults has a single "factory-default" configuration: 116.Bd -literal -offset indent 117# ldomctl list 118factory-default [current] 119.Ed 120.Pp 121Create a new configuration based on the defaults: 122.Bd -literal -offset indent 123# mkdir factory-default 124# cd factory-default 125# ldomctl dump 126# cd .. 127# cp -R factory-default openbsd 128# cd openbsd 129.Ed 130.Pp 131A file describing the desired configuration must be created - see 132.Xr ldom.conf 5 . 133.Pp 134Generate a set of configuration files and download to non-volatile storage. 135If a configuration with the same name already exists, it must be removed first: 136.Bd -literal -offset indent 137# ldomctl init-system ldom.conf 138# cd .. 139# ldomctl delete openbsd 140# ldomctl download openbsd 141# ldomctl list 142factory-default [current] 143openbsd [next] 144.Ed 145.Pp 146Create a virtual disk image for each guest domain: 147.Bd -literal -offset indent 148# ldomctl create-vdisk -s 8G /home/puffy/vdisk0 149# ldomctl create-vdisk -s 8G /home/salmah/vdisk0 150.Ed 151.Pp 152The minirootfs install media can be used to boot guest domains: 153.Bd -literal -offset indent 154# cp miniroot67.img /home/puffy/vdisk1 155# cp miniroot67.img /home/salmah/vdisk1 156.Ed 157.Pp 158To have 159.Nm 160enabled at boot time, use 161.Dq rcctl enable ldomd , 162which sets 163.Pp 164.Dl ldomd_flags=\(dq\(dq 165.Pp 166in 167.Xr rc.conf.local 8 . 168.Pp 169Halt the primary domain and reset the hardware: 170.Bd -literal -offset indent 171# halt 172sc> reset -c # ALOM 173-> reset /SYS # ILOM 174.Ed 175.Pp 176The machine will now reset and boot into the new configuration. 177The primary domain should have less CPUs and memory, since they 178are now assigned to the guest domains: 179.Bd -literal -offset indent 180# ldomctl status 181primary - running OpenBSD running 1% 182puffy ttyV0 running OpenBoot Primary Boot Loader 8% 183salmah ttyV1 running OpenBoot Primary Boot Loader 12% 184.Ed 185.Pp 186Configure the 187.Xr vnet 4 188interfaces for the guest domains. 189This example bridges guest domains into the physical network: 190.Bd -literal -offset indent 191# ifconfig vnet0 up 192# ifconfig vnet1 up 193# ifconfig bridge0 create 194# ifconfig bridge0 add em0 add vnet0 add vnet1 up 195.Ed 196.Pp 197Access the console of the first domain and boot it: 198.Bd -literal -offset indent 199# ldomctl console puffy 200ok boot disk1 201.Ed 202.Sh SEE ALSO 203.Xr dd 1 , 204.Xr ddb 4 , 205.Xr vnet 4 , 206.Xr ldom.conf 5 , 207.Xr ldomd 8 208.Sh HISTORY 209The 210.Nm 211program first appeared in 212.Ox 5.3 . 213.Sh AUTHORS 214The 215.Nm 216program was written by 217.An Mark Kettenis Aq Mt kettenis@openbsd.org . 218