summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorerdgeist <erdgeist@erdgeist.org>2011-01-20 21:03:50 +0000
committererdgeist <erdgeist@erdgeist.org>2011-01-20 21:03:50 +0000
commit712cdc830d1456cec055ffd9a96540c047c96225 (patch)
treea9356100d7d2ee2b997037bd5f6bfc0944723c34
parent38bd97262a80fc5fb73b076115610eee501a6ea0 (diff)
New man pages, also put in new sections
-rwxr-xr-xMakefile6
-rwxr-xr-xman1/ezjail-admin.1268
-rwxr-xr-xman5/ezjail.540
-rwxr-xr-xman5/ezjail.conf.5288
-rw-r--r--man7/ezjail.7605
-rw-r--r--man8/ezjail-admin.8606
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:
13 cp -R -p examples/nullmailer-example ${PREFIX}/share/examples/ezjail/ 13 cp -R -p examples/nullmailer-example ${PREFIX}/share/examples/ezjail/
14 sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh 14 sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
15 sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin 15 sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
16 sed s:EZJAIL_PREFIX:${PREFIX}: man1/ezjail-admin.1 > ${PREFIX}/man/man1/ezjail-admin.1 16 sed s:EZJAIL_PREFIX:${PREFIX}: man8/ezjail-admin.8 > ${PREFIX}/man/man8/ezjail-admin.8
17 sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5 17 sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
18 sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.5 > ${PREFIX}/man/man5/ezjail.5 18 sed s:EZJAIL_PREFIX:${PREFIX}: man7/ezjail.7 > ${PREFIX}/man/man7/ezjail.7
19 chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin 19 chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
20 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/ 20 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/
21 chmod 0440 ${PREFIX}/share/examples/ezjail/example/usr/local/etc/sudoers 21 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 @@
1.TH ezjail\-admin 1
2.SH NAME
3ezjail-admin \- Administrate ezjail
4.SH SYNOPSIS
5.T
6.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release]
7
8.T
9.B ezjail-admin create
10[-f flavours] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip
11
12.T
13.B ezjail-admin console\fR [-f] [-e command]\fI jailname
14
15.T
16.B ezjail-admin list
17
18.T
19.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
20
21.T
22.B ezjail-admin delete \fR[-w] \fI hostname
23
24.T
25.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]
26
27.T
28.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)...
29
30.T
31.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
32
33.SH DESCRIPTION
34The \fBezjail-admin\fR tool is used to manage the ezjail environment
35and jails inside the ezjail scope.
36
37It can also be used to start or stop and to get a console in ezjail's
38jails by proxying everything looking like
39\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
40.SH ezjail-admin install
41fetches everything needed to setup an ezjail environment from an FTP server and
42installs it.
43
44The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you
45have enough space there (a FreeBSD base without man pages, sources and ports
46is around 120MB).
47
48The -m and -s option will fetch and install man pages (ca. 10MB) and
49sources packages (ca. 450MB) respectively. The -p option invokes the
50portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
51Options -M, -P or -S behave like their lower case pendants, but they
52disable (re)installing your basejail.
53
54The default OS version is whatever uname -r returns. If this does not match
55"*-RELEASE", you will be prompted for a better guess. (Normally
56ftp-servers do not provide release candidates or CURRENT builds). You can
57use the -r option to specify a release on the command line.
58
59The default host to fetch packages from is ftp.freebsd.org; you may want to
60change this via the -h option or in ezjail.conf(5).
61
62If the specified location begins with file://, your local copy of the
63release is used. That way you can modify the install.sh scripts before
64executing them.
65
66You can later update your world from CVS or update ports with \fIezjail-admin
67update\fR or rerun this subcommand with another OS version.
68.SH ezjail-admin create
69installs a new jail inside ezjail's scope. It either copies the template
70jail or an ezjail archive to the root of that new jail, whose name and IP
71address are provided as mandatory parameters.
72
73A new entry in ezjail's config directory is created, a corresponding new
74\Fi/etc/fstab.hostname\fR allows the jail to be brought up by next
75reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
76
77If no jail root is specified via the -r option, it is derived from
78the jail's name. In this case or, if a jail root is given and does not
79start with a '/', it is interpreted relative to ezjail's root dir
80(default: \fI/usr/jails\fR). If a specified jail root lies outside the
81ezjail root dir, a soft link is created inside this root dir pointing
82to the newly created jail's location.
83
84The -i option requires a size passed via the -s option and creates a
85file-backed jail image using md(4).
86The image file is named after the jail root suffixed with \fI.img\fR.
87
88The -c options allows to generate a file-backed jail image encrypted
89via gbde or geli, it requires a size passed via the -s option.
90The image file is named after the jail root suffixed with \fI.img\fR.
91
92Starting with ZFS version 13 in FreeBSD, the -c option allows to
93create a ZFS-backed jail with an optional ZFS filesystem-quota passed
94via the -s option. The filesystem is named after the jailname.
95
96To install an ezjail archive instead of a vanilla copy of newjail use
97-a with the backup's location. Note that you will probably need to tidy
98up things inside an ezjail if you migrate it between different ezjail
99environments. This may include (but is not limited to) reinstalling ports
100or packages for different CPUs or library versions. You may also need to
101copy some libraries from the source host's basejail. Also consider using
102\fIezjail-admin restore\fR, if you only want to revert to an old jail's
103state from a backup on the same host.
104
105The -x option indicates that an ezjail already exists at the jail root.
106.B In this case nothing is copied. ezjail only updates its config.
107This is useful in situations where you just want to alter some of a
108jail's properties and called ezjail-admin delete without the -w option
109before. However, sanity checks are performed.
110
111Using the -f \fIflavour\fR option you can specify one or multiple space
112separated ezjail \fBFLAVOUR\fRs to be installed in your ezjail (e.g.
113preinstall packages, add users, configure rc). \fIflavours\fR points to
114one or more directory trees under ezjail's root dir (default:
115\fI/usr/jails/flavours\fR). If no flavours are passed, the global
116ezjail_default_flavour (default: \fI""\fR) is used. See \fBFLAVOURS\fR below
117for more details.
118
119Options for newly created jails are read from \fBezjail.conf\fR; refer to
120ezjail.conf(5) for more information.
121.SH ezjail-admin console
122Attaches your console to a jail by executing a jexec with its jid.
123
124The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
125but can be set with the -e modifier or by setting the ezjail_default_execute
126config variable. A non-running jail is not started by default. If you want
127that, force it with -f.
128.SH ezjail-admin list
129lists all jails inside ezjail's scope. They are sorted by the order they
130start up, as defined by rcorder. The list format is straightforward.
131
132A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR
133based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto
134image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
135running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
136\fIezjail-admin config\fR).
137
138The rest of the row is the jail's jid (if available), its IP address, hostname and
139root directory.
140.SH ezjail-admin config
141manages specific ezjails.
142
143You can prevent an ezjail from being run at system start with the -r norun
144option and reenable it with -r run.
145
146You can rename an ezjail by using the -n newname option. If the specified
147ezjail is an image jail and the image has its default name, the image is
148renamed as well.
149
150You can configure a cpuset(1) for the jail to use with the -c option. The setting
151will be configured and, if the jail is running, appliedto the running jail. The specification
152may include numbers separated by '-' for ranges and commas separating individual numbers.
153
154With the -z option, one or more zfs-datasets can be configured to be attached to the jail.
155You need to configure the sysctl security.jail.mount_allowed=1 and security.jail.enforce_statfs=0,
156set the jailed zfs property to on as well as "add path zfs unhide" in the devfs ruleset for the jail.
157
158You can configure an altered network view (FIB) for the jail with the -f option. For setting up FIBs, see
159setfib(1). The jail needs to be restarted after the option has been applied to take effect.
160
161You can attach image jails for administrative purposes with the -i attach
162option, and detach them with -i detach. It is not possible to run or delete
163an attached jail. You can force fscking a jail image with the -i fsck command.
164.SH ezjail-admin delete
165removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
166file, thus preventing the jail from being brought up on next reboot.
167
168If the -w (wipe) option is given, the directory pointed to by the jail
169root entry is removed as well as the soft link in ezjail's root dir.
170.SH ezjail-admin archive
171creates a backup of one, multiple or all ezjails.
172
173Unless an archive name is given via -a switch, its file name is derived from
174jailname, date and time. It is saved to a directory provided by -d switch
175or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to
176\fI.\fR .
177
178Use -A with no further parameters to archive all jails \fBor\fR specify one or more
179ezjails as parameters.
180
181Use \fIezjail-admin restore\fR or \fIezjail-admin create -a archive\fR to restore
182an archive.
183.SH ezjail-admin restore
184creates new ezjails from archived versions. It tries to collect all information
185necessary to do that without user interaction from the archives, thus allowing
186it to be run from a script.
187
188Pass one or more archives or jail names. For jail names, ezjail-admin will try to
189find the newest backup in its archive directory, as given in ezjail.conf(5), which
190defaults to \fI.\fR and can be overridden via -d.
191
192By default \fIezjail-admin restore\fR refuses to restore on a host different from
193where it was archived. Use -f to force that.
194.SH ezjail-admin update
195creates or updates ezjail's environment (aka basejail) from source. To install it
196from ftp servers, use ezjail-admin install.
197
198Depending on the parameters given, it will install the basejail from a source
199tree whose location is either provided in the \fBezjail.conf\fR config file or
200via the -s option.
201
202If the -p or -P option is given, the base jail also is given a copy of
203FreeBSDs ports tree, which is in turn linked into all newly created
204ezjails. The portsnap utility is invoked to do the actual work.
205
206If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
207be done while jails are running.
208
209If the -i (install only) option is given, \fBezjail-admin update\fR performs a
210\fImake installworld,\fR otherwise \fImake world\fR is invoked.
211
212.SH NOTES
213.B ezjail-admin update\fR uses a temporary directory to install its world to,
214thus leaving intact all installed libraries, if a base jail already exists.
215
216When using the \fBezjail-admin update\fR option, be careful to use the same
217FreeBSD source tree used to build the host system's world, or at least its
218kernel. Combining a make world in the host system with \fBezjail-admin update\fR
219is considered a good idea.
220
221When a ports tree exists in basejail, a make.conf containing reasonable
222values for having ports in jails is created in the template jail.
223.SH FLAVOURS
224.B ezjail-admin\fR provides an easy way to create many jails with similar or
225identical properties.
226
227A sample flavour config directory resides under
228.I EZJAIL_PREFIX/share/examples/ezjail/example/.\fR Some typical jail
229initialization actions are demonstrated, and you are encouraged to use it as
230a template for your flavours.
231
232If flavours are selected on jail creation, their root directories are
233copied to the new jail's root, each containing an \fI/ezjail.flavour\fR.
234When the jail starts up for the first time, these scripts are run and deleted.
235
236In its default form it will create some groups and users, change the
237ownership of some files and install all packages residing under /pkg.
238
239It allows you to add some post-install actions.
240.SH EXAMPLES
241ezjail-admin update -p
242.br
243ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12
244.br
245EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org
246.br
247EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org
248.br
249ezjail-admin delete ns.test.org
250.br
251ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
252.SH BUGS
253Due to the way ezjail handles jail config files, it is not possible to
254create multiple jails if their names are identical when piped through
255.B tr -C [:alnum:] _
256
257Sure to be others.
258.SH FILES
259.T4
260EZJAIL_PREFIX/etc/ezjail.conf
261.br
262EZJAIL_PREFIX/etc/rc.d/ezjail.sh
263.br
264EZJAIL_PREFIX/share/examples/ezjail/
265.SH "SEE ALSO"
266ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1)
267.SH AUTHOR
268Dirk 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 @@
1.TH ezjail 5
2.SH NAME
3ezjail \- A simple jail setup framework
4.SH SYNOPSIS
5EZJAIL_PREFIX/etc/rc.d/ezjail.sh
6.SH DESCRIPTION
7The ezjail framework provides a simple way to create many virtual FreeBSD
8servers by using FreeBSD's jail system. It requires little administration
9effort and aims for minimum system resource usage.
10
11If you are not familiar with the FreeBSD jail concept, please refer to
12jail(8) before continuing.
13.SH OVERVIEW
14One \fIbase jail\fR is filled with most userland binaries and libraries and
15then mounted read only into a number of stripped down jails via
16.B mount_nullfs(8)\fR - thus saving lots of inodes and memory resources.
17.SH INVOCATION
18The ezjail script \fBEZJAIL_PREFIX/etc/rc.d/ezjail.sh\fR takes parameters \fIstart,
19startcrypto, restart\fR and \fIstop\fR. It may be passed an additional list of
20jails. If no jail name is specified (usually when the script is called by
21rc.local at boot and shutdown time), all jails in ezjail's scope, except crypto
22image jails (or jails marked as blocking), are started/stopped. To start
23all crytpo image jails (or those depending on them), use the \fIstartcrypto\fR parameter.
24
25The script examines its config, attaches and mounts images, and sets
26variables for each jail in the jail_list before passing its command on
27to the \fB/etc/rc.d/jail\fR script.
28.SH NOTES
29.B ezjail.sh\fR enforces the execution of \fB/etc/rc.d/jail\fR, by
30prepending \fI"one"\fR to the start, restart, and stop commands so it is
31.B NOT NECESSARY\fR to set \fIjail_enable\fR in the \fB/etc/rc.conf\fR
32config file.
33.SH FILES
34EZJAIL_PREFIX/etc/ezjail.conf
35.br
36EZJAIL_PREFIX/etc/rc.d/ezjail.sh
37.SH "SEE ALSO"
38ezjail-admin(1), ezjail.conf(5), jail(8), mount_nullfs(8)
39.SH AUTHOR
40Dirk 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 @@
1.TH ezjail.conf 5 1.Dd January 15, 2011
2.SH NAME 2.Dt EZJAIL.CONF 5 USD
3ezjail.conf \- configuration file for ezjail script 3.Os FreeBSD
4.SH DESCRIPTION 4.Sh NAME
5.Pa ezjail.conf
6.Nd configuration file for ezjail script
7.Sh DESCRIPTION
5The file 8The file
6.B ezjail.conf 9.Pa ezjail.conf
7contains settings that control the operation of the ezjail rc script. It is 10contains settings that control the operation of the ezjail rc script. It is
8also read by the 11also read by the
9.B ezjail-admin 12.Cm ezjail-admin
10utility to figure out where it should perform its actions. 13utility to figure out where it should perform its actions. Its path is
11.SH PATH OPTIONS 14set at installation time to
12.TP 15.Pa EZJAIL_PREFIX/etc/ezjail.conf ,
13.B ezjail_jaildir (str) 16with an example file installed at
14Location of jail root directories 17.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
15.br 18.Pp
16.I default: /usr/jails 19This file is really a shell script that is sourced by the
17.TP 20.Cm ezjail-admin
18.B ezjail_jailtemplate (str) 21command at run-time.
22.Dq (str)
23denotes a string; it should be enclosed in quotes if it contains space.
24.Dq (bool)
25notes a boolean, whose possible values are
26.Dq YES
27and
28.Dq NO .
29.Sh PATH OPTIONS
30.Bl -tag -width option
31.It ezjail_jaildir (str)
32Location of jail root directories.
33.br
34Default:
35.Em /usr/jails .
36.It ezjail_jailtemplate (str)
19Location of template jail used to create a new jail 37Location of template jail used to create a new jail
20.br 38.br
21.I default: /usr/jails/newjail 39Default:
22.TP 40.Em ${ezjail_jaildir}/newjail .
23.B ezjail_jailbase (str) 41.It ezjail_jailbase (str)
24Location of base jail, the one that is mounted to all jails 42Location of base jail, the one that is mounted to all jails
25.br 43.br
26.I default: /usr/jails/basejail 44Default:
27.TP 45.Em ${ezjail_jaildir}/basejail .
28.B ezjail_sourcetree (str) 46.It ezjail_sourcetree (str)
29Location of your copy of FreeBSD's source tree (refer to the 47Location of your copy of FreeBSD's source tree (refer to the
30.B ezjail-admin(1) 48.Xr ezjail-admin 1
31utility for more information) 49utility for more information).
32.br 50.br
33.I default: /usr/src 51Default:
34.TP 52.Em /usr/src .
35.B ezjail_portscvsroot (str) 53.It ezjail_flavours_dir (str)
36Cvs root to use when checking out or updating the ports tree in base jail 54Location of the flavours, where each directory is a different flavour.
37.br 55.br
38.I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs 56Default:
39.TP 57.Em ${ezjail_jaildir}/flavours .
40.B ezjail_ftphost (str) 58.It ezjail_portscvsroot (str)
41This is where the install subcommand defaults to fetch its packages from 59CVS root to use when checking out or updating the ports tree in base jail.
42.br 60.br
43.I default: ftp.freebsd.org 61Default:
44.TP 62.Em :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs .
45.B ezjail_archivedir (str) 63.It ezjail_ftphost (str)
46This is the default archive location for the \fIezjail-admin archive\fR command. 64This is where the install subcommand defaults to fetch its packages from.
47.br 65.br
48.I default: `pwd -P` 66Default:
49.SH JAIL ADMIN OPTIONS 67.Em ftp.freebsd.org .
50.TP 68.It ezjail_archivedir (str)
51.B ezjail_default_execute (str) 69This is the default archive location for the
52This is the default command executed in a jail by ezjail-admin console. 70.Cm ezjail-admin archive
53.br 71command.
54.I default: YES 72.br
55.SH JAIL CREATION OPTIONS 73Default:
74.Em ${ezjail_jaildir}/ezjail_archives .
75.El
76.Sh JAIL ADMIN OPTIONS
77.Bl -tag -width option
78.It ezjail_default_execute (str)
79This is the default command executed in a jail by
80.Cm ezjail-admin console .
81.br
82Default:
83.Em /usr/bin/login -f root .
84.It ezjail_exec_start (str)
85The command to execute in a jail when starting it.
86.br
87Default:
88.Em /bin/sh /etc/rc .
89.El
90.Sh JAIL CREATION OPTIONS
56Default options for newly created jails. Used by the 91Default options for newly created jails. Used by the
57.B ezjail-admin(1) 92.Xr ezjail-admin 1
58utility. Be careful about disabling ezjail_mount_enable. (Refer to 93utility. Be careful about disabling
59.B ezjail-admin(1) 94.Em ezjail_mount_enable .
60for more information). 95.Bl -tag -width option
61.TP 96.It ezjail_mount_enable (bool)
62.B ezjail_mount_enable (bool) 97Controls whether
63Controls whether /etc/fstab.hostname should be executed at jail startup 98.Pa /etc/fstab. Ar hostname
64time. 99should be executed at jail startup time.
65.br 100.br
66.I default: "YES" 101Default:
67.TP 102.Em YES .
68.B ezjail_devfs_enable (bool) 103.It ezjail_devfs_enable (bool)
69Controls whether newly created jails are given a working 104Controls whether newly created jails are given a working
70.I /dev 105.Pa /dev
71directory. (Refer to 106directory. (Refer to
72.B devfs(5) 107.Xr devfs 5
73and 108and
74.B jail(8) 109.Xr jail 8
75for more information). 110for more information).
76.br 111.br
77.I default: "YES" 112Default:
78.TP 113.Em YES .
79.B ezjail_devfs_ruleset (str) 114.It ezjail_devfs_ruleset (str)
80Specifies which devfs ruleset should apply for newly created jails. 115Specifies which devfs ruleset should apply for newly created jails.
81(Refer to 116(Refer to
82.B devfs(5) 117.Xr devfs 5
83and 118and
84.N jail(8) 119.Xr jail 8
85for more information). 120for more information).
86.br 121.br
87.I default: "devfsrules_jail" 122Default:
88.TP 123.Em devfsrules_jail .
89.B ezjail_procfs_enable (bool) 124.It ezjail_procfs_enable (bool)
90Controls whether newly created jails are given a working 125Controls whether newly created jails are given a working
91.I /proc 126.Pa /proc
92directory. (Refer to 127directory. (Refer to
93.B procfs(5) 128.Xr procfs 5
94and 129and
95.B jail(8) 130.Xr jail (8)
96for more information). 131for more information).
97.br 132.br
98.I default: "YES" 133Default:
99.TP 134.Em YES .
100.B ezjail_fdescfs_enable (bool) 135.It ezjail_fdescfs_enable (bool)
101Controls whether newly created jails are given a working 136Controls whether newly created jails are given a working
102.I /dev/fd/ 137.Pa /dev/fd/
103directory. (Refer to 138directory. (Refer to
104.B fdescfs(5) 139.Xr fdescfs (5)
105and 140and
106.B jail(8) 141.Xr jail (8)
107for more information). 142for more information).
108.br 143.br
109.I default: "YES" 144Default:
110.TP 145.Em YES .
111.B ezjail_uglyperlhack (bool) 146.It ezjail_uglyperlhack (bool)
112Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail. 147Set to YES, if ezjail should provide a soft link from
113.br 148.Pa /usr/bin/perl
114.I default: YES 149to
115.TP 150.Pa /usr/local/bin/perl
116.B ezjail_default_flavour (str) 151in base jail.
117Controls which flavours should be used for newly created jails if none are given on the command line. 152.br
118.br 153Default:
119.I default: none 154.Em YES .
120.SH ZFS OPTIONS 155.It ezjail_default_flavour (str)
121.TP 156Controls which flavours should be used for newly created jails if none
122.B ezjail_use_zfs (bool) 157are given on the command line.
123Set to YES, if ezjail should manage basejail and newjail in a seperate ZFS-datasets. 158.br
124.br 159Default:
125.I default: NO 160.Em none .
126.TP 161.It ezjail_imagetype (one of simple, bde, eli, zfs)
127.B ezjail_jailzfs (str) 162Type of jail to create when creating a jail with the
128The 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. 163.Fl i
129.br 164flag without specifying the type explicitely.
130.I default: none 165.br
131.TP 166Default:
132.B ezjail_zfs_properties (str) 167.Em simple
133Default properties ZFS will use for creating datasets. See zfs(1m) for details. ADVANCED, be very careful! 168.El
134.br 169.Sh ZFS OPTIONS
135.I default: none 170.Bl -tag -width option
136.SH FILES 171.It ezjail_use_zfs (bool)
172Set to YES, if ezjail should manage basejail and newjail in a seperate
173ZFS-datasets.
174.br
175Default:
176.Em NO .
177.It ezjail_jailzfs (str)
178The name of the parent ZFS-dataset which ezjail will use to create
179jails on. It will be mounted in
180.Em ezjail_jaildir .
181Setting this will automaticly enable ezjail managing jails in seperate
182ZFS-datasets.
183.br
184Default:
185.Em none .
186.It ezjail_zfs_properties (str)
187Default properties ZFS will use for creating datasets. See
188.Xr zfs 1m
189for details. ADVANCED, be very careful!
190.br
191Default:
192.Em none .
193.El
194.Sh FILES
137EZJAIL_PREFIX/etc/ezjail.conf 195EZJAIL_PREFIX/etc/ezjail.conf
138.br 196.br
139EZJAIL_PREFIX/etc/rc.d/ezjail.sh 197EZJAIL_PREFIX/etc/rc.d/ezjail.sh
140.SH "SEE ALSO" 198.Sh SEE ALSO
141ezjail-admin(1), ezjail(5), jail(8), devfs(5), fdescfs(5), procfs(5) 199.Xr ezjail-admin 1 ,
142.SH AUTHOR 200.Xr ezjail 5 ,
143Dirk Engling <erdgeist@erdgeist.org> 201.Xr jail 8 ,
202.Xr devfs 5 ,
203.Xr fdescfs 5 ,
204.Xr procfs 5 .
205.Sh AUTHOR
206Dirk Engling
207.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 @@
1.Dd January 15, 2011
2.Dt EZJAIL 7 USD
3.Os
4.Sh NAME
5.Cm ezjail
6.Nd Jail administration framework.
7.Sh SYNOPSIS
8.Nm ezjail-admin Ar command arguments...
9.Sh OVERVIEW
10The ezjail commands provides a simple way to create multiple jails
11using FreeBSD's jail system. It simplifies jail administration effort
12and minimizes jail system resource usage.
13.Pp
14If you are not familiar with the FreeBSD jail concept, please refer to
15.Xr jail 8
16before continuing. For additional design information, see the ezjail
17site at
18.Li http://erdgeist.org/arts/software/ezjail .
19.Sh DESCRIPTION
20The ezjail system enables the system administrator to create multiple
21OS-level virtualization containers called jails. Services like web
22servers, mail servers, FTP servers, are typically under frequent attack
23from the public Internet and are exposed to possible compromise. The
24typical usage of jails is to run a single service in each jail and if
25that service becomes compromised the rest of the jails and the host
26system are protected from also being compromised.
27.Pp
28The major shortcoming of jails is that each jail has its own copy of
29the world. This eats disk space, inodes, and more importantly,
30prevents the sharing of binaries images between jails, thus increasing
31the memory pressure on the host system. In addition, this causes a
32major administration headache when comes the time to update the host
33system, as each jail need to be updated independently.
34.Pp
35Ezjail addresses these problems by creating a single basejail (a read-only
36.Xr nullfs 4 )
37populated with the same running binaries as the host system and them
38shares that basejail with all the other service jails created by
39ezjail. Is is possible to update the base jail (and thus all the
40jails) in a single ezjail command.
41.Pp
42Typical usage of jails include separation of services, creating test
43environments, consolidation of different services on a single physical
44host, and more.
45.Sh EZJAIL SYSTEM
46The administrative interface to the ezjail system is the
47.Xr ezjail-admin 8
48command. It is used to install the ezjail environment, create new
49jails, archive, restore, delete and update jails, open a jail console,
50and list the status of all the jails. See below for example usage, and
51refer to its man page for complete usage details.
52.Pp
53The configuration is done in the
54.Xr ezjail.conf 5
55file, which see. It will not be necessary to edit this file for most
56users. A sample file is installed as
57.Pa EZJAIL_PREFIX/etc/ezjail.conf .
58.Pp
59A rc script is also installed to allow the ezjail to be started
60at boot time, as
61.Pa ezjail.sh .
62It is enabled by setting the
63.Xr rc.conf 5
64variable
65.Dq Li $ezjail_enable
66to
67.Dq Li YES .
68.Sh WHAT'S IN A JAIL
69.Ss The Life of an Ezjail Installation
70The base jail is first created by running
71.Nm Cm update
72or
73.Nm Cm install .
74Example usage of this command is section
75.Sx EXAMPLES .
76This will create the base jail, setup a template jail used when
77setting up new jails, install an example flavour (see below),
78configure miscellaneous things.
79.Pp
80This step is necessary before using the ezjail system. In particular,
81it is not possible to create new jails without initializing the base
82jail in advance.
83.Pp
84Once the base jail has been created, new jails may be created with
85.Nm Cm create .
86A new jail is defined by its name and its IP address (or addresses).
87Creating a new jail involves copying the template jail to the new
88location, configuring
89.Xr nullfs 4
90mounts for giving access to the base jail, and little more. A jail
91that has just be created occupies about 2MB of disk space ; when
92running, only a handful of daemons (cron, syslog, sendmail mainly) use
93memory.
94.Pp
95After their creation, jails may be archived to a
96.Xr pax 1
97archive, restored, and eventually deleted.
98.Pp
99When a new version of FreeBSD is released, or when an errata is
100published, only the base jail need to be updated. Both source upgrades
101and binary upgrades (using
102.Xr freebsd-update 8 )
103are supported. The
104.Xr ports 7
105collection may also be updated by ezjail, but individual ports need to
106be upgraded individually by the administrator.
107.Ss Anatomy of a Jail
108In the ezjail system, a jail is defined by a root directory and a
109couple of configuration values, mainly a name and IP addresses. The
110root directory of the jail contains only the jail-specific files:
111configuration files, data files, and ports installed by the
112administrator. The base system is shared amongst all jails, using a
113.Xr nullfs 4
114mount. This saves space and inodes (especially when the ports
115collection in made available to the jails), and also memory, as the
116kernel is now able to share copies of running programs between the
117jails.
118.Pp
119Unless the variable
120.Dq Li $ezjail_jaildir
121has been set by the administrator, the root directory of the jail is
122kept in
123.Pa /usr/jails ,
124which therefore needs to reside on a partition big enough.
125.Pp
126There are also file-based jails, in which the storage space for the
127jail is kept in a file mounted with
128.Xr mdconfig 8 .
129There are two advantages to image jails. The amount of disk space
130allocated to the jail is limited, while normal jails have no bound on
131the amount of disk space they use. On the other hand, the space
132dedicated to the jail is no longer available to the host, even if the
133jail doesn't use all its allocated space. In addition, image jails
134contain a full copy of the basejail. This makes them portable between
135hosts running the same FreeBSD version as the image was created with.
136Of course, the jail now needs to be updated independently from all
137other jails, and there is no longer any sharing of common files
138between the jails.
139.Pp
140Image jails may also be encrypted using
141.Xr bde 4
142or
143.Xr geli 8 ,
144depending on the options given at creation time.
145.Ss Per-Jail options
146As we saw earlier, a jail is described by a file in
147.Pa EZJAIL_PREFIX/etc/ezjail/ .
148This file has the same name as the jail it configures. It is a set of
149variables interpreted by
150.Xr sh 1 ,
151much like
152.Xr rc.conf 5
153is. This file is created at the same time as the jail, and usually
154doesn't require tweaking from the administrator.
155.Pp
156In addition to the variables described below, any variable used by the
157init script
158.Pa /etc/rc.d/jail
159may be added manually by the administrator. The following variables
160are handled by ezjail, replacing JAILNAME with the actual name of the jail:
161.Bl -tag -width indent
162.It jail_JAILNAME_hostname
163The hostname of the jail. Defaults to the name of the jail, unless
164special characters needed to be stripped.
165.It jail_JAILNAME_ip
166The IP addresses the jail is allowed to use. Since FreeBSD 7.2,
167several IP addresses may be given, separated by commas.
168.It jail_JAILNAME_rootdir
169The directory holding the jail files (the directory used as a mount
170point for file-based jails). Defaults to the jail name inside
171.Dq Li $ezjail_jaildir .
172.It jail_JAILNAME_exec_start
173The command to run inside the jail when starting it. Defaults to
174.Dq Li $ezjail_exec_start
175or
176.Dq Li /bin/sh /etc/rc .
177.It jail_JAILNAME_exec_stop
178The command to run inside the jail when stopping it. Defaults to the
179empty string, which means
180.Dq Li /bin/sh /etc/rc.shutdown .
181.It jail_JAILNAME_mount_enable
182A boolean
183.Dq ( YES
184or
185.Dq NO ) ,
186that specifies whether the filesystems in
187.Pa /etc/fstab. Ar JAILNAME
188are carried out. Set by ezjail to
189.Dq Li YES ,
190set to
191.Qd Li NO
192at your own risk.
193.It jail_JAILNAME_devfs_enable
194A boolean specifying whether to mount a
195.Pa /dev
196filesystem inside the jail. Defaults to
197.Dq Li $ezjail_devfs_enable ,
198or
199.Dq Li YES .
200.It jail_JAILNAME_devfs_ruleset
201The ruleset to apply when mounting a
202.Pa /dev
203filesystem inside a jail. Defaults to
204.Dq Li $ezjail_devfs_ruleset ,
205or
206.Dq Li devfsrules_jail .
207.It ezjail_JAILNAME_procfs
208A boolean specifying whether to mount a
209.Pa /proc
210filesystem inside the jail. Defaults to
211.Dq Li $ezjail_procfs_enable ,
212or
213.Dq Li YES .
214.It ezjail_JAILNAME_fdescfs
215A boolean specifying whether to mount a
216.Pa /dev/fs
217filesystem inside the jail. Defaults to
218.Dq Li $ezjail_fdescfs_enable ,
219or
220.Dq Li YES .
221.It ezjail_JAILNAME_image
222The path to the image file backing the jail, if the jail is
223file-based; or the empty string.
224.It ezjail_JAILNAME_imagetype
225The type of the image, if the jail is file-based; the empty string
226otherwise.
227.It ezjail_JAILNAME_attachparams
228The parameters to pass to the tool used to decrypt file-based,
229encrypted jails. Initialized from the
230.Fl C
231option when creating such a jail, or the empty string.
232.Ir ezjail_JAILNAME_attachblocking
233.Dq Li YES
234if the jail requires interaction with the administrator when starting
235(typically, encrypted jails that needs a password to be decrypted).
236.It ezjail_JAILNAME_forceblocking
237If
238.Dq Li YES ,
239start the jail even when it is marked as blocking.
240.It ezjail_JAILNAME_zfs_datasets
241For ZFS jails, additionnal ZFS datasets to attach to the jail when
242starting it. Taken from the
243.Fl z
244option when configuring a jail; the empty string otherwise.
245.It ezjail_JAILNAME_cpuset
246The processor set to place the jail in when starting it (see
247.Xr cpuset 1 ) .
248Taken from the
249.Fl c
250option when configuring a jail; the empty string otherwise.
251.It ezjail_JAILNAME_fib
252The network view to give to the jail (see
253.Xr setfib 1 )
254when starting it. Taken from the
255.Fl f
256option when configuring the jail; the empty string otherwise.
257.El
258.Pp
259In addition to these
260.Xr sh 1 Ns No -style
261variables, the administrator may add comment lines starting with
262.Dq PROVIDE: ,
263.Dq REQUIRE:
264and
265.Dq BEFORE: .
266These comments are used by
267.Xr rcorder 8
268to determine the order in which the jails are started. The default is
269to keep
270.Dq REQUIRE
271and
272.Dq BEFORE
273empty, meaning the jails are started in no particular order.
274.Ss Flavours
275When a jail is created, it is not configured; in particular you likely
276want to edit files such as
277.Pa /etc/resolv.conf , /etc/localtime
278and others. You may also want to create some system users, maybe
279enable
280.Xr sshd 8 .
281Ezjail solves this problem by using the concept of
282.Dq flavours .
283When a flavour is selected at jail creation time, the flavour
284directory tree is merged into the new jail's directory tree. In
285addition, the jail is configured so that on its first boot, the file
286.Pa ezjail.flavour
287is executed.
288.Pp
289As part of the install sub-command, the flavour base directory
290was created as
291.Pa /usr/jails/flavours
292and populated with an single flavour named
293.Cm example .
294This flavour contains 3 files customized for running in a
295jail
296.Pa ( etc/make.conf , etc/periodic.conf , etc/rc.conf ) .
297The example
298.Pa ezjail.flavour
299also show how to create users, and introduce the convention of placing
300packages in
301.Pa /pkg
302that are installed when the jail is first brought up. You are
303encouraged to copy the example flavour to create your own flavour.
304Typical flavour usages include setting up jails with site-specific
305configuration, creating classes of jails for development or testing
306(such as a webdev flavour that would install Apache with your
307favourite web development framework), pre-creating local users, and so
308on.
309.Ss Updating the Base Jail
310We already mentionned how easy it is to update jails, since only one
311copy needs to be updated. Ezjail only handles updating the base
312system; updating the ports is left to the administrator (but see
313.Dq Li ports-mgmt/jailaudit
314for a way to get notified of ports in need of an update). Updates are
315handled with the
316.Nm Cm update
317command. It is possible to update the base jail from source or from
318binary packages. If a base jail already exists, the
319.Cm update
320command installs the world in a temporary directory before moving it
321to the basejail, thus leaving intact all installed libraries. After
322making sure all software running in the jails is linked with the new
323librairies, you may want to remove the old library versions. It is
324often a good idea to update the jails when a new kernel is installed
325in the host, using the same sources.
326.Ss Starting Jails
327The ezjail script
328.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
329takes parameters
330.Cm start , startcrypto , restart
331and
332.Cm stop .
333It may be passed an additional list of jails. If no jail name is
334specified (usually when the script is called by the rc system at boot
335and shutdown time), all jails in ezjail's scope, except crypto image
336jails (or jails marked as blocking), are started/stopped. To start all
337crypto image jails (or those depending on them), use the
338.Cm startcrypto
339parameter.
340.Pp
341The
342.Nm Cm start
343command provides the same functionnality.
344.Pp
345The script examines its config, attaches and mounts images, and sets
346variables for each jail in the jail_list before passing its command on
347to the
348.Pa /etc/rc.d/jail
349script.
350.Pp
351.Cm ezjail.sh
352enforces the execution of \fB/etc/rc.d/jail\fR, by prepending
353.Em one
354to the start, restart, and stop commands so it is
355.Em NOT NECESSARY
356to set
357.Dq Li $jail_enable
358in the
359.Xr /etc/rc.conf 5
360config file.
361.Pp
362It is possible to set jails as either
363.Em norun
364(using
365.Nm Cm config Fl r Ar norun Ar jailname )
366or as blocking
367.Ss Remarks & Tips
368Jails can be either accessed from the network, for instance by using
369.Xr ssh 1 ,
370or from the host system by using the
371.Cm console
372command, which gives you an interactive shell inside the jail. It is
373also possible to edit the files of a running jail, and the
374modifications will appear immediately inside the jail environment.
375When dealing image-based, the
376.Cm config -i attach
377command allows one to access the disk of a file-based jail without starting it.
378.Pp
379Raw sockets are disallowed by default for all jails. This is not a ezjail
380restriction, but a design default of the jail command. This means the
381.Xr ping 8
382command will get
383.Dq Operation not permitted.
384error when used from inside of a jail. There are
385.Xr sysctl 3
386knobs for allowing a jail to access raw sockets, see the
387.Xr jail 8
388man page for details.
389.Pp
390Once your jail has network access, then all your normal application
391install functions are availabe, right from the jails console. In
392particular, if the ports collection was installed, it can be used as
393if from the host system. A modified
394.Pa make.conf
395file is installed by the example flavour, that enable the ports
396collection to work even with a read-only
397.Pa /usr/ports .
398.Pp
399It is possible to change the IP address of a jail by editing its
400configuration file in
401.Pa EZJAIL_PREFIX/etc/ezjail
402and restarting the jail.
403.Pp
404The jails use the same network stack as the host system. In
405particular, that means that if a firewall is needed, it must be
406configured in the host system.
407.Pp
408The ezjail system (and the jails it controls) depends on the
409.Dq Li $ezjail_enable
410variable being set to
411.Dq Li YES
412in
413.Pa rc.conf .
414It is possible to set this variable to
415.Dq Li NO
416if the administrator wants to temporarily ezjail, or if she doesn't
417want the jails to be automatically started on boot.
418.Pp
419The ezjail system may be reset to a printine state by removing all its
420files, that is:
421.Bl -item -compact
422.It
423.Pa /usr/jails/
424.It
425.Pa EZJAIL_PREFIX/etc/ezjail/
426.It
427.Pa EZJAIL_PREFIX/etc/ezjail.conf
428.It
429.Pa /etc/fstab.* No (but check the list of files this matches)
430.El
431.Sh EXAMPLES
432The examples below are only that, examples. The reader is encouraged
433to read the
434.Xr ezjail-admin 8
435man page for definitive documentation of all the options.
436.Ss Initial Binary Installation
437The ezjail system may be bootstrapped either from binary packages, or
438by building from source. The
439.Cm install
440command allow to bootstrap from binary packages, while the
441.Cm update
442deals with installations (and updates) from source.
443.Bl -tag -width indent
444.It Nm Cm install No (without any options)
445Fetch and install binaries for populating the base jail from the
446FreeBSD FTP server. If the host is not running a -RELEASE version, you
447will be asked for the release to install. Neither the man pages nor
448the source nor the ports tree are installed. Note that the FreeBSD FTP
449server is sometimes so busy the download times out. Use the
450.Fl h Ar host
451option to specify a less loaded server, or the
452.Dq Li $ezjail_ftphost
453option in
454.Xr ezjail.conf 8 .
455.It Nm Cm install Fl ms
456Same behavior as above, except that man pages and sources are installed in the
457base jail.
458.It Nm Cm install Fl p
459Same as the first example, but use
460.Xr portsnap 8
461to fetch and extract a full FreeBSD ports tree from
462.Li portsnap.FreeBSD.org
463into the base jail. This is necessary if you plan to install ports at later
464time into service jails.
465.It Nm Cm install Fl P No (note uppercase P)
466Only fetch the current version of the ports tree, adding it to the base jail.
467This allow to either add the ports tree after the initial installation or update the ports tree in the base jail.
468.It Install from a disk image
469Mount and use a downloaded
470.Pa disc1.iso
471CDRom image file.
472.Bd -literal -offset indent
473mdconfig -a -f /usr/8.0-RELEASE-i386-disc1.iso md0
474mount -v -t cd9660 /dev/md0 /mnt
475cd /mnt/8.0-RELEASE
476ezjail-admin install -h file:// -sm
477.Ed
478.Pp
479When the installation finishes, use the following to release the
480.Pa disc1.iso
481.Pa md0
482file.
483.Bd -literal -offset indent
484cd /usr
485umount /mnt
486mdconfig -d -u md0
487.Ed
488.It Install from a local directory
489To fetch the RELEASE base files manually, create a
490.Pa .netrc
491file in your home directory and populate it with this.
492.Bd -literal -offset indent
493machine ftp2.jp.FreeBSD.org
494login anonymous
495password FBSD@home.com
496macdef init
497prompt off
498cd /pub/FreeBSD/releases/i386/8.0-RELEASE
499epsv4 off
500$ getdir base kernels manpages src
501quit
502macdef getdir
503! mkdir $i
504mreget $i/*
505.Ed
506.Pp
507Then issue this command on the command line. If the FTP download
508times out re-issue the FTP command again to resume where it left off.
509.Bd -literal -offset indent
510mkdir /usr/8.0-RELEASE
511cd /usr/8.0-RELEASE
512ftp -v ftp2.jp.FreeBSD.org
513ezjail-admin install -h file:// -sm
514.Ed
515.Pp
516Use this option to target the 8.0-RELEASE files you FTP'ed as the source of
517the running binaries used to populate the base jail. In addition the man
518pages and sources will be installed into the base jail.
519.El
520.Ss From Source Installation and Update
521The
522.Cm update
523is used to both install or update from source the base jail, and for
524updating the base jail from binary packages.
525.Bl -tag -width indent
526.It Nm Cm update Fl b
527Build and install a world from source. The sources are taken from
528.Pa /usr/src
529(but see the
530.Fl s
531flag). This can be used both for creating the initial base jail, and
532for updating it after the host has been upgraded.
533.It Nm Cm update Fl u
534Update the base jail to the next release using
535.Xr freebsd-update 8
536(i.e. using binary packages). This may be used only to update an
537existing installation.
538.El
539.Ss Jail Creation Examples
540.Bl -tag -width indent
541.It Nm Cm create Ar www.example.com 10.0.10.1
542Create a new jail. The jail files will reside in directory
543.Pa www_example_com
544in
545.Pa /usr/jails ,
546unless the variable
547.Dq Li $ezjail_jaildir
548has been set to some other value. The jail will only be allowed to use
549the given IP address. A warning will be displayed if this IP address
550is not already configured in the host, or if some network daemon is
551already listening on this address. The name of the jail which will
552appear in the
553.Cm list
554command or which will need to be given to the
555.Cm console
556command is
557.Ar www.example.com .
558.It Nm Cm create Fl f Ar example Fl r Ar webserver www.example.com 10.0.10.2,2001:db8:1:9243::80
559Create a new jail, placing it in directory
560.Pa webserver
561instead of deriving the directory name of the jail from its host name.
562The jail will be created with the flavour
563.Ar example .
564This jail will be given two IP addressses; this is possible only since
565FreeBSD 7.2.
566.It Nm Cm create Fl i Fl s Ar 600M sandbox2 10.0.10.4
567This creates a new file-based jail having a file size of 600 megabytes
568in
569.Pa /usr/jails/sandbox2.img .
570An empty directory,
571.Pa /usr/jails/sandbox2 ,
572will be created, and used as a mount point when starting the jail.
573.It Nm Cm create Fl i Fl c Cm bde Fl s Ar 600M sandbox3 10.0.10.5
574This creates a new file based image jail, with
575.Xr gbde 4
576encryption. During the gbde creation process you are asked to enter a
577passphrase that is used as the prime seed value of the encryption
578process. Remember this passphrase, you will be asked for the
579passphrase every time sub-command start is used on this jail. As they
580require administrator interaction, jails backed by an encrypted file
581are not automatically started when the system boots.
582.El
583.Sh FILES
584.Pa EZJAIL_PREFIX/bin/ezjail-admin
585.br
586.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
587.br
588.Pa EZJAIL_PREFIX/etc/ezjail.conf
589.br
590.Pa EZJAIL_PREFIX/share/examples/ezjail/
591.br
592.Pa EZJAIL_PREFIX/etc/ezjail/*
593.br
594.Pa /usr/etc/fstab.*
595.Sh SEE ALSO
596.Xr ezjail-admin 8 ,
597.Xr ezjail.conf 5 ,
598.Xr jail 8 ,
599.Xr nullfs 4 .
600.Pp
601Interesting additional tools include:
602.Dq Li ports-mgmt/jailaudit .
603.Sh AUTHOR
604.An Dirk Engling
605.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 @@
1.Dd January 15, 2011
2.Dt EZJAIL-ADMIN 8 USD
3.Os FreeBSD
4.Sh NAME
5.Nm ezjail-admin
6.Nd Administrate ezjail environment
7.Sh SYNOPSIS
8.Nm Cm install
9.Op Fl mMpPsS
10.Op Fl h Ar host
11.Op Fl r Ar release
12.Nm
13.Cm create
14.Op Fl bx
15.Op Fl f Ar flavour
16.Op Fl r Ar jailroot
17.Op Fl a Ar archive
18.Op Fl A Ar options
19.Op Fl c Ar jailtype Fl s Ar imagesize Op Fl C Ar attachargs
20.Bk -words
21.Ar jailname ipaddress Ns Op Ar ,ipaddress2,...
22.Ek
23.Nm
24.Cm console
25.Op Fl f
26.Op Fl e Ar command
27.Ar jailname
28.Nm
29.Cm list
30.Nm
31.Cm start | stop | restart | cryptostart Ar jailname...
32.Nm
33.Cm config
34.Op Fl r Ar run | norun
35.Op Fl n Ar newname
36.Op Fl i Ar attach | detach | fsck
37.Op Fl z Ar newdataset
38.Op Fl c Ar newcpuset
39.Op Fl f Ar newfib
40.Ar jailname
41.Nm
42.Cm delete
43.Op Fl wf
44.Ar jailname
45.Nm
46.Cm archive
47.Op Fl Af
48.Op Fl a Ar archive
49.Op Fl d Ar archivedir
50.Ar jailname...
51.Nm
52.Cm restore
53.Op Fl f
54.Op Fl d Ar archivedir
55.Ar archive | jailname...
56.Nm
57.Cm update
58.Op Fl s Ar sourcetree
59.Op Fl p
60.Fl b | Fl i | Fl P | Fl u
61.Sh DESCRIPTION
62The
63.Nm
64utility is used to manage the ezjail environment and all the jails inside the
65ezjail scope. This man page describes the invocation of
66.Nm .
67Refer to
68.Xr ezjail 7
69in order to get an introduction to the usage of ezjail, as well as
70usage examples.
71.Pp
72The description of some options ends with
73.Sq Variable: Dq Li $ezjail_abcd .
74This means that the default value of the option may be overridden by setting
75this variable in
76.Xr ezjail.conf 5 ,
77which see.
78.Ss Nm Cm install
79This function sub-command is normally run once in the life of the ezjail
80environment. It allocates the directory structure used by ezjail and populates
81the base jail using the minimal distribution set from a FreeBSD FTP server.
82.Pp
83The default location for ezjail's basejail is in
84.Pa /usr/jails ,
85so be sure you have enough space there (a FreeBSD base release without man
86pages, sources and ports is around 120MB). This location may be modified in
87.Xr ezjail.conf 5 .
88.Pp
89See also
90.Nm
91.Cm update
92to install the base jail from source, as well as a method to update
93the base jail using
94.Xr freebsd-update 8 .
95.Pp
96The following options are available:
97.Bl -tag -width indent
98.It Fl m
99Fetch and install man pages (ca. 10MB).
100.It Fl M
101Fetch and install man pages, without (re)installing the base jail. May be used
102to add the man pages to the base jail after the intial installation.
103.It Fl s
104Fetch and install sources (ca. 450MB).
105.It Fl S
106Fetch and install sources, without (re)installing the base jail.
107.It Fl p
108Invoke the
109.Xr portsnap 8
110utility to fetch and extract a FreeBSD ports tree from
111.Li portsnap.FreeBSD.org
112(ca. 475MB). When a ports tree is added to the base jail, a modified
113.Pa make.conf
114containing reasonable values to function in the jailed environment is added to
115the new jail template so all jails created from the new jail template will
116have a working ports environment. See the appendix
117.%B Using Portsnap
118in the
119.%B FreeBSD Handbook
120for details or
121.Xr portsnap 8 .
122.It Fl P
123Fetch and extract a ports tree, without (re)installing the base jail.
124.It Fl h Ar host
125Set the remote host to fetch FreeBSD distribution sets from. If absent the
126default host
127.Li ftp.FreeBSD.org
128is used. Variable:
129.Dq Li $ezjail_ftphost .
130.Pp
131It is possible to install from the
132.Li disc1
133CDRom, or an extracted -RELEASE directory, by specifying the
134.Ar host
135argument as
136.Pa file://path/to/source .
137.It Fl r Ar release
138Install this release of FreeBSD in the base jail, instead of the version
139returned by
140.Dq Li uname -r
141on the host system. Note that the FreeBSD FTP servers usually provide only
142-RELEASE versions, not -STABLE nor -CURRENT versions; you will be prompted for
143confirmation when trying to install a non -RELEASE version. If you want to
144install a -CURRENT version, you may have to compile from source the base jail;
145see the
146.Nm Cm update
147sub-command for this.
148.El
149.Ss Nm Cm create
150Create a new jail inside ezjail's scope. It either copies the new jail
151directory tree template or an ezjail archive directory tree to
152.Pa /usr/jails/ Ns Ar jailname
153directory tree. Jailname and IP address are mandatory parameters.
154.Pp
155When a new jail is created, a corresponding new
156.Pa /etc/fstab. Ns Ar jailname
157file is also created, with a
158.Xr nullfs 5
159mount giving access to the base jail from the new jail.
160.Pp
161The following operands are mandatory:
162.Bl -tag -width indent
163.It Ar jailname
164The name of the jail. It is customary to use the network name of the jail,
165such as
166.Dq Li jail1.example.com
167(or maybe simply
168.Dq Li jail1 ) ,
169but really any name may be used.
170.Pp
171It is an error to have several jails of the same name.
172.It Ar ipaddress Ns Op Ar ,ipaddress2,...
173The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
174assign several several IPv4 or IPv6 addresses to a jail, by separating them
175with commas. Previous versions of FreeBSD allowed only a single IPv4 address
176per jail.
177.Pp
178The addresses of the jail are not configured on the host.
179.Nm
180will display a warning if the requested address is not found on any interface,
181and the jail will probably not start.
182.Pp
183XXX: is the following relevant, except maybe the warning about dynamic
184addresses?
185.Pp
186This is the static (premanent, never changes) public internet
187routable ip address assigned to you by your ISP. If you purchased a
188continous block of static public internet routable ip address, then each
189jail could be assigned one of those individual ip address from the block.
190.Pp
191Normally phone dialup PPP access and cable providers assign
192dynamic ip address. The assigned ip address may change every time you
193dialup and with cable providers when the lease time expires or you
194reboot your system. \fBUse dynamic ip address at your own risk.\fR
195.Pp
196On the host issue 'ifconfig -a' command to see your assigned ip address.
197Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is
198the 'unit name' of the NIC card facing the public internet. You will
199also need this same ifconfig_XXX="DHCP" statement in the rc.conf of
200each jail to enable the public network for that jail.
201.Pp
202If your host is acting as a 'gateway' (IE. has a LAN behind it), you
203can provide jails for LAN access only. In this configuration your host
204/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
205the 'unit name' of the NIC card facing the private LAN
206(local-area-network), where x.x.x.x is a private ip address from the
207list of reserved non-public routable ip address. You will also need
208this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
209jail to enable the lan network for that jail.
210.El
211.Pp
212The following options are available:
213.Bl -tag -width indent
214.It Fl r Ar jailroot
215Use this name as the directory name of the new jail. Without this option, it
216is derived from the jail's name. If this option is given and does not start
217with a '/', it is interpreted as relative to ezjail's root directory
218.Pa (/usr/jails
219by default). If a specified jailroot path lies outside the ezjail root
220directory, a soft link is created inside
221.Pa /usr/jails/
222pointing to the location of the newly created jail.
223.It Fl a Ar archive
224Restore a jail from an archive created with
225.Nm Cm archive .
226The archive files are kept in
227.Pa /usr/jails/archive
228by default. Use
229.Pa -
230to restore an archive from the standard input.
231.Pp
232You will probably need to tidy up things inside an ezjail if you migrate it
233between different ezjail environments. This may include (but is not limited
234to) reinstalling ports or packages for different CPUs or library versions. You
235may also need to copy some libraries from the source host's base jail.
236.Pp
237See also
238.Nm Cm restore ,
239if you only want to revert to an old jail's state from an archive on the same
240release version.
241.It Fl A Ar jailconf
242Copy the comments, in particular the
243.Dq Li PROVIDE ,
244.Dq Li REQUIRE
245and
246.Dq Li BEFORE
247lines, from this jail.
248.Pp
249XXX: This is my understanding from the code. Is that correct?
250.It Fl x
251This flag indicates that an jail of that name already exists. In this case,
252ezjail will only update the configuration of the jail. Sanity checks are
253performed.
254.It Fl f Ar flavour
255Install the requested
256.Ar flavour
257in the new jail.
258.Pp
259This option may not be used with the
260.Fl a
261option.
262.It Fl c Cm simple | bde | eli | zfs
263Create a jail of the given type.
264.Pp
265A
266.Cm simple
267jail is backed with a single file. The jail will not be allowed to grow beyond
268its allocated size. The base jail is included in the image, making it portable
269between hosts running the same (or sufficiently close) version of FreeBSD. The
270jail will be stored in a file named
271.Ar jailname Ns Pa .img ,
272unless
273.Fl r Ar jailroot
274is given, in which case the jail is stored in
275.Ar jailroot Ns Pa .img .
276.Pp
277A
278.Cm bde No or Cm eli
279jail is a
280.Cm simple
281jail whose file has been encrypted using
282.Xr gbde 4
283(for
284.Cm bde )
285or
286.Xr geli 8
287(for
288.Cm eli ) .
289See also the
290.Fl C
291flag when creating this kind of jail.
292.Pp
293A
294.Cm zfs
295jail is backed with a
296.Xr zfs 8
297volume, whose initial quota is given with the
298.Fl s
299option. The volume is compressed using the lzjb method. The volume is created
300in the
301.Cm ezjail_jailzfs
302data set, if set in
303.Xr ezjail.conf 5 .
304.Pp
305XXX: from the code, it looks like the user needs to have done
306ezjail-admin install with ezjail_use_zfs. Is that correct?
307.Pp
308In each case, the
309.Fl s
310flag is mandatory when creating such a jail. An empty directory (without the
311.Pa .img
312suffix in the case of file-based jails) will be created and used as a mount
313point when running the jail.
314.It Fl s Ar imagesize
315Allocate this size to the jail. Without an unit, the size is in bytes. The
316valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes,
317and g/G for gigabytes. As a reference point, a newly created jail requires
3182MB.
319.Pp
320It is not possible to increase the size of file-based jails after their
321creation, short of creating a new image jail with a larger size.
322.It Fl C Ar imageopt
323Pass this argument to
324.Li gbde No or Li geli init .
325.Fl P No and Fl K
326(and
327.Fl L
328for
329.Xr gbde 4 )
330will be translated and passed to
331.Li gbde No or Li geli attach
332when starting the jail.
333.It Fl i
334Synonym of
335.Fl c Cm simple .
336.It Fl b
337Don't start the jail at boot time.
338.El
339.Ss Nm Cm console
340Attach your console to the selected jail. You are logged in as root by
341default. The command line prompt shows the name of the jail. You have to
342use the pwd command to see where in the directory tree you are. Entering
343\fBexit\fR will terminate the jail console.
344.Pp
345The following options are available:
346.Bl -tag -width indent
347.It Fl f
348Start the jail if it is not running yet.
349.It Fl e Ar command
350Use
351.Ar command
352instead of
353.Dq /usr/bin/login -f root .
354A one time change to use a different user can be accomplished by using
355.Fl e Qq Li /usr/bin/login -f user .
356Variable:
357.Dq Li $ezjail_default_execute .
358.El
359.Ss Nm Cm list
360List all jails inside ezjail's scope. They are sorted by the order they start
361up, as defined by
362.Xr rcorder 1 .
363.Pp
364The first column is the status flag consisting of 2 or 3 letters. The first
365letter is the type of jail:
366.Bl -tag -width 4n -offset indent -compact
367.It Sy D
368Directory tree based jail.
369.It Sy I
370File-based jail.
371.It Sy E
372Geli encrypted file-based jail.
373.It Sy B
374Bde encrypted file-based jail.
375.It Sy Z
376ZFS filesystem-based jail.
377.El
378.Pp
379The second letter is the status of the jail:
380.Bl -tag -width 4n -offset indent -compact
381.It Sy R
382The jail is running.
383.It Sy A
384The image of the jail is mounted, but the jail is not running.
385.It Sy S
386The jail is stopped.
387.El
388.Pp
389If present, the third letter,
390.Sy N ,
391means that the jail is not automatically started.
392.Pp
393The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
394.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ...
395Execute the given action on
396.Ar jailname ,
397or on all jails if the operand is omitted. Several jails may be specified.
398.Pp
399As this is just a shortcut to the
400.Xr rc 8
401.Cm ezjail
402script, if ezjail is not enabled in
403.Xr rc.conf 5
404with
405.Dq Li ezjail_enable= Ns Qq Li YES ,
406nothing will be done. Prefix the action with
407.Cm one
408(as in
409.Cm onestart ,
410etc.) to force the action regardless of the value of
411.Dq Li $ezjail_enable .
412.Pp
413.Cm cryptostart
414is used to start jails that use
415.Xr gbde 4
416or
417.Xr geli 8
418encryption. Those jails require interaction with the administrator
419when starting.
420.Ss Nm Cm config Ar jailname
421Manage parameters of specific ezjails. For running jails, most of the
422configuration changes described below will not be applied until the next time
423the jail is restarted.
424.Pp
425The following options are available:
426.Bl -tag -width indent
427.It Fl r Cm run | norun
428Set the jail to be automatically started or not on boot.
429.It Fl n An newname
430Rename the jail. Unless a custom root directory was given with the
431.Fl r
432flag when creating the jail, the root directory will be renamed as well. A
433running jail may not be renamed.
434.It Fl i Cm attach | detach | fsck
435Only valid for stopped image jails. Attaching a jail means making the content
436of the root of the jail accessible from the host. No other sub-commands will
437function on an jail while its image is attached. With
438.Cm fsck ,
439the image jail is attached,
440.Xr fsck 8
441is run, then the image jail is detached. You can only fsck image based jails.
442.It Fl z Ar newdataset
443Set the given ZFS dataset to be mounted inside the jail file system
444when it is started.
445.It Fl f Ar newfib
446Change the FIB of the jail (see
447.Xr setfib 2 ) .
448.It Fl c Ar newcpuset
449Change the CPU affinity set of the jail (see
450.Xr cpuset 2 ) .
451.El
452.Ss Nm Cm delete Ar jailname
453Delete a jail. By default, this command only deletes ezjail's control file for
454the selected jail as well as
455.Pa /etc/fstab. Ns Ar jailname .
456The
457.Pa /usr/jails/ Ns Ar jailname
458directory is not deleted.
459.Pp
460.Bl -tag -width indent
461.It Fl f
462Stop the jail before deleting it.
463.It Fl w
464Delete the directory or the file backing the jail.
465.El
466.Ss Nm Cm archive
467Create a backup of one, multiple or all ezjails. The specified service
468jail's root directory tree is backed up as a
469.Xr pax 1
470file. The jail needs to be stopped.
471.Pp
472See
473.Nm Cm restore
474or
475.Nm Cm create Fl a Ar archive
476to restore an archive.
477.Pp
478The basejail can not be archived. There is no ezjail function to
479delete archive files; they may be removed from the host using
480.Xr rm 1 .
481.Bl -tag -width indent
482.It Fl a Ar archivename
483Use this name for the archive file. If absent, the archive file name
484is derived from the jail name, with the date and time of the archive
485appended to the file name.
486.It Fl d Ar directory
487Save the archive in this directory. If this option is not given and
488.Dq Li $ezjail_archivedir
489is not set, the archive is saved in the default directory.
490Variable:
491.Dq Li $ezjail_archivedir .
492.It Fl f
493Archive the jail even when it is running.
494.It Fl A
495Archive all jails.
496.It Ar jailname
497Archive only this jail. This argument is mandatory if
498.Fl a
499is not given.
500.El
501.Ss Nm Cm restore
502Create new ezjails from archived versions. It tries to collect all
503information necessary to do that without user interaction from the
504user.
505.Pp
506The following operand is mandatory:
507.Bl -tag -width indent
508.It Ar archive | jailname
509Restore this jail. If only the jail name is given,
510.Nm
511will use the most recent archive file matching the name you specified.
512To restore an older version, specify the complete archive file name
513(file name with the date and time of the archive appended to it).
514.El
515The following options are available:
516.Bl -tag -width indent
517.It Fl d Ar archivedir
518Search the archive file in this directory. If this option is not given and
519.Dq Li $ezjail_archivedir
520is not set, the archive is searched in the current directory. Variable:
521.Dq Li $ezjail_archivedir .
522.It Fl f
523Restore the archive even if running on a host different from
524where it was archived. Be default,
525.Nm
526will refuse to restore an archive if the hostname, the FreeBSD version
527or the CPU architecture is modified.
528.El
529.Ss Nm Cm update
530Creates or updates ezjail's basejail from source. This performs a
531.Dq make world ; make installworld
532using the basejail's RELEASE source located at
533.Pa /usr/src
534(but see the
535.Fl s
536option). Exactly one of
537.Fl b , i , u , P
538is mandatory.
539.Pp
540See the
541.Cm install
542command to install the basejail from binary packages.
543.Pp
544Exactly one of the following operand must be specified:
545.Bl -tag -width indent
546.It Fl b
547Build and install a world from source located in the basejail.
548.It Fl i
549Perform a
550.Qq make installworld ,
551assuming the world has already been built.
552.It Fl u
553Use
554.Xr freebsd-update 8
555to update the basejail. Note that as
556.Xr freebsd-update 8
557uses
558.Dq Li uname -r
559to determine the currently running system, the base jail and the host
560need to be updated at the same time, without rebooting on the new
561kernel in the meantime.
562.Pp
563Jails that are stored in a ZFS volume are snapshot first.
564.It Fl P
565Install only the ports tree, assuming the basejail has already been
566created.This can be done while jails are running. The
567.Xr portsnap 8
568utility is invoked to do the actual work.
569.El
570The following options are available:
571.Bl -tag -width indent
572.It Fl p
573Give the new basejail a copy of FreeBSD's ports tree. The
574.Xr portsnap 8
575utility is invoked to do the actual work.
576.It Fl s Ar sourcedir
577Use the sources in
578.Ar sourcedir
579instead of
580.Pa /usr/src .
581Variable:
582.Dq Li $ezjail_sourcetree .
583.El
584.Sh FILES
585.Pa EZJAIL_PREFIX/bin/ezjail-admin
586.br
587.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
588.br
589.Pa EZJAIL_PREFIX/etc/ezjail.conf
590.br
591.Pa EZJAIL_PREFIX/share/examples/ezjail/
592.br
593.Pa EZJAIL_PREFIX/etc/ezjail/*
594.br
595.Pa /usr/etc/fstab.*
596.Sh SEE ALSO
597.Xr ezjail 7 ,
598.Xr ezjail.conf 8 ,
599.Xr jail 8 ,
600.Xr devfs 5 ,
601.Xr fdescfs 5 ,
602.Xr procfs 5 ,
603.Xr portsnap 8 .
604.Sh AUTHOR
605.An Dirk Engling
606.Aq erdgeist@erdgeist.org .