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 June 24, 2009 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.Ar 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.Ar jid , 99or NULL if the jail does not exist. 100.Pp 101The 102.Fn jail_setv 103function takes a null-terminated list of name and value strings, 104and passes it to 105.Xr jail_set 2 . 106.Pp 107The 108.Fn jail_getv 109function takes a null-terminated list of name and value strings, 110and passes it to 111.Xr jail_get 2 . 112It is the caller's responsibility to ensure that the value strings point 113to buffers large enough to hold the string representation of the 114returned parameters. 115.Pp 116The 117.Fn jailparam_all 118function sets 119.Ar jpp 120to a list of all known jail parameters, and returns the number of 121parameters. 122The list should later be freed with 123.Fn jailparam_free 124and 125.Xr free 3 . 126.Pp 127The 128.Fn jailparam_init 129function clears a parameter record and copies the 130.Ar name 131to it. After use, it should be freed with 132.Fn jailparam_free . 133.Pp 134The 135.Fn jailparam_import 136function adds a 137.Ar value 138to a parameter record, converting it from a string to its native form. 139The 140.Fn jailparam_import_raw 141function adds a value without performing any conversion. 142.Pp 143The 144.Fn jailparam_set 145function passes a list of parameters to 146.Xr jail_set 2 . 147The parameters are assumed to have been created with 148.Fn jailparam_init 149and 150.Fn jailparam_import . 151.Pp 152The 153.Fn jailparam_get 154function function passes a list of parameters to 155.Xr jail_get 2 . 156The parameters are assumed to have been created with 157.Fn jailparam_init 158or 159.Fn jailparam_list , 160with one parameter (the key) having been given a value with 161.Fn jailparam_import . 162.Pp 163The 164.Fn jailparam_export 165function returns the string equivalent of a parameter value. 166The returned string should freed after use. 167.Pp 168The 169.Fn jailparam_free 170function frees the stored names and values in a parameter list. 171If the list itself came from 172.Fn jailparam_all , 173it should be freed as well. 174.Sh EXAMPLES 175Set the hostname of jail 176.Dq foo 177to 178.Dq foo.bar : 179.Bd -literal -offset indent 180jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar", 181 NULL); 182.Ed 183.Pp 184OR: 185.Bd -literal -offset indent 186struct jailparam params[2]; 187jailparam_init(¶ms[0], "name"); 188jailparam_import(¶ms[0], "foo"); 189jailparam_init(¶ms[1], "host.hostname"); 190jailparam_import(¶ms[1], "foo.bar"); 191jailparam_set(params, 2, JAIL_UPDATE); 192jailparam_free(params, 2); 193.Ed 194.Pp 195Retrieve the hostname of jail 196.Dq foo : 197.Bd -literal -offset indent 198char hostname[MAXHOSTNAMELEN]; 199jail_getv(0, "name", "foo", "host.hostname", hostname, NULL); 200.Ed 201.Pp 202OR: 203.Bd -literal -offset indent 204struct jailparam params[2]; 205jailparam_init(¶ms[0], "name"); 206jailparam_import(¶ms[0], "foo"); 207jailparam_init(¶ms[1], "host.hostname"); 208jailparam_get(params, 2, 0); 209hostname = jailparam_export(¶ms[1]); 210jailparam_free(params, 2); 211.Ed 212.Sh RETURN VALUES 213The 214.Fn jail_getid , 215.Fn jail_setv , 216.Fn jail_getv , 217.Fn jailparam_set 218and 219.Fn jailparam_get 220functions return a JID on success, or \-1 on error. 221.Pp 222The 223.Fn jail_getname 224and 225.Fn jailparam_export 226functions return a dynamically allocated string on success, or NULL on error. 227.Pp 228The 229.Fn jailparam_all 230function returns the number of parameters on success, or \-1 on error. 231.Pp 232The 233.Fn jailparam_init , 234.Fn jailparam_import 235and 236.Fn jailparam_import_raw 237functions return 0 on success, or \-1 on error. 238.Pp 239Whenever an error is returned, 240.Va errno 241is set, and the global string 242.Va jail_errmsg 243contains a descrption of the error, possibly from 244.Xr jail_set 2 245or 246.Xr jail_get 2 . 247.Sh ERRORS 248The 249.Nm jail 250functions may return errors from 251.Xr jail_set 2 , 252.Xr jail_get 2 , 253.Xr malloc 3 254or 255.Xr sysctl 3 . 256In addition, the following errors are possible: 257.Bl -tag -width Er 258.It Bq Er EINVAL 259A prameter value cannot be convert from the passed string to its 260internal form. 261.It Bq Er ENOENT 262The named parameter does not exist. 263.It Bq Er ENOENT 264A parameter is of an unknown type. 265.Sh SEE ALSO 266.Xr jail 2 , 267.Xr jail 8 , 268.Xr sysctl 3 269.Sh HISTORY 270The 271.Nm jail 272library first appeared in 273.Fx 8.0 . 274.Sh AUTHORS 275.An James Gritton 276