Name Date Size #Lines LOC

..27-Mar-2024-

README.zfsH A D12-Jul-20223.4 KiB8165

lapi.cH A D14-Feb-202129.2 KiB1,2841,020

lapi.hH A D14-Feb-2021545 2511

lauxlib.cH A D14-Feb-202122 KiB792542

lauxlib.hH A D14-Feb-20216.2 KiB177101

lbaselib.cH A D14-Feb-20217.2 KiB293232

lbitlib.cH A D14-Feb-20214.3 KiB213147

lcode.cH A D14-Feb-202122 KiB886728

lcode.hH A D14-Feb-20213 KiB8455

lcompat.cH A D14-Feb-20211.4 KiB10386

lcorolib.cH A D14-Feb-20213.5 KiB155122

lctype.cH A D14-Feb-20212.3 KiB5341

lctype.hH A D14-Feb-20211.8 KiB9438

ldebug.cH A D14-Feb-202116.1 KiB608499

ldebug.hH A D14-Feb-20211.1 KiB3517

ldo.cH A D14-Feb-202120.4 KiB686549

ldo.hH A D14-Feb-20211.5 KiB4726

ldump.cH A D14-Feb-20213.2 KiB174145

lfunc.cH A D14-Feb-20214.2 KiB162124

lfunc.hH A D14-Feb-20211 KiB3418

lgc.cH A D14-Feb-202136.9 KiB1,221841

lgc.hH A D14-Feb-20215.3 KiB15877

llex.cH A D14-Feb-202115 KiB530417

llex.hH A D14-Feb-20212.1 KiB7946

llimits.hH A D14-Feb-20217.5 KiB309151

lmem.cH A D14-Feb-20212.6 KiB10056

lmem.hH A D14-Feb-20211.8 KiB5829

lobject.cH A D14-Feb-20217.7 KiB284224

lobject.hH A D14-Feb-202114.6 KiB607314

lopcodes.cH A D14-Feb-20213 KiB10889

lopcodes.hH A D14-Feb-20218.3 KiB289124

lparser.cH A D14-Feb-202144.9 KiB1,6381,268

lparser.hH A D14-Feb-20213.3 KiB12081

lstate.cH A D14-Feb-20217.5 KiB322228

lstate.hH A D14-Feb-20217.4 KiB229139

lstring.cH A D14-Feb-20214.8 KiB186121

lstring.hH A D14-Feb-20211.2 KiB4720

lstrlib.cH A D14-Feb-202128.5 KiB1,052855

ltable.cH A D14-Feb-202116.1 KiB590411

ltable.hH A D14-Feb-20211.4 KiB4627

ltablib.cH A D14-Feb-20217.5 KiB285220

ltm.cH A D14-Feb-20211.8 KiB7853

ltm.hH A D14-Feb-20211.1 KiB5834

lua.hH A D14-Feb-202113.3 KiB444221

luaconf.hH A D14-Feb-202115 KiB553189

lualib.hH A D14-Feb-20211.1 KiB5627

lundump.cH A D14-Feb-20215.5 KiB259220

lundump.hH A D14-Feb-2021772 2910

lvm.cH A D14-Feb-202130.1 KiB931785

lvm.hH A D14-Feb-20211.4 KiB4525

lzio.cH A D14-Feb-20211.6 KiB7755

lzio.hH A D14-Feb-20211.5 KiB6634

README.zfs

1#
2# CDDL HEADER START
3#
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
7# 1.0 of the CDDL.
8#
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.
12#
13# CDDL HEADER END
14#
15
16#
17# Copyright (c) 2017 by Delphix. All rights reserved.
18#
19
20Introduction
21------------
22
23This README describes the Lua interpreter source code that lives in the ZFS
24source tree to enable execution of ZFS channel programs, including its
25maintenance policy, the modifications that have been made to it, and how it
26should (and should not) be used.
27
28For a description of the Lua language and features exposed by ZFS channel
29programs, please refer to the zfs-program(8) man page instead.
30
31
32Maintenance policy
33------------------
34
35The Lua runtime is considered stable software. Channel programs don't need much
36complicated logic, so updates to the Lua runtime from upstream are viewed as
37nice-to-have, but not required for channel programs to be well-supported. As
38such, the Lua runtime in ZFS should be updated on an as-needed basis for
39security vulnerabilities, but not much else.
40
41
42Modifications to Lua
43--------------------
44
45The version of the Lua runtime we're using in ZFS has been modified in a variety
46of ways to make it more useful for the specific purpose of running channel
47programs. These changes include:
48
491. "Normal" Lua uses floating point for all numbers it stores, but those aren't
50   useful inside ZFS / the kernel. We have changed the runtime to use int64_t
51   throughout for all numbers.
522. Some of the Lua standard libraries do file I/O or spawn processes, but
53   neither of these make sense from inside channel programs. We have removed
54   those libraries rather than reimplementing them using kernel APIs.
553. The "normal" Lua runtime handles errors by failing fatally, but since this
56   version of Lua runs inside the kernel we must handle these failures and
57   return meaningful error codes to userland. We have customized the Lua
58   failure paths so that they aren't fatal.
594. Running poorly-vetted code inside the kernel is always a risk; even if the
60   ability to do so is restricted to the root user, it's still possible to write
61   an incorrect program that results in an infinite loop or massive memory use.
62   We've added new protections into the Lua interpreter to limit the runtime
63   (measured in number of Lua instructions run) and memory overhead of running
64   a channel program.
655. The Lua bytecode is not designed to be secure / safe, so it would be easy to
66   pass invalid bytecode which can panic the kernel. By comparison, the parser
67   is hardened and fails gracefully on invalid input. Therefore, we only accept
68   Lua source code at the ioctl level and then interpret it inside the kernel.
69
70Each of these modifications have been tested in the zfs-test suite. If / when
71new modifications are made, new tests should be added to the suite located in
72zfs-tests/tests/functional/channel_program/lua_core.
73
74
75How to use this Lua interpreter
76-------------------------------
77
78From the above, it should be clear that this is not a general-purpose Lua
79interpreter. Additional work would be required to extricate this custom version
80of Lua from ZFS and make it usable by other areas of the kernel.
81