lib/libjail/jail.3

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