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