2005-09-05 02:49:33 +00:00
|
|
|
.TH ezjail\-admin 1
|
|
|
|
.SH NAME
|
|
|
|
ezjail-admin \- Administrate ezjail
|
|
|
|
.SH SYNOPSIS
|
2008-07-08 18:45:24 +00:00
|
|
|
.T
|
2008-07-10 18:55:39 +00:00
|
|
|
.B ezjail-admin install\fR [-mMpPsS] [-h host] [-r release]
|
2008-07-08 18:45:24 +00:00
|
|
|
|
2005-09-05 02:49:33 +00:00
|
|
|
.T
|
|
|
|
.B ezjail-admin create
|
2009-08-21 13:46:27 +00:00
|
|
|
[-f flavour] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli|zfs] [-C attachargs] [-a archive]\fI hostname jailip
|
2005-09-05 02:49:33 +00:00
|
|
|
|
|
|
|
.T
|
2008-07-08 18:45:24 +00:00
|
|
|
.B ezjail-admin console\fR [-f] [-e command]\fI jailname
|
2005-09-05 02:49:33 +00:00
|
|
|
|
|
|
|
.T
|
|
|
|
.B ezjail-admin list
|
|
|
|
|
2006-05-16 10:53:16 +00:00
|
|
|
.T
|
2010-01-08 22:08:26 +00:00
|
|
|
.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
|
2006-05-22 00:20:47 +00:00
|
|
|
|
2007-09-15 00:25:52 +00:00
|
|
|
.T
|
2008-07-08 18:45:24 +00:00
|
|
|
.B ezjail-admin delete \fR[-w] \fI hostname
|
2007-09-15 00:25:52 +00:00
|
|
|
|
2007-10-01 01:44:04 +00:00
|
|
|
.T
|
|
|
|
.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]
|
|
|
|
|
2006-05-22 00:20:47 +00:00
|
|
|
.T
|
2008-07-08 18:45:24 +00:00
|
|
|
.B ezjail-admin restore\fR [-f] [-d archivedir]\fI (archive|jailname)...
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2005-09-05 02:49:33 +00:00
|
|
|
.T
|
2007-02-21 04:20:56 +00:00
|
|
|
.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
|
2008-07-08 18:45:24 +00:00
|
|
|
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH DESCRIPTION
|
2008-07-08 18:45:24 +00:00
|
|
|
The \fBezjail-admin\fR tool is used to manage the ezjail environment
|
|
|
|
and jails inside the ezjail scope.
|
2007-09-15 00:25:52 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
It can also be used to start or stop and to get a console in ezjail's
|
2007-09-15 00:25:52 +00:00
|
|
|
jails by proxying everything looking like
|
|
|
|
\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
|
2008-07-08 18:45:24 +00:00
|
|
|
.SH ezjail-admin install
|
|
|
|
fetches everything needed to setup an ezjail environment from an FTP server and
|
|
|
|
installs it.
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
The default location for ezjail's base jail is \fI/usr/jails\fR, so be sure you
|
2008-07-08 18:45:24 +00:00
|
|
|
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).
|
2008-08-06 16:05:08 +00:00
|
|
|
Options -M, -P or -S behave like their lower case pendants, but they
|
2008-07-10 18:55:39 +00:00
|
|
|
disable (re)installing your basejail.
|
2008-07-08 18:45:24 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
The default OS version is whatever uname -r returns. If this does not match
|
2008-07-08 18:45:24 +00:00
|
|
|
"*-RELEASE", you will be prompted for a better guess. (Normally
|
|
|
|
ftp-servers do not provide release candidates or CURRENT builds). You can
|
2008-08-06 16:05:08 +00:00
|
|
|
use the -r option to specify a release on the command line.
|
2008-07-08 18:45:24 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
The default host to fetch packages from is ftp.freebsd.org; you may want to
|
2008-07-08 18:45:24 +00:00
|
|
|
change this via the -h option or in ezjail.conf(5).
|
|
|
|
|
|
|
|
If the specified location begins with file://, your local copy of the
|
2008-08-06 16:05:08 +00:00
|
|
|
release is used. That way you can modify the install.sh scripts before
|
|
|
|
executing them.
|
2008-07-08 18:45:24 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
You can later update your world from CVS or update ports with \fIezjail-admin
|
2008-07-08 18:45:24 +00:00
|
|
|
update\fR or rerun this subcommand with another OS version.
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH ezjail-admin create
|
2008-08-06 16:05:08 +00:00
|
|
|
installs a new jail inside ezjail's scope. It either copies the template
|
2008-07-08 18:45:24 +00:00
|
|
|
jail or an ezjail archive to the root of that new jail, whose name and IP
|
2006-02-08 11:13:58 +00:00
|
|
|
address are provided as mandatory parameters.
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
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
|
2008-07-08 18:45:24 +00:00
|
|
|
reboot (or) via the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
|
|
|
|
|
2006-02-08 11:13:58 +00:00
|
|
|
If no jail root is specified via the -r option, it is derived from
|
2008-08-06 16:05:08 +00:00
|
|
|
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
|
2007-02-21 04:20:56 +00:00
|
|
|
ezjail root dir, a soft link is created inside this root dir pointing
|
2008-08-06 16:05:08 +00:00
|
|
|
to the newly created jail's location.
|
2006-02-08 11:13:58 +00:00
|
|
|
|
2009-08-21 13:46:27 +00:00
|
|
|
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.
|
2008-07-08 18:45:24 +00:00
|
|
|
|
|
|
|
To install an ezjail archive instead of a vanilla copy of newjail use
|
2008-08-06 16:05:08 +00:00
|
|
|
-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
|
2008-07-08 18:45:24 +00:00
|
|
|
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
|
2008-08-06 16:05:08 +00:00
|
|
|
\fIezjail-admin restore\fR, if you only want to revert to an old jail's
|
2008-07-08 18:45:24 +00:00
|
|
|
state from a backup on the same host.
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
The -x option indicates that an ezjail already exists at the jail root.
|
2006-02-08 11:13:58 +00:00
|
|
|
.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
|
2008-08-06 16:05:08 +00:00
|
|
|
jail's properties and called ezjail-admin delete without the -w option
|
|
|
|
before. However, sanity checks are performed.
|
2006-02-08 11:13:58 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
Using the -f \fIflavour\fR option you can apply an ezjail \fBFLAVOUR\fR
|
2008-08-06 16:05:08 +00:00
|
|
|
to your ezjail (e.g. preinstall packages, add users, configure rc).
|
|
|
|
\fIflavour\fR is a directory tree under ezjail's root dir (default:
|
|
|
|
\fI/usr/jails/flavours\fR). See \fBFLAVOURS\fR below for more details.
|
2007-02-21 04:20:56 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
Options for newly created jails are read from \fBezjail.conf\fR; refer to
|
2007-02-21 04:20:56 +00:00
|
|
|
ezjail.conf(5) for more information.
|
2008-07-08 18:45:24 +00:00
|
|
|
.SH ezjail-admin console
|
|
|
|
Attaches your console to a jail by executing a jexec with its jid.
|
2005-09-05 02:49:33 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
The command executed in that jail defaults to \fI/usr/bin/login -f root\fR
|
2008-08-06 16:05:08 +00:00
|
|
|
but can be set with the -e modifier or by setting the ezjail_default_execute
|
2008-07-08 18:45:24 +00:00
|
|
|
config variable. A non-running jail is not started by default. If you want
|
|
|
|
that, force it with -f.
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH ezjail-admin list
|
2008-08-06 16:05:08 +00:00
|
|
|
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.
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2007-02-21 04:20:56 +00:00
|
|
|
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
|
2008-08-06 16:05:08 +00:00
|
|
|
image based, and the second one meaning \fB(R)unning\fR, \fB(A)ttached\fR but not
|
2007-02-21 04:20:56 +00:00
|
|
|
running, \fB(S)topped\fR. An optional \fB(N)orun\fR stands for disabled jails (see
|
|
|
|
\fIezjail-admin config\fR).
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
The rest of the row is the jail's jid (if available), its IP address, hostname and
|
|
|
|
root directory.
|
2006-05-22 00:20:47 +00:00
|
|
|
.SH ezjail-admin config
|
2008-07-08 18:45:24 +00:00
|
|
|
manages specific ezjails.
|
2006-05-22 00:20:47 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
You can prevent an ezjail from being run at system start with the -r norun
|
|
|
|
option and reenable it with -r run.
|
2006-05-22 00:20:47 +00:00
|
|
|
|
2006-11-15 19:37:21 +00:00
|
|
|
You can rename an ezjail by using the -n newname option. If the specified
|
2008-08-06 16:05:08 +00:00
|
|
|
ezjail is an image jail and the image has its default name, the image is
|
2006-11-15 19:37:21 +00:00
|
|
|
renamed as well.
|
|
|
|
|
2010-01-08 22:08:26 +00:00
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
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
|
2007-02-22 15:36:57 +00:00
|
|
|
an attached jail. You can force fscking a jail image with the -i fsck command.
|
2008-07-08 18:45:24 +00:00
|
|
|
.SH ezjail-admin delete
|
2008-08-06 16:05:08 +00:00
|
|
|
removes a jail from ezjail's config and the corresponding \fI/etc/fstab.hostname\fR
|
2008-07-08 18:45:24 +00:00
|
|
|
file, thus preventing the jail from being brought up on next reboot.
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
If the -w (wipe) option is given, the directory pointed to by the jail
|
2008-08-06 16:05:08 +00:00
|
|
|
root entry is removed as well as the soft link in ezjail's root dir.
|
2008-07-08 18:45:24 +00:00
|
|
|
.SH ezjail-admin archive
|
|
|
|
creates a backup of one, multiple or all ezjails.
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
Unless an archive name is given via -a switch, its file name is derived from
|
2008-08-06 16:05:08 +00:00
|
|
|
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
|
2008-07-08 18:45:24 +00:00
|
|
|
\fI.\fR .
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
Use -A with no further parameters to archive all jails \fBor\fR specify one or more
|
|
|
|
ezjails as parameters.
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
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.
|
2006-05-22 00:20:47 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
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.
|
2006-05-16 10:53:16 +00:00
|
|
|
|
2008-07-08 18:45:24 +00:00
|
|
|
By default \fBezjail-admin restore\R refuses to restore on a host different from
|
|
|
|
where it was archived. Use -f to force that.
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH ezjail-admin update
|
2008-08-06 16:05:08 +00:00
|
|
|
creates or updates ezjail's environment (aka basejail) from source. To install it
|
2008-07-08 18:45:24 +00:00
|
|
|
from ftp servers, use ezjail-admin install.
|
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
Depending on the parameters given, it will install the basejail from a source
|
2008-07-08 18:45:24 +00:00
|
|
|
tree whose location is either provided in the \fBezjail.conf\fR config file or
|
|
|
|
via the -s option.
|
2006-01-30 19:02:44 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
If the -p or -P option is given, the base jail also is given a copy of
|
2006-02-08 11:13:58 +00:00
|
|
|
FreeBSDs ports tree, which is in turn linked into all newly created
|
2006-05-16 10:53:16 +00:00
|
|
|
ezjails. The portsnap utility is invoked to do the actual work.
|
2006-01-30 19:02:44 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
If the -P option is given, \fBonly the ports tree will be updated,\fR so this can
|
|
|
|
be done while jails are running.
|
2005-09-20 22:34:11 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
If the -i (install only) option is given, \fBezjail-admin update\fR performs a
|
|
|
|
\fImake installworld,\fR otherwise \fImake world\fR is invoked.
|
2005-09-05 02:49:33 +00:00
|
|
|
|
2005-09-09 20:06:00 +00:00
|
|
|
.SH NOTES
|
2007-02-21 04:20:56 +00:00
|
|
|
.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
|
2008-08-06 16:05:08 +00:00
|
|
|
FreeBSD source tree used to build the host system's world, or at least its
|
2007-02-21 04:20:56 +00:00
|
|
|
kernel. Combining a make world in the host system with \fBezjail-admin update\fR
|
2005-09-09 20:06:00 +00:00
|
|
|
is considered a good idea.
|
2006-01-16 05:01:43 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
When a ports tree exists in basejail, a make.conf containing reasonable
|
2006-01-16 05:01:43 +00:00
|
|
|
values for having ports in jails is created in the template jail.
|
2005-11-21 17:37:12 +00:00
|
|
|
.SH FLAVOURS
|
2007-02-21 04:20:56 +00:00
|
|
|
.B ezjail-admin\fR provides an easy way to create many jails with similar or
|
|
|
|
identical properties.
|
2005-11-21 17:37:12 +00:00
|
|
|
|
2005-12-31 02:41:10 +00:00
|
|
|
A sample flavour config directory resides under
|
2008-08-06 16:05:08 +00:00
|
|
|
.I EZJAIL_PREFIX/share/examples/ezjail/default/.\fR Some typical jail
|
|
|
|
initialization actions are demonstrated, and you are encouraged to use it as
|
|
|
|
a template for your flavours.
|
2005-12-31 02:41:10 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
If a flavour is selected on jail creation, the flavour root is
|
|
|
|
copied to the new jail's root, mostly containing an \fI/ezjail.flavour\fR.
|
|
|
|
When the jail starts up for the first time, this script is run and deleted.
|
2006-02-09 01:21:56 +00:00
|
|
|
|
|
|
|
In its default form it will create some groups and users, change the
|
2008-08-06 16:05:08 +00:00
|
|
|
ownership of some files and install all packages residing under /pkg.
|
2006-02-08 17:12:04 +00:00
|
|
|
|
2008-08-06 16:05:08 +00:00
|
|
|
It allows you to add some post-install actions.
|
2005-11-21 17:37:12 +00:00
|
|
|
.SH EXAMPLES
|
2006-01-18 20:19:01 +00:00
|
|
|
ezjail-admin update -p
|
2005-11-21 17:37:12 +00:00
|
|
|
.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
|
2008-08-06 16:05:08 +00:00
|
|
|
Due to the way ezjail handles jail config files, it is not possible to
|
2006-02-08 11:13:58 +00:00
|
|
|
create multiple jails if their names are identical when piped through
|
|
|
|
.B tr -C [:alnum:] _
|
|
|
|
|
|
|
|
Sure to be others.
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH FILES
|
|
|
|
.T4
|
2005-09-24 14:46:53 +00:00
|
|
|
EZJAIL_PREFIX/etc/ezjail.conf
|
2005-09-05 02:49:33 +00:00
|
|
|
.br
|
2005-09-26 01:30:00 +00:00
|
|
|
EZJAIL_PREFIX/etc/rc.d/ezjail.sh
|
2005-11-21 17:37:12 +00:00
|
|
|
.br
|
|
|
|
EZJAIL_PREFIX/share/examples/ezjail/
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH "SEE ALSO"
|
2010-01-08 22:08:26 +00:00
|
|
|
ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8), cpuset(1), setfib(1)
|
2005-09-05 02:49:33 +00:00
|
|
|
.SH AUTHOR
|
|
|
|
Dirk Engling <erdgeist@erdgeist.org>
|