xref: /freebsd/lib/libsys/jail.2 (revision 59c8e88e72633afbc47a4ace0d2170d00d51f7dc)
1.\" Copyright (c) 1999 Poul-Henning Kamp.
2.\" Copyright (c) 2009 James Gritton.
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
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
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
24.\" SUCH DAMAGE.
25.\"
26.Dd November 29, 2023
27.Dt JAIL 2
28.Os
29.Sh NAME
30.Nm jail ,
31.Nm jail_get ,
32.Nm jail_set ,
33.Nm jail_remove ,
34.Nm jail_attach
35.Nd create and manage system jails
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In sys/param.h
40.In sys/jail.h
41.Ft int
42.Fn jail "struct jail *jail"
43.Ft int
44.Fn jail_attach "int jid"
45.Ft int
46.Fn jail_remove "int jid"
47.In sys/uio.h
48.Ft int
49.Fn jail_get "struct iovec *iov" "u_int niov" "int flags"
50.Ft int
51.Fn jail_set "struct iovec *iov" "u_int niov" "int flags"
52.Sh DESCRIPTION
53The
54.Fn jail
55system call sets up a jail and locks the current process in it.
56.Pp
57The argument is a pointer to a structure describing the prison:
58.Bd -literal -offset indent
59struct jail {
60	uint32_t	version;
61	char		*path;
62	char		*hostname;
63	char		*jailname;
64	unsigned int	ip4s;
65	unsigned int	ip6s;
66	struct in_addr	*ip4;
67	struct in6_addr	*ip6;
68};
69.Ed
70.Pp
71.Dq Li version
72defines the version of the API in use.
73.Dv JAIL_API_VERSION
74is defined for the current version.
75.Pp
76The
77.Dq Li path
78pointer should be set to the directory which is to be the root of the
79prison.
80.Pp
81The
82.Dq Li hostname
83pointer can be set to the hostname of the prison.
84This can be changed
85from the inside of the prison.
86.Pp
87The
88.Dq Li jailname
89pointer is an optional name that can be assigned to the jail
90for example for management purposes.
91.Pp
92The
93.Dq Li ip4s
94and
95.Dq Li ip6s
96give the numbers of IPv4 and IPv6 addresses that will be passed
97via their respective pointers.
98.Pp
99The
100.Dq Li ip4
101and
102.Dq Li ip6
103pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
104the prison, or NULL if none.
105IPv4 addresses must be in network byte order.
106.Pp
107This is equivalent to, and deprecated in favor of, the
108.Fn jail_set
109system call (see below), with the parameters
110.Va path ,
111.Va host.hostname ,
112.Va name ,
113.Va ip4.addr ,
114and
115.Va ip6.addr ,
116and with the
117.Dv JAIL_ATTACH
118flag.
119.Pp
120The
121.Fn jail_set
122system call creates a new jail, or modifies an existing one, and optionally
123locks the current process in it.
124Jail parameters are passed as an array of name-value pairs in the array
125.Fa iov ,
126containing
127.Fa niov
128elements.
129Parameter names are a null-terminated string, and values may be strings,
130integers, or other arbitrary data.
131Some parameters are boolean, and do not have a value (their length is zero)
132but are set by the name alone with or without a
133.Dq no
134prefix, e.g.
135.Va persist
136or
137.Va nopersist .
138Any parameters not set will be given default values, generally based on
139the current environment.
140.Pp
141Jails have a set of core parameters, and modules can add their own jail
142parameters.
143The current set of available parameters, and their formats, can be
144retrieved via the
145.Va security.jail.param
146sysctl MIB entry.
147Notable parameters include those mentioned in the
148.Fn jail
149description above, as well as
150.Va jid
151and
152.Va name ,
153which identify the jail being created or modified.
154See
155.Xr jail 8
156for more information on the core jail parameters.
157.Pp
158The
159.Fa flags
160arguments consists of one or more of the following flags:
161.Bl -tag -width indent
162.It Dv JAIL_CREATE
163Create a new jail.
164If a
165.Va jid
166or
167.Va name
168parameters exists, they must not refer to an existing jail.
169.It Dv JAIL_UPDATE
170Modify an existing jail.
171One of the
172.Va jid
173or
174.Va name
175parameters must exist, and must refer to an existing jail.
176If both
177.Dv JAIL_CREATE
178and
179.Dv JAIL_UPDATE
180are set, a jail will be created if it does not yet exist, and modified if it
181does exist.
182.It Dv JAIL_ATTACH
183In addition to creating or modifying the jail, attach the current process to
184it, as with the
185.Fn jail_attach
186system call.
187.It Dv JAIL_DYING
188This is deprecated in
189.Fn jail_set
190and has no effect.
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
228system call attaches the current process to an existing jail,
229identified by
230.Fa jid .
231It changes the process's root and current directories to the jail's
232.Va path
233directory.
234.Pp
235The
236.Fn jail_remove
237system call removes the jail identified by
238.Fa jid .
239It will kill all processes belonging to the jail, and remove any children
240of that jail.
241.Sh RETURN VALUES
242If successful,
243.Fn jail ,
244.Fn jail_set ,
245and
246.Fn jail_get
247return a non-negative integer, termed the jail identifier (JID).
248They return \-1 on failure, and set
249.Va errno
250to indicate the error.
251.Pp
252.Rv -std jail_attach jail_remove
253.Sh ERRORS
254The
255.Fn jail
256system call
257will fail if:
258.Bl -tag -width Er
259.It Bq Er EPERM
260This process is not allowed to create a jail, either because it is not
261the super-user, or because it would exceed the jail's
262.Va children.max
263limit.
264.It Bq Er EFAULT
265.Fa jail
266points to an address outside the allocated address space of the process.
267.It Bq Er EINVAL
268The version number of the argument is not correct.
269.It Bq Er EAGAIN
270No free JID could be found.
271.El
272.Pp
273The
274.Fn jail_set
275system call
276will fail if:
277.Bl -tag -width Er
278.It Bq Er EPERM
279This process is not allowed to create a jail, either because it is not
280the super-user, or because it would exceed the jail's
281.Va children.max
282limit.
283.It Bq Er EPERM
284A jail parameter was set to a less restrictive value then the current
285environment.
286.It Bq Er EFAULT
287.Fa Iov ,
288or one of the addresses contained within it,
289points to an address outside the allocated address space of the process.
290.It Bq Er ENOENT
291The jail referred to by a
292.Va jid
293or
294.Va name
295parameter does not exist, and the
296.Dv JAIL_CREATE
297flag is not set.
298.It Bq Er ENOENT
299The jail referred to by a
300.Va jid
301is not accessible by the process, because the process is in a different
302jail.
303.It Bq Er EEXIST
304The jail referred to by a
305.Va jid
306or
307.Va name
308parameter exists, and the
309.Dv JAIL_UPDATE
310flag is not set.
311.It Bq Er EINVAL
312A supplied parameter is the wrong size.
313.It Bq Er EINVAL
314A supplied parameter is out of range.
315.It Bq Er EINVAL
316A supplied string parameter is not null-terminated.
317.It Bq Er EINVAL
318A supplied parameter name does not match any known parameters.
319.It Bq Er EINVAL
320One of the
321.Dv JAIL_CREATE
322or
323.Dv JAIL_UPDATE
324flags is not set.
325.It Bq Er ENAMETOOLONG
326A supplied string parameter is longer than allowed.
327.It Bq Er EAGAIN
328There are no jail IDs left.
329.El
330.Pp
331The
332.Fn jail_get
333system call
334will fail if:
335.Bl -tag -width Er
336.It Bq Er EFAULT
337.Fa Iov ,
338or one of the addresses contained within it,
339points to an address outside the allocated address space of the process.
340.It Bq Er ENOENT
341The jail referred to by a
342.Va jid
343or
344.Va name
345parameter does not exist.
346.It Bq Er ENOENT
347The jail referred to by a
348.Va jid
349is not accessible by the process, because the process is in a different
350jail.
351.It Bq Er ENOENT
352The
353.Va lastjid
354parameter is greater than the highest current jail ID.
355.It Bq Er EINVAL
356A supplied parameter is the wrong size.
357.It Bq Er EINVAL
358A supplied parameter name does not match any known parameters.
359.El
360.Pp
361The
362.Fn jail_attach
363and
364.Fn jail_remove
365system calls
366will fail if:
367.Bl -tag -width Er
368.It Bq Er EPERM
369A user other than the super-user attempted to attach to or remove a jail.
370.It Bq Er EINVAL
371The jail specified by
372.Fa jid
373does not exist.
374.El
375.Pp
376Further
377.Fn jail ,
378.Fn jail_set ,
379and
380.Fn jail_attach
381call
382.Xr chroot 2
383internally, so they can fail for all the same reasons.
384Please consult the
385.Xr chroot 2
386manual page for details.
387.Sh SEE ALSO
388.Xr chdir 2 ,
389.Xr chroot 2 ,
390.Xr jail 8
391.Sh HISTORY
392The
393.Fn jail
394system call appeared in
395.Fx 4.0 .
396The
397.Fn jail_attach
398system call appeared in
399.Fx 5.1 .
400The
401.Fn jail_set ,
402.Fn jail_get ,
403and
404.Fn jail_remove
405system calls appeared in
406.Fx 8.0 .
407.Sh AUTHORS
408The jail feature was written by
409.An Poul-Henning Kamp
410for R&D Associates
411who contributed it to
412.Fx .
413.An James Gritton
414added the extensible jail parameters and hierarchical jails.
415