JAILCTL(1) User's Reference Manual JAILCTL(1)NAMEjailctl — FreeBSD 4.x/5.x/6.x jail management shellscript
SYNOPSISjailctl [command jail parameter ...]
DESCRIPTIONjailctl is a tool to allow for easy creating, upgrading, starting, stop‐
ping, backing up, restoring and deleting of jails. It is easily config‐
ured either through in-file configuration or through a configuration file
located in /usr/local/etc/jails.conf.
IMPLEMENTATION NOTESjailctl is implemented as a shellscript, requiring only what is present
in any default FreeBSD installation.
This version of jailctl will work on FreeBSD versions 4.5 and above. On
versions 5.0 and above, it will make use of the new jexec(8) and jls(8)
commands, which are only present in the FreeBSD 5-series. Versions prior
to 5.3 (apart from betas and release candidates of 5.3) have exhibited
various issues with these tools, so their function cannot be guaranteed.
GETTING STARTED
In order to use jailctl you need to decide where you want your jails to
be stored. This directory needs to exist, and the addons.tar.gz file
should be unpacked into this directory. The jails.conf file must be
placed into /usr/local/etc, or whereever you specify in jailctl itself
that it is located. Edit this file to suit your tastes and the jails you
wish to run; it should be self-documenting.
If you have installed jailctl from a port (sysutils/jailctl), or ran make
install to install it from source distribution, the jail directory
defaults to /usr/local/jails, and the addons are copied to this directory
automatically. There will also be a sample configuration file in
/usr/local/etc/jails.conf.sample, of which you should make a copy to cus‐
tomize.
The addons directory contains files that will be copied into new jails
when they are created. The directory structure will be copied as-is. The
important file runme.sh will be executed inside the jail when the jail is
created, so this is the place to put any pkg_adds or other one-time com‐
mands that should be run automagically.
Once you have created a jail with jailctl create <jail>, you can start
and stop the jails with jailctl start <jail> and jailctl stop <jail>.
Place the jails.sh script into /usr/local/etc/rc.d to facilitate auto‐
matic starting of the jails upon host system bootup.
USAGEjailctl accepts two or more arguments: command, jail and any parameters
required by command.
command specifies the mode of operation, and can be either of
create Creates a new jail from scratch. This will run a make
installworld from /usr/src, and thus requires that the
sources there have been built and are in sync with what is
installed on the host system.
Default configuration files will then be installed, and the
jail will be started once in order to execute the runme.sh
script that is copied in from the addons directory. The
/etc/hosts and /etc/resolv.conf files inside the jail are
created/updated. After all this is done, excess files in
the jail are cleaned away to minimize diskspace usage. The
files to be cleaned out are listed in the /dellist?.txt
file (where ? denotes FreeBSD version; jailctl will choose
the closest match) from the addons directory.
upgrade This will run make installworld and mergemaster(8) to bring
the specified jail up to the same version as the host sys‐
tem. Subsequently, the same cleaning up procedure as is
done during create is repeated to remove any unneeded files
that may have been installed during the upgrade. If exe‐
cuted on a running jail, remember to restart the jail
afterwards.
start [force]
Starts the specified jail. This will mount all the filesys‐
tems the jail needs to function, like /proc,
/compat/linux/proc, and /dev. It will then bring up the
virtual network interface (alias), and start the jail. Set
the force parameter to 1 to force starting the jail, in
case jailctl falsely thinks the jail is already running.
stop Stops the jail, undoing what the start command did.
On FreeBSD 4.x it will consult the /proc filesystem on the
host to identify processes running in the jail, and termi‐
nate/kill these.
On FreeBSD 5.x/6.x, the jexec(8) command is used to execute
any existing /etc/rc.d/shutdown script in the jail, and
subsequently terminate any remaining processes in the jail.
After the jail has terminated successfully, mountpoints are
unmounted, and the network interface alias is removed.
backup Backs up the jail. The backup destination defaults to the
jail directory ( $JAILS_HOME ), or can be set using the
$BACKUPDIR variable in jails.conf.
On FreeBSD 4.x, all backups are done by chroot(8) - ing
into the jail directory before running tar(1) to perform
the backup.
For FreeBSD 5.x and 6.x, warm and cold backups are differ‐
ent in that while the cold backup is performed in the same
way as a backup on FreeBSD 4.x, the warm backup is per‐
formed by using jexec(8). This way the tar(1) command is
run from inside the jail, as opposed to running it on the
host system. Benefits include more reliable permission han‐
dling and special file treatment.
restore Restores a jail from a .tar.gz file. If a filename is not
specified, jailctl tries to determine the name and location
of the backup automatically. Otherwise the specified file
is used. The jail directory is created and the backup is
extracted into this directory.
delete Deletes a jail directory entirely. Will use chflags(1) to
reset the immutable flags, before the entire tree is
deleted. Set the force parameter to 1 to force deleting the
jail.
status Displays status of the configured jails. A jail can be in
three states, started (*), not yet created (!) and not run‐
ning (no marker). Can be called without further arguments
to show the status of all jails. When called with a jail
name, status will output a process listing for the speci‐
fied jail.
jail specifies which jail to operate on. This can either be the full name
of a jail as specified in the $JAILS variable, or the special keyword
all, which will cause the command to be executed on all jails. Note that
the all keyword can only be used with the start, stop, backup, upgrade
and status commands.
FILES
Recommended/default locations in parenthesis.
jailctl Main program (/usr/local/sbin)
jails.conf Configuration file (/usr/local/etc)
jails.sh Startup script (/usr/local/etc/rc.d)
addons Directory containing files that will be copied into new
jails
runme.sh Located within the addons directory, will be executed dur‐
ing creation of jail to allow for customization (package
installations, etc.)
EXAMPLESjailctl start jail.example.org
Starts the jail 'jail.example.org'
jailctl create jail.foo.biz
Creates the jail 'jail.foo.biz'
jailctl status all
Shows a list of configured jails and their status
jailctl status jail.example.org
Shows a process list for the jail 'jail.example.org'
jailctl backup jail.example.org
Backs up the jail 'jail.example.org'
jailctl restore jail.example.org
Restores the jail 'jail.example.org' from the default
backup file
jailctl restore jail.example.org /tmp/jailbackup.tar.gz
Restores the jail 'jail.example.org' from /tmp/jail‐
backup.tar.gz
jailctl Displays usage information (brief)
SEE ALSOjail(8), jail(2).
HISTORY
This script was created in February/March 2004. It received a major
facelift in February/March 2005, gaining support for both FreeBSD 4.x and
5.x, plus the backup/restore functions. It was officially added to the
FreeBSD ports tree on the 6th of April 2005.
AUTHORS
Eirik �verby <ltning@anduin.net>
BUGS
None known.
FreeBSD 6.1 March 14, 2004 FreeBSD 6.1
