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 9, 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.Pp 344Jail operations via descriptors can be done by processes that do not 345normally have permission to see or affect the jail, 346as long as they are allowed by the file permissions of the jail 347descriptor itself. 348These permissions can be changed by the descriptor owner via 349.Xr fchmod 2 350and 351.Xr fchown 2 . 352.Fn jail_get 353requires read permission, 354.Fn jail_set 355and 356.Fn jail_remove 357require write permission, 358and 359.Fn jail_attach 360requires execute permission. 361Also, use of a descriptor with the 362.Dv JAIL_AT_DESC 363flag requires execute permission. 364An owning descriptor is identified by the 365.Em sticky bit , 366which may also be changed via 367.Xr fchmod 2 . 368.Sh RETURN VALUES 369If successful, 370.Fn jail , 371.Fn jail_set , 372and 373.Fn jail_get 374return a non-negative integer, termed the jail identifier (JID). 375They return \-1 on failure, and set 376.Va errno 377to indicate the error. 378.Pp 379.Rv -std jail_attach jail_remove jail_attach_jd jail_remove_jd 380.Sh ERRORS 381The 382.Fn jail 383system call 384will fail if: 385.Bl -tag -width Er 386.It Bq Er EPERM 387This process is not allowed to create a jail, either because it is not 388the super-user, or because it would exceed the jail's 389.Va children.max 390limit. 391.It Bq Er EFAULT 392.Fa jail 393points to an address outside the allocated address space of the process. 394.It Bq Er EINVAL 395The version number of the argument is not correct. 396.It Bq Er EAGAIN 397No free JID could be found. 398.El 399.Pp 400The 401.Fn jail_set 402system call 403will fail if: 404.Bl -tag -width Er 405.It Bq Er EACCES 406Write permission is denied on the jail descriptor in the 407.Va desc 408parameter, 409and the 410.Dv JAIL_USE_DESC 411flag was set. 412.It Bq Er EACCES 413Execute permission is denied on the jail descriptor in the 414.Va desc 415parameter, 416and either the 417.Dv JAIL_AT_DESC 418or 419.Dv JAIL_ATTACH 420flag was set. 421.It Bq Er EPERM 422This process is not allowed to create a jail, either because it is not 423the super-user, or because it would exceed the jail's 424.Va children.max 425limit. 426.It Bq Er EPERM 427The jail descriptor in the 428.Va desc 429parameter was created by a user other than the super-user, 430and the 431.Dv JAIL_USE_DESC 432flag was set. 433.It Bq Er EPERM 434A jail parameter was set to a less restrictive value then the current 435environment. 436.It Bq Er EFAULT 437.Fa Iov , 438or one of the addresses contained within it, 439points to an address outside the allocated address space of the process. 440.It Bq Er ENOENT 441The jail referred to by a 442.Va jid 443or 444.Va name 445parameter does not exist, and the 446.Dv JAIL_CREATE 447flag is not set. 448.It Bq Er ENOENT 449The jail referred to by a 450.Va jid 451parameter is not accessible by the process, because the process is in a 452different jail. 453.It Bq Er ENOENT 454The jail referred to by a 455.Va desc 456parameter has been removed. 457.It Bq Er EEXIST 458The jail referred to by a 459.Va jid 460or 461.Va name 462parameter exists, and the 463.Dv JAIL_UPDATE 464flag is not set. 465.It Bq Er EINVAL 466A supplied parameter is the wrong size. 467.It Bq Er EINVAL 468A supplied parameter is out of range. 469.It Bq Er EINVAL 470A supplied string parameter is not null-terminated. 471.It Bq Er EINVAL 472A supplied parameter name does not match any known parameters. 473.It Bq Er EINVAL 474One of the 475.Dv JAIL_CREATE 476or 477.Dv JAIL_UPDATE 478flags is not set. 479.It Bq Er ENAMETOOLONG 480A supplied string parameter is longer than allowed. 481.It Bq Er EAGAIN 482There are no jail IDs left. 483.It Bq Er EMFILE 484A jail descriptor could not be created for the 485.Va desc 486parameter with either the 487.Dv JAIL_GET_DESC 488or 489.Dv JAIL_OWN_DESC 490flag set, 491because the process has already reached its limit for open file descriptors. 492.It Bq Er ENFILE 493A jail descriptor could not be created for the 494.Va desc 495parameter with either the 496.Dv JAIL_GET_DESC 497or 498.Dv JAIL_OWN_DESC 499flag set, 500because the system file table is full. 501.El 502.Pp 503The 504.Fn jail_get 505system call 506will fail if: 507.Bl -tag -width Er 508.It Bq Er EACCES 509Read permission is denied on the jail descriptor in the 510.Va desc 511parameter, 512and the 513.Dv JAIL_USE_DESC 514flag was set. 515.It Bq Er EACCES 516Execute permission is denied on the jail descriptor in the 517.Va desc 518parameter, 519and the 520.Dv JAIL_AT_DESC 521flag was set. 522.It Bq Er EFAULT 523.Fa Iov , 524or one of the addresses contained within it, 525points to an address outside the allocated address space of the process. 526.It Bq Er ENOENT 527The jail referred to by a 528.Va jid 529or 530.Va name 531parameter does not exist. 532.It Bq Er ENOENT 533The jail referred to by a 534.Va jid 535is not accessible by the process, because the process is in a different 536jail. 537.It Bq Er ENOENT 538The 539.Va lastjid 540parameter is greater than the highest current jail ID. 541.It Bq Er ENOENT 542The jail referred to by a 543.Va desc 544parameter has been removed 545.Pq even if the Dv JAIL_CREATE flag has been set . 546.It Bq Er EINVAL 547A supplied parameter is the wrong size. 548.It Bq Er EINVAL 549A supplied parameter is out of range. 550.It Bq Er EINVAL 551A supplied string parameter is not null-terminated. 552.It Bq Er EINVAL 553A supplied parameter name does not match any known parameters. 554.It Bq Er EMFILE 555A jail descriptor could not be created for the 556.Va desc 557parameter with either the 558.Dv JAIL_GET_DESC 559or 560.Dv JAIL_OWN_DESC 561flag set, 562because the process has already reached its limit for open file descriptors. 563.It Bq Er ENFILE 564A jail descriptor could not be created for the 565.Va desc 566parameter with either the 567.Dv JAIL_GET_DESC 568or 569.Dv JAIL_OWN_DESC 570flag set, 571because the system file table is full. 572.El 573.Pp 574The 575.Fn jail_attach 576and 577.Fn jail_remove 578system calls 579will fail if: 580.Bl -tag -width Er 581.It Bq Er EPERM 582A user other than the super-user attempted to attach to or remove a jail. 583.It Bq Er EINVAL 584The jail specified by 585.Fa jid 586does not exist. 587.El 588.Pp 589The 590.Fn jail_attach_jd 591and 592.Fn jail_remove_jd 593system calls 594will fail if: 595.Bl -tag -width Er 596.It Bq Er EINVAL 597The 598.Fa fd 599argument is not a valid jail descriptor. 600.It Bq Er EACCES 601Permission is denied on the jail descriptor 602.Po 603execute permission for 604.Fn jail_attach_fd , 605or write permission for 606.Fn jail_remove_fd 607.Pc . 608.It Bq Er EPERM 609The jail descriptor was created by a user other than the super-user. 610.It Bq Er EINVAL 611The jail specified by 612.Fa jid 613has been removed. 614.El 615.Pp 616Further 617.Fn jail , 618.Fn jail_set , 619.Fn jail_attach , 620and 621.Fn jail_attach_jd 622call 623.Xr chroot 2 624internally, so they can fail for all the same reasons. 625Please consult the 626.Xr chroot 2 627manual page for details. 628.Sh SEE ALSO 629.Xr chdir 2 , 630.Xr chroot 2 , 631.Xr jail 8 632.Sh HISTORY 633The 634.Fn jail 635system call appeared in 636.Fx 4.0 . 637The 638.Fn jail_attach 639system call appeared in 640.Fx 5.1 . 641The 642.Fn jail_set , 643.Fn jail_get , 644and 645.Fn jail_remove 646system calls appeared in 647.Fx 8.0 . 648.Sh AUTHORS 649The jail feature was written by 650.An Poul-Henning Kamp 651for R&D Associates 652who contributed it to 653.Fx . 654.An James Gritton 655added the extensible jail parameters and hierarchical jails. 656