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