Deleted Added
sdiff udiff text old ( 191668 ) new ( 191673 )
full compact
jail.2 (191668) jail.2 (191673)
1.\" Copyright (c) 1999 Poul-Henning Kamp.
1.\" Copyright (c) 1999 Poul-Henning Kamp.
2.\" Copyright (c) 2009 James Gritton.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright

--- 7 unchanged lines hidden (view full) ---

17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
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

--- 7 unchanged lines hidden (view full) ---

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
24.\" SUCH DAMAGE.
25.\"
25.\" $FreeBSD: head/lib/libc/sys/jail.2 191668 2009-04-29 16:02:52Z jamie $
26.\" $FreeBSD: head/lib/libc/sys/jail.2 191673 2009-04-29 21:14:15Z jamie $
26.\"
27.\"
27.Dd January 6, 2009
28.Dd April 29, 2009
28.Dt JAIL 2
29.Os
30.Sh NAME
29.Dt JAIL 2
30.Os
31.Sh NAME
31.Nm jail , jail_attach
32.Nd imprison current process and future descendants
32.Nm jail ,
33.Nm jail_get ,
34.Nm jail_set ,
35.Nm jail_remove ,
36.Nm jail_attach
37.Nd create and manage system jails
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In sys/param.h
37.In sys/jail.h
38.Ft int
39.Fn jail "struct jail *jail"
40.Ft int
41.Fn jail_attach "int jid"
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In sys/param.h
42.In sys/jail.h
43.Ft int
44.Fn jail "struct jail *jail"
45.Ft int
46.Fn jail_attach "int jid"
47.Ft int
48.Fn jail_remove "int jid"
49.In sys/uio.h
50.Ft int
51.Fn jail_get "struct iovec *iov" "u_int niov" "int flags"
52.Ft int
53.Fn jail_set "struct iovec *iov" "u_int niov" "int flags"
42.Sh DESCRIPTION
43The
44.Fn jail
45system call sets up a jail and locks the current process in it.
46.Pp
47The argument is a pointer to a structure describing the prison:
48.Bd -literal -offset indent
49struct jail {

--- 39 unchanged lines hidden (view full) ---

89The
90.Dq Li ip4
91and
92.Dq Li ip6
93pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
94the prison, or NULL if none.
95IPv4 addresses must be in network byte order.
96.Pp
54.Sh DESCRIPTION
55The
56.Fn jail
57system call sets up a jail and locks the current process in it.
58.Pp
59The argument is a pointer to a structure describing the prison:
60.Bd -literal -offset indent
61struct jail {

--- 39 unchanged lines hidden (view full) ---

101The
102.Dq Li ip4
103and
104.Dq Li ip6
105pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
106the prison, or NULL if none.
107IPv4 addresses must be in network byte order.
108.Pp
109This is equivalent to the
110.Fn jail_set
111system call (see below), with the parameters
112.Va path ,
113.Va host.hostname ,
114.Va name ,
115.Va ip4.addr ,
116and
117.Va ip6.addr ,
118and with the
119.Dv JAIL_ATTACH
120flag.
121.Pp
97The
122The
123.Fn jail_set
124system call creates a new jail, or modifies an existing one, and optionally
125locks the current process in it.
126Jail parameters are passed as an array of name-value pairs in the array
127.Fa iov ,
128containing
129.Fa niov
130elements.
131Parameter names are a null-terminated string, and values may be strings,
132integers, or other arbitrary data.
133Some parameters are boolean, and do not have a value (their length is zero)
134but are set by the name alone with or without a
135.Dq no
136prefix, e.g.
137.Va persist
138or
139.Va nopersist .
140Any parameters not set will be given default values, generally based on
141the current environment.
142.Pp
143Jails have a set of core parameters, and modules can add their own jail
144parameters.
145The current set of available parameters, and their formats, can be
146retrieved via the
147.Va security.jail.param
148sysctl MIB entry.
149Notable parameters include those mentioned in the
150.Fn jail
151description above, as well as
152.Va jid
153and
154.Va name ,
155which identify the jail being created or modified.
156See
157.Xr jail 8
158for more information on the core jail parameters.
159.Pp
160The
161.Fa flags
162arguments consists of one or more of the following flags:
163.Bl -tag -width indent
164.It Dv JAIL_CREATE
165Create a new jail.
166If a
167.Va jid
168or
169.Va name
170parameters exists, they must not refer to an existing jail.
171.It Dv JAIL_UPDATE
172Modify an existing jail.
173One of the
174.Va jid
175or
176.Va name
177parameters must exist, and must refer to an existing jail.
178If both
179.Dv JAIL_CREATE
180and
181.Dv JAIL_UPDATE
182are set, a jail will be created if it does not yet exist, and modified if it
183does exist.
184.It Dv JAIL_ATTACH
185In addition to creating or modifying the jail, attach the current process to
186it, as with the
98.Fn jail_attach
187.Fn jail_attach
188system call.
189.It Dv JAIL_DYING
190Allow setting a jail that is in the process of being removed.
191.El
192.Pp
193The
194.Fn jail_get
195system call retrieves jail parameters, using the same name-value list as
196.Fn jail_set
197in the
198.Fa iov
199and
200.Fa niov
201arguments.
202The jail to read can be specified by either
203.Va jid
204or
205.Va name
206by including those parameters in the list.
207If they are included but are not intended to be the search key, they
208should be cleared (zero and the empty string respectively).
209.Pp
210The special parameter
211.Va lastjid
212can be used to retrieve a list of all jails.
213It will fetch the jail with the jid above and closest to the passed value.
214The first jail (usually but not always jid 1) can be found by passing a
215.Va lastjid
216of zero.
217.Pp
218The
219.Fa flags
220arguments consists of one or more following flags:
221.Bl -tag -width indent
222.It Dv JAIL_DYING
223Allow getting a jail that is in the process of being removed.
224.El
225.Pp
226The
227.Fn jail_attach
99system call attaches the current process to an existing jail,
100identified by
101.Fa jid .
228system call attaches the current process to an existing jail,
229identified by
230.Fa jid .
231.Pp
232The
233.Fn jail_remove
234system call removes the jail identified by
235.Fa jid .
236It will kill all processes belonging to the jail, and remove any children
237of that jail.
102.Sh RETURN VALUES
103If successful,
238.Sh RETURN VALUES
239If successful,
104.Fn jail
105returns a non-negative integer, termed the jail identifier (JID).
106It returns \-1 on failure, and sets
240.Fn jail ,
241.Fn jail_set ,
242and
243.Fn jail_get
244return a non-negative integer, termed the jail identifier (JID).
245They return \-1 on failure, and set
107.Va errno
108to indicate the error.
109.Pp
246.Va errno
247to indicate the error.
248.Pp
110.Rv -std jail_attach
249.Rv -std jail_attach jail_remove
111.Sh PRISON?
112Once a process has been put in a prison, it and its descendants cannot escape
113the prison.
114.Pp
115Inside the prison, the concept of
116.Dq superuser
117is very diluted.
118In general,

--- 28 unchanged lines hidden (view full) ---

147a single hyphen for a process at large, or the hostname currently
148set for the prison for jailed processes.
149.Sh ERRORS
150The
151.Fn jail
152system call
153will fail if:
154.Bl -tag -width Er
250.Sh PRISON?
251Once a process has been put in a prison, it and its descendants cannot escape
252the prison.
253.Pp
254Inside the prison, the concept of
255.Dq superuser
256is very diluted.
257In general,

--- 28 unchanged lines hidden (view full) ---

286a single hyphen for a process at large, or the hostname currently
287set for the prison for jailed processes.
288.Sh ERRORS
289The
290.Fn jail
291system call
292will fail if:
293.Bl -tag -width Er
294.It Bq Er EPERM
295This process is not allowed to create a jail.
296.It Bq Er EFAULT
297.Fa jail
298points to an address outside the allocated address space of the process.
155.It Bq Er EINVAL
156The version number of the argument is not correct.
157.It Bq Er EAGAIN
158No free JID could be found.
159.El
160.Pp
299.It Bq Er EINVAL
300The version number of the argument is not correct.
301.It Bq Er EAGAIN
302No free JID could be found.
303.El
304.Pp
305The
306.Fn jail_set
307system call
308will fail if:
309.Bl -tag -width Er
310.It Bq Er EPERM
311This process is not allowed to create a jail.
312.It Bq Er EPERM
313A jail parameter was set to a less restrictive value then the current
314environment.
315.It Bq Er EFAULT
316.Fa Iov ,
317or one of the addresses contained within it,
318points to an address outside the allocated address space of the process.
319.It Bq Er ENOENT
320The jail referred to by a
321.Va jid
322or
323.Va name
324parameter does not exist, and the
325.Dv JAIL_CREATE
326flag is not set.
327.It Bq Er EEXIST
328The jail referred to by a
329.Va jid
330or
331.Va name
332parameter exists, and the
333.Dv JAIL_UPDATE
334flag is not set.
335.It Bq Er EINVAL
336A supplied parameter is the wrong size.
337.It Bq Er EINVAL
338A supplied parameter is out of range.
339.It Bq Er EINVAL
340A supplied string parameter is not null-terminated.
341.It Bq Er EINVAL
342A supplied parameter name does not match any known parameters.
343.It Bq Er EINVAL
344One of the
345.Dv JAIL_CREATE
346or
347.Dv JAIL_UPDATE
348flags is not set.
349.It Bq Er ENAMETOOLONG
350A supplied string parameter is longer than allowed.
351.It Bq Er EAGAIN
352There are no jail IDs left.
353.El
354.Pp
355The
356.Fn jail_get
357system call
358will fail if:
359.Bl -tag -width Er
360.It Bq Er EFAULT
361.Fa Iov ,
362or one of the addresses contained within it,
363points to an address outside the allocated address space of the process.
364.It Bq Er ENOENT
365The jail referred to by a
366.Va jid
367or
368.Va name
369parameter does not exist.
370.It Bq Er ENOENT
371The
372.Va lastjid
373parameter is greater than the highest current jail ID.
374.It Bq Er EINVAL
375A supplied parameter is the wrong size.
376.It Bq Er EINVAL
377A supplied parameter name does not match any known parameters.
378.El
379.Pp
380The
381.Fn jail_attach
382and
383.Fn jail_remove
384system calls
385will fail if:
386.Bl -tag -width Er
387.It Bq Er EINVAL
388The jail specified by
389.Fa jid
390does not exist.
391.El
392.Pp
161Further
393Further
162.Fn jail
163calls
394.Fn jail ,
395.Fn jail_set ,
396and
397.Fn jail_attach
398call
164.Xr chroot 2
165internally, so it can fail for all the same reasons.
166Please consult the
167.Xr chroot 2
168manual page for details.
169.Sh SEE ALSO
170.Xr chdir 2 ,
399.Xr chroot 2
400internally, so it can fail for all the same reasons.
401Please consult the
402.Xr chroot 2
403manual page for details.
404.Sh SEE ALSO
405.Xr chdir 2 ,
171.Xr chroot 2
406.Xr chroot 2 ,
407.Xr jail 8
172.Sh HISTORY
173The
174.Fn jail
175system call appeared in
176.Fx 4.0 .
177The
178.Fn jail_attach
179system call appeared in
180.Fx 5.1 .
408.Sh HISTORY
409The
410.Fn jail
411system call appeared in
412.Fx 4.0 .
413The
414.Fn jail_attach
415system call appeared in
416.Fx 5.1 .
417The
418.Fn jail_set ,
419.Fn jail_get ,
420and
421.Fn jail_remove
422system calls appeared in
423.Fx 8.0 .
181.Sh AUTHORS
182The jail feature was written by
183.An Poul-Henning Kamp
184for R&D Associates
185.Dq Li http://www.rndassociates.com/
186who contributed it to
187.Fx .
424.Sh AUTHORS
425The jail feature was written by
426.An Poul-Henning Kamp
427for R&D Associates
428.Dq Li http://www.rndassociates.com/
429who contributed it to
430.Fx .
431.An James Gritton
432added the extensible jail parameters.