GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  JAILCTL (1)

NAME

jailctl - FreeBSD 4.x/5.x/6.x jail management shellscript

CONTENTS

Synopsis
Description
Implementation Notes
Getting Started
Usage
Files
Examples
See Also
History
Authors
Bugs

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


.An Eirik �verby <ltning@anduin.net>

BUGS

None known.
Search for    or go to Top of page |  Section 1 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.