Several clarifications added to man pages

2 files changed, 168 insertions, 173 deletions

diff --git a/man7/ezjail.7 b/man7/ezjail.7
index 8b3b2fb..03f11c5 100644
--- a/man7/ezjail.7
+++ b/man7/ezjail.7
@@ -352,46 +352,50 @@ librairies, you may want to remove the old library versions. It is
 often a good idea to update the jails when a new kernel is installed
 in the host, using the same sources.
 .Ss Starting Jails
-The ezjail script
+Like all
+.Xr rc 8
+scripts, the ezjail script
 .Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-takes parameters
-.Cm start , startcrypto , restart
-and
-.Cm stop .
-It may be passed an additional list of jails. If no jail name is
-specified (usually when the script is called by the rc system at boot
-and shutdown time), all jails in ezjail's scope, except crypto image
-jails (or jails marked as blocking), are started/stopped. To start all
-crypto image jails (or those depending on them), use the
-.Cm startcrypto
-parameter.
+accepts parameters
+.Cm start , restart No and Cm stop, No running, restarting and stopping
+all (non-blocking) jails under ezjail's control by default. When passed an
+additional list of jails, only these jails are acted upon.
 .Pp
-The
-.Nm Cm start
-command provides the same functionnality.
+The order in which jails are started is determined by the
+.Xr rcorder 8
+tool, using cues from the jail configurations in ezjails
+.Pa EZJAIL_PREFIX/etc/ezjail
+control directory.
 .Pp
 The script examines its config, attaches and mounts images, and sets
-variables for each jail in the jail_list before passing its command on
+variables for each jail in the list before passing its command on
 to the
 .Pa /etc/rc.d/jail
 script.
 .Pp
-.Cm ezjail.sh
-enforces the execution of \fB/etc/rc.d/jail\fR, by prepending
-.Em one
-to the start, restart, and stop commands so it is
-.Em NOT NECESSARY
-to set
-.Dq Li $jail_enable
-in the
-.Xr /etc/rc.conf 5
-config file.
-.Pp
-It is possible to set jails as either
+To interactively start all crypto image jails (or those depending on
+them), that were not automatically started during booting, use the
+.Cm startcrypto
+parameter.
+.Pp
+Note that jails configured to be in the
 .Em norun
-(using
+state (using
 .Nm Cm config Fl r Ar norun Ar jailname )
-or as blocking
+are never started by the ezjail.sh script.
+.Pp
+As a convenient shortcut, the
+.Nm Cm
+command invokes the rc.d script and passes the corresponding parameters,
+if they look like valid parameters.
+.Pp
+Even if ezjail is not enabled in the
+.Xr rc.conf 5 ,
+ezjail.sh can be used to start and stop jails by prepending
+.Cm force No or Cm one No to the Cm start, restart No or Cm stop No parameter.
+Refer to
+.Xr rc 8
+for details.
 .Ss Remarks & Tips
 Jails can be either accessed from the network, for instance by using
 .Xr ssh 1 ,
diff --git a/man8/ezjail-admin.8 b/man8/ezjail-admin.8
index 78ae8df..be6fb33 100644
--- a/man8/ezjail-admin.8
+++ b/man8/ezjail-admin.8
@@ -72,8 +72,7 @@ The description of some options ends with
 .Sq Variable: Dq Li $ezjail_abcd .
 This means that the default value of the option may be overridden by setting
 this variable in
-.Xr ezjail.conf 5 ,
-which see.
+.Xr ezjail.conf 5 .
 .Ss Nm Cm install
 This function sub-command is normally run once in the life of the ezjail
 environment. It allocates the directory structure used by ezjail and populates
@@ -98,7 +97,7 @@ The following options are available:
 Fetch and install man pages (ca. 10MB).
 .It Fl M
 Fetch and install man pages, without (re)installing the base jail. May be used
-to add the man pages to the base jail after the intial installation.
+to add the man pages to the base jail after the initial installation.
 .It Fl s
 Fetch and install sources (ca. 450MB).
 .It Fl S
@@ -147,9 +146,10 @@ sub-command for this.
 .El
 .Ss Nm Cm create
 Create a new jail inside ezjail's scope. It either copies the new jail 
-directory tree template or an ezjail archive directory tree to
+directory tree template or an ezjail archive directory tree to new jail root
+directory,
 .Pa /usr/jails/ Ns Ar jailname
-directory tree. Jailname and IP address are mandatory parameters.
+by default. Jailname and IP address are mandatory parameters.
 .Pp
 When a new jail is created, a corresponding new
 .Pa /etc/fstab. Ns Ar jailname
@@ -167,7 +167,16 @@ such as
 .Dq Li jail1 ) ,
 but really any name may be used.
 .Pp
