path: root/man7
diff options
authorerdgeist <>2011-01-20 21:03:50 +0000
committererdgeist <>2011-01-20 21:03:50 +0000
commit712cdc830d1456cec055ffd9a96540c047c96225 (patch)
treea9356100d7d2ee2b997037bd5f6bfc0944723c34 /man7
parent38bd97262a80fc5fb73b076115610eee501a6ea0 (diff)
New man pages, also put in new sections
Diffstat (limited to 'man7')
1 files changed, 605 insertions, 0 deletions
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
5.Cm ezjail
6.Nd Jail administration framework.
8.Nm ezjail-admin Ar command arguments...
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.
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 .
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.
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.
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.
42Typical usage of jails include separation of services, creating test
43environments, consolidation of different services on a single physical
44host, and more.
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.
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 .
59A rc script is also installed to allow the ezjail to be started
60at boot time, as
61.Pa .
62It is enabled by setting the
63.Xr rc.conf 5
65.Dq Li $ezjail_enable
67.Dq Li YES .
69.Ss The Life of an Ezjail Installation
70The base jail is first created by running
71.Nm Cm update
73.Nm Cm install .
74Example usage of this command is section
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.
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.
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
95After their creation, jails may be archived to a
96.Xr pax 1
97archive, restored, and eventually deleted.
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
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.
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.
140Image jails may also be encrypted using
141.Xr bde 4
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.
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
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
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 ,
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 ,
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 ,
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 ,
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
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
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.
259In addition to these
260.Xr sh 1 Ns No -style
261variables, the administrator may add comment lines starting with
262.Dq PROVIDE: ,
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
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
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.
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
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
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/
329takes parameters
330.Cm start , startcrypto , restart
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
342.Nm Cm start
343command provides the same functionnality.
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
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
356to set
357.Dq Li $jail_enable
358in the
359.Xr /etc/rc.conf 5
360config file.
362It is possible to set jails as either
363.Em norun
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.
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.
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 .
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.
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.
408The ezjail system (and the jails it controls) depends on the
409.Dq Li $ezjail_enable
410variable being set to
411.Dq Li YES
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.
419The ezjail system may be reset to a printine state by removing all its
420files, that is:
421.Bl -item -compact
423.Pa /usr/jails/
425.Pa EZJAIL_PREFIX/etc/ezjail/
427.Pa EZJAIL_PREFIX/etc/ezjail.conf
429.Pa /etc/fstab.* No (but check the list of files this matches)
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
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
479When the installation finishes, use the following to release the
480.Pa disc1.iso
481.Pa md0
483.Bd -literal -offset indent
484cd /usr
485umount /mnt
486mdconfig -d -u md0
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
494login anonymous
496macdef init
497prompt off
498cd /pub/FreeBSD/releases/i386/8.0-RELEASE
499epsv4 off
500$ getdir base kernels manpages src
502macdef getdir
503! mkdir $i
504mreget $i/*
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
513ezjail-admin install -h file:// -sm
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.
520.Ss From Source Installation and Update
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.
539.Ss Jail Creation Examples
540.Bl -tag -width indent
541.It Nm Cm create Ar
542Create a new jail. The jail files will reside in directory
543.Pa www_example_com
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 .
558.It Nm Cm create Fl f Ar example Fl r Ar webserver,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
567This creates a new file-based jail having a file size of 600 megabytes
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
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.
583.Sh FILES
584.Pa EZJAIL_PREFIX/bin/ezjail-admin
586.Pa EZJAIL_PREFIX/etc/rc.d/
588.Pa EZJAIL_PREFIX/etc/ezjail.conf
590.Pa EZJAIL_PREFIX/share/examples/ezjail/
592.Pa EZJAIL_PREFIX/etc/ezjail/*
594.Pa /usr/etc/fstab.*
596.Xr ezjail-admin 8 ,
597.Xr ezjail.conf 5 ,
598.Xr jail 8 ,
599.Xr nullfs 4 .
601Interesting additional tools include:
602.Dq Li ports-mgmt/jailaudit .
604.An Dirk Engling
605.Aq .