home | help 
JAIL(2) 		       System Calls Manual			 JAIL(2)

NAME
     jail, jail_attach -- imprison current process and future descendants

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/param.h>
     #include <sys/jail.h>

     int
     jail(struct jail *jail);

     int
     jail_attach(int jid);

DESCRIPTION
     The jail() system call sets up a jail and locks the current process in it.

     The argument is a pointer to a structure describing the prison:

	   struct jail {
		   u_int32_t	   version;
		   char 	   *path;
		   char 	   *hostname;
		   u_int32_t	   ip_number;
	   };

     "version"	defines the version of the API in use.	It should be set to zero
     at this time.

     The "path" pointer should be set to the directory which is to be  the  root
     of the prison.

     The  "hostname" pointer can be set to the hostname of the prison.	This can
     be changed from the inside of the prison.

     The "ip_number" can be set to the IP number assigned to the prison.

     The jail_attach() system call attaches the current process to  an	existing
     jail, identified by jid.

RETURN VALUES
     If successful, jail() returns a non-negative integer, termed the jail iden-
     tifier (JID).  It returns -1 on failure, and sets errno to indicate the er-
     ror.

     The jail_attach() function returns the value 0 if successful; otherwise the
     value  -1	is returned and the global variable errno is set to indicate the
     error.

PRISON?
     Once a process has been put in a prison, it and its descendants cannot  es-
     cape the prison.

     Inside the prison, the concept of "superuser" is very diluted.  In general,
     it  can  be  assumed that nothing can be mangled from inside a prison which
     does not exist entirely inside that prison.   For	instance  the  directory
     tree  below  "path"  can be manipulated all the ways a root can normally do
     it, including "rm -rf /*" but new device special nodes  cannot  be  created
     because they reference shared resources (the device drivers in the kernel).
     The  effective  "securelevel"  for  a  process is the greater of the global
     "securelevel" or, if present, the per-jail "securelevel".

     All IP activity will be forced to happen to/from the IP  number  specified,
     which should be an alias on one of the network interfaces.

     It   is   possible   to   identify   a   process  as  jailed  by  examining
     "/proc/<pid>/status": it will show a field near the end of the line, either
     as a single hyphen for a process at large, or the	hostname  currently  set
     for the prison for jailed processes.

ERRORS
     The jail() system call will fail if:

     [EINVAL]		The version number of the argument is not correct.

     Further  jail() calls chroot(2) internally, so it can fail for all the same
     reasons.  Please consult the chroot(2) manual page for details.

SEE ALSO
     chdir(2), chroot(2)

HISTORY
     The jail() system call appeared in FreeBSD 4.0.  The  jail_attach()  system
     call appeared in FreeBSD 5.1.

AUTHORS
     The  jail	feature  was  written  by  Poul-Henning  Kamp for R&D Associates
     "http://www.rndassociates.com/" who contributed it to FreeBSD.

FreeBSD 6.0			  April 8, 2003 			 JAIL(2)
home | help