Next round of fixing all kinds of spelling mistakes.
[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.9 2007/05/17 08:19:00 swildner 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 descendants
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        n_ips;
37         struct sockaddr_storage *ips;
38 };
39 .Ed
40 .Pp
41 .Dq Li version
42 defines the version of the API in use.  It should be set to 1 at this time.
43 .Pp
44 The
45 .Dq Li path
46 pointer should be set to the directory which is to be the root of the
47 prison.
48 .Pp
49 The
50 .Dq Li hostname
51 pointer can be set to the hostname of the prison.  This can be changed
52 from the inside of the prison.
53 .Pp
54 .Dq Li n_ips
55 is the number of IP addresses that are on ips.
56 .Pp
57 The
58 .Dq ips
59 pointer contains the IP addresses assigned to the jail.
60 .Sh PRISON
61 Once a process has been put in a prison, it and its descendants cannot escape
62 the prison.
63 A process can be attached to a prison by calling
64 .Xr jail_attach 2 .
65 .Pp
66 Inside the prison, the concept of "superuser" is very diluted.  In general,
67 it can be assumed that nothing can be mangled from inside a prison which
68 does not exist entirely inside that prison.  For instance the directory
69 tree below
70 .Dq Li path
71 can be manipulated all the ways a root can normally do it, including
72 .Dq Li "rm -rf /*"
73 but new device special nodes cannot be created because they reference
74 shared resources (the device drivers in the kernel).
75 .Pp
76 All IP activity will be forced to happen to/from the IP numbers specified,
77 which should be an alias on one or more of the network interfaces.
78 .Pp
79 It is possible to identify a process as jailed by examining
80 .Dq Li /proc/<pid>/status :
81 it will show a field near the end of the line, either as
82 a single hyphen for a process at large, or the hostname currently
83 set for the prison for jailed processes.
84 .Pp
85 The program
86 .Xr jls 8
87 ca be used to identify all active jails.
88 .Sh RETURN VALUES
89 If successful, jail() returns a non-negative integer, termed the jail
90 identifier (JID). It returns -1 on failure, and sets errno to indicate
91 the error.
92 .Sh ERRORS
93 The
94 .Fn jail
95 system call will fail if:
96 .Bl -tag -width Er
97 .It Bq Er EINVAL
98 The version number of the argument is not correct.
99 .El
100 .Pp
101 Further
102 .Fn jail
103 calls
104 .Xr chroot 2
105 internally, so it can fail for all the same reasons.
106 Please consult the
107 .Xr chroot 2
108 manual page for details.
109 .Sh SEE ALSO
110 .Xr chdir 2 ,
111 .Xr chroot 2 ,
112 .Xr jail_attach 2 ,
113 .Xr jail 8 ,
114 .Xr jexec 8 ,
115 .Xr jls 8
116 .Sh HISTORY
117 The
118 .Fn jail
119 function call appeared in
120 .Fx 4.0 .
121 .Sh AUTHORS
122 The jail feature was written by
123 .An Poul-Henning Kamp
124 for R&D Associates
125 .Dq Li http://www.rndassociates.com/
126 who contributed it to
127 .Fx .