]>
Commit | Line | Data |
---|---|---|
d99a0153 CW |
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 | ||
20 | Introduction | |
21 | ------------ | |
22 | ||
23 | This README describes the Lua interpreter source code that lives in the ZFS | |
24 | source tree to enable execution of ZFS channel programs, including its | |
25 | maintenance policy, the modifications that have been made to it, and how it | |
26 | should (and should not) be used. | |
27 | ||
28 | For a description of the Lua language and features exposed by ZFS channel | |
29 | programs, please refer to the zfs-program(1m) man page instead. | |
30 | ||
31 | ||
32 | Maintenance policy | |
33 | ------------------ | |
34 | ||
35 | The Lua runtime is considered stable software. Channel programs don't need much | |
36 | complicated logic, so updates to the Lua runtime from upstream are viewed as | |
37 | nice-to-have, but not required for channel programs to be well-supported. As | |
38 | such, the Lua runtime in ZFS should be updated on an as-needed basis for | |
39 | security vulnerabilities, but not much else. | |
40 | ||
41 | ||
42 | Modifications to Lua | |
43 | -------------------- | |
44 | ||
45 | The version of the Lua runtime we're using in ZFS has been modified in a variety | |
46 | of ways to make it more useful for the specific purpose of running channel | |
47 | programs. These changes include: | |
48 | ||
49 | 1. "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. | |
52 | 2. 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. | |
55 | 3. 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. | |
59 | 4. 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. | |
65 | 5. 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 | ||
70 | Each of these modifications have been tested in the zfs-test suite. If / when | |
71 | new modifications are made, new tests should be added to the suite located in | |
72 | zfs-tests/tests/functional/channel_program/lua_core. | |
73 | ||
74 | ||
75 | How to use this Lua interpreter | |
76 | ------------------------------- | |
77 | ||
78 | From the above, it should be clear that this is not a general-purpose Lua | |
79 | interpreter. Additional work would be required to extricate this custom version | |
80 | of Lua from ZFS and make it usable by other areas of the kernel. |