4 * This file and its contents are supplied under the terms of the
5 * Common Development and Distribution License ("CDDL"), version 1.0.
6 * You may only use this file in accordance with the terms of version
9 * A full copy of the text of the CDDL should have accompanied this
10 * source. A copy of the CDDL is also available via the Internet at
11 * http://www.illumos.org/license/CDDL.
17 * Copyright (c) 2016, 2017 by Delphix. All rights reserved.
21 * ZFS Channel Programs (ZCP)
23 * The ZCP interface allows various ZFS commands and operations ZFS
24 * administrative operations (e.g. creating and destroying snapshots, typically
25 * performed via an ioctl to /dev/zfs by the zfs(1M) command and
26 * libzfs/libzfs_core) to be run * programmatically as a Lua script. A ZCP
27 * script is run as a dsl_sync_task and fully executed during one transaction
28 * group sync. This ensures that no other changes can be written concurrently
29 * with a running Lua script. Combining multiple calls to the exposed ZFS
30 * functions into one script gives a number of benefits:
32 * 1. Atomicity. For some compound or iterative operations, it's useful to be
33 * able to guarantee that the state of a pool has not changed between calls to
36 * 2. Performance. If a large number of changes need to be made (e.g. deleting
37 * many filesystems), there can be a significant performance penalty as a
38 * result of the need to wait for a transaction group sync to pass for every
39 * single operation. When expressed as a single ZCP script, all these changes
40 * can be performed at once in one txg sync.
42 * A modified version of the Lua 5.2 interpreter is used to run channel program
43 * scripts. The Lua 5.2 manual can be found at:
45 * http://www.lua.org/manual/5.2/
47 * If being run by a user (via an ioctl syscall), executing a ZCP script
48 * requires root privileges in the global zone.
50 * Scripts are passed to zcp_eval() as a string, then run in a synctask by
51 * zcp_eval_sync(). Arguments can be passed into the Lua script as an nvlist,
52 * which will be converted to a Lua table. Similarly, values returned from
53 * a ZCP script will be converted to an nvlist. See zcp_lua_to_nvlist_impl()
54 * for details on exact allowed types and conversion.
56 * ZFS functionality is exposed to a ZCP script as a library of function calls.
57 * These calls are sorted into submodules, such as zfs.list and zfs.sync, for
58 * iterators and synctasks, respectively. Each of these submodules resides in
59 * its own source file, with a zcp_*_info structure describing each library
60 * call in the submodule.
62 * Error handling in ZCP scripts is handled by a number of different methods
65 * 1. Memory and time limits are in place to prevent a channel program from
66 * consuming excessive system or running forever. If one of these limits is
67 * hit, the channel program will be stopped immediately and return from
68 * zcp_eval() with an error code. No attempt will be made to roll back or undo
69 * any changes made by the channel program before the error occured.
70 * Consumers invoking zcp_eval() from elsewhere in the kernel may pass a time
71 * limit of 0, disabling the time limit.
73 * 2. Internal Lua errors can occur as a result of a syntax error, calling a
74 * library function with incorrect arguments, invoking the error() function,
75 * failing an assert(), or other runtime errors. In these cases the channel
76 * program will stop executing and return from zcp_eval() with an error code.
77 * In place of a return value, an error message will also be returned in the
78 * 'result' nvlist containing information about the error. No attempt will be
79 * made to roll back or undo any changes made by the channel program before the
82 * 3. If an error occurs inside a ZFS library call which returns an error code,
83 * the error is returned to the Lua script to be handled as desired.
85 * In the first two cases, Lua's error-throwing mechanism is used, which
86 * longjumps out of the script execution with luaL_error() and returns with the
89 * See zfs-program(1M) for more information on high level usage.
96 #include <sys/dsl_prop.h>
97 #include <sys/dsl_synctask.h>
98 #include <sys/dsl_dataset.h>
100 #include <sys/zcp_iter.h>
101 #include <sys/zcp_prop.h>
102 #include <sys/zcp_global.h>
104 #include <util/sscanf.h>
109 #define ETIME ETIMEDOUT
112 #define ZCP_NVLIST_MAX_DEPTH 20
114 uint64_t zfs_lua_check_instrlimit_interval = 100;
115 uint64_t zfs_lua_max_instrlimit = ZCP_MAX_INSTRLIMIT;
116 uint64_t zfs_lua_max_memlimit = ZCP_MAX_MEMLIMIT;
119 * Forward declarations for mutually recursive functions
121 static int zcp_nvpair_value_to_lua(lua_State *, nvpair_t *, char *, int);
122 static int zcp_lua_to_nvlist_impl(lua_State *, int, nvlist_t *, const char *,
125 typedef struct zcp_alloc_arg {
126 boolean_t aa_must_succeed;
127 int64_t aa_alloc_remaining;
128 int64_t aa_alloc_limit;
131 typedef struct zcp_eval_arg {
133 zcp_alloc_arg_t *ea_allocargs;
137 uint64_t ea_instrlimit;
141 * The outer-most error callback handler for use with lua_pcall(). On
142 * error Lua will call this callback with a single argument that
143 * represents the error value. In most cases this will be a string
144 * containing an error message, but channel programs can use Lua's
145 * error() function to return arbitrary objects as errors. This callback
146 * returns (on the Lua stack) the original error object along with a traceback.
148 * Fatal Lua errors can occur while resources are held, so we also call any
149 * registered cleanup function here.
152 zcp_error_handler(lua_State *state)
158 VERIFY3U(1, ==, lua_gettop(state));
159 msg = lua_tostring(state, 1);
160 luaL_traceback(state, state, msg, 1);
165 zcp_argerror(lua_State *state, int narg, const char *msg, ...)
169 va_start(alist, msg);
170 const char *buf = lua_pushvfstring(state, msg, alist);
173 return (luaL_argerror(state, narg, buf));
177 * Install a new cleanup function, which will be invoked with the given
178 * opaque argument if a fatal error causes the Lua interpreter to longjump out
179 * of a function call.
181 * If an error occurs, the cleanup function will be invoked exactly once and
184 * Returns the registered cleanup handler so the caller can deregister it
185 * if no error occurs.
187 zcp_cleanup_handler_t *
188 zcp_register_cleanup(lua_State *state, zcp_cleanup_t cleanfunc, void *cleanarg)
190 zcp_run_info_t *ri = zcp_run_info(state);
192 zcp_cleanup_handler_t *zch = kmem_alloc(sizeof (*zch), KM_SLEEP);
193 zch->zch_cleanup_func = cleanfunc;
194 zch->zch_cleanup_arg = cleanarg;
195 list_insert_head(&ri->zri_cleanup_handlers, zch);
201 zcp_deregister_cleanup(lua_State *state, zcp_cleanup_handler_t *zch)
203 zcp_run_info_t *ri = zcp_run_info(state);
204 list_remove(&ri->zri_cleanup_handlers, zch);
205 kmem_free(zch, sizeof (*zch));
209 * Execute the currently registered cleanup handlers then free them and
210 * destroy the handler list.
213 zcp_cleanup(lua_State *state)
215 zcp_run_info_t *ri = zcp_run_info(state);
217 for (zcp_cleanup_handler_t *zch =
218 list_remove_head(&ri->zri_cleanup_handlers); zch != NULL;
219 zch = list_remove_head(&ri->zri_cleanup_handlers)) {
220 zch->zch_cleanup_func(zch->zch_cleanup_arg);
221 kmem_free(zch, sizeof (*zch));
226 * Convert the lua table at the given index on the Lua stack to an nvlist
229 * If the table can not be converted for any reason, NULL is returned and
230 * an error message is pushed onto the Lua stack.
233 zcp_table_to_nvlist(lua_State *state, int index, int depth)
237 * Converting a Lua table to an nvlist with key uniqueness checking is
238 * O(n^2) in the number of keys in the nvlist, which can take a long
239 * time when we return a large table from a channel program.
240 * Furthermore, Lua's table interface *almost* guarantees unique keys
241 * on its own (details below). Therefore, we don't use fnvlist_alloc()
242 * here to avoid the built-in uniqueness checking.
244 * The *almost* is because it's possible to have key collisions between
245 * e.g. the string "1" and the number 1, or the string "true" and the
246 * boolean true, so we explicitly check that when we're looking at a
247 * key which is an integer / boolean or a string that can be parsed as
248 * one of those types. In the worst case this could still devolve into
249 * O(n^2), so we only start doing these checks on boolean/integer keys
250 * once we've seen a string key which fits this weird usage pattern.
252 * Ultimately, we still want callers to know that the keys in this
253 * nvlist are unique, so before we return this we set the nvlist's
254 * flags to reflect that.
256 VERIFY0(nvlist_alloc(&nvl, 0, KM_SLEEP));
259 * Push an empty stack slot where lua_next() will store each
263 boolean_t saw_str_could_collide = B_FALSE;
264 while (lua_next(state, index) != 0) {
266 * The next key-value pair from the table at index is
267 * now on the stack, with the key at stack slot -2 and
268 * the value at slot -1.
272 const char *key = NULL;
273 boolean_t key_could_collide = B_FALSE;
275 switch (lua_type(state, -2)) {
277 key = lua_tostring(state, -2);
279 /* check if this could collide with a number or bool */
282 if ((sscanf(key, "%lld%n", &tmp, &parselen) > 0 &&
283 parselen == strlen(key)) ||
284 strcmp(key, "true") == 0 ||
285 strcmp(key, "false") == 0) {
286 key_could_collide = B_TRUE;
287 saw_str_could_collide = B_TRUE;
291 key = (lua_toboolean(state, -2) == B_TRUE ?
293 if (saw_str_could_collide) {
294 key_could_collide = B_TRUE;
298 VERIFY3U(sizeof (buf), >,
299 snprintf(buf, sizeof (buf), "%lld",
300 (longlong_t)lua_tonumber(state, -2)));
302 if (saw_str_could_collide) {
303 key_could_collide = B_TRUE;
308 (void) lua_pushfstring(state, "Invalid key "
309 "type '%s' in table",
310 lua_typename(state, lua_type(state, -2)));
314 * Check for type-mismatched key collisions, and throw an error.
316 if (key_could_collide && nvlist_exists(nvl, key)) {
318 (void) lua_pushfstring(state, "Collision of "
319 "key '%s' in table", key);
323 * Recursively convert the table value and insert into
324 * the new nvlist with the parsed key. To prevent
325 * stack overflow on circular or heavily nested tables,
326 * we track the current nvlist depth.
328 if (depth >= ZCP_NVLIST_MAX_DEPTH) {
330 (void) lua_pushfstring(state, "Maximum table "
331 "depth (%d) exceeded for table",
332 ZCP_NVLIST_MAX_DEPTH);
335 err = zcp_lua_to_nvlist_impl(state, -1, nvl, key,
340 * Error message has been pushed to the lua
341 * stack by the recursive call.
346 * Pop the value pushed by lua_next().
352 * Mark the nvlist as having unique keys. This is a little ugly, but we
353 * ensured above that there are no duplicate keys in the nvlist.
355 nvl->nvl_nvflag |= NV_UNIQUE_NAME;
361 * Convert a value from the given index into the lua stack to an nvpair, adding
362 * it to an nvlist with the given key.
364 * Values are converted as follows:
369 * nil -> boolean (no value)
371 * Lua tables are converted to nvlists and then inserted. The table's keys
372 * are converted to strings then used as keys in the nvlist to store each table
373 * element. Keys are converted as follows:
375 * string -> no change
377 * boolean -> "true" | "false"
380 * In the case of a key collision, an error is thrown.
382 * If an error is encountered, a nonzero error code is returned, and an error
383 * string will be pushed onto the Lua stack.
386 zcp_lua_to_nvlist_impl(lua_State *state, int index, nvlist_t *nvl,
387 const char *key, int depth)
390 * Verify that we have enough remaining space in the lua stack to parse
391 * a key-value pair and push an error.
393 if (!lua_checkstack(state, 3)) {
394 (void) lua_pushstring(state, "Lua stack overflow");
398 index = lua_absindex(state, index);
400 switch (lua_type(state, index)) {
402 fnvlist_add_boolean(nvl, key);
405 fnvlist_add_boolean_value(nvl, key,
406 lua_toboolean(state, index));
409 fnvlist_add_int64(nvl, key, lua_tonumber(state, index));
412 fnvlist_add_string(nvl, key, lua_tostring(state, index));
415 nvlist_t *value_nvl = zcp_table_to_nvlist(state, index, depth);
416 if (value_nvl == NULL)
419 fnvlist_add_nvlist(nvl, key, value_nvl);
420 fnvlist_free(value_nvl);
424 (void) lua_pushfstring(state,
425 "Invalid value type '%s' for key '%s'",
426 lua_typename(state, lua_type(state, index)), key);
434 * Convert a lua value to an nvpair, adding it to an nvlist with the given key.
437 zcp_lua_to_nvlist(lua_State *state, int index, nvlist_t *nvl, const char *key)
440 * On error, zcp_lua_to_nvlist_impl pushes an error string onto the Lua
441 * stack before returning with a nonzero error code. If an error is
442 * returned, throw a fatal lua error with the given string.
444 if (zcp_lua_to_nvlist_impl(state, index, nvl, key, 0) != 0)
445 (void) lua_error(state);
449 zcp_lua_to_nvlist_helper(lua_State *state)
451 nvlist_t *nv = (nvlist_t *)lua_touserdata(state, 2);
452 const char *key = (const char *)lua_touserdata(state, 1);
453 zcp_lua_to_nvlist(state, 3, nv, key);
458 zcp_convert_return_values(lua_State *state, nvlist_t *nvl,
459 const char *key, zcp_eval_arg_t *evalargs)
462 VERIFY3U(1, ==, lua_gettop(state));
463 lua_pushcfunction(state, zcp_lua_to_nvlist_helper);
464 lua_pushlightuserdata(state, (char *)key);
465 lua_pushlightuserdata(state, nvl);
466 lua_pushvalue(state, 1);
467 lua_remove(state, 1);
468 err = lua_pcall(state, 3, 0, 0); /* zcp_lua_to_nvlist_helper */
470 zcp_lua_to_nvlist(state, 1, nvl, ZCP_RET_ERROR);
471 evalargs->ea_result = SET_ERROR(ECHRNG);
476 * Push a Lua table representing nvl onto the stack. If it can't be
477 * converted, return EINVAL, fill in errbuf, and push nothing. errbuf may
478 * be specified as NULL, in which case no error string will be output.
480 * Most nvlists are converted as simple key->value Lua tables, but we make
481 * an exception for the case where all nvlist entries are BOOLEANs (a string
482 * key without a value). In Lua, a table key pointing to a value of Nil
483 * (no value) is equivalent to the key not existing, so a BOOLEAN nvlist
484 * entry can't be directly converted to a Lua table entry. Nvlists of entirely
485 * BOOLEAN entries are frequently used to pass around lists of datasets, so for
486 * convenience we check for this case, and convert it to a simple Lua array of
490 zcp_nvlist_to_lua(lua_State *state, nvlist_t *nvl,
491 char *errbuf, int errbuf_len)
495 boolean_t has_values = B_FALSE;
497 * If the list doesn't have any values, just convert it to a string
500 for (pair = nvlist_next_nvpair(nvl, NULL);
501 pair != NULL; pair = nvlist_next_nvpair(nvl, pair)) {
502 if (nvpair_type(pair) != DATA_TYPE_BOOLEAN) {
509 for (pair = nvlist_next_nvpair(nvl, NULL);
510 pair != NULL; pair = nvlist_next_nvpair(nvl, pair)) {
511 (void) lua_pushinteger(state, i);
512 (void) lua_pushstring(state, nvpair_name(pair));
513 (void) lua_settable(state, -3);
517 for (pair = nvlist_next_nvpair(nvl, NULL);
518 pair != NULL; pair = nvlist_next_nvpair(nvl, pair)) {
519 int err = zcp_nvpair_value_to_lua(state, pair,
525 (void) lua_setfield(state, -2, nvpair_name(pair));
532 * Push a Lua object representing the value of "pair" onto the stack.
534 * Only understands boolean_value, string, int64, nvlist,
535 * string_array, and int64_array type values. For other
536 * types, returns EINVAL, fills in errbuf, and pushes nothing.
539 zcp_nvpair_value_to_lua(lua_State *state, nvpair_t *pair,
540 char *errbuf, int errbuf_len)
549 switch (nvpair_type(pair)) {
550 case DATA_TYPE_BOOLEAN_VALUE:
551 (void) lua_pushboolean(state,
552 fnvpair_value_boolean_value(pair));
554 case DATA_TYPE_STRING:
555 (void) lua_pushstring(state, fnvpair_value_string(pair));
557 case DATA_TYPE_INT64:
558 (void) lua_pushinteger(state, fnvpair_value_int64(pair));
560 case DATA_TYPE_NVLIST:
561 err = zcp_nvlist_to_lua(state,
562 fnvpair_value_nvlist(pair), errbuf, errbuf_len);
564 case DATA_TYPE_STRING_ARRAY: {
567 (void) nvpair_value_string_array(pair, &strarr, &nelem);
569 for (int i = 0; i < nelem; i++) {
570 (void) lua_pushinteger(state, i + 1);
571 (void) lua_pushstring(state, strarr[i]);
572 (void) lua_settable(state, -3);
576 case DATA_TYPE_UINT64_ARRAY: {
579 (void) nvpair_value_uint64_array(pair, &intarr, &nelem);
581 for (int i = 0; i < nelem; i++) {
582 (void) lua_pushinteger(state, i + 1);
583 (void) lua_pushinteger(state, intarr[i]);
584 (void) lua_settable(state, -3);
588 case DATA_TYPE_INT64_ARRAY: {
591 (void) nvpair_value_int64_array(pair, &intarr, &nelem);
593 for (int i = 0; i < nelem; i++) {
594 (void) lua_pushinteger(state, i + 1);
595 (void) lua_pushinteger(state, intarr[i]);
596 (void) lua_settable(state, -3);
601 if (errbuf != NULL) {
602 (void) snprintf(errbuf, errbuf_len,
603 "Unhandled nvpair type %d for key '%s'",
604 nvpair_type(pair), nvpair_name(pair));
613 zcp_dataset_hold_error(lua_State *state, dsl_pool_t *dp, const char *dsname,
616 if (error == ENOENT) {
617 (void) zcp_argerror(state, 1, "no such dataset '%s'", dsname);
618 return (0); /* not reached; zcp_argerror will longjmp */
619 } else if (error == EXDEV) {
620 (void) zcp_argerror(state, 1,
621 "dataset '%s' is not in the target pool '%s'",
622 dsname, spa_name(dp->dp_spa));
623 return (0); /* not reached; zcp_argerror will longjmp */
624 } else if (error == EIO) {
625 (void) luaL_error(state,
626 "I/O error while accessing dataset '%s'", dsname);
627 return (0); /* not reached; luaL_error will longjmp */
628 } else if (error != 0) {
629 (void) luaL_error(state,
630 "unexpected error %d while accessing dataset '%s'",
632 return (0); /* not reached; luaL_error will longjmp */
638 * Note: will longjmp (via lua_error()) on error.
639 * Assumes that the dsname is argument #1 (for error reporting purposes).
642 zcp_dataset_hold(lua_State *state, dsl_pool_t *dp, const char *dsname,
646 int error = dsl_dataset_hold(dp, dsname, tag, &ds);
647 (void) zcp_dataset_hold_error(state, dp, dsname, error);
651 static int zcp_debug(lua_State *);
652 static zcp_lib_info_t zcp_debug_info = {
656 { .za_name = "debug string", .za_lua_type = LUA_TSTRING},
665 zcp_debug(lua_State *state)
667 const char *dbgstring;
668 zcp_run_info_t *ri = zcp_run_info(state);
669 zcp_lib_info_t *libinfo = &zcp_debug_info;
671 zcp_parse_args(state, libinfo->name, libinfo->pargs, libinfo->kwargs);
673 dbgstring = lua_tostring(state, 1);
675 zfs_dbgmsg("txg %lld ZCP: %s", ri->zri_tx->tx_txg, dbgstring);
680 static int zcp_exists(lua_State *);
681 static zcp_lib_info_t zcp_exists_info = {
685 { .za_name = "dataset", .za_lua_type = LUA_TSTRING},
694 zcp_exists(lua_State *state)
696 zcp_run_info_t *ri = zcp_run_info(state);
697 dsl_pool_t *dp = ri->zri_pool;
698 zcp_lib_info_t *libinfo = &zcp_exists_info;
700 zcp_parse_args(state, libinfo->name, libinfo->pargs, libinfo->kwargs);
702 const char *dsname = lua_tostring(state, 1);
705 int error = dsl_dataset_hold(dp, dsname, FTAG, &ds);
707 dsl_dataset_rele(ds, FTAG);
708 lua_pushboolean(state, B_TRUE);
709 } else if (error == ENOENT) {
710 lua_pushboolean(state, B_FALSE);
711 } else if (error == EXDEV) {
712 return (luaL_error(state, "dataset '%s' is not in the "
713 "target pool", dsname));
714 } else if (error == EIO) {
715 return (luaL_error(state, "I/O error opening dataset '%s'",
717 } else if (error != 0) {
718 return (luaL_error(state, "unexpected error %d", error));
725 * Allocate/realloc/free a buffer for the lua interpreter.
727 * When nsize is 0, behaves as free() and returns NULL.
729 * If ptr is NULL, behaves as malloc() and returns an allocated buffer of size
732 * Otherwise, behaves as realloc(), changing the allocation from osize to nsize.
733 * Shrinking the buffer size never fails.
735 * The original allocated buffer size is stored as a uint64 at the beginning of
736 * the buffer to avoid actually reallocating when shrinking a buffer, since lua
737 * requires that this operation never fail.
740 zcp_lua_alloc(void *ud, void *ptr, size_t osize, size_t nsize)
742 zcp_alloc_arg_t *allocargs = ud;
743 int flags = (allocargs->aa_must_succeed) ?
744 KM_SLEEP : (KM_NOSLEEP | KM_NORMALPRI);
748 int64_t *allocbuf = (int64_t *)ptr - 1;
749 int64_t allocsize = *allocbuf;
750 ASSERT3S(allocsize, >, 0);
751 ASSERT3S(allocargs->aa_alloc_remaining + allocsize, <=,
752 allocargs->aa_alloc_limit);
753 allocargs->aa_alloc_remaining += allocsize;
754 kmem_free(allocbuf, allocsize);
757 } else if (ptr == NULL) {
759 int64_t allocsize = nsize + sizeof (int64_t);
761 if (!allocargs->aa_must_succeed &&
763 allocsize > allocargs->aa_alloc_remaining)) {
767 allocbuf = kmem_alloc(allocsize, flags);
768 if (allocbuf == NULL) {
771 allocargs->aa_alloc_remaining -= allocsize;
773 *allocbuf = allocsize;
774 return (allocbuf + 1);
775 } else if (nsize <= osize) {
777 * If shrinking the buffer, lua requires that the reallocation
782 ASSERT3U(nsize, >, osize);
784 uint64_t *luabuf = zcp_lua_alloc(ud, NULL, 0, nsize);
785 if (luabuf == NULL) {
788 (void) memcpy(luabuf, ptr, osize);
789 VERIFY3P(zcp_lua_alloc(ud, ptr, osize, 0), ==, NULL);
796 zcp_lua_counthook(lua_State *state, lua_Debug *ar)
799 * If we're called, check how many instructions the channel program has
800 * executed so far, and compare against the limit.
802 lua_getfield(state, LUA_REGISTRYINDEX, ZCP_RUN_INFO_KEY);
803 zcp_run_info_t *ri = lua_touserdata(state, -1);
805 ri->zri_curinstrs += zfs_lua_check_instrlimit_interval;
806 if (ri->zri_maxinstrs != 0 && ri->zri_curinstrs > ri->zri_maxinstrs) {
807 ri->zri_timed_out = B_TRUE;
808 (void) lua_pushstring(state,
809 "Channel program timed out.");
810 (void) lua_error(state);
815 zcp_panic_cb(lua_State *state)
817 panic("unprotected error in call to Lua API (%s)\n",
818 lua_tostring(state, -1));
823 zcp_eval_impl(dmu_tx_t *tx, boolean_t sync, zcp_eval_arg_t *evalargs)
827 lua_State *state = evalargs->ea_state;
829 VERIFY3U(3, ==, lua_gettop(state));
832 * Store the zcp_run_info_t struct for this run in the Lua registry.
833 * Registry entries are not directly accessible by the Lua scripts but
834 * can be accessed by our callbacks.
836 ri.zri_space_used = 0;
837 ri.zri_pool = dmu_tx_pool(tx);
838 ri.zri_cred = evalargs->ea_cred;
840 ri.zri_timed_out = B_FALSE;
842 list_create(&ri.zri_cleanup_handlers, sizeof (zcp_cleanup_handler_t),
843 offsetof(zcp_cleanup_handler_t, zch_node));
844 ri.zri_curinstrs = 0;
845 ri.zri_maxinstrs = evalargs->ea_instrlimit;
847 lua_pushlightuserdata(state, &ri);
848 lua_setfield(state, LUA_REGISTRYINDEX, ZCP_RUN_INFO_KEY);
849 VERIFY3U(3, ==, lua_gettop(state));
852 * Tell the Lua interpreter to call our handler every count
853 * instructions. Channel programs that execute too many instructions
854 * should die with ETIMEDOUT.
856 (void) lua_sethook(state, zcp_lua_counthook, LUA_MASKCOUNT,
857 zfs_lua_check_instrlimit_interval);
860 * Tell the Lua memory allocator to stop using KM_SLEEP before handing
861 * off control to the channel program. Channel programs that use too
862 * much memory should die with ENOSPC.
864 evalargs->ea_allocargs->aa_must_succeed = B_FALSE;
867 * Call the Lua function that open-context passed us. This pops the
868 * function and its input from the stack and pushes any return
871 err = lua_pcall(state, 1, LUA_MULTRET, 1);
874 * Let Lua use KM_SLEEP while we interpret the return values.
876 evalargs->ea_allocargs->aa_must_succeed = B_TRUE;
879 * Remove the error handler callback from the stack. At this point,
880 * there shouldn't be any cleanup handler registered in the handler
881 * list (zri_cleanup_handlers), regardless of whether it ran or not.
883 list_destroy(&ri.zri_cleanup_handlers);
884 lua_remove(state, 1);
889 * Lua supports returning multiple values in a single return
890 * statement. Return values will have been pushed onto the
895 * To simplify the process of retrieving a return value from a
896 * channel program, we disallow returning more than one value
897 * to ZFS from the Lua script, yielding a singleton return
898 * nvlist of the form { "return": Return value 1 }.
900 int return_count = lua_gettop(state);
902 if (return_count == 1) {
903 evalargs->ea_result = 0;
904 zcp_convert_return_values(state, evalargs->ea_outnvl,
905 ZCP_RET_RETURN, evalargs);
906 } else if (return_count > 1) {
907 evalargs->ea_result = SET_ERROR(ECHRNG);
908 lua_settop(state, 0);
909 (void) lua_pushfstring(state, "Multiple return "
910 "values not supported");
911 zcp_convert_return_values(state, evalargs->ea_outnvl,
912 ZCP_RET_ERROR, evalargs);
919 * The channel program encountered a fatal error within the
920 * script, such as failing an assertion, or calling a function
921 * with incompatible arguments. The error value and the
922 * traceback generated by zcp_error_handler() should be on the
925 VERIFY3U(1, ==, lua_gettop(state));
926 if (ri.zri_timed_out) {
927 evalargs->ea_result = SET_ERROR(ETIME);
929 evalargs->ea_result = SET_ERROR(ECHRNG);
932 zcp_convert_return_values(state, evalargs->ea_outnvl,
933 ZCP_RET_ERROR, evalargs);
938 * The channel program encountered a fatal error within the
939 * script, and we encountered another error while trying to
940 * compute the traceback in zcp_error_handler(). We can only
941 * return the error message.
943 VERIFY3U(1, ==, lua_gettop(state));
944 if (ri.zri_timed_out) {
945 evalargs->ea_result = SET_ERROR(ETIME);
947 evalargs->ea_result = SET_ERROR(ECHRNG);
950 zcp_convert_return_values(state, evalargs->ea_outnvl,
951 ZCP_RET_ERROR, evalargs);
956 * Lua ran out of memory while running the channel program.
957 * There's not much we can do.
959 evalargs->ea_result = SET_ERROR(ENOSPC);
967 zcp_pool_error(zcp_eval_arg_t *evalargs, const char *poolname)
969 evalargs->ea_result = SET_ERROR(ECHRNG);
970 lua_settop(evalargs->ea_state, 0);
971 (void) lua_pushfstring(evalargs->ea_state, "Could not open pool: %s",
973 zcp_convert_return_values(evalargs->ea_state, evalargs->ea_outnvl,
974 ZCP_RET_ERROR, evalargs);
979 zcp_eval_sync(void *arg, dmu_tx_t *tx)
981 zcp_eval_arg_t *evalargs = arg;
984 * Open context should have setup the stack to contain:
985 * 1: Error handler callback
986 * 2: Script to run (converted to a Lua function)
987 * 3: nvlist input to function (converted to Lua table or nil)
989 VERIFY3U(3, ==, lua_gettop(evalargs->ea_state));
991 zcp_eval_impl(tx, B_TRUE, evalargs);
995 zcp_eval_open(zcp_eval_arg_t *evalargs, const char *poolname)
1003 * See comment from the same assertion in zcp_eval_sync().
1005 VERIFY3U(3, ==, lua_gettop(evalargs->ea_state));
1007 error = dsl_pool_hold(poolname, FTAG, &dp);
1009 zcp_pool_error(evalargs, poolname);
1014 * As we are running in open-context, we have no transaction associated
1015 * with the channel program. At the same time, functions from the
1016 * zfs.check submodule need to be associated with a transaction as
1017 * they are basically dry-runs of their counterparts in the zfs.sync
1018 * submodule. These functions should be able to run in open-context.
1019 * Therefore we create a new transaction that we later abort once
1020 * the channel program has been evaluated.
1022 tx = dmu_tx_create_dd(dp->dp_mos_dir);
1024 zcp_eval_impl(tx, B_FALSE, evalargs);
1028 dsl_pool_rele(dp, FTAG);
1032 zcp_eval(const char *poolname, const char *program, boolean_t sync,
1033 uint64_t instrlimit, uint64_t memlimit, nvpair_t *nvarg, nvlist_t *outnvl)
1037 zcp_eval_arg_t evalargs;
1039 if (instrlimit > zfs_lua_max_instrlimit)
1040 return (SET_ERROR(EINVAL));
1041 if (memlimit == 0 || memlimit > zfs_lua_max_memlimit)
1042 return (SET_ERROR(EINVAL));
1044 zcp_alloc_arg_t allocargs = {
1045 .aa_must_succeed = B_TRUE,
1046 .aa_alloc_remaining = (int64_t)memlimit,
1047 .aa_alloc_limit = (int64_t)memlimit,
1051 * Creates a Lua state with a memory allocator that uses KM_SLEEP.
1052 * This should never fail.
1054 state = lua_newstate(zcp_lua_alloc, &allocargs);
1055 VERIFY(state != NULL);
1056 (void) lua_atpanic(state, zcp_panic_cb);
1059 * Load core Lua libraries we want access to.
1061 VERIFY3U(1, ==, luaopen_base(state));
1063 VERIFY3U(1, ==, luaopen_coroutine(state));
1064 lua_setglobal(state, LUA_COLIBNAME);
1065 VERIFY0(lua_gettop(state));
1066 VERIFY3U(1, ==, luaopen_string(state));
1067 lua_setglobal(state, LUA_STRLIBNAME);
1068 VERIFY0(lua_gettop(state));
1069 VERIFY3U(1, ==, luaopen_table(state));
1070 lua_setglobal(state, LUA_TABLIBNAME);
1071 VERIFY0(lua_gettop(state));
1074 * Load globally visible variables such as errno aliases.
1076 zcp_load_globals(state);
1077 VERIFY0(lua_gettop(state));
1080 * Load ZFS-specific modules.
1082 lua_newtable(state);
1083 VERIFY3U(1, ==, zcp_load_list_lib(state));
1084 lua_setfield(state, -2, "list");
1085 VERIFY3U(1, ==, zcp_load_synctask_lib(state, B_FALSE));
1086 lua_setfield(state, -2, "check");
1087 VERIFY3U(1, ==, zcp_load_synctask_lib(state, B_TRUE));
1088 lua_setfield(state, -2, "sync");
1089 VERIFY3U(1, ==, zcp_load_get_lib(state));
1090 lua_pushcclosure(state, zcp_debug_info.func, 0);
1091 lua_setfield(state, -2, zcp_debug_info.name);
1092 lua_pushcclosure(state, zcp_exists_info.func, 0);
1093 lua_setfield(state, -2, zcp_exists_info.name);
1094 lua_setglobal(state, "zfs");
1095 VERIFY0(lua_gettop(state));
1098 * Push the error-callback that calculates Lua stack traces on
1099 * unexpected failures.
1101 lua_pushcfunction(state, zcp_error_handler);
1102 VERIFY3U(1, ==, lua_gettop(state));
1105 * Load the actual script as a function onto the stack as text ("t").
1106 * The only valid error condition is a syntax error in the script.
1107 * ERRMEM should not be possible because our allocator is using
1108 * KM_SLEEP. ERRGCMM should not be possible because we have not added
1109 * any objects with __gc metamethods to the interpreter that could
1112 err = luaL_loadbufferx(state, program, strlen(program),
1113 "channel program", "t");
1114 if (err == LUA_ERRSYNTAX) {
1115 fnvlist_add_string(outnvl, ZCP_RET_ERROR,
1116 lua_tostring(state, -1));
1118 return (SET_ERROR(EINVAL));
1121 VERIFY3U(2, ==, lua_gettop(state));
1124 * Convert the input nvlist to a Lua object and put it on top of the
1128 err = zcp_nvpair_value_to_lua(state, nvarg,
1129 errmsg, sizeof (errmsg));
1131 fnvlist_add_string(outnvl, ZCP_RET_ERROR, errmsg);
1133 return (SET_ERROR(EINVAL));
1135 VERIFY3U(3, ==, lua_gettop(state));
1137 evalargs.ea_state = state;
1138 evalargs.ea_allocargs = &allocargs;
1139 evalargs.ea_instrlimit = instrlimit;
1140 evalargs.ea_cred = CRED();
1141 evalargs.ea_outnvl = outnvl;
1142 evalargs.ea_result = 0;
1145 err = dsl_sync_task(poolname, NULL,
1146 zcp_eval_sync, &evalargs, 0, ZFS_SPACE_CHECK_ZCP_EVAL);
1148 zcp_pool_error(&evalargs, poolname);
1150 zcp_eval_open(&evalargs, poolname);
1154 return (evalargs.ea_result);
1158 * Retrieve metadata about the currently running channel program.
1161 zcp_run_info(lua_State *state)
1165 lua_getfield(state, LUA_REGISTRYINDEX, ZCP_RUN_INFO_KEY);
1166 ri = lua_touserdata(state, -1);
1175 * The Lua language allows methods to be called with any number
1176 * of arguments of any type. When calling back into ZFS we need to sanitize
1177 * arguments from channel programs to make sure unexpected arguments or
1178 * arguments of the wrong type result in clear error messages. To do this
1179 * in a uniform way all callbacks from channel programs should use the
1180 * zcp_parse_args() function to interpret inputs.
1182 * Positional vs Keyword Arguments
1183 * ===============================
1185 * Every callback function takes a fixed set of required positional arguments
1186 * and optional keyword arguments. For example, the destroy function takes
1187 * a single positional string argument (the name of the dataset to destroy)
1188 * and an optional "defer" keyword boolean argument. When calling lua functions
1189 * with parentheses, only positional arguments can be used:
1191 * zfs.sync.snapshot("rpool@snap")
1193 * To use keyword arguments functions should be called with a single argument
1194 * that is a lua table containing mappings of integer -> positional arguments
1195 * and string -> keyword arguments:
1197 * zfs.sync.snapshot({1="rpool@snap", defer=true})
1199 * The lua language allows curly braces to be used in place of parenthesis as
1200 * syntactic sugar for this calling convention:
1202 * zfs.sync.snapshot{"rpool@snap", defer=true}
1206 * Throw an error and print the given arguments. If there are too many
1207 * arguments to fit in the output buffer, only the error format string is
1211 zcp_args_error(lua_State *state, const char *fname, const zcp_arg_t *pargs,
1212 const zcp_arg_t *kwargs, const char *fmt, ...)
1216 size_t len = sizeof (errmsg);
1220 va_start(argp, fmt);
1221 VERIFY3U(len, >, vsnprintf(errmsg, len, fmt, argp));
1225 * Calculate the total length of the final string, including extra
1226 * formatting characters. If the argument dump would be too large,
1227 * only print the error string.
1229 msglen = strlen(errmsg);
1230 msglen += strlen(fname) + 4; /* : + {} + null terminator */
1231 for (i = 0; pargs[i].za_name != NULL; i++) {
1232 msglen += strlen(pargs[i].za_name);
1233 msglen += strlen(lua_typename(state, pargs[i].za_lua_type));
1234 if (pargs[i + 1].za_name != NULL || kwargs[0].za_name != NULL)
1235 msglen += 5; /* < + ( + )> + , */
1237 msglen += 4; /* < + ( + )> */
1239 for (i = 0; kwargs[i].za_name != NULL; i++) {
1240 msglen += strlen(kwargs[i].za_name);
1241 msglen += strlen(lua_typename(state, kwargs[i].za_lua_type));
1242 if (kwargs[i + 1].za_name != NULL)
1243 msglen += 4; /* =( + ) + , */
1245 msglen += 3; /* =( + ) */
1249 (void) luaL_error(state, errmsg);
1251 VERIFY3U(len, >, strlcat(errmsg, ": ", len));
1252 VERIFY3U(len, >, strlcat(errmsg, fname, len));
1253 VERIFY3U(len, >, strlcat(errmsg, "{", len));
1254 for (i = 0; pargs[i].za_name != NULL; i++) {
1255 VERIFY3U(len, >, strlcat(errmsg, "<", len));
1256 VERIFY3U(len, >, strlcat(errmsg, pargs[i].za_name, len));
1257 VERIFY3U(len, >, strlcat(errmsg, "(", len));
1258 VERIFY3U(len, >, strlcat(errmsg,
1259 lua_typename(state, pargs[i].za_lua_type), len));
1260 VERIFY3U(len, >, strlcat(errmsg, ")>", len));
1261 if (pargs[i + 1].za_name != NULL || kwargs[0].za_name != NULL) {
1262 VERIFY3U(len, >, strlcat(errmsg, ", ", len));
1265 for (i = 0; kwargs[i].za_name != NULL; i++) {
1266 VERIFY3U(len, >, strlcat(errmsg, kwargs[i].za_name, len));
1267 VERIFY3U(len, >, strlcat(errmsg, "=(", len));
1268 VERIFY3U(len, >, strlcat(errmsg,
1269 lua_typename(state, kwargs[i].za_lua_type), len));
1270 VERIFY3U(len, >, strlcat(errmsg, ")", len));
1271 if (kwargs[i + 1].za_name != NULL) {
1272 VERIFY3U(len, >, strlcat(errmsg, ", ", len));
1275 VERIFY3U(len, >, strlcat(errmsg, "}", len));
1277 (void) luaL_error(state, errmsg);
1278 panic("unreachable code");
1282 zcp_parse_table_args(lua_State *state, const char *fname,
1283 const zcp_arg_t *pargs, const zcp_arg_t *kwargs)
1288 for (i = 0; pargs[i].za_name != NULL; i++) {
1290 * Check the table for this positional argument, leaving it
1291 * on the top of the stack once we finish validating it.
1293 lua_pushinteger(state, i + 1);
1294 lua_gettable(state, 1);
1296 type = lua_type(state, -1);
1297 if (type == LUA_TNIL) {
1298 zcp_args_error(state, fname, pargs, kwargs,
1299 "too few arguments");
1300 panic("unreachable code");
1301 } else if (type != pargs[i].za_lua_type) {
1302 zcp_args_error(state, fname, pargs, kwargs,
1303 "arg %d wrong type (is '%s', expected '%s')",
1304 i + 1, lua_typename(state, type),
1305 lua_typename(state, pargs[i].za_lua_type));
1306 panic("unreachable code");
1310 * Remove the positional argument from the table.
1312 lua_pushinteger(state, i + 1);
1314 lua_settable(state, 1);
1317 for (i = 0; kwargs[i].za_name != NULL; i++) {
1319 * Check the table for this keyword argument, which may be
1320 * nil if it was omitted. Leave the value on the top of
1321 * the stack after validating it.
1323 lua_getfield(state, 1, kwargs[i].za_name);
1325 type = lua_type(state, -1);
1326 if (type != LUA_TNIL && type != kwargs[i].za_lua_type) {
1327 zcp_args_error(state, fname, pargs, kwargs,
1328 "kwarg '%s' wrong type (is '%s', expected '%s')",
1329 kwargs[i].za_name, lua_typename(state, type),
1330 lua_typename(state, kwargs[i].za_lua_type));
1331 panic("unreachable code");
1335 * Remove the keyword argument from the table.
1338 lua_setfield(state, 1, kwargs[i].za_name);
1342 * Any entries remaining in the table are invalid inputs, print
1343 * an error message based on what the entry is.
1346 if (lua_next(state, 1)) {
1347 if (lua_isnumber(state, -2) && lua_tointeger(state, -2) > 0) {
1348 zcp_args_error(state, fname, pargs, kwargs,
1349 "too many positional arguments");
1350 } else if (lua_isstring(state, -2)) {
1351 zcp_args_error(state, fname, pargs, kwargs,
1352 "invalid kwarg '%s'", lua_tostring(state, -2));
1354 zcp_args_error(state, fname, pargs, kwargs,
1355 "kwarg keys must be strings");
1357 panic("unreachable code");
1360 lua_remove(state, 1);
1364 zcp_parse_pos_args(lua_State *state, const char *fname, const zcp_arg_t *pargs,
1365 const zcp_arg_t *kwargs)
1370 for (i = 0; pargs[i].za_name != NULL; i++) {
1371 type = lua_type(state, i + 1);
1372 if (type == LUA_TNONE) {
1373 zcp_args_error(state, fname, pargs, kwargs,
1374 "too few arguments");
1375 panic("unreachable code");
1376 } else if (type != pargs[i].za_lua_type) {
1377 zcp_args_error(state, fname, pargs, kwargs,
1378 "arg %d wrong type (is '%s', expected '%s')",
1379 i + 1, lua_typename(state, type),
1380 lua_typename(state, pargs[i].za_lua_type));
1381 panic("unreachable code");
1384 if (lua_gettop(state) != i) {
1385 zcp_args_error(state, fname, pargs, kwargs,
1386 "too many positional arguments");
1387 panic("unreachable code");
1390 for (i = 0; kwargs[i].za_name != NULL; i++) {
1396 * Checks the current Lua stack against an expected set of positional and
1397 * keyword arguments. If the stack does not match the expected arguments
1398 * aborts the current channel program with a useful error message, otherwise
1399 * it re-arranges the stack so that it contains the positional arguments
1400 * followed by the keyword argument values in declaration order. Any missing
1401 * keyword argument will be represented by a nil value on the stack.
1403 * If the stack contains exactly one argument of type LUA_TTABLE the curly
1404 * braces calling convention is assumed, otherwise the stack is parsed for
1405 * positional arguments only.
1407 * This function should be used by every function callback. It should be called
1408 * before the callback manipulates the Lua stack as it assumes the stack
1409 * represents the function arguments.
1412 zcp_parse_args(lua_State *state, const char *fname, const zcp_arg_t *pargs,
1413 const zcp_arg_t *kwargs)
1415 if (lua_gettop(state) == 1 && lua_istable(state, 1)) {
1416 zcp_parse_table_args(state, fname, pargs, kwargs);
1418 zcp_parse_pos_args(state, fname, pargs, kwargs);