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 January 6, 2009
  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         char            *jailname;
  38         unsigned int    ip4s;
  39         unsigned int    ip6s;
  40         struct in_addr  *ip4;
  41         struct in6_addr *ip6;
  42 };
  43 .Ed
  44 .Pp
  45 .Dq Li version
  46 defines the version of the API in use.
  47 .Dv JAIL_API_VERSION
  48 is defined for the current version.
  49 .Pp
  50 The
  51 .Dq Li path
  52 pointer should be set to the directory which is to be the root of the
  53 prison.
  54 .Pp
  55 The
  56 .Dq Li hostname
  57 pointer can be set to the hostname of the prison.
  58 This can be changed
  59 from the inside of the prison.
  60 .Pp
  61 The
  62 .Dq Li jailname
  63 pointer is an optional name that can be assigned to the jail
  64 for example for managment purposes.
  65 .Pp
  66 The
  67 .Dq Li ip4s
  68 and
  69 .Dq Li ip6s
  70 give the numbers of IPv4 and IPv6 addresses that will be passed
  71 via their respective pointers.
  72 .Pp
  73 The
  74 .Dq Li ip4
  75 and
  76 .Dq Li ip6
  77 pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
  78 the prison, or NULL if none.
  79 IPv4 addresses must be in network byte order.
  80 .Pp
  81 The
  82 .Fn jail_attach
  83 system call attaches the current process to an existing jail,
  84 identified by
  85 .Fa jid .
  86 .Sh RETURN VALUES
  87 If successful,
  88 .Fn jail
  89 returns a non-negative integer, termed the jail identifier (JID).
  90 It returns \-1 on failure, and sets
  91 .Va errno
  92 to indicate the error.
  93 .Pp
  94 .Rv -std jail_attach
  95 .Sh PRISON?
  96 Once a process has been put in a prison, it and its descendants cannot escape
  97 the prison.
  98 .Pp
  99 Inside the prison, the concept of
 100 .Dq superuser
 101 is very diluted.
 102 In general,
 103 it can be assumed that nothing can be mangled from inside a prison which
 104 does not exist entirely inside that prison.
 105 For instance the directory
 106 tree below
 107 .Dq Li path
 108 can be manipulated all the ways a root can normally do it, including
 109 .Dq Li "rm -rf /*"
 110 but new device special nodes cannot be created because they reference
 111 shared resources (the device drivers in the kernel).
 112 The effective
 113 .Dq securelevel
 114 for a process is the greater of the global
 115 .Dq securelevel
 116 or, if present, the per-jail
 117 .Dq securelevel .
 118 .Pp
 119 All IP activity will be forced to happen to/from the IP number specified,
 120 which should be an alias on one of the network interfaces.
 121 All connections to/from the loopback address
 122 .Pf ( Li 127.0.0.1
 123 for IPv4,
 124 .Li ::1
 125 for IPv6) will be changed to be to/from the primary address
 126 of the jail for the given address family.
 127 .Pp
 128 It is possible to identify a process as jailed by examining
 129 .Dq Li /proc/<pid>/status :
 130 it will show a field near the end of the line, either as
 131 a single hyphen for a process at large, or the hostname currently
 132 set for the prison for jailed processes.
 133 .Sh ERRORS
 134 The
 135 .Fn jail
 136 system call
 137 will fail if:
 138 .Bl -tag -width Er
 139 .It Bq Er EINVAL
 140 The version number of the argument is not correct.
 141 .El
 142 .Pp
 143 Further
 144 .Fn jail
 145 calls
 146 .Xr chroot 2
 147 internally, so it can fail for all the same reasons.
 148 Please consult the
 149 .Xr chroot 2
 150 manual page for details.
 151 .Sh SEE ALSO
 152 .Xr chdir 2 ,
 153 .Xr chroot 2
 154 .Sh HISTORY
 155 The
 156 .Fn jail
 157 system call appeared in
 158 .Fx 4.0 .
 159 The
 160 .Fn jail_attach
 161 system call appeared in
 162 .Fx 5.1 .
 163 .Sh AUTHORS
 164 The jail feature was written by
 165 .An Poul-Henning Kamp
 166 for R&D Associates
 167 .Dq Li http://www.rndassociates.com/
 168 who contributed it to
 169 .Fx .