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, 2018 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(8) 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(8) for more information on high level usage.
92 #include <sys/lua/lua.h>
93 #include <sys/lua/lualib.h>
94 #include <sys/lua/lauxlib.h>
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>
105 #define KM_NORMALPRI 0
108 #define ZCP_NVLIST_MAX_DEPTH 20
110 uint64_t zfs_lua_check_instrlimit_interval
= 100;
111 unsigned long zfs_lua_max_instrlimit
= ZCP_MAX_INSTRLIMIT
;
112 unsigned long zfs_lua_max_memlimit
= ZCP_MAX_MEMLIMIT
;
115 * Forward declarations for mutually recursive functions
117 static int zcp_nvpair_value_to_lua(lua_State
*, nvpair_t
*, char *, int);
118 static int zcp_lua_to_nvlist_impl(lua_State
*, int, nvlist_t
*, const char *,
121 typedef struct zcp_alloc_arg
{
122 boolean_t aa_must_succeed
;
123 int64_t aa_alloc_remaining
;
124 int64_t aa_alloc_limit
;
127 typedef struct zcp_eval_arg
{
129 zcp_alloc_arg_t
*ea_allocargs
;
133 uint64_t ea_instrlimit
;
137 * The outer-most error callback handler for use with lua_pcall(). On
138 * error Lua will call this callback with a single argument that
139 * represents the error value. In most cases this will be a string
140 * containing an error message, but channel programs can use Lua's
141 * error() function to return arbitrary objects as errors. This callback
142 * returns (on the Lua stack) the original error object along with a traceback.
144 * Fatal Lua errors can occur while resources are held, so we also call any
145 * registered cleanup function here.
148 zcp_error_handler(lua_State
*state
)
154 VERIFY3U(1, ==, lua_gettop(state
));
155 msg
= lua_tostring(state
, 1);
156 luaL_traceback(state
, state
, msg
, 1);
161 zcp_argerror(lua_State
*state
, int narg
, const char *msg
, ...)
165 va_start(alist
, msg
);
166 const char *buf
= lua_pushvfstring(state
, msg
, alist
);
169 return (luaL_argerror(state
, narg
, buf
));
173 * Install a new cleanup function, which will be invoked with the given
174 * opaque argument if a fatal error causes the Lua interpreter to longjump out
175 * of a function call.
177 * If an error occurs, the cleanup function will be invoked exactly once and
180 * Returns the registered cleanup handler so the caller can deregister it
181 * if no error occurs.
183 zcp_cleanup_handler_t
*
184 zcp_register_cleanup(lua_State
*state
, zcp_cleanup_t cleanfunc
, void *cleanarg
)
186 zcp_run_info_t
*ri
= zcp_run_info(state
);
188 zcp_cleanup_handler_t
*zch
= kmem_alloc(sizeof (*zch
), KM_SLEEP
);
189 zch
->zch_cleanup_func
= cleanfunc
;
190 zch
->zch_cleanup_arg
= cleanarg
;
191 list_insert_head(&ri
->zri_cleanup_handlers
, zch
);
197 zcp_deregister_cleanup(lua_State
*state
, zcp_cleanup_handler_t
*zch
)
199 zcp_run_info_t
*ri
= zcp_run_info(state
);
200 list_remove(&ri
->zri_cleanup_handlers
, zch
);
201 kmem_free(zch
, sizeof (*zch
));
205 * Execute the currently registered cleanup handlers then free them and
206 * destroy the handler list.
209 zcp_cleanup(lua_State
*state
)
211 zcp_run_info_t
*ri
= zcp_run_info(state
);
213 for (zcp_cleanup_handler_t
*zch
=
214 list_remove_head(&ri
->zri_cleanup_handlers
); zch
!= NULL
;
215 zch
= list_remove_head(&ri
->zri_cleanup_handlers
)) {
216 zch
->zch_cleanup_func(zch
->zch_cleanup_arg
);
217 kmem_free(zch
, sizeof (*zch
));
222 * Convert the lua table at the given index on the Lua stack to an nvlist
225 * If the table can not be converted for any reason, NULL is returned and
226 * an error message is pushed onto the Lua stack.
229 zcp_table_to_nvlist(lua_State
*state
, int index
, int depth
)
233 * Converting a Lua table to an nvlist with key uniqueness checking is
234 * O(n^2) in the number of keys in the nvlist, which can take a long
235 * time when we return a large table from a channel program.
236 * Furthermore, Lua's table interface *almost* guarantees unique keys
237 * on its own (details below). Therefore, we don't use fnvlist_alloc()
238 * here to avoid the built-in uniqueness checking.
240 * The *almost* is because it's possible to have key collisions between
241 * e.g. the string "1" and the number 1, or the string "true" and the
242 * boolean true, so we explicitly check that when we're looking at a
243 * key which is an integer / boolean or a string that can be parsed as
244 * one of those types. In the worst case this could still devolve into
245 * O(n^2), so we only start doing these checks on boolean/integer keys
246 * once we've seen a string key which fits this weird usage pattern.
248 * Ultimately, we still want callers to know that the keys in this
249 * nvlist are unique, so before we return this we set the nvlist's
250 * flags to reflect that.
252 VERIFY0(nvlist_alloc(&nvl
, 0, KM_SLEEP
));
255 * Push an empty stack slot where lua_next() will store each
259 boolean_t saw_str_could_collide
= B_FALSE
;
260 while (lua_next(state
, index
) != 0) {
262 * The next key-value pair from the table at index is
263 * now on the stack, with the key at stack slot -2 and
264 * the value at slot -1.
268 const char *key
= NULL
;
269 boolean_t key_could_collide
= B_FALSE
;
271 switch (lua_type(state
, -2)) {
273 key
= lua_tostring(state
, -2);
275 /* check if this could collide with a number or bool */
278 if ((sscanf(key
, "%lld%n", &tmp
, &parselen
) > 0 &&
279 parselen
== strlen(key
)) ||
280 strcmp(key
, "true") == 0 ||
281 strcmp(key
, "false") == 0) {
282 key_could_collide
= B_TRUE
;
283 saw_str_could_collide
= B_TRUE
;
287 key
= (lua_toboolean(state
, -2) == B_TRUE
?
289 if (saw_str_could_collide
) {
290 key_could_collide
= B_TRUE
;
294 VERIFY3U(sizeof (buf
), >,
295 snprintf(buf
, sizeof (buf
), "%lld",
296 (longlong_t
)lua_tonumber(state
, -2)));
298 if (saw_str_could_collide
) {
299 key_could_collide
= B_TRUE
;
304 (void) lua_pushfstring(state
, "Invalid key "
305 "type '%s' in table",
306 lua_typename(state
, lua_type(state
, -2)));
310 * Check for type-mismatched key collisions, and throw an error.
312 if (key_could_collide
&& nvlist_exists(nvl
, key
)) {
314 (void) lua_pushfstring(state
, "Collision of "
315 "key '%s' in table", key
);
319 * Recursively convert the table value and insert into
320 * the new nvlist with the parsed key. To prevent
321 * stack overflow on circular or heavily nested tables,
322 * we track the current nvlist depth.
324 if (depth
>= ZCP_NVLIST_MAX_DEPTH
) {
326 (void) lua_pushfstring(state
, "Maximum table "
327 "depth (%d) exceeded for table",
328 ZCP_NVLIST_MAX_DEPTH
);
331 err
= zcp_lua_to_nvlist_impl(state
, -1, nvl
, key
,
336 * Error message has been pushed to the lua
337 * stack by the recursive call.
342 * Pop the value pushed by lua_next().
348 * Mark the nvlist as having unique keys. This is a little ugly, but we
349 * ensured above that there are no duplicate keys in the nvlist.
351 nvl
->nvl_nvflag
|= NV_UNIQUE_NAME
;
357 * Convert a value from the given index into the lua stack to an nvpair, adding
358 * it to an nvlist with the given key.
360 * Values are converted as follows:
365 * nil -> boolean (no value)
367 * Lua tables are converted to nvlists and then inserted. The table's keys
368 * are converted to strings then used as keys in the nvlist to store each table
369 * element. Keys are converted as follows:
371 * string -> no change
373 * boolean -> "true" | "false"
376 * In the case of a key collision, an error is thrown.
378 * If an error is encountered, a nonzero error code is returned, and an error
379 * string will be pushed onto the Lua stack.
382 zcp_lua_to_nvlist_impl(lua_State
*state
, int index
, nvlist_t
*nvl
,
383 const char *key
, int depth
)
386 * Verify that we have enough remaining space in the lua stack to parse
387 * a key-value pair and push an error.
389 if (!lua_checkstack(state
, 3)) {
390 (void) lua_pushstring(state
, "Lua stack overflow");
394 index
= lua_absindex(state
, index
);
396 switch (lua_type(state
, index
)) {
398 fnvlist_add_boolean(nvl
, key
);
401 fnvlist_add_boolean_value(nvl
, key
,
402 lua_toboolean(state
, index
));
405 fnvlist_add_int64(nvl
, key
, lua_tonumber(state
, index
));
408 fnvlist_add_string(nvl
, key
, lua_tostring(state
, index
));
411 nvlist_t
*value_nvl
= zcp_table_to_nvlist(state
, index
, depth
);
412 if (value_nvl
== NULL
)
415 fnvlist_add_nvlist(nvl
, key
, value_nvl
);
416 fnvlist_free(value_nvl
);
420 (void) lua_pushfstring(state
,
421 "Invalid value type '%s' for key '%s'",
422 lua_typename(state
, lua_type(state
, index
)), key
);
430 * Convert a lua value to an nvpair, adding it to an nvlist with the given key.
433 zcp_lua_to_nvlist(lua_State
*state
, int index
, nvlist_t
*nvl
, const char *key
)
436 * On error, zcp_lua_to_nvlist_impl pushes an error string onto the Lua
437 * stack before returning with a nonzero error code. If an error is
438 * returned, throw a fatal lua error with the given string.
440 if (zcp_lua_to_nvlist_impl(state
, index
, nvl
, key
, 0) != 0)
441 (void) lua_error(state
);
445 zcp_lua_to_nvlist_helper(lua_State
*state
)
447 nvlist_t
*nv
= (nvlist_t
*)lua_touserdata(state
, 2);
448 const char *key
= (const char *)lua_touserdata(state
, 1);
449 zcp_lua_to_nvlist(state
, 3, nv
, key
);
454 zcp_convert_return_values(lua_State
*state
, nvlist_t
*nvl
,
455 const char *key
, zcp_eval_arg_t
*evalargs
)
458 lua_pushcfunction(state
, zcp_lua_to_nvlist_helper
);
459 lua_pushlightuserdata(state
, (char *)key
);
460 lua_pushlightuserdata(state
, nvl
);
461 lua_pushvalue(state
, 1);
462 lua_remove(state
, 1);
463 err
= lua_pcall(state
, 3, 0, 0); /* zcp_lua_to_nvlist_helper */
465 zcp_lua_to_nvlist(state
, 1, nvl
, ZCP_RET_ERROR
);
466 evalargs
->ea_result
= SET_ERROR(ECHRNG
);
471 * Push a Lua table representing nvl onto the stack. If it can't be
472 * converted, return EINVAL, fill in errbuf, and push nothing. errbuf may
473 * be specified as NULL, in which case no error string will be output.
475 * Most nvlists are converted as simple key->value Lua tables, but we make
476 * an exception for the case where all nvlist entries are BOOLEANs (a string
477 * key without a value). In Lua, a table key pointing to a value of Nil
478 * (no value) is equivalent to the key not existing, so a BOOLEAN nvlist
479 * entry can't be directly converted to a Lua table entry. Nvlists of entirely
480 * BOOLEAN entries are frequently used to pass around lists of datasets, so for
481 * convenience we check for this case, and convert it to a simple Lua array of
485 zcp_nvlist_to_lua(lua_State
*state
, nvlist_t
*nvl
,
486 char *errbuf
, int errbuf_len
)
490 boolean_t has_values
= B_FALSE
;
492 * If the list doesn't have any values, just convert it to a string
495 for (pair
= nvlist_next_nvpair(nvl
, NULL
);
496 pair
!= NULL
; pair
= nvlist_next_nvpair(nvl
, pair
)) {
497 if (nvpair_type(pair
) != DATA_TYPE_BOOLEAN
) {
504 for (pair
= nvlist_next_nvpair(nvl
, NULL
);
505 pair
!= NULL
; pair
= nvlist_next_nvpair(nvl
, pair
)) {
506 (void) lua_pushinteger(state
, i
);
507 (void) lua_pushstring(state
, nvpair_name(pair
));
508 (void) lua_settable(state
, -3);
512 for (pair
= nvlist_next_nvpair(nvl
, NULL
);
513 pair
!= NULL
; pair
= nvlist_next_nvpair(nvl
, pair
)) {
514 int err
= zcp_nvpair_value_to_lua(state
, pair
,
520 (void) lua_setfield(state
, -2, nvpair_name(pair
));
527 * Push a Lua object representing the value of "pair" onto the stack.
529 * Only understands boolean_value, string, int64, nvlist,
530 * string_array, and int64_array type values. For other
531 * types, returns EINVAL, fills in errbuf, and pushes nothing.
534 zcp_nvpair_value_to_lua(lua_State
*state
, nvpair_t
*pair
,
535 char *errbuf
, int errbuf_len
)
544 switch (nvpair_type(pair
)) {
545 case DATA_TYPE_BOOLEAN_VALUE
:
546 (void) lua_pushboolean(state
,
547 fnvpair_value_boolean_value(pair
));
549 case DATA_TYPE_STRING
:
550 (void) lua_pushstring(state
, fnvpair_value_string(pair
));
552 case DATA_TYPE_INT64
:
553 (void) lua_pushinteger(state
, fnvpair_value_int64(pair
));
555 case DATA_TYPE_NVLIST
:
556 err
= zcp_nvlist_to_lua(state
,
557 fnvpair_value_nvlist(pair
), errbuf
, errbuf_len
);
559 case DATA_TYPE_STRING_ARRAY
: {
562 (void) nvpair_value_string_array(pair
, &strarr
, &nelem
);
564 for (int i
= 0; i
< nelem
; i
++) {
565 (void) lua_pushinteger(state
, i
+ 1);
566 (void) lua_pushstring(state
, strarr
[i
]);
567 (void) lua_settable(state
, -3);
571 case DATA_TYPE_UINT64_ARRAY
: {
574 (void) nvpair_value_uint64_array(pair
, &intarr
, &nelem
);
576 for (int i
= 0; i
< nelem
; i
++) {
577 (void) lua_pushinteger(state
, i
+ 1);
578 (void) lua_pushinteger(state
, intarr
[i
]);
579 (void) lua_settable(state
, -3);
583 case DATA_TYPE_INT64_ARRAY
: {
586 (void) nvpair_value_int64_array(pair
, &intarr
, &nelem
);
588 for (int i
= 0; i
< nelem
; i
++) {
589 (void) lua_pushinteger(state
, i
+ 1);
590 (void) lua_pushinteger(state
, intarr
[i
]);
591 (void) lua_settable(state
, -3);
596 if (errbuf
!= NULL
) {
597 (void) snprintf(errbuf
, errbuf_len
,
598 "Unhandled nvpair type %d for key '%s'",
599 nvpair_type(pair
), nvpair_name(pair
));
608 zcp_dataset_hold_error(lua_State
*state
, dsl_pool_t
*dp
, const char *dsname
,
611 if (error
== ENOENT
) {
612 (void) zcp_argerror(state
, 1, "no such dataset '%s'", dsname
);
613 return (0); /* not reached; zcp_argerror will longjmp */
614 } else if (error
== EXDEV
) {
615 (void) zcp_argerror(state
, 1,
616 "dataset '%s' is not in the target pool '%s'",
617 dsname
, spa_name(dp
->dp_spa
));
618 return (0); /* not reached; zcp_argerror will longjmp */
619 } else if (error
== EIO
) {
620 (void) luaL_error(state
,
621 "I/O error while accessing dataset '%s'", dsname
);
622 return (0); /* not reached; luaL_error will longjmp */
623 } else if (error
!= 0) {
624 (void) luaL_error(state
,
625 "unexpected error %d while accessing dataset '%s'",
627 return (0); /* not reached; luaL_error will longjmp */
633 * Note: will longjmp (via lua_error()) on error.
634 * Assumes that the dsname is argument #1 (for error reporting purposes).
637 zcp_dataset_hold(lua_State
*state
, dsl_pool_t
*dp
, const char *dsname
,
641 int error
= dsl_dataset_hold(dp
, dsname
, tag
, &ds
);
642 (void) zcp_dataset_hold_error(state
, dp
, dsname
, error
);
646 static int zcp_debug(lua_State
*);
647 static zcp_lib_info_t zcp_debug_info
= {
651 { .za_name
= "debug string", .za_lua_type
= LUA_TSTRING
},
660 zcp_debug(lua_State
*state
)
662 const char *dbgstring
;
663 zcp_run_info_t
*ri
= zcp_run_info(state
);
664 zcp_lib_info_t
*libinfo
= &zcp_debug_info
;
666 zcp_parse_args(state
, libinfo
->name
, libinfo
->pargs
, libinfo
->kwargs
);
668 dbgstring
= lua_tostring(state
, 1);
670 zfs_dbgmsg("txg %lld ZCP: %s", ri
->zri_tx
->tx_txg
, dbgstring
);
675 static int zcp_exists(lua_State
*);
676 static zcp_lib_info_t zcp_exists_info
= {
680 { .za_name
= "dataset", .za_lua_type
= LUA_TSTRING
},
689 zcp_exists(lua_State
*state
)
691 zcp_run_info_t
*ri
= zcp_run_info(state
);
692 dsl_pool_t
*dp
= ri
->zri_pool
;
693 zcp_lib_info_t
*libinfo
= &zcp_exists_info
;
695 zcp_parse_args(state
, libinfo
->name
, libinfo
->pargs
, libinfo
->kwargs
);
697 const char *dsname
= lua_tostring(state
, 1);
700 int error
= dsl_dataset_hold(dp
, dsname
, FTAG
, &ds
);
702 dsl_dataset_rele(ds
, FTAG
);
703 lua_pushboolean(state
, B_TRUE
);
704 } else if (error
== ENOENT
) {
705 lua_pushboolean(state
, B_FALSE
);
706 } else if (error
== EXDEV
) {
707 return (luaL_error(state
, "dataset '%s' is not in the "
708 "target pool", dsname
));
709 } else if (error
== EIO
) {
710 return (luaL_error(state
, "I/O error opening dataset '%s'",
712 } else if (error
!= 0) {
713 return (luaL_error(state
, "unexpected error %d", error
));
720 * Allocate/realloc/free a buffer for the lua interpreter.
722 * When nsize is 0, behaves as free() and returns NULL.
724 * If ptr is NULL, behaves as malloc() and returns an allocated buffer of size
727 * Otherwise, behaves as realloc(), changing the allocation from osize to nsize.
728 * Shrinking the buffer size never fails.
730 * The original allocated buffer size is stored as a uint64 at the beginning of
731 * the buffer to avoid actually reallocating when shrinking a buffer, since lua
732 * requires that this operation never fail.
735 zcp_lua_alloc(void *ud
, void *ptr
, size_t osize
, size_t nsize
)
737 zcp_alloc_arg_t
*allocargs
= ud
;
738 int flags
= (allocargs
->aa_must_succeed
) ?
739 KM_SLEEP
: (KM_NOSLEEP
| KM_NORMALPRI
);
743 int64_t *allocbuf
= (int64_t *)ptr
- 1;
744 int64_t allocsize
= *allocbuf
;
745 ASSERT3S(allocsize
, >, 0);
746 ASSERT3S(allocargs
->aa_alloc_remaining
+ allocsize
, <=,
747 allocargs
->aa_alloc_limit
);
748 allocargs
->aa_alloc_remaining
+= allocsize
;
749 vmem_free(allocbuf
, allocsize
);
752 } else if (ptr
== NULL
) {
754 int64_t allocsize
= nsize
+ sizeof (int64_t);
756 if (!allocargs
->aa_must_succeed
&&
758 allocsize
> allocargs
->aa_alloc_remaining
)) {
762 allocbuf
= vmem_alloc(allocsize
, flags
);
763 if (allocbuf
== NULL
) {
766 allocargs
->aa_alloc_remaining
-= allocsize
;
768 *allocbuf
= allocsize
;
769 return (allocbuf
+ 1);
770 } else if (nsize
<= osize
) {
772 * If shrinking the buffer, lua requires that the reallocation
777 ASSERT3U(nsize
, >, osize
);
779 uint64_t *luabuf
= zcp_lua_alloc(ud
, NULL
, 0, nsize
);
780 if (luabuf
== NULL
) {
783 (void) memcpy(luabuf
, ptr
, osize
);
784 VERIFY3P(zcp_lua_alloc(ud
, ptr
, osize
, 0), ==, NULL
);
791 zcp_lua_counthook(lua_State
*state
, lua_Debug
*ar
)
794 * If we're called, check how many instructions the channel program has
795 * executed so far, and compare against the limit.
797 lua_getfield(state
, LUA_REGISTRYINDEX
, ZCP_RUN_INFO_KEY
);
798 zcp_run_info_t
*ri
= lua_touserdata(state
, -1);
800 ri
->zri_curinstrs
+= zfs_lua_check_instrlimit_interval
;
801 if (ri
->zri_maxinstrs
!= 0 && ri
->zri_curinstrs
> ri
->zri_maxinstrs
) {
802 ri
->zri_timed_out
= B_TRUE
;
803 (void) lua_pushstring(state
,
804 "Channel program timed out.");
805 (void) lua_error(state
);
810 zcp_panic_cb(lua_State
*state
)
812 panic("unprotected error in call to Lua API (%s)\n",
813 lua_tostring(state
, -1));
818 zcp_eval_impl(dmu_tx_t
*tx
, boolean_t sync
, zcp_eval_arg_t
*evalargs
)
822 lua_State
*state
= evalargs
->ea_state
;
824 VERIFY3U(3, ==, lua_gettop(state
));
827 * Store the zcp_run_info_t struct for this run in the Lua registry.
828 * Registry entries are not directly accessible by the Lua scripts but
829 * can be accessed by our callbacks.
831 ri
.zri_space_used
= 0;
832 ri
.zri_pool
= dmu_tx_pool(tx
);
833 ri
.zri_cred
= evalargs
->ea_cred
;
835 ri
.zri_timed_out
= B_FALSE
;
837 list_create(&ri
.zri_cleanup_handlers
, sizeof (zcp_cleanup_handler_t
),
838 offsetof(zcp_cleanup_handler_t
, zch_node
));
839 ri
.zri_curinstrs
= 0;
840 ri
.zri_maxinstrs
= evalargs
->ea_instrlimit
;
842 lua_pushlightuserdata(state
, &ri
);
843 lua_setfield(state
, LUA_REGISTRYINDEX
, ZCP_RUN_INFO_KEY
);
844 VERIFY3U(3, ==, lua_gettop(state
));
847 * Tell the Lua interpreter to call our handler every count
848 * instructions. Channel programs that execute too many instructions
849 * should die with ETIME.
851 (void) lua_sethook(state
, zcp_lua_counthook
, LUA_MASKCOUNT
,
852 zfs_lua_check_instrlimit_interval
);
855 * Tell the Lua memory allocator to stop using KM_SLEEP before handing
856 * off control to the channel program. Channel programs that use too
857 * much memory should die with ENOSPC.
859 evalargs
->ea_allocargs
->aa_must_succeed
= B_FALSE
;
862 * Call the Lua function that open-context passed us. This pops the
863 * function and its input from the stack and pushes any return
866 err
= lua_pcall(state
, 1, LUA_MULTRET
, 1);
869 * Let Lua use KM_SLEEP while we interpret the return values.
871 evalargs
->ea_allocargs
->aa_must_succeed
= B_TRUE
;
874 * Remove the error handler callback from the stack. At this point,
875 * there shouldn't be any cleanup handler registered in the handler
876 * list (zri_cleanup_handlers), regardless of whether it ran or not.
878 list_destroy(&ri
.zri_cleanup_handlers
);
879 lua_remove(state
, 1);
884 * Lua supports returning multiple values in a single return
885 * statement. Return values will have been pushed onto the
890 * To simplify the process of retrieving a return value from a
891 * channel program, we disallow returning more than one value
892 * to ZFS from the Lua script, yielding a singleton return
893 * nvlist of the form { "return": Return value 1 }.
895 int return_count
= lua_gettop(state
);
897 if (return_count
== 1) {
898 evalargs
->ea_result
= 0;
899 zcp_convert_return_values(state
, evalargs
->ea_outnvl
,
900 ZCP_RET_RETURN
, evalargs
);
901 } else if (return_count
> 1) {
902 evalargs
->ea_result
= SET_ERROR(ECHRNG
);
903 (void) lua_pushfstring(state
, "Multiple return "
904 "values not supported");
905 zcp_convert_return_values(state
, evalargs
->ea_outnvl
,
906 ZCP_RET_ERROR
, evalargs
);
913 * The channel program encountered a fatal error within the
914 * script, such as failing an assertion, or calling a function
915 * with incompatible arguments. The error value and the
916 * traceback generated by zcp_error_handler() should be on the
919 VERIFY3U(1, ==, lua_gettop(state
));
920 if (ri
.zri_timed_out
) {
921 evalargs
->ea_result
= SET_ERROR(ETIME
);
923 evalargs
->ea_result
= SET_ERROR(ECHRNG
);
926 zcp_convert_return_values(state
, evalargs
->ea_outnvl
,
927 ZCP_RET_ERROR
, evalargs
);
929 if (evalargs
->ea_result
== ETIME
&&
930 evalargs
->ea_outnvl
!= NULL
) {
931 (void) nvlist_add_uint64(evalargs
->ea_outnvl
,
932 ZCP_ARG_INSTRLIMIT
, ri
.zri_curinstrs
);
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 (void) lua_pushfstring(evalargs
->ea_state
, "Could not open pool: %s",
972 zcp_convert_return_values(evalargs
->ea_state
, evalargs
->ea_outnvl
,
973 ZCP_RET_ERROR
, evalargs
);
978 zcp_eval_sync(void *arg
, dmu_tx_t
*tx
)
980 zcp_eval_arg_t
*evalargs
= arg
;
983 * Open context should have setup the stack to contain:
984 * 1: Error handler callback
985 * 2: Script to run (converted to a Lua function)
986 * 3: nvlist input to function (converted to Lua table or nil)
988 VERIFY3U(3, ==, lua_gettop(evalargs
->ea_state
));
990 zcp_eval_impl(tx
, B_TRUE
, evalargs
);
994 zcp_eval_open(zcp_eval_arg_t
*evalargs
, const char *poolname
)
1002 * See comment from the same assertion in zcp_eval_sync().
1004 VERIFY3U(3, ==, lua_gettop(evalargs
->ea_state
));
1006 error
= dsl_pool_hold(poolname
, FTAG
, &dp
);
1008 zcp_pool_error(evalargs
, poolname
);
1013 * As we are running in open-context, we have no transaction associated
1014 * with the channel program. At the same time, functions from the
1015 * zfs.check submodule need to be associated with a transaction as
1016 * they are basically dry-runs of their counterparts in the zfs.sync
1017 * submodule. These functions should be able to run in open-context.
1018 * Therefore we create a new transaction that we later abort once
1019 * the channel program has been evaluated.
1021 tx
= dmu_tx_create_dd(dp
->dp_mos_dir
);
1023 zcp_eval_impl(tx
, B_FALSE
, evalargs
);
1027 dsl_pool_rele(dp
, FTAG
);
1031 zcp_eval(const char *poolname
, const char *program
, boolean_t sync
,
1032 uint64_t instrlimit
, uint64_t memlimit
, nvpair_t
*nvarg
, nvlist_t
*outnvl
)
1036 zcp_eval_arg_t evalargs
;
1038 if (instrlimit
> zfs_lua_max_instrlimit
)
1039 return (SET_ERROR(EINVAL
));
1040 if (memlimit
== 0 || memlimit
> zfs_lua_max_memlimit
)
1041 return (SET_ERROR(EINVAL
));
1043 zcp_alloc_arg_t allocargs
= {
1044 .aa_must_succeed
= B_TRUE
,
1045 .aa_alloc_remaining
= (int64_t)memlimit
,
1046 .aa_alloc_limit
= (int64_t)memlimit
,
1050 * Creates a Lua state with a memory allocator that uses KM_SLEEP.
1051 * This should never fail.
1053 state
= lua_newstate(zcp_lua_alloc
, &allocargs
);
1054 VERIFY(state
!= NULL
);
1055 (void) lua_atpanic(state
, zcp_panic_cb
);
1058 * Load core Lua libraries we want access to.
1060 VERIFY3U(1, ==, luaopen_base(state
));
1062 VERIFY3U(1, ==, luaopen_coroutine(state
));
1063 lua_setglobal(state
, LUA_COLIBNAME
);
1064 VERIFY0(lua_gettop(state
));
1065 VERIFY3U(1, ==, luaopen_string(state
));
1066 lua_setglobal(state
, LUA_STRLIBNAME
);
1067 VERIFY0(lua_gettop(state
));
1068 VERIFY3U(1, ==, luaopen_table(state
));
1069 lua_setglobal(state
, LUA_TABLIBNAME
);
1070 VERIFY0(lua_gettop(state
));
1073 * Load globally visible variables such as errno aliases.
1075 zcp_load_globals(state
);
1076 VERIFY0(lua_gettop(state
));
1079 * Load ZFS-specific modules.
1081 lua_newtable(state
);
1082 VERIFY3U(1, ==, zcp_load_list_lib(state
));
1083 lua_setfield(state
, -2, "list");
1084 VERIFY3U(1, ==, zcp_load_synctask_lib(state
, B_FALSE
));
1085 lua_setfield(state
, -2, "check");
1086 VERIFY3U(1, ==, zcp_load_synctask_lib(state
, B_TRUE
));
1087 lua_setfield(state
, -2, "sync");
1088 VERIFY3U(1, ==, zcp_load_get_lib(state
));
1089 lua_pushcclosure(state
, zcp_debug_info
.func
, 0);
1090 lua_setfield(state
, -2, zcp_debug_info
.name
);
1091 lua_pushcclosure(state
, zcp_exists_info
.func
, 0);
1092 lua_setfield(state
, -2, zcp_exists_info
.name
);
1093 lua_setglobal(state
, "zfs");
1094 VERIFY0(lua_gettop(state
));
1097 * Push the error-callback that calculates Lua stack traces on
1098 * unexpected failures.
1100 lua_pushcfunction(state
, zcp_error_handler
);
1101 VERIFY3U(1, ==, lua_gettop(state
));
1104 * Load the actual script as a function onto the stack as text ("t").
1105 * The only valid error condition is a syntax error in the script.
1106 * ERRMEM should not be possible because our allocator is using
1107 * KM_SLEEP. ERRGCMM should not be possible because we have not added
1108 * any objects with __gc metamethods to the interpreter that could
1111 err
= luaL_loadbufferx(state
, program
, strlen(program
),
1112 "channel program", "t");
1113 if (err
== LUA_ERRSYNTAX
) {
1114 fnvlist_add_string(outnvl
, ZCP_RET_ERROR
,
1115 lua_tostring(state
, -1));
1117 return (SET_ERROR(EINVAL
));
1120 VERIFY3U(2, ==, lua_gettop(state
));
1123 * Convert the input nvlist to a Lua object and put it on top of the
1127 err
= zcp_nvpair_value_to_lua(state
, nvarg
,
1128 errmsg
, sizeof (errmsg
));
1130 fnvlist_add_string(outnvl
, ZCP_RET_ERROR
, errmsg
);
1132 return (SET_ERROR(EINVAL
));
1134 VERIFY3U(3, ==, lua_gettop(state
));
1136 evalargs
.ea_state
= state
;
1137 evalargs
.ea_allocargs
= &allocargs
;
1138 evalargs
.ea_instrlimit
= instrlimit
;
1139 evalargs
.ea_cred
= CRED();
1140 evalargs
.ea_outnvl
= outnvl
;
1141 evalargs
.ea_result
= 0;
1144 err
= dsl_sync_task(poolname
, NULL
,
1145 zcp_eval_sync
, &evalargs
, 0, ZFS_SPACE_CHECK_NONE
);
1147 zcp_pool_error(&evalargs
, poolname
);
1149 zcp_eval_open(&evalargs
, poolname
);
1153 return (evalargs
.ea_result
);
1157 * Retrieve metadata about the currently running channel program.
1160 zcp_run_info(lua_State
*state
)
1164 lua_getfield(state
, LUA_REGISTRYINDEX
, ZCP_RUN_INFO_KEY
);
1165 ri
= lua_touserdata(state
, -1);
1174 * The Lua language allows methods to be called with any number
1175 * of arguments of any type. When calling back into ZFS we need to sanitize
1176 * arguments from channel programs to make sure unexpected arguments or
1177 * arguments of the wrong type result in clear error messages. To do this
1178 * in a uniform way all callbacks from channel programs should use the
1179 * zcp_parse_args() function to interpret inputs.
1181 * Positional vs Keyword Arguments
1182 * ===============================
1184 * Every callback function takes a fixed set of required positional arguments
1185 * and optional keyword arguments. For example, the destroy function takes
1186 * a single positional string argument (the name of the dataset to destroy)
1187 * and an optional "defer" keyword boolean argument. When calling lua functions
1188 * with parentheses, only positional arguments can be used:
1190 * zfs.sync.snapshot("rpool@snap")
1192 * To use keyword arguments functions should be called with a single argument
1193 * that is a lua table containing mappings of integer -> positional arguments
1194 * and string -> keyword arguments:
1196 * zfs.sync.snapshot({1="rpool@snap", defer=true})
1198 * The lua language allows curly braces to be used in place of parenthesis as
1199 * syntactic sugar for this calling convention:
1201 * zfs.sync.snapshot{"rpool@snap", defer=true}
1205 * Throw an error and print the given arguments. If there are too many
1206 * arguments to fit in the output buffer, only the error format string is
1210 zcp_args_error(lua_State
*state
, const char *fname
, const zcp_arg_t
*pargs
,
1211 const zcp_arg_t
*kwargs
, const char *fmt
, ...)
1215 size_t len
= sizeof (errmsg
);
1219 va_start(argp
, fmt
);
1220 VERIFY3U(len
, >, vsnprintf(errmsg
, len
, fmt
, argp
));
1224 * Calculate the total length of the final string, including extra
1225 * formatting characters. If the argument dump would be too large,
1226 * only print the error string.
1228 msglen
= strlen(errmsg
);
1229 msglen
+= strlen(fname
) + 4; /* : + {} + null terminator */
1230 for (i
= 0; pargs
[i
].za_name
!= NULL
; i
++) {
1231 msglen
+= strlen(pargs
[i
].za_name
);
1232 msglen
+= strlen(lua_typename(state
, pargs
[i
].za_lua_type
));
1233 if (pargs
[i
+ 1].za_name
!= NULL
|| kwargs
[0].za_name
!= NULL
)
1234 msglen
+= 5; /* < + ( + )> + , */
1236 msglen
+= 4; /* < + ( + )> */
1238 for (i
= 0; kwargs
[i
].za_name
!= NULL
; i
++) {
1239 msglen
+= strlen(kwargs
[i
].za_name
);
1240 msglen
+= strlen(lua_typename(state
, kwargs
[i
].za_lua_type
));
1241 if (kwargs
[i
+ 1].za_name
!= NULL
)
1242 msglen
+= 4; /* =( + ) + , */
1244 msglen
+= 3; /* =( + ) */
1248 (void) luaL_error(state
, errmsg
);
1250 VERIFY3U(len
, >, strlcat(errmsg
, ": ", len
));
1251 VERIFY3U(len
, >, strlcat(errmsg
, fname
, len
));
1252 VERIFY3U(len
, >, strlcat(errmsg
, "{", len
));
1253 for (i
= 0; pargs
[i
].za_name
!= NULL
; i
++) {
1254 VERIFY3U(len
, >, strlcat(errmsg
, "<", len
));
1255 VERIFY3U(len
, >, strlcat(errmsg
, pargs
[i
].za_name
, len
));
1256 VERIFY3U(len
, >, strlcat(errmsg
, "(", len
));
1257 VERIFY3U(len
, >, strlcat(errmsg
,
1258 lua_typename(state
, pargs
[i
].za_lua_type
), len
));
1259 VERIFY3U(len
, >, strlcat(errmsg
, ")>", len
));
1260 if (pargs
[i
+ 1].za_name
!= NULL
|| kwargs
[0].za_name
!= NULL
) {
1261 VERIFY3U(len
, >, strlcat(errmsg
, ", ", len
));
1264 for (i
= 0; kwargs
[i
].za_name
!= NULL
; i
++) {
1265 VERIFY3U(len
, >, strlcat(errmsg
, kwargs
[i
].za_name
, len
));
1266 VERIFY3U(len
, >, strlcat(errmsg
, "=(", len
));
1267 VERIFY3U(len
, >, strlcat(errmsg
,
1268 lua_typename(state
, kwargs
[i
].za_lua_type
), len
));
1269 VERIFY3U(len
, >, strlcat(errmsg
, ")", len
));
1270 if (kwargs
[i
+ 1].za_name
!= NULL
) {
1271 VERIFY3U(len
, >, strlcat(errmsg
, ", ", len
));
1274 VERIFY3U(len
, >, strlcat(errmsg
, "}", len
));
1276 (void) luaL_error(state
, errmsg
);
1277 panic("unreachable code");
1281 zcp_parse_table_args(lua_State
*state
, const char *fname
,
1282 const zcp_arg_t
*pargs
, const zcp_arg_t
*kwargs
)
1287 for (i
= 0; pargs
[i
].za_name
!= NULL
; i
++) {
1289 * Check the table for this positional argument, leaving it
1290 * on the top of the stack once we finish validating it.
1292 lua_pushinteger(state
, i
+ 1);
1293 lua_gettable(state
, 1);
1295 type
= lua_type(state
, -1);
1296 if (type
== LUA_TNIL
) {
1297 zcp_args_error(state
, fname
, pargs
, kwargs
,
1298 "too few arguments");
1299 panic("unreachable code");
1300 } else if (type
!= pargs
[i
].za_lua_type
) {
1301 zcp_args_error(state
, fname
, pargs
, kwargs
,
1302 "arg %d wrong type (is '%s', expected '%s')",
1303 i
+ 1, lua_typename(state
, type
),
1304 lua_typename(state
, pargs
[i
].za_lua_type
));
1305 panic("unreachable code");
1309 * Remove the positional argument from the table.
1311 lua_pushinteger(state
, i
+ 1);
1313 lua_settable(state
, 1);
1316 for (i
= 0; kwargs
[i
].za_name
!= NULL
; i
++) {
1318 * Check the table for this keyword argument, which may be
1319 * nil if it was omitted. Leave the value on the top of
1320 * the stack after validating it.
1322 lua_getfield(state
, 1, kwargs
[i
].za_name
);
1324 type
= lua_type(state
, -1);
1325 if (type
!= LUA_TNIL
&& type
!= kwargs
[i
].za_lua_type
) {
1326 zcp_args_error(state
, fname
, pargs
, kwargs
,
1327 "kwarg '%s' wrong type (is '%s', expected '%s')",
1328 kwargs
[i
].za_name
, lua_typename(state
, type
),
1329 lua_typename(state
, kwargs
[i
].za_lua_type
));
1330 panic("unreachable code");
1334 * Remove the keyword argument from the table.
1337 lua_setfield(state
, 1, kwargs
[i
].za_name
);
1341 * Any entries remaining in the table are invalid inputs, print
1342 * an error message based on what the entry is.
1345 if (lua_next(state
, 1)) {
1346 if (lua_isnumber(state
, -2) && lua_tointeger(state
, -2) > 0) {
1347 zcp_args_error(state
, fname
, pargs
, kwargs
,
1348 "too many positional arguments");
1349 } else if (lua_isstring(state
, -2)) {
1350 zcp_args_error(state
, fname
, pargs
, kwargs
,
1351 "invalid kwarg '%s'", lua_tostring(state
, -2));
1353 zcp_args_error(state
, fname
, pargs
, kwargs
,
1354 "kwarg keys must be strings");
1356 panic("unreachable code");
1359 lua_remove(state
, 1);
1363 zcp_parse_pos_args(lua_State
*state
, const char *fname
, const zcp_arg_t
*pargs
,
1364 const zcp_arg_t
*kwargs
)
1369 for (i
= 0; pargs
[i
].za_name
!= NULL
; i
++) {
1370 type
= lua_type(state
, i
+ 1);
1371 if (type
== LUA_TNONE
) {
1372 zcp_args_error(state
, fname
, pargs
, kwargs
,
1373 "too few arguments");
1374 panic("unreachable code");
1375 } else if (type
!= pargs
[i
].za_lua_type
) {
1376 zcp_args_error(state
, fname
, pargs
, kwargs
,
1377 "arg %d wrong type (is '%s', expected '%s')",
1378 i
+ 1, lua_typename(state
, type
),
1379 lua_typename(state
, pargs
[i
].za_lua_type
));
1380 panic("unreachable code");
1383 if (lua_gettop(state
) != i
) {
1384 zcp_args_error(state
, fname
, pargs
, kwargs
,
1385 "too many positional arguments");
1386 panic("unreachable code");
1389 for (i
= 0; kwargs
[i
].za_name
!= NULL
; i
++) {
1395 * Checks the current Lua stack against an expected set of positional and
1396 * keyword arguments. If the stack does not match the expected arguments
1397 * aborts the current channel program with a useful error message, otherwise
1398 * it re-arranges the stack so that it contains the positional arguments
1399 * followed by the keyword argument values in declaration order. Any missing
1400 * keyword argument will be represented by a nil value on the stack.
1402 * If the stack contains exactly one argument of type LUA_TTABLE the curly
1403 * braces calling convention is assumed, otherwise the stack is parsed for
1404 * positional arguments only.
1406 * This function should be used by every function callback. It should be called
1407 * before the callback manipulates the Lua stack as it assumes the stack
1408 * represents the function arguments.
1411 zcp_parse_args(lua_State
*state
, const char *fname
, const zcp_arg_t
*pargs
,
1412 const zcp_arg_t
*kwargs
)
1414 if (lua_gettop(state
) == 1 && lua_istable(state
, 1)) {
1415 zcp_parse_table_args(state
, fname
, pargs
, kwargs
);
1417 zcp_parse_pos_args(state
, fname
, pargs
, kwargs
);
1421 #if defined(_KERNEL)
1423 module_param(zfs_lua_max_instrlimit
, ulong
, 0644);
1424 MODULE_PARM_DESC(zfs_lua_max_instrlimit
,
1425 "Max instruction limit that can be specified for a channel program");
1427 module_param(zfs_lua_max_memlimit
, ulong
, 0644);
1428 MODULE_PARM_DESC(zfs_lua_max_memlimit
,
1429 "Max memory limit that can be specified for a channel program");