diff options
Diffstat (limited to 'lib/libc/sys/jail.2')
| -rw-r--r-- | lib/libc/sys/jail.2 | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/lib/libc/sys/jail.2 b/lib/libc/sys/jail.2 new file mode 100644 index 0000000..bf6218c --- /dev/null +++ b/lib/libc/sys/jail.2 @@ -0,0 +1,448 @@ +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd June 23, 2009 +.Dt JAIL 2 +.Os +.Sh NAME +.Nm jail , +.Nm jail_get , +.Nm jail_set , +.Nm jail_remove , +.Nm jail_attach +.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" +.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 { + u_int32_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 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 +Allow setting a jail that is in the process of being removed. +.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. +.El +.Pp +The +.Fn jail_attach +system call attaches the current process to an existing jail, +identified by +.Fa jid . +.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. +.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 +.Sh PRISON? +Once a process has been put in a prison, it and its descendants cannot escape +the prison. +.Pp +Inside the prison, the concept of +.Dq superuser +is very diluted. +In general, +it can be assumed that nothing can be mangled from inside a prison which +does not exist entirely inside that prison. +For instance the directory +tree below +.Dq Li path +can be manipulated all the ways a root can normally do it, including +.Dq Li "rm -rf /*" +but new device special nodes cannot be created because they reference +shared resources (the device drivers in the kernel). +The effective +.Dq securelevel +for a process is the greater of the global +.Dq securelevel +or, if present, the per-jail +.Dq securelevel . +.Pp +All IP activity will be forced to happen to/from the IP number specified, +which should be an alias on one of the network interfaces. +All connections to/from the loopback address +.Pf ( Li 127.0.0.1 +for IPv4, +.Li ::1 +for IPv6) will be changed to be to/from the primary address +of the jail for the given address family. +.Pp +It is possible to identify a process as jailed by examining +.Dq Li /proc/<pid>/status : +it will show a field near the end of the line, either as +a single hyphen for a process at large, or the name currently +set for the prison for jailed processes. +.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 +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 +is not accessible by the process, because the process is in a different +jail. +.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. +.El +.Pp +The +.Fn jail_get +system call +will fail if: +.Bl -tag -width Er +.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. +.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 EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.El +.Pp +The +.Fn jail_attach +and +.Fn jail_remove +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The jail specified by +.Fa jid +does not exist. +.El +.Pp +Further +.Fn jail , +.Fn jail_set , +and +.Fn jail_attach +call +.Xr chroot 2 +internally, so it can fail for all the same reasons. +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 +.Dq Li http://www.rndassociates.com/ +who contributed it to +.Fx . +.An James Gritton +added the extensible jail parameters and hierarchical jails. |
