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 4, 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 EBADF 406The 407.Va desc 408parameter does not refer to a valid jail descriptor, 409and either the 410.Dv JAIL_USE_DESC 411or 412.Dv JAIL_AT_DESC 413flag was set. 414.It Bq Er EACCES 415Write permission is denied on the jail descriptor in the 416.Va desc 417parameter, 418and the 419.Dv JAIL_USE_DESC 420flag was set. 421.It Bq Er EACCES 422Execute permission is denied on the jail descriptor in the 423.Va desc 424parameter, 425and either the 426.Dv JAIL_AT_DESC 427or 428.Dv JAIL_ATTACH 429flag was set. 430.It Bq Er EPERM 431This process is not allowed to create a jail, either because it is not 432the super-user, or because it would exceed the jail's 433.Va children.max 434limit. 435.It Bq Er EPERM 436The jail descriptor in the 437.Va desc 438parameter was created by a user other than the super-user, 439and the 440.Dv JAIL_USE_DESC 441flag was set. 442.It Bq Er EPERM 443A jail parameter was set to a less restrictive value then the current 444environment. 445.It Bq Er EFAULT 446.Fa Iov , 447or one of the addresses contained within it, 448points to an address outside the allocated address space of the process. 449.It Bq Er ENOENT 450The jail referred to by a 451.Va jid 452or 453.Va name 454parameter does not exist, and the 455.Dv JAIL_CREATE 456flag is not set. 457.It Bq Er ENOENT 458The jail referred to by a 459.Va jid 460parameter is not accessible by the process, because the process is in a 461different jail. 462.It Bq Er ENOENT 463The jail referred to by a 464.Va desc 465parameter has been removed. 466.It Bq Er EEXIST 467The jail referred to by a 468.Va jid 469or 470.Va name 471parameter exists, and the 472.Dv JAIL_UPDATE 473flag is not set. 474.It Bq Er EINVAL 475A supplied parameter is the wrong size. 476.It Bq Er EINVAL 477A supplied parameter is out of range. 478.It Bq Er EINVAL 479A supplied string parameter is not null-terminated. 480.It Bq Er EINVAL 481A supplied parameter name does not match any known parameters. 482.It Bq Er EINVAL 483One of the 484.Dv JAIL_CREATE 485or 486.Dv JAIL_UPDATE 487flags is not set. 488.It Bq Er ENAMETOOLONG 489A supplied string parameter is longer than allowed. 490.It Bq Er EAGAIN 491There are no jail IDs left. 492.It Bq Er EMFILE 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 process has already reached its limit for open file descriptors. 501.It Bq Er ENFILE 502A jail descriptor could not be created for the 503.Va desc 504parameter with either the 505.Dv JAIL_GET_DESC 506or 507.Dv JAIL_OWN_DESC 508flag set, 509because the system file table is full. 510.El 511.Pp 512The 513.Fn jail_get 514system call 515will fail if: 516.Bl -tag -width Er 517.It Bq Er EBADF 518The 519.Va desc 520parameter does not refer to a valid jail descriptor, 521and either the 522.Dv JAIL_USE_DESC 523or 524.Dv JAIL_AT_DESC 525flag was set. 526.It Bq Er EACCES 527Read permission is denied on the jail descriptor in the 528.Va desc 529parameter, 530and the 531.Dv JAIL_USE_DESC 532flag was set. 533.It Bq Er EACCES 534Execute permission is denied on the jail descriptor in the 535.Va desc 536parameter, 537and the 538.Dv JAIL_AT_DESC 539flag was set. 540.It Bq Er EFAULT 541.Fa Iov , 542or one of the addresses contained within it, 543points to an address outside the allocated address space of the process. 544.It Bq Er ENOENT 545The jail referred to by a 546.Va jid 547or 548.Va name 549parameter does not exist. 550.It Bq Er ENOENT 551The jail referred to by a 552.Va jid 553is not accessible by the process, because the process is in a different 554jail. 555.It Bq Er ENOENT 556The 557.Va lastjid 558parameter is greater than the highest current jail ID. 559.It Bq Er ENOENT 560The jail referred to by a 561.Va desc 562parameter has been removed 563.Pq even if the Dv JAIL_CREATE flag has been set . 564.It Bq Er EINVAL 565A supplied parameter is the wrong size. 566.It Bq Er EINVAL 567A supplied parameter name does not match any known parameters. 568.It Bq Er EMFILE 569A jail descriptor could not be created for the 570.Va desc 571parameter with either the 572.Dv JAIL_GET_DESC 573or 574.Dv JAIL_OWN_DESC 575flag set, 576because the process has already reached its limit for open file descriptors. 577.It Bq Er ENFILE 578A jail descriptor could not be created for the 579.Va desc 580parameter with either the 581.Dv JAIL_GET_DESC 582or 583.Dv JAIL_OWN_DESC 584flag set, 585because the system file table is full. 586.El 587.Pp 588The 589.Fn jail_attach 590and 591.Fn jail_remove 592system calls 593will fail if: 594.Bl -tag -width Er 595.It Bq Er EPERM 596A user other than the super-user attempted to attach to or remove a jail. 597.It Bq Er EINVAL 598The jail specified by 599.Fa jid 600does not exist. 601.El 602.Pp 603The 604.Fn jail_attach_jd 605and 606.Fn jail_remove_jd 607system calls 608will fail if: 609.Bl -tag -width Er 610.It Bq Er EBADF 611The 612.Fa fd 613argument is not a valid jail descriptor. 614.It Bq Er EACCES 615Permission is denied on the jail descriptor 616.Po 617execute permission for 618.Fn jail_attach_fd , 619or write permission for 620.Fn jail_remove_fd 621.Pc . 622.It Bq Er EPERM 623The jail descriptor was created by a user other than the super-user. 624.It Bq Er EINVAL 625The jail specified by 626.Fa jid 627has been removed. 628.El 629.Pp 630Further 631.Fn jail , 632.Fn jail_set , 633.Fn jail_attach , 634and 635.Fn jail_attach_jd 636call 637.Xr chroot 2 638internally, so they can fail for all the same reasons. 639Please consult the 640.Xr chroot 2 641manual page for details. 642.Sh SEE ALSO 643.Xr chdir 2 , 644.Xr chroot 2 , 645.Xr jail 8 646.Sh HISTORY 647The 648.Fn jail 649system call appeared in 650.Fx 4.0 . 651The 652.Fn jail_attach 653system call appeared in 654.Fx 5.1 . 655The 656.Fn jail_set , 657.Fn jail_get , 658and 659.Fn jail_remove 660system calls appeared in 661.Fx 8.0 . 662.Sh AUTHORS 663The jail feature was written by 664.An Poul-Henning Kamp 665for R&D Associates 666who contributed it to 667.Fx . 668.An James Gritton 669added the extensible jail parameters and hierarchical jails. 670