diff mbox series

[12/13] doc: explain Lua and shell script handlers

Message ID 20240221082221.11997-13-stefano.babic@swupdate.org
State Accepted
Delegated to: Stefano Babic
Headers show
Series Extend Lua Environemnt and post-failure scripts | expand

Commit Message

Stefano Babic Feb. 21, 2024, 8:22 a.m. UTC
Signed-off-by: Stefano Babic <stefano.babic@swupdate.org>
---
 doc/source/handlers.rst | 86 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 4 deletions(-)

--
2.34.1
diff mbox series

Patch

diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst
index 1a1988f0..da0bbeb8 100644
--- a/doc/source/handlers.rst
+++ b/doc/source/handlers.rst
@@ -457,6 +457,84 @@  image, this is not implemented as it carries some security
 implications since the behavior of SWUpdate is changed
 dynamically.

+Shell script handler
+--------------------
+
+This handler allows to run a shell script thta is packed into the SWU. Please note
+that running a shell script opens a set of different security issues. Shell scripts
+are supported due to their large acceptance, but you should prefer Lua Scripts.
+
+SWUpdate will run the binary shell "/bin/sh" to execute the script.
+
+Lua script handler
+------------------
+
+A Lua Script handler runs a script in Lua language. There are two possible ways to run the
+script:
+
+        - local: the script runs in own (isolated) Lua state that is created for the script.
+          The script has access only to function defined inside the script or functions
+          provided by external libraries, like the internal swupdate library called via
+          "require(swupdate)".
+        - global: SWUpdate create a Lua state at the beginning of an Update and this is
+          valid until the update is terminated. In this case, the script has access to any function
+          and structure that was defined during the update. For example, a function
+          can be defined inside sw-description, and the script can call it.
+
+As default, each script runs in isolated / local Lua state. If the property "global-state" is set,
+then the common LUa state used for each Update transaction is taken.
+
+Scripts ran in isolated context in previous versions. SWUpdate allocates a new
+Lua state, and import the basic libraries before loading the script. A
+script is then isolated, but it cannot access to function already
+loaded, or it is not possible to reuse functions from 2 or more scripts.
+
+With the introduction of a per installation Lua state, Lua scripts can
+call functions already defined in previous scripts, or defined in
+sw-description. Because when a script is loaded, existing functions with the same name are overwritten,
+it was decided that functions in scripts must be unique, that is each function should be declared just
+once during an installation process.
+
+This means that for global state, sw-description should contain the name of the function for each step
+(pre- , postinstall or postfailure) that should be called: the names preinst, postinst and postfailure are
+still valid in case the script runs with isolated state.
+
+This allows also to load a script without executing if no functions are defined, and functions in the script
+can be called by later scripts.
+
+Note that the handler will load the script in case of global state just once during the "preinstall" call.
+Later, it is assumed that functions will be already available.
+
+
+Example:
+
+::
+
+	scripts: (
+		{
+                        filename = "testscript.lua";
+                        type = "lua";
+                        properties: {
+				global-state = "true";
+                                preinstall = "pretest1";
+			}
+		},
+		{
+			filename = "test2script.lua";
+			type = "lua";
+			properties: {
+				global-state = "true";
+                                postinstall = "posttest2";
+                                postfailure = "failure";
+			}
+		}
+
+Two scripts are defined. Both are using the global Lua state.
+Functions in test2script can find and run functions defined in testscript.lua,
+because both are belonging to the same context. When preinstall scripts are called, only the function
+"pretest1" from the first script is called, because no function name is defined for this step with
+the following scripts.
+
 Remote handler
 --------------

@@ -1326,7 +1404,7 @@  passed to the daemon:
 Docker Remove Image
 -------------------

-It is implemented as script (post install).
+It is implemented as script (post install).
 Example:

 ::
@@ -1341,7 +1419,7 @@  Example:
 Docker Delete Unused Images
 ---------------------------

-It is implemented as script (post install).
+It is implemented as script (post install).
 Example:

 ::
@@ -1386,7 +1464,7 @@  Creating the container can be done in sw-description with:
 Docker Remove Container
 -----------------------

-It is implemented as script (post install).
+It is implemented as script (post install).
 Example:

 ::
@@ -1411,7 +1489,7 @@  Examples:
 			name = "helloworld";
 		};
 	});
-
+
 ::

 	scripts: ( {