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
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.
11 .\" Copyright (c) 2016, 2017 by Delphix. All Rights Reserved.
18 .Nd executes ZFS channel programs
21 .Op Fl t Ar instruction-limit
22 .Op Fl m Ar memory-limit
25 .\".Op Ar optional arguments to channel program
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.
34 A modified version of the Lua 5.2 interpreter is used to run channel program
36 The Lua 5.2 manual can be found at:
37 .Bd -centered -offset indent
38 .Lk http://www.lua.org/manual/5.2/
41 The channel program given by
45 and any attempts to access or modify other pools will cause an error.
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.
61 All remaining argument strings will be passed directly to the Lua script as
66 A channel program can be invoked either from the command line, or via a library
68 .Fn lzc_channel_program .
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
76 -- argv == {1="arg1", 2="arg2", ...}
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
82 .Bd -literal -offset indent
84 -- args == {"foo"="bar", "baz"={...}, ...}
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.
92 in a C array passed to a channel program will be stored in
94 when accessed from Lua.
96 Lua return statements take the form:
97 .Bd -literal -offset indent
98 return ret0, ret1, ret2, ...
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}
111 Will be output formatted as:
112 .Bd -literal -offset indent
113 Channel program fully executed with return value:
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"
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.
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
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.
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.
144 ZFS API functions do not generate Fatal Errors when correctly invoked, they
145 return an error code and the channel program continues executing.
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,
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
158 .Bd -literal -offset indent
161 boolean -> boolean_value
162 nil -> boolean (no value)
166 Likewise, table keys are replaced by string equivalents as follows:
167 .Bd -literal -offset indent
169 number -> signed decimal string ("%lld")
170 boolean -> "true" | "false"
173 Any collision of table key strings (for example, the string "true" and a
174 true boolean value) will cause a fatal error.
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
181 collectgarbage rawget
195 built-in submodules are also available.
196 A complete list and documentation of these modules is available in the Lua
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
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
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")
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})
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}
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
238 API functions do not generate Fatal Errors except in the case of an
239 unrecoverable internal file system error.
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
247 Any such function may be called expecting a single return value:
248 .Bd -literal -offset indent
249 errno = zfs.sync.promote(dataset)
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
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
275 For detailed descriptions of the exact behavior of any zfs administrative
276 operations, see the main
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))}'
289 .Bd -ragged -compact -offset "xxxx"
290 Debug message to be printed.
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.
300 .Bd -ragged -compact -offset "xxxx"
301 Dataset to check for existence.
302 Must be in the target pool.
304 .It Em zfs.get_prop(dataset, property)
306 First, a string, number or table containing the property value for the given
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
313 This means very large values (like guid) may wrap around and appear negative.
316 .Bd -ragged -compact -offset "xxxx"
317 Filesystem or snapshot path to retrieve properties from.
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
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".
335 The available sync submodule functions are as follows:
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
344 .Bd -ragged -compact -offset "xxxx"
345 Filesystem or snapshot to be destroyed.
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.
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.
361 .Bd -ragged -compact -offset "xxxx"
362 Clone to be promoted.
364 .It Em zfs.sync.rollback(filesystem)
365 Rollback to the previous snapshot for a dataset.
366 Returns 0 on successful rollback, or a nonzero error code otherwise.
367 Rollbacks can be performed on filesystems or zvols, but not on snapshots
369 EBUSY is returned in the case where the filesystem is mounted.
372 .Bd -ragged -compact -offset "xxxx"
373 Filesystem to rollback.
375 .It Em zfs.sync.snapshot(dataset)
376 Create a snapshot of a filesystem.
377 Returns 0 if the snapshot was successfully created,
378 and a nonzero error code otherwise.
380 Note: Taking a snapshot will fail on any pool older than legacy version 27.
381 To enable taking snapshots from ZCP scripts, the pool must be upgraded.
384 .Bd -ragged -compact -offset "xxxx"
385 Name of snapshot to create.
388 .It Sy zfs.check submodule
389 For each function in the zfs.sync submodule, there is a corresponding zfs.check
390 function which performs a "dry run" of the same operation.
391 Each takes the same arguments as its zfs.sync counterpart and returns 0 if the
392 operation would succeed, or a non-zero error code if it would fail, along with
393 any other error details.
394 That is, each has the same behavior as the corresponding sync function except
395 for actually executing the requested change.
397 .Em zfs.check.destroy("fs")
399 .Em zfs.sync.destroy("fs")
400 would successfully destroy the dataset.
402 The available zfs.check functions are:
404 .It Em zfs.check.destroy(dataset, [defer=true|false])
405 .It Em zfs.check.promote(dataset)
406 .It Em zfs.check.rollback(filesystem)
407 .It Em zfs.check.snapshot(dataset)
409 .It Sy zfs.list submodule
410 The zfs.list submodule provides functions for iterating over datasets and
412 Rather than returning tables, these functions act as Lua iterators, and are
413 generally used as follows:
414 .Bd -literal -offset indent
415 for child in zfs.list.children("rpool") do
420 The available zfs.list functions are:
422 .It Em zfs.list.clones(snapshot)
423 Iterate through all clones of the given snapshot.
426 .Bd -ragged -compact -offset "xxxx"
427 Must be a valid snapshot path in the current pool.
429 .It Em zfs.list.snapshots(dataset)
430 Iterate through all snapshots of the given dataset.
431 Each snapshot is returned as a string containing the full dataset name, e.g.
435 .Bd -ragged -compact -offset "xxxx"
436 Must be a valid filesystem or volume.
438 .It Em zfs.list.children(dataset)
439 Iterate through all direct children of the given dataset.
440 Each child is returned as a string containing the full dataset name, e.g.
444 .Bd -ragged -compact -offset "xxxx"
445 Must be a valid filesystem or volume.
447 .It Em zfs.list.properties(dataset)
448 Iterate through all user properties for the given dataset.
451 .Bd -ragged -compact -offset "xxxx"
452 Must be a valid filesystem, snapshot, or volume.
454 .It Em zfs.list.system_properties(dataset)
455 Returns an array of strings, the names of the valid system (non-user defined)
456 properties for the given dataset.
457 Throws a Lua error if the dataset is invalid.
460 .Bd -ragged -compact -offset "xxxx"
461 Must be a valid filesystem, snapshot or volume.
467 The following channel program recursively destroys a filesystem and all its
468 snapshots and children in a naive manner.
469 Note that this does not involve any error handling or reporting.
470 .Bd -literal -offset indent
471 function destroy_recursive(root)
472 for child in zfs.list.children(root) do
473 destroy_recursive(child)
475 for snap in zfs.list.snapshots(root) do
476 zfs.sync.destroy(snap)
478 zfs.sync.destroy(root)
480 destroy_recursive("pool/somefs")
483 A more verbose and robust version of the same channel program, which
484 properly detects and reports errors, and also takes the dataset to destroy
485 as a command line argument, would be as follows:
486 .Bd -literal -offset indent
490 function destroy_recursive(root)
491 for child in zfs.list.children(root) do
492 destroy_recursive(child)
494 for snap in zfs.list.snapshots(root) do
495 err = zfs.sync.destroy(snap)
499 succeeded[snap] = err
502 err = zfs.sync.destroy(root)
506 succeeded[root] = err
513 destroy_recursive(argv[1])
516 results["succeeded"] = succeeded
517 results["failed"] = failed
521 The following function performs a forced promote operation by attempting to
522 promote the given clone and destroying any conflicting snapshots.
523 .Bd -literal -offset indent
524 function force_promote(ds)
525 errno, details = zfs.check.promote(ds)
526 if (errno == EEXIST) then
527 assert(details ~= Nil)
528 for i, snap in ipairs(details) do
529 zfs.sync.destroy(ds .. "@" .. snap)
531 elseif (errno ~= 0) then
534 return zfs.sync.promote(ds)