diff options
Diffstat (limited to 'static/freebsd/man2/jail.2')
| -rw-r--r-- | static/freebsd/man2/jail.2 | 591 |
1 files changed, 591 insertions, 0 deletions
diff --git a/static/freebsd/man2/jail.2 b/static/freebsd/man2/jail.2 new file mode 100644 index 00000000..4c8530ca --- /dev/null +++ b/static/freebsd/man2/jail.2 @@ -0,0 +1,591 @@ +.\" Copyright (c) 1999 Poul-Henning Kamp. +.\" Copyright (c) 2009 James Gritton. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 15, 2025 +.Dt JAIL 2 +.Os +.Sh NAME +.Nm jail , +.Nm jail_get , +.Nm jail_set , +.Nm jail_remove , +.Nm jail_attach , +.Nm jail_remove_jd , +.Nm jail_attach_jd +.Nd create and manage system jails +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/jail.h +.Ft int +.Fn jail "struct jail *jail" +.Ft int +.Fn jail_attach "int jid" +.Ft int +.Fn jail_remove "int jid" +.Ft int +.Fn jail_attach_jd "int fd" +.Ft int +.Fn jail_remove_jd "int fd" +.In sys/uio.h +.Ft int +.Fn jail_get "struct iovec *iov" "u_int niov" "int flags" +.Ft int +.Fn jail_set "struct iovec *iov" "u_int niov" "int flags" +.Sh DESCRIPTION +The +.Fn jail +system call sets up a jail and locks the current process in it. +.Pp +The argument is a pointer to a structure describing the prison: +.Bd -literal -offset indent +struct jail { + uint32_t version; + char *path; + char *hostname; + char *jailname; + unsigned int ip4s; + unsigned int ip6s; + struct in_addr *ip4; + struct in6_addr *ip6; +}; +.Ed +.Pp +.Dq Li version +defines the version of the API in use. +.Dv JAIL_API_VERSION +is defined for the current version. +.Pp +The +.Dq Li path +pointer should be set to the directory which is to be the root of the +prison. +.Pp +The +.Dq Li hostname +pointer can be set to the hostname of the prison. +This can be changed +from the inside of the prison. +.Pp +The +.Dq Li jailname +pointer is an optional name that can be assigned to the jail +for example for management purposes. +.Pp +The +.Dq Li ip4s +and +.Dq Li ip6s +give the numbers of IPv4 and IPv6 addresses that will be passed +via their respective pointers. +.Pp +The +.Dq Li ip4 +and +.Dq Li ip6 +pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to +the prison, or NULL if none. +IPv4 addresses must be in network byte order. +.Pp +This is equivalent to, and deprecated in favor of, the +.Fn jail_set +system call (see below), with the parameters +.Va path , +.Va host.hostname , +.Va name , +.Va ip4.addr , +and +.Va ip6.addr , +and with the +.Dv JAIL_ATTACH +flag. +.Pp +The +.Fn jail_set +system call creates a new jail, or modifies an existing one, and optionally +locks the current process in it. +Jail parameters are passed as an array of name-value pairs in the array +.Fa iov , +containing +.Fa niov +elements. +Parameter names are a null-terminated string, and values may be strings, +integers, or other arbitrary data. +Some parameters are boolean, and do not have a value (their length is zero) +but are set by the name alone with or without a +.Dq no +prefix, e.g. +.Va persist +or +.Va nopersist . +Any parameters not set will be given default values, generally based on +the current environment. +.Pp +Jails have a set of core parameters, and modules can add their own jail +parameters. +The current set of available parameters, and their formats, can be +retrieved via the +.Va security.jail.param +sysctl MIB entry. +Notable parameters include those mentioned in the +.Fn jail +description above, as well as +.Va jid +and +.Va name , +which identify the jail being created or modified. +See +.Xr jail 8 +for more information on the core jail parameters. +.Pp +The +.Fa flags +arguments consists of one or more of the following flags: +.Bl -tag -width indent +.It Dv JAIL_CREATE +Create a new jail. +If a +.Va jid +or +.Va name +parameters exists, they must not refer to an existing jail. +.It Dv JAIL_UPDATE +Modify an existing jail. +One of the +.Va jid +or +.Va name +parameters must exist, and must refer to an existing jail. +If both +.Dv JAIL_CREATE +and +.Dv JAIL_UPDATE +are set, a jail will be created if it does not yet exist, and modified if it +does exist. +.It Dv JAIL_ATTACH +In addition to creating or modifying the jail, attach the current process to +it, as with the +.Fn jail_attach +system call. +.It Dv JAIL_DYING +This is deprecated in +.Fn jail_set +and has no effect. +.It Dv JAIL_USE_DESC +Identify the jail by a descriptor in the +.Va desc +parameter. +.It Dv JAIL_AT_DESC +Operate in the context of the jail described by the +.Va desc +parameter, instead of the current jail. +Only one of +.Dv JAIL_USE_DESC +or +.Dv JAIL_AT_DESC +may be specified. +.It Dv JAIL_GET_DESC +Return a new jail descriptor for the jail in the +.Va desc +parameter. +.It Dv JAIL_OWN_DESC +Return an +.Dq owning +jail descriptor in the +.Va desc +parameter. +.El +.Pp +The +.Fn jail_get +system call retrieves jail parameters, using the same name-value list as +.Fn jail_set +in the +.Fa iov +and +.Fa niov +arguments. +The jail to read can be specified by either +.Va jid +or +.Va name +by including those parameters in the list. +If they are included but are not intended to be the search key, they +should be cleared (zero and the empty string respectively). +.Pp +The special parameter +.Va lastjid +can be used to retrieve a list of all jails. +It will fetch the jail with the jid above and closest to the passed value. +The first jail (usually but not always jid 1) can be found by passing a +.Va lastjid +of zero. +.Pp +The +.Fa flags +arguments consists of one or more following flags: +.Bl -tag -width indent +.It Dv JAIL_DYING +Allow getting a jail that is in the process of being removed. +.It Dv JAIL_USE_DESC , Dv JAIL_AT_DESC , Dv JAIL_GET_DESC , Dv JAIL_OWN_DESC +These have the same meaning as they do in +.Fn jail_set . +.El +.Pp +The +.Fn jail_attach +system call attaches the current process to an existing jail, +identified by +.Fa jid . +It changes the process's root and current directories to the jail's +.Va path +directory. +.Pp +The +.Fn jail_remove +system call removes the jail identified by +.Fa jid . +It will kill all processes belonging to the jail, and remove any children +of that jail. +.Pp +The +.Fn jail_attach_fd +and +.Fn jail_remove_fd +system calls work the same as +.Fn jail_attach +and +.Fn jail_remove , +except that they operate on the jail identified by jail descriptor +.Fa fd . +.Ss Jail Descriptors +In addition to the jail ID, +jails can be referred to using a jail descriptor, +a type of file descriptor tied to a particular jail. +Jail descriptors are created by calling +.Fn jail_set +or +.Fn jail_get +with the special parameter +.Va desc , +and either the +.Dv JAIL_GET_DESC +or +.Dv JAIL_OWN_DESC +flags set. +The difference between the two flags is that descriptors created with +.Dv JAIL_OWN_DESC +.Po +called +.Dq owning +descriptors +.Pc +will automatically remove the jail when the descriptor is closed. +.Pp +Jail descriptors can be passed back to +.Fn jail_set +or +.Fm jail_get +with the +.Va desc +parameter, +and either the +.Dv JAIL_USE_DESC +or +.Dv JAIL_AT_DESC +flags set. +With +.Dv JAIL_USE_DESC , +the descriptor identifies the jail to operate on, +instead of the +.Va jid +or +.Va name +parameter. +With +.Dv JAIL_AT_DESC , +the descriptor is used in place of the current jail, +allowing accessing or creating jails that are children of the +descriptor jail. +.Pp +The system calls +.Fn jail_attach_jd +and +.Fn jail_remove_jd +work the same as +.Fn jail_attach +and +.Fn jail_remove , +except that they operate on the jail referred to by the passed descriptor. +.Sh RETURN VALUES +If successful, +.Fn jail , +.Fn jail_set , +and +.Fn jail_get +return a non-negative integer, termed the jail identifier (JID). +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Pp +.Rv -std jail_attach jail_remove jail_attach_jd jail_remove_jd +.Sh ERRORS +The +.Fn jail +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EFAULT +.Fa jail +points to an address outside the allocated address space of the process. +.It Bq Er EINVAL +The version number of the argument is not correct. +.It Bq Er EAGAIN +No free JID could be found. +.El +.Pp +The +.Fn jail_set +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EPERM +The jail descriptor in the +.Va desc +parameter was created by a user other than the super-user, +and the +.Dv JAIL_USE_DESC +flag was set. +.It Bq Er EPERM +A jail parameter was set to a less restrictive value then the current +environment. +.It Bq Er EFAULT +.Fa Iov , +or one of the addresses contained within it, +points to an address outside the allocated address space of the process. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist, and the +.Dv JAIL_CREATE +flag is not set. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +parameter is not accessible by the process, because the process is in a +different jail. +.It Bq Er ENOENT +The jail referred to by a +.Va desc +parameter has been removed. +.It Bq Er EEXIST +The jail referred to by a +.Va jid +or +.Va name +parameter exists, and the +.Dv JAIL_UPDATE +flag is not set. +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter is out of range. +.It Bq Er EINVAL +A supplied string parameter is not null-terminated. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.It Bq Er EINVAL +One of the +.Dv JAIL_CREATE +or +.Dv JAIL_UPDATE +flags is not set. +.It Bq Er ENAMETOOLONG +A supplied string parameter is longer than allowed. +.It Bq Er EAGAIN +There are no jail IDs left. +.It Bq Er EMFILE +A jail descriptor could not be created for the +.Va desc +parameter with either the +.Dv JAIL_GET_DESC +or +.Dv JAIL_OWN_DESC +flag set, +because the process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +A jail descriptor could not be created for the +.Va desc +parameter with either the +.Dv JAIL_GET_DESC +or +.Dv JAIL_OWN_DESC +flag set, +because the system file table is full. +.El +.Pp +The +.Fn jail_get +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +is not accessible by the process, because the process is in a different +jail. +.It Bq Er ENOENT +The +.Va lastjid +parameter is greater than the highest current jail ID. +.It Bq Er ENOENT +The jail referred to by a +.Va desc +parameter has been removed +.Pq even if the Dv JAIL_CREATE flag has been set . +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter is out of range. +.It Bq Er EINVAL +A supplied string parameter is not null-terminated. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.It Bq Er EMFILE +A jail descriptor could not be created for the +.Va desc +parameter with either the +.Dv JAIL_GET_DESC +or +.Dv JAIL_OWN_DESC +flag set, +because the process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +A jail descriptor could not be created for the +.Va desc +parameter with either the +.Dv JAIL_GET_DESC +or +.Dv JAIL_OWN_DESC +flag set, +because the system file table is full. +.El +.Pp +The +.Fn jail_attach +and +.Fn jail_remove +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +A user other than the super-user attempted to attach to or remove a jail. +.It Bq Er EINVAL +The jail specified by +.Fa jid +does not exist. +.El +.Pp +The +.Fn jail_attach_jd +and +.Fn jail_remove_jd +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa fd +argument is not a valid jail descriptor. +.It Bq Er EPERM +The jail descriptor was created by a user other than the super-user. +.It Bq Er EINVAL +The jail specified by +.Fa jid +has been removed. +.El +.Pp +Further +.Fn jail , +.Fn jail_set , +.Fn jail_attach , +and +.Fn jail_attach_jd +call +.Xr chroot 2 +internally, so they can fail for all the same reasons. +In particular, they return the +.Bq Er EPERM +error when the process to join a jail has open directories. +Please consult the +.Xr chroot 2 +manual page for details. +.Sh SEE ALSO +.Xr chdir 2 , +.Xr chroot 2 , +.Xr jail 8 +.Sh HISTORY +The +.Fn jail +system call appeared in +.Fx 4.0 . +The +.Fn jail_attach +system call appeared in +.Fx 5.1 . +The +.Fn jail_set , +.Fn jail_get , +and +.Fn jail_remove +system calls appeared in +.Fx 8.0 . +.Sh AUTHORS +The jail feature was written by +.An Poul-Henning Kamp +for R&D Associates +who contributed it to +.Fx . +.An James Gritton +added the extensible jail parameters and hierarchical jails. |