2.\" ----------------------------------------------------------------------------
3.\" "THE BEER-WARE LICENSE" (Revision 42):
4.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you
5.\" can do whatever you want with this stuff. If we meet some day, and you think
6.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
7.\" ----------------------------------------------------------------------------
| 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
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
|
9.\" $FreeBSD: head/lib/libc/sys/jail.2 186834 2009-01-06 18:10:17Z bz $
| 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
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.
|
11.Dd January 6, 2009
12.Dt JAIL 2
13.Os
14.Sh NAME
15.Nm jail , jail_attach
16.Nd imprison current process and future descendants
17.Sh LIBRARY
18.Lb libc
19.Sh SYNOPSIS
20.In sys/param.h
21.In sys/jail.h
22.Ft int
23.Fn jail "struct jail *jail"
24.Ft int
25.Fn jail_attach "int jid"
26.Sh DESCRIPTION
27The
28.Fn jail
29system call sets up a jail and locks the current process in it.
30.Pp
31The argument is a pointer to a structure describing the prison:
32.Bd -literal -offset indent
33struct jail {
34 u_int32_t version;
35 char *path;
36 char *hostname;
37 char *jailname;
38 unsigned int ip4s;
39 unsigned int ip6s;
40 struct in_addr *ip4;
41 struct in6_addr *ip6;
42};
43.Ed
44.Pp
45.Dq Li version
46defines the version of the API in use.
47.Dv JAIL_API_VERSION
48is defined for the current version.
49.Pp
50The
51.Dq Li path
52pointer should be set to the directory which is to be the root of the
53prison.
54.Pp
55The
56.Dq Li hostname
57pointer can be set to the hostname of the prison.
58This can be changed
59from the inside of the prison.
60.Pp
61The
62.Dq Li jailname
63pointer is an optional name that can be assigned to the jail
64for example for managment purposes.
65.Pp
66The
67.Dq Li ip4s
68and
69.Dq Li ip6s
70give the numbers of IPv4 and IPv6 addresses that will be passed
71via their respective pointers.
72.Pp
73The
74.Dq Li ip4
75and
76.Dq Li ip6
77pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to
78the prison, or NULL if none.
79IPv4 addresses must be in network byte order.
80.Pp
81The
82.Fn jail_attach
83system call attaches the current process to an existing jail,
84identified by
85.Fa jid .
86.Sh RETURN VALUES
87If successful,
88.Fn jail
89returns a non-negative integer, termed the jail identifier (JID).
90It returns \-1 on failure, and sets
91.Va errno
92to indicate the error.
93.Pp
94.Rv -std jail_attach
95.Sh PRISON?
96Once a process has been put in a prison, it and its descendants cannot escape
97the prison.
98.Pp
99Inside the prison, the concept of
100.Dq superuser
101is very diluted.
102In general,
103it can be assumed that nothing can be mangled from inside a prison which
104does not exist entirely inside that prison.
105For instance the directory
106tree below
107.Dq Li path
108can be manipulated all the ways a root can normally do it, including
109.Dq Li "rm -rf /*"
110but new device special nodes cannot be created because they reference
111shared resources (the device drivers in the kernel).
112The effective
113.Dq securelevel
114for a process is the greater of the global
115.Dq securelevel
116or, if present, the per-jail
117.Dq securelevel .
118.Pp
119All IP activity will be forced to happen to/from the IP number specified,
120which should be an alias on one of the network interfaces.
121All connections to/from the loopback address
122.Pf ( Li 127.0.0.1
123for IPv4,
124.Li ::1
125for IPv6) will be changed to be to/from the primary address
126of the jail for the given address family.
127.Pp
128It is possible to identify a process as jailed by examining
129.Dq Li /proc/<pid>/status :
130it will show a field near the end of the line, either as
131a single hyphen for a process at large, or the hostname currently
132set for the prison for jailed processes.
133.Sh ERRORS
134The
135.Fn jail
136system call
137will fail if:
138.Bl -tag -width Er
139.It Bq Er EINVAL
140The version number of the argument is not correct.
141.It Bq Er EAGAIN
142No free JID could be found.
143.El
144.Pp
145Further
146.Fn jail
147calls
148.Xr chroot 2
149internally, so it can fail for all the same reasons.
150Please consult the
151.Xr chroot 2
152manual page for details.
153.Sh SEE ALSO
154.Xr chdir 2 ,
155.Xr chroot 2
156.Sh HISTORY
157The
158.Fn jail
159system call appeared in
160.Fx 4.0 .
161The
162.Fn jail_attach
163system call appeared in
164.Fx 5.1 .
165.Sh AUTHORS
166The jail feature was written by
167.An Poul-Henning Kamp
168for R&D Associates
169.Dq Li http://www.rndassociates.com/
170who contributed it to
171.Fx .
| 27.Dd January 6, 2009
28.Dt JAIL 2
29.Os
30.Sh NAME
31.Nm jail , jail_attach
32.Nd imprison current process and future descendants
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"
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 {
50 u_int32_t version;
51 char *path;
52 char *hostname;
53 char *jailname;
54 unsigned int ip4s;
55 unsigned int ip6s;
56 struct in_addr *ip4;
57 struct in6_addr *ip6;
58};
59.Ed
60.Pp
61.Dq Li version
62defines the version of the API in use.
63.Dv JAIL_API_VERSION
64is defined for the current version.
65.Pp
66The
67.Dq Li path
68pointer should be set to the directory which is to be the root of the
69prison.
70.Pp
71The
72.Dq Li hostname
73pointer can be set to the hostname of the prison.
74This can be changed
75from the inside of the prison.
76.Pp
77The
78.Dq Li jailname
79pointer is an optional name that can be assigned to the jail
80for example for managment purposes.
81.Pp
82The
83.Dq Li ip4s
84and
85.Dq Li ip6s
86give the numbers of IPv4 and IPv6 addresses that will be passed
87via their respective pointers.
88.Pp
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
97The
98.Fn jail_attach
99system call attaches the current process to an existing jail,
100identified by
101.Fa jid .
102.Sh RETURN VALUES
103If successful,
104.Fn jail
105returns a non-negative integer, termed the jail identifier (JID).
106It returns \-1 on failure, and sets
107.Va errno
108to indicate the error.
109.Pp
110.Rv -std jail_attach
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,
119it can be assumed that nothing can be mangled from inside a prison which
120does not exist entirely inside that prison.
121For instance the directory
122tree below
123.Dq Li path
124can be manipulated all the ways a root can normally do it, including
125.Dq Li "rm -rf /*"
126but new device special nodes cannot be created because they reference
127shared resources (the device drivers in the kernel).
128The effective
129.Dq securelevel
130for a process is the greater of the global
131.Dq securelevel
132or, if present, the per-jail
133.Dq securelevel .
134.Pp
135All IP activity will be forced to happen to/from the IP number specified,
136which should be an alias on one of the network interfaces.
137All connections to/from the loopback address
138.Pf ( Li 127.0.0.1
139for IPv4,
140.Li ::1
141for IPv6) will be changed to be to/from the primary address
142of the jail for the given address family.
143.Pp
144It is possible to identify a process as jailed by examining
145.Dq Li /proc/<pid>/status :
146it will show a field near the end of the line, either as
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
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
161Further
162.Fn jail
163calls
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 ,
171.Xr chroot 2
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 .
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 .
|