module/lua/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
  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.