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