-It is an error to have several jails of the same name.
+It is an error to have several jails of the same name, note that due to
+ezjail's internal jailname sanitation,
+.Dq Li sand-box.com
+and
+.Dq Li sand_box_com
+are considered identical. Some names such as
+.Dq Li basejail
+and
+.Dq Li flavours
+are reserved for ezjails internal administrative purposes.
 .It Ar ipaddress Ns Op Ar ,ipaddress2,...
 The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
 assign several several IPv4 or IPv6 addresses to a jail, by separating them
@@ -179,33 +188,8 @@ The addresses of the jail are not configured on the host.
 will display a warning if the requested address is not found on any interface,
 and the jail will probably not start.
 .Pp
-XXX: is the following relevant, except maybe the warning about dynamic
-addresses?
-.Pp
-This is the static (premanent, never changes) public internet 
-routable ip address assigned to you by your ISP. If you purchased a 
-continous block of static public internet routable ip address, then each 
-jail could be assigned one of those individual ip address from the block.
-.Pp
-Normally phone dialup PPP access and cable providers assign 
-dynamic ip address. The assigned ip address may change every time you 
-dialup and with cable providers when the lease time expires or you 
-reboot your system. \fBUse dynamic ip address at your own risk.\fR
-.Pp
-On the host issue 'ifconfig -a' command to see your assigned ip address.
-Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is 
-the 'unit name' of the NIC card facing the public internet. You will 
-also need this same ifconfig_XXX="DHCP" statement in the rc.conf of 
-each jail to enable the public network for that jail.
-.Pp
-If your host is acting as a 'gateway' (IE. has a LAN behind it), you 
-can provide jails for LAN access only. In this configuration your host
-/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
-the 'unit name' of the NIC card facing the private LAN 
-(local-area-network), where x.x.x.x is a private ip address from the 
-list of reserved non-public routable ip address. You will also need 
-this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
-jail to enable the lan network for that jail.
+It is common to bind jails to loopback addresses, so they provide services
+visible to other jails only. 
 .El
 .Pp
 The following options are available:
@@ -238,37 +222,38 @@ See also
 if you only want to revert to an old jail's state from an archive on the same
 release version.
 .It Fl x
-This flag indicates that an jail of that name already exists. In this case,
-ezjail will only update the configuration of the jail. Sanity checks are
-performed.
+This flag indicates that a jail root directory for that jail already exists.
+In this case, ezjail will only import the jail to its control directory. Sanity
+checks are performed.
 .It Fl f Ar flavour
 Install the requested
 .Ar flavour
-in the new jail.
+in the new jail. Refer to
+.Xr ezjail 7
+for more details on flavours.
 .Pp
 This option may not be used with the
 .Fl a
 option.
 .It Fl c Cm simple | bde | eli | zfs
-Create a jail of the given type.
+Create an image jail of the given type.
 .Pp
-A
-.Cm simple
-jail is backed with a single file. The jail will not be allowed to grow beyond
-its allocated size. The base jail is included in the image, making it portable
-between hosts running the same (or sufficiently close) version of FreeBSD. The
-jail will be stored in a file named
+.Cm simple, No Cm bde No and Cm eli
+image jails are file backed memory discs attached as
+.Xr md 4
+devices, so the jail can never grow beyond its allocated size and can
+even be mounted read only. The jail will be stored in a file named
 .Ar jailname Ns Pa .img ,
 unless
 .Fl r Ar jailroot
 is given, in which case the jail is stored in
 .Ar jailroot Ns Pa .img .
 .Pp
-A
-.Cm bde No or Cm eli
-jail is a
-.Cm simple
-jail whose file has been encrypted using
+Both
+.Cm bde No and Cm eli
+jails use the
+.Xr geom 4
+framework to encrypt all data written to the image file using
 .Xr gbde 4
 (for
 .Cm bde )
@@ -276,24 +261,27 @@ or
 .Xr geli 8
 (for
 .Cm eli ) .
-See also the
+.Pp
+Unless you pass some options to the encryption geom commands using the
 .Fl C
-flag when creating this kind of jail.
+parameter, you will be prompted for a passphrase to protect the crypto
+image. Note that, since starting normal encrypted image jails requires user
+interaction to enter the passphrase, they will
+.Cm NOT automatically be started at boot time. No Use
+.Cm ezjail-admin startcrypto No to manually start all crypto image jails.
 .Pp
 A
 .Cm zfs
 jail is backed with a
 .Xr zfs 8
-volume, whose initial quota is given with the
+filesystem, whose initial quota is given with the
 .Fl s
-option. The volume is compressed using the lzjb method. The volume is created
-in the
-.Cm ezjail_jailzfs
-data set, if set in
-.Xr ezjail.conf 5 .
-.Pp
-XXX: from the code, it looks like the user needs to have done
-ezjail-admin install with ezjail_use_zfs. Is that correct?
+option. The filesystem is created in the
+.Dq Li $ezjail_jailzfs
+zpool and by default compressed using the lzjb method, as set in the
+.Dq Li ezjail_zfs_jail_properies
+variable, both values configured in
+.Xr ezjail.conf 5
 .Pp
 In each case, the
 .Fl s
