lib/libc/sys/jail.2

   1 .\"
   2 .\"----------------------------------------------------------------------------
   3 .\""THE BEER-WARE LICENSE" (Revision 42):
   4 .\"<phk@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
   5 .\"can do whatever you want with this stuff. If we meet some day, and you think
   6 .\"this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
   7 .\"----------------------------------------------------------------------------
   8 .\"
   9 .\"$FreeBSD: src/lib/libc/sys/jail.2,v 1.10.2.10 2002/12/12 05:26:38 trhodes Exp $
  10 .\"
  11 .Dd April 28, 1999
  12 .Dt JAIL 2
  13 .Os
  14 .Sh NAME
  15 .Nm jail
  16 .Nd imprison current process and future decendants
  17 .Sh LIBRARY
  18 .Lb libc
  19 .Sh SYNOPSIS
  20 .In sys/types.h
  21 .In sys/jail.h
  22 .Ft int
  23 .Fn jail "struct jail *jail"
  24 .Sh DESCRIPTION
  25 The
  26 .Nm
  27 system call sets up a jail and locks the current process in it.
  28 .Pp
  29 The argument is a pointer to a structure describing the prison:
  30 .Bd -literal -offset indent
  31 struct jail {
  32         u_int32_t       version;
  33         char            *path;
  34         char            *hostname;
  35         u_int32_t       ip_number;
  36 };
  37 .Ed
  38 .Pp
  39 .Dq Li version
  40 defines the version of the API in use.  It should be set to zero at this time.
  41 .Pp
  42 The
  43 .Dq Li path
  44 pointer should be set to the directory which is to be the root of the
  45 prison.
  46 .Pp
  47 The
  48 .Dq Li hostname
  49 pointer can be set to the hostname of the prison.  This can be changed
  50 from the inside of the prison.
  51 .Pp
  52 The
  53 .Dq Li ip_number
  54 can be set to the IP number assigned to the prison.
  55 .Sh PRISON?
  56 Once a process has been put in a prison, it and its decendants cannot escape
  57 the prison.  It is not possible to add a process to a preexisting prison.
  58 .Pp
  59 Inside the prison, the concept of "superuser" is very diluted.  In general,
  60 it can be assumed that nothing can be mangled from inside a prison which
  61 does not exist entirely inside that prison.  For instance the directory
  62 tree below
  63 .Dq Li path
  64 can be manipulated all the ways a root can normally do it, including
  65 .Dq Li "rm -rf /*"
  66 but new device special nodes cannot be created because they reference
  67 shared resources (the device drivers in the kernel).
  68 .Pp
  69 All IP activity will be forced to happen to/from the IP number specified,
  70 which should be an alias on one of the network interfaces.
  71 .Pp
  72 It is possible to identify a process as jailed by examining
  73 .Dq Li /proc/<pid>/status :
  74 it will show a field near the end of the line, either as
  75 a single hyphen for a process at large, or the hostname currently
  76 set for the prison for jailed processes.
  77 .Sh ERRORS
  78 .Fn jail
  79 will fail if:
  80 .Bl -tag -width Er
  81 .It Bq Er EINVAL
  82 The version number of the argument is not correct.
  83 .El
  84 .Pp
  85 Further
  86 .Fn jail
  87 calls
  88 .Xr chroot 2
  89 internally, so it can fail for all the same reasons.
  90 Please consult the
  91 .Xr chroot 2
  92 manual page for details.
  93 .Sh SEE ALSO
  94 .Xr chdir 2 ,
  95 .Xr chroot 2
  96 .Sh HISTORY
  97 The
  98 .Fn jail
  99 function call appeared in
 100 .Fx 4.0 .
 101 .Sh AUTHORS
 102 The jail feature was written by
 103 .An Poul-Henning Kamp
 104 for R&D Associates
 105 .Dq Li http://www.rndassociates.com/
 106 who contributed it to
 107 .Fx .