New man pages, also put in new sections

1 files changed, 606 insertions, 0 deletions

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 .