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 February 8, 2012
  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         uint32_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 management 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 ERRORS
 251 The
 252 .Fn jail
 253 system call
 254 will fail if:
 255 .Bl -tag -width Er
 256 .It Bq Er EPERM
 257 This process is not allowed to create a jail, either because it is not
 258 the super-user, or because it would exceed the jail's
 259 .Va children.max
 260 limit.
 261 .It Bq Er EFAULT
 262 .Fa jail
 263 points to an address outside the allocated address space of the process.
 264 .It Bq Er EINVAL
 265 The version number of the argument is not correct.
 266 .It Bq Er EAGAIN
 267 No free JID could be found.
 268 .El
 269 .Pp
 270 The
 271 .Fn jail_set
 272 system call
 273 will fail if:
 274 .Bl -tag -width Er
 275 .It Bq Er EPERM
 276 This process is not allowed to create a jail, either because it is not
 277 the super-user, or because it would exceed the jail's
 278 .Va children.max
 279 limit.
 280 .It Bq Er EPERM
 281 A jail parameter was set to a less restrictive value then the current
 282 environment.
 283 .It Bq Er EFAULT
 284 .Fa Iov ,
 285 or one of the addresses contained within it,
 286 points to an address outside the allocated address space of the process.
 287 .It Bq Er ENOENT
 288 The jail referred to by a
 289 .Va jid
 290 or
 291 .Va name
 292 parameter does not exist, and the
 293 .Dv JAIL_CREATE
 294 flag is not set.
 295 .It Bq Er ENOENT
 296 The jail referred to by a
 297 .Va jid
 298 is not accessible by the process, because the process is in a different
 299 jail.
 300 .It Bq Er EEXIST
 301 The jail referred to by a
 302 .Va jid
 303 or
 304 .Va name
 305 parameter exists, and the
 306 .Dv JAIL_UPDATE
 307 flag is not set.
 308 .It Bq Er EINVAL
 309 A supplied parameter is the wrong size.
 310 .It Bq Er EINVAL
 311 A supplied parameter is out of range.
 312 .It Bq Er EINVAL
 313 A supplied string parameter is not null-terminated.
 314 .It Bq Er EINVAL
 315 A supplied parameter name does not match any known parameters.
 316 .It Bq Er EINVAL
 317 One of the
 318 .Dv JAIL_CREATE
 319 or
 320 .Dv JAIL_UPDATE
 321 flags is not set.
 322 .It Bq Er ENAMETOOLONG
 323 A supplied string parameter is longer than allowed.
 324 .It Bq Er EAGAIN
 325 There are no jail IDs left.
 326 .El
 327 .Pp
 328 The
 329 .Fn jail_get
 330 system call
 331 will fail if:
 332 .Bl -tag -width Er
 333 .It Bq Er EFAULT
 334 .Fa Iov ,
 335 or one of the addresses contained within it,
 336 points to an address outside the allocated address space of the process.
 337 .It Bq Er ENOENT
 338 The jail referred to by a
 339 .Va jid
 340 or
 341 .Va name
 342 parameter does not exist.
 343 .It Bq Er ENOENT
 344 The jail referred to by a
 345 .Va jid
 346 is not accessible by the process, because the process is in a different
 347 jail.
 348 .It Bq Er ENOENT
 349 The
 350 .Va lastjid
 351 parameter is greater than the highest current jail ID.
 352 .It Bq Er EINVAL
 353 A supplied parameter is the wrong size.
 354 .It Bq Er EINVAL
 355 A supplied parameter name does not match any known parameters.
 356 .El
 357 .Pp
 358 The
 359 .Fn jail_attach
 360 and
 361 .Fn jail_remove
 362 system calls
 363 will fail if:
 364 .Bl -tag -width Er
 365 .It Bq Er EPERM
 366 A user other than the super-user attempted to attach to or remove a jail.
 367 .It Bq Er EINVAL
 368 The jail specified by
 369 .Fa jid
 370 does not exist.
 371 .El
 372 .Pp
 373 Further
 374 .Fn jail ,
 375 .Fn jail_set ,
 376 and
 377 .Fn jail_attach
 378 call
 379 .Xr chroot 2
 380 internally, so they can fail for all the same reasons.
 381 Please consult the
 382 .Xr chroot 2
 383 manual page for details.
 384 .Sh SEE ALSO
 385 .Xr chdir 2 ,
 386 .Xr chroot 2 ,
 387 .Xr jail 8
 388 .Sh HISTORY
 389 The
 390 .Fn jail
 391 system call appeared in
 392 .Fx 4.0 .
 393 The
 394 .Fn jail_attach
 395 system call appeared in
 396 .Fx 5.1 .
 397 The
 398 .Fn jail_set ,
 399 .Fn jail_get ,
 400 and
 401 .Fn jail_remove
 402 system calls appeared in
 403 .Fx 8.0 .
 404 .Sh AUTHORS
 405 The jail feature was written by
 406 .An Poul-Henning Kamp
 407 for R&D Associates
 408 .Dq Li http://www.rndassociates.com/
 409 who contributed it to
 410 .Fx .
 411 .An James Gritton
 412 added the extensible jail parameters and hierarchical jails.