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(¶ms[0], "name"); 228jailparam_import(¶ms[0], "foo"); 229jailparam_init(¶ms[1], "host.hostname"); 230jailparam_import(¶ms[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(¶ms[0], "name"); 246jailparam_import(¶ms[0], "foo"); 247jailparam_init(¶ms[1], "host.hostname"); 248jailparam_get(params, 2, 0); 249hostname = jailparam_export(¶ms[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 sysctl 3 , 276.Xr jail 8 277.Sh HISTORY 278The 279.Nm jail 280library first appeared in 281.Fx 8.0 . 282.Sh AUTHORS 283.An James Gritton 284