@@ -303,34 +291,38 @@ suffix in the case of file-based jails) will be created and used as a mount
 point when running the jail.
 .It Fl s Ar imagesize
 Allocate this size to the jail. Without an unit, the size is in bytes. The
-valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes,
-and g/G for gigabytes. As a reference point, a newly created jail requires
-2MB.
+valid suffix values are b/B for blocks (i. e. 512 bytes), k/K for kilobytes,
+m/M for megabytes, and g/G for gigabytes. As a reference point, a newly
+created jail requires 2 MB.
 .Pp
 It is not possible to increase the size of file-based jails after their
 creation, short of creating a new image jail with a larger size.
 .It Fl C Ar imageopt
 Pass this argument to
-.Li gbde No or Li geli init .
+.Xr gbde 8
+or
+.Xr geli 8
+when initialising crypto image jails. The
 .Fl P No and Fl K
 (and
 .Fl L
 for
 .Xr gbde 4 )
-will be translated and passed to
-.Li gbde No or Li geli attach
-when starting the jail.
+options will be translated and passed to the respective attach command when
+starting the jail. You will have to escape parameters with single ticks to
+protect them from shell expansion.
 .It Fl i
 Synonym of
 .Fl c Cm simple .
 .It Fl b
-Don't start the jail at boot time.
+Tell ezjail that starting this jail would block unattended reboots. This may
+happen when certain services need private SSL keys that require the user to
+interactively enter a passphrase. The jail is then not automatically started
+at boot time.
 .El
 .Ss Nm Cm console
 Attach your console to the selected jail. You are logged in as root by 
-default. The command line prompt shows the name of the jail. You have to 
-use the pwd command to see where in the directory tree you are. Entering 
-\fBexit\fR will terminate the jail console.
+default.
 .Pp
 The following options are available:
 .Bl -tag -width indent
@@ -339,9 +331,10 @@ Start the jail if it is not running yet.
 .It Fl e Ar command
 Use
 .Ar command
-instead of
+instead of the default
 .Dq /usr/bin/login -f root .
-A one time change to use a different user can be accomplished by using
+loogin command. A one time change to use a different user can be
+accomplished by using
 .Fl e Qq Li /usr/bin/login -f user .
 Variable:
 .Dq Li $ezjail_default_execute .
@@ -381,32 +374,26 @@ If present, the third letter,
 means that the jail is not automatically started.
 .Pp
 The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
-.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ...
-Execute the given action on
-.Ar jailname ,
-or on all jails if the operand is omitted. Several jails may be specified.
+.Ss Nm Cm start | restart | stop | startcrypto Op Ar jailname ...
 .Pp
-As this is just a shortcut to the
+This is a shortcut to the
 .Xr rc 8
-.Cm ezjail
-script, if ezjail is not enabled in
+.Cm ezjail.sh
+script. Refer to
+.Xr ezjail 7
+section
+.Pa Starting jails
+for details.
+.Pp
+Note that, if ezjail is not enabled in
 .Xr rc.conf 5
 with
 .Dq Li ezjail_enable= Ns Qq Li YES ,
-nothing will be done. Prefix the action with
-.Cm one
-(as in
-.Cm onestart ,
-etc.) to force the action regardless of the value of
-.Dq Li $ezjail_enable .
-.Pp
-.Cm cryptostart
-is used to start jails that use
-.Xr gbde 4
-or
-.Xr geli 8
-encryption. Those jails require interaction with the administrator
-when starting.
+nothing happens. 
+.Pp
+Since starting crypto image jails requires interaction with the administrator, they are not run at
+boot time. Use
+.Cm startcrypto No to run them all at once.
 .Ss Nm Cm config Ar jailname
 Manage parameters of specific ezjails. For running jails, most of the
 configuration changes described below will not be applied until the next time
@@ -416,7 +403,7 @@ The following options are available:
 .Bl -tag -width indent
 .It Fl r Cm run | norun
 Set the jail to be automatically started or not on boot.
-.It Fl n An newname
+.It Fl n Ar newname
 Rename the jail. Unless a custom root directory was given with the
 .Fl r
 flag when creating the jail, the root directory will be renamed as well. A
@@ -453,26 +440,21 @@ Stop the jail before deleting it.
 .It Fl w
 Delete the directory or the file backing the jail.
 .El
-.Ss Nm Cm archive
-Create a backup of one, multiple or all ezjails. The specified service
-jail's root directory tree is backed up as a
+.Ss Nm Cm archive Op jailname
+Create a backup of one or all jails. The jail's root directory tree is backed
+up as a
 .Xr pax 1
-file. The jail needs to be stopped.
-.Pp
-See
-.Nm Cm restore
-or
-.Nm Cm create Fl a Ar archive
-to restore an archive.
-.Pp
-The basejail can not be archived. There is no ezjail function to
-delete archive files; they may be removed from the host using
-.Xr rm 1 .
+archive. By default, the jail needs to be stopped.
 .Bl -tag -width indent
+.It Fl A
+Archive all jails. You must neither specify an archivename nor a jailname in
+this case.
 .It Fl a Ar archivename
-Use this name for the archive file. If absent, the archive file name
-is derived from the jail name, with the date and time of the archive
-appended to the file name.
+Use this name for the archive file. If absent, the archive file name is
+derived from the jail name, with the current date and time appended to the
+archive's file name. Use
+.Pa -
+to write to stdout.
 .It Fl d Ar directory
 Save the archive in this directory. If this option is not given and
 .Dq Li $ezjail_archivedir
@@ -481,13 +463,13 @@ Variable:
 .Dq Li $ezjail_archivedir .
 .It Fl f
 Archive the jail even when it is running.
-.It Fl A
-Archive all jails.
-.It Ar jailname
-Archive only this jail. This argument is mandatory if
-.Fl a
-is not given.
 .El
+.Pp
+Use
+.Nm Cm restore
+or
+.Nm Cm create Fl a Ar archive
+to restore an archive.
 .Ss Nm Cm restore
 Create new ezjails from archived versions. It tries to collect all
 information necessary to do that without user interaction from the
@@ -502,43 +484,46 @@ will use the most recent archive file matching the name you specified.
 To restore an older version, specify the complete archive file name
 (file name with the date and time of the archive appended to it).
 .El
+.Pp
 The following options are available:
 .Bl -tag -width indent
 .It Fl d Ar archivedir
-Search the archive file in this directory. If this option is not given and
-.Dq Li $ezjail_archivedir
-is not set, the archive is searched in the current directory. Variable:
+Search the archive file in this directory. If this option is not given, the
+archive is searched in
 .Dq Li $ezjail_archivedir .
 .It Fl f
 Restore the archive even if running on a host different from
 where it was archived. Be default,
 .Nm
-will refuse to restore an archive if the hostname, the FreeBSD version
-or the CPU architecture is modified.
+will refuse to restore an archive if the archived host system's hostname,
+its FreeBSD version or CPU architecture do not match the current host.
 .El
 .Ss Nm Cm update
-Creates or updates ezjail's basejail from source. This performs a
-.Dq make world ; make installworld
-using the basejail's RELEASE source located at 
-.Pa /usr/src
-(but see the
-.Fl s
-option). Exactly one of
-.Fl b , i , u , P
-is mandatory.
-.Pp
-See the
-.Cm install
-command to install the basejail from binary packages.
+Updates ezjail's basejail, or in the
+.Fl b
+or
+.Fl i
+case, install a FreeBSD world from source to be used as basejail.
 .Pp
 Exactly one of the following operand must be specified:
 .Bl -tag -width indent
 .It Fl b
-Build and install a world from source located in the basejail.
+Build a world from source and install it as the (updated) basejail.
+.Dq make buildworld ; make installworld
+by default using the sources located at 
+.Pa /usr/src
+(but see the
+.Fl s
+option).
+.Pp
+As the old basejail is not deleted, but merely overwritten, this usually
+leaves all jails in a state where they still find older versions of libraries
+they were linked against.
 .It Fl i
-Perform a
-.Qq make installworld ,
-assuming the world has already been built.
+As above but only perform a
+.Dq make installworld ,
+assuming the world has already been built. That is highly likely since it is
+recommended to update the basejail along with the host system.
 .It Fl u
 Use
 .Xr freebsd-update 8
@@ -549,14 +534,13 @@ uses
 to determine the currently running system, the base jail and the host
 need to be updated at the same time, without rebooting on the new
 kernel in the meantime.
-.Pp
-Jails that are stored in a ZFS volume are snapshot first.
 .It Fl P
 Install only the ports tree, assuming the basejail has already been
-created.This can be done while jails are running. The
+created. This can be done while jails are running. The
 .Xr portsnap 8
 utility is invoked to do the actual work.
 .El
+.Pp
 The following options are available:
 .Bl -tag -width indent
 .It Fl p
@@ -571,6 +555,13 @@ instead of
 Variable:
 .Dq Li $ezjail_sourcetree .
 .El
+.Pp
+See the
+.Cm install
+sub command to install the basejail from binary packages.
+.Pp
+If the basejail is managed in its own ZFS filesystem, a snapshot of that
+filesystem is taken first.
 .Sh FILES
 .Pa EZJAIL_PREFIX/bin/ezjail-admin
 .br