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 .Dd November 29, 2023
  27 .Dt JAIL 2
  28 .Os
  29 .Sh NAME
  30 .Nm jail ,
  31 .Nm jail_get ,
  32 .Nm jail_set ,
  33 .Nm jail_remove ,
  34 .Nm jail_attach
  35 .Nd create and manage system jails
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/jail.h
  41 .Ft int
  42 .Fn jail "struct jail *jail"
  43 .Ft int
  44 .Fn jail_attach "int jid"
  45 .Ft int
  46 .Fn jail_remove "int jid"
  47 .In sys/uio.h
  48 .Ft int
  49 .Fn jail_get "struct iovec *iov" "u_int niov" "int flags"
  50 .Ft int
  51 .Fn jail_set "struct iovec *iov" "u_int niov" "int flags"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn jail
  55 system call sets up a jail and locks the current process in it.
  56 .Pp
  57 The argument is a pointer to a structure describing the prison:
  58 .Bd -literal -offset indent
  59 struct jail {
  60         uint32_t        version;
  61         char            *path;
  62         char            *hostname;
  63         char            *jailname;
  64         unsigned int    ip4s;
  65         unsigned int    ip6s;
  66         struct in_addr  *ip4;
  67         struct in6_addr *ip6;
  68 };
  69 .Ed
  70 .Pp
  71 .Dq Li version
  72 defines the version of the API in use.
  73 .Dv JAIL_API_VERSION
  74 is defined for the current version.
  75 .Pp
  76 The
  77 .Dq Li path
  78 pointer should be set to the directory which is to be the root of the
  79 prison.
  80 .Pp
  81 The
  82 .Dq Li hostname
  83 pointer can be set to the hostname of the prison.
  84 This can be changed
  85 from the inside of the prison.
  86 .Pp
  87 The
  88 .Dq Li jailname
  89 pointer is an optional name that can be assigned to the jail
  90 for example for management purposes.
  91 .Pp
  92 The
  93 .Dq Li ip4s
  94 and
  95 .Dq Li ip6s
  96 give the numbers of IPv4 and IPv6 addresses that will be passed
  97 via their respective pointers.
  98 .Pp
  99 The
 100 .Dq Li ip4
 101 and
 102 .Dq Li ip6
 103 pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
 104 the prison, or NULL if none.
 105 IPv4 addresses must be in network byte order.
 106 .Pp
 107 This is equivalent to, and deprecated in favor of, the
 108 .Fn jail_set
 109 system call (see below), with the parameters
 110 .Va path ,
 111 .Va host.hostname ,
 112 .Va name ,
 113 .Va ip4.addr ,
 114 and
 115 .Va ip6.addr ,
 116 and with the
 117 .Dv JAIL_ATTACH
 118 flag.
 119 .Pp
 120 The
 121 .Fn jail_set
 122 system call creates a new jail, or modifies an existing one, and optionally
 123 locks the current process in it.
 124 Jail parameters are passed as an array of name-value pairs in the array
 125 .Fa iov ,
 126 containing
 127 .Fa niov
 128 elements.
 129 Parameter names are a null-terminated string, and values may be strings,
 130 integers, or other arbitrary data.
 131 Some parameters are boolean, and do not have a value (their length is zero)
 132 but are set by the name alone with or without a
 133 .Dq no
 134 prefix, e.g.
 135 .Va persist
 136 or
 137 .Va nopersist .
 138 Any parameters not set will be given default values, generally based on
 139 the current environment.
 140 .Pp
 141 Jails have a set of core parameters, and modules can add their own jail
 142 parameters.
 143 The current set of available parameters, and their formats, can be
 144 retrieved via the
 145 .Va security.jail.param
 146 sysctl MIB entry.
 147 Notable parameters include those mentioned in the
 148 .Fn jail
 149 description above, as well as
 150 .Va jid
 151 and
 152 .Va name ,
 153 which identify the jail being created or modified.
 154 See
 155 .Xr jail 8
 156 for more information on the core jail parameters.
 157 .Pp
 158 The
 159 .Fa flags
 160 arguments consists of one or more of the following flags:
 161 .Bl -tag -width indent
 162 .It Dv JAIL_CREATE
 163 Create a new jail.
 164 If a
 165 .Va jid
 166 or
 167 .Va name
 168 parameters exists, they must not refer to an existing jail.
 169 .It Dv JAIL_UPDATE
 170 Modify an existing jail.
 171 One of the
 172 .Va jid
 173 or
 174 .Va name
 175 parameters must exist, and must refer to an existing jail.
 176 If both
 177 .Dv JAIL_CREATE
 178 and
 179 .Dv JAIL_UPDATE
 180 are set, a jail will be created if it does not yet exist, and modified if it
 181 does exist.
 182 .It Dv JAIL_ATTACH
 183 In addition to creating or modifying the jail, attach the current process to
 184 it, as with the
 185 .Fn jail_attach
 186 system call.
 187 .It Dv JAIL_DYING
 188 This is deprecated in
 189 .Fn jail_set
 190 and has no effect.
 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 It changes the process's root and current directories to the jail's
 232 .Va path
 233 directory.
 234 .Pp
 235 The
 236 .Fn jail_remove
 237 system call removes the jail identified by
 238 .Fa jid .
 239 It will kill all processes belonging to the jail, and remove any children
 240 of that jail.
 241 .Sh RETURN VALUES
 242 If successful,
 243 .Fn jail ,
 244 .Fn jail_set ,
 245 and
 246 .Fn jail_get
 247 return a non-negative integer, termed the jail identifier (JID).
 248 They return \-1 on failure, and set
 249 .Va errno
 250 to indicate the error.
 251 .Pp
 252 .Rv -std jail_attach jail_remove
 253 .Sh ERRORS
 254 The
 255 .Fn jail
 256 system call
 257 will fail if:
 258 .Bl -tag -width Er
 259 .It Bq Er EPERM
 260 This process is not allowed to create a jail, either because it is not
 261 the super-user, or because it would exceed the jail's
 262 .Va children.max
 263 limit.
 264 .It Bq Er EFAULT
 265 .Fa jail
 266 points to an address outside the allocated address space of the process.
 267 .It Bq Er EINVAL
 268 The version number of the argument is not correct.
 269 .It Bq Er EAGAIN
 270 No free JID could be found.
 271 .El
 272 .Pp
 273 The
 274 .Fn jail_set
 275 system call
 276 will fail if:
 277 .Bl -tag -width Er
 278 .It Bq Er EPERM
 279 This process is not allowed to create a jail, either because it is not
 280 the super-user, or because it would exceed the jail's
 281 .Va children.max
 282 limit.
 283 .It Bq Er EPERM
 284 A jail parameter was set to a less restrictive value then the current
 285 environment.
 286 .It Bq Er EFAULT
 287 .Fa Iov ,
 288 or one of the addresses contained within it,
 289 points to an address outside the allocated address space of the process.
 290 .It Bq Er ENOENT
 291 The jail referred to by a
 292 .Va jid
 293 or
 294 .Va name
 295 parameter does not exist, and the
 296 .Dv JAIL_CREATE
 297 flag is not set.
 298 .It Bq Er ENOENT
 299 The jail referred to by a
 300 .Va jid
 301 is not accessible by the process, because the process is in a different
 302 jail.
 303 .It Bq Er EEXIST
 304 The jail referred to by a
 305 .Va jid
 306 or
 307 .Va name
 308 parameter exists, and the
 309 .Dv JAIL_UPDATE
 310 flag is not set.
 311 .It Bq Er EINVAL
 312 A supplied parameter is the wrong size.
 313 .It Bq Er EINVAL
 314 A supplied parameter is out of range.
 315 .It Bq Er EINVAL
 316 A supplied string parameter is not null-terminated.
 317 .It Bq Er EINVAL
 318 A supplied parameter name does not match any known parameters.
 319 .It Bq Er EINVAL
 320 One of the
 321 .Dv JAIL_CREATE
 322 or
 323 .Dv JAIL_UPDATE
 324 flags is not set.
 325 .It Bq Er ENAMETOOLONG
 326 A supplied string parameter is longer than allowed.
 327 .It Bq Er EAGAIN
 328 There are no jail IDs left.
 329 .El
 330 .Pp
 331 The
 332 .Fn jail_get
 333 system call
 334 will fail if:
 335 .Bl -tag -width Er
 336 .It Bq Er EFAULT
 337 .Fa Iov ,
 338 or one of the addresses contained within it,
 339 points to an address outside the allocated address space of the process.
 340 .It Bq Er ENOENT
 341 The jail referred to by a
 342 .Va jid
 343 or
 344 .Va name
 345 parameter does not exist.
 346 .It Bq Er ENOENT
 347 The jail referred to by a
 348 .Va jid
 349 is not accessible by the process, because the process is in a different
 350 jail.
 351 .It Bq Er ENOENT
 352 The
 353 .Va lastjid
 354 parameter is greater than the highest current jail ID.
 355 .It Bq Er EINVAL
 356 A supplied parameter is the wrong size.
 357 .It Bq Er EINVAL
 358 A supplied parameter name does not match any known parameters.
 359 .El
 360 .Pp
 361 The
 362 .Fn jail_attach
 363 and
 364 .Fn jail_remove
 365 system calls
 366 will fail if:
 367 .Bl -tag -width Er
 368 .It Bq Er EPERM
 369 A user other than the super-user attempted to attach to or remove a jail.
 370 .It Bq Er EINVAL
 371 The jail specified by
 372 .Fa jid
 373 does not exist.
 374 .El
 375 .Pp
 376 Further
 377 .Fn jail ,
 378 .Fn jail_set ,
 379 and
 380 .Fn jail_attach
 381 call
 382 .Xr chroot 2
 383 internally, so they can fail for all the same reasons.
 384 Please consult the
 385 .Xr chroot 2
 386 manual page for details.
 387 .Sh SEE ALSO
 388 .Xr chdir 2 ,
 389 .Xr chroot 2 ,
 390 .Xr jail 8
 391 .Sh HISTORY
 392 The
 393 .Fn jail
 394 system call appeared in
 395 .Fx 4.0 .
 396 The
 397 .Fn jail_attach
 398 system call appeared in
 399 .Fx 5.1 .
 400 The
 401 .Fn jail_set ,
 402 .Fn jail_get ,
 403 and
 404 .Fn jail_remove
 405 system calls appeared in
 406 .Fx 8.0 .
 407 .Sh AUTHORS
 408 The jail feature was written by
 409 .An Poul-Henning Kamp
 410 for R&D Associates
 411 who contributed it to
 412 .Fx .
 413 .An James Gritton
 414 added the extensible jail parameters and hierarchical jails.