From: stsp Date: Sat, 23 Aug 2014 10:34:18 +0000 (+0000) Subject: Enhance the ldomctl(8) man page. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=52046a90b5563a15ef8fe7f995c4bbfc0d293585;p=openbsd Enhance the ldomctl(8) man page. Describe all available commands, document the init-system file format, and add examples guiding users through the process of setting up guest domains based on http://undeadly.org/cgi?action=article&sid=20121214153413 input and ok jasper jmc schwarze --- diff --git a/usr.sbin/ldomctl/ldomctl.8 b/usr.sbin/ldomctl/ldomctl.8 index 69396a1d516..5ae2b771f19 100644 --- a/usr.sbin/ldomctl/ldomctl.8 +++ b/usr.sbin/ldomctl/ldomctl.8 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ldomctl.8,v 1.6 2013/07/16 11:13:33 schwarze Exp $ +.\" $OpenBSD: ldomctl.8,v 1.7 2014/08/23 10:34:18 stsp Exp $ .\" .\" Copyright (c) 2012 Mark Kettenis .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 16 2013 $ +.Dd $Mdocdate: August 23 2014 $ .Dt LDOMCTL 8 sparc64 .Os .Sh NAME @@ -28,29 +28,195 @@ The .Nm program is used to manage logical domains on sun4v systems. -It can be used to start and stop guest domains and to display information -about domains running on the system. +It can be used to assign resources to the primary and guest domains, +start and stop guest domains from the primary domain, and to display +information about domains running on the system. .Pp The following commands are available: .Bl -tag -width Ds -.It Cm start Ar domain -Start a domain. -.It Cm stop Ar domain -Stop a domain. +.It Cm delete Ar configuration +Delete the specified configuration from non-volatile storage. +.It Cm download Ar directory +Save a logical domain configuration to non-volatile storage on the +service processor. +The configuration will take effect after the primary domain is rebooted. +The name of the configuration is taken from the name of the +.Ar directory +which must contain files created with the +.Cm init-system +command. +The download is aborted if a configuration with the same name already exists. +.It Cm dump Ar configuration +Dump the specified configuration from non-volatile storage into the current +working directory. +.It Cm init-system Ar file +Generates files describing a logical domain configuration. +The generated files are written to the current working directory. +The provided +.Ar file +describes resources assigned to logical domains in a plain text format +with the following syntax: +.Bl -tag -width Ds +.It Ic domain Ar name Ic \&{ Ar resource ... Ic \&} +Declares a scope for resources assigned to the specified domain. +The scope must be opened and closed with curly braces and contains +one or more of the following keywords, each on a separate line. +A scope with +.Ar name +"primary" configures resources for the primary domain. +If no configuration for the primary domain exists it is assigned +all CPU and memory resources not used by any guest domains. +.It Ic vcpu Ar number +Declares the number of virtual CPUs assigned to a domain. +.It Ic memory Ar number Ns Op Ar unit +Declares the amount of memory assigned to a domain, in bytes. +Optionally, the units 'K', 'M', or 'G', for kilo-, mega-, and gigabytes +can be used. +.It Ic vdisk Ar file +The specified disk image file is used to back a virtual disk of the guest +domain. +A disk image file is created with +.Xr dd 1 . +This keyword can be used multiple times. +.It Ic vnet Op Ic \&{ Ar keyword value ... Ic \&} +Assign a +.Xr vnet 4 +network interface to the guest domain. +This keyword can be used multiple times. +The curly braces are optional and can contain the following keywords: +.Bl -tag -width Ds +.It Ic mac-addr Ar address +Configures the MAC address of the interface. +.It Ic mtu Ar number +Configures the MTU of the interface. +.El +.El +.It Cm list +List configurations stored in non-volatile storage. +Indicate the currently running configuration, +and the configuration which will be used next +(after rebooting the primary domain) if it differs from the currently running one. .It Cm panic Ar domain -Panic a domain. +Panic a guest domain. The exact behaviour of this command depends on the OS running in the domain. For .Ox the default behaviour is to enter .Xr ddb 4 . +.It Cm start Ar domain +Start a guest domain. .It Cm status Op Ar domain Display status information for .Ar domain , or for all domains running on the system. +.It Cm stop Ar domain +Stop a guest domain. .El +.Sh EXAMPLES +A system using factory defaults has a single "factory-default" configuration: +.Bd -literal -offset indent +# ldomctl list +factory-default [current] +.Ed +.Pp +Create a new configuration based on the defaults: +.Bd -literal -offset indent +# mkdir factory-default +# cd factory-default +# ldomctl dump +# cd .. +# cp -R factory-default openbsd +# cd openbsd +.Ed +.Pp +A file describing the desired configuration must be created: +.Bd -literal -offset indent +# cat ldom.conf +domain puffy { + vcpu 12 + memory 4G + vdisk "/home/puffy/vdisk0" + vdisk "/home/puffy/vdisk1" + vnet +} + +domain salmah { + vcpu 8 + memory 2G + vdisk "/home/salmah/vdisk0" + vdisk "/home/salmah/vdisk1" + vnet +} +.Ed +.Pp +Generate a set of configuration files and download to non-volatile storage. +If a configuration with the same name already exists, it must be removed first: +.Bd -literal -offset indent +# ldomctl init-system ldom.conf +# cd .. +# ldomctl delete openbsd +# ldomctl download openbsd +# ldomctl list +factory-default [current] +openbsd [next] +.Ed +.Pp +Create a virtual disk image for each guest domain: +.Bd -literal -offset indent +# dd if=/dev/zero of=/home/puffy/vdisk0 bs=1m count=8192 +# dd if=/dev/zero of=/home/salmah/vdisk0 bs=1m count=8192 +.Ed +.Pp +The minirootfs install media can be used to boot guest domains: +.Bd -literal -offset indent +# cp miniroot56.fs /home/puffy/vdisk1 +# cp miniroot56.fs /home/salmah/vdisk1 +.Ed +.Pp +Enable +.Xr ldomd 8 +by adding the following +to +.Pa /etc/rc.conf.local : +.Pp +.Dl ldomd_flags= +.Pp +Halt the primary domain and reset the machine from ALOM: +.Bd -literal -offset indent +# halt +sc> reset -c +.Ed +.Pp +The machine will now reset and boot into the new configuration. +The primary domain should have less CPUs and memory, since they +are now assigned to the guest domains: +.Bd -literal -offset indent +# ldomctl status +primary running OpenBSD running 1% +puffy running OpenBoot Primary Boot Loader 8% +salmah running OpenBoot Primary Boot Loader 12% +.Ed +.Pp +Configure the +.Xr vnet 4 +interfaces for the guest domains. +This example bridges guest domains into the physical network: +.Bd -literal -offset indent +# ifconfig vnet0 -inet6 up +# ifconfig vnet1 -inet6 up +# ifconfig bridge0 create +# ifconfig bridge0 add em0 add vnet0 add vnet1 up +.Ed +.Pp +Access the console of the first domain and boot it: +.Bd -literal -offset indent +# cu -l ttyV0 +ok boot disk1 +.Ed .Sh SEE ALSO +.Xr dd 1 , .Xr ddb 4 , +.Xr vnet 4 , .Xr ldomd 8 .Sh HISTORY The