path: root/man1/ezjail-admin.1

.TH ezjail\-admin 1
.SH NAME
ezjail-admin \- Administrate ezjail
.SH SYNOPSIS
.T
.B ezjail-admin create
[-f flavour] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli] [-C attachargs] [-a archive]\fI hostname jailip

.T
.B ezjail-admin delete \fR[-w] \fI hostname

.T
.B ezjail-admin list

.T
.B ezjail-admin config\fR [-r run|norun] [-n newname] [-i attach|detach|fsck]\fI jailname

.T
.B ezjail-admin console\fR [-f] [-e command]\fI jailname

.T
.B ezjail-admin archive\fR [-Af] [-a archive] [-d archivedir]\fI [jailname...]

.T
.B ezjail-admin install\fR [-mps] [-h host] [-r release]

.T
.B ezjail-admin update\fR [-s sourcetree] [-i] [-pP]
.SH DESCRIPTION
The \fB ezjail-admin\fR tool is used to manage jails inside the ezjail
scope.

It can also be used to start or stop and to get a console in ezjails
jails by proxying everything looking like
\fBezjail-admin start\fR, \fBstop\fR or \fBrestart\fR to the ezjail rc.d script.
.SH ezjail-admin create
copies the template jail to the root of a new jail, whose name and IP
address are provided as mandatory parameters.

If no jail root is specified via the -r option, it is derived from
the jails name. In this case or, if a jail root is given and does not
start with a '/', it is interpreted relative to ezjails root dir
(default: \fI/usr/jails\fR). If a specified jail root lies outside
ezjail root dir, a soft link is created inside this root dir pointing
to the newly created jails location.

The -i and the -c option both require a size passed via the -s option
and create a file based jail image, gbde or geli encrypted for the -c 
case. The image file is named as the jail root suffixed with \fI.img\fR.

The -x (jail exists) 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 properties and called ezjail-admin delete without the -w option
before. However, sanity checks are being performed.

The script creates an entry in its config and a \Fi/etc/fstab.hostname\fR
file allowing the jail to be brought up after next reboot (or) via
the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.

The newly created jail can perform some initializiation actions, if the
-f \fIflavour\fR option is given, where \fIflavour\fR is a directory tree
under ezjails root dir (default: \fI/usr/jails/flavours\fR). See section
\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 delete
removes a jail from ezjails 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 ezjails root dir.
.SH ezjail-admin list
lists all jails inside ezjails scope. They are sorted by the order they 
start up, as defined by rcorder. The list format is straight forward.

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. 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).

Rest of the row is jails jid (if available), its IP, hostname and root directory.
.SH ezjail-admin archive
creates a backup of one, multiple or all ezjails.

Unless an archive name is given via -a switch, the archive's name is derived from
jailname, date and time. It is being 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 or specify one or more
ezjails.
.SH ezjail-admin config
manages existing specific ezjails.

You can prevent an ezjail from being run at system start by the -r norun
option and reenable it by -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, it is being
renamed as well.

You can attach image jails for administrative purposes by 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 console
Attaches your console to a jail by executing a jexec with its jid.

The command executed in that jail defaults to /bin/sh but can be set with the
-e modifier or by 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 install
fetches everything needed to setup a base jail from an FTP server and 
installs it.

Default location for ezjails 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).

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 from command line.

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 do some modifications to install.sh
scripts before executing them.

You can later update your world from CVS or update ports by \fIezjail-admin
update\fR or rerun this subcommand with another OS version.
.SH ezjail-admin update
creates or update ezjails basejail. Depending on the parameters
given it will install a FreeBSD system 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 options are 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 this can
be done, while jails are running.

If the -i (install only) option is given, \fBezjail-admin update\fR only
performes 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 systems 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 base jail, 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/default/.\fR Some typical Jail
initialization actions are demonstrated and you are encouraged to use it as a
template for your flavours.

If a flavour is selected on jail creation, the flavour root is being
copied to the new Jails root, mostly containing an \fI/ezjail.flavour\fR.
If the Jail starts up for the first time this script is run.

In its default form it will create some groups and users, change the
ownership of some files and installs 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)
.SH AUTHOR
Dirk Engling <erdgeist@erdgeist.org>