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 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 188This is deprecated in 189.Fn jail_set 190and has no effect. 191.El 192.Pp 193The 194.Fn jail_get 195system call retrieves jail parameters, using the same name-value list as 196.Fn jail_set 197in the 198.Fa iov 199and 200.Fa niov 201arguments. 202The jail to read can be specified by either 203.Va jid 204or 205.Va name 206by including those parameters in the list. 207If they are included but are not intended to be the search key, they 208should be cleared (zero and the empty string respectively). 209.Pp 210The special parameter 211.Va lastjid 212can be used to retrieve a list of all jails. 213It will fetch the jail with the jid above and closest to the passed value. 214The first jail (usually but not always jid 1) can be found by passing a 215.Va lastjid 216of zero. 217.Pp 218The 219.Fa flags 220arguments consists of one or more following flags: 221.Bl -tag -width indent 222.It Dv JAIL_DYING 223Allow getting a jail that is in the process of being removed. 224.El 225.Pp 226The 227.Fn jail_attach 228system call attaches the current process to an existing jail, 229identified by 230.Fa jid . 231It changes the process's root and current directories to the jail's 232.Va path 233directory. 234.Pp 235The 236.Fn jail_remove 237system call removes the jail identified by 238.Fa jid . 239It will kill all processes belonging to the jail, and remove any children 240of that jail. 241.Sh RETURN VALUES 242If successful, 243.Fn jail , 244.Fn jail_set , 245and 246.Fn jail_get 247return a non-negative integer, termed the jail identifier (JID). 248They return \-1 on failure, and set 249.Va errno 250to indicate the error. 251.Pp 252.Rv -std jail_attach jail_remove 253.Sh ERRORS 254The 255.Fn jail 256system call 257will fail if: 258.Bl -tag -width Er 259.It Bq Er EPERM 260This process is not allowed to create a jail, either because it is not 261the super-user, or because it would exceed the jail's 262.Va children.max 263limit. 264.It Bq Er EFAULT 265.Fa jail 266points to an address outside the allocated address space of the process. 267.It Bq Er EINVAL 268The version number of the argument is not correct. 269.It Bq Er EAGAIN 270No free JID could be found. 271.El 272.Pp 273The 274.Fn jail_set 275system call 276will fail if: 277.Bl -tag -width Er 278.It Bq Er EPERM 279This process is not allowed to create a jail, either because it is not 280the super-user, or because it would exceed the jail's 281.Va children.max 282limit. 283.It Bq Er EPERM 284A jail parameter was set to a less restrictive value then the current 285environment. 286.It Bq Er EFAULT 287.Fa Iov , 288or one of the addresses contained within it, 289points to an address outside the allocated address space of the process. 290.It Bq Er ENOENT 291The jail referred to by a 292.Va jid 293or 294.Va name 295parameter does not exist, and the 296.Dv JAIL_CREATE 297flag is not set. 298.It Bq Er ENOENT 299The jail referred to by a 300.Va jid 301is not accessible by the process, because the process is in a different 302jail. 303.It Bq Er EEXIST 304The jail referred to by a 305.Va jid 306or 307.Va name 308parameter exists, and the 309.Dv JAIL_UPDATE 310flag is not set. 311.It Bq Er EINVAL 312A supplied parameter is the wrong size. 313.It Bq Er EINVAL 314A supplied parameter is out of range. 315.It Bq Er EINVAL 316A supplied string parameter is not null-terminated. 317.It Bq Er EINVAL 318A supplied parameter name does not match any known parameters. 319.It Bq Er EINVAL 320One of the 321.Dv JAIL_CREATE 322or 323.Dv JAIL_UPDATE 324flags is not set. 325.It Bq Er ENAMETOOLONG 326A supplied string parameter is longer than allowed. 327.It Bq Er EAGAIN 328There are no jail IDs left. 329.El 330.Pp 331The 332.Fn jail_get 333system call 334will fail if: 335.Bl -tag -width Er 336.It Bq Er EFAULT 337.Fa Iov , 338or one of the addresses contained within it, 339points to an address outside the allocated address space of the process. 340.It Bq Er ENOENT 341The jail referred to by a 342.Va jid 343or 344.Va name 345parameter does not exist. 346.It Bq Er ENOENT 347The jail referred to by a 348.Va jid 349is not accessible by the process, because the process is in a different 350jail. 351.It Bq Er ENOENT 352The 353.Va lastjid 354parameter is greater than the highest current jail ID. 355.It Bq Er EINVAL 356A supplied parameter is the wrong size. 357.It Bq Er EINVAL 358A supplied parameter name does not match any known parameters. 359.El 360.Pp 361The 362.Fn jail_attach 363and 364.Fn jail_remove 365system calls 366will fail if: 367.Bl -tag -width Er 368.It Bq Er EPERM 369A user other than the super-user attempted to attach to or remove a jail. 370.It Bq Er EINVAL 371The jail specified by 372.Fa jid 373does not exist. 374.El 375.Pp 376Further 377.Fn jail , 378.Fn jail_set , 379and 380.Fn jail_attach 381call 382.Xr chroot 2 383internally, so they can fail for all the same reasons. 384Please consult the 385.Xr chroot 2 386manual page for details. 387.Sh SEE ALSO 388.Xr chdir 2 , 389.Xr chroot 2 , 390.Xr jail 8 391.Sh HISTORY 392The 393.Fn jail 394system call appeared in 395.Fx 4.0 . 396The 397.Fn jail_attach 398system call appeared in 399.Fx 5.1 . 400The 401.Fn jail_set , 402.Fn jail_get , 403and 404.Fn jail_remove 405system calls appeared in 406.Fx 8.0 . 407.Sh AUTHORS 408The jail feature was written by 409.An Poul-Henning Kamp 410for R&D Associates 411who contributed it to 412.Fx . 413.An James Gritton 414added the extensible jail parameters and hierarchical jails. 415