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 19, 2021 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 55The 56.Fn jail 57system call sets up a jail and locks the current process in it. 58.Pp 59The argument is a pointer to a structure describing the prison: 60.Bd -literal -offset indent 61struct 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 74defines the version of the API in use. 75.Dv JAIL_API_VERSION 76is defined for the current version. 77.Pp 78The 79.Dq Li path 80pointer should be set to the directory which is to be the root of the 81prison. 82.Pp 83The 84.Dq Li hostname 85pointer can be set to the hostname of the prison. 86This can be changed 87from the inside of the prison. 88.Pp 89The 90.Dq Li jailname 91pointer is an optional name that can be assigned to the jail 92for example for management purposes. 93.Pp 94The 95.Dq Li ip4s 96and 97.Dq Li ip6s 98give the numbers of IPv4 and IPv6 addresses that will be passed 99via their respective pointers. 100.Pp 101The 102.Dq Li ip4 103and 104.Dq Li ip6 105pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to 106the prison, or NULL if none. 107IPv4 addresses must be in network byte order. 108.Pp 109This is equivalent to, and deprecated in favor of, the 110.Fn jail_set 111system call (see below), with the parameters 112.Va path , 113.Va host.hostname , 114.Va name , 115.Va ip4.addr , 116and 117.Va ip6.addr , 118and with the 119.Dv JAIL_ATTACH 120flag. 121.Pp 122The 123.Fn jail_set 124system call creates a new jail, or modifies an existing one, and optionally 125locks the current process in it. 126Jail parameters are passed as an array of name-value pairs in the array 127.Fa iov , 128containing 129.Fa niov 130elements. 131Parameter names are a null-terminated string, and values may be strings, 132integers, or other arbitrary data. 133Some parameters are boolean, and do not have a value (their length is zero) 134but are set by the name alone with or without a 135.Dq no 136prefix, e.g. 137.Va persist 138or 139.Va nopersist . 140Any parameters not set will be given default values, generally based on 141the current environment. 142.Pp 143Jails have a set of core parameters, and modules can add their own jail 144parameters. 145The current set of available parameters, and their formats, can be 146retrieved via the 147.Va security.jail.param 148sysctl MIB entry. 149Notable parameters include those mentioned in the 150.Fn jail 151description above, as well as 152.Va jid 153and 154.Va name , 155which identify the jail being created or modified. 156See 157.Xr jail 8 158for more information on the core jail parameters. 159.Pp 160The 161.Fa flags 162arguments consists of one or more of the following flags: 163.Bl -tag -width indent 164.It Dv JAIL_CREATE 165Create a new jail. 166If a 167.Va jid 168or 169.Va name 170parameters exists, they must not refer to an existing jail. 171.It Dv JAIL_UPDATE 172Modify an existing jail. 173One of the 174.Va jid 175or 176.Va name 177parameters must exist, and must refer to an existing jail. 178If both 179.Dv JAIL_CREATE 180and 181.Dv JAIL_UPDATE 182are set, a jail will be created if it does not yet exist, and modified if it 183does exist. 184.It Dv JAIL_ATTACH 185In addition to creating or modifying the jail, attach the current process to 186it, as with the 187.Fn jail_attach 188system call. 189.It Dv JAIL_DYING 190Allow setting a jail that is in the process of being removed. 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