Fix some groff warnings.
[dragonfly.git] / lib / libc / sys / jail.2
CommitLineData
984263bc
MD
1.\"
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.\"----------------------------------------------------------------------------
8.\"
9.\"$FreeBSD: src/lib/libc/sys/jail.2,v 1.10.2.10 2002/12/12 05:26:38 trhodes Exp $
cb65615c 10.\"$DragonFly: src/lib/libc/sys/jail.2,v 1.4 2005/03/08 20:29:55 swildner Exp $
984263bc
MD
11.\"
12.Dd April 28, 1999
13.Dt JAIL 2
14.Os
15.Sh NAME
16.Nm jail
17.Nd imprison current process and future decendants
18.Sh LIBRARY
19.Lb libc
20.Sh SYNOPSIS
21.In sys/types.h
22.In sys/jail.h
23.Ft int
24.Fn jail "struct jail *jail"
25.Sh DESCRIPTION
26The
27.Nm
28system call sets up a jail and locks the current process in it.
29.Pp
30The argument is a pointer to a structure describing the prison:
31.Bd -literal -offset indent
32struct jail {
b40e316c
JS
33 uint32_t version;
34 char *path;
35 char *hostname;
36 uint32_t ip_number;
984263bc
MD
37};
38.Ed
39.Pp
40.Dq Li version
41defines the version of the API in use. It should be set to zero at this time.
42.Pp
43The
44.Dq Li path
45pointer should be set to the directory which is to be the root of the
46prison.
47.Pp
48The
49.Dq Li hostname
50pointer can be set to the hostname of the prison. This can be changed
51from the inside of the prison.
52.Pp
53The
54.Dq Li ip_number
55can be set to the IP number assigned to the prison.
b40e316c 56.Sh PRISON
984263bc 57Once a process has been put in a prison, it and its decendants cannot escape
b40e316c
JS
58the prison.
59A process can be attached to a prison by calling
60.Xr jail_attach 2 .
984263bc
MD
61.Pp
62Inside the prison, the concept of "superuser" is very diluted. In general,
63it can be assumed that nothing can be mangled from inside a prison which
64does not exist entirely inside that prison. For instance the directory
65tree below
66.Dq Li path
67can be manipulated all the ways a root can normally do it, including
68.Dq Li "rm -rf /*"
69but new device special nodes cannot be created because they reference
70shared resources (the device drivers in the kernel).
71.Pp
72All IP activity will be forced to happen to/from the IP number specified,
73which should be an alias on one of the network interfaces.
74.Pp
75It is possible to identify a process as jailed by examining
76.Dq Li /proc/<pid>/status :
77it will show a field near the end of the line, either as
78a single hyphen for a process at large, or the hostname currently
79set for the prison for jailed processes.
cb65615c 80.Pp
b40e316c
JS
81The program
82.Xr jls 8
83ca be used to identify all active jails.
984263bc
MD
84.Sh ERRORS
85.Fn jail
86will fail if:
87.Bl -tag -width Er
88.It Bq Er EINVAL
89The version number of the argument is not correct.
90.El
91.Pp
92Further
93.Fn jail
94calls
95.Xr chroot 2
96internally, so it can fail for all the same reasons.
97Please consult the
98.Xr chroot 2
99manual page for details.
100.Sh SEE ALSO
101.Xr chdir 2 ,
b40e316c
JS
102.Xr chroot 2 ,
103.Xr jail 8 ,
104.Xr jail_attach 2 ,
105.Xr jexec 8 ,
106.Xr jls 8
984263bc
MD
107.Sh HISTORY
108The
109.Fn jail
110function call appeared in
111.Fx 4.0 .
112.Sh AUTHORS
113The jail feature was written by
114.An Poul-Henning Kamp
115for R&D Associates
116.Dq Li http://www.rndassociates.com/
117who contributed it to
118.Fx .