This is an object oriented wrapper around the FreeBSD jail subsystem.

A 5.x or higher FreeBSD system is required.


Here is an exact replica of the 'jls' utility in just a few lines of perl:

 use BSD::Jail::Object 'jids';

 print "   JID  IP Address      Hostname                      Path\n";
 printf "%6d  %-15.15s %-29.29s %.74s\n",
        $_->jid, $_->ip, $_->hostname, $_->path foreach jids( instantiate => 1 );

And here's 'jexec' (actually, a jexec that lets you optionally select by something other than jid):

 my $j = BSD::Jail::Object->new( $ARGV[0] ) or die $@;
 $j->attach && chdir('/') && exec $ARGV[1] or exit;


Create a new jail
 $options = {
     path     => '/tmp',
     ip       => '',
     hostname => ''

 $j = BSD::Jail::Object->new( $options ) or die $@;
Attach to an existing jail
 $j = BSD::Jail::Object->new( '' );
Do something in all jails
 foreach $j ( jids(instantiate => 1) ) {

     if ( fork ) {

         # do something exciting

Get information on a jail

(See the SYNOPSIS section above)



Instantiate a new BSD::Jail::Object object, either by associating ourselves with an already running jail, or by creating a new one from scratch.

To associate with an already active jail, new() accepts a jid, hostname, or ip address. Errors are placed into $@.

 # existing jail, find by jid
 $j = BSD::Jail::Object->new( 23 ) or die $@;

 # existing jail, find by hostname
 $j = BSD::Jail::Object->new( '' ) or die $@;

 # existing jail, find by ip address
 $j = BSD::Jail::Object->new( '' ) or die $@;

Note that if you're selecting a jail by hostname or IP, those aren't always unique values. Two jails could be running with the same hostname or IP address - this module will always select the highest numbered jid in that case. If you need to be sure you're in the 'right' jail when there are duplicates, select by JID.

Create a new jail by passing a hash reference. Required keys are 'hostname', 'ip', and 'path'. See the jail(8) man page for specifics on these keys.

 # create a new jail under /tmp
 $j = BSD::Jail::Object->new({
        hostname => '',
        ip       => '',
        path     => '/tmp'
 }) or die $@;


Get the current jail identifier. JIDs are assigned sequentially from the kernel.


Get the current jail hostname.


Get the root path the jail was bound to.


Imprison ourselves within a jail. Note that this generally requires root access, and is a one way operation. Once the script process is imprisioned, there is no way to perform a jailbreak! You'd need to fork() if you intended to attach to more than one jail. See EXAMPLES.



Returns an array of active JIDs. Can also return them as pre-instantiated objects by passing 'instantiate => 1' as an argument.

 my @jail_jids    = jids();
 my @jail_objects = jids( instantiate => 1 );

Only exported upon request.


Most of the jail specific C code was based on work by Mike Barcroft <> and Poul-Henning Kamp <> for the FreeBSD Project.


Mahlon E. Smith for Spime Solutions Group (