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
251 Once a process has been put in a prison, it and its descendants cannot escape
254 Inside the prison, the concept of
258 it can be assumed that nothing can be mangled from inside a prison which
259 does not exist entirely inside that prison.
260 For instance the directory
263 can be manipulated all the ways a root can normally do it, including
265 but new device special nodes cannot be created because they reference
266 shared resources (the device drivers in the kernel).
269 for a process is the greater of the global
271 or, if present, the per-jail
274 All IP activity will be forced to happen to/from the IP number specified,
275 which should be an alias on one of the network interfaces.
276 All connections to/from the loopback address
280 for IPv6) will be changed to be to/from the primary address
281 of the jail for the given address family.
283 It is possible to identify a process as jailed by examining
284 .Dq Li /proc/<pid>/status :
285 it will show a field near the end of the line, either as
286 a single hyphen for a process at large, or the name currently
287 set for the prison for jailed processes.
295 This process is not allowed to create a jail, either because it is not
296 the super-user, or because it would exceed the jail's
301 points to an address outside the allocated address space of the process.
303 The version number of the argument is not correct.
305 No free JID could be found.
314 This process is not allowed to create a jail, either because it is not
315 the super-user, or because it would exceed the jail's
319 A jail parameter was set to a less restrictive value then the current
323 or one of the addresses contained within it,
324 points to an address outside the allocated address space of the process.
326 The jail referred to by a
330 parameter does not exist, and the
334 The jail referred to by a
336 is not accessible by the process, because the process is in a different
339 The jail referred to by a
343 parameter exists, and the
347 A supplied parameter is the wrong size.
349 A supplied parameter is out of range.
351 A supplied string parameter is not null-terminated.
353 A supplied parameter name does not match any known parameters.
360 .It Bq Er ENAMETOOLONG
361 A supplied string parameter is longer than allowed.
363 There are no jail IDs left.
373 or one of the addresses contained within it,
374 points to an address outside the allocated address space of the process.
376 The jail referred to by a
380 parameter does not exist.
382 The jail referred to by a
384 is not accessible by the process, because the process is in a different
389 parameter is greater than the highest current jail ID.
391 A supplied parameter is the wrong size.
393 A supplied parameter name does not match any known parameters.
404 A user other than the super-user attempted to attach to or remove a jail.
406 The jail specified by
418 internally, so it can fail for all the same reasons.
421 manual page for details.
429 system call appeared in
433 system call appeared in
440 system calls appeared in
443 The jail feature was written by
444 .An Poul-Henning Kamp
446 .Dq Li http://www.rndassociates.com/
447 who contributed it to
450 added the extensible jail parameters and hierarchical jails.