1 .\" Copyright (c) 1999 Poul-Henning Kamp.
2 .\" Copyright (c) 2009 James Gritton.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
37 .Nd create and manage system jails
44 .Fn jail "struct jail *jail"
46 .Fn jail_attach "int jid"
48 .Fn jail_remove "int jid"
51 .Fn jail_get "struct iovec *iov" "u_int niov" "int flags"
53 .Fn jail_set "struct iovec *iov" "u_int niov" "int flags"
57 system call sets up a jail and locks the current process in it.
59 The argument is a pointer to a structure describing the prison:
60 .Bd -literal -offset indent
74 defines the version of the API in use.
76 is defined for the current version.
80 pointer should be set to the directory which is to be the root of the
85 pointer can be set to the hostname of the prison.
87 from the inside of the prison.
91 pointer is an optional name that can be assigned to the jail
92 for example for management purposes.
98 give the numbers of IPv4 and IPv6 addresses that will be passed
99 via their respective pointers.
105 pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
106 the prison, or NULL if none.
107 IPv4 addresses must be in network byte order.
109 This is equivalent to the
111 system call (see below), with the parameters
124 system call creates a new jail, or modifies an existing one, and optionally
125 locks the current process in it.
126 Jail parameters are passed as an array of name-value pairs in the array
131 Parameter names are a null-terminated string, and values may be strings,
132 integers, or other arbitrary data.
133 Some parameters are boolean, and do not have a value (their length is zero)
134 but are set by the name alone with or without a
140 Any parameters not set will be given default values, generally based on
141 the current environment.
143 Jails have a set of core parameters, and modules can add their own jail
145 The current set of available parameters, and their formats, can be
147 .Va security.jail.param
149 Notable parameters include those mentioned in the
151 description above, as well as
155 which identify the jail being created or modified.
158 for more information on the core jail parameters.
162 arguments consists of one or more of the following flags:
163 .Bl -tag -width indent
170 parameters exists, they must not refer to an existing jail.
172 Modify an existing jail.
177 parameters must exist, and must refer to an existing jail.
182 are set, a jail will be created if it does not yet exist, and modified if it
185 In addition to creating or modifying the jail, attach the current process to
190 Allow setting a jail that is in the process of being removed.
195 system call retrieves jail parameters, using the same name-value list as
202 The jail to read can be specified by either
206 by including those parameters in the list.
207 If they are included but are not intended to be the search key, they
208 should be cleared (zero and the empty string respectively).
210 The special parameter
212 can be used to retrieve a list of all jails.
213 It will fetch the jail with the jid above and closest to the passed value.
214 The first jail (usually but not always jid 1) can be found by passing a
220 arguments consists of one or more following flags:
221 .Bl -tag -width indent
223 Allow getting a jail that is in the process of being removed.
228 system call attaches the current process to an existing jail,
234 system call removes the jail identified by
236 It will kill all processes belonging to the jail, and remove any children
244 return a non-negative integer, termed the jail identifier (JID).
245 They return \-1 on failure, and set
247 to indicate the error.
249 .Rv -std jail_attach jail_remove
257 This process is not allowed to create a jail, either because it is not
258 the super-user, or because it would exceed the jail's
263 points to an address outside the allocated address space of the process.
265 The version number of the argument is not correct.
267 No free JID could be found.
276 This process is not allowed to create a jail, either because it is not
277 the super-user, or because it would exceed the jail's
281 A jail parameter was set to a less restrictive value then the current
285 or one of the addresses contained within it,
286 points to an address outside the allocated address space of the process.
288 The jail referred to by a
292 parameter does not exist, and the
296 The jail referred to by a
298 is not accessible by the process, because the process is in a different
301 The jail referred to by a
305 parameter exists, and the
309 A supplied parameter is the wrong size.
311 A supplied parameter is out of range.
313 A supplied string parameter is not null-terminated.
315 A supplied parameter name does not match any known parameters.
322 .It Bq Er ENAMETOOLONG
323 A supplied string parameter is longer than allowed.
325 There are no jail IDs left.
335 or one of the addresses contained within it,
336 points to an address outside the allocated address space of the process.
338 The jail referred to by a
342 parameter does not exist.
344 The jail referred to by a
346 is not accessible by the process, because the process is in a different
351 parameter is greater than the highest current jail ID.
353 A supplied parameter is the wrong size.
355 A supplied parameter name does not match any known parameters.
366 A user other than the super-user attempted to attach to or remove a jail.
368 The jail specified by
380 internally, so they can fail for all the same reasons.
383 manual page for details.
391 system call appeared in
395 system call appeared in
402 system calls appeared in
405 The jail feature was written by
406 .An Poul-Henning Kamp
408 .Dq Li http://www.rndassociates.com/
409 who contributed it to
412 added the extensible jail parameters and hierarchical jails.