===========================================================================
=== JAIL_TOOLS README, written by Rene K. Mueller <kiwi at the-labs dot com>
=== VERSION=0.12

History:
   (see HISTORY file)

Platform: FreeBSD 4.x and 5.x
   
===========================================================================
== Programs:

   jail_install: creates a jail, including /etc/rc.conf and sample user 'jail' 
      
   jail_start:   starts jail
   
   jail_stop:    stops jail (and all its sub-processes)
   
   jail_delete:  removes jail (deletes diretory recursively)
                 WARNING: don't use it when you have still mounted content
                         within the jail, it will be removed as well!!!

   jail_update:  update/upgrade existing jail to new version (e.g. 4.8->4.9)

   jail_ps:      list processes of a particular jail or all running jails

   jail.sh:      called at boot to start particular jails as listed in
                 /usr/local/etc/jailtab

   For simplicity the jails are named after the IP they reside on, the
   hostname of the jails is <ip> too.

   In jail.conf (usually resides in /usr/local/etc/) you can config
   particular jails with dedicated hostnames:
      jailconfig_profx="ip 192.168.0.100"
      jailconfig_storm="ip 192.168.0.101"
      jailconfig_magneto="ip 192.168.0.102"
   etc.
   
   Possible fields in jailconfig_<name>:
         ip <ip>        e.g. ip 192.168.0.100
         shell <shell>  e.g. shell /bin/sh
         login <script> e.g. login /etc/rc
         if <if>        e.g. if rl0
         x11 <w>x<h>    e.g. x11 1024x768
         depth <depth>  e.g. depth 24
         ro_usr <path>  e.g. -t null /usr
         
   Read jail.conf (or jail.conf.dist) for detailed comments.
  
   Examples:
      % jail_install 192.168.0.100
      % jail_start 192.168.0.100
      % jail_stop 192.168.0.100

   or if defined:
      % jail_install profx
      % jail_start profx
      % jail_stop profx

   jail.sh takes care to start jails at boot of the host, the file
   /usr/local/etc/jailtab defines the jails to be started (like /etc/fstab)

      
===========================================================================
== Introduction

Check http://the-labs.com/FreeBSD/JailTools/ for an introduction to jails.



===========================================================================
== Prepare to run jails

= Install jail_tools, as root:
   make install 

edit /usr/local/etc/jail.conf (copy it jail.conf.dist), it's well documented


= Build FreeBSD 'WORLD' from Sources:

In order to create a jail you need to have freebsd 'world' build from sources:

   SYSINSTALL:
      run /stand/sysinstall and go to Configure -> Distributions -> src
      you can even select if you install the sources via CD, FTP, HTTP etc
      
   CVSUP:
      another way is via cvsup, if you miss cvsup do this:
         pkg_add -r cvsup-without-gui
      first and then
         cvsup -g -L 2 -h cvsup2.freebsd.org \
            /usr/share/examples/cvsup/standard-supfile

      (replace cvsup2... with cvsupN... where N=2..14)
      
Compile the system from sources:
   cd /usr/src
   make buildworld


= procfs Activation

Make sure (especially under FreeBSD 5.x) that the /proc is mounted, if not
      mount -t procfs proc /proc
and/or put it into /etc/fstab
   proc   /proc  procfs  rw 0 0
   
as it is required by jail_ps (listing running jails, and its processes), and
jail_stop

   
===========================================================================
== Tools for the Jail Host:

= Install Jail:

   jail_install 192.168.0.100  this may take 1-2 mins, and produces some
   jail_install profx          outputs (most is redirected to /dev/null),
                               as the entire freebsd system is installed 
                               there
                               
   jail_install -light profx   makes a 'light-install', copies various 
                               dirs of the jail-host, and when jail_start
                               is done /usr is mounted to the jail (like
                               as diskless would do it)

   jail_install -disk 256000 profx
   jail_install -light -disk 256000 profx
                               makes a file-based disk-install, the
                               entire file-system is in 192.168.0.100.dsk
                               <disk_size> in KB (1KB = 1024 bytes)

   NOTE: 
   
   if you reboot or crash the jail-host (and all jails stop without jail_stop)
   you have to clean up <jail_root>/.vn/* with "rm -f" or so, there the list 
   of vnodes (pseudo disk devices) are stored. best add following line to 
   your /etc/rc.local
      /bin/rm -f <jail_root>/.vn/*
   lookup your jail_root setting within your jail.conf in /usr/local/etc/.
   
   if defined your jails in jailtab (to start up when jail-host bootup), 
   then jail.sh cleans up <jail_root>/.vn/* for you.


= Start Jail:

   jail_start 192.168.0.100    according what you defined in ../etc/jail.conf
   jail_start profx            it enters the jail, once you exited you are
                               out and jail terminated. in case /etc/rc
                               and its jailed inetd is running the jail
                               actually still exists, and you can ftp/rlogin
                               to it when it's enabled in inetd.conf in the
                               jail

   NOTE:
   When you have aliased/named a jail in jail.conf, then preferable 
   use the alias to start it, this way the jail_stop works properly.


= Stop Jail:

   jail_stop 192.168.0.100     stops all processes related to this jail,
   jail_stop profx             used /proc of the host

   NOTE:
   When you have aliased/named a jail in jail.conf, then preferable 
   use the alias to stop it.


= Delete Jail:

   jail_delete 192.168.0.100   removes the entire jail, be aware after that
   jail_delete profx           it's gone entirely
                               WARNING: don't use it when you have still 
                               mounted content within the jail, it will be 
                               removed as well!!!

= Jail Update:

   jail_update 192.168.0.100   updates/upgrades jail (world), required is
                               that jail-host has been upgraded already,
                               and buildworld is up-to-date
                               

= List Process List:
   jail_ps                     list all running jails by their names
   
   jail_ps 192.168.0.100       list all processes associated to a
   jail_ps profx               particular jail



= FreeBSD 5.x Features

Since FreeBSD 5.1 new commands or features are part of system:

   - jail(8) now supports a -i flag to output an identifier for a 
     newly-created jail.
 
   - jexec(8) utility has been added to execute a command inside 
     an existing jail.
 
   - jls(8) utility has been added to list existing jails.

   - killall(1) now supports a -j option to kill all processes inside 
     a jail.

jail(8) creates an unique ID for each jail, and jls(8) lists them. It seems
each jail(8) call creates a new unique ID, and those cannot be removed (even
the jail is stopped). At the first sight this new jail-ID makes little
sense to me, rather should have name/alias and/or the IP used as unique
identifier.


===========================================================================
== Layout Details:

Assuming the jail_root is at /usr/jails/, then the 
jail with ip 192.168.0.100 (or named):

   % ls /usr/jails/192.168.0.100
   .cshrc          boot            kernel          root            tmp
   .profile        dev             mnt             sbin            usr
   COPYRIGHT       etc             modules         stand           var
   bin             home            proc            sys

and requires aprx. 140-150MB per jail.


===========================================================================
== VNode (Pseudo Device) Details:

jail_install takes vn9 to install the base-system (full or light), 
and afterwards frees it again. jail_start looks up which vnX is free 
(<jail_root>/.vn/*) and uses it, it starts with vn10 and up. The 
vn0 .. vn8 are free to be used for other purposes (e.g. file-based
disks) etc.

NOTE: Make sure no other applications uses vn9...vnMAX (where MAX is
      the max amount of jails with file-based disks), otherwise you 
      corrupt the file-based disks jails! Under FreeBSD 5.x the mdX 
      is used, so md9..mdMAX respectively.

===========================================================================
== X11 setup using Xvnc (VNC)

(see README.x11 file)


-- Rene K. Mueller, 02/2004