-.\" $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 <kettenis@openbsd.org>
.\"
.\" 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
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
projects / openbsd / commitdiff