lib/flua/libjail/jail.3lua

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2020, Ryan Moeller <freqlabs@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd October 24, 2020
  30 .Dt JAIL 3lua
  31 .Os
  32 .Sh NAME
  33 .Nm getid ,
  34 .Nm getname ,
  35 .Nm allparams ,
  36 .Nm getparams ,
  37 .Nm setparams ,
  38 .Nm CREATE ,
  39 .Nm UPDATE ,
  40 .Nm ATTACH ,
  41 .Nm DYING
  42 .Nd Lua binding to
  43 .Xr jail 3
  44 .Sh SYNOPSIS
  45 .Bd -literal
  46 local jail = require('jail')
  47 .Ed
  48 .Pp
  49 .Bl -tag -width XXXX -compact
  50 .It Dv jid, err = jail.getid(name)
  51 .It Dv name, err = jail.getname(jid)
  52 .It Dv params, err = jail.allparams()
  53 .It Dv jid, res = jail.getparams(jid|name, params [, flags ] )
  54 .It Dv jid, err = jail.setparams(jid|name, params, flags )
  55 .It Dv jail.CREATE
  56 .It Dv jail.UPDATE
  57 .It Dv jail.ATTACH
  58 .It Dv jail.DYING
  59 .El
  60 .Sh DESCRIPTION
  61 The
  62 .Nm jail
  63 module is a binding to the
  64 .Xr jail 3
  65 library.
  66 It provides a string-oriented interface for the
  67 .Xr jail_get 2
  68 and
  69 .Xr jail_set 2
  70 system calls.
  71 .Bl -tag -width XXXX
  72 .It Dv jid, err = jail.getid(name)
  73 Get the jail identifier
  74 .Pq jid
  75 as an integer.
  76 .Fa name
  77 is the name of a jail or a jid in the form of a string.
  78 .It Dv name, err = jail.getname(jid)
  79 Get the name of a jail as a string for the given
  80 .Fa jid
  81 .Pq an integer .
  82 .It Dv params, err = jail.allparams()
  83 Get a list of all supported parameter names
  84 .Pq as strings .
  85 See
  86 .Xr jail 8
  87 for descriptions of the core jail parameters.
  88 .It Dv jid, res = jail.getparams(jid|name, params [, flags ] )
  89 Get a table of the requested parameters for the given jail.
  90 .Nm jid|name
  91 can either be the jid as an integer or the jid or name as a string.
  92 .Nm params
  93 is a list of parameter names.
  94 .Nm flags
  95 is an optional integer representing the flag bits to apply for the operation.
  96 See the list of flags below.
  97 Only the
  98 .Dv DYING
  99 flag is valid to set.
 100 .It Dv jid, err = jail.setparams(jid|name, params [, flags ] )
 101 Set parameters for a given jail.
 102 This is used to create, update, attach to, or destroy a jail.
 103 .Nm jid|name
 104 can either be the jid as an integer or the jid or name as a string.
 105 .Nm params
 106 is a table of parameters to apply to the jail, where each key in the table
 107 is a parameter name as a string and each value is a string that will be
 108 converted to the internal value type by
 109 .Xr jailparam_import 3 .
 110 .Nm flags
 111 is an optional integer representing the flag bits to apply for the operation.
 112 See the list of flags below.
 113 .El
 114 .Pp
 115 The
 116 .Nm flags
 117 arguments are an integer bitwise-or combination of one or more of the following
 118 flags:
 119 .Bl -tag -width XXXX
 120 .It Dv jail.CREATE
 121 Used with
 122 .Fn setparams
 123 to create a new jail.
 124 The jail must not already exist, unless combined with
 125 .Dv UPDATE .
 126 .It Dv jail.UPDATE
 127 Used with
 128 .Fn setparams
 129 to modify an existing jail.
 130 The jail must already exist, unless combined with
 131 .Dv CREATE .
 132 .It Dv jail.ATTACH
 133 Used with
 134 .Fn setparams
 135 in combination with
 136 .Dv CREATE
 137 or
 138 .Dv UPDATE
 139 to attach the current process to a jail.
 140 .It Dv jail.DYING
 141 Allow operating on a jail that is in the process of being removed.
 142 .El
 143 .Sh RETURN VALUES
 144 The
 145 .Fn getid
 146 and
 147 .Fn setparams
 148 functions return a jail identifier integer on success, or
 149 .Dv nil
 150 and an error message string if an error occurred.
 151 .Pp
 152 The
 153 .Fn getname
 154 function returns a jail name string on success, or
 155 .Dv nil
 156 and an error message string if an error occurred.
 157 .Pp
 158 The
 159 .Fn allparams
 160 function returns a list of parameter name strings on success, or
 161 .Dv nil
 162 and an error message string if an error occurred.
 163 .Pp
 164 The
 165 .Fn getparams
 166 function returns a jail identifier integer and a table of jail parameters
 167 with parameter name strings as keys and strings for values on success, or
 168 .Dv nil
 169 and an error message string if an error occurred.
 170 .Sh EXAMPLES
 171 Set the hostname of jail
 172 .Dq foo
 173 to
 174 .Dq foo.bar :
 175 .Bd -literal -offset indent
 176 local jail = require('jail')
 177
 178 jid, err = jail.setparams("foo", {["host.hostname"]="foo.bar"},
 179     jail.UPDATE)
 180 if not jid then
 181     error(err)
 182 end
 183 .Ed
 184 .Pp
 185 Retrieve the hostname of jail
 186 .Dq foo :
 187 .Bd -literal -offset indent
 188 local jail = require('jail')
 189
 190 jid, res = jail.getparams("foo", {"host.hostname"})
 191 if not jid then
 192     error(res)
 193 end
 194 print(res["host.hostname"])
 195 .Ed
 196 .Sh SEE ALSO
 197 .Xr jail 2 ,
 198 .Xr jail 3 ,
 199 .Xr jail 8
 200 .Sh HISTORY
 201 The
 202 .Nm jail
 203 Lua module for flua first appeared in
 204 .Fx 13.0 .
 205 .Sh AUTHORS
 206 .An Ryan Moeller ,
 207 with inspiration from
 208 .Nx
 209 gpio(3lua), by
 210 .An Mark Balmer .