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