man/man8/zfs-program.8

   1 .\" This file and its contents are supplied under the terms of the
   2 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   3 .\" You may only use this file in accordance with the terms of version
   4 .\" 1.0 of the CDDL.
   5 .\"
   6 .\" A full copy of the text of the CDDL should have accompanied this
   7 .\" source.  A copy of the CDDL is also available via the Internet at
   8 .\" http://www.illumos.org/license/CDDL.
   9 .\"
  10 .\"
  11 .\" Copyright (c) 2016 by Delphix. All Rights Reserved.
  12 .\"
  13 .Dd January 21, 2016
  14 .Dt ZFS-PROGRAM 8
  15 .Os
  16 .Sh NAME
  17 .Nm zfs program
  18 .Nd executes ZFS channel programs
  19 .Sh SYNOPSIS
  20 .Cm zfs program
  21 .Op Fl t Ar instruction-limit
  22 .Op Fl m Ar memory-limit
  23 .Ar pool
  24 .Ar script
  25 .\".Op Ar optional arguments to channel program
  26 .Sh DESCRIPTION
  27 The ZFS channel program interface allows ZFS administrative operations to be
  28 run programmatically as a Lua script.
  29 The entire script is executed atomically, with no other administrative
  30 operations taking effect concurrently.
  31 A library of ZFS calls is made available to channel program scripts.
  32 Channel programs may only be run with root privileges.
  33 .Pp
  34 A modified version of the Lua 5.2 interpreter is used to run channel program
  35 scripts.
  36 The Lua 5.2 manual can be found at:
  37 .Bd -centered -offset indent
  38 .Lk http://www.lua.org/manual/5.2/
  39 .Ed
  40 .Pp
  41 The channel program given by
  42 .Ar script
  43 will be run on
  44 .Ar pool ,
  45 and any attempts to access or modify other pools will cause an error.
  46 .Sh OPTIONS
  47 .Bl -tag -width "-t"
  48 .It Fl t Ar instruction-limit
  49 Execution time limit, in number of Lua instructions to execute.
  50 If a channel program executes more than the specified number of instructions,
  51 it will be stopped and an error will be returned.
  52 The default limit is 10 million instructions, and it can be set to a maximum of
  53 100 million instructions.
  54 .It Fl m Ar memory-limit
  55 Memory limit, in bytes.
  56 If a channel program attempts to allocate more memory than the given limit, it
  57 will be stopped and an error returned.
  58 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
  59 .El
  60 .Pp
  61 All remaining argument strings will be passed directly to the Lua script as
  62 described in the
  63 .Sx LUA INTERFACE
  64 section below.
  65 .Sh LUA INTERFACE
  66 A channel program can be invoked either from the command line, or via a library
  67 call to
  68 .Fn lzc_channel_program .
  69 .Ss Arguments
  70 Arguments passed to the channel program are converted to a Lua table.
  71 If invoked from the command line, extra arguments to the Lua script will be
  72 accessible as an array stored in the argument table with the key 'argv':
  73 .Bd -literal -offset indent
  74 args = ...
  75 argv = args["argv"]
  76 -- argv == {1="arg1", 2="arg2", ...}
  77 .Ed
  78 .Pp
  79 If invoked from the libZFS interface, an arbitrary argument list can be
  80 passed to the channel program, which is accessible via the same
  81 "..." syntax in Lua:
  82 .Bd -literal -offset indent
  83 args = ...
  84 -- args == {"foo"="bar", "baz"={...}, ...}
  85 .Ed
  86 .Pp
  87 Note that because Lua arrays are 1-indexed, arrays passed to Lua from the
  88 libZFS interface will have their indices incremented by 1.
  89 That is, the element
  90 in
  91 .Va arr[0]
  92 in a C array passed to a channel program will be stored in
  93 .Va arr[1]
  94 when accessed from Lua.
  95 .Ss Return Values
  96 Lua return statements take the form:
  97 .Bd -literal -offset indent
  98 return ret0, ret1, ret2, ...
  99 .Ed
 100 .Pp
 101 Return statements returning multiple values are permitted internally in a
 102 channel program script, but attempting to return more than one value from the
 103 top level of the channel program is not permitted and will throw an error.
 104 However, tables containing multiple values can still be returned.
 105 If invoked from the command line, a return statement:
 106 .Bd -literal -offset indent
 107 a = {foo="bar", baz=2}
 108 return a
 109 .Ed
 110 .Pp
 111 Will be output formatted as:
 112 .Bd -literal -offset indent
 113 Channel program fully executed with return value:
 114     return:
 115         baz: 2
 116         foo: 'bar'
 117 .Ed
 118 .Ss Fatal Errors
 119 If the channel program encounters a fatal error while running, a non-zero exit
 120 status will be returned.
 121 If more information about the error is available, a singleton list will be
 122 returned detailing the error:
 123 .Bd -literal -offset indent
 124 error: "error string, including Lua stack trace"
 125 .Ed
 126 .Pp
 127 If a fatal error is returned, the channel program may have not executed at all,
 128 may have partially executed, or may have fully executed but failed to pass a
 129 return value back to userland.
 130 .Pp
 131 If the channel program exhausts an instruction or memory limit, a fatal error
 132 will be generated and the program will be stopped, leaving the program partially
 133 executed.
 134 No attempt is made to reverse or undo any operations already performed.
 135 Note that because both the instruction count and amount of memory used by a
 136 channel program are deterministic when run against the same inputs and
 137 filesystem state, as long as a channel program has run successfully once, you
 138 can guarantee that it will finish successfully against a similar size system.
 139 .Pp
 140 If a channel program attempts to return too large a value, the program will
 141 fully execute but exit with a nonzero status code and no return value.
 142 .Pp
 143 .Em Note:
 144 ZFS API functions do not generate Fatal Errors when correctly invoked, they
 145 return an error code and the channel program continues executing.
 146 See the
 147 .Sx ZFS API
 148 section below for function-specific details on error return codes.
 149 .Ss Lua to C Value Conversion
 150 When invoking a channel program via the libZFS interface, it is necessary to
 151 translate arguments and return values from Lua values to their C equivalents,
 152 and vice-versa.
 153 .Pp
 154 There is a correspondence between nvlist values in C and Lua tables.
 155 A Lua table which is returned from the channel program will be recursively
 156 converted to an nvlist, with table values converted to their natural
 157 equivalents:
 158 .Bd -literal -offset indent
 159 string -> string
 160 number -> int64
 161 boolean -> boolean_value
 162 nil -> boolean (no value)
 163 table -> nvlist
 164 .Ed
 165 .Pp
 166 Likewise, table keys are replaced by string equivalents as follows:
 167 .Bd -literal -offset indent
 168 string -> no change
 169 number -> signed decimal string ("%lld")
 170 boolean -> "true" | "false"
 171 .Ed
 172 .Pp
 173 Any collision of table key strings (for example, the string "true" and a
 174 true boolean value) will cause a fatal error.
 175 .Pp
 176 Lua numbers are represented internally as signed 64-bit integers.
 177 .Sh LUA STANDARD LIBRARY
 178 The following Lua built-in base library functions are available:
 179 .Bd -literal -offset indent
 180 assert                  rawlen
 181 collectgarbage          rawget
 182 error                   rawset
 183 getmetatable            select
 184 ipairs                  setmetatable
 185 next                    tonumber
 186 pairs                   tostring
 187 rawequal                type
 188 .Ed
 189 .Pp
 190 All functions in the
 191 .Em coroutine ,
 192 .Em string ,
 193 and
 194 .Em table
 195 built-in submodules are also available.
 196 A complete list and documentation of these modules is available in the Lua
 197 manual.
 198 .Pp
 199 The following functions base library functions have been disabled and are
 200 not available for use in channel programs:
 201 .Bd -literal -offset indent
 202 dofile
 203 loadfile
 204 load
 205 pcall
 206 print
 207 xpcall
 208 .Ed
 209 .Sh ZFS API
 210 .Ss Function Arguments
 211 Each API function takes a fixed set of required positional arguments and
 212 optional keyword arguments.
 213 For example, the destroy function takes a single positional string argument
 214 (the name of the dataset to destroy) and an optional "defer" keyword boolean
 215 argument.
 216 When using parentheses to specify the arguments to a Lua function, only
 217 positional arguments can be used:
 218 .Bd -literal -offset indent
 219 zfs.sync.destroy("rpool@snap")
 220 .Ed
 221 .Pp
 222 To use keyword arguments, functions must be called with a single argument that
 223 is a Lua table containing entries mapping integers to positional arguments and
 224 strings to keyword arguments:
 225 .Bd -literal -offset indent
 226 zfs.sync.destroy({1="rpool@snap", defer=true})
 227 .Ed
 228 .Pp
 229 The Lua language allows curly braces to be used in place of parenthesis as
 230 syntactic sugar for this calling convention:
 231 .Bd -literal -offset indent
 232 zfs.sync.snapshot{"rpool@snap", defer=true}
 233 .Ed
 234 .Ss Function Return Values
 235 If an API function succeeds, it returns 0.
 236 If it fails, it returns an error code and the channel program continues
 237 executing.
 238 API functions do not generate Fatal Errors except in the case of an
 239 unrecoverable internal file system error.
 240 .Pp
 241 In addition to returning an error code, some functions also return extra
 242 details describing what caused the error.
 243 This extra description is given as a second return value, and will always be a
 244 Lua table, or Nil if no error details were returned.
 245 Different keys will exist in the error details table depending on the function
 246 and error case.
 247 Any such function may be called expecting a single return value:
 248 .Bd -literal -offset indent
 249 errno = zfs.sync.promote(dataset)
 250 .Ed
 251 .Pp
 252 Or, the error details can be retrieved:
 253 .Bd -literal -offset indent
 254 errno, details = zfs.sync.promote(dataset)
 255 if (errno == EEXIST) then
 256     assert(details ~= Nil)
 257     list_of_conflicting_snapshots = details
 258 end
 259 .Ed
 260 .Pp
 261 The following global aliases for API function error return codes are defined
 262 for use in channel programs:
 263 .Bd -literal -offset indent
 264 EPERM     ECHILD      ENODEV      ENOSPC
 265 ENOENT    EAGAIN      ENOTDIR     ESPIPE
 266 ESRCH     ENOMEM      EISDIR      EROFS
 267 EINTR     EACCES      EINVAL      EMLINK
 268 EIO       EFAULT      ENFILE      EPIPE
 269 ENXIO     ENOTBLK     EMFILE      EDOM
 270 E2BIG     EBUSY       ENOTTY      ERANGE
 271 ENOEXEC   EEXIST      ETXTBSY     EDQUOT
 272 EBADF     EXDEV       EFBIG
 273 .Ed
 274 .Ss API Functions
 275 For detailed descriptions of the exact behavior of any zfs administrative
 276 operations, see the main
 277 .Xr zfs 1
 278 manual page.
 279 .Bl -tag -width "xx"
 280 .It Em zfs.debug(msg)
 281 Record a debug message in the zfs_dbgmsg log.
 282 A log of these messages can be printed via mdb's "::zfs_dbgmsg" command, or
 283 can be monitored live by running:
 284 .Bd -literal -offset indent
 285   dtrace -n 'zfs-dbgmsg{trace(stringof(arg0))}'
 286 .Ed
 287 .Pp
 288 msg (string)
 289 .Bd -ragged -compact -offset "xxxx"
 290 Debug message to be printed.
 291 .Ed
 292 .It Em zfs.exists(dataset)
 293 Returns true if the given dataset exists, or false if it doesn't.
 294 A fatal error will be thrown if the dataset is not in the target pool.
 295 That is, in a channel program running on rpool,
 296 zfs.exists("rpool/nonexistent_fs") returns false, but
 297 zfs.exists("somepool/fs_that_may_exist") will error.
 298 .Pp
 299 dataset (string)
 300 .Bd -ragged -compact -offset "xxxx"
 301 Dataset to check for existence.
 302 Must be in the target pool.
 303 .Ed
 304 .It Em zfs.get_prop(dataset, property)
 305 Returns two values.
 306 First, a string, number or table containing the property value for the given
 307 dataset.
 308 Second, a string containing the source of the property (i.e. the name of the
 309 dataset in which it was set or nil if it is readonly).
 310 Throws a Lua error if the dataset is invalid or the property doesn't exist.
 311 Note that Lua only supports int64 number types whereas ZFS number properties
 312 are uint64.
 313 This means very large values (like guid) may wrap around and appear negative.
 314 .Pp
 315 dataset (string)
 316 .Bd -ragged -compact -offset "xxxx"
 317 Filesystem or snapshot path to retrieve properties from.
 318 .Ed
 319 .Pp
 320 property (string)
 321 .Bd -ragged -compact -offset "xxxx"
 322 Name of property to retrieve.
 323 All filesystem, snapshot and volume properties are supported except
 324 for 'mounted' and 'iscsioptions.'
 325 Also supports the 'written@snap' and 'written#bookmark' properties and
 326 the '<user|group><quota|used>@id' properties, though the id must be in numeric
 327 form.
 328 .Ed
 329 .El
 330 .Bl -tag -width "xx"
 331 .It Sy zfs.sync submodule
 332 The sync submodule contains functions that modify the on-disk state.
 333 They are executed in "syncing context".
 334 .Pp
 335 The available sync submodule functions are as follows:
 336 .Bl -tag -width "xx"
 337 .It Em zfs.sync.destroy(dataset, [defer=true|false])
 338 Destroy the given dataset.
 339 Returns 0 on successful destroy, or a nonzero error code if the dataset could
 340 not be destroyed (for example, if the dataset has any active children or
 341 clones).
 342 .Pp
 343 dataset (string)
 344 .Bd -ragged -compact -offset "xxxx"
 345 Filesystem or snapshot to be destroyed.
 346 .Ed
 347 .Pp
 348 [optional] defer (boolean)
 349 .Bd -ragged -compact -offset "xxxx"
 350 Valid only for destroying snapshots.
 351 If set to true, and the snapshot has holds or clones, allows the snapshot to be
 352 marked for deferred deletion rather than failing.
 353 .Ed
 354 .It Em zfs.sync.promote(dataset)
 355 Promote the given clone to a filesystem.
 356 Returns 0 on successful promotion, or a nonzero error code otherwise.
 357 If EEXIST is returned, the second return value will be an array of the clone's
 358 snapshots whose names collide with snapshots of the parent filesystem.
 359 .Pp
 360 dataset (string)
 361 .Bd -ragged -compact -offset "xxxx"
 362 Clone to be promoted.
 363 .Ed
 364 .El
 365 .It Sy zfs.check submodule
 366 For each function in the zfs.sync submodule, there is a corresponding zfs.check
 367 function which performs a "dry run" of the same operation.
 368 Each takes the same arguments as its zfs.sync counterpart and returns 0 if the
 369 operation would succeed, or a non-zero error code if it would fail, along with
 370 any other error details.
 371 That is, each has the same behavior as the corresponding sync function except
 372 for actually executing the requested change.
 373 For example,
 374 .Em zfs.check.destroy("fs")
 375 returns 0 if
 376 .Em zfs.sync.destroy("fs")
 377 would successfully destroy the dataset.
 378 .Pp
 379 The available zfs.check functions are:
 380 .Bl -tag -width "xx"
 381 .It Em zfs.check.destroy(dataset, [defer=true|false])
 382 .It Em zfs.check.promote(dataset)
 383 .El
 384 .It Sy zfs.list submodule
 385 The zfs.list submodule provides functions for iterating over datasets and
 386 properties.
 387 Rather than returning tables, these functions act as Lua iterators, and are
 388 generally used as follows:
 389 .Bd -literal -offset indent
 390 for child in zfs.list.children("rpool") do
 391     ...
 392 end
 393 .Ed
 394 .Pp
 395 The available zfs.list functions are:
 396 .Bl -tag -width "xx"
 397 .It Em zfs.list.clones(snapshot)
 398 Iterate through all clones of the given snapshot.
 399 .Pp
 400 snapshot (string)
 401 .Bd -ragged -compact -offset "xxxx"
 402 Must be a valid snapshot path in the current pool.
 403 .Ed
 404 .It Em zfs.list.snapshots(dataset)
 405 Iterate through all snapshots of the given dataset.
 406 Each snapshot is returned as a string containing the full dataset name, e.g.
 407 "pool/fs@snap".
 408 .Pp
 409 dataset (string)
 410 .Bd -ragged -compact -offset "xxxx"
 411 Must be a valid filesystem or volume.
 412 .Ed
 413 .It Em zfs.list.children(dataset)
 414 Iterate through all direct children of the given dataset.
 415 Each child is returned as a string containing the full dataset name, e.g.
 416 "pool/fs/child".
 417 .Pp
 418 dataset (string)
 419 .Bd -ragged -compact -offset "xxxx"
 420 Must be a valid filesystem or volume.
 421 .Ed
 422 .It Em zfs.list.properties(dataset)
 423 Iterate through all user properties for the given dataset.
 424 .Pp
 425 dataset (string)
 426 .Bd -ragged -compact -offset "xxxx"
 427 Must be a valid filesystem, snapshot, or volume.
 428 .Ed
 429 .It Em zfs.list.system_properties(dataset)
 430 Returns an array of strings, the names of the valid system (non-user defined)
 431 properties for the given dataset.
 432 Throws a Lua error if the dataset is invalid.
 433 .Pp
 434 dataset (string)
 435 .Bd -ragged -compact -offset "xxxx"
 436 Must be a valid filesystem, snapshot or volume.
 437 .Ed
 438 .El
 439 .El
 440 .Sh EXAMPLES
 441 .Ss Example 1
 442 The following channel program recursively destroys a filesystem and all its
 443 snapshots and children in a naive manner.
 444 Note that this does not involve any error handling or reporting.
 445 .Bd -literal -offset indent
 446 function destroy_recursive(root)
 447     for child in zfs.list.children(root) do
 448         destroy_recursive(child)
 449     end
 450     for snap in zfs.list.snapshots(root) do
 451         zfs.sync.destroy(snap)
 452     end
 453     zfs.sync.destroy(root)
 454 end
 455 destroy_recursive("pool/somefs")
 456 .Ed
 457 .Ss Example 2
 458 A more verbose and robust version of the same channel program, which
 459 properly detects and reports errors, and also takes the dataset to destroy
 460 as a command line argument, would be as follows:
 461 .Bd -literal -offset indent
 462 succeeded = {}
 463 failed = {}
 464
 465 function destroy_recursive(root)
 466     for child in zfs.list.children(root) do
 467         destroy_recursive(child)
 468     end
 469     for snap in zfs.list.snapshots(root) do
 470         err = zfs.sync.destroy(snap)
 471         if (err ~= 0) then
 472             failed[snap] = err
 473         else
 474             succeeded[snap] = err
 475         end
 476     end
 477     err = zfs.sync.destroy(root)
 478     if (err ~= 0) then
 479         failed[root] = err
 480     else
 481         succeeded[root] = err
 482     end
 483 end
 484
 485 args = ...
 486 argv = args["argv"]
 487
 488 destroy_recursive(argv[1])
 489
 490 results = {}
 491 results["succeeded"] = succeeded
 492 results["failed"] = failed
 493 return results
 494 .Ed
 495 .Ss Example 3
 496 The following function performs a forced promote operation by attempting to
 497 promote the given clone and destroying any conflicting snapshots.
 498 .Bd -literal -offset indent
 499 function force_promote(ds)
 500    errno, details = zfs.check.promote(ds)
 501    if (errno == EEXIST) then
 502        assert(details ~= Nil)
 503        for i, snap in ipairs(details) do
 504            zfs.sync.destroy(ds .. "@" .. snap)
 505        end
 506    elseif (errno ~= 0) then
 507        return errno
 508    end
 509    return zfs.sync.promote(ds)
 510 end
 511 .Ed