lib/libc/sys/jail.2

   1 .\" Copyright (c) 1999 Poul-Henning Kamp.
   2 .\" Copyright (c) 2009 James Gritton.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd June 23, 2009
  29 .Dt JAIL 2
  30 .Os
  31 .Sh NAME
  32 .Nm jail ,
  33 .Nm jail_get ,
  34 .Nm jail_set ,
  35 .Nm jail_remove ,
  36 .Nm jail_attach
  37 .Nd create and manage system jails
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/jail.h
  43 .Ft int
  44 .Fn jail "struct jail *jail"
  45 .Ft int
  46 .Fn jail_attach "int jid"
  47 .Ft int
  48 .Fn jail_remove "int jid"
  49 .In sys/uio.h
  50 .Ft int
  51 .Fn jail_get "struct iovec *iov" "u_int niov" "int flags"
  52 .Ft int
  53 .Fn jail_set "struct iovec *iov" "u_int niov" "int flags"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn jail
  57 system call sets up a jail and locks the current process in it.
  58 .Pp
  59 The argument is a pointer to a structure describing the prison:
  60 .Bd -literal -offset indent
  61 struct jail {
  62         u_int32_t       version;
  63         char            *path;
  64         char            *hostname;
  65         char            *jailname;
  66         unsigned int    ip4s;
  67         unsigned int    ip6s;
  68         struct in_addr  *ip4;
  69         struct in6_addr *ip6;
  70 };
  71 .Ed
  72 .Pp
  73 .Dq Li version
  74 defines the version of the API in use.
  75 .Dv JAIL_API_VERSION
  76 is defined for the current version.
  77 .Pp
  78 The
  79 .Dq Li path
  80 pointer should be set to the directory which is to be the root of the
  81 prison.
  82 .Pp
  83 The
  84 .Dq Li hostname
  85 pointer can be set to the hostname of the prison.
  86 This can be changed
  87 from the inside of the prison.
  88 .Pp
  89 The
  90 .Dq Li jailname
  91 pointer is an optional name that can be assigned to the jail
  92 for example for managment purposes.
  93 .Pp
  94 The
  95 .Dq Li ip4s
  96 and
  97 .Dq Li ip6s
  98 give the numbers of IPv4 and IPv6 addresses that will be passed
  99 via their respective pointers.
 100 .Pp
 101 The
 102 .Dq Li ip4
 103 and
 104 .Dq Li ip6
 105 pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
 106 the prison, or NULL if none.
 107 IPv4 addresses must be in network byte order.
 108 .Pp
 109 This is equivalent to the
 110 .Fn jail_set
 111 system call (see below), with the parameters
 112 .Va path ,
 113 .Va host.hostname ,
 114 .Va name ,
 115 .Va ip4.addr ,
 116 and
 117 .Va ip6.addr ,
 118 and with the
 119 .Dv JAIL_ATTACH
 120 flag.
 121 .Pp
 122 The
 123 .Fn jail_set
 124 system call creates a new jail, or modifies an existing one, and optionally
 125 locks the current process in it.
 126 Jail parameters are passed as an array of name-value pairs in the array
 127 .Fa iov ,
 128 containing
 129 .Fa niov
 130 elements.
 131 Parameter names are a null-terminated string, and values may be strings,
 132 integers, or other arbitrary data.
 133 Some parameters are boolean, and do not have a value (their length is zero)
 134 but are set by the name alone with or without a
 135 .Dq no
 136 prefix, e.g.
 137 .Va persist
 138 or
 139 .Va nopersist .
 140 Any parameters not set will be given default values, generally based on
 141 the current environment.
 142 .Pp
 143 Jails have a set of core parameters, and modules can add their own jail
 144 parameters.
 145 The current set of available parameters, and their formats, can be
 146 retrieved via the
 147 .Va security.jail.param
 148 sysctl MIB entry.
 149 Notable parameters include those mentioned in the
 150 .Fn jail
 151 description above, as well as
 152 .Va jid
 153 and
 154 .Va name ,
 155 which identify the jail being created or modified.
 156 See
 157 .Xr jail 8
 158 for more information on the core jail parameters.
 159 .Pp
 160 The
 161 .Fa flags
 162 arguments consists of one or more of the following flags:
 163 .Bl -tag -width indent
 164 .It Dv JAIL_CREATE
 165 Create a new jail.
 166 If a
 167 .Va jid
 168 or
 169 .Va name
 170 parameters exists, they must not refer to an existing jail.
 171 .It Dv JAIL_UPDATE
 172 Modify an existing jail.
 173 One of the
 174 .Va jid
 175 or
 176 .Va name
 177 parameters must exist, and must refer to an existing jail.
 178 If both
 179 .Dv JAIL_CREATE
 180 and
 181 .Dv JAIL_UPDATE
 182 are set, a jail will be created if it does not yet exist, and modified if it
 183 does exist.
 184 .It Dv JAIL_ATTACH
 185 In addition to creating or modifying the jail, attach the current process to
 186 it, as with the
 187 .Fn jail_attach
 188 system call.
 189 .It Dv JAIL_DYING
 190 Allow setting a jail that is in the process of being removed.
 191 .El
 192 .Pp
 193 The
 194 .Fn jail_get
 195 system call retrieves jail parameters, using the same name-value list as
 196 .Fn jail_set
 197 in the
 198 .Fa iov
 199 and
 200 .Fa niov
 201 arguments.
 202 The jail to read can be specified by either
 203 .Va jid
 204 or
 205 .Va name
 206 by including those parameters in the list.
 207 If they are included but are not intended to be the search key, they
 208 should be cleared (zero and the empty string respectively).
 209 .Pp
 210 The special parameter
 211 .Va lastjid
 212 can be used to retrieve a list of all jails.
 213 It will fetch the jail with the jid above and closest to the passed value.
 214 The first jail (usually but not always jid 1) can be found by passing a
 215 .Va lastjid
 216 of zero.
 217 .Pp
 218 The
 219 .Fa flags
 220 arguments consists of one or more following flags:
 221 .Bl -tag -width indent
 222 .It Dv JAIL_DYING
 223 Allow getting a jail that is in the process of being removed.
 224 .El
 225 .Pp
 226 The
 227 .Fn jail_attach
 228 system call attaches the current process to an existing jail,
 229 identified by
 230 .Fa jid .
 231 .Pp
 232 The
 233 .Fn jail_remove
 234 system call removes the jail identified by
 235 .Fa jid .
 236 It will kill all processes belonging to the jail, and remove any children
 237 of that jail.
 238 .Sh RETURN VALUES
 239 If successful,
 240 .Fn jail ,
 241 .Fn jail_set ,
 242 and
 243 .Fn jail_get
 244 return a non-negative integer, termed the jail identifier (JID).
 245 They return \-1 on failure, and set
 246 .Va errno
 247 to indicate the error.
 248 .Pp
 249 .Rv -std jail_attach jail_remove
 250 .Sh PRISON?
 251 Once a process has been put in a prison, it and its descendants cannot escape
 252 the prison.
 253 .Pp
 254 Inside the prison, the concept of
 255 .Dq superuser
 256 is very diluted.
 257 In general,
 258 it can be assumed that nothing can be mangled from inside a prison which
 259 does not exist entirely inside that prison.
 260 For instance the directory
 261 tree below
 262 .Dq Li path
 263 can be manipulated all the ways a root can normally do it, including
 264 .Dq Li "rm -rf /*"
 265 but new device special nodes cannot be created because they reference
 266 shared resources (the device drivers in the kernel).
 267 The effective
 268 .Dq securelevel
 269 for a process is the greater of the global
 270 .Dq securelevel
 271 or, if present, the per-jail
 272 .Dq securelevel .
 273 .Pp
 274 All IP activity will be forced to happen to/from the IP number specified,
 275 which should be an alias on one of the network interfaces.
 276 All connections to/from the loopback address
 277 .Pf ( Li 127.0.0.1
 278 for IPv4,
 279 .Li ::1
 280 for IPv6) will be changed to be to/from the primary address
 281 of the jail for the given address family.
 282 .Pp
 283 It is possible to identify a process as jailed by examining
 284 .Dq Li /proc/<pid>/status :
 285 it will show a field near the end of the line, either as
 286 a single hyphen for a process at large, or the name currently
 287 set for the prison for jailed processes.
 288 .Sh ERRORS
 289 The
 290 .Fn jail
 291 system call
 292 will fail if:
 293 .Bl -tag -width Er
 294 .It Bq Er EPERM
 295 This process is not allowed to create a jail, either because it is not
 296 the super-user, or because it would exceed the jail's
 297 .Va children.max
 298 limit.
 299 .It Bq Er EFAULT
 300 .Fa jail
 301 points to an address outside the allocated address space of the process.
 302 .It Bq Er EINVAL
 303 The version number of the argument is not correct.
 304 .It Bq Er EAGAIN
 305 No free JID could be found.
 306 .El
 307 .Pp
 308 The
 309 .Fn jail_set
 310 system call
 311 will fail if:
 312 .Bl -tag -width Er
 313 .It Bq Er EPERM
 314 This process is not allowed to create a jail, either because it is not
 315 the super-user, or because it would exceed the jail's
 316 .Va children.max
 317 limit.
 318 .It Bq Er EPERM
 319 A jail parameter was set to a less restrictive value then the current
 320 environment.
 321 .It Bq Er EFAULT
 322 .Fa Iov ,
 323 or one of the addresses contained within it,
 324 points to an address outside the allocated address space of the process.
 325 .It Bq Er ENOENT
 326 The jail referred to by a
 327 .Va jid
 328 or
 329 .Va name
 330 parameter does not exist, and the
 331 .Dv JAIL_CREATE
 332 flag is not set.
 333 .It Bq Er ENOENT
 334 The jail referred to by a
 335 .Va jid
 336 is not accessible by the process, because the process is in a different
 337 jail.
 338 .It Bq Er EEXIST
 339 The jail referred to by a
 340 .Va jid
 341 or
 342 .Va name
 343 parameter exists, and the
 344 .Dv JAIL_UPDATE
 345 flag is not set.
 346 .It Bq Er EINVAL
 347 A supplied parameter is the wrong size.
 348 .It Bq Er EINVAL
 349 A supplied parameter is out of range.
 350 .It Bq Er EINVAL
 351 A supplied string parameter is not null-terminated.
 352 .It Bq Er EINVAL
 353 A supplied parameter name does not match any known parameters.
 354 .It Bq Er EINVAL
 355 One of the
 356 .Dv JAIL_CREATE
 357 or
 358 .Dv JAIL_UPDATE
 359 flags is not set.
 360 .It Bq Er ENAMETOOLONG
 361 A supplied string parameter is longer than allowed.
 362 .It Bq Er EAGAIN
 363 There are no jail IDs left.
 364 .El
 365 .Pp
 366 The
 367 .Fn jail_get
 368 system call
 369 will fail if:
 370 .Bl -tag -width Er
 371 .It Bq Er EFAULT
 372 .Fa Iov ,
 373 or one of the addresses contained within it,
 374 points to an address outside the allocated address space of the process.
 375 .It Bq Er ENOENT
 376 The jail referred to by a
 377 .Va jid
 378 or
 379 .Va name
 380 parameter does not exist.
 381 .It Bq Er ENOENT
 382 The jail referred to by a
 383 .Va jid
 384 is not accessible by the process, because the process is in a different
 385 jail.
 386 .It Bq Er ENOENT
 387 The
 388 .Va lastjid
 389 parameter is greater than the highest current jail ID.
 390 .It Bq Er EINVAL
 391 A supplied parameter is the wrong size.
 392 .It Bq Er EINVAL
 393 A supplied parameter name does not match any known parameters.
 394 .El
 395 .Pp
 396 The
 397 .Fn jail_attach
 398 and
 399 .Fn jail_remove
 400 system calls
 401 will fail if:
 402 .Bl -tag -width Er
 403 .It Bq Er EINVAL
 404 The jail specified by
 405 .Fa jid
 406 does not exist.
 407 .El
 408 .Pp
 409 Further
 410 .Fn jail ,
 411 .Fn jail_set ,
 412 and
 413 .Fn jail_attach
 414 call
 415 .Xr chroot 2
 416 internally, so it can fail for all the same reasons.
 417 Please consult the
 418 .Xr chroot 2
 419 manual page for details.
 420 .Sh SEE ALSO
 421 .Xr chdir 2 ,
 422 .Xr chroot 2 ,
 423 .Xr jail 8
 424 .Sh HISTORY
 425 The
 426 .Fn jail
 427 system call appeared in
 428 .Fx 4.0 .
 429 The
 430 .Fn jail_attach
 431 system call appeared in
 432 .Fx 5.1 .
 433 The
 434 .Fn jail_set ,
 435 .Fn jail_get ,
 436 and
 437 .Fn jail_remove
 438 system calls appeared in
 439 .Fx 8.0 .
 440 .Sh AUTHORS
 441 The jail feature was written by
 442 .An Poul-Henning Kamp
 443 for R&D Associates
 444 .Dq Li http://www.rndassociates.com/
 445 who contributed it to
 446 .Fx .
 447 .An James Gritton
 448 added the extensible jail parameters and hierarchical jails.