New man pages, also put in new sections
This commit is contained in:
erdgeist
parent
38bd97262a
commit
712cdc830d
6
Makefile
6
Makefile
@ -13,9 +13,9 @@ install:
|
|||||||
cp -R -p examples/nullmailer-example ${PREFIX}/share/examples/ezjail/
|
cp -R -p examples/nullmailer-example ${PREFIX}/share/examples/ezjail/
|
||||||
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
|
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
|
||||||
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
|
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
|
||||||
sed s:EZJAIL_PREFIX:${PREFIX}: man1/ezjail-admin.1 > ${PREFIX}/man/man1/ezjail-admin.1
|
sed s:EZJAIL_PREFIX:${PREFIX}: man8/ezjail-admin.8 > ${PREFIX}/man/man8/ezjail-admin.8
|
||||||
sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
|
sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
|
||||||
sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.5 > ${PREFIX}/man/man5/ezjail.5
|
sed s:EZJAIL_PREFIX:${PREFIX}: man7/ezjail.7 > ${PREFIX}/man/man7/ezjail.7
|
||||||
chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
|
chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
|
||||||
chown -R root:wheel ${PREFIX}/man/man1/ezjail-admin.1 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man5/ezjail.5 ${PREFIX}/share/examples/ezjail/
|
chown -R root:wheel ${PREFIX}/man/man8/ezjail-admin.8 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man7/ezjail.7 ${PREFIX}/share/examples/ezjail/
|
||||||
chmod 0440 ${PREFIX}/share/examples/ezjail/example/usr/local/etc/sudoers
|
chmod 0440 ${PREFIX}/share/examples/ezjail/example/usr/local/etc/sudoers
|
||||||
|
|||||||
@ -1,268 +0,0 @@
|
|||||||
.TH ezjail\-admin 1
|
|
||||||
.SH NAME
|
|
||||||
ezjail-admin \- Administrate ezjail
|
|
||||||
.SH SYNOPSIS
|
|
||||||
.T
|
|
||||||
.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release]
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin create
|
|
||||||
[-f flavours] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin console\fR [-f] [-e command]\fI jailname
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin list
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin config\fR [-r run|norun] [-n newname] [-c cpu-list] [-z zfs-dataset] [-f fib-number] [-i attach|detach|fsck]\fI jailname
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin delete \fR[-w] \fI hostname
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)...
|
|
||||||
|
|
||||||
.T
|
|
||||||
.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
|
|
||||||
|
|
||||||
.SH DESCRIPTION
|
|
||||||
The \fBezjail-admin\fR tool is used to manage the ezjail environment
|
|
||||||
and jails inside the ezjail scope.
|
|
||||||
|
|
||||||
It can also be used to start or stop and to get a console in ezjail's
|
|
||||||
jails by proxying everything looking like
|
|
||||||
\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
|
|
||||||
.SH ezjail-admin install
|
|
||||||
fetches everything needed to setup an ezjail environment from an FTP server and
|
|
||||||
installs it.
|
|
||||||
|
|
||||||
The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you
|
|
||||||
have enough space there (a FreeBSD base without man pages, sources and ports
|
|
||||||
is around 120MB).
|
|
||||||
|
|
||||||
The -m and -s option will fetch and install man pages (ca. 10MB) and
|
|
||||||
sources packages (ca. 450MB) respectively. The -p option invokes the
|
|
||||||
portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
|
|
||||||
Options -M, -P or -S behave like their lower case pendants, but they
|
|
||||||
disable (re)installing your basejail.
|
|
||||||
|
|
||||||
The default OS version is whatever uname -r returns. If this does not match
|
|
||||||
"*-RELEASE", you will be prompted for a better guess. (Normally
|
|
||||||
ftp-servers do not provide release candidates or CURRENT builds). You can
|
|
||||||
use the -r option to specify a release on the command line.
|
|
||||||
|
|
||||||
The default host to fetch packages from is ftp.freebsd.org; you may want to
|
|
||||||
change this via the -h option or in ezjail.conf(5).
|
|
||||||
|
|
||||||
If the specified location begins with file://, your local copy of the
|
|
||||||
release is used. That way you can modify the install.sh scripts before
|
|
||||||
executing them.
|
|
||||||
|
|
||||||
You can later update your world from CVS or update ports with \fIezjail-admin
|
|
||||||
update\fR or rerun this subcommand with another OS version.
|
|
||||||
.SH ezjail-admin create
|
|
||||||
installs a new jail inside ezjail's scope. It either copies the template
|
|
||||||
jail or an ezjail archive to the root of that new jail, whose name and IP
|
|
||||||
address are provided as mandatory parameters.
|
|
||||||
|
|
||||||
A new entry in ezjail's config directory is created, a corresponding new
|
|
||||||
\Fi/etc/fstab.hostname\fR allows the jail to be brought up by next
|
|
||||||
reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
|
|
||||||
|
|
||||||
If no jail root is specified via the -r option, it is derived from
|
|
||||||
the jail's name. In this case or, if a jail root is given and does not
|
|
||||||
start with a '/', it is interpreted relative to ezjail's root dir
|
|
||||||
(default: \fI/usr/jails\fR). If a specified jail root lies outside the
|
|
||||||
ezjail root dir, a soft link is created inside this root dir pointing
|
|
||||||
to the newly created jail's location.
|
|
||||||
|
|
||||||
The -i option requires a size passed via the -s option and creates a
|
|
||||||
file-backed jail image using md(4).
|
|
||||||
The image file is named after the jail root suffixed with \fI.img\fR.
|
|
||||||
|
|
||||||
The -c options allows to generate a file-backed jail image encrypted
|
|
||||||
via gbde or geli, it requires a size passed via the -s option.
|
|
||||||
The image file is named after the jail root suffixed with \fI.img\fR.
|
|
||||||
|
|
||||||
Starting with ZFS version 13 in FreeBSD, the -c option allows to
|
|
||||||
create a ZFS-backed jail with an optional ZFS filesystem-quota passed
|
|
||||||
via the -s option. The filesystem is named after the jailname.
|
|
||||||
|
|
||||||
To install an ezjail archive instead of a vanilla copy of newjail use
|
|
||||||
-a with the backup's location. Note that you will probably need to tidy
|
|
||||||
up things inside an ezjail if you migrate it between different ezjail
|
|
||||||
environments. This may include (but is not limited to) reinstalling ports
|
|
||||||
or packages for different CPUs or library versions. You may also need to
|
|
||||||
copy some libraries from the source host's basejail. Also consider using
|
|
||||||
\fIezjail-admin restore\fR, if you only want to revert to an old jail's
|
|
||||||
state from a backup on the same host.
|
|
||||||
|
|
||||||
The -x option indicates that an ezjail already exists at the jail root.
|
|
||||||
.B In this case nothing is copied. ezjail only updates its config.
|
|
||||||
This is useful in situations where you just want to alter some of a
|
|
||||||
jail's properties and called ezjail-admin delete without the -w option
|
|
||||||
before. However, sanity checks are performed.
|
|
||||||
|
|
||||||
Using the -f \fIflavour\fR option you can specify one or multiple space
|
|
||||||
separated ezjail \fBFLAVOUR\fRs to be installed in your ezjail (e.g.
|
|
||||||
preinstall packages, add users, configure rc). \fIflavours\fR points to
|
|
||||||
one or more directory trees under ezjail's root dir (default:
|
|
||||||
\fI/usr/jails/flavours\fR). If no flavours are passed, the global
|
|
||||||
ezjail_default_flavour (default: \fI""\fR) is used. See \fBFLAVOURS\fR below
|
|
||||||
for more details.
|
|
||||||
|
|
||||||
Options for newly created jails are read from \fBezjail.conf\fR; refer to
|
|
||||||
ezjail.conf(5) for more information.
|
|
||||||
.SH ezjail-admin console
|
|
||||||
Attaches your console to a jail by executing a jexec with its jid.
|
|
||||||
|
|
||||||
The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
|
|
||||||
but can be set with the -e modifier or by setting the ezjail_default_execute
|
|
||||||
config variable. A non-running jail is not started by default. If you want
|
|
||||||
that, force it with -f.
|
|
||||||
.SH ezjail-admin list
|
|
||||||
lists all jails inside ezjail's scope. They are sorted by the order they
|
|
||||||
start up, as defined by rcorder. The list format is straightforward.
|
|
||||||
|
|
||||||
A status flag consisting of 2 or 3 letters, the first meaning \fB(D)irectory\fR
|
|
||||||
based, \fB(I)mage\fR based, \fB(B)de\fR crypto image based, \fB(E)li\fR crypto
|
|
||||||
image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
|
|
||||||
running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
|
|
||||||
\fIezjail-admin config\fR).
|
|
||||||
|
|
||||||
The rest of the row is the jail's jid (if available), its IP address, hostname and
|
|
||||||
root directory.
|
|
||||||
.SH ezjail-admin config
|
|
||||||
manages specific ezjails.
|
|
||||||
|
|
||||||
You can prevent an ezjail from being run at system start with the -r norun
|
|
||||||
option and reenable it with -r run.
|
|
||||||
|
|
||||||
You can rename an ezjail by using the -n newname option. If the specified
|
|
||||||
ezjail is an image jail and the image has its default name, the image is
|
|
||||||
renamed as well.
|
|
||||||
|
|
||||||
You can configure a cpuset(1) for the jail to use with the -c option. The setting
|
|
||||||
will be configured and, if the jail is running, appliedto the running jail. The specification
|
|
||||||
may include numbers separated by '-' for ranges and commas separating individual numbers.
|
|
||||||
|
|
||||||
With the -z option, one or more zfs-datasets can be configured to be attached to the jail.
|
|
||||||
You need to configure the sysctl security.jail.mount_allowed=1 and security.jail.enforce_statfs=0,
|
|
||||||
set the jailed zfs property to on as well as "add path zfs unhide" in the devfs ruleset for the jail.
|
|
||||||
|
|
||||||
You can configure an altered network view (FIB) for the jail with the -f option. For setting up FIBs, see
|
|
||||||
setfib(1). The jail needs to be restarted after the option has been applied to take effect.
|
|
||||||
|
|
||||||
You can attach image jails for administrative purposes with the -i attach
|
|
||||||
option, and detach them with -i detach. It is not possible to run or delete
|
|
||||||
an attached jail. You can force fscking a jail image with the -i fsck command.
|
|
||||||
.SH ezjail-admin delete
|
|
||||||
removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
|
|
||||||
file, thus preventing the jail from being brought up on next reboot.
|
|
||||||
|
|
||||||
If the -w (wipe) option is given, the directory pointed to by the jail
|
|
||||||
root entry is removed as well as the soft link in ezjail's root dir.
|
|
||||||
.SH ezjail-admin archive
|
|
||||||
creates a backup of one, multiple or all ezjails.
|
|
||||||
|
|
||||||
Unless an archive name is given via -a switch, its file name is derived from
|
|
||||||
jailname, date and time. It is saved to a directory provided by -d switch
|
|
||||||
or the \fIezjail_archivedir\fR variable in \fBezjail.conf\fR, and defaults to
|
|
||||||
\fI.\fR .
|
|
||||||
|
|
||||||
Use -A with no further parameters to archive all jails \fBor\fR specify one or more
|
|
||||||
ezjails as parameters.
|
|
||||||
|
|
||||||
Use \fIezjail-admin restore\fR or \fIezjail-admin create -a archive\fR to restore
|
|
||||||
an archive.
|
|
||||||
.SH ezjail-admin restore
|
|
||||||
creates new ezjails from archived versions. It tries to collect all information
|
|
||||||
necessary to do that without user interaction from the archives, thus allowing
|
|
||||||
it to be run from a script.
|
|
||||||
|
|
||||||
Pass one or more archives or jail names. For jail names, ezjail-admin will try to
|
|
||||||
find the newest backup in its archive directory, as given in ezjail.conf(5), which
|
|
||||||
defaults to \fI.\fR and can be overridden via -d.
|
|
||||||
|
|
||||||
By default \fIezjail-admin restore\fR refuses to restore on a host different from
|
|
||||||
where it was archived. Use -f to force that.
|
|
||||||
.SH ezjail-admin update
|
|
||||||
creates or updates ezjail's environment (aka basejail) from source. To install it
|
|
||||||
from ftp servers, use ezjail-admin install.
|
|
||||||
|
|
||||||
Depending on the parameters given, it will install the basejail from a source
|
|
||||||
tree whose location is either provided in the \fBezjail.conf\fR config file or
|
|
||||||
via the -s option.
|
|
||||||
|
|
||||||
If the -p or -P option is given, the base jail also is given a copy of
|
|
||||||
FreeBSDs ports tree, which is in turn linked into all newly created
|
|
||||||
ezjails. The portsnap utility is invoked to do the actual work.
|
|
||||||
|
|
||||||
If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
|
|
||||||
be done while jails are running.
|
|
||||||
|
|
||||||
If the -i (install only) option is given, \fBezjail-admin update\fR performs a
|
|
||||||
\fImake installworld,\fR otherwise \fImake world\fR is invoked.
|
|
||||||
|
|
||||||
.SH NOTES
|
|
||||||
.B ezjail-admin update\fR uses a temporary directory to install its world to,
|
|
||||||
thus leaving intact all installed libraries, if a base jail already exists.
|
|
||||||
|
|
||||||
When using the \fBezjail-admin update\fR option, be careful to use the same
|
|
||||||
FreeBSD source tree used to build the host system's world, or at least its
|
|
||||||
kernel. Combining a make world in the host system with \fBezjail-admin update\fR
|
|
||||||
is considered a good idea.
|
|
||||||
|
|
||||||
When a ports tree exists in basejail, a make.conf containing reasonable
|
|
||||||
values for having ports in jails is created in the template jail.
|
|
||||||
.SH FLAVOURS
|
|
||||||
.B ezjail-admin\fR provides an easy way to create many jails with similar or
|
|
||||||
identical properties.
|
|
||||||
|
|
||||||
A sample flavour config directory resides under
|
|
||||||
.I EZJAIL_PREFIX/share/examples/ezjail/example/.\fR Some typical jail
|
|
||||||
initialization actions are demonstrated, and you are encouraged to use it as
|
|
||||||
a template for your flavours.
|
|
||||||
|
|
||||||
If flavours are selected on jail creation, their root directories are
|
|
||||||
copied to the new jail's root, each containing an \fI/ezjail.flavour\fR.
|
|
||||||
When the jail starts up for the first time, these scripts are run and deleted.
|
|
||||||
|
|
||||||
In its default form it will create some groups and users, change the
|
|
||||||
ownership of some files and install all packages residing under /pkg.
|
|
||||||
|
|
||||||
It allows you to add some post-install actions.
|
|
||||||
.SH EXAMPLES
|
|
||||||
ezjail-admin update -p
|
|
||||||
.br
|
|
||||||
ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12
|
|
||||||
.br
|
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org
|
|
||||||
.br
|
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org
|
|
||||||
.br
|
|
||||||
ezjail-admin delete ns.test.org
|
|
||||||
.br
|
|
||||||
ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
|
|
||||||
.SH BUGS
|
|
||||||
Due to the way ezjail handles jail config files, it is not possible to
|
|
||||||
create multiple jails if their names are identical when piped through
|
|
||||||
.B tr -C [:alnum:] _
|
|
||||||
|
|
||||||
Sure to be others.
|
|
||||||
.SH FILES
|
|
||||||
.T4
|
|
||||||
EZJAIL_PREFIX/etc/ezjail.conf
|
|
||||||
.br
|
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
|
||||||
.br
|
|
||||||
EZJAIL_PREFIX/share/examples/ezjail/
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1)
|
|
||||||
.SH AUTHOR
|
|
||||||
Dirk Engling <erdgeist@erdgeist.org>
|
|
||||||
@ -1,40 +0,0 @@
|
|||||||
.TH ezjail 5
|
|
||||||
.SH NAME
|
|
||||||
ezjail \- A simple jail setup framework
|
|
||||||
.SH SYNOPSIS
|
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
|
||||||
.SH DESCRIPTION
|
|
||||||
The ezjail framework provides a simple way to create many virtual FreeBSD
|
|
||||||
servers by using FreeBSD's jail system. It requires little administration
|
|
||||||
effort and aims for minimum system resource usage.
|
|
||||||
|
|
||||||
If you are not familiar with the FreeBSD jail concept, please refer to
|
|
||||||
jail(8) before continuing.
|
|
||||||
.SH OVERVIEW
|
|
||||||
One \fIbase jail\fR is filled with most userland binaries and libraries and
|
|
||||||
then mounted read only into a number of stripped down jails via
|
|
||||||
.B mount_nullfs(8)\fR - thus saving lots of inodes and memory resources.
|
|
||||||
.SH INVOCATION
|
|
||||||
The ezjail script \fBEZJAIL_PREFIX/etc/rc.d/ezjail.sh\fR takes parameters \fIstart,
|
|
||||||
startcrypto, restart\fR and \fIstop\fR. It may be passed an additional list of
|
|
||||||
jails. If no jail name is specified (usually when the script is called by
|
|
||||||
rc.local at boot and shutdown time), all jails in ezjail's scope, except crypto
|
|
||||||
image jails (or jails marked as blocking), are started/stopped. To start
|
|
||||||
all crytpo image jails (or those depending on them), use the \fIstartcrypto\fR parameter.
|
|
||||||
|
|
||||||
The script examines its config, attaches and mounts images, and sets
|
|
||||||
variables for each jail in the jail_list before passing its command on
|
|
||||||
to the \fB/etc/rc.d/jail\fR script.
|
|
||||||
.SH NOTES
|
|
||||||
.B ezjail.sh\fR enforces the execution of \fB/etc/rc.d/jail\fR, by
|
|
||||||
prepending \fI"one"\fR to the start, restart, and stop commands so it is
|
|
||||||
.B NOT NECESSARY\fR to set \fIjail_enable\fR in the \fB/etc/rc.conf\fR
|
|
||||||
config file.
|
|
||||||
.SH FILES
|
|
||||||
EZJAIL_PREFIX/etc/ezjail.conf
|
|
||||||
.br
|
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
|
||||||
.SH "SEE ALSO"
|
|
||||||
ezjail-admin(1), ezjail.conf(5), jail(8), mount_nullfs(8)
|
|
||||||
.SH AUTHOR
|
|
||||||
Dirk Engling <erdgeist@erdgeist.org>
|
|
||||||
@ -1,143 +1,207 @@
|
|||||||
.TH ezjail.conf 5
|
.Dd January 15, 2011
|
||||||
.SH NAME
|
.Dt EZJAIL.CONF 5 USD
|
||||||
ezjail.conf \- configuration file for ezjail script
|
.Os FreeBSD
|
||||||
.SH DESCRIPTION
|
.Sh NAME
|
||||||
|
.Pa ezjail.conf
|
||||||
|
.Nd configuration file for ezjail script
|
||||||
|
.Sh DESCRIPTION
|
||||||
The file
|
The file
|
||||||
.B ezjail.conf
|
.Pa ezjail.conf
|
||||||
contains settings that control the operation of the ezjail rc script. It is
|
contains settings that control the operation of the ezjail rc script. It is
|
||||||
also read by the
|
also read by the
|
||||||
.B ezjail-admin
|
.Cm ezjail-admin
|
||||||
utility to figure out where it should perform its actions.
|
utility to figure out where it should perform its actions. Its path is
|
||||||
.SH PATH OPTIONS
|
set at installation time to
|
||||||
.TP
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf ,
|
||||||
.B ezjail_jaildir (str)
|
with an example file installed at
|
||||||
Location of jail root directories
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
|
||||||
|
.Pp
|
||||||
|
This file is really a shell script that is sourced by the
|
||||||
|
.Cm ezjail-admin
|
||||||
|
command at run-time.
|
||||||
|
.Dq (str)
|
||||||
|
denotes a string; it should be enclosed in quotes if it contains space.
|
||||||
|
.Dq (bool)
|
||||||
|
notes a boolean, whose possible values are
|
||||||
|
.Dq YES
|
||||||
|
and
|
||||||
|
.Dq NO .
|
||||||
|
.Sh PATH OPTIONS
|
||||||
|
.Bl -tag -width option
|
||||||
|
.It ezjail_jaildir (str)
|
||||||
|
Location of jail root directories.
|
||||||
.br
|
.br
|
||||||
.I default: /usr/jails
|
Default:
|
||||||
.TP
|
.Em /usr/jails .
|
||||||
.B ezjail_jailtemplate (str)
|
.It ezjail_jailtemplate (str)
|
||||||
Location of template jail used to create a new jail
|
Location of template jail used to create a new jail
|
||||||
.br
|
.br
|
||||||
.I default: /usr/jails/newjail
|
Default:
|
||||||
.TP
|
.Em ${ezjail_jaildir}/newjail .
|
||||||
.B ezjail_jailbase (str)
|
.It ezjail_jailbase (str)
|
||||||
Location of base jail, the one that is mounted to all jails
|
Location of base jail, the one that is mounted to all jails
|
||||||
.br
|
.br
|
||||||
.I default: /usr/jails/basejail
|
Default:
|
||||||
.TP
|
.Em ${ezjail_jaildir}/basejail .
|
||||||
.B ezjail_sourcetree (str)
|
.It ezjail_sourcetree (str)
|
||||||
Location of your copy of FreeBSD's source tree (refer to the
|
Location of your copy of FreeBSD's source tree (refer to the
|
||||||
.B ezjail-admin(1)
|
.Xr ezjail-admin 1
|
||||||
utility for more information)
|
utility for more information).
|
||||||
.br
|
.br
|
||||||
.I default: /usr/src
|
Default:
|
||||||
.TP
|
.Em /usr/src .
|
||||||
.B ezjail_portscvsroot (str)
|
.It ezjail_flavours_dir (str)
|
||||||
Cvs root to use when checking out or updating the ports tree in base jail
|
Location of the flavours, where each directory is a different flavour.
|
||||||
.br
|
.br
|
||||||
.I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
|
Default:
|
||||||
.TP
|
.Em ${ezjail_jaildir}/flavours .
|
||||||
.B ezjail_ftphost (str)
|
.It ezjail_portscvsroot (str)
|
||||||
This is where the install subcommand defaults to fetch its packages from
|
CVS root to use when checking out or updating the ports tree in base jail.
|
||||||
.br
|
.br
|
||||||
.I default: ftp.freebsd.org
|
Default:
|
||||||
.TP
|
.Em :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs .
|
||||||
.B ezjail_archivedir (str)
|
.It ezjail_ftphost (str)
|
||||||
This is the default archive location for the \fIezjail-admin archive\fR command.
|
This is where the install subcommand defaults to fetch its packages from.
|
||||||
.br
|
.br
|
||||||
.I default: `pwd -P`
|
Default:
|
||||||
.SH JAIL ADMIN OPTIONS
|
.Em ftp.freebsd.org .
|
||||||
.TP
|
.It ezjail_archivedir (str)
|
||||||
.B ezjail_default_execute (str)
|
This is the default archive location for the
|
||||||
This is the default command executed in a jail by ezjail-admin console.
|
.Cm ezjail-admin archive
|
||||||
|
command.
|
||||||
.br
|
.br
|
||||||
.I default: YES
|
Default:
|
||||||
.SH JAIL CREATION OPTIONS
|
.Em ${ezjail_jaildir}/ezjail_archives .
|
||||||
|
.El
|
||||||
|
.Sh JAIL ADMIN OPTIONS
|
||||||
|
.Bl -tag -width option
|
||||||
|
.It ezjail_default_execute (str)
|
||||||
|
This is the default command executed in a jail by
|
||||||
|
.Cm ezjail-admin console .
|
||||||
|
.br
|
||||||
|
Default:
|
||||||
|
.Em /usr/bin/login -f root .
|
||||||
|
.It ezjail_exec_start (str)
|
||||||
|
The command to execute in a jail when starting it.
|
||||||
|
.br
|
||||||
|
Default:
|
||||||
|
.Em /bin/sh /etc/rc .
|
||||||
|
.El
|
||||||
|
.Sh JAIL CREATION OPTIONS
|
||||||
Default options for newly created jails. Used by the
|
Default options for newly created jails. Used by the
|
||||||
.B ezjail-admin(1)
|
.Xr ezjail-admin 1
|
||||||
utility. Be careful about disabling ezjail_mount_enable. (Refer to
|
utility. Be careful about disabling
|
||||||
.B ezjail-admin(1)
|
.Em ezjail_mount_enable .
|
||||||
for more information).
|
.Bl -tag -width option
|
||||||
.TP
|
.It ezjail_mount_enable (bool)
|
||||||
.B ezjail_mount_enable (bool)
|
Controls whether
|
||||||
Controls whether /etc/fstab.hostname should be executed at jail startup
|
.Pa /etc/fstab. Ar hostname
|
||||||
time.
|
should be executed at jail startup time.
|
||||||
.br
|
.br
|
||||||
.I default: "YES"
|
Default:
|
||||||
.TP
|
.Em YES .
|
||||||
.B ezjail_devfs_enable (bool)
|
.It ezjail_devfs_enable (bool)
|
||||||
Controls whether newly created jails are given a working
|
Controls whether newly created jails are given a working
|
||||||
.I /dev
|
.Pa /dev
|
||||||
directory. (Refer to
|
directory. (Refer to
|
||||||
.B devfs(5)
|
.Xr devfs 5
|
||||||
and
|
and
|
||||||
.B jail(8)
|
.Xr jail 8
|
||||||
for more information).
|
for more information).
|
||||||
.br
|
.br
|
||||||
.I default: "YES"
|
Default:
|
||||||
.TP
|
.Em YES .
|
||||||
.B ezjail_devfs_ruleset (str)
|
.It ezjail_devfs_ruleset (str)
|
||||||
Specifies which devfs ruleset should apply for newly created jails.
|
Specifies which devfs ruleset should apply for newly created jails.
|
||||||
(Refer to
|
(Refer to
|
||||||
.B devfs(5)
|
.Xr devfs 5
|
||||||
and
|
and
|
||||||
.N jail(8)
|
.Xr jail 8
|
||||||
for more information).
|
for more information).
|
||||||
.br
|
.br
|
||||||
.I default: "devfsrules_jail"
|
Default:
|
||||||
.TP
|
.Em devfsrules_jail .
|
||||||
.B ezjail_procfs_enable (bool)
|
.It ezjail_procfs_enable (bool)
|
||||||
Controls whether newly created jails are given a working
|
Controls whether newly created jails are given a working
|
||||||
.I /proc
|
.Pa /proc
|
||||||
directory. (Refer to
|
directory. (Refer to
|
||||||
.B procfs(5)
|
.Xr procfs 5
|
||||||
and
|
and
|
||||||
.B jail(8)
|
.Xr jail (8)
|
||||||
for more information).
|
for more information).
|
||||||
.br
|
.br
|
||||||
.I default: "YES"
|
Default:
|
||||||
.TP
|
.Em YES .
|
||||||
.B ezjail_fdescfs_enable (bool)
|
.It ezjail_fdescfs_enable (bool)
|
||||||
Controls whether newly created jails are given a working
|
Controls whether newly created jails are given a working
|
||||||
.I /dev/fd/
|
.Pa /dev/fd/
|
||||||
directory. (Refer to
|
directory. (Refer to
|
||||||
.B fdescfs(5)
|
.Xr fdescfs (5)
|
||||||
and
|
and
|
||||||
.B jail(8)
|
.Xr jail (8)
|
||||||
for more information).
|
for more information).
|
||||||
.br
|
.br
|
||||||
.I default: "YES"
|
Default:
|
||||||
.TP
|
.Em YES .
|
||||||
.B ezjail_uglyperlhack (bool)
|
.It ezjail_uglyperlhack (bool)
|
||||||
Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail.
|
Set to YES, if ezjail should provide a soft link from
|
||||||
|
.Pa /usr/bin/perl
|
||||||
|
to
|
||||||
|
.Pa /usr/local/bin/perl
|
||||||
|
in base jail.
|
||||||
.br
|
.br
|
||||||
.I default: YES
|
Default:
|
||||||
.TP
|
.Em YES .
|
||||||
.B ezjail_default_flavour (str)
|
.It ezjail_default_flavour (str)
|
||||||
Controls which flavours should be used for newly created jails if none are given on the command line.
|
Controls which flavours should be used for newly created jails if none
|
||||||
|
are given on the command line.
|
||||||
.br
|
.br
|
||||||
.I default: none
|
Default:
|
||||||
.SH ZFS OPTIONS
|
.Em none .
|
||||||
.TP
|
.It ezjail_imagetype (one of simple, bde, eli, zfs)
|
||||||
.B ezjail_use_zfs (bool)
|
Type of jail to create when creating a jail with the
|
||||||
Set to YES, if ezjail should manage basejail and newjail in a seperate ZFS-datasets.
|
.Fl i
|
||||||
|
flag without specifying the type explicitely.
|
||||||
.br
|
.br
|
||||||
.I default: NO
|
Default:
|
||||||
.TP
|
.Em simple
|
||||||
.B ezjail_jailzfs (str)
|
.El
|
||||||
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.
|
.Sh ZFS OPTIONS
|
||||||
|
.Bl -tag -width option
|
||||||
|
.It ezjail_use_zfs (bool)
|
||||||
|
Set to YES, if ezjail should manage basejail and newjail in a seperate
|
||||||
|
ZFS-datasets.
|
||||||
.br
|
.br
|
||||||
.I default: none
|
Default:
|
||||||
.TP
|
.Em NO .
|
||||||
.B ezjail_zfs_properties (str)
|
.It ezjail_jailzfs (str)
|
||||||
Default properties ZFS will use for creating datasets. See zfs(1m) for details. ADVANCED, be very careful!
|
The name of the parent ZFS-dataset which ezjail will use to create
|
||||||
|
jails on. It will be mounted in
|
||||||
|
.Em ezjail_jaildir .
|
||||||
|
Setting this will automaticly enable ezjail managing jails in seperate
|
||||||
|
ZFS-datasets.
|
||||||
.br
|
.br
|
||||||
.I default: none
|
Default:
|
||||||
.SH FILES
|
.Em none .
|
||||||
|
.It ezjail_zfs_properties (str)
|
||||||
|
Default properties ZFS will use for creating datasets. See
|
||||||
|
.Xr zfs 1m
|
||||||
|
for details. ADVANCED, be very careful!
|
||||||
|
.br
|
||||||
|
Default:
|
||||||
|
.Em none .
|
||||||
|
.El
|
||||||
|
.Sh FILES
|
||||||
EZJAIL_PREFIX/etc/ezjail.conf
|
EZJAIL_PREFIX/etc/ezjail.conf
|
||||||
.br
|
.br
|
||||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
||||||
.SH "SEE ALSO"
|
.Sh SEE ALSO
|
||||||
ezjail-admin(1), ezjail(5), jail(8), devfs(5), fdescfs(5), procfs(5)
|
.Xr ezjail-admin 1 ,
|
||||||
.SH AUTHOR
|
.Xr ezjail 5 ,
|
||||||
Dirk Engling <erdgeist@erdgeist.org>
|
.Xr jail 8 ,
|
||||||
|
.Xr devfs 5 ,
|
||||||
|
.Xr fdescfs 5 ,
|
||||||
|
.Xr procfs 5 .
|
||||||
|
.Sh AUTHOR
|
||||||
|
Dirk Engling
|
||||||
|
.Aq erdgeist@erdgeist.org .
|
||||||
|
|||||||
605
man7/ezjail.7
Normal file
605
man7/ezjail.7
Normal file
@ -0,0 +1,605 @@
|
|||||||
|
.Dd January 15, 2011
|
||||||
|
.Dt EZJAIL 7 USD
|
||||||
|
.Os
|
||||||
|
.Sh NAME
|
||||||
|
.Cm ezjail
|
||||||
|
.Nd Jail administration framework.
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Nm ezjail-admin Ar command arguments...
|
||||||
|
.Sh OVERVIEW
|
||||||
|
The ezjail commands provides a simple way to create multiple jails
|
||||||
|
using FreeBSD's jail system. It simplifies jail administration effort
|
||||||
|
and minimizes jail system resource usage.
|
||||||
|
.Pp
|
||||||
|
If you are not familiar with the FreeBSD jail concept, please refer to
|
||||||
|
.Xr jail 8
|
||||||
|
before continuing. For additional design information, see the ezjail
|
||||||
|
site at
|
||||||
|
.Li http://erdgeist.org/arts/software/ezjail .
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
The ezjail system enables the system administrator to create multiple
|
||||||
|
OS-level virtualization containers called jails. Services like web
|
||||||
|
servers, mail servers, FTP servers, are typically under frequent attack
|
||||||
|
from the public Internet and are exposed to possible compromise. The
|
||||||
|
typical usage of jails is to run a single service in each jail and if
|
||||||
|
that service becomes compromised the rest of the jails and the host
|
||||||
|
system are protected from also being compromised.
|
||||||
|
.Pp
|
||||||
|
The major shortcoming of jails is that each jail has its own copy of
|
||||||
|
the world. This eats disk space, inodes, and more importantly,
|
||||||
|
prevents the sharing of binaries images between jails, thus increasing
|
||||||
|
the memory pressure on the host system. In addition, this causes a
|
||||||
|
major administration headache when comes the time to update the host
|
||||||
|
system, as each jail need to be updated independently.
|
||||||
|
.Pp
|
||||||
|
Ezjail addresses these problems by creating a single basejail (a read-only
|
||||||
|
.Xr nullfs 4 )
|
||||||
|
populated with the same running binaries as the host system and them
|
||||||
|
shares that basejail with all the other service jails created by
|
||||||
|
ezjail. Is is possible to update the base jail (and thus all the
|
||||||
|
jails) in a single ezjail command.
|
||||||
|
.Pp
|
||||||
|
Typical usage of jails include separation of services, creating test
|
||||||
|
environments, consolidation of different services on a single physical
|
||||||
|
host, and more.
|
||||||
|
.Sh EZJAIL SYSTEM
|
||||||
|
The administrative interface to the ezjail system is the
|
||||||
|
.Xr ezjail-admin 8
|
||||||
|
command. It is used to install the ezjail environment, create new
|
||||||
|
jails, archive, restore, delete and update jails, open a jail console,
|
||||||
|
and list the status of all the jails. See below for example usage, and
|
||||||
|
refer to its man page for complete usage details.
|
||||||
|
.Pp
|
||||||
|
The configuration is done in the
|
||||||
|
.Xr ezjail.conf 5
|
||||||
|
file, which see. It will not be necessary to edit this file for most
|
||||||
|
users. A sample file is installed as
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf .
|
||||||
|
.Pp
|
||||||
|
A rc script is also installed to allow the ezjail to be started
|
||||||
|
at boot time, as
|
||||||
|
.Pa ezjail.sh .
|
||||||
|
It is enabled by setting the
|
||||||
|
.Xr rc.conf 5
|
||||||
|
variable
|
||||||
|
.Dq Li $ezjail_enable
|
||||||
|
to
|
||||||
|
.Dq Li YES .
|
||||||
|
.Sh WHAT'S IN A JAIL
|
||||||
|
.Ss The Life of an Ezjail Installation
|
||||||
|
The base jail is first created by running
|
||||||
|
.Nm Cm update
|
||||||
|
or
|
||||||
|
.Nm Cm install .
|
||||||
|
Example usage of this command is section
|
||||||
|
.Sx EXAMPLES .
|
||||||
|
This will create the base jail, setup a template jail used when
|
||||||
|
setting up new jails, install an example flavour (see below),
|
||||||
|
configure miscellaneous things.
|
||||||
|
.Pp
|
||||||
|
This step is necessary before using the ezjail system. In particular,
|
||||||
|
it is not possible to create new jails without initializing the base
|
||||||
|
jail in advance.
|
||||||
|
.Pp
|
||||||
|
Once the base jail has been created, new jails may be created with
|
||||||
|
.Nm Cm create .
|
||||||
|
A new jail is defined by its name and its IP address (or addresses).
|
||||||
|
Creating a new jail involves copying the template jail to the new
|
||||||
|
location, configuring
|
||||||
|
.Xr nullfs 4
|
||||||
|
mounts for giving access to the base jail, and little more. A jail
|
||||||
|
that has just be created occupies about 2MB of disk space ; when
|
||||||
|
running, only a handful of daemons (cron, syslog, sendmail mainly) use
|
||||||
|
memory.
|
||||||
|
.Pp
|
||||||
|
After their creation, jails may be archived to a
|
||||||
|
.Xr pax 1
|
||||||
|
archive, restored, and eventually deleted.
|
||||||
|
.Pp
|
||||||
|
When a new version of FreeBSD is released, or when an errata is
|
||||||
|
published, only the base jail need to be updated. Both source upgrades
|
||||||
|
and binary upgrades (using
|
||||||
|
.Xr freebsd-update 8 )
|
||||||
|
are supported. The
|
||||||
|
.Xr ports 7
|
||||||
|
collection may also be updated by ezjail, but individual ports need to
|
||||||
|
be upgraded individually by the administrator.
|
||||||
|
.Ss Anatomy of a Jail
|
||||||
|
In the ezjail system, a jail is defined by a root directory and a
|
||||||
|
couple of configuration values, mainly a name and IP addresses. The
|
||||||
|
root directory of the jail contains only the jail-specific files:
|
||||||
|
configuration files, data files, and ports installed by the
|
||||||
|
administrator. The base system is shared amongst all jails, using a
|
||||||
|
.Xr nullfs 4
|
||||||
|
mount. This saves space and inodes (especially when the ports
|
||||||
|
collection in made available to the jails), and also memory, as the
|
||||||
|
kernel is now able to share copies of running programs between the
|
||||||
|
jails.
|
||||||
|
.Pp
|
||||||
|
Unless the variable
|
||||||
|
.Dq Li $ezjail_jaildir
|
||||||
|
has been set by the administrator, the root directory of the jail is
|
||||||
|
kept in
|
||||||
|
.Pa /usr/jails ,
|
||||||
|
which therefore needs to reside on a partition big enough.
|
||||||
|
.Pp
|
||||||
|
There are also file-based jails, in which the storage space for the
|
||||||
|
jail is kept in a file mounted with
|
||||||
|
.Xr mdconfig 8 .
|
||||||
|
There are two advantages to image jails. The amount of disk space
|
||||||
|
allocated to the jail is limited, while normal jails have no bound on
|
||||||
|
the amount of disk space they use. On the other hand, the space
|
||||||
|
dedicated to the jail is no longer available to the host, even if the
|
||||||
|
jail doesn't use all its allocated space. In addition, image jails
|
||||||
|
contain a full copy of the basejail. This makes them portable between
|
||||||
|
hosts running the same FreeBSD version as the image was created with.
|
||||||
|
Of course, the jail now needs to be updated independently from all
|
||||||
|
other jails, and there is no longer any sharing of common files
|
||||||
|
between the jails.
|
||||||
|
.Pp
|
||||||
|
Image jails may also be encrypted using
|
||||||
|
.Xr bde 4
|
||||||
|
or
|
||||||
|
.Xr geli 8 ,
|
||||||
|
depending on the options given at creation time.
|
||||||
|
.Ss Per-Jail options
|
||||||
|
As we saw earlier, a jail is described by a file in
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail/ .
|
||||||
|
This file has the same name as the jail it configures. It is a set of
|
||||||
|
variables interpreted by
|
||||||
|
.Xr sh 1 ,
|
||||||
|
much like
|
||||||
|
.Xr rc.conf 5
|
||||||
|
is. This file is created at the same time as the jail, and usually
|
||||||
|
doesn't require tweaking from the administrator.
|
||||||
|
.Pp
|
||||||
|
In addition to the variables described below, any variable used by the
|
||||||
|
init script
|
||||||
|
.Pa /etc/rc.d/jail
|
||||||
|
may be added manually by the administrator. The following variables
|
||||||
|
are handled by ezjail, replacing JAILNAME with the actual name of the jail:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It jail_JAILNAME_hostname
|
||||||
|
The hostname of the jail. Defaults to the name of the jail, unless
|
||||||
|
special characters needed to be stripped.
|
||||||
|
.It jail_JAILNAME_ip
|
||||||
|
The IP addresses the jail is allowed to use. Since FreeBSD 7.2,
|
||||||
|
several IP addresses may be given, separated by commas.
|
||||||
|
.It jail_JAILNAME_rootdir
|
||||||
|
The directory holding the jail files (the directory used as a mount
|
||||||
|
point for file-based jails). Defaults to the jail name inside
|
||||||
|
.Dq Li $ezjail_jaildir .
|
||||||
|
.It jail_JAILNAME_exec_start
|
||||||
|
The command to run inside the jail when starting it. Defaults to
|
||||||
|
.Dq Li $ezjail_exec_start
|
||||||
|
or
|
||||||
|
.Dq Li /bin/sh /etc/rc .
|
||||||
|
.It jail_JAILNAME_exec_stop
|
||||||
|
The command to run inside the jail when stopping it. Defaults to the
|
||||||
|
empty string, which means
|
||||||
|
.Dq Li /bin/sh /etc/rc.shutdown .
|
||||||
|
.It jail_JAILNAME_mount_enable
|
||||||
|
A boolean
|
||||||
|
.Dq ( YES
|
||||||
|
or
|
||||||
|
.Dq NO ) ,
|
||||||
|
that specifies whether the filesystems in
|
||||||
|
.Pa /etc/fstab. Ar JAILNAME
|
||||||
|
are carried out. Set by ezjail to
|
||||||
|
.Dq Li YES ,
|
||||||
|
set to
|
||||||
|
.Qd Li NO
|
||||||
|
at your own risk.
|
||||||
|
.It jail_JAILNAME_devfs_enable
|
||||||
|
A boolean specifying whether to mount a
|
||||||
|
.Pa /dev
|
||||||
|
filesystem inside the jail. Defaults to
|
||||||
|
.Dq Li $ezjail_devfs_enable ,
|
||||||
|
or
|
||||||
|
.Dq Li YES .
|
||||||
|
.It jail_JAILNAME_devfs_ruleset
|
||||||
|
The ruleset to apply when mounting a
|
||||||
|
.Pa /dev
|
||||||
|
filesystem inside a jail. Defaults to
|
||||||
|
.Dq Li $ezjail_devfs_ruleset ,
|
||||||
|
or
|
||||||
|
.Dq Li devfsrules_jail .
|
||||||
|
.It ezjail_JAILNAME_procfs
|
||||||
|
A boolean specifying whether to mount a
|
||||||
|
.Pa /proc
|
||||||
|
filesystem inside the jail. Defaults to
|
||||||
|
.Dq Li $ezjail_procfs_enable ,
|
||||||
|
or
|
||||||
|
.Dq Li YES .
|
||||||
|
.It ezjail_JAILNAME_fdescfs
|
||||||
|
A boolean specifying whether to mount a
|
||||||
|
.Pa /dev/fs
|
||||||
|
filesystem inside the jail. Defaults to
|
||||||
|
.Dq Li $ezjail_fdescfs_enable ,
|
||||||
|
or
|
||||||
|
.Dq Li YES .
|
||||||
|
.It ezjail_JAILNAME_image
|
||||||
|
The path to the image file backing the jail, if the jail is
|
||||||
|
file-based; or the empty string.
|
||||||
|
.It ezjail_JAILNAME_imagetype
|
||||||
|
The type of the image, if the jail is file-based; the empty string
|
||||||
|
otherwise.
|
||||||
|
.It ezjail_JAILNAME_attachparams
|
||||||
|
The parameters to pass to the tool used to decrypt file-based,
|
||||||
|
encrypted jails. Initialized from the
|
||||||
|
.Fl C
|
||||||
|
option when creating such a jail, or the empty string.
|
||||||
|
.Ir ezjail_JAILNAME_attachblocking
|
||||||
|
.Dq Li YES
|
||||||
|
if the jail requires interaction with the administrator when starting
|
||||||
|
(typically, encrypted jails that needs a password to be decrypted).
|
||||||
|
.It ezjail_JAILNAME_forceblocking
|
||||||
|
If
|
||||||
|
.Dq Li YES ,
|
||||||
|
start the jail even when it is marked as blocking.
|
||||||
|
.It ezjail_JAILNAME_zfs_datasets
|
||||||
|
For ZFS jails, additionnal ZFS datasets to attach to the jail when
|
||||||
|
starting it. Taken from the
|
||||||
|
.Fl z
|
||||||
|
option when configuring a jail; the empty string otherwise.
|
||||||
|
.It ezjail_JAILNAME_cpuset
|
||||||
|
The processor set to place the jail in when starting it (see
|
||||||
|
.Xr cpuset 1 ) .
|
||||||
|
Taken from the
|
||||||
|
.Fl c
|
||||||
|
option when configuring a jail; the empty string otherwise.
|
||||||
|
.It ezjail_JAILNAME_fib
|
||||||
|
The network view to give to the jail (see
|
||||||
|
.Xr setfib 1 )
|
||||||
|
when starting it. Taken from the
|
||||||
|
.Fl f
|
||||||
|
option when configuring the jail; the empty string otherwise.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
In addition to these
|
||||||
|
.Xr sh 1 Ns No -style
|
||||||
|
variables, the administrator may add comment lines starting with
|
||||||
|
.Dq PROVIDE: ,
|
||||||
|
.Dq REQUIRE:
|
||||||
|
and
|
||||||
|
.Dq BEFORE: .
|
||||||
|
These comments are used by
|
||||||
|
.Xr rcorder 8
|
||||||
|
to determine the order in which the jails are started. The default is
|
||||||
|
to keep
|
||||||
|
.Dq REQUIRE
|
||||||
|
and
|
||||||
|
.Dq BEFORE
|
||||||
|
empty, meaning the jails are started in no particular order.
|
||||||
|
.Ss Flavours
|
||||||
|
When a jail is created, it is not configured; in particular you likely
|
||||||
|
want to edit files such as
|
||||||
|
.Pa /etc/resolv.conf , /etc/localtime
|
||||||
|
and others. You may also want to create some system users, maybe
|
||||||
|
enable
|
||||||
|
.Xr sshd 8 .
|
||||||
|
Ezjail solves this problem by using the concept of
|
||||||
|
.Dq flavours .
|
||||||
|
When a flavour is selected at jail creation time, the flavour
|
||||||
|
directory tree is merged into the new jail's directory tree. In
|
||||||
|
addition, the jail is configured so that on its first boot, the file
|
||||||
|
.Pa ezjail.flavour
|
||||||
|
is executed.
|
||||||
|
.Pp
|
||||||
|
As part of the install sub-command, the flavour base directory
|
||||||
|
was created as
|
||||||
|
.Pa /usr/jails/flavours
|
||||||
|
and populated with an single flavour named
|
||||||
|
.Cm example .
|
||||||
|
This flavour contains 3 files customized for running in a
|
||||||
|
jail
|
||||||
|
.Pa ( etc/make.conf , etc/periodic.conf , etc/rc.conf ) .
|
||||||
|
The example
|
||||||
|
.Pa ezjail.flavour
|
||||||
|
also show how to create users, and introduce the convention of placing
|
||||||
|
packages in
|
||||||
|
.Pa /pkg
|
||||||
|
that are installed when the jail is first brought up. You are
|
||||||
|
encouraged to copy the example flavour to create your own flavour.
|
||||||
|
Typical flavour usages include setting up jails with site-specific
|
||||||
|
configuration, creating classes of jails for development or testing
|
||||||
|
(such as a webdev flavour that would install Apache with your
|
||||||
|
favourite web development framework), pre-creating local users, and so
|
||||||
|
on.
|
||||||
|
.Ss Updating the Base Jail
|
||||||
|
We already mentionned how easy it is to update jails, since only one
|
||||||
|
copy needs to be updated. Ezjail only handles updating the base
|
||||||
|
system; updating the ports is left to the administrator (but see
|
||||||
|
.Dq Li ports-mgmt/jailaudit
|
||||||
|
for a way to get notified of ports in need of an update). Updates are
|
||||||
|
handled with the
|
||||||
|
.Nm Cm update
|
||||||
|
command. It is possible to update the base jail from source or from
|
||||||
|
binary packages. If a base jail already exists, the
|
||||||
|
.Cm update
|
||||||
|
command installs the world in a temporary directory before moving it
|
||||||
|
to the basejail, thus leaving intact all installed libraries. After
|
||||||
|
making sure all software running in the jails is linked with the new
|
||||||
|
librairies, you may want to remove the old library versions. It is
|
||||||
|
often a good idea to update the jails when a new kernel is installed
|
||||||
|
in the host, using the same sources.
|
||||||
|
.Ss Starting Jails
|
||||||
|
The ezjail script
|
||||||
|
.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
||||||
|
takes parameters
|
||||||
|
.Cm start , startcrypto , restart
|
||||||
|
and
|
||||||
|
.Cm stop .
|
||||||
|
It may be passed an additional list of jails. If no jail name is
|
||||||
|
specified (usually when the script is called by the rc system at boot
|
||||||
|
and shutdown time), all jails in ezjail's scope, except crypto image
|
||||||
|
jails (or jails marked as blocking), are started/stopped. To start all
|
||||||
|
crypto image jails (or those depending on them), use the
|
||||||
|
.Cm startcrypto
|
||||||
|
parameter.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Nm Cm start
|
||||||
|
command provides the same functionnality.
|
||||||
|
.Pp
|
||||||
|
The script examines its config, attaches and mounts images, and sets
|
||||||
|
variables for each jail in the jail_list before passing its command on
|
||||||
|
to the
|
||||||
|
.Pa /etc/rc.d/jail
|
||||||
|
script.
|
||||||
|
.Pp
|
||||||
|
.Cm ezjail.sh
|
||||||
|
enforces the execution of \fB/etc/rc.d/jail\fR, by prepending
|
||||||
|
.Em one
|
||||||
|
to the start, restart, and stop commands so it is
|
||||||
|
.Em NOT NECESSARY
|
||||||
|
to set
|
||||||
|
.Dq Li $jail_enable
|
||||||
|
in the
|
||||||
|
.Xr /etc/rc.conf 5
|
||||||
|
config file.
|
||||||
|
.Pp
|
||||||
|
It is possible to set jails as either
|
||||||
|
.Em norun
|
||||||
|
(using
|
||||||
|
.Nm Cm config Fl r Ar norun Ar jailname )
|
||||||
|
or as blocking
|
||||||
|
.Ss Remarks & Tips
|
||||||
|
Jails can be either accessed from the network, for instance by using
|
||||||
|
.Xr ssh 1 ,
|
||||||
|
or from the host system by using the
|
||||||
|
.Cm console
|
||||||
|
command, which gives you an interactive shell inside the jail. It is
|
||||||
|
also possible to edit the files of a running jail, and the
|
||||||
|
modifications will appear immediately inside the jail environment.
|
||||||
|
When dealing image-based, the
|
||||||
|
.Cm config -i attach
|
||||||
|
command allows one to access the disk of a file-based jail without starting it.
|
||||||
|
.Pp
|
||||||
|
Raw sockets are disallowed by default for all jails. This is not a ezjail
|
||||||
|
restriction, but a design default of the jail command. This means the
|
||||||
|
.Xr ping 8
|
||||||
|
command will get
|
||||||
|
.Dq Operation not permitted.
|
||||||
|
error when used from inside of a jail. There are
|
||||||
|
.Xr sysctl 3
|
||||||
|
knobs for allowing a jail to access raw sockets, see the
|
||||||
|
.Xr jail 8
|
||||||
|
man page for details.
|
||||||
|
.Pp
|
||||||
|
Once your jail has network access, then all your normal application
|
||||||
|
install functions are availabe, right from the jails console. In
|
||||||
|
particular, if the ports collection was installed, it can be used as
|
||||||
|
if from the host system. A modified
|
||||||
|
.Pa make.conf
|
||||||
|
file is installed by the example flavour, that enable the ports
|
||||||
|
collection to work even with a read-only
|
||||||
|
.Pa /usr/ports .
|
||||||
|
.Pp
|
||||||
|
It is possible to change the IP address of a jail by editing its
|
||||||
|
configuration file in
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail
|
||||||
|
and restarting the jail.
|
||||||
|
.Pp
|
||||||
|
The jails use the same network stack as the host system. In
|
||||||
|
particular, that means that if a firewall is needed, it must be
|
||||||
|
configured in the host system.
|
||||||
|
.Pp
|
||||||
|
The ezjail system (and the jails it controls) depends on the
|
||||||
|
.Dq Li $ezjail_enable
|
||||||
|
variable being set to
|
||||||
|
.Dq Li YES
|
||||||
|
in
|
||||||
|
.Pa rc.conf .
|
||||||
|
It is possible to set this variable to
|
||||||
|
.Dq Li NO
|
||||||
|
if the administrator wants to temporarily ezjail, or if she doesn't
|
||||||
|
want the jails to be automatically started on boot.
|
||||||
|
.Pp
|
||||||
|
The ezjail system may be reset to a printine state by removing all its
|
||||||
|
files, that is:
|
||||||
|
.Bl -item -compact
|
||||||
|
.It
|
||||||
|
.Pa /usr/jails/
|
||||||
|
.It
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail/
|
||||||
|
.It
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf
|
||||||
|
.It
|
||||||
|
.Pa /etc/fstab.* No (but check the list of files this matches)
|
||||||
|
.El
|
||||||
|
.Sh EXAMPLES
|
||||||
|
The examples below are only that, examples. The reader is encouraged
|
||||||
|
to read the
|
||||||
|
.Xr ezjail-admin 8
|
||||||
|
man page for definitive documentation of all the options.
|
||||||
|
.Ss Initial Binary Installation
|
||||||
|
The ezjail system may be bootstrapped either from binary packages, or
|
||||||
|
by building from source. The
|
||||||
|
.Cm install
|
||||||
|
command allow to bootstrap from binary packages, while the
|
||||||
|
.Cm update
|
||||||
|
deals with installations (and updates) from source.
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Nm Cm install No (without any options)
|
||||||
|
Fetch and install binaries for populating the base jail from the
|
||||||
|
FreeBSD FTP server. If the host is not running a -RELEASE version, you
|
||||||
|
will be asked for the release to install. Neither the man pages nor
|
||||||
|
the source nor the ports tree are installed. Note that the FreeBSD FTP
|
||||||
|
server is sometimes so busy the download times out. Use the
|
||||||
|
.Fl h Ar host
|
||||||
|
option to specify a less loaded server, or the
|
||||||
|
.Dq Li $ezjail_ftphost
|
||||||
|
option in
|
||||||
|
.Xr ezjail.conf 8 .
|
||||||
|
.It Nm Cm install Fl ms
|
||||||
|
Same behavior as above, except that man pages and sources are installed in the
|
||||||
|
base jail.
|
||||||
|
.It Nm Cm install Fl p
|
||||||
|
Same as the first example, but use
|
||||||
|
.Xr portsnap 8
|
||||||
|
to fetch and extract a full FreeBSD ports tree from
|
||||||
|
.Li portsnap.FreeBSD.org
|
||||||
|
into the base jail. This is necessary if you plan to install ports at later
|
||||||
|
time into service jails.
|
||||||
|
.It Nm Cm install Fl P No (note uppercase P)
|
||||||
|
Only fetch the current version of the ports tree, adding it to the base jail.
|
||||||
|
This allow to either add the ports tree after the initial installation or update the ports tree in the base jail.
|
||||||
|
.It Install from a disk image
|
||||||
|
Mount and use a downloaded
|
||||||
|
.Pa disc1.iso
|
||||||
|
CDRom image file.
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
mdconfig -a -f /usr/8.0-RELEASE-i386-disc1.iso md0
|
||||||
|
mount -v -t cd9660 /dev/md0 /mnt
|
||||||
|
cd /mnt/8.0-RELEASE
|
||||||
|
ezjail-admin install -h file:// -sm
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
When the installation finishes, use the following to release the
|
||||||
|
.Pa disc1.iso
|
||||||
|
.Pa md0
|
||||||
|
file.
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
cd /usr
|
||||||
|
umount /mnt
|
||||||
|
mdconfig -d -u md0
|
||||||
|
.Ed
|
||||||
|
.It Install from a local directory
|
||||||
|
To fetch the RELEASE base files manually, create a
|
||||||
|
.Pa .netrc
|
||||||
|
file in your home directory and populate it with this.
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
machine ftp2.jp.FreeBSD.org
|
||||||
|
login anonymous
|
||||||
|
password FBSD@home.com
|
||||||
|
macdef init
|
||||||
|
prompt off
|
||||||
|
cd /pub/FreeBSD/releases/i386/8.0-RELEASE
|
||||||
|
epsv4 off
|
||||||
|
$ getdir base kernels manpages src
|
||||||
|
quit
|
||||||
|
macdef getdir
|
||||||
|
! mkdir $i
|
||||||
|
mreget $i/*
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
Then issue this command on the command line. If the FTP download
|
||||||
|
times out re-issue the FTP command again to resume where it left off.
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
mkdir /usr/8.0-RELEASE
|
||||||
|
cd /usr/8.0-RELEASE
|
||||||
|
ftp -v ftp2.jp.FreeBSD.org
|
||||||
|
ezjail-admin install -h file:// -sm
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
Use this option to target the 8.0-RELEASE files you FTP'ed as the source of
|
||||||
|
the running binaries used to populate the base jail. In addition the man
|
||||||
|
pages and sources will be installed into the base jail.
|
||||||
|
.El
|
||||||
|
.Ss From Source Installation and Update
|
||||||
|
The
|
||||||
|
.Cm update
|
||||||
|
is used to both install or update from source the base jail, and for
|
||||||
|
updating the base jail from binary packages.
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Nm Cm update Fl b
|
||||||
|
Build and install a world from source. The sources are taken from
|
||||||
|
.Pa /usr/src
|
||||||
|
(but see the
|
||||||
|
.Fl s
|
||||||
|
flag). This can be used both for creating the initial base jail, and
|
||||||
|
for updating it after the host has been upgraded.
|
||||||
|
.It Nm Cm update Fl u
|
||||||
|
Update the base jail to the next release using
|
||||||
|
.Xr freebsd-update 8
|
||||||
|
(i.e. using binary packages). This may be used only to update an
|
||||||
|
existing installation.
|
||||||
|
.El
|
||||||
|
.Ss Jail Creation Examples
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Nm Cm create Ar www.example.com 10.0.10.1
|
||||||
|
Create a new jail. The jail files will reside in directory
|
||||||
|
.Pa www_example_com
|
||||||
|
in
|
||||||
|
.Pa /usr/jails ,
|
||||||
|
unless the variable
|
||||||
|
.Dq Li $ezjail_jaildir
|
||||||
|
has been set to some other value. The jail will only be allowed to use
|
||||||
|
the given IP address. A warning will be displayed if this IP address
|
||||||
|
is not already configured in the host, or if some network daemon is
|
||||||
|
already listening on this address. The name of the jail which will
|
||||||
|
appear in the
|
||||||
|
.Cm list
|
||||||
|
command or which will need to be given to the
|
||||||
|
.Cm console
|
||||||
|
command is
|
||||||
|
.Ar www.example.com .
|
||||||
|
.It Nm Cm create Fl f Ar example Fl r Ar webserver www.example.com 10.0.10.2,2001:db8:1:9243::80
|
||||||
|
Create a new jail, placing it in directory
|
||||||
|
.Pa webserver
|
||||||
|
instead of deriving the directory name of the jail from its host name.
|
||||||
|
The jail will be created with the flavour
|
||||||
|
.Ar example .
|
||||||
|
This jail will be given two IP addressses; this is possible only since
|
||||||
|
FreeBSD 7.2.
|
||||||
|
.It Nm Cm create Fl i Fl s Ar 600M sandbox2 10.0.10.4
|
||||||
|
This creates a new file-based jail having a file size of 600 megabytes
|
||||||
|
in
|
||||||
|
.Pa /usr/jails/sandbox2.img .
|
||||||
|
An empty directory,
|
||||||
|
.Pa /usr/jails/sandbox2 ,
|
||||||
|
will be created, and used as a mount point when starting the jail.
|
||||||
|
.It Nm Cm create Fl i Fl c Cm bde Fl s Ar 600M sandbox3 10.0.10.5
|
||||||
|
This creates a new file based image jail, with
|
||||||
|
.Xr gbde 4
|
||||||
|
encryption. During the gbde creation process you are asked to enter a
|
||||||
|
passphrase that is used as the prime seed value of the encryption
|
||||||
|
process. Remember this passphrase, you will be asked for the
|
||||||
|
passphrase every time sub-command start is used on this jail. As they
|
||||||
|
require administrator interaction, jails backed by an encrypted file
|
||||||
|
are not automatically started when the system boots.
|
||||||
|
.El
|
||||||
|
.Sh FILES
|
||||||
|
.Pa EZJAIL_PREFIX/bin/ezjail-admin
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/share/examples/ezjail/
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail/*
|
||||||
|
.br
|
||||||
|
.Pa /usr/etc/fstab.*
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr ezjail-admin 8 ,
|
||||||
|
.Xr ezjail.conf 5 ,
|
||||||
|
.Xr jail 8 ,
|
||||||
|
.Xr nullfs 4 .
|
||||||
|
.Pp
|
||||||
|
Interesting additional tools include:
|
||||||
|
.Dq Li ports-mgmt/jailaudit .
|
||||||
|
.Sh AUTHOR
|
||||||
|
.An Dirk Engling
|
||||||
|
.Aq erdgeist@erdgeist.org .
|
||||||
606
man8/ezjail-admin.8
Normal file
606
man8/ezjail-admin.8
Normal file
@ -0,0 +1,606 @@
|
|||||||
|
.Dd January 15, 2011
|
||||||
|
.Dt EZJAIL-ADMIN 8 USD
|
||||||
|
.Os FreeBSD
|
||||||
|
.Sh NAME
|
||||||
|
.Nm ezjail-admin
|
||||||
|
.Nd Administrate ezjail environment
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Nm Cm install
|
||||||
|
.Op Fl mMpPsS
|
||||||
|
.Op Fl h Ar host
|
||||||
|
.Op Fl r Ar release
|
||||||
|
.Nm
|
||||||
|
.Cm create
|
||||||
|
.Op Fl bx
|
||||||
|
.Op Fl f Ar flavour
|
||||||
|
.Op Fl r Ar jailroot
|
||||||
|
.Op Fl a Ar archive
|
||||||
|
.Op Fl A Ar options
|
||||||
|
.Op Fl c Ar jailtype Fl s Ar imagesize Op Fl C Ar attachargs
|
||||||
|
.Bk -words
|
||||||
|
.Ar jailname ipaddress Ns Op Ar ,ipaddress2,...
|
||||||
|
.Ek
|
||||||
|
.Nm
|
||||||
|
.Cm console
|
||||||
|
.Op Fl f
|
||||||
|
.Op Fl e Ar command
|
||||||
|
.Ar jailname
|
||||||
|
.Nm
|
||||||
|
.Cm list
|
||||||
|
.Nm
|
||||||
|
.Cm start | stop | restart | cryptostart Ar jailname...
|
||||||
|
.Nm
|
||||||
|
.Cm config
|
||||||
|
.Op Fl r Ar run | norun
|
||||||
|
.Op Fl n Ar newname
|
||||||
|
.Op Fl i Ar attach | detach | fsck
|
||||||
|
.Op Fl z Ar newdataset
|
||||||
|
.Op Fl c Ar newcpuset
|
||||||
|
.Op Fl f Ar newfib
|
||||||
|
.Ar jailname
|
||||||
|
.Nm
|
||||||
|
.Cm delete
|
||||||
|
.Op Fl wf
|
||||||
|
.Ar jailname
|
||||||
|
.Nm
|
||||||
|
.Cm archive
|
||||||
|
.Op Fl Af
|
||||||
|
.Op Fl a Ar archive
|
||||||
|
.Op Fl d Ar archivedir
|
||||||
|
.Ar jailname...
|
||||||
|
.Nm
|
||||||
|
.Cm restore
|
||||||
|
.Op Fl f
|
||||||
|
.Op Fl d Ar archivedir
|
||||||
|
.Ar archive | jailname...
|
||||||
|
.Nm
|
||||||
|
.Cm update
|
||||||
|
.Op Fl s Ar sourcetree
|
||||||
|
.Op Fl p
|
||||||
|
.Fl b | Fl i | Fl P | Fl u
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
The
|
||||||
|
.Nm
|
||||||
|
utility is used to manage the ezjail environment and all the jails inside the
|
||||||
|
ezjail scope. This man page describes the invocation of
|
||||||
|
.Nm .
|
||||||
|
Refer to
|
||||||
|
.Xr ezjail 7
|
||||||
|
in order to get an introduction to the usage of ezjail, as well as
|
||||||
|
usage examples.
|
||||||
|
.Pp
|
||||||
|
The description of some options ends with
|
||||||
|
.Sq Variable: Dq Li $ezjail_abcd .
|
||||||
|
This means that the default value of the option may be overridden by setting
|
||||||
|
this variable in
|
||||||
|
.Xr ezjail.conf 5 ,
|
||||||
|
which see.
|
||||||
|
.Ss Nm Cm install
|
||||||
|
This function sub-command is normally run once in the life of the ezjail
|
||||||
|
environment. It allocates the directory structure used by ezjail and populates
|
||||||
|
the base jail using the minimal distribution set from a FreeBSD FTP server.
|
||||||
|
.Pp
|
||||||
|
The default location for ezjail's basejail is in
|
||||||
|
.Pa /usr/jails ,
|
||||||
|
so be sure you have enough space there (a FreeBSD base release without man
|
||||||
|
pages, sources and ports is around 120MB). This location may be modified in
|
||||||
|
.Xr ezjail.conf 5 .
|
||||||
|
.Pp
|
||||||
|
See also
|
||||||
|
.Nm
|
||||||
|
.Cm update
|
||||||
|
to install the base jail from source, as well as a method to update
|
||||||
|
the base jail using
|
||||||
|
.Xr freebsd-update 8 .
|
||||||
|
.Pp
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl m
|
||||||
|
Fetch and install man pages (ca. 10MB).
|
||||||
|
.It Fl M
|
||||||
|
Fetch and install man pages, without (re)installing the base jail. May be used
|
||||||
|
to add the man pages to the base jail after the intial installation.
|
||||||
|
.It Fl s
|
||||||
|
Fetch and install sources (ca. 450MB).
|
||||||
|
.It Fl S
|
||||||
|
Fetch and install sources, without (re)installing the base jail.
|
||||||
|
.It Fl p
|
||||||
|
Invoke the
|
||||||
|
.Xr portsnap 8
|
||||||
|
utility to fetch and extract a FreeBSD ports tree from
|
||||||
|
.Li portsnap.FreeBSD.org
|
||||||
|
(ca. 475MB). When a ports tree is added to the base jail, a modified
|
||||||
|
.Pa make.conf
|
||||||
|
containing reasonable values to function in the jailed environment is added to
|
||||||
|
the new jail template so all jails created from the new jail template will
|
||||||
|
have a working ports environment. See the appendix
|
||||||
|
.%B Using Portsnap
|
||||||
|
in the
|
||||||
|
.%B FreeBSD Handbook
|
||||||
|
for details or
|
||||||
|
.Xr portsnap 8 .
|
||||||
|
.It Fl P
|
||||||
|
Fetch and extract a ports tree, without (re)installing the base jail.
|
||||||
|
.It Fl h Ar host
|
||||||
|
Set the remote host to fetch FreeBSD distribution sets from. If absent the
|
||||||
|
default host
|
||||||
|
.Li ftp.FreeBSD.org
|
||||||
|
is used. Variable:
|
||||||
|
.Dq Li $ezjail_ftphost .
|
||||||
|
.Pp
|
||||||
|
It is possible to install from the
|
||||||
|
.Li disc1
|
||||||
|
CDRom, or an extracted -RELEASE directory, by specifying the
|
||||||
|
.Ar host
|
||||||
|
argument as
|
||||||
|
.Pa file://path/to/source .
|
||||||
|
.It Fl r Ar release
|
||||||
|
Install this release of FreeBSD in the base jail, instead of the version
|
||||||
|
returned by
|
||||||
|
.Dq Li uname -r
|
||||||
|
on the host system. Note that the FreeBSD FTP servers usually provide only
|
||||||
|
-RELEASE versions, not -STABLE nor -CURRENT versions; you will be prompted for
|
||||||
|
confirmation when trying to install a non -RELEASE version. If you want to
|
||||||
|
install a -CURRENT version, you may have to compile from source the base jail;
|
||||||
|
see the
|
||||||
|
.Nm Cm update
|
||||||
|
sub-command for this.
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm create
|
||||||
|
Create a new jail inside ezjail's scope. It either copies the new jail
|
||||||
|
directory tree template or an ezjail archive directory tree to
|
||||||
|
.Pa /usr/jails/ Ns Ar jailname
|
||||||
|
directory tree. Jailname and IP address are mandatory parameters.
|
||||||
|
.Pp
|
||||||
|
When a new jail is created, a corresponding new
|
||||||
|
.Pa /etc/fstab. Ns Ar jailname
|
||||||
|
file is also created, with a
|
||||||
|
.Xr nullfs 5
|
||||||
|
mount giving access to the base jail from the new jail.
|
||||||
|
.Pp
|
||||||
|
The following operands are mandatory:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Ar jailname
|
||||||
|
The name of the jail. It is customary to use the network name of the jail,
|
||||||
|
such as
|
||||||
|
.Dq Li jail1.example.com
|
||||||
|
(or maybe simply
|
||||||
|
.Dq Li jail1 ) ,
|
||||||
|
but really any name may be used.
|
||||||
|
.Pp
|
||||||
|
It is an error to have several jails of the same name.
|
||||||
|
.It Ar ipaddress Ns Op Ar ,ipaddress2,...
|
||||||
|
The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
|
||||||
|
assign several several IPv4 or IPv6 addresses to a jail, by separating them
|
||||||
|
with commas. Previous versions of FreeBSD allowed only a single IPv4 address
|
||||||
|
per jail.
|
||||||
|
.Pp
|
||||||
|
The addresses of the jail are not configured on the host.
|
||||||
|
.Nm
|
||||||
|
will display a warning if the requested address is not found on any interface,
|
||||||
|
and the jail will probably not start.
|
||||||
|
.Pp
|
||||||
|
XXX: is the following relevant, except maybe the warning about dynamic
|
||||||
|
addresses?
|
||||||
|
.Pp
|
||||||
|
This is the static (premanent, never changes) public internet
|
||||||
|
routable ip address assigned to you by your ISP. If you purchased a
|
||||||
|
continous block of static public internet routable ip address, then each
|
||||||
|
jail could be assigned one of those individual ip address from the block.
|
||||||
|
.Pp
|
||||||
|
Normally phone dialup PPP access and cable providers assign
|
||||||
|
dynamic ip address. The assigned ip address may change every time you
|
||||||
|
dialup and with cable providers when the lease time expires or you
|
||||||
|
reboot your system. \fBUse dynamic ip address at your own risk.\fR
|
||||||
|
.Pp
|
||||||
|
On the host issue 'ifconfig -a' command to see your assigned ip address.
|
||||||
|
Your host /etc/rc.conf should have ifconfig_XXX="DHCP" where XXX is
|
||||||
|
the 'unit name' of the NIC card facing the public internet. You will
|
||||||
|
also need this same ifconfig_XXX="DHCP" statement in the rc.conf of
|
||||||
|
each jail to enable the public network for that jail.
|
||||||
|
.Pp
|
||||||
|
If your host is acting as a 'gateway' (IE. has a LAN behind it), you
|
||||||
|
can provide jails for LAN access only. In this configuration your host
|
||||||
|
/etc/rc.conf should have ifconfig_XXX="inet x.x.x.x" where XXX is
|
||||||
|
the 'unit name' of the NIC card facing the private LAN
|
||||||
|
(local-area-network), where x.x.x.x is a private ip address from the
|
||||||
|
list of reserved non-public routable ip address. You will also need
|
||||||
|
this same ifconfig_XXX="inet x.x.x.x" statement in the rc.conf of each
|
||||||
|
jail to enable the lan network for that jail.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl r Ar jailroot
|
||||||
|
Use this name as the directory name of the new jail. Without this option, it
|
||||||
|
is derived from the jail's name. If this option is given and does not start
|
||||||
|
with a '/', it is interpreted as relative to ezjail's root directory
|
||||||
|
.Pa (/usr/jails
|
||||||
|
by default). If a specified jailroot path lies outside the ezjail root
|
||||||
|
directory, a soft link is created inside
|
||||||
|
.Pa /usr/jails/
|
||||||
|
pointing to the location of the newly created jail.
|
||||||
|
.It Fl a Ar archive
|
||||||
|
Restore a jail from an archive created with
|
||||||
|
.Nm Cm archive .
|
||||||
|
The archive files are kept in
|
||||||
|
.Pa /usr/jails/archive
|
||||||
|
by default. Use
|
||||||
|
.Pa -
|
||||||
|
to restore an archive from the standard input.
|
||||||
|
.Pp
|
||||||
|
You will probably need to tidy up things inside an ezjail if you migrate it
|
||||||
|
between different ezjail environments. This may include (but is not limited
|
||||||
|
to) reinstalling ports or packages for different CPUs or library versions. You
|
||||||
|
may also need to copy some libraries from the source host's base jail.
|
||||||
|
.Pp
|
||||||
|
See also
|
||||||
|
.Nm Cm restore ,
|
||||||
|
if you only want to revert to an old jail's state from an archive on the same
|
||||||
|
release version.
|
||||||
|
.It Fl A Ar jailconf
|
||||||
|
Copy the comments, in particular the
|
||||||
|
.Dq Li PROVIDE ,
|
||||||
|
.Dq Li REQUIRE
|
||||||
|
and
|
||||||
|
.Dq Li BEFORE
|
||||||
|
lines, from this jail.
|
||||||
|
.Pp
|
||||||
|
XXX: This is my understanding from the code. Is that correct?
|
||||||
|
.It Fl x
|
||||||
|
This flag indicates that an jail of that name already exists. In this case,
|
||||||
|
ezjail will only update the configuration of the jail. Sanity checks are
|
||||||
|
performed.
|
||||||
|
.It Fl f Ar flavour
|
||||||
|
Install the requested
|
||||||
|
.Ar flavour
|
||||||
|
in the new jail.
|
||||||
|
.Pp
|
||||||
|
This option may not be used with the
|
||||||
|
.Fl a
|
||||||
|
option.
|
||||||
|
.It Fl c Cm simple | bde | eli | zfs
|
||||||
|
Create a jail of the given type.
|
||||||
|
.Pp
|
||||||
|
A
|
||||||
|
.Cm simple
|
||||||
|
jail is backed with a single file. The jail will not be allowed to grow beyond
|
||||||
|
its allocated size. The base jail is included in the image, making it portable
|
||||||
|
between hosts running the same (or sufficiently close) version of FreeBSD. The
|
||||||
|
jail will be stored in a file named
|
||||||
|
.Ar jailname Ns Pa .img ,
|
||||||
|
unless
|
||||||
|
.Fl r Ar jailroot
|
||||||
|
is given, in which case the jail is stored in
|
||||||
|
.Ar jailroot Ns Pa .img .
|
||||||
|
.Pp
|
||||||
|
A
|
||||||
|
.Cm bde No or Cm eli
|
||||||
|
jail is a
|
||||||
|
.Cm simple
|
||||||
|
jail whose file has been encrypted using
|
||||||
|
.Xr gbde 4
|
||||||
|
(for
|
||||||
|
.Cm bde )
|
||||||
|
or
|
||||||
|
.Xr geli 8
|
||||||
|
(for
|
||||||
|
.Cm eli ) .
|
||||||
|
See also the
|
||||||
|
.Fl C
|
||||||
|
flag when creating this kind of jail.
|
||||||
|
.Pp
|
||||||
|
A
|
||||||
|
.Cm zfs
|
||||||
|
jail is backed with a
|
||||||
|
.Xr zfs 8
|
||||||
|
volume, whose initial quota is given with the
|
||||||
|
.Fl s
|
||||||
|
option. The volume is compressed using the lzjb method. The volume is created
|
||||||
|
in the
|
||||||
|
.Cm ezjail_jailzfs
|
||||||
|
data set, if set in
|
||||||
|
.Xr ezjail.conf 5 .
|
||||||
|
.Pp
|
||||||
|
XXX: from the code, it looks like the user needs to have done
|
||||||
|
ezjail-admin install with ezjail_use_zfs. Is that correct?
|
||||||
|
.Pp
|
||||||
|
In each case, the
|
||||||
|
.Fl s
|
||||||
|
flag is mandatory when creating such a jail. An empty directory (without the
|
||||||
|
.Pa .img
|
||||||
|
suffix in the case of file-based jails) will be created and used as a mount
|
||||||
|
point when running the jail.
|
||||||
|
.It Fl s Ar imagesize
|
||||||
|
Allocate this size to the jail. Without an unit, the size is in bytes. The
|
||||||
|
valid suffix values are b/B for bytes, k/K for kilobytes, m/M for megabytes,
|
||||||
|
and g/G for gigabytes. As a reference point, a newly created jail requires
|
||||||
|
2MB.
|
||||||
|
.Pp
|
||||||
|
It is not possible to increase the size of file-based jails after their
|
||||||
|
creation, short of creating a new image jail with a larger size.
|
||||||
|
.It Fl C Ar imageopt
|
||||||
|
Pass this argument to
|
||||||
|
.Li gbde No or Li geli init .
|
||||||
|
.Fl P No and Fl K
|
||||||
|
(and
|
||||||
|
.Fl L
|
||||||
|
for
|
||||||
|
.Xr gbde 4 )
|
||||||
|
will be translated and passed to
|
||||||
|
.Li gbde No or Li geli attach
|
||||||
|
when starting the jail.
|
||||||
|
.It Fl i
|
||||||
|
Synonym of
|
||||||
|
.Fl c Cm simple .
|
||||||
|
.It Fl b
|
||||||
|
Don't start the jail at boot time.
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm console
|
||||||
|
Attach your console to the selected jail. You are logged in as root by
|
||||||
|
default. The command line prompt shows the name of the jail. You have to
|
||||||
|
use the pwd command to see where in the directory tree you are. Entering
|
||||||
|
\fBexit\fR will terminate the jail console.
|
||||||
|
.Pp
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl f
|
||||||
|
Start the jail if it is not running yet.
|
||||||
|
.It Fl e Ar command
|
||||||
|
Use
|
||||||
|
.Ar command
|
||||||
|
instead of
|
||||||
|
.Dq /usr/bin/login -f root .
|
||||||
|
A one time change to use a different user can be accomplished by using
|
||||||
|
.Fl e Qq Li /usr/bin/login -f user .
|
||||||
|
Variable:
|
||||||
|
.Dq Li $ezjail_default_execute .
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm list
|
||||||
|
List all jails inside ezjail's scope. They are sorted by the order they start
|
||||||
|
up, as defined by
|
||||||
|
.Xr rcorder 1 .
|
||||||
|
.Pp
|
||||||
|
The first column is the status flag consisting of 2 or 3 letters. The first
|
||||||
|
letter is the type of jail:
|
||||||
|
.Bl -tag -width 4n -offset indent -compact
|
||||||
|
.It Sy D
|
||||||
|
Directory tree based jail.
|
||||||
|
.It Sy I
|
||||||
|
File-based jail.
|
||||||
|
.It Sy E
|
||||||
|
Geli encrypted file-based jail.
|
||||||
|
.It Sy B
|
||||||
|
Bde encrypted file-based jail.
|
||||||
|
.It Sy Z
|
||||||
|
ZFS filesystem-based jail.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
The second letter is the status of the jail:
|
||||||
|
.Bl -tag -width 4n -offset indent -compact
|
||||||
|
.It Sy R
|
||||||
|
The jail is running.
|
||||||
|
.It Sy A
|
||||||
|
The image of the jail is mounted, but the jail is not running.
|
||||||
|
.It Sy S
|
||||||
|
The jail is stopped.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
If present, the third letter,
|
||||||
|
.Sy N ,
|
||||||
|
means that the jail is not automatically started.
|
||||||
|
.Pp
|
||||||
|
The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
|
||||||
|
.Ss Nm Cm start | stop | restart | cryptostart Op Ar jailname ...
|
||||||
|
Execute the given action on
|
||||||
|
.Ar jailname ,
|
||||||
|
or on all jails if the operand is omitted. Several jails may be specified.
|
||||||
|
.Pp
|
||||||
|
As this is just a shortcut to the
|
||||||
|
.Xr rc 8
|
||||||
|
.Cm ezjail
|
||||||
|
script, if ezjail is not enabled in
|
||||||
|
.Xr rc.conf 5
|
||||||
|
with
|
||||||
|
.Dq Li ezjail_enable= Ns Qq Li YES ,
|
||||||
|
nothing will be done. Prefix the action with
|
||||||
|
.Cm one
|
||||||
|
(as in
|
||||||
|
.Cm onestart ,
|
||||||
|
etc.) to force the action regardless of the value of
|
||||||
|
.Dq Li $ezjail_enable .
|
||||||
|
.Pp
|
||||||
|
.Cm cryptostart
|
||||||
|
is used to start jails that use
|
||||||
|
.Xr gbde 4
|
||||||
|
or
|
||||||
|
.Xr geli 8
|
||||||
|
encryption. Those jails require interaction with the administrator
|
||||||
|
when starting.
|
||||||
|
.Ss Nm Cm config Ar jailname
|
||||||
|
Manage parameters of specific ezjails. For running jails, most of the
|
||||||
|
configuration changes described below will not be applied until the next time
|
||||||
|
the jail is restarted.
|
||||||
|
.Pp
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl r Cm run | norun
|
||||||
|
Set the jail to be automatically started or not on boot.
|
||||||
|
.It Fl n An newname
|
||||||
|
Rename the jail. Unless a custom root directory was given with the
|
||||||
|
.Fl r
|
||||||
|
flag when creating the jail, the root directory will be renamed as well. A
|
||||||
|
running jail may not be renamed.
|
||||||
|
.It Fl i Cm attach | detach | fsck
|
||||||
|
Only valid for stopped image jails. Attaching a jail means making the content
|
||||||
|
of the root of the jail accessible from the host. No other sub-commands will
|
||||||
|
function on an jail while its image is attached. With
|
||||||
|
.Cm fsck ,
|
||||||
|
the image jail is attached,
|
||||||
|
.Xr fsck 8
|
||||||
|
is run, then the image jail is detached. You can only fsck image based jails.
|
||||||
|
.It Fl z Ar newdataset
|
||||||
|
Set the given ZFS dataset to be mounted inside the jail file system
|
||||||
|
when it is started.
|
||||||
|
.It Fl f Ar newfib
|
||||||
|
Change the FIB of the jail (see
|
||||||
|
.Xr setfib 2 ) .
|
||||||
|
.It Fl c Ar newcpuset
|
||||||
|
Change the CPU affinity set of the jail (see
|
||||||
|
.Xr cpuset 2 ) .
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm delete Ar jailname
|
||||||
|
Delete a jail. By default, this command only deletes ezjail's control file for
|
||||||
|
the selected jail as well as
|
||||||
|
.Pa /etc/fstab. Ns Ar jailname .
|
||||||
|
The
|
||||||
|
.Pa /usr/jails/ Ns Ar jailname
|
||||||
|
directory is not deleted.
|
||||||
|
.Pp
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl f
|
||||||
|
Stop the jail before deleting it.
|
||||||
|
.It Fl w
|
||||||
|
Delete the directory or the file backing the jail.
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm archive
|
||||||
|
Create a backup of one, multiple or all ezjails. The specified service
|
||||||
|
jail's root directory tree is backed up as a
|
||||||
|
.Xr pax 1
|
||||||
|
file. The jail needs to be stopped.
|
||||||
|
.Pp
|
||||||
|
See
|
||||||
|
.Nm Cm restore
|
||||||
|
or
|
||||||
|
.Nm Cm create Fl a Ar archive
|
||||||
|
to restore an archive.
|
||||||
|
.Pp
|
||||||
|
The basejail can not be archived. There is no ezjail function to
|
||||||
|
delete archive files; they may be removed from the host using
|
||||||
|
.Xr rm 1 .
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl a Ar archivename
|
||||||
|
Use this name for the archive file. If absent, the archive file name
|
||||||
|
is derived from the jail name, with the date and time of the archive
|
||||||
|
appended to the file name.
|
||||||
|
.It Fl d Ar directory
|
||||||
|
Save the archive in this directory. If this option is not given and
|
||||||
|
.Dq Li $ezjail_archivedir
|
||||||
|
is not set, the archive is saved in the default directory.
|
||||||
|
Variable:
|
||||||
|
.Dq Li $ezjail_archivedir .
|
||||||
|
.It Fl f
|
||||||
|
Archive the jail even when it is running.
|
||||||
|
.It Fl A
|
||||||
|
Archive all jails.
|
||||||
|
.It Ar jailname
|
||||||
|
Archive only this jail. This argument is mandatory if
|
||||||
|
.Fl a
|
||||||
|
is not given.
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm restore
|
||||||
|
Create new ezjails from archived versions. It tries to collect all
|
||||||
|
information necessary to do that without user interaction from the
|
||||||
|
user.
|
||||||
|
.Pp
|
||||||
|
The following operand is mandatory:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Ar archive | jailname
|
||||||
|
Restore this jail. If only the jail name is given,
|
||||||
|
.Nm
|
||||||
|
will use the most recent archive file matching the name you specified.
|
||||||
|
To restore an older version, specify the complete archive file name
|
||||||
|
(file name with the date and time of the archive appended to it).
|
||||||
|
.El
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl d Ar archivedir
|
||||||
|
Search the archive file in this directory. If this option is not given and
|
||||||
|
.Dq Li $ezjail_archivedir
|
||||||
|
is not set, the archive is searched in the current directory. Variable:
|
||||||
|
.Dq Li $ezjail_archivedir .
|
||||||
|
.It Fl f
|
||||||
|
Restore the archive even if running on a host different from
|
||||||
|
where it was archived. Be default,
|
||||||
|
.Nm
|
||||||
|
will refuse to restore an archive if the hostname, the FreeBSD version
|
||||||
|
or the CPU architecture is modified.
|
||||||
|
.El
|
||||||
|
.Ss Nm Cm update
|
||||||
|
Creates or updates ezjail's basejail from source. This performs a
|
||||||
|
.Dq make world ; make installworld
|
||||||
|
using the basejail's RELEASE source located at
|
||||||
|
.Pa /usr/src
|
||||||
|
(but see the
|
||||||
|
.Fl s
|
||||||
|
option). Exactly one of
|
||||||
|
.Fl b , i , u , P
|
||||||
|
is mandatory.
|
||||||
|
.Pp
|
||||||
|
See the
|
||||||
|
.Cm install
|
||||||
|
command to install the basejail from binary packages.
|
||||||
|
.Pp
|
||||||
|
Exactly one of the following operand must be specified:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl b
|
||||||
|
Build and install a world from source located in the basejail.
|
||||||
|
.It Fl i
|
||||||
|
Perform a
|
||||||
|
.Qq make installworld ,
|
||||||
|
assuming the world has already been built.
|
||||||
|
.It Fl u
|
||||||
|
Use
|
||||||
|
.Xr freebsd-update 8
|
||||||
|
to update the basejail. Note that as
|
||||||
|
.Xr freebsd-update 8
|
||||||
|
uses
|
||||||
|
.Dq Li uname -r
|
||||||
|
to determine the currently running system, the base jail and the host
|
||||||
|
need to be updated at the same time, without rebooting on the new
|
||||||
|
kernel in the meantime.
|
||||||
|
.Pp
|
||||||
|
Jails that are stored in a ZFS volume are snapshot first.
|
||||||
|
.It Fl P
|
||||||
|
Install only the ports tree, assuming the basejail has already been
|
||||||
|
created.This can be done while jails are running. The
|
||||||
|
.Xr portsnap 8
|
||||||
|
utility is invoked to do the actual work.
|
||||||
|
.El
|
||||||
|
The following options are available:
|
||||||
|
.Bl -tag -width indent
|
||||||
|
.It Fl p
|
||||||
|
Give the new basejail a copy of FreeBSD's ports tree. The
|
||||||
|
.Xr portsnap 8
|
||||||
|
utility is invoked to do the actual work.
|
||||||
|
.It Fl s Ar sourcedir
|
||||||
|
Use the sources in
|
||||||
|
.Ar sourcedir
|
||||||
|
instead of
|
||||||
|
.Pa /usr/src .
|
||||||
|
Variable:
|
||||||
|
.Dq Li $ezjail_sourcetree .
|
||||||
|
.El
|
||||||
|
.Sh FILES
|
||||||
|
.Pa EZJAIL_PREFIX/bin/ezjail-admin
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail.conf
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/share/examples/ezjail/
|
||||||
|
.br
|
||||||
|
.Pa EZJAIL_PREFIX/etc/ezjail/*
|
||||||
|
.br
|
||||||
|
.Pa /usr/etc/fstab.*
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr ezjail 7 ,
|
||||||
|
.Xr ezjail.conf 8 ,
|
||||||
|
.Xr jail 8 ,
|
||||||
|
.Xr devfs 5 ,
|
||||||
|
.Xr fdescfs 5 ,
|
||||||
|
.Xr procfs 5 ,
|
||||||
|
.Xr portsnap 8 .
|
||||||
|
.Sh AUTHOR
|
||||||
|
.An Dirk Engling
|
||||||
|
.Aq erdgeist@erdgeist.org .
|
||||||
Loading…
x
Reference in New Issue
Block a user