1dfc11533SChris Williamson.\" This file and its contents are supplied under the terms of the 2dfc11533SChris Williamson.\" Common Development and Distribution License ("CDDL"), version 1.0. 3dfc11533SChris Williamson.\" You may only use this file in accordance with the terms of version 4dfc11533SChris Williamson.\" 1.0 of the CDDL. 5dfc11533SChris Williamson.\" 6dfc11533SChris Williamson.\" A full copy of the text of the CDDL should have accompanied this 7dfc11533SChris Williamson.\" source. A copy of the CDDL is also available via the Internet at 8dfc11533SChris Williamson.\" http://www.illumos.org/license/CDDL. 9dfc11533SChris Williamson.\" 10dfc11533SChris Williamson.\" 11000cce6bSBrad Lewis.\" Copyright (c) 2016, 2017 by Delphix. All rights reserved. 1252675910SAlek Pinchuk.\" Copyright (c) 2018 Datto Inc. 132d85dedbSJason King.\" Copyright 2020 Joyent, Inc. 14d8f839f9SJason King.\" Copyright 2021 Jason King 15dfc11533SChris Williamson.\" 16d8f839f9SJason King.Dd November 8, 2021 17*bbf21555SRichard Lowe.Dt ZFS-PROGRAM 8 18dfc11533SChris Williamson.Os 19dfc11533SChris Williamson.Sh NAME 20b31ca922SChris Fraire.Nm "zfs program" 21dfc11533SChris Williamson.Nd executes ZFS channel programs 22dfc11533SChris Williamson.Sh SYNOPSIS 23b31ca922SChris Fraire.Cm "zfs program" 2452675910SAlek Pinchuk.Op Fl jn 25dfc11533SChris Williamson.Op Fl t Ar instruction-limit 26dfc11533SChris Williamson.Op Fl m Ar memory-limit 27dfc11533SChris Williamson.Ar pool 28dfc11533SChris Williamson.Ar script 29dfc11533SChris Williamson.\".Op Ar optional arguments to channel program 30dfc11533SChris Williamson.Sh DESCRIPTION 31dfc11533SChris WilliamsonThe ZFS channel program interface allows ZFS administrative operations to be 32dfc11533SChris Williamsonrun programmatically as a Lua script. 33dfc11533SChris WilliamsonThe entire script is executed atomically, with no other administrative 34dfc11533SChris Williamsonoperations taking effect concurrently. 35dfc11533SChris WilliamsonA library of ZFS calls is made available to channel program scripts. 36dfc11533SChris WilliamsonChannel programs may only be run with root privileges. 37dfc11533SChris Williamson.Pp 38dfc11533SChris WilliamsonA modified version of the Lua 5.2 interpreter is used to run channel program 39dfc11533SChris Williamsonscripts. 40dfc11533SChris WilliamsonThe Lua 5.2 manual can be found at: 41dfc11533SChris Williamson.Bd -centered -offset indent 42dfc11533SChris Williamson.Lk http://www.lua.org/manual/5.2/ 43dfc11533SChris Williamson.Ed 44dfc11533SChris Williamson.Pp 45dfc11533SChris WilliamsonThe channel program given by 46dfc11533SChris Williamson.Ar script 47dfc11533SChris Williamsonwill be run on 48dfc11533SChris Williamson.Ar pool , 49dfc11533SChris Williamsonand any attempts to access or modify other pools will cause an error. 50dfc11533SChris Williamson.Sh OPTIONS 51dfc11533SChris Williamson.Bl -tag -width "-t" 5252675910SAlek Pinchuk.It Fl j 5352675910SAlek PinchukDisplay channel program output in JSON format. 5452675910SAlek PinchukWhen this flag is specified and standard output is empty - 5552675910SAlek Pinchukchannel program encountered an error. 5652675910SAlek PinchukThe details of such an error will be printed to standard error in plain text. 57a3b28680SSerapheim Dimitropoulos.It Fl n 58a3b28680SSerapheim DimitropoulosExecutes a read-only channel program, which runs faster. 59a3b28680SSerapheim DimitropoulosThe program cannot change on-disk state by calling functions from the 60a3b28680SSerapheim Dimitropouloszfs.sync submodule. 61a3b28680SSerapheim DimitropoulosThe program can be used to gather information such as properties and 62a3b28680SSerapheim Dimitropoulosdetermining if changes would succeed (zfs.check.*). 63a3b28680SSerapheim DimitropoulosWithout this flag, all pending changes must be synced to disk before a 64a3b28680SSerapheim Dimitropouloschannel program can complete. 65dfc11533SChris Williamson.It Fl t Ar instruction-limit 66dfc11533SChris WilliamsonExecution time limit, in number of Lua instructions to execute. 67dfc11533SChris WilliamsonIf a channel program executes more than the specified number of instructions, 68dfc11533SChris Williamsonit will be stopped and an error will be returned. 69dfc11533SChris WilliamsonThe default limit is 10 million instructions, and it can be set to a maximum of 70dfc11533SChris Williamson100 million instructions. 71dfc11533SChris Williamson.It Fl m Ar memory-limit 72dfc11533SChris WilliamsonMemory limit, in bytes. 73dfc11533SChris WilliamsonIf a channel program attempts to allocate more memory than the given limit, it 74dfc11533SChris Williamsonwill be stopped and an error returned. 75dfc11533SChris WilliamsonThe default memory limit is 10 MB, and can be set to a maximum of 100 MB. 76dfc11533SChris Williamson.El 77dfc11533SChris Williamson.Pp 78dfc11533SChris WilliamsonAll remaining argument strings will be passed directly to the Lua script as 79dfc11533SChris Williamsondescribed in the 80dfc11533SChris Williamson.Sx LUA INTERFACE 81dfc11533SChris Williamsonsection below. 82dfc11533SChris Williamson.Sh LUA INTERFACE 83dfc11533SChris WilliamsonA channel program can be invoked either from the command line, or via a library 84dfc11533SChris Williamsoncall to 85dfc11533SChris Williamson.Fn lzc_channel_program . 86dfc11533SChris Williamson.Ss Arguments 87dfc11533SChris WilliamsonArguments passed to the channel program are converted to a Lua table. 88dfc11533SChris WilliamsonIf invoked from the command line, extra arguments to the Lua script will be 89dfc11533SChris Williamsonaccessible as an array stored in the argument table with the key 'argv': 90dfc11533SChris Williamson.Bd -literal -offset indent 91dfc11533SChris Williamsonargs = ... 92dfc11533SChris Williamsonargv = args["argv"] 93dfc11533SChris Williamson-- argv == {1="arg1", 2="arg2", ...} 94dfc11533SChris Williamson.Ed 95dfc11533SChris Williamson.Pp 96dfc11533SChris WilliamsonIf invoked from the libZFS interface, an arbitrary argument list can be 97dfc11533SChris Williamsonpassed to the channel program, which is accessible via the same 98dfc11533SChris Williamson"..." syntax in Lua: 99dfc11533SChris Williamson.Bd -literal -offset indent 100dfc11533SChris Williamsonargs = ... 101dfc11533SChris Williamson-- args == {"foo"="bar", "baz"={...}, ...} 102dfc11533SChris Williamson.Ed 103dfc11533SChris Williamson.Pp 104dfc11533SChris WilliamsonNote that because Lua arrays are 1-indexed, arrays passed to Lua from the 105dfc11533SChris WilliamsonlibZFS interface will have their indices incremented by 1. 106dfc11533SChris WilliamsonThat is, the element 107dfc11533SChris Williamsonin 108dfc11533SChris Williamson.Va arr[0] 109dfc11533SChris Williamsonin a C array passed to a channel program will be stored in 110dfc11533SChris Williamson.Va arr[1] 111dfc11533SChris Williamsonwhen accessed from Lua. 112dfc11533SChris Williamson.Ss Return Values 113dfc11533SChris WilliamsonLua return statements take the form: 114dfc11533SChris Williamson.Bd -literal -offset indent 115dfc11533SChris Williamsonreturn ret0, ret1, ret2, ... 116dfc11533SChris Williamson.Ed 117dfc11533SChris Williamson.Pp 118dfc11533SChris WilliamsonReturn statements returning multiple values are permitted internally in a 119dfc11533SChris Williamsonchannel program script, but attempting to return more than one value from the 120dfc11533SChris Williamsontop level of the channel program is not permitted and will throw an error. 121dfc11533SChris WilliamsonHowever, tables containing multiple values can still be returned. 122dfc11533SChris WilliamsonIf invoked from the command line, a return statement: 123dfc11533SChris Williamson.Bd -literal -offset indent 124dfc11533SChris Williamsona = {foo="bar", baz=2} 125dfc11533SChris Williamsonreturn a 126dfc11533SChris Williamson.Ed 127dfc11533SChris Williamson.Pp 128dfc11533SChris WilliamsonWill be output formatted as: 129dfc11533SChris Williamson.Bd -literal -offset indent 130dfc11533SChris WilliamsonChannel program fully executed with return value: 131dfc11533SChris Williamson return: 132dfc11533SChris Williamson baz: 2 133dfc11533SChris Williamson foo: 'bar' 134dfc11533SChris Williamson.Ed 135dfc11533SChris Williamson.Ss Fatal Errors 136dfc11533SChris WilliamsonIf the channel program encounters a fatal error while running, a non-zero exit 137dfc11533SChris Williamsonstatus will be returned. 138dfc11533SChris WilliamsonIf more information about the error is available, a singleton list will be 139dfc11533SChris Williamsonreturned detailing the error: 140dfc11533SChris Williamson.Bd -literal -offset indent 141dfc11533SChris Williamsonerror: "error string, including Lua stack trace" 142dfc11533SChris Williamson.Ed 143dfc11533SChris Williamson.Pp 144dfc11533SChris WilliamsonIf a fatal error is returned, the channel program may have not executed at all, 145dfc11533SChris Williamsonmay have partially executed, or may have fully executed but failed to pass a 146dfc11533SChris Williamsonreturn value back to userland. 147dfc11533SChris Williamson.Pp 148dfc11533SChris WilliamsonIf the channel program exhausts an instruction or memory limit, a fatal error 149dfc11533SChris Williamsonwill be generated and the program will be stopped, leaving the program partially 150dfc11533SChris Williamsonexecuted. 151dfc11533SChris WilliamsonNo attempt is made to reverse or undo any operations already performed. 152dfc11533SChris WilliamsonNote that because both the instruction count and amount of memory used by a 153dfc11533SChris Williamsonchannel program are deterministic when run against the same inputs and 154dfc11533SChris Williamsonfilesystem state, as long as a channel program has run successfully once, you 155dfc11533SChris Williamsoncan guarantee that it will finish successfully against a similar size system. 156dfc11533SChris Williamson.Pp 157dfc11533SChris WilliamsonIf a channel program attempts to return too large a value, the program will 158dfc11533SChris Williamsonfully execute but exit with a nonzero status code and no return value. 159dfc11533SChris Williamson.Pp 160b2d2f356SSara Hartse.Em Note : 161dfc11533SChris WilliamsonZFS API functions do not generate Fatal Errors when correctly invoked, they 162dfc11533SChris Williamsonreturn an error code and the channel program continues executing. 163dfc11533SChris WilliamsonSee the 164dfc11533SChris Williamson.Sx ZFS API 165dfc11533SChris Williamsonsection below for function-specific details on error return codes. 166dfc11533SChris Williamson.Ss Lua to C Value Conversion 167dfc11533SChris WilliamsonWhen invoking a channel program via the libZFS interface, it is necessary to 168dfc11533SChris Williamsontranslate arguments and return values from Lua values to their C equivalents, 169dfc11533SChris Williamsonand vice-versa. 170dfc11533SChris Williamson.Pp 171dfc11533SChris WilliamsonThere is a correspondence between nvlist values in C and Lua tables. 172dfc11533SChris WilliamsonA Lua table which is returned from the channel program will be recursively 173dfc11533SChris Williamsonconverted to an nvlist, with table values converted to their natural 174dfc11533SChris Williamsonequivalents: 175dfc11533SChris Williamson.Bd -literal -offset indent 176dfc11533SChris Williamsonstring -> string 177dfc11533SChris Williamsonnumber -> int64 178dfc11533SChris Williamsonboolean -> boolean_value 179dfc11533SChris Williamsonnil -> boolean (no value) 180dfc11533SChris Williamsontable -> nvlist 181dfc11533SChris Williamson.Ed 182dfc11533SChris Williamson.Pp 183dfc11533SChris WilliamsonLikewise, table keys are replaced by string equivalents as follows: 184dfc11533SChris Williamson.Bd -literal -offset indent 185dfc11533SChris Williamsonstring -> no change 186dfc11533SChris Williamsonnumber -> signed decimal string ("%lld") 187dfc11533SChris Williamsonboolean -> "true" | "false" 188dfc11533SChris Williamson.Ed 189dfc11533SChris Williamson.Pp 190dfc11533SChris WilliamsonAny collision of table key strings (for example, the string "true" and a 191dfc11533SChris Williamsontrue boolean value) will cause a fatal error. 192dfc11533SChris Williamson.Pp 193dfc11533SChris WilliamsonLua numbers are represented internally as signed 64-bit integers. 194dfc11533SChris Williamson.Sh LUA STANDARD LIBRARY 195dfc11533SChris WilliamsonThe following Lua built-in base library functions are available: 196dfc11533SChris Williamson.Bd -literal -offset indent 197dfc11533SChris Williamsonassert rawlen 198dfc11533SChris Williamsoncollectgarbage rawget 199dfc11533SChris Williamsonerror rawset 200dfc11533SChris Williamsongetmetatable select 201dfc11533SChris Williamsonipairs setmetatable 202dfc11533SChris Williamsonnext tonumber 203dfc11533SChris Williamsonpairs tostring 204dfc11533SChris Williamsonrawequal type 205dfc11533SChris Williamson.Ed 206dfc11533SChris Williamson.Pp 207dfc11533SChris WilliamsonAll functions in the 208dfc11533SChris Williamson.Em coroutine , 209dfc11533SChris Williamson.Em string , 210dfc11533SChris Williamsonand 211dfc11533SChris Williamson.Em table 212dfc11533SChris Williamsonbuilt-in submodules are also available. 213dfc11533SChris WilliamsonA complete list and documentation of these modules is available in the Lua 214dfc11533SChris Williamsonmanual. 215dfc11533SChris Williamson.Pp 216dfc11533SChris WilliamsonThe following functions base library functions have been disabled and are 217dfc11533SChris Williamsonnot available for use in channel programs: 218dfc11533SChris Williamson.Bd -literal -offset indent 219dfc11533SChris Williamsondofile 220dfc11533SChris Williamsonloadfile 221dfc11533SChris Williamsonload 222dfc11533SChris Williamsonpcall 223dfc11533SChris Williamsonprint 224dfc11533SChris Williamsonxpcall 225dfc11533SChris Williamson.Ed 226dfc11533SChris Williamson.Sh ZFS API 227dfc11533SChris Williamson.Ss Function Arguments 228dfc11533SChris WilliamsonEach API function takes a fixed set of required positional arguments and 229dfc11533SChris Williamsonoptional keyword arguments. 230dfc11533SChris WilliamsonFor example, the destroy function takes a single positional string argument 231dfc11533SChris Williamson(the name of the dataset to destroy) and an optional "defer" keyword boolean 232dfc11533SChris Williamsonargument. 233dfc11533SChris WilliamsonWhen using parentheses to specify the arguments to a Lua function, only 234dfc11533SChris Williamsonpositional arguments can be used: 235dfc11533SChris Williamson.Bd -literal -offset indent 236dfc11533SChris Williamsonzfs.sync.destroy("rpool@snap") 237dfc11533SChris Williamson.Ed 238dfc11533SChris Williamson.Pp 239dfc11533SChris WilliamsonTo use keyword arguments, functions must be called with a single argument that 240dfc11533SChris Williamsonis a Lua table containing entries mapping integers to positional arguments and 241dfc11533SChris Williamsonstrings to keyword arguments: 242dfc11533SChris Williamson.Bd -literal -offset indent 243dfc11533SChris Williamsonzfs.sync.destroy({1="rpool@snap", defer=true}) 244dfc11533SChris Williamson.Ed 245dfc11533SChris Williamson.Pp 246dfc11533SChris WilliamsonThe Lua language allows curly braces to be used in place of parenthesis as 247dfc11533SChris Williamsonsyntactic sugar for this calling convention: 248dfc11533SChris Williamson.Bd -literal -offset indent 249dfc11533SChris Williamsonzfs.sync.snapshot{"rpool@snap", defer=true} 250dfc11533SChris Williamson.Ed 251dfc11533SChris Williamson.Ss Function Return Values 252dfc11533SChris WilliamsonIf an API function succeeds, it returns 0. 253dfc11533SChris WilliamsonIf it fails, it returns an error code and the channel program continues 254dfc11533SChris Williamsonexecuting. 255dfc11533SChris WilliamsonAPI functions do not generate Fatal Errors except in the case of an 256dfc11533SChris Williamsonunrecoverable internal file system error. 257dfc11533SChris Williamson.Pp 258dfc11533SChris WilliamsonIn addition to returning an error code, some functions also return extra 259dfc11533SChris Williamsondetails describing what caused the error. 260dfc11533SChris WilliamsonThis extra description is given as a second return value, and will always be a 261dfc11533SChris WilliamsonLua table, or Nil if no error details were returned. 262dfc11533SChris WilliamsonDifferent keys will exist in the error details table depending on the function 263dfc11533SChris Williamsonand error case. 264dfc11533SChris WilliamsonAny such function may be called expecting a single return value: 265dfc11533SChris Williamson.Bd -literal -offset indent 266dfc11533SChris Williamsonerrno = zfs.sync.promote(dataset) 267dfc11533SChris Williamson.Ed 268dfc11533SChris Williamson.Pp 269dfc11533SChris WilliamsonOr, the error details can be retrieved: 270dfc11533SChris Williamson.Bd -literal -offset indent 271dfc11533SChris Williamsonerrno, details = zfs.sync.promote(dataset) 272dfc11533SChris Williamsonif (errno == EEXIST) then 273dfc11533SChris Williamson assert(details ~= Nil) 274dfc11533SChris Williamson list_of_conflicting_snapshots = details 275dfc11533SChris Williamsonend 276dfc11533SChris Williamson.Ed 277dfc11533SChris Williamson.Pp 278dfc11533SChris WilliamsonThe following global aliases for API function error return codes are defined 279dfc11533SChris Williamsonfor use in channel programs: 280dfc11533SChris Williamson.Bd -literal -offset indent 281dfc11533SChris WilliamsonEPERM ECHILD ENODEV ENOSPC 282dfc11533SChris WilliamsonENOENT EAGAIN ENOTDIR ESPIPE 283dfc11533SChris WilliamsonESRCH ENOMEM EISDIR EROFS 284dfc11533SChris WilliamsonEINTR EACCES EINVAL EMLINK 285dfc11533SChris WilliamsonEIO EFAULT ENFILE EPIPE 286dfc11533SChris WilliamsonENXIO ENOTBLK EMFILE EDOM 287dfc11533SChris WilliamsonE2BIG EBUSY ENOTTY ERANGE 288dfc11533SChris WilliamsonENOEXEC EEXIST ETXTBSY EDQUOT 289dfc11533SChris WilliamsonEBADF EXDEV EFBIG 290dfc11533SChris Williamson.Ed 291dfc11533SChris Williamson.Ss API Functions 292dfc11533SChris WilliamsonFor detailed descriptions of the exact behavior of any zfs administrative 293dfc11533SChris Williamsonoperations, see the main 294*bbf21555SRichard Lowe.Xr zfs 8 295dfc11533SChris Williamsonmanual page. 296dfc11533SChris Williamson.Bl -tag -width "xx" 297dfc11533SChris Williamson.It Em zfs.debug(msg) 298dfc11533SChris WilliamsonRecord a debug message in the zfs_dbgmsg log. 299dfc11533SChris WilliamsonA log of these messages can be printed via mdb's "::zfs_dbgmsg" command, or 300dfc11533SChris Williamsoncan be monitored live by running: 301dfc11533SChris Williamson.Bd -literal -offset indent 302dfc11533SChris Williamson dtrace -n 'zfs-dbgmsg{trace(stringof(arg0))}' 303dfc11533SChris Williamson.Ed 304dfc11533SChris Williamson.Pp 305dfc11533SChris Williamsonmsg (string) 306dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 307dfc11533SChris WilliamsonDebug message to be printed. 308dfc11533SChris Williamson.Ed 3095f39f884SChris Williamson.It Em zfs.exists(dataset) 3105f39f884SChris WilliamsonReturns true if the given dataset exists, or false if it doesn't. 3115f39f884SChris WilliamsonA fatal error will be thrown if the dataset is not in the target pool. 3125f39f884SChris WilliamsonThat is, in a channel program running on rpool, 3135f39f884SChris Williamsonzfs.exists("rpool/nonexistent_fs") returns false, but 3145f39f884SChris Williamsonzfs.exists("somepool/fs_that_may_exist") will error. 3155f39f884SChris Williamson.Pp 3165f39f884SChris Williamsondataset (string) 3175f39f884SChris Williamson.Bd -ragged -compact -offset "xxxx" 3185f39f884SChris WilliamsonDataset to check for existence. 3195f39f884SChris WilliamsonMust be in the target pool. 3205f39f884SChris Williamson.Ed 321dfc11533SChris Williamson.It Em zfs.get_prop(dataset, property) 322dfc11533SChris WilliamsonReturns two values. 323dfc11533SChris WilliamsonFirst, a string, number or table containing the property value for the given 324dfc11533SChris Williamsondataset. 325dfc11533SChris WilliamsonSecond, a string containing the source of the property (i.e. the name of the 326dfc11533SChris Williamsondataset in which it was set or nil if it is readonly). 327dfc11533SChris WilliamsonThrows a Lua error if the dataset is invalid or the property doesn't exist. 328dfc11533SChris WilliamsonNote that Lua only supports int64 number types whereas ZFS number properties 329dfc11533SChris Williamsonare uint64. 330dfc11533SChris WilliamsonThis means very large values (like guid) may wrap around and appear negative. 331dfc11533SChris Williamson.Pp 332dfc11533SChris Williamsondataset (string) 333dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 334dfc11533SChris WilliamsonFilesystem or snapshot path to retrieve properties from. 335dfc11533SChris Williamson.Ed 336dfc11533SChris Williamson.Pp 337dfc11533SChris Williamsonproperty (string) 338dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 339dfc11533SChris WilliamsonName of property to retrieve. 340dfc11533SChris WilliamsonAll filesystem, snapshot and volume properties are supported except 341dfc11533SChris Williamsonfor 'mounted' and 'iscsioptions.' 342dfc11533SChris WilliamsonAlso supports the 'written@snap' and 'written#bookmark' properties and 343dfc11533SChris Williamsonthe '<user|group><quota|used>@id' properties, though the id must be in numeric 344dfc11533SChris Williamsonform. 345dfc11533SChris Williamson.Ed 346dfc11533SChris Williamson.El 347dfc11533SChris Williamson.Bl -tag -width "xx" 348dfc11533SChris Williamson.It Sy zfs.sync submodule 349dfc11533SChris WilliamsonThe sync submodule contains functions that modify the on-disk state. 350dfc11533SChris WilliamsonThey are executed in "syncing context". 351dfc11533SChris Williamson.Pp 352dfc11533SChris WilliamsonThe available sync submodule functions are as follows: 353dfc11533SChris Williamson.Bl -tag -width "xx" 354d8f839f9SJason King.It Em zfs.sync.change_key(dataset, key) 355d8f839f9SJason KingChange the dataset encryption key. 356d8f839f9SJason King.Fa key 357d8f839f9SJason Kingmust be in the format (raw or hex) specified by the dataset 358d8f839f9SJason King.Sy keyformat 359d8f839f9SJason Kingproperty. 360dfc11533SChris Williamson.It Em zfs.sync.destroy(dataset, [defer=true|false]) 361dfc11533SChris WilliamsonDestroy the given dataset. 362dfc11533SChris WilliamsonReturns 0 on successful destroy, or a nonzero error code if the dataset could 363dfc11533SChris Williamsonnot be destroyed (for example, if the dataset has any active children or 364dfc11533SChris Williamsonclones). 365dfc11533SChris Williamson.Pp 366dfc11533SChris Williamsondataset (string) 367dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 368dfc11533SChris WilliamsonFilesystem or snapshot to be destroyed. 369dfc11533SChris Williamson.Ed 370dfc11533SChris Williamson.Pp 371dfc11533SChris Williamson[optional] defer (boolean) 372dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 373dfc11533SChris WilliamsonValid only for destroying snapshots. 374dfc11533SChris WilliamsonIf set to true, and the snapshot has holds or clones, allows the snapshot to be 375dfc11533SChris Williamsonmarked for deferred deletion rather than failing. 376dfc11533SChris Williamson.Ed 3772d85dedbSJason King.It Em zfs.sync.inherit(dataset, property) 3782d85dedbSJason KingClears the specified property in the given dataset, causing it to be inherited 3792d85dedbSJason Kingfrom an ancestor, or restored to the default if no ancestor property is set. 3802d85dedbSJason KingThe 3812d85dedbSJason King.Ql zfs inherit -S 3822d85dedbSJason Kingoption has not been implemented. 3832d85dedbSJason KingReturns 0 on success, or a nonzero error code if the property could not be 3842d85dedbSJason Kingcleared. 3852d85dedbSJason King.Pp 3862d85dedbSJason Kingdataset (string) 3872d85dedbSJason King.Bd -ragged -compact -offset "xxxx" 3882d85dedbSJason KingFilesystem or snapshot containing the property to clear. 3892d85dedbSJason King.Ed 3902d85dedbSJason King.Pp 3912d85dedbSJason Kingproperty (string) 3922d85dedbSJason King.Bd -ragged -compact -offset "xxxx" 3932d85dedbSJason KingThe property to clear. 3942d85dedbSJason KingAllowed properties are the same as those for the 3952d85dedbSJason King.Nm zfs Cm inherit 3962d85dedbSJason Kingcommand. 3972d85dedbSJason King.Ed 398dfc11533SChris Williamson.It Em zfs.sync.promote(dataset) 399dfc11533SChris WilliamsonPromote the given clone to a filesystem. 400dfc11533SChris WilliamsonReturns 0 on successful promotion, or a nonzero error code otherwise. 401dfc11533SChris WilliamsonIf EEXIST is returned, the second return value will be an array of the clone's 402dfc11533SChris Williamsonsnapshots whose names collide with snapshots of the parent filesystem. 403dfc11533SChris Williamson.Pp 404dfc11533SChris Williamsondataset (string) 405dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 406dfc11533SChris WilliamsonClone to be promoted. 407dfc11533SChris Williamson.Ed 408000cce6bSBrad Lewis.It Em zfs.sync.rollback(filesystem) 409000cce6bSBrad LewisRollback to the previous snapshot for a dataset. 410000cce6bSBrad LewisReturns 0 on successful rollback, or a nonzero error code otherwise. 411000cce6bSBrad LewisRollbacks can be performed on filesystems or zvols, but not on snapshots 412000cce6bSBrad Lewisor mounted datasets. 413000cce6bSBrad LewisEBUSY is returned in the case where the filesystem is mounted. 414000cce6bSBrad Lewis.Pp 415000cce6bSBrad Lewisfilesystem (string) 416000cce6bSBrad Lewis.Bd -ragged -compact -offset "xxxx" 417000cce6bSBrad LewisFilesystem to rollback. 418000cce6bSBrad Lewis.Ed 419b2d2f356SSara Hartse.It Em zfs.sync.set_prop(dataset, property, value) 420b2d2f356SSara HartseSets the given property on a dataset. 421b2d2f356SSara HartseCurrently only user properties are supported. 422b2d2f356SSara HartseReturns 0 if the property was set, or a nonzero error code otherwise. 423b2d2f356SSara Hartse.Pp 424b2d2f356SSara Hartsedataset (string) 425b2d2f356SSara Hartse.Bd -ragged -compact -offset "xxxx" 426b2d2f356SSara HartseThe dataset where the property will be set. 427b2d2f356SSara Hartse.Ed 428b2d2f356SSara Hartse.Pp 429b2d2f356SSara Hartseproperty (string) 430b2d2f356SSara Hartse.Bd -ragged -compact -offset "xxxx" 431b2d2f356SSara HartseThe property to set. 432b2d2f356SSara HartseOnly user properties are supported. 433b2d2f356SSara Hartse.Ed 434b2d2f356SSara Hartse.Pp 435b2d2f356SSara Hartsevalue (string) 436b2d2f356SSara Hartse.Bd -ragged -compact -offset "xxxx" 437b2d2f356SSara HartseThe value of the property to be set. 438b2d2f356SSara Hartse.Ed 4392840dce1SChris Williamson.It Em zfs.sync.snapshot(dataset) 4402840dce1SChris WilliamsonCreate a snapshot of a filesystem. 4412840dce1SChris WilliamsonReturns 0 if the snapshot was successfully created, 4422840dce1SChris Williamsonand a nonzero error code otherwise. 4432840dce1SChris Williamson.Pp 4442840dce1SChris WilliamsonNote: Taking a snapshot will fail on any pool older than legacy version 27. 4452840dce1SChris WilliamsonTo enable taking snapshots from ZCP scripts, the pool must be upgraded. 4462840dce1SChris Williamson.Pp 4472840dce1SChris Williamsondataset (string) 4482840dce1SChris Williamson.Bd -ragged -compact -offset "xxxx" 4492840dce1SChris WilliamsonName of snapshot to create. 4502840dce1SChris Williamson.Ed 451dfc11533SChris Williamson.El 452dfc11533SChris Williamson.It Sy zfs.check submodule 453dfc11533SChris WilliamsonFor each function in the zfs.sync submodule, there is a corresponding zfs.check 454dfc11533SChris Williamsonfunction which performs a "dry run" of the same operation. 455dfc11533SChris WilliamsonEach takes the same arguments as its zfs.sync counterpart and returns 0 if the 456dfc11533SChris Williamsonoperation would succeed, or a non-zero error code if it would fail, along with 457dfc11533SChris Williamsonany other error details. 458dfc11533SChris WilliamsonThat is, each has the same behavior as the corresponding sync function except 459dfc11533SChris Williamsonfor actually executing the requested change. 460dfc11533SChris WilliamsonFor example, 461dfc11533SChris Williamson.Em zfs.check.destroy("fs") 462dfc11533SChris Williamsonreturns 0 if 463dfc11533SChris Williamson.Em zfs.sync.destroy("fs") 464dfc11533SChris Williamsonwould successfully destroy the dataset. 465dfc11533SChris Williamson.Pp 466dfc11533SChris WilliamsonThe available zfs.check functions are: 467dfc11533SChris Williamson.Bl -tag -width "xx" 468d8f839f9SJason King.It Em zfs.check.change_key(dataset, key) 469dfc11533SChris Williamson.It Em zfs.check.destroy(dataset, [defer=true|false]) 470dfc11533SChris Williamson.It Em zfs.check.promote(dataset) 471000cce6bSBrad Lewis.It Em zfs.check.rollback(filesystem) 472b2d2f356SSara Hartse.It Em zfs.check.set_property(dataset, property, value) 4732840dce1SChris Williamson.It Em zfs.check.snapshot(dataset) 474dfc11533SChris Williamson.El 475dfc11533SChris Williamson.It Sy zfs.list submodule 476dfc11533SChris WilliamsonThe zfs.list submodule provides functions for iterating over datasets and 477dfc11533SChris Williamsonproperties. 478dfc11533SChris WilliamsonRather than returning tables, these functions act as Lua iterators, and are 479dfc11533SChris Williamsongenerally used as follows: 480dfc11533SChris Williamson.Bd -literal -offset indent 481dfc11533SChris Williamsonfor child in zfs.list.children("rpool") do 482dfc11533SChris Williamson ... 483dfc11533SChris Williamsonend 484dfc11533SChris Williamson.Ed 485dfc11533SChris Williamson.Pp 486dfc11533SChris WilliamsonThe available zfs.list functions are: 487dfc11533SChris Williamson.Bl -tag -width "xx" 488dfc11533SChris Williamson.It Em zfs.list.clones(snapshot) 489dfc11533SChris WilliamsonIterate through all clones of the given snapshot. 490dfc11533SChris Williamson.Pp 491dfc11533SChris Williamsonsnapshot (string) 492dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 493dfc11533SChris WilliamsonMust be a valid snapshot path in the current pool. 494dfc11533SChris Williamson.Ed 495dfc11533SChris Williamson.It Em zfs.list.snapshots(dataset) 496dfc11533SChris WilliamsonIterate through all snapshots of the given dataset. 497dfc11533SChris WilliamsonEach snapshot is returned as a string containing the full dataset name, e.g. 498dfc11533SChris Williamson"pool/fs@snap". 499dfc11533SChris Williamson.Pp 500dfc11533SChris Williamsondataset (string) 501dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 502dfc11533SChris WilliamsonMust be a valid filesystem or volume. 503dfc11533SChris Williamson.Ed 504dfc11533SChris Williamson.It Em zfs.list.children(dataset) 505dfc11533SChris WilliamsonIterate through all direct children of the given dataset. 506dfc11533SChris WilliamsonEach child is returned as a string containing the full dataset name, e.g. 507dfc11533SChris Williamson"pool/fs/child". 508dfc11533SChris Williamson.Pp 509dfc11533SChris Williamsondataset (string) 510dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 511dfc11533SChris WilliamsonMust be a valid filesystem or volume. 512dfc11533SChris Williamson.Ed 513dfc11533SChris Williamson.It Em zfs.list.properties(dataset) 514dfc11533SChris WilliamsonIterate through all user properties for the given dataset. 515dfc11533SChris Williamson.Pp 516dfc11533SChris Williamsondataset (string) 517dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 518dfc11533SChris WilliamsonMust be a valid filesystem, snapshot, or volume. 519dfc11533SChris Williamson.Ed 520dfc11533SChris Williamson.It Em zfs.list.system_properties(dataset) 521dfc11533SChris WilliamsonReturns an array of strings, the names of the valid system (non-user defined) 522dfc11533SChris Williamsonproperties for the given dataset. 523dfc11533SChris WilliamsonThrows a Lua error if the dataset is invalid. 524dfc11533SChris Williamson.Pp 525dfc11533SChris Williamsondataset (string) 526dfc11533SChris Williamson.Bd -ragged -compact -offset "xxxx" 527dfc11533SChris WilliamsonMust be a valid filesystem, snapshot or volume. 528dfc11533SChris Williamson.Ed 529dfc11533SChris Williamson.El 530dfc11533SChris Williamson.El 531dfc11533SChris Williamson.Sh EXAMPLES 532dfc11533SChris Williamson.Ss Example 1 533dfc11533SChris WilliamsonThe following channel program recursively destroys a filesystem and all its 534dfc11533SChris Williamsonsnapshots and children in a naive manner. 535dfc11533SChris WilliamsonNote that this does not involve any error handling or reporting. 536dfc11533SChris Williamson.Bd -literal -offset indent 537dfc11533SChris Williamsonfunction destroy_recursive(root) 538dfc11533SChris Williamson for child in zfs.list.children(root) do 539dfc11533SChris Williamson destroy_recursive(child) 540dfc11533SChris Williamson end 541dfc11533SChris Williamson for snap in zfs.list.snapshots(root) do 542dfc11533SChris Williamson zfs.sync.destroy(snap) 543dfc11533SChris Williamson end 544dfc11533SChris Williamson zfs.sync.destroy(root) 545dfc11533SChris Williamsonend 546dfc11533SChris Williamsondestroy_recursive("pool/somefs") 547dfc11533SChris Williamson.Ed 548dfc11533SChris Williamson.Ss Example 2 549dfc11533SChris WilliamsonA more verbose and robust version of the same channel program, which 550dfc11533SChris Williamsonproperly detects and reports errors, and also takes the dataset to destroy 551dfc11533SChris Williamsonas a command line argument, would be as follows: 552dfc11533SChris Williamson.Bd -literal -offset indent 553dfc11533SChris Williamsonsucceeded = {} 554dfc11533SChris Williamsonfailed = {} 555dfc11533SChris Williamson 556dfc11533SChris Williamsonfunction destroy_recursive(root) 557dfc11533SChris Williamson for child in zfs.list.children(root) do 558dfc11533SChris Williamson destroy_recursive(child) 559dfc11533SChris Williamson end 560dfc11533SChris Williamson for snap in zfs.list.snapshots(root) do 561dfc11533SChris Williamson err = zfs.sync.destroy(snap) 562dfc11533SChris Williamson if (err ~= 0) then 563dfc11533SChris Williamson failed[snap] = err 564dfc11533SChris Williamson else 565dfc11533SChris Williamson succeeded[snap] = err 566dfc11533SChris Williamson end 567dfc11533SChris Williamson end 568dfc11533SChris Williamson err = zfs.sync.destroy(root) 569dfc11533SChris Williamson if (err ~= 0) then 570dfc11533SChris Williamson failed[root] = err 571dfc11533SChris Williamson else 572dfc11533SChris Williamson succeeded[root] = err 573dfc11533SChris Williamson end 574dfc11533SChris Williamsonend 575dfc11533SChris Williamson 576dfc11533SChris Williamsonargs = ... 577dfc11533SChris Williamsonargv = args["argv"] 578dfc11533SChris Williamson 579dfc11533SChris Williamsondestroy_recursive(argv[1]) 580dfc11533SChris Williamson 581dfc11533SChris Williamsonresults = {} 582dfc11533SChris Williamsonresults["succeeded"] = succeeded 583dfc11533SChris Williamsonresults["failed"] = failed 584dfc11533SChris Williamsonreturn results 585dfc11533SChris Williamson.Ed 586dfc11533SChris Williamson.Ss Example 3 587dfc11533SChris WilliamsonThe following function performs a forced promote operation by attempting to 588dfc11533SChris Williamsonpromote the given clone and destroying any conflicting snapshots. 589dfc11533SChris Williamson.Bd -literal -offset indent 590dfc11533SChris Williamsonfunction force_promote(ds) 591dfc11533SChris Williamson errno, details = zfs.check.promote(ds) 592dfc11533SChris Williamson if (errno == EEXIST) then 593dfc11533SChris Williamson assert(details ~= Nil) 594dfc11533SChris Williamson for i, snap in ipairs(details) do 595dfc11533SChris Williamson zfs.sync.destroy(ds .. "@" .. snap) 596dfc11533SChris Williamson end 597dfc11533SChris Williamson elseif (errno ~= 0) then 598dfc11533SChris Williamson return errno 599dfc11533SChris Williamson end 600dfc11533SChris Williamson return zfs.sync.promote(ds) 601dfc11533SChris Williamsonend 602dfc11533SChris Williamson.Ed 603