DragonFly On-Line Manual Pages
JAILCTL(1) DragonFly General Commands Manual (urm) JAILCTL(1)
NAME
jailctl - FreeBSD 4.x/5.x/6.x jail management shellscript
SYNOPSIS
jailctl [command jail parameter ...]
DESCRIPTION
jailctl is a tool to allow for easy creating, upgrading, starting,
stopping, backing up, restoring and deleting of jails. It is easily
configured either through in-file configuration or through a
configuration file located in /usr/local/etc/jails.conf.
IMPLEMENTATION NOTES
jailctl 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
customize.
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
commands 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
automatic starting of the jails upon host system bootup.
USAGE
jailctl 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 system.
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 executed on a running
jail, remember to restart the jail afterwards.
start [force]
Starts the specified jail. This will mount all the filesystems
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 terminate/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 different in
that while the cold backup is performed in the same way as a
backup on FreeBSD 4.x, the warm backup is performed 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 handling 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 running (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 specified 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 during
creation of jail to allow for customization (package
installations, etc.)
EXAMPLES
jailctl 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/jailbackup.tar.gz
jailctl
Displays usage information (brief)
SEE ALSO
jail(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 Overby <ltning@anduin.net>
BUGS
None known.
FreeBSD 6.1 March 14, 2004 FreeBSD 6.1