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$
  10 .\"
  11 .Dd August 3, 2008
  12 .Dt JAIL 2
  13 .Os
  14 .Sh NAME
  15 .Nm jail , jail_attach
  16 .Nd imprison current process and future descendants
  17 .Sh LIBRARY
  18 .Lb libc
  19 .Sh SYNOPSIS
  20 .In sys/param.h
  21 .In sys/jail.h
  22 .Ft int
  23 .Fn jail "struct jail *jail"
  24 .Ft int
  25 .Fn jail_attach "int jid"
  26 .Sh DESCRIPTION
  27 The
  28 .Fn jail
  29 system call sets up a jail and locks the current process in it.
  30 .Pp
  31 The argument is a pointer to a structure describing the prison:
  32 .Bd -literal -offset indent
  33 struct jail {
  34         u_int32_t       version;
  35         char            *path;
  36         char            *hostname;
  37         u_int32_t       ip_number;
  38 };
  39 .Ed
  40 .Pp
  41 .Dq Li version
  42 defines the version of the API in use.
  43 It should be set to zero at this time.
  44 .Pp
  45 The
  46 .Dq Li path
  47 pointer should be set to the directory which is to be the root of the
  48 prison.
  49 .Pp
  50 The
  51 .Dq Li hostname
  52 pointer can be set to the hostname of the prison.
  53 This can be changed
  54 from the inside of the prison.
  55 .Pp
  56 The
  57 .Dq Li ip_number
  58 can be set to the IP number assigned to the prison.
  59 .Pp
  60 The
  61 .Fn jail_attach
  62 system call attaches the current process to an existing jail,
  63 identified by
  64 .Fa jid .
  65 .Sh RETURN VALUES
  66 If successful,
  67 .Fn jail
  68 returns a non-negative integer, termed the jail identifier (JID).
  69 It returns \-1 on failure, and sets
  70 .Va errno
  71 to indicate the error.
  72 .Pp
  73 .Rv -std jail_attach
  74 .Sh PRISON?
  75 Once a process has been put in a prison, it and its descendants cannot escape
  76 the prison.
  77 .Pp
  78 Inside the prison, the concept of
  79 .Dq superuser
  80 is very diluted.
  81 In general,
  82 it can be assumed that nothing can be mangled from inside a prison which
  83 does not exist entirely inside that prison.
  84 For instance the directory
  85 tree below
  86 .Dq Li path
  87 can be manipulated all the ways a root can normally do it, including
  88 .Dq Li "rm -rf /*"
  89 but new device special nodes cannot be created because they reference
  90 shared resources (the device drivers in the kernel).
  91 The effective
  92 .Dq securelevel
  93 for a process is the greater of the global
  94 .Dq securelevel
  95 or, if present, the per-jail
  96 .Dq securelevel .
  97 .Pp
  98 All IP activity will be forced to happen to/from the IP number specified,
  99 which should be an alias on one of the network interfaces.
 100 .Pp
 101 It is possible to identify a process as jailed by examining
 102 .Dq Li /proc/<pid>/status :
 103 it will show a field near the end of the line, either as
 104 a single hyphen for a process at large, or the hostname currently
 105 set for the prison for jailed processes.
 106 .Sh ERRORS
 107 The
 108 .Fn jail
 109 system call
 110 will fail if:
 111 .Bl -tag -width Er
 112 .It Bq Er EINVAL
 113 The version number of the argument is not correct.
 114 .It Bq Er EAGAIN
 115 No free JID could be found.
 116 .El
 117 .Pp
 118 Further
 119 .Fn jail
 120 calls
 121 .Xr chroot 2
 122 internally, so it can fail for all the same reasons.
 123 Please consult the
 124 .Xr chroot 2
 125 manual page for details.
 126 .Sh SEE ALSO
 127 .Xr chdir 2 ,
 128 .Xr chroot 2
 129 .Sh HISTORY
 130 The
 131 .Fn jail
 132 system call appeared in
 133 .Fx 4.0 .
 134 The
 135 .Fn jail_attach
 136 system call appeared in
 137 .Fx 5.1 .
 138 .Sh AUTHORS
 139 The jail feature was written by
 140 .An Poul-Henning Kamp
 141 for R&D Associates
 142 .Dq Li http://www.rndassociates.com/
 143 who contributed it to
 144 .Fx .