Hi Stefan, Stefan Sperling wrote on Fri, Aug 08, 2014 at 08:56:30PM +0200:
> I can never remember the exact steps of configuring logical > domains on sparc64 without referencing the undeadly article at > http://undeadly.org/cgi?action=article&sid=20121214153413 > > It would be nice if this information was in the man page. > The diff below fills in missing bits of documentation for ldomctl > and its config syntax, That should certainly go in, the manual is clearly incomplete. I cannot judge whether the content of your text is accurate, though. > and also adds an EXAMPLES section based on the above article. Apparently, there is quite some work to so, so having an EXAMPLES section in this style makes sense to me, too. > There is more work to be done here, e.g. usage() of ldomctl is > lacking many subcommands. > > I realise the EXAMPLES section might not be a very good place for > tutorial-style walkthroughs. But I would find it convenient to have > a single place to look this up. If the FAQ would be a much better > place for the examples I will a diff for that instead. IMHO, the FAQ is ideal for questions that people ask *without* knowing which tool(s) they are going to use. Information pertaining to one specific tool does have a place in the manual, i think. In any style, your mdoc(7) usage is ok; well, some nits inline... Yours, Ingo > Index: ldomctl.8 > =================================================================== > RCS file: /cvs/src/usr.sbin/ldomctl/ldomctl.8,v > retrieving revision 1.6 > diff -u -p -r1.6 ldomctl.8 > --- ldomctl.8 16 Jul 2013 11:13:33 -0000 1.6 > +++ ldomctl.8 8 Aug 2014 18:48:16 -0000 > @@ -28,17 +28,79 @@ > 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 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 { ... } That should probably be .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 brackets and contains I'd prefer "curly braces". > +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[unit] .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 { ... } Probably .It Ic vnet Op Ic \&{ Ar keyword value ... Ic \&} or something similar. > +Assign a > +.Xr vnet 4 > +network interface to the guest domain. > +This keyword can be used multiple times. > +The curly brackets are optional and can contain the following keywords: braces > +.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 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 delete Ar configuration > +Delete the specified configuration from non-volatile storage. > +.It Cm dump Ar configuration > +Dump the specified configuration from non-volatile storage into the current > +working directory. > +.It Cm list > +List configurations stored in non-volatile storage. Indicate the currently New sentence, new line. > +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 start Ar domain > -Start a domain. > +Start a guest domain. > .It Cm stop Ar domain > -Stop a domain. > +Stop a guest domain. > .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 > @@ -49,9 +111,118 @@ Display status information for > .Ar domain , > or for all domains running on the system. > .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 .. > +# mkdir openbsd > +# cp factory-default/* openbsd/ These two commands can be simplified to: # 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 <<EOF > +domain puffy { > + vcpu 12 In .Bd -literal, you can use tabs if you want to. > + 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 > +} > +EOF > +.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 line > +.Bd -literal -offset indent > +ldomd_flags= > +.Ed > +.Pp > +to the file > +.Pa /etc/rc.conf.local . There is a blank character at the end of the previous line. Beides, maybe to .Xr rc.conf.local 8 . is better? > +.Pp > +Halt the primary domain and reset the machine from ALOM. > +.Pp You can remove this .Pp, right before non-compact .Bd, it has no effect. > +.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. > +.Pp This .Pp isn't needed, either. > +.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 ldomd 8 > +.Xr ldomd 8 , > +.Xr vnet 4 Wrong order: .Xr dd 1 , .Xr ddb 4 , .Xr vnet 4 , .Xr ldomd 8 > .Sh HISTORY > The > .Nm
