From 712cdc830d1456cec055ffd9a96540c047c96225 Mon Sep 17 00:00:00 2001 From: erdgeist Date: Thu, 20 Jan 2011 21:03:50 +0000 Subject: New man pages, also put in new sections --- Makefile | 6 +- man1/ezjail-admin.1 | 268 ----------------------- man5/ezjail.5 | 40 ---- man5/ezjail.conf.5 | 288 +++++++++++++++---------- man7/ezjail.7 | 605 +++++++++++++++++++++++++++++++++++++++++++++++++++ man8/ezjail-admin.8 | 606 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 1390 insertions(+), 423 deletions(-) delete mode 100755 man1/ezjail-admin.1 delete mode 100755 man5/ezjail.5 create mode 100644 man7/ezjail.7 create mode 100644 man8/ezjail-admin.8 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 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 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 +.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 . -- cgit v1.2.3