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