New man pages, also put in new sections

6 files changed, 1390 insertions, 423 deletions

diff --git a/Makefile b/Makefile
index bfd5e87..a2a526b 100755
--- a/Makefile
+++ b/Makefile
@@ -13,9 +13,9 @@ install:
         cp -R -p examples/nullmailer-example ${PREFIX}/share/examples/ezjail/
         sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
         sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
-        sed s:EZJAIL_PREFIX:${PREFIX}: man1/ezjail-admin.1 > ${PREFIX}/man/man1/ezjail-admin.1
+        sed s:EZJAIL_PREFIX:${PREFIX}: man8/ezjail-admin.8 > ${PREFIX}/man/man8/ezjail-admin.8
         sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
-        sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.5 > ${PREFIX}/man/man5/ezjail.5
+        sed s:EZJAIL_PREFIX:${PREFIX}: man7/ezjail.7 > ${PREFIX}/man/man7/ezjail.7
         chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
-        chown -R root:wheel ${PREFIX}/man/man1/ezjail-admin.1 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man5/ezjail.5 ${PREFIX}/share/examples/ezjail/
+        chown -R root:wheel ${PREFIX}/man/man8/ezjail-admin.8 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man7/ezjail.7 ${PREFIX}/share/examples/ezjail/
         chmod 0440 ${PREFIX}/share/examples/ezjail/example/usr/local/etc/sudoers
diff --git a/man1/ezjail-admin.1 b/man1/ezjail-admin.1
deleted file mode 100755
index 18cea26..0000000
--- a/man1/ezjail-admin.1
+++ /dev/null
@@ -1,268 +0,0 @@
-.TH ezjail\-admin 1
-.SH NAME
-ezjail-admin \- Administrate ezjail
-.SH SYNOPSIS
-.T
-.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release]
-
-.T
-.B ezjail-admin create
-[-f flavours] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip
-
-.T
-.B ezjail-admin console\fR [-f] [-e command]\fI jailname
-
-.T
-.B ezjail-admin list
-
-.T
-.B ezjail-admin config\fR [-r run|norun] [-n newname] [-c cpu-list] [-z zfs-dataset] [-f fib-number] [-i attach|detach|fsck]\fI jailname
-
-.T
-.B ezjail-admin delete \fR[-w] \fI hostname
-
-.T
-.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]
-
-.T
-.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)...
-
-.T
-.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
-
-.SH DESCRIPTION
-The \fBezjail-admin\fR tool is used to manage the ezjail environment
-and jails inside the ezjail scope.
-
-It can also be used to start or stop and to get a console in ezjail's
-jails by proxying everything looking like
-\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
-.SH ezjail-admin install
-fetches everything needed to setup an ezjail environment from an FTP server and 
-installs it.
-
-The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you
-have enough space there (a FreeBSD base without man pages, sources and ports
-is around 120MB).
-
-The -m and -s option will fetch and install man pages (ca. 10MB) and
-sources packages (ca. 450MB) respectively. The -p option invokes the
-portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
-Options -M, -P or -S behave like their lower case pendants, but they
-disable (re)installing your basejail.
-
-The default OS version is whatever uname -r returns. If this does not match
-"*-RELEASE", you will be prompted for a better guess. (Normally
-ftp-servers do not provide release candidates or CURRENT builds). You can
-use the -r option to specify a release on the command line.
-
-The default host to fetch packages from is ftp.freebsd.org; you may want to
-change this via the -h option or in ezjail.conf(5).
-
-If the specified location begins with file://, your local copy of the
-release is used. That way you can modify the install.sh scripts before
-executing them.
-
-You can later update your world from CVS or update ports with \fIezjail-admin
-update\fR or rerun this subcommand with another OS version.
-.SH ezjail-admin create
-installs a new jail inside ezjail's scope. It either copies the template
-jail or an ezjail archive to the root of that new jail, whose name and IP
-address are provided as mandatory parameters.
-
-A new entry in ezjail's config directory is created, a corresponding new
-\Fi/etc/fstab.hostname\fR allows the jail to be brought up by next
-reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
-
-If no jail root is specified via the -r option, it is derived from
-the jail's name. In this case or, if a jail root is given and does not
-start with a '/', it is interpreted relative to ezjail's root dir
-(default: \fI/usr/jails\fR). If a specified jail root lies outside the
-ezjail root dir, a soft link is created inside this root dir pointing
-to the newly created jail's location.
-
-The -i option requires a size passed via the -s option and creates a
-file-backed jail image using md(4). 
-The image file is named after the jail root suffixed with \fI.img\fR.
-
-The -c options allows to generate a file-backed jail image encrypted 
-via gbde or geli, it requires a size passed via the -s option. 
-The image file is named after the jail root suffixed with \fI.img\fR.
-
-Starting with ZFS version 13 in FreeBSD, the -c option allows to 
-create a ZFS-backed jail with an optional ZFS filesystem-quota passed
-via the -s option. The filesystem is named after the jailname.
-
-To install an ezjail archive instead of a vanilla copy of newjail use
--a with the backup's location. Note that you will probably need to tidy
-up things inside an ezjail if you migrate it between different ezjail
-environments. This may include (but is not limited to) reinstalling ports
-or packages for different CPUs or library versions. You may also need to
-copy some libraries from the source host's basejail. Also consider using
-\fIezjail-admin restore\fR, if you only want to revert to an old jail's
-state from a backup on the same host.
-
-The -x option indicates that an ezjail already exists at the jail root.
-.B In this case nothing is copied. ezjail only updates its config.
-This is useful in situations where you just want to alter some of a
-jail's properties and called ezjail-admin delete without the -w option
-before. However, sanity checks are performed.
-
-Using the -f \fIflavour\fR option you can specify one or multiple space
-separated ezjail \fBFLAVOUR\fRs to be installed in your ezjail (e.g.
-preinstall packages, add users, configure rc). \fIflavours\fR points to
-one or more directory trees under ezjail's root dir (default:
-\fI/usr/jails/flavours\fR). If no flavours are passed, the global
-ezjail_default_flavour (default: \fI""\fR) is used. See \fBFLAVOURS\fR below
-for more details.
-
-Options for newly created jails are read from \fBezjail.conf\fR; refer to
-ezjail.conf(5) for more information.
-.SH ezjail-admin console
-Attaches your console to a jail by executing a jexec with its jid.
-
-The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
-but can be set with the -e modifier or by setting the ezjail_default_execute
-config variable. A non-running jail is not started by default. If you want
-that, force it with -f.
-.SH ezjail-admin list
-lists all jails inside ezjail's scope. They are sorted by the order they 
-start up, as defined by rcorder. The list format is straightforward.
-
-A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR
-based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto
-image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
-running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
-\fIezjail-admin config\fR).
-
-The rest of the row is the jail's jid (if available), its IP address, hostname and
-root directory.
-.SH ezjail-admin config
-manages specific ezjails.
-
-You can prevent an ezjail from being run at system start with the -r norun
-option and reenable it with -r run.
-
-You can rename an ezjail by using the -n newname option. If the specified
-ezjail is an image jail and the image has its default name, the image is
-renamed as well.
-
-You can configure a cpuset(1) for the jail to use with the -c option. The setting
-will be configured and, if the jail is running, appliedto the running jail. The specification
-may include numbers separated by '-' for ranges and commas separating individual numbers.
-
-With the -z option, one or more zfs-datasets can be configured to be attached to the jail.
-You need to configure the sysctl security.jail.mount_allowed=1 and security.jail.enforce_statfs=0,
-set the jailed zfs property to on  as well as "add path zfs unhide" in the devfs ruleset for the jail.
-
-You can configure an altered network view (FIB) for the jail with the -f option. For setting up FIBs, see
-setfib(1). The jail needs to be restarted after the option has been applied to take effect.
-
-You can attach image jails for administrative purposes with the -i attach
-option, and detach them with -i detach. It is not possible to run or delete
-an attached jail. You can force fscking a jail image with the -i fsck command.
-.SH ezjail-admin delete
-removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
-file, thus preventing the jail from being brought up on next reboot.
-
-If the -w (wipe) option is given, the directory pointed to by the jail
-root entry is removed as well as the soft link in ezjail's root dir.
-.SH ezjail-admin archive
-creates a backup of one, multiple or all ezjails.
-
-Unless an archive name is given via -a switch, its file name is derived from
-jailname, date and time. It is saved to a directory provided by -d switch
-or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to
-\fI.\fR .
-
-Use -A with no further parameters to archive all jails \fBor\fR specify one or more
-ezjails as parameters.
-
-Use \fIezjail-admin restore\fR or \fIezjail-admin create -a archive\fR to restore
-an archive.
-.SH ezjail-admin restore
-creates new ezjails from archived versions. It tries to collect all information
-necessary to do that without user interaction from the archives, thus allowing
-it to be run from a script.
-
-Pass one or more archives or jail names. For jail names, ezjail-admin will try to
-find the newest backup in its archive directory, as given in ezjail.conf(5), which
-defaults to \fI.\fR and can be overridden via -d.
-
-By default \fIezjail-admin restore\fR refuses to restore on a host different from
-where it was archived. Use -f to force that.
-.SH ezjail-admin update
-creates or updates ezjail's environment (aka basejail) from source. To install it
-from ftp servers, use ezjail-admin install.
-
-Depending on the parameters given, it will install the basejail from a source
-tree whose location is either provided in the \fBezjail.conf\fR config file or
-via the -s option.
-
-If the -p or -P option is given, the base jail also is given a copy of
-FreeBSDs ports tree, which is in turn linked into all newly created
-ezjails. The portsnap utility is invoked to do the actual work.
-
-If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
-be done while jails are running.
-
-If the -i (install only) option is given, \fBezjail-admin update\fR performs a
-\fImake installworld,\fR otherwise \fImake world\fR is invoked.
-
-.SH NOTES
-.B ezjail-admin update\fR uses a temporary directory to install its world to,
-thus leaving intact all installed libraries, if a base jail already exists.
-
-When using the \fBezjail-admin update\fR option, be careful to use the same
-FreeBSD source tree used to build the host system's world, or at least its
-kernel. Combining a make world in the host system with \fBezjail-admin update\fR
-is considered a good idea.
-
-When a ports tree exists in basejail, a make.conf containing reasonable
-values for having ports in jails is created in the template jail.
-.SH FLAVOURS
-.B ezjail-admin\fR provides an easy way to create many jails with similar or
-identical properties.
-
-A sample flavour config directory resides under
-.I EZJAIL_PREFIX/share/examples/ezjail/example/.\fR Some typical jail
-initialization actions are demonstrated, and you are encouraged to use it as
-a template for your flavours.
-
-If flavours are selected on jail creation, their root directories are
-copied to the new jail's root, each containing an \fI/ezjail.flavour\fR.
-When the jail starts up for the first time, these scripts are run and deleted.
-
-In its default form it will create some groups and users, change the
-ownership of some files and install all packages residing under /pkg.
-
-It allows you to add some post-install actions.
-.SH EXAMPLES
-ezjail-admin update -p
-.br
-ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org
-.br
-ezjail-admin delete ns.test.org
-.br
-ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
-.SH BUGS
-Due to the way ezjail handles jail config files, it is not possible to
-create multiple jails if their names are identical when piped through
-.B tr -C [:alnum:] _
-
-Sure to be others.
-.SH FILES
-.T4
-EZJAIL_PREFIX/etc/ezjail.conf
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.br
-EZJAIL_PREFIX/share/examples/ezjail/
-.SH "SEE ALSO"
-ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1)
-.SH AUTHOR
-Dirk Engling <erdgeist@erdgeist.org>
diff --git a/man5/ezjail.5 b/man5/ezjail.5
deleted file mode 100755
index 62cbb42..0000000
--- a/man5/ezjail.5
+++ /dev/null
@@ -1,40 +0,0 @@
-.TH ezjail 5
-.SH NAME
-ezjail \- A simple jail setup framework
-.SH SYNOPSIS
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH DESCRIPTION
-The ezjail framework provides a simple way to create many virtual FreeBSD 
-servers by using FreeBSD's jail system. It requires little administration 
-effort and aims for minimum system resource usage.
-
-If you are not familiar with the FreeBSD jail concept, please refer to 
-jail(8) before continuing.
-.SH OVERVIEW
-One \fIbase jail\fR is filled with most userland binaries and libraries and
-then mounted read only into a number of stripped down jails via
-.B mount_nullfs(8)\fR - thus saving lots of inodes and memory resources.
-.SH INVOCATION
-The ezjail script \fBEZJAIL_PREFIX/etc/rc.d/ezjail.sh\fR takes parameters \fIstart,
-startcrypto, restart\fR and \fIstop\fR. It may be passed an additional list of
-jails. If no jail name is specified (usually when the script is called by
-rc.local 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 crytpo image jails (or those depending on them), use the \fIstartcrypto\fR parameter.
-
-The script examines its config, attaches and mounts images, and sets
-variables for each jail in the jail_list before passing its command on
-to the \fB/etc/rc.d/jail\fR script.
-.SH NOTES
-.B ezjail.sh\fR enforces the execution of \fB/etc/rc.d/jail\fR, by
-prepending \fI"one"\fR to the start, restart, and stop commands so it is
-.B NOT NECESSARY\fR to set \fIjail_enable\fR in the \fB/etc/rc.conf\fR
-config file.
-.SH FILES
-EZJAIL_PREFIX/etc/ezjail.conf
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH "SEE ALSO"
-ezjail-admin(1), ezjail.conf(5), jail(8), mount_nullfs(8)
-.SH AUTHOR
-Dirk Engling <erdgeist@erdgeist.org>
diff --git a/man5/ezjail.conf.5 b/man5/ezjail.conf.5
index 81ac1ba..27e6e2a 100755
--- a/man5/ezjail.conf.5
+++ b/man5/ezjail.conf.5
@@ -1,143 +1,207 @@
-.TH ezjail.conf 5
-.SH NAME
-ezjail.conf \- configuration file for ezjail script
-.SH DESCRIPTION
+.Dd January 15, 2011
+.Dt EZJAIL.CONF 5 USD
+.Os FreeBSD
+.Sh NAME
+.Pa ezjail.conf
+.Nd configuration file for ezjail script
+.Sh DESCRIPTION
 The file
-.B ezjail.conf
+.Pa ezjail.conf
 contains settings that control the operation of the ezjail rc script. It is 
 also read by the
-.B ezjail-admin
-utility to figure out where it should perform its actions.
-.SH PATH OPTIONS
-.TP
-.B ezjail_jaildir (str)
-Location of jail root directories
-.br
-.I default: /usr/jails
-.TP
-.B ezjail_jailtemplate (str)
+.Cm ezjail-admin
+utility to figure out where it should perform its actions. Its path is
+set at installation time to
+.Pa EZJAIL_PREFIX/etc/ezjail.conf ,
+with an example file installed at
+.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
+.Pp
+This file is really a shell script that is sourced by the
+.Cm ezjail-admin
+command at run-time.
+.Dq (str)
+denotes a string; it should be enclosed in quotes if it contains space.
+.Dq (bool)
+notes a boolean, whose possible values are
+.Dq YES
+and
+.Dq NO .
+.Sh PATH OPTIONS
+.Bl -tag -width option
+.It ezjail_jaildir (str)
+Location of jail root directories.
+.br
+Default:
+.Em /usr/jails .
+.It ezjail_jailtemplate (str)
 Location of template jail used to create a new jail
 .br
-.I default: /usr/jails/newjail
-.TP
-.B ezjail_jailbase (str)
+Default:
+.Em ${ezjail_jaildir}/newjail .
+.It ezjail_jailbase (str)
 Location of base jail, the one that is mounted to all jails
 .br
-.I default: /usr/jails/basejail
-.TP
-.B ezjail_sourcetree (str)
+Default:
+.Em ${ezjail_jaildir}/basejail .
+.It ezjail_sourcetree (str)
 Location of your copy of FreeBSD's source tree (refer to the
-.B ezjail-admin(1)
-utility for more information)
-.br
-.I default: /usr/src
-.TP
-.B ezjail_portscvsroot (str)
-Cvs root to use when checking out or updating the ports tree in base jail
-.br
-.I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
-.TP
-.B ezjail_ftphost (str)
-This is where the install subcommand defaults to fetch its packages from
-.br
-.I default: ftp.freebsd.org
-.TP
-.B ezjail_archivedir (str)
-This is the default archive location for the \fIezjail-admin archive\fR command.
-.br
-.I default: `pwd -P`
-.SH JAIL ADMIN OPTIONS
-.TP
-.B ezjail_default_execute (str)
-This is the default command executed in a jail by ezjail-admin console.
-.br
-.I default: YES
-.SH JAIL CREATION OPTIONS
+.Xr ezjail-admin 1
+utility for more information).
+.br
+Default:
+.Em /usr/src .
+.It ezjail_flavours_dir (str)
+Location of the flavours, where each directory is a different flavour.
+.br
+Default:
+.Em ${ezjail_jaildir}/flavours .
+.It ezjail_portscvsroot (str)
+CVS root to use when checking out or updating the ports tree in base jail.
+.br
+Default:
+.Em :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs .
+.It ezjail_ftphost (str)
+This is where the install subcommand defaults to fetch its packages from.
+.br
+Default:
+.Em ftp.freebsd.org .
+.It ezjail_archivedir (str)
+This is the default archive location for the
+.Cm ezjail-admin archive
+command.
+.br
+Default:
+.Em ${ezjail_jaildir}/ezjail_archives .
+.El
+.Sh JAIL ADMIN OPTIONS
+.Bl -tag -width option
+.It ezjail_default_execute (str)
+This is the default command executed in a jail by
+.Cm ezjail-admin console .
+.br
+Default:
+.Em /usr/bin/login -f root .
+.It ezjail_exec_start (str)
+The command to execute in a jail when starting it.
+.br
+Default:
+.Em /bin/sh /etc/rc .
+.El
+.Sh JAIL CREATION OPTIONS
 Default options for newly created jails. Used by the
-.B ezjail-admin(1)
-utility. Be careful about disabling ezjail_mount_enable. (Refer to
-.B ezjail-admin(1)
-for more information).
-.TP
-.B ezjail_mount_enable (bool)
-Controls whether /etc/fstab.hostname should be executed at jail startup 
-time.
-.br
-.I default: "YES"
-.TP
-.B ezjail_devfs_enable (bool)
+.Xr ezjail-admin 1
+utility. Be careful about disabling
+.Em ezjail_mount_enable .
+.Bl -tag -width option
+.It ezjail_mount_enable (bool)
+Controls whether
+.Pa /etc/fstab. Ar hostname
+should be executed at jail startup time.
+.br
+Default: 
+.Em YES .
+.It ezjail_devfs_enable (bool)
 Controls whether newly created jails are given a working
-.I /dev
+.Pa /dev
 directory. (Refer to
-.B devfs(5)
+.Xr devfs 5
 and
-.B jail(8)
+.Xr jail 8
 for more information).
 .br
-.I default: "YES"
-.TP
-.B ezjail_devfs_ruleset (str)
-Specifies which devfs ruleset should apply for newly created jails. 
+Default:
+.Em YES .
+.It ezjail_devfs_ruleset (str)
+Specifies which devfs ruleset should apply for newly created jails.
 (Refer to
-.B devfs(5)
+.Xr devfs 5
 and
-.N jail(8)
+.Xr jail 8
 for more information).
 .br
-.I default: "devfsrules_jail"
-.TP
-.B ezjail_procfs_enable (bool)
+Default:
+.Em devfsrules_jail .
+.It ezjail_procfs_enable (bool)
 Controls whether newly created jails are given a working
-.I /proc
+.Pa /proc
 directory. (Refer to
-.B procfs(5)
+.Xr procfs 5
 and
-.B jail(8)
+.Xr jail (8)
 for more information).
 .br
-.I default: "YES"
-.TP
-.B ezjail_fdescfs_enable (bool)
+Default:
+.Em YES .
+.It ezjail_fdescfs_enable (bool)
 Controls whether newly created jails are given a working
-.I /dev/fd/
+.Pa /dev/fd/
 directory. (Refer to
-.B fdescfs(5)
+.Xr fdescfs (5)
 and
-.B jail(8)
+.Xr jail (8)
 for more information).
 .br
-.I default: "YES"
-.TP
-.B ezjail_uglyperlhack (bool)
-Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail.
-.br
-.I default: YES
-.TP
-.B ezjail_default_flavour (str)
-Controls which flavours should be used for newly created jails if none are given on the command line.
-.br
-.I default: none
-.SH ZFS OPTIONS
-.TP
-.B ezjail_use_zfs (bool)
-Set to YES, if ezjail should manage basejail and newjail in a seperate ZFS-datasets.
-.br
-.I default: NO
-.TP
-.B ezjail_jailzfs (str)
-The name of the parent ZFS-dataset which ezjail will use to create jails on. It will be mounted at the ezjail_jaildir. Setting this will automaticly enable ezjail managing jails in seperate ZFS-datasets.
-.br
-.I default: none
-.TP
-.B ezjail_zfs_properties (str)
-Default properties ZFS will use for creating datasets. See zfs(1m) for details. ADVANCED, be very careful!
-.br
-.I default: none
-.SH FILES
+Default:
+.Em YES .
+.It ezjail_uglyperlhack (bool)
+Set to YES, if ezjail should provide a soft link from
+.Pa /usr/bin/perl
+to
+.Pa /usr/local/bin/perl
+in base jail.
+.br
+Default:
+.Em YES .
+.It ezjail_default_flavour (str)
+Controls which flavours should be used for newly created jails if none
+are given on the command line.
+.br
+Default:
+.Em none .
+.It ezjail_imagetype (one of simple, bde, eli, zfs)
+Type of jail to create when creating a jail with the
+.Fl i
+flag without specifying the type explicitely.
+.br
+Default:
+.Em simple
+.El
+.Sh ZFS OPTIONS
+.Bl -tag -width option
+.It ezjail_use_zfs (bool)
+Set to YES, if ezjail should manage basejail and newjail in a seperate
+ZFS-datasets.
+.br
+Default:
+.Em NO .
+.It ezjail_jailzfs (str)
+The name of the parent ZFS-dataset which ezjail will use to create
+jails on. It will be mounted in
+.Em ezjail_jaildir .
+Setting this will automaticly enable ezjail managing jails in seperate
+ZFS-datasets.
+.br
+Default:
+.Em none .
+.It ezjail_zfs_properties (str)
+Default properties ZFS will use for creating datasets. See
+.Xr zfs 1m
+for details. ADVANCED, be very careful!
+.br
+Default:
+.Em none .
+.El
+.Sh FILES
 EZJAIL_PREFIX/etc/ezjail.conf
 .br
 EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH "SEE ALSO"
-ezjail-admin(1), ezjail(5), jail(8), devfs(5), fdescfs(5), procfs(5)
-.SH AUTHOR
-Dirk Engling <erdgeist@erdgeist.org>
+.Sh SEE ALSO
+.Xr ezjail-admin 1 ,
+.Xr ezjail 5 ,
+.Xr jail 8 ,
+.Xr devfs 5 ,
+.Xr fdescfs 5 ,
+.Xr procfs 5 .
+.Sh AUTHOR
+Dirk Engling
+.Aq erdgeist@erdgeist.org .
diff --git a/man7/ezjail.7 b/man7/ezjail.7
new file mode 100644
index 0000000..95fde42
--- /dev/null
+++ b/man7/ezjail.7
@@ -0,0 +1,605 @@
+.Dd January 15, 2011
+.Dt EZJAIL 7 USD
+.Os
+.Sh NAME
+.Cm ezjail
+.Nd Jail administration framework.
+.Sh SYNOPSIS
+.Nm ezjail-admin Ar command arguments...
+.Sh OVERVIEW
+The ezjail commands provides a simple way to create multiple jails
+using FreeBSD's jail system. It simplifies jail administration effort
+and minimizes jail system resource usage.
+.Pp
+If you are not familiar with the FreeBSD jail concept, please refer to
+.Xr jail 8
+before continuing. For additional design information, see the ezjail
+site at
+.Li http://erdgeist.org/arts/software/ezjail .
+.Sh DESCRIPTION
+The ezjail system enables the system administrator to create multiple
+OS-level virtualization containers called jails. Services like web
+servers, mail servers, FTP servers, are typically under frequent attack
+from the public Internet and are exposed to possible compromise. The
+typical usage of jails is to run a single service in each jail and if
+that service becomes compromised the rest of the jails and the host
+system are protected from also being compromised.
+.Pp
+The major shortcoming of jails is that each jail has its own copy of
+the world. This eats disk space, inodes, and more importantly,
+prevents the sharing of binaries images between jails, thus increasing
+the memory pressure on the host system. In addition, this causes a
+major administration headache when comes the time to update the host
+system, as each jail need to be updated independently.
+.Pp
+Ezjail addresses these problems by creating a single basejail (a read-only
+.Xr nullfs 4 )
+populated with the same running binaries as the host system and them
+shares that basejail with all the other service jails created by
+ezjail. Is is possible to update the base jail (and thus all the
+jails) in a single ezjail command.
+.Pp
+Typical usage of jails include separation of services, creating test
+environments, consolidation of different services on a single physical
+host, and more.
+.Sh EZJAIL SYSTEM
+The administrative interface to the ezjail system is the
+.Xr ezjail-admin 8
+command. It is used to install the ezjail environment, create new
+jails, archive, restore, delete and update jails, open a jail console,
+and list the status of all the jails. See below for example usage, and
+refer to its man page for complete usage details.
+.Pp
+The configuration is done in the
+.Xr ezjail.conf 5
+file, which see. It will not be necessary to edit this file for most
+users. A sample file is installed as
+.Pa EZJAIL_PREFIX/etc/ezjail.conf .
+.Pp
+A rc script is also installed to allow the ezjail to be started
+at boot time, as
+.Pa ezjail.sh .
+It is enabled by setting the
+.Xr rc.conf 5
+variable
+.Dq Li $ezjail_enable
+to
+.Dq Li YES .
+.Sh WHAT'S IN A JAIL
+.Ss The Life of an Ezjail Installation
+The base jail is first created by running
+.Nm Cm update
+or
+.Nm Cm install .
+Example usage of this command is section
+.Sx EXAMPLES .
+This will create the base jail, setup a template jail used when
+setting up new jails, install an example flavour (see below),
+configure miscellaneous things.
+.Pp
+This step is necessary before using the ezjail system. In particular,
+it is not possible to create new jails without initializing the base
+jail in advance.
+.Pp
+Once the base jail has been created, new jails may be created with
+.Nm Cm create .
+A new jail is defined by its name and its IP address (or addresses).
+Creating a new jail involves copying the template jail to the new
+location, configuring
+.Xr nullfs 4
+mounts for giving access to the base jail, and little more. A jail
+that has just be created occupies about 2MB of disk space ; when
+running, only a handful of daemons (cron, syslog, sendmail mainly) use
+memory.
+.Pp
+After their creation, jails may be archived to a
+.Xr pax 1
+archive, restored, and eventually deleted.
+.Pp
+When a new version of FreeBSD is released, or when an errata is
+published, only the base jail need to be updated. Both source upgrades
+and binary upgrades (using
+.Xr freebsd-update 8 )
+are supported. The
+.Xr ports 7
+collection may also be updated by ezjail, but individual ports need to
+be upgraded individually by the administrator.
+.Ss Anatomy of a Jail
+In the ezjail system, a jail is defined by a root directory and a
+couple of configuration values, mainly a name and IP addresses. The
+root directory of the jail contains only the jail-specific files:
+configuration files, data files, and ports installed by the
+administrator. The base system is shared amongst all jails, using a
+.Xr nullfs 4
+mount. This saves space and inodes (especially when the ports
+collection in made available to the jails), and also memory, as the
+kernel is now able to share copies of running programs between the
+jails.
+.Pp
+Unless the variable
+.Dq Li $ezjail_jaildir
+has been set by the administrator, the root directory of the jail is
+kept in
+.Pa /usr/jails ,
+which therefore needs to reside on a partition big enough.
+.Pp
+There are also file-based jails, in which the storage space for the
+jail is kept in a file mounted with
+.Xr mdconfig 8 .
+There are two advantages to image jails. The amount of disk space
+allocated to the jail is limited, while normal jails have no bound on
+the amount of disk space they use. On the other hand, the space
+dedicated to the jail is no longer available to the host, even if the
+jail doesn't use all its allocated space. In addition, image jails
+contain a full copy of the basejail. This makes them portable between
+hosts running the same FreeBSD version as the image was created with.
+Of course, the jail now needs to be updated independently from all
+other jails, and there is no longer any sharing of common files
+between the jails.
+.Pp
+Image jails may also be encrypted using
+.Xr bde 4
+or
+.Xr geli 8 ,
+depending on the options given at creation time.
+.Ss Per-Jail options
+As we saw earlier, a jail is described by a file in
+.Pa EZJAIL_PREFIX/etc/ezjail/ .
+This file has the same name as the jail it configures. It is a set of
+variables interpreted by
+.Xr sh 1 ,
+much like
+.Xr rc.conf 5
+is. This file is created at the same time as the jail, and usually
+doesn't require tweaking from the administrator.
+.Pp
+In addition to the variables described below, any variable used by the
+init script
+.Pa /etc/rc.d/jail
+may be added manually by the administrator. The following variables
+are handled by ezjail, replacing JAILNAME with the actual name of the jail:
+.Bl -tag -width indent
+.It jail_JAILNAME_hostname
+The hostname of the jail. Defaults to the name of the jail, unless
+special characters needed to be stripped.
+.It jail_JAILNAME_ip
+The IP addresses the jail is allowed to use. Since FreeBSD 7.2,
+several IP addresses may be given, separated by commas.
+.It jail_JAILNAME_rootdir
+The directory holding the jail files (the directory used as a mount
+point for file-based jails). Defaults to the jail name inside
+.Dq Li $ezjail_jaildir .
+.It jail_JAILNAME_exec_start
+The command to run inside the jail when starting it. Defaults to
+.Dq Li $ezjail_exec_start
+or
+.Dq Li /bin/sh /etc/rc .
+.It jail_JAILNAME_exec_stop
+The command to run inside the jail when stopping it. Defaults to the
+empty string, which means
+.Dq Li /bin/sh /etc/rc.shutdown .
+.It jail_JAILNAME_mount_enable
+A boolean
+.Dq ( YES
+or
+.Dq NO ) ,
+that specifies whether the filesystems in
+.Pa /etc/fstab. Ar JAILNAME
+are carried out. Set by ezjail to
+.Dq Li YES ,
+set to
+.Qd Li NO
+at your own risk.
+.It jail_JAILNAME_devfs_enable
+A boolean specifying whether to mount a
+.Pa /dev
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_devfs_enable ,
+or
+.Dq Li YES .
+.It jail_JAILNAME_devfs_ruleset
+The ruleset to apply when mounting a
+.Pa /dev
+filesystem inside a jail. Defaults to
+.Dq Li $ezjail_devfs_ruleset ,
+or
+.Dq Li devfsrules_jail .
+.It ezjail_JAILNAME_procfs
+A boolean specifying whether to mount a
+.Pa /proc
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_procfs_enable ,
+or
+.Dq Li YES .
+.It ezjail_JAILNAME_fdescfs
+A boolean specifying whether to mount a
+.Pa /dev/fs
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_fdescfs_enable ,
+or
+.Dq Li YES .
+.It ezjail_JAILNAME_image
+The path to the image file backing the jail, if the jail is
+file-based; or the empty string.
+.It ezjail_JAILNAME_imagetype
+The type of the image, if the jail is file-based; the empty string
+otherwise.
+.It ezjail_JAILNAME_attachparams
+The parameters to pass to the tool used to decrypt file-based,
+encrypted jails. Initialized from the
+.Fl C
+option when creating such a jail, or the empty string.
+.Ir ezjail_JAILNAME_attachblocking
+.Dq Li YES
+if the jail requires interaction with the administrator when starting
+(typically, encrypted jails that needs a password to be decrypted).
+.It ezjail_JAILNAME_forceblocking
+If
+.Dq Li YES ,
+start the jail even when it is marked as blocking.
+.It ezjail_JAILNAME_zfs_datasets
+For ZFS jails, additionnal ZFS datasets to attach to the jail when
+starting it. Taken from the
+.Fl z
+option when configuring a jail; the empty string otherwise.
+.It ezjail_JAILNAME_cpuset
+The processor set to place the jail in when starting it (see
+.Xr cpuset 1 ) .
+Taken from the
+.Fl c
+option when configuring a jail; the empty string otherwise.
+.It ezjail_JAILNAME_fib
+The network view to give to the jail (see
+.Xr setfib 1 )
+when starting it. Taken from the
+.Fl f
+option when configuring the jail; the empty string otherwise.
+.El
+.Pp
+In addition to these
+.Xr sh 1 Ns No -style
+variables, the administrator may add comment lines starting with
+.Dq PROVIDE: ,
+.Dq REQUIRE:
+and
+.Dq BEFORE: .
+These comments are used by
+.Xr rcorder 8
+to determine the order in which the jails are started. The default is
+to keep
+.Dq REQUIRE
+and
+.Dq BEFORE
+empty, meaning the jails are started in no particular order.
+.Ss Flavours
+When a jail is created, it is not configured; in particular you likely
+want to edit files such as
+.Pa /etc/resolv.conf , /etc/localtime
+and others. You may also want to create some system users, maybe
+enable
+.Xr sshd 8 .
+Ezjail solves this problem by using the concept of
+.Dq flavours .
+When a flavour is selected at jail creation time, the flavour
+directory tree is merged into the new jail's directory tree. In
+addition, the jail is configured so that on its first boot, the file
+.Pa ezjail.flavour
+is executed.
+.Pp
+As part of the install sub-command, the flavour base directory 
+was created as
+.Pa /usr/jails/flavours
+and populated with an single flavour named
+.Cm example .
+This flavour contains 3 files customized for running in a
+jail
+.Pa ( etc/make.conf , etc/periodic.conf , etc/rc.conf ) .
+The example
+.Pa ezjail.flavour
+also show how to create users, and introduce the convention of placing
+packages in
+.Pa /pkg
+that are installed when the jail is first brought up. You are
+encouraged to copy the example flavour to create your own flavour.
+Typical flavour usages include setting up jails with site-specific
+configuration, creating classes of jails for development or testing
+(such as a webdev flavour that would install Apache with your
+favourite web development framework), pre-creating local users, and so
+on.
+.Ss Updating the Base Jail
+We already mentionned how easy it is to update jails, since only one
+copy needs to be updated. Ezjail only handles updating the base
+system; updating the ports is left to the administrator (but see
+.Dq Li ports-mgmt/jailaudit
+for a way to get notified of ports in need of an update). Updates are
+handled with the
+.Nm Cm update
+command. It is possible to update the base jail from source or from
+binary packages. If a base jail already exists, the
+.Cm update
+command installs the world in a temporary directory before moving it
+to the basejail, thus leaving intact all installed libraries. After
+making sure all software running in the jails is linked with the new
+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
+.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.
+.Pp
+The
+.Nm Cm start
+command provides the same functionnality.
+.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
+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
+.Em norun
+(using
+.Nm Cm config Fl r Ar norun Ar jailname )
+or as blocking
+.Ss Remarks & Tips
+Jails can be either accessed from the network, for instance by using
+.Xr ssh 1 ,
+or from the host system by using the
+.Cm console
+command, which gives you an interactive shell inside the jail. It is
+also possible to edit the files of a running jail, and the
+modifications will appear immediately inside the jail environment.
+When dealing image-based, the
+.Cm config -i attach
+command allows one to access the disk of a file-based jail without starting it.
+.Pp
+Raw sockets are disallowed by default for all jails. This is not a ezjail
+restriction, but a design default of the jail command. This means the
+.Xr ping 8
+command will get
+.Dq Operation not permitted.
+error when used from inside of a jail. There are
+.Xr sysctl 3
+knobs for allowing a jail to access raw sockets, see the
+.Xr jail 8
+man page for details.
+.Pp
+Once your jail has network access, then all your normal application
+install functions are availabe, right from the jails console. In
+particular, if the ports collection was installed, it can be used as
+if from the host system. A modified
+.Pa make.conf
+file is installed by the example flavour, that enable the ports
+collection to work even with a read-only
+.Pa /usr/ports .
+.Pp
+It is possible to change the IP address of a jail by editing its
+configuration file in
+.Pa EZJAIL_PREFIX/etc/ezjail
+and restarting the jail.
+.Pp
+The jails use the same network stack as the host system. In
+particular, that means that if a firewall is needed, it must be
+configured in the host system.
+.Pp
+The ezjail system (and the jails it controls) depends on the
+.Dq Li $ezjail_enable
+variable being set to
+.Dq Li YES
+in
+.Pa rc.conf .
+It is possible to set this variable to
+.Dq Li NO
+if the administrator wants to temporarily ezjail, or if she doesn't
+want the jails to be automatically started on boot.
+.Pp
+The ezjail system may be reset to a printine state by removing all its
+files, that is:
+.Bl -item -compact
+.It
+.Pa /usr/jails/
+.It
+.Pa EZJAIL_PREFIX/etc/ezjail/
+.It
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.It
+.Pa /etc/fstab.* No (but check the list of files this matches)
+.El
+.Sh EXAMPLES
+The examples below are only that, examples. The reader is encouraged
+to read the
+.Xr ezjail-admin 8
+man page for definitive documentation of all the options.
+.Ss Initial Binary Installation
+The ezjail system may be bootstrapped either from binary packages, or
+by building from source. The
+.Cm install
+command allow to bootstrap from binary packages, while the
+.Cm update
+deals with installations (and updates) from source.
+.Bl -tag -width indent
+.It Nm Cm install No (without any options)
+Fetch and install binaries for populating the base jail from the
+FreeBSD FTP server. If the host is not running a -RELEASE version, you
+will be asked for the release to install. Neither the man pages nor
+the source nor the ports tree are installed. Note that the FreeBSD FTP
+server is sometimes so busy the download times out. Use the
+.Fl h Ar host
+option to specify a less loaded server, or the 
+.Dq Li $ezjail_ftphost
+option in
+.Xr ezjail.conf 8 .
+.It Nm Cm install Fl ms
+Same behavior as above, except that man pages and sources are installed in the
+base jail.
+.It Nm Cm install Fl p
+Same as the first example, but use
+.Xr portsnap 8
+to fetch and extract a full FreeBSD ports tree from
+.Li portsnap.FreeBSD.org
+into the base jail. This is necessary if you plan to install ports at later
+time into service jails.
+.It Nm Cm install Fl P No (note uppercase P)
+Only fetch the current version of the ports tree, adding it to the base jail.
+This allow to either add the ports tree after the initial installation or update the ports tree in the base jail.
+.It Install from a disk image
+Mount and use a downloaded
+.Pa disc1.iso
+CDRom image file.
+.Bd -literal -offset indent
+mdconfig -a -f /usr/8.0-RELEASE-i386-disc1.iso md0
+mount -v -t cd9660 /dev/md0 /mnt
+cd /mnt/8.0-RELEASE
+ezjail-admin install -h file:// -sm
+.Ed
+.Pp
+When the installation finishes, use the following to release the
+.Pa disc1.iso
+.Pa md0
+file.
+.Bd -literal -offset indent
+cd /usr
+umount /mnt
+mdconfig -d -u md0
+.Ed
+.It Install from a local directory
+To fetch the RELEASE base files manually, create a
+.Pa .netrc
+file in your home directory and populate it with this.
+.Bd -literal -offset indent
+machine ftp2.jp.FreeBSD.org
+login anonymous
+password FBSD@home.com
+macdef init
+prompt off
+cd /pub/FreeBSD/releases/i386/8.0-RELEASE
+epsv4 off
+$ getdir base kernels manpages src
+quit
+macdef getdir
+! mkdir $i
+mreget $i/*
+.Ed
+.Pp
+Then issue this command on the command line. If the FTP download 
+times out re-issue the FTP command again to resume where it left off.
+.Bd -literal -offset indent
+mkdir /usr/8.0-RELEASE
+cd /usr/8.0-RELEASE
+ftp -v ftp2.jp.FreeBSD.org
+ezjail-admin install -h file:// -sm
+.Ed
+.Pp
+Use this option to target the 8.0-RELEASE files you FTP'ed as the source of
+the running binaries used to populate the base jail. In addition the man
+pages and sources will be installed into the base jail.
+.El
+.Ss From Source Installation and Update
+The
+.Cm update
+is used to both install or update from source the base jail, and for
+updating the base jail from binary packages.
+.Bl -tag -width indent
+.It Nm Cm update Fl b
+Build and install a world from source. The sources are taken from
+.Pa /usr/src
+(but see the
+.Fl s
+flag). This can be used both for creating the initial base jail, and
+for updating it after the host has been upgraded.
+.It Nm Cm update Fl u
+Update the base jail to the next release using
+.Xr freebsd-update 8
+(i.e. using binary packages). This may be used only to update an
+existing installation.
+.El
+.Ss Jail Creation Examples
+.Bl -tag -width indent
+.It Nm Cm create Ar www.example.com 10.0.10.1
+Create a new jail. The jail files will reside in directory
+.Pa www_example_com
+in
+.Pa /usr/jails ,
+unless the variable
+.Dq Li $ezjail_jaildir
+has been set to some other value. The jail will only be allowed to use
+the given IP address. A warning will be displayed if this IP address
+is not already configured in the host, or if some network daemon is
+already listening on this address. The name of the jail which will
+appear in the
+.Cm list
+command or which will need to be given to the
+.Cm console
+command is
+.Ar www.example.com .
+.It Nm Cm create Fl f Ar example Fl r Ar webserver www.example.com 10.0.10.2,2001:db8:1:9243::80
+Create a new jail, placing it in directory
+.Pa webserver
+instead of deriving the directory name of the jail from its host name.
+The jail will be created with the flavour
+.Ar example .
+This jail will be given two IP addressses; this is possible only since
+FreeBSD 7.2.
+.It Nm Cm create Fl i Fl s Ar 600M sandbox2 10.0.10.4
+This creates a new file-based jail having a file size of 600 megabytes
+in
+.Pa /usr/jails/sandbox2.img .
+An empty directory,
+.Pa /usr/jails/sandbox2 ,
+will be created, and used as a mount point when starting the jail.
+.It Nm Cm create Fl i Fl c Cm bde Fl s Ar 600M sandbox3 10.0.10.5
+This creates a new file based image jail, with
+.Xr gbde 4
+encryption. During the gbde creation process you are asked to enter a
+passphrase that is used as the prime seed value of the encryption
+process. Remember this passphrase, you will be asked for the
+passphrase every time sub-command start is used on this jail. As they
+require administrator interaction, jails backed by an encrypted file
+are not automatically started when the system boots.
+.El
+.Sh FILES
+.Pa EZJAIL_PREFIX/bin/ezjail-admin
+.br
+.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.br
+.Pa EZJAIL_PREFIX/share/examples/ezjail/
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail/*
+.br
+.Pa /usr/etc/fstab.*
+.Sh SEE ALSO
+.Xr ezjail-admin 8 ,
+.Xr ezjail.conf 5 ,
+.Xr jail 8 ,
+.Xr nullfs 4 .
+.Pp
+Interesting additional tools include:
+.Dq Li ports-mgmt/jailaudit .
+.Sh AUTHOR
+.An Dirk Engling 
+.Aq erdgeist@erdgeist.org .
diff --git a/man8/ezjail-admin.8 b/man8/ezjail-admin.8
new file mode 100644
index 0000000..99b3110
--- /dev/null
+++ b/man8/ezjail-admin.8
@@ -0,0 +1,606 @@
+.Dd January 15, 2011
+.Dt EZJAIL-ADMIN 8 USD
+.Os FreeBSD
+.Sh NAME
+.Nm ezjail-admin
+.Nd Administrate ezjail environment 
+.Sh SYNOPSIS
+.Nm Cm install
+.Op Fl mMpPsS
+.Op Fl h Ar host
+.Op Fl r Ar release
+.Nm
+.Cm create
+.Op Fl bx
+.Op Fl f Ar flavour
+.Op Fl r Ar jailroot
+.Op Fl a Ar archive
+.Op Fl A Ar options
+.Op Fl c Ar jailtype Fl s Ar imagesize Op Fl C Ar attachargs
+.Bk -words
+.Ar jailname ipaddress Ns Op Ar ,ipaddress2,...
+.Ek
+.Nm
+.Cm console
+.Op Fl f
+.Op Fl e Ar command
+.Ar jailname
+.Nm
+.Cm list
+.Nm
+.Cm start | stop | restart | cryptostart Ar jailname...
+.Nm
+.Cm config
+.Op Fl r Ar run | norun
+.Op Fl n Ar newname
+.Op Fl i Ar attach | detach | fsck
+.Op Fl z Ar newdataset
+.Op Fl c Ar newcpuset
+.Op Fl f Ar newfib
+.Ar jailname
+.Nm
+.Cm delete
+.Op Fl wf
+.Ar jailname
+.Nm
+.Cm archive
+.Op Fl Af
+.Op Fl a Ar archive
+.Op Fl d Ar archivedir
+.Ar jailname...
+.Nm
+.Cm restore
+.Op Fl f
+.Op Fl d Ar archivedir
+.Ar archive | jailname...
+.Nm
+.Cm update
+.Op Fl s Ar sourcetree
+.Op Fl p
+.Fl b | Fl i | Fl P | Fl u
+.Sh DESCRIPTION
+The
+.Nm
+utility is used to manage the ezjail environment and all the jails inside the
+ezjail scope. This man page describes the invocation of
+.Nm .
+Refer to
+.Xr ezjail 7
+in order to get an introduction to the usage of ezjail, as well as
+usage examples.
+.Pp
+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.
+.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
+the base jail using the minimal distribution set from a FreeBSD FTP server.
+.Pp
+The default location for ezjail's basejail is in
+.Pa /usr/jails ,
+so be sure you have enough space there (a FreeBSD base release without man
+pages, sources and ports is around 120MB). This location may be modified in
+.Xr ezjail.conf 5 .
+.Pp
+See also
+.Nm
+.Cm update
+to install the base jail from source, as well as a method to update
+the base jail using
+.Xr freebsd-update 8 .
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl m
+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.
+.It Fl s
+Fetch and install sources (ca. 450MB).
+.It Fl S
+Fetch and install sources, without (re)installing the base jail.
+.It Fl p
+Invoke the
+.Xr portsnap 8
+utility to fetch and extract a FreeBSD ports tree from
+.Li portsnap.FreeBSD.org
+(ca. 475MB). When a ports tree is added to the base jail, a modified
+.Pa make.conf
+containing reasonable values to function in the jailed environment is added to
+the new jail template so all jails created from the new jail template will
+have a working ports environment. See the appendix 
+.%B Using Portsnap
+in the
+.%B FreeBSD Handbook
+for details or
+.Xr portsnap 8 .
+.It Fl P
+Fetch and extract a ports tree, without (re)installing the base jail.
+.It Fl h Ar host
+Set the remote host to fetch FreeBSD distribution sets from. If absent the
+default host
+.Li ftp.FreeBSD.org
+is used. Variable:
+.Dq Li $ezjail_ftphost .
+.Pp
+It is possible to install from the 
+.Li disc1
+CDRom, or an extracted -RELEASE directory, by specifying the
+.Ar host
+argument as
+.Pa file://path/to/source .
+.It Fl r Ar release
+Install this release of FreeBSD in the base jail, instead of the version
+returned by
+.Dq Li uname -r
+on the host system. Note that the FreeBSD FTP servers usually provide only
+-RELEASE versions, not -STABLE nor -CURRENT versions; you will be prompted for
+confirmation when trying to install a non -RELEASE version. If you want to
+install a -CURRENT version, you may have to compile from source the base jail;
+see the
+.Nm Cm update
+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
+.Pa /usr/jails/ Ns Ar jailname
+directory tree. Jailname and IP address are mandatory parameters.
+.Pp
+When a new jail is created, a corresponding new
+.Pa /etc/fstab. Ns Ar jailname
+file is also created, with a 
+.Xr nullfs 5
+mount giving access to the base jail from the new jail.
+.Pp
+The following operands are mandatory:
+.Bl -tag -width indent
+.It Ar jailname
+The name of the jail. It is customary to use the network name of the jail,
+such as
+.Dq Li jail1.example.com
+(or maybe simply
+.Dq Li jail1 ) ,
+but really any name may be used.
+.Pp
+It is an error to have several jails of the same name.
+.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
+with commas. Previous versions of FreeBSD allowed only a single IPv4 address
+per jail.
+.Pp
+The addresses of the jail are not configured on the host.
+.Nm
+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.
+.El
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl r Ar jailroot
+Use this name as the directory name of the new jail. Without this option, it
+is derived from the jail's name. If this option is given and does not start
+with a '/', it is interpreted as relative to ezjail's root directory
+.Pa (/usr/jails
+by default). If a specified jailroot path lies outside the ezjail root
+directory, a soft link is created inside
+.Pa /usr/jails/
+pointing to the location of the newly created jail.
+.It Fl a Ar archive
+Restore a jail from an archive created with
+.Nm Cm archive .
+The archive files are kept in
+.Pa /usr/jails/archive
+by default. Use
+.Pa -
+to restore an archive from the standard input.
+.Pp
+You will probably need to tidy up things inside an ezjail if you migrate it
+between different ezjail environments. This may include (but is not limited
+to) reinstalling ports or packages for different CPUs or library versions. You
+may also need to copy some libraries from the source host's base jail.
+.Pp
+See also
+.Nm Cm restore ,
+if you only want to revert to an old jail's state from an archive on the same
+release version.
+.It Fl A Ar jailconf
+Copy the comments, in particular the
+.Dq Li PROVIDE ,
+.Dq Li REQUIRE
+and
+.Dq Li BEFORE
+lines, from this jail.
+.Pp
+XXX: This is my understanding from the code. Is that correct?
+.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.
+.It Fl f Ar flavour
+Install the requested
+.Ar flavour
+in the new jail.
+.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.
+.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
+.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
+.Xr gbde 4
+(for
+.Cm bde )
+or
+.Xr geli 8
+(for
+.Cm eli ) .
+See also the
+.Fl C
+flag when creating this kind of jail.
+.Pp
+A
+.Cm zfs
+jail is backed with a
+.Xr zfs 8
+volume, 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?
+.Pp
+In each case, the
+.Fl s
+flag is mandatory when creating such a jail. An empty directory (without the
+.Pa .img
+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.
+.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 .
+.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.
+.It Fl i
+Synonym of
+.Fl c Cm simple .
+.It Fl b
+Don't start the jail 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.
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl f
+Start the jail if it is not running yet.
+.It Fl e Ar command
+Use
+.Ar command
+instead of
+.Dq /usr/bin/login -f root .
+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 .
+.El
+.Ss Nm Cm list
+List all jails inside ezjail's scope. They are sorted by the order they start
+up, as defined by
+.Xr rcorder 1 .
+.Pp
+The first column is the status flag consisting of 2 or 3 letters. The first
+letter is the type of jail:
+.Bl -tag -width 4n -offset indent -compact
+.It Sy D
+Directory tree based jail.
+.It Sy I
+File-based jail.
+.It Sy E
+Geli encrypted file-based jail.
+.It Sy B
+Bde encrypted file-based jail.
+.It Sy Z
+ZFS filesystem-based jail.
+.El
+.Pp
+The second letter is the status of the jail:
+.Bl -tag -width 4n -offset indent -compact
+.It Sy R
+The jail is running.
+.It Sy A
+The image of the jail is mounted, but the jail is not running.
+.It Sy S
+The jail is stopped.
+.El
+.Pp
+If present, the third letter,
+.Sy N ,
+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.
+.Pp
+As this is just a shortcut to the
+.Xr rc 8
+.Cm ezjail
+script, 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.
+.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
+the jail is restarted.
+.Pp
+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
+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
+running jail may not be renamed.
+.It Fl i Cm attach | detach | fsck
+Only valid for stopped image jails. Attaching a jail means making the content
+of the root of the jail accessible from the host. No other sub-commands will
+function on an jail while its image is attached. With
+.Cm fsck ,
+the image jail is attached,
+.Xr fsck 8
+is run, then the image jail is detached. You can only fsck image based jails.
+.It Fl z Ar newdataset
+Set the given ZFS dataset to be mounted inside the jail file system
+when it is started.
+.It Fl f Ar newfib
+Change the FIB of the jail (see
+.Xr setfib 2 ) .
+.It Fl c Ar newcpuset
+Change the CPU affinity set of the jail (see
+.Xr cpuset 2 ) .
+.El
+.Ss Nm Cm delete Ar jailname
+Delete a jail. By default, this command only deletes ezjail's control file for
+the selected jail as well as
+.Pa /etc/fstab. Ns Ar jailname .
+The
+.Pa /usr/jails/ Ns Ar jailname
+directory is not deleted.
+.Pp
+.Bl -tag -width indent
+.It Fl f
+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
+.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 .
+.Bl -tag -width indent
+.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.
+.It Fl d Ar directory
+Save the archive in this directory. If this option is not given and
+.Dq Li $ezjail_archivedir
+is not set, the archive is saved in the default directory.
+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
+.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
+user.
+.Pp
+The following operand is mandatory:
+.Bl -tag -width indent
+.It Ar archive | jailname
+Restore this jail. If only the jail name is given,
+.Nm
+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
+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:
+.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.
+.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.
+.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.
+.It Fl i
+Perform a
+.Qq make installworld ,
+assuming the world has already been built.
+.It Fl u
+Use
+.Xr freebsd-update 8
+to update the basejail. Note that as 
+.Xr freebsd-update 8
+uses
+.Dq Li uname -r
+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
+.Xr portsnap 8
+utility is invoked to do the actual work.
+.El
+The following options are available:
+.Bl -tag -width indent
+.It Fl p
+Give the new basejail a copy of FreeBSD's ports tree. The
+.Xr portsnap 8
+utility is invoked to do the actual work.
+.It Fl s Ar sourcedir
+Use the sources in
+.Ar sourcedir
+instead of
+.Pa /usr/src .
+Variable:
+.Dq Li $ezjail_sourcetree .
+.El
+.Sh FILES
+.Pa EZJAIL_PREFIX/bin/ezjail-admin
+.br
+.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.br
+.Pa EZJAIL_PREFIX/share/examples/ezjail/
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail/*
+.br
+.Pa /usr/etc/fstab.*
+.Sh SEE ALSO
+.Xr ezjail 7 ,
+.Xr ezjail.conf 8 ,
+.Xr jail 8 ,
+.Xr devfs 5 ,
+.Xr fdescfs 5 ,
+.Xr procfs 5 ,
+.Xr portsnap 8 .
+.Sh AUTHOR
+.An Dirk Engling 
+.Aq erdgeist@erdgeist.org .