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