DESCRIPTION

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

A 5.x or higher FreeBSD system is required.

SYNOPSIS

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;

EXAMPLES

Create a new jail

 $options = {
     path     => '/tmp',
     ip       => '127.0.0.1',
     hostname => 'example.com'
 };

 $j = BSD::Jail::Object->new( $options ) or die $@;

Attach to an existing jail

 $j = BSD::Jail::Object->new( 'example.com' );
 $j->attach;

Do something in all jails

 foreach $j ( jids(instantiate => 1) ) {

     if ( fork ) {
         $j->attach;

         #
         # do something exciting
         #

         exit;
     }
 }

Get information on a jail

(See the SYNOPSIS section above)

OBJECT METHODS

new()

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( 'example.com' ) or die $@;

 # existing jail, find by ip address
 $j = BSD::Jail::Object->new( '127.0.0.1' ) 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 => 'example.com',
        ip       => '127.0.0.1',
        path     => '/tmp'
 }) or die $@;

jid()

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

hostname()

Get the current jail hostname.

path()

Get the root path the jail was bound to.

attach()

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.

EXPORTABLE METHODS

jids()

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.

ACKNOWLEDGEMENTS

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

AUTHOR

Mahlon E. Smith mahlon@martini.nu for Spime Solutions Group (www.spime.net)

cpanm BSD::Jail::Object

perl -MCPAN -e shell
install BSD::Jail::Object