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