1a2
> .\" Copyright (c) 2009 James Gritton.
25c26
< .\" $FreeBSD: head/lib/libc/sys/jail.2 191668 2009-04-29 16:02:52Z jamie $
---
> .\" $FreeBSD: head/lib/libc/sys/jail.2 191673 2009-04-29 21:14:15Z jamie $
27c28
< .Dd January 6, 2009
---
> .Dd April 29, 2009
31,32c32,37
< .Nm jail , jail_attach
< .Nd imprison current process and future descendants
---
> .Nm jail ,
> .Nm jail_get ,
> .Nm jail_set ,
> .Nm jail_remove ,
> .Nm jail_attach
> .Nd create and manage system jails
41a47,53
> .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"
96a109,121
> 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
97a123,186
> .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
98a188,227
> 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
101a231,237
> .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.
104,106c240,245
< .Fn jail
< returns a non-negative integer, termed the jail identifier (JID).
< It returns \-1 on failure, and sets
---
> .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
110c249
< .Rv -std jail_attach
---
> .Rv -std jail_attach jail_remove
154a294,298
> .It Bq Er EPERM
> This process is not allowed to create a jail.
> .It Bq Er EFAULT
> .Fa jail
> points to an address outside the allocated address space of the process.
160a305,392
> 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.
> .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 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
> .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
162,163c394,398
< .Fn jail
< calls
---
> .Fn jail ,
> .Fn jail_set ,
> and
> .Fn jail_attach
> call
171c406,407
< .Xr chroot 2
---
> .Xr chroot 2 ,
> .Xr jail 8
180a417,423
> The
> .Fn jail_set ,
> .Fn jail_get ,
> and
> .Fn jail_remove
> system calls appeared in
> .Fx 8.0 .
187a431,432
> .An James Gritton
> added the extensible jail parameters.
> .\" Copyright (c) 2009 James Gritton.
25c26
< .\" $FreeBSD: head/lib/libc/sys/jail.2 191668 2009-04-29 16:02:52Z jamie $
---
> .\" $FreeBSD: head/lib/libc/sys/jail.2 191673 2009-04-29 21:14:15Z jamie $
27c28
< .Dd January 6, 2009
---
> .Dd April 29, 2009
31,32c32,37
< .Nm jail , jail_attach
< .Nd imprison current process and future descendants
---
> .Nm jail ,
> .Nm jail_get ,
> .Nm jail_set ,
> .Nm jail_remove ,
> .Nm jail_attach
> .Nd create and manage system jails
41a47,53
> .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"
96a109,121
> 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
97a123,186
> .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
98a188,227
> 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
101a231,237
> .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.
104,106c240,245
< .Fn jail
< returns a non-negative integer, termed the jail identifier (JID).
< It returns \-1 on failure, and sets
---
> .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
110c249
< .Rv -std jail_attach
---
> .Rv -std jail_attach jail_remove
154a294,298
> .It Bq Er EPERM
> This process is not allowed to create a jail.
> .It Bq Er EFAULT
> .Fa jail
> points to an address outside the allocated address space of the process.
160a305,392
> 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.
> .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 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
> .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
162,163c394,398
< .Fn jail
< calls
---
> .Fn jail ,
> .Fn jail_set ,
> and
> .Fn jail_attach
> call
171c406,407
< .Xr chroot 2
---
> .Xr chroot 2 ,
> .Xr jail 8
180a417,423
> The
> .Fn jail_set ,
> .Fn jail_get ,
> and
> .Fn jail_remove
> system calls appeared in
> .Fx 8.0 .
187a431,432
> .An James Gritton
> added the extensible jail parameters.