xref: /freebsd/lib/libjail/jail.3 (revision 9c067b844f85a224f0416e6eb46ba3ef82aec5c4)
1.\" Copyright (c) 2009 James Gritton.
2.\" All rights reserved.
3.\"
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.
12.\"
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.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd August 31, 2010
28.Dt JAIL 3
29.Os
30.Sh NAME
31.Nm jail_getid ,
32.Nm jail_getname ,
33.Nm jail_setv ,
34.Nm jail_getv ,
35.Nm jailparam_all ,
36.Nm jailparam_init ,
37.Nm jailparam_import ,
38.Nm jailparam_import_raw ,
39.Nm jailparam_set ,
40.Nm jailparam_get ,
41.Nm jailparam_export ,
42.Nm jailparam_free
43.Nd create and manage system jails
44.Sh LIBRARY
45.Lb libjail
46.Sh SYNOPSIS
47.In sys/param.h
48.In sys/jail.h
49.In jail.h
50.Vt extern char jail_errmsg[] ;
51.Ft int
52.Fn jail_getid "const char *name"
53.Ft char *
54.Fn jail_getname "int jid"
55.Ft int
56.Fn jail_setv "int flags" ...
57.Ft int
58.Fn jail_getv "int flags" ...
59.Ft int
60.Fn jailparam_all "struct jailparam **jpp"
61.Ft int
62.Fn jailparam_init "struct jailparam *jp" "const char *name"
63.Ft int
64.Fn jailparam_import "struct jailparam *jp" "const char *value"
65.Ft int
66.Fn jailparam_import_raw "struct jailparam *jp" "void *value" "size_t valuelen"
67.Ft int
68.Fn jailparam_set "struct jailparam *jp" "unsigned njp" "int flags"
69.Ft int
70.Fn jailparam_get "struct jailparam *jp" "unsigned njp" "int flags"
71.Ft char *
72.Fn jailparam_export "struct jailparam *jp"
73.Ft void
74.Fn jailparam_free "struct jailparam *jp" "unsigned njp"
75.Sh DESCRIPTION
76The
77.Nm jail
78library is an interface to the
79.Xr jail_set 2
80and
81.Xr jail_get 2
82system calls, and the
83.Va security.jail.param
84MIB entries.
85It simplifies the conversion of prison parameters between internal and
86string formats, allowing the setting and querying of prisons without
87knowing the parameter formats.
88.Pp
89The
90.Fn jail_getid
91function returns the JID of the jail identified by
92.Fa name ,
93or \-1 if the jail does not exist.
94.Pp
95The
96.Fn jail_getname
97function returns the name of the jail identified by
98.Fa jid ,
99or
100.Dv NULL
101if the jail does not exist.
102.Pp
103The
104.Fn jail_setv
105function takes a null-terminated list of name and value strings,
106and passes it to
107.Xr jail_set 2 .
108.Pp
109The
110.Fn jail_getv
111function takes a null-terminated list of name and value strings,
112and passes it to
113.Xr jail_get 2 .
114It is the caller's responsibility to ensure that the value strings point
115to buffers large enough to hold the string representation of the
116returned parameters.
117.Pp
118The
119.Fn jailparam_all
120function sets
121.Fa jpp
122to a list of all known jail parameters, and returns the number of
123parameters.
124The list should later be freed with
125.Fn jailparam_free
126and
127.Xr free 3 .
128.Pp
129The
130.Fn jailparam_init
131function clears a parameter record and copies the
132.Fa name
133to it.
134After use, it should be freed with
135.Fn jailparam_free .
136.Pp
137The
138.Fn jailparam_import
139function adds a
140.Fa value
141to a parameter record, converting it from a string to its native form.
142The
143.Fn jailparam_import_raw
144function adds a value without performing any conversion.
145.Pp
146The
147.Fn jailparam_set
148function passes a list of parameters to
149.Xr jail_set 2 .
150The parameters are assumed to have been created with
151.Fn jailparam_init
152and
153.Fn jailparam_import .
154.Pp
155The
156.Fn jailparam_get
157function passes a list of parameters to
158.Xr jail_get 2 .
159The parameters are assumed to have been created with
160.Fn jailparam_init
161or
162.Fn jailparam_list ,
163with one parameter (the key) having been given a value with
164.Fn jailparam_import .
165.Pp
166The
167.Fn jailparam_export
168function returns the string equivalent of a parameter value.
169The returned string should be freed after use.
170.Pp
171The
172.Fn jailparam_free
173function frees the stored names and values in a parameter list.
174If the list itself came from
175.Fn jailparam_all ,
176it should be freed as well.
177.Sh RETURN VALUES
178The
179.Fn jail_getid ,
180.Fn jail_setv ,
181.Fn jail_getv ,
182.Fn jailparam_set
183and
184.Fn jailparam_get
185functions return a JID on success, or \-1 on error.
186.Pp
187The
188.Fn jail_getname
189and
190.Fn jailparam_export
191functions return a dynamically allocated string on success, or
192.Dv NULL
193on error.
194.Pp
195The
196.Fn jailparam_all
197function returns the number of parameters on success, or \-1 on error.
198.Pp
199The
200.Fn jailparam_init ,
201.Fn jailparam_import
202and
203.Fn jailparam_import_raw
204functions return 0 on success, or \-1 on error.
205.Pp
206Whenever an error is returned,
207.Va errno
208is set, and the global string
209.Va jail_errmsg
210contains a description of the error, possibly from
211.Xr jail_set 2
212or
213.Xr jail_get 2 .
214.Sh EXAMPLES
215Set the hostname of jail
216.Dq foo
217to
218.Dq foo.bar :
219.Bd -literal -offset indent
220jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar",
221    NULL);
222.Ed
223.Pp
224OR:
225.Bd -literal -offset indent
226struct jailparam params[2];
227jailparam_init(&params[0], "name");
228jailparam_import(&params[0], "foo");
229jailparam_init(&params[1], "host.hostname");
230jailparam_import(&params[1], "foo.bar");
231jailparam_set(params, 2, JAIL_UPDATE);
232jailparam_free(params, 2);
233.Ed
234.Pp
235Retrieve the hostname of jail
236.Dq foo :
237.Bd -literal -offset indent
238char hostname[MAXHOSTNAMELEN];
239jail_getv(0, "name", "foo", "host.hostname", hostname, NULL);
240.Ed
241.Pp
242OR:
243.Bd -literal -offset indent
244struct jailparam params[2];
245jailparam_init(&params[0], "name");
246jailparam_import(&params[0], "foo");
247jailparam_init(&params[1], "host.hostname");
248jailparam_get(params, 2, 0);
249hostname = jailparam_export(&params[1]);
250jailparam_free(params, 2);
251\&...
252free(hostname);
253.Ed
254.Sh ERRORS
255The
256.Nm jail
257functions may return errors from
258.Xr jail_set 2 ,
259.Xr jail_get 2 ,
260.Xr malloc 3
261or
262.Xr sysctl 3 .
263In addition, the following errors are possible:
264.Bl -tag -width Er
265.It Bq Er EINVAL
266A parameter value cannot be converted from the passed string to its
267internal form.
268.It Bq Er ENOENT
269The named parameter does not exist.
270.It Bq Er ENOENT
271A parameter is of an unknown type.
272.El
273.Sh SEE ALSO
274.Xr jail 2 ,
275.Xr jail 3lua ,
276.Xr sysctl 3 ,
277.Xr jail 8
278.Sh HISTORY
279The
280.Nm jail
281library first appeared in
282.Fx 8.0 .
283.Sh AUTHORS
284.An James Gritton
285