d99a015343
Authored by: Chris Williamson <chris.williamson@delphix.com> Reviewed by: Matthew Ahrens <mahrens@delphix.com> Reviewed by: George Wilson <george.wilson@delphix.com> Reviewed by: John Kennedy <john.kennedy@delphix.com> Reviewed by: Dan Kimmel <dan.kimmel@delphix.com> Approved by: Garrett D'Amore <garrett@damore.org> Ported-by: Don Brady <don.brady@delphix.com> Ported-by: John Kennedy <john.kennedy@delphix.com> OpenZFS-issue: https://www.illumos.org/issues/7431 OpenZFS-commit: https://github.com/openzfs/openzfs/commit/dfc11533 Porting Notes: * The CLI long option arguments for '-t' and '-m' don't parse on linux * Switched from kmem_alloc to vmem_alloc in zcp_lua_alloc * Lua implementation is built as its own module (zlua.ko) * Lua headers consumed directly by zfs code moved to 'include/sys/lua/' * There is no native setjmp/longjump available in stock Linux kernel. Brought over implementations from illumos and FreeBSD * The get_temporary_prop() was adapted due to VFS platform differences * Use of inline functions in lua parser to reduce stack usage per C call * Skip some ZFS Test Suite ZCP tests on sparc64 to avoid stack overflow
81 lines
3.4 KiB
Plaintext
81 lines
3.4 KiB
Plaintext
#
|
|
# CDDL HEADER START
|
|
#
|
|
# This file and its contents are supplied under the terms of the
|
|
# Common Development and Distribution License ("CDDL"), version 1.0.
|
|
# You may only use this file in accordance with the terms of version
|
|
# 1.0 of the CDDL.
|
|
#
|
|
# A full copy of the text of the CDDL should have accompanied this
|
|
# source. A copy of the CDDL is also available via the Internet at
|
|
# http://www.illumos.org/license/CDDL.
|
|
#
|
|
# CDDL HEADER END
|
|
#
|
|
|
|
#
|
|
# Copyright (c) 2017 by Delphix. All rights reserved.
|
|
#
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This README describes the Lua interpreter source code that lives in the ZFS
|
|
source tree to enable execution of ZFS channel programs, including its
|
|
maintenance policy, the modifications that have been made to it, and how it
|
|
should (and should not) be used.
|
|
|
|
For a description of the Lua language and features exposed by ZFS channel
|
|
programs, please refer to the zfs-program(1m) man page instead.
|
|
|
|
|
|
Maintenance policy
|
|
------------------
|
|
|
|
The Lua runtime is considered stable software. Channel programs don't need much
|
|
complicated logic, so updates to the Lua runtime from upstream are viewed as
|
|
nice-to-have, but not required for channel programs to be well-supported. As
|
|
such, the Lua runtime in ZFS should be updated on an as-needed basis for
|
|
security vulnerabilities, but not much else.
|
|
|
|
|
|
Modifications to Lua
|
|
--------------------
|
|
|
|
The version of the Lua runtime we're using in ZFS has been modified in a variety
|
|
of ways to make it more useful for the specific purpose of running channel
|
|
programs. These changes include:
|
|
|
|
1. "Normal" Lua uses floating point for all numbers it stores, but those aren't
|
|
useful inside ZFS / the kernel. We have changed the runtime to use int64_t
|
|
throughout for all numbers.
|
|
2. Some of the Lua standard libraries do file I/O or spawn processes, but
|
|
neither of these make sense from inside channel programs. We have removed
|
|
those libraries rather than reimplementing them using kernel APIs.
|
|
3. The "normal" Lua runtime handles errors by failing fatally, but since this
|
|
version of Lua runs inside the kernel we must handle these failures and
|
|
return meaningful error codes to userland. We have customized the Lua
|
|
failure paths so that they aren't fatal.
|
|
4. Running poorly-vetted code inside the kernel is always a risk; even if the
|
|
ability to do so is restricted to the root user, it's still possible to write
|
|
an incorrect program that results in an infinite loop or massive memory use.
|
|
We've added new protections into the Lua interpreter to limit the runtime
|
|
(measured in number of Lua instructions run) and memory overhead of running
|
|
a channel program.
|
|
5. The Lua bytecode is not designed to be secure / safe, so it would be easy to
|
|
pass invalid bytecode which can panic the kernel. By comparison, the parser
|
|
is hardened and fails gracefully on invalid input. Therefore, we only accept
|
|
Lua source code at the ioctl level and then interpret it inside the kernel.
|
|
|
|
Each of these modifications have been tested in the zfs-test suite. If / when
|
|
new modifications are made, new tests should be added to the suite located in
|
|
zfs-tests/tests/functional/channel_program/lua_core.
|
|
|
|
|
|
How to use this Lua interpreter
|
|
-------------------------------
|
|
|
|
From the above, it should be clear that this is not a general-purpose Lua
|
|
interpreter. Additional work would be required to extricate this custom version
|
|
of Lua from ZFS and make it usable by other areas of the kernel.
|