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/
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: man1/ezjail-admin.1 > ${PREFIX}/man/man1/ezjail-admin.1
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: man8/ezjail-admin.8 > ${PREFIX}/man/man8/ezjail-admin.8
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.5 > ${PREFIX}/man/man5/ezjail.5
|
||||
sed s:EZJAIL_PREFIX:${PREFIX}: man7/ezjail.7 > ${PREFIX}/man/man7/ezjail.7
|
||||
chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
|
||||
chown -R root:wheel ${PREFIX}/man/man1/ezjail-admin.1 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man5/ezjail.5 ${PREFIX}/share/examples/ezjail/
|
||||
chown -R root:wheel ${PREFIX}/man/man8/ezjail-admin.8 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man7/ezjail.7 ${PREFIX}/share/examples/ezjail/
|
||||
chmod 0440 ${PREFIX}/share/examples/ezjail/example/usr/local/etc/sudoers
|
||||
|
||||
@ -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
|
||||
.SH NAME
|
||||
ezjail.conf \- configuration file for ezjail script
|
||||
.SH DESCRIPTION
|
||||
.Dd January 15, 2011
|
||||
.Dt EZJAIL.CONF 5 USD
|
||||
.Os FreeBSD
|
||||
.Sh NAME
|
||||
.Pa ezjail.conf
|
||||
.Nd configuration file for ezjail script
|
||||
.Sh DESCRIPTION
|
||||
The file
|
||||
.B ezjail.conf
|
||||
.Pa ezjail.conf
|
||||
contains settings that control the operation of the ezjail rc script. It is
|
||||
also read by the
|
||||
.B ezjail-admin
|
||||
utility to figure out where it should perform its actions.
|
||||
.SH PATH OPTIONS
|
||||
.TP
|
||||
.B ezjail_jaildir (str)
|
||||
Location of jail root directories
|
||||
.Cm ezjail-admin
|
||||
utility to figure out where it should perform its actions. Its path is
|
||||
set at installation time to
|
||||
.Pa EZJAIL_PREFIX/etc/ezjail.conf ,
|
||||
with an example file installed at
|
||||
.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
|
||||
.Pp
|
||||
This file is really a shell script that is sourced by the
|
||||
.Cm ezjail-admin
|
||||
command at run-time.
|
||||
.Dq (str)
|
||||
denotes a string; it should be enclosed in quotes if it contains space.
|
||||
.Dq (bool)
|
||||
notes a boolean, whose possible values are
|
||||
.Dq YES
|
||||
and
|
||||
.Dq NO .
|
||||
.Sh PATH OPTIONS
|
||||
.Bl -tag -width option
|
||||
.It ezjail_jaildir (str)
|
||||
Location of jail root directories.
|
||||
.br
|
||||
.I default: /usr/jails
|
||||
.TP
|
||||
.B ezjail_jailtemplate (str)
|
||||
Default:
|
||||
.Em /usr/jails .
|
||||
.It ezjail_jailtemplate (str)
|
||||
Location of template jail used to create a new jail
|
||||
.br
|
||||
.I default: /usr/jails/newjail
|
||||
.TP
|
||||
.B ezjail_jailbase (str)
|
||||
Default:
|
||||
.Em ${ezjail_jaildir}/newjail .
|
||||
.It ezjail_jailbase (str)
|
||||
Location of base jail, the one that is mounted to all jails
|
||||
.br
|
||||
.I default: /usr/jails/basejail
|
||||
.TP
|
||||
.B ezjail_sourcetree (str)
|
||||
Default:
|
||||
.Em ${ezjail_jaildir}/basejail .
|
||||
.It ezjail_sourcetree (str)
|
||||
Location of your copy of FreeBSD's source tree (refer to the
|
||||
.B ezjail-admin(1)
|
||||
utility for more information)
|
||||
.Xr ezjail-admin 1
|
||||
utility for more information).
|
||||
.br
|
||||
.I default: /usr/src
|
||||
.TP
|
||||
.B ezjail_portscvsroot (str)
|
||||
Cvs root to use when checking out or updating the ports tree in base jail
|
||||
Default:
|
||||
.Em /usr/src .
|
||||
.It ezjail_flavours_dir (str)
|
||||
Location of the flavours, where each directory is a different flavour.
|
||||
.br
|
||||
.I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
|
||||
.TP
|
||||
.B ezjail_ftphost (str)
|
||||
This is where the install subcommand defaults to fetch its packages from
|
||||
Default:
|
||||
.Em ${ezjail_jaildir}/flavours .
|
||||
.It ezjail_portscvsroot (str)
|
||||
CVS root to use when checking out or updating the ports tree in base jail.
|
||||
.br
|
||||
.I default: ftp.freebsd.org
|
||||
.TP
|
||||
.B ezjail_archivedir (str)
|
||||
This is the default archive location for the \fIezjail-admin archive\fR command.
|
||||
Default:
|
||||
.Em :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs .
|
||||
.It ezjail_ftphost (str)
|
||||
This is where the install subcommand defaults to fetch its packages from.
|
||||
.br
|
||||
.I default: `pwd -P`
|
||||
.SH JAIL ADMIN OPTIONS
|
||||
.TP
|
||||
.B ezjail_default_execute (str)
|
||||
This is the default command executed in a jail by ezjail-admin console.
|
||||
Default:
|
||||
.Em ftp.freebsd.org .
|
||||
.It ezjail_archivedir (str)
|
||||
This is the default archive location for the
|
||||
.Cm ezjail-admin archive
|
||||
command.
|
||||
.br
|
||||
.I default: YES
|
||||
.SH JAIL CREATION OPTIONS
|
||||
Default:
|
||||
.Em ${ezjail_jaildir}/ezjail_archives .
|
||||
.El
|
||||
.Sh JAIL ADMIN OPTIONS
|
||||
.Bl -tag -width option
|
||||
.It ezjail_default_execute (str)
|
||||
This is the default command executed in a jail by
|
||||
.Cm ezjail-admin console .
|
||||
.br
|
||||
Default:
|
||||
.Em /usr/bin/login -f root .
|
||||
.It ezjail_exec_start (str)
|
||||
The command to execute in a jail when starting it.
|
||||
.br
|
||||
Default:
|
||||
.Em /bin/sh /etc/rc .
|
||||
.El
|
||||
.Sh JAIL CREATION OPTIONS
|
||||
Default options for newly created jails. Used by the
|
||||
.B ezjail-admin(1)
|
||||
utility. Be careful about disabling ezjail_mount_enable. (Refer to
|
||||
.B ezjail-admin(1)
|
||||
for more information).
|
||||
.TP
|
||||
.B ezjail_mount_enable (bool)
|
||||
Controls whether /etc/fstab.hostname should be executed at jail startup
|
||||
time.
|
||||
.Xr ezjail-admin 1
|
||||
utility. Be careful about disabling
|
||||
.Em ezjail_mount_enable .
|
||||
.Bl -tag -width option
|
||||
.It ezjail_mount_enable (bool)
|
||||
Controls whether
|
||||
.Pa /etc/fstab. Ar hostname
|
||||
should be executed at jail startup time.
|
||||
.br
|
||||
.I default: "YES"
|
||||
.TP
|
||||
.B ezjail_devfs_enable (bool)
|
||||
Default:
|
||||
.Em YES .
|
||||
.It ezjail_devfs_enable (bool)
|
||||
Controls whether newly created jails are given a working
|
||||
.I /dev
|
||||
.Pa /dev
|
||||
directory. (Refer to
|
||||
.B devfs(5)
|
||||
.Xr devfs 5
|
||||
and
|
||||
.B jail(8)
|
||||
.Xr jail 8
|
||||
for more information).
|
||||
.br
|
||||
.I default: "YES"
|
||||
.TP
|
||||
.B ezjail_devfs_ruleset (str)
|
||||
Default:
|
||||
.Em YES .
|
||||
.It ezjail_devfs_ruleset (str)
|
||||
Specifies which devfs ruleset should apply for newly created jails.
|
||||
(Refer to
|
||||
.B devfs(5)
|
||||
.Xr devfs 5
|
||||
and
|
||||
.N jail(8)
|
||||
.Xr jail 8
|
||||
for more information).
|
||||
.br
|
||||
.I default: "devfsrules_jail"
|
||||
.TP
|
||||
.B ezjail_procfs_enable (bool)
|
||||
Default:
|
||||
.Em devfsrules_jail .
|
||||
.It ezjail_procfs_enable (bool)
|
||||
Controls whether newly created jails are given a working
|
||||
.I /proc
|
||||
.Pa /proc
|
||||
directory. (Refer to
|
||||
.B procfs(5)
|
||||
.Xr procfs 5
|
||||
and
|
||||
.B jail(8)
|
||||
.Xr jail (8)
|
||||
for more information).
|
||||
.br
|
||||
.I default: "YES"
|
||||
.TP
|
||||
.B ezjail_fdescfs_enable (bool)
|
||||
Default:
|
||||
.Em YES .
|
||||
.It ezjail_fdescfs_enable (bool)
|
||||
Controls whether newly created jails are given a working
|
||||
.I /dev/fd/
|
||||
.Pa /dev/fd/
|
||||
directory. (Refer to
|
||||
.B fdescfs(5)
|
||||
.Xr fdescfs (5)
|
||||
and
|
||||
.B jail(8)
|
||||
.Xr jail (8)
|
||||
for more information).
|
||||
.br
|
||||
.I default: "YES"
|
||||
.TP
|
||||
.B ezjail_uglyperlhack (bool)
|
||||
Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail.
|
||||
Default:
|
||||
.Em YES .
|
||||
.It ezjail_uglyperlhack (bool)
|
||||
Set to YES, if ezjail should provide a soft link from
|
||||
.Pa /usr/bin/perl
|
||||
to
|
||||
.Pa /usr/local/bin/perl
|
||||
in base jail.
|
||||
.br
|
||||
.I default: YES
|
||||
.TP
|
||||
.B ezjail_default_flavour (str)
|
||||
Controls which flavours should be used for newly created jails if none are given on the command line.
|
||||
Default:
|
||||
.Em YES .
|
||||
.It ezjail_default_flavour (str)
|
||||
Controls which flavours should be used for newly created jails if none
|
||||
are given on the command line.
|
||||
.br
|
||||
.I default: none
|
||||
.SH ZFS OPTIONS
|
||||
.TP
|
||||
.B ezjail_use_zfs (bool)
|
||||
Set to YES, if ezjail should manage basejail and newjail in a seperate ZFS-datasets.
|
||||
Default:
|
||||
.Em none .
|
||||
.It ezjail_imagetype (one of simple, bde, eli, zfs)
|
||||
Type of jail to create when creating a jail with the
|
||||
.Fl i
|
||||
flag without specifying the type explicitely.
|
||||
.br
|
||||
.I default: NO
|
||||
.TP
|
||||
.B ezjail_jailzfs (str)
|
||||
The name of the parent ZFS-dataset which ezjail will use to create jails on. It will be mounted at the ezjail_jaildir. Setting this will automaticly enable ezjail managing jails in seperate ZFS-datasets.
|
||||
Default:
|
||||
.Em simple
|
||||
.El
|
||||
.Sh ZFS OPTIONS
|
||||
.Bl -tag -width option
|
||||
.It ezjail_use_zfs (bool)
|
||||
Set to YES, if ezjail should manage basejail and newjail in a seperate
|
||||
ZFS-datasets.
|
||||
.br
|
||||
.I default: none
|
||||
.TP
|
||||
.B ezjail_zfs_properties (str)
|
||||
Default properties ZFS will use for creating datasets. See zfs(1m) for details. ADVANCED, be very careful!
|
||||
Default:
|
||||
.Em NO .
|
||||
.It ezjail_jailzfs (str)
|
||||
The name of the parent ZFS-dataset which ezjail will use to create
|
||||
jails on. It will be mounted in
|
||||
.Em ezjail_jaildir .
|
||||
Setting this will automaticly enable ezjail managing jails in seperate
|
||||
ZFS-datasets.
|
||||
.br
|
||||
.I default: none
|
||||
.SH FILES
|
||||
Default:
|
||||
.Em none .
|
||||
.It ezjail_zfs_properties (str)
|
||||
Default properties ZFS will use for creating datasets. See
|
||||
.Xr zfs 1m
|
||||
for details. ADVANCED, be very careful!
|
||||
.br
|
||||
Default:
|
||||
.Em none .
|
||||
.El
|
||||
.Sh FILES
|
||||
EZJAIL_PREFIX/etc/ezjail.conf
|
||||
.br
|
||||
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
||||
.SH "SEE ALSO"
|
||||
ezjail-admin(1), ezjail(5), jail(8), devfs(5), fdescfs(5), procfs(5)
|
||||
.SH AUTHOR
|
||||
Dirk Engling <erdgeist@erdgeist.org>
|
||||
.Sh SEE ALSO
|
||||
.Xr ezjail-admin 1 ,
|
||||
.Xr ezjail 5 ,
|
||||
.Xr jail 8 ,
|
||||
.Xr devfs 5 ,
|
||||
.Xr fdescfs 5 ,
|
||||
.Xr procfs 5 .
|
||||
.Sh AUTHOR
|
||||
Dirk Engling
|
||||
.Aq erdgeist@erdgeist.org .
|
||||
|
||||
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