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 September 15, 2025 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.Nm jail_remove_jd , 36.Nm jail_attach_jd 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.Ft int 50.Fn jail_attach_jd "int fd" 51.Ft int 52.Fn jail_remove_jd "int fd" 53.In sys/uio.h 54.Ft int 55.Fn jail_get "struct iovec *iov" "u_int niov" "int flags" 56.Ft int 57.Fn jail_set "struct iovec *iov" "u_int niov" "int flags" 58.Sh DESCRIPTION 59The 60.Fn jail 61system call sets up a jail and locks the current process in it. 62.Pp 63The argument is a pointer to a structure describing the prison: 64.Bd -literal -offset indent 65struct jail { 66 uint32_t version; 67 char *path; 68 char *hostname; 69 char *jailname; 70 unsigned int ip4s; 71 unsigned int ip6s; 72 struct in_addr *ip4; 73 struct in6_addr *ip6; 74}; 75.Ed 76.Pp 77.Dq Li version 78defines the version of the API in use. 79.Dv JAIL_API_VERSION 80is defined for the current version. 81.Pp 82The 83.Dq Li path 84pointer should be set to the directory which is to be the root of the 85prison. 86.Pp 87The 88.Dq Li hostname 89pointer can be set to the hostname of the prison. 90This can be changed 91from the inside of the prison. 92.Pp 93The 94.Dq Li jailname 95pointer is an optional name that can be assigned to the jail 96for example for management purposes. 97.Pp 98The 99.Dq Li ip4s 100and 101.Dq Li ip6s 102give the numbers of IPv4 and IPv6 addresses that will be passed 103via their respective pointers. 104.Pp 105The 106.Dq Li ip4 107and 108.Dq Li ip6 109pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to 110the prison, or NULL if none. 111IPv4 addresses must be in network byte order. 112.Pp 113This is equivalent to, and deprecated in favor of, the 114.Fn jail_set 115system call (see below), with the parameters 116.Va path , 117.Va host.hostname , 118.Va name , 119.Va ip4.addr , 120and 121.Va ip6.addr , 122and with the 123.Dv JAIL_ATTACH 124flag. 125.Pp 126The 127.Fn jail_set 128system call creates a new jail, or modifies an existing one, and optionally 129locks the current process in it. 130Jail parameters are passed as an array of name-value pairs in the array 131.Fa iov , 132containing 133.Fa niov 134elements. 135Parameter names are a null-terminated string, and values may be strings, 136integers, or other arbitrary data. 137Some parameters are boolean, and do not have a value (their length is zero) 138but are set by the name alone with or without a 139.Dq no 140prefix, e.g. 141.Va persist 142or 143.Va nopersist . 144Any parameters not set will be given default values, generally based on 145the current environment. 146.Pp 147Jails have a set of core parameters, and modules can add their own jail 148parameters. 149The current set of available parameters, and their formats, can be 150retrieved via the 151.Va security.jail.param 152sysctl MIB entry. 153Notable parameters include those mentioned in the 154.Fn jail 155description above, as well as 156.Va jid 157and 158.Va name , 159which identify the jail being created or modified. 160See 161.Xr jail 8 162for more information on the core jail parameters. 163.Pp 164The 165.Fa flags 166arguments consists of one or more of the following flags: 167.Bl -tag -width indent 168.It Dv JAIL_CREATE 169Create a new jail. 170If a 171.Va jid 172or 173.Va name 174parameters exists, they must not refer to an existing jail. 175.It Dv JAIL_UPDATE 176Modify an existing jail. 177One of the 178.Va jid 179or 180.Va name 181parameters must exist, and must refer to an existing jail. 182If both 183.Dv JAIL_CREATE 184and 185.Dv JAIL_UPDATE 186are set, a jail will be created if it does not yet exist, and modified if it 187does exist. 188.It Dv JAIL_ATTACH 189In addition to creating or modifying the jail, attach the current process to 190it, as with the 191.Fn jail_attach 192system call. 193.It Dv JAIL_DYING 194This is deprecated in 195.Fn jail_set 196and has no effect. 197.It Dv JAIL_USE_DESC 198Identify the jail by a descriptor in the 199.Va desc 200parameter. 201.It Dv JAIL_AT_DESC 202Operate in the context of the jail described by the 203.Va desc 204parameter, instead of the current jail. 205Only one of 206.Dv JAIL_USE_DESC 207or 208.Dv JAIL_AT_DESC 209may be specified. 210.It Dv JAIL_GET_DESC 211Return a new jail descriptor for the jail in the 212.Va desc 213parameter. 214.It Dv JAIL_OWN_DESC 215Return an 216.Dq owning 217jail descriptor in the 218.Va desc 219parameter. 220.El 221.Pp 222The 223.Fn jail_get 224system call retrieves jail parameters, using the same name-value list as 225.Fn jail_set 226in the 227.Fa iov 228and 229.Fa niov 230arguments. 231The jail to read can be specified by either 232.Va jid 233or 234.Va name 235by including those parameters in the list. 236If they are included but are not intended to be the search key, they 237should be cleared (zero and the empty string respectively). 238.Pp 239The special parameter 240.Va lastjid 241can be used to retrieve a list of all jails. 242It will fetch the jail with the jid above and closest to the passed value. 243The first jail (usually but not always jid 1) can be found by passing a 244.Va lastjid 245of zero. 246.Pp 247The 248.Fa flags 249arguments consists of one or more following flags: 250.Bl -tag -width indent 251.It Dv JAIL_DYING 252Allow getting a jail that is in the process of being removed. 253.It Dv JAIL_USE_DESC , Dv JAIL_AT_DESC , Dv JAIL_GET_DESC , Dv JAIL_OWN_DESC 254These have the same meaning as they do in 255.Fn jail_set . 256.El 257.Pp 258The 259.Fn jail_attach 260system call attaches the current process to an existing jail, 261identified by 262.Fa jid . 263It changes the process's root and current directories to the jail's 264.Va path 265directory. 266.Pp 267The 268.Fn jail_remove 269system call removes the jail identified by 270.Fa jid . 271It will kill all processes belonging to the jail, and remove any children 272of that jail. 273.Pp 274The 275.Fn jail_attach_fd 276and 277.Fn jail_remove_fd 278system calls work the same as 279.Fn jail_attach 280and 281.Fn jail_remove , 282except that they operate on the jail identified by jail descriptor 283.Fa fd . 284.Ss Jail Descriptors 285In addition to the jail ID, 286jails can be referred to using a jail descriptor, 287a type of file descriptor tied to a particular jail. 288Jail descriptors are created by calling 289.Fn jail_set 290or 291.Fn jail_get 292with the special parameter 293.Va desc , 294and either the 295.Dv JAIL_GET_DESC 296or 297.Dv JAIL_OWN_DESC 298flags set. 299The difference between the two flags is that descriptors created with 300.Dv JAIL_OWN_DESC 301.Po 302called 303.Dq owning 304descriptors 305.Pc 306will automatically remove the jail when the descriptor is closed. 307.Pp 308Jail descriptors can be passed back to 309.Fn jail_set 310or 311.Fm jail_get 312with the 313.Va desc 314parameter, 315and either the 316.Dv JAIL_USE_DESC 317or 318.Dv JAIL_AT_DESC 319flags set. 320With 321.Dv JAIL_USE_DESC , 322the descriptor identifies the jail to operate on, 323instead of the 324.Va jid 325or 326.Va name 327parameter. 328With 329.Dv JAIL_AT_DESC , 330the descriptor is used in place of the current jail, 331allowing accessing or creating jails that are children of the 332descriptor jail. 333.Pp 334The system calls 335.Fn jail_attach_jd 336and 337.Fn jail_aremove_jd 338work the same as 339.Fn jail_attach 340and 341.Fn jail_remove , 342except that they operate on the jail referred to by the passed descriptor. 343.Sh RETURN VALUES 344If successful, 345.Fn jail , 346.Fn jail_set , 347and 348.Fn jail_get 349return a non-negative integer, termed the jail identifier (JID). 350They return \-1 on failure, and set 351.Va errno 352to indicate the error. 353.Pp 354.Rv -std jail_attach jail_remove jail_attach_jd jail_remove_jd 355.Sh ERRORS 356The 357.Fn jail 358system call 359will fail if: 360.Bl -tag -width Er 361.It Bq Er EPERM 362This process is not allowed to create a jail, either because it is not 363the super-user, or because it would exceed the jail's 364.Va children.max 365limit. 366.It Bq Er EFAULT 367.Fa jail 368points to an address outside the allocated address space of the process. 369.It Bq Er EINVAL 370The version number of the argument is not correct. 371.It Bq Er EAGAIN 372No free JID could be found. 373.El 374.Pp 375The 376.Fn jail_set 377system call 378will fail if: 379.Bl -tag -width Er 380.It Bq Er EPERM 381This process is not allowed to create a jail, either because it is not 382the super-user, or because it would exceed the jail's 383.Va children.max 384limit. 385.It Bq Er EPERM 386The jail descriptor in the 387.Va desc 388parameter was created by a user other than the super-user, 389and the 390.Dv JAIL_USE_DESC 391flag was set. 392.It Bq Er EPERM 393A jail parameter was set to a less restrictive value then the current 394environment. 395.It Bq Er EFAULT 396.Fa Iov , 397or one of the addresses contained within it, 398points to an address outside the allocated address space of the process. 399.It Bq Er ENOENT 400The jail referred to by a 401.Va jid 402or 403.Va name 404parameter does not exist, and the 405.Dv JAIL_CREATE 406flag is not set. 407.It Bq Er ENOENT 408The jail referred to by a 409.Va jid 410parameter is not accessible by the process, because the process is in a 411different jail. 412.It Bq Er ENOENT 413The jail referred to by a 414.Va desc 415parameter has been removed. 416.It Bq Er EEXIST 417The jail referred to by a 418.Va jid 419or 420.Va name 421parameter exists, and the 422.Dv JAIL_UPDATE 423flag is not set. 424.It Bq Er EINVAL 425A supplied parameter is the wrong size. 426.It Bq Er EINVAL 427A supplied parameter is out of range. 428.It Bq Er EINVAL 429A supplied string parameter is not null-terminated. 430.It Bq Er EINVAL 431A supplied parameter name does not match any known parameters. 432.It Bq Er EINVAL 433One of the 434.Dv JAIL_CREATE 435or 436.Dv JAIL_UPDATE 437flags is not set. 438.It Bq Er ENAMETOOLONG 439A supplied string parameter is longer than allowed. 440.It Bq Er EAGAIN 441There are no jail IDs left. 442.It Bq Er EMFILE 443A jail descriptor could not be created for the 444.Va desc 445parameter with either the 446.Dv JAIL_GET_DESC 447or 448.Dv JAIL_OWN_DESC 449flag set, 450because the process has already reached its limit for open file descriptors. 451.It Bq Er ENFILE 452A jail descriptor could not be created for the 453.Va desc 454parameter with either the 455.Dv JAIL_GET_DESC 456or 457.Dv JAIL_OWN_DESC 458flag set, 459because the system file table is full. 460.El 461.Pp 462The 463.Fn jail_get 464system call 465will fail if: 466.Bl -tag -width Er 467.It Bq Er ENOENT 468The jail referred to by a 469.Va jid 470or 471.Va name 472parameter does not exist. 473.It Bq Er ENOENT 474The jail referred to by a 475.Va jid 476is not accessible by the process, because the process is in a different 477jail. 478.It Bq Er ENOENT 479The 480.Va lastjid 481parameter is greater than the highest current jail ID. 482.It Bq Er ENOENT 483The jail referred to by a 484.Va desc 485parameter has been removed 486.Pq even if the Dv JAIL_CREATE flag has been set . 487.It Bq Er EINVAL 488A supplied parameter is the wrong size. 489.It Bq Er EINVAL 490A supplied parameter is out of range. 491.It Bq Er EINVAL 492A supplied string parameter is not null-terminated. 493.It Bq Er EINVAL 494A supplied parameter name does not match any known parameters. 495.It Bq Er EMFILE 496A jail descriptor could not be created for the 497.Va desc 498parameter with either the 499.Dv JAIL_GET_DESC 500or 501.Dv JAIL_OWN_DESC 502flag set, 503because the process has already reached its limit for open file descriptors. 504.It Bq Er ENFILE 505A jail descriptor could not be created for the 506.Va desc 507parameter with either the 508.Dv JAIL_GET_DESC 509or 510.Dv JAIL_OWN_DESC 511flag set, 512because the system file table is full. 513.El 514.Pp 515The 516.Fn jail_attach 517and 518.Fn jail_remove 519system calls 520will fail if: 521.Bl -tag -width Er 522.It Bq Er EPERM 523A user other than the super-user attempted to attach to or remove a jail. 524.It Bq Er EINVAL 525The jail specified by 526.Fa jid 527does not exist. 528.El 529.Pp 530The 531.Fn jail_attach_jd 532and 533.Fn jail_remove_jd 534system calls 535will fail if: 536.Bl -tag -width Er 537.It Bq Er EINVAL 538The 539.Fa fd 540argument is not a valid jail descriptor. 541.It Bq Er EPERM 542The jail descriptor was created by a user other than the super-user. 543.It Bq Er EINVAL 544The jail specified by 545.Fa jid 546has been removed. 547.El 548.Pp 549Further 550.Fn jail , 551.Fn jail_set , 552.Fn jail_attach , 553and 554.Fn jail_attach_jd 555call 556.Xr chroot 2 557internally, so they can fail for all the same reasons. 558In particular, they return the 559.Bq Er EPERM 560error when the process to join a jail has open directories. 561Please consult the 562.Xr chroot 2 563manual page for details. 564.Sh SEE ALSO 565.Xr chdir 2 , 566.Xr chroot 2 , 567.Xr jail 8 568.Sh HISTORY 569The 570.Fn jail 571system call appeared in 572.Fx 4.0 . 573The 574.Fn jail_attach 575system call appeared in 576.Fx 5.1 . 577The 578.Fn jail_set , 579.Fn jail_get , 580and 581.Fn jail_remove 582system calls appeared in 583.Fx 8.0 . 584.Sh AUTHORS 585The jail feature was written by 586.An Poul-Henning Kamp 587for R&D Associates 588who contributed it to 589.Fx . 590.An James Gritton 591added the extensible jail parameters and hierarchical jails. 592