From patchwork Wed Feb 21 08:22:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefano Babic X-Patchwork-Id: 1901895 X-Patchwork-Delegate: sbabic@denx.de Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.a=rsa-sha256 header.s=20230601 header.b=AYtCbd/q; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4864:20::63a; helo=mail-ej1-x63a.google.com; envelope-from=swupdate+bncbaabbq7f22xamgqe35sp7hi@googlegroups.com; receiver=patchwork.ozlabs.org) Received: from mail-ej1-x63a.google.com (mail-ej1-x63a.google.com [IPv6:2a00:1450:4864:20::63a]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Tfq5M6S1pz23l0 for ; Wed, 21 Feb 2024 19:22:31 +1100 (AEDT) Received: by mail-ej1-x63a.google.com with SMTP id a640c23a62f3a-a2b6c2a5fddsf423055066b.1 for ; Wed, 21 Feb 2024 00:22:31 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1708503748; cv=pass; d=google.com; s=arc-20160816; b=SSrAQaAnpWyKSX+zKbIfRcRPQPhvRuuc5iQ5Js4Gg7Q66xVG0w/osijPVzzPw3B2Ln NXkmw8gLSgUFvcvukdJeiH6wslWRp7HmxFG4dBhZnis/PfhDmt1QNpMNGQ3b8GKTwxG+ aWHg6UFLYNgc7AAV43u6PwrwlG79xwSJiVW4cqKya/rkxO9mnl5ipLI0lqLJVcPOCz2q bOqJn2PRAEdbOnh25WEYfExUfC25kTnAmyseT0q3nSul4qy6I1Hk/no1Mariu1qby3Cx A4Fe2hMgA6Z4aTkuqfddA0rU2vIIfkutZRDPvJ+2UtdS2VyTFl3rv3TVaOTu/V6XizQz iDqg== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:ui-outboundreport:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from:sender :dkim-signature; bh=CVAowEz/yuMjTFbzYh5/ZLa56QYTyepZ8ScbSbeB+xY=; fh=f98PhOZ9MAOwkQ0frCtLaJO62PtH7frSltCcn+HKI4o=; b=Wz5nFOQFVfwchWAYY+eEWAJlLRtHaSaD/ddaUcBlfhg5c14R7/BuugYPUCNs2tVLXl NpX16sQV8n7W7fpU/Ra3fOjKQwrIjLLggRU82v8uvlKoxWQWgMNam5qTLS3ZwZUzMl2n jvi7W1PjNN96ObnccgWhRetdvzXIkvouEVmYzYIuQRBLVP8XfRzz36VXU7pm7/HF/sbH 1FryYKi4zGn7C/vIUxdCsDRAMqv9wyKo3JIzMR0mGXVFZOKFxrbu4w1gxHBqBY2WmP9O qdYuKFDvnWXz+lslAQ0OJLK7F8lT1QGNzHJXOOpDHLCKgvuJs1LczArLXPB9wLWtff2G zZLw==; darn=patchwork.ozlabs.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@swupdate.org header.s=s1-ionos header.b=yjwHw7dV; spf=pass (google.com: domain of stefano.babic@swupdate.org designates 212.227.126.131 as permitted sender) smtp.mailfrom=stefano.babic@swupdate.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20230601; t=1708503748; x=1709108548; darn=patchwork.ozlabs.org; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:x-original-authentication-results :x-original-sender:ui-outboundreport:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:sender:from:to:cc :subject:date:message-id:reply-to; bh=CVAowEz/yuMjTFbzYh5/ZLa56QYTyepZ8ScbSbeB+xY=; b=AYtCbd/qc//BwwogKaw1xhdVVmndY5X44Gt85hygnvd2oebFwTIJSIt/xciXXXEaDH +HygEejC3Rtiba3LQNkl/OwgIs7ZLAaLqvA6PkXns8EQWKWdYaIHebWDUkfN+bWfGnSI zMNbiKm4DAkHiE8jixI2e2VoRrYe2iwtZxz9ywKZ3R20aiDeI+Ab5VVNTIByhTSNeoPv AYxzUUZtjnBOa/0X5zenVOR8TcRTcRkXvKSw9hFENlHdN4DKFxK+1ayDenaHO6nOwe66 XE8+YElH5jEYjKlr7bMI+grqaarMBuzDT+GV+27vfzCJOyX+omlmCOj43HzVYXqaaVTw B8jw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1708503748; x=1709108548; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :x-spam-checked-in-group:list-id:mailing-list:precedence :x-original-authentication-results:x-original-sender :ui-outboundreport:mime-version:references:in-reply-to:message-id :date:subject:cc:to:from:x-beenthere:x-gm-message-state:sender:from :to:cc:subject:date:message-id:reply-to; bh=CVAowEz/yuMjTFbzYh5/ZLa56QYTyepZ8ScbSbeB+xY=; b=wpsWt2XPEietmqnezOOniEys9O92UMqO9ksgftcw7HS1qOLWPFvF+GlkPGmyr1RZ2K dctENFX5qat/2omZHz+uESI7cbdSQ8+NhInL5jxULx3IOP3zBzeF7GWidotqNYBQJC02 3lGs9JxiKmgCGx7bi6sMbUiiaUc9aiKfZe4daz9g+aE2jMwSgR3kWhG8Z1CejW7uoawu potdNQu7ASKx32JWk9+Ocdfp1UWRa581Xty0fbUNpb2VkF1pqma+t0e80Q/XRiU6sX73 iiPfcezfzaqz9lliRE9Kwd7YjLh5OnR1z9bVvWQPt8yw3NYZW83OnhnwxGu9aB1oN5Yp +asw== Sender: swupdate@googlegroups.com X-Forwarded-Encrypted: i=2; AJvYcCW0+PT2+lfV2j3aeZ52SwqmzE9axcMMwyjWCr7Wr6DKc2+D4vsLtOux3jM+0cZyD/vXn1kAHwonscV8weTHgKHUyGUGN95Vx2Vq0D1/2g== X-Gm-Message-State: AOJu0Yy7KNYW041XsUYsa5w+r6UHFllStvcjVZ+2EPlqumgoF6X0hv4o /e2uySLwifStDSN24JfZlgD5vlZsGFY4RHTFvzRqV5sT7jSzlKzD X-Google-Smtp-Source: AGHT+IEwfY4GS6C+/UdHbuE7v3l2g1q/fW7TFdmHcW3xsHMs4+XtHMjqYuYgkOicp2yUTsq4LCirog== X-Received: by 2002:aa7:cad4:0:b0:564:5f40:e11a with SMTP id l20-20020aa7cad4000000b005645f40e11amr6686646edt.16.1708503747536; Wed, 21 Feb 2024 00:22:27 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a05:6402:5293:b0:561:2701:7e02 with SMTP id en19-20020a056402529300b0056127017e02ls956599edb.0.-pod-prod-07-eu; Wed, 21 Feb 2024 00:22:26 -0800 (PST) X-Received: by 2002:a05:6402:3457:b0:564:a62e:dad with SMTP id l23-20020a056402345700b00564a62e0dadmr4466656edc.34.1708503745791; Wed, 21 Feb 2024 00:22:25 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1708503745; cv=none; d=google.com; s=arc-20160816; b=mVzlZdLCe3KMb5LxK8fDwtFqpSvbMxfZjCGXBe32kiW4i0qed3JRwg+N19rXgJXo44 3geeC/29qlhEpppgu9dmVyI6oPJlu97ONIrL5BNLuPLHeWNSmsPH3izf5z/INNiqrqLW +iE9hrt04bDgqqI2RwFt4G1ejbymFTsFYDOmkYZDnLGcWFwgFwcgqbj+0TknkuObuUmQ XEh8nCqFMeM9oTixjTYhWXIXPPP80sMG7tEjPUjfDrS4HpVaM6OV+LeZK/h8TuZNcRcL oxfRAPi9P0Lm5fWjVTGNSoyMvnZVen2S6XFH9ZQf1Z4KHX6sdGZgafjmGcjLd30YfuZk jYCg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=ui-outboundreport:content-transfer-encoding:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:dkim-signature; bh=N4Fk12mSL1boQ5SZkymm2gDhBtTRxq/GhTgTXSWtP14=; fh=TiEWcqMcKpHk5s7uErzpntoONrNfOXwKpI5P8bIlggk=; b=drTcebOi3Jtx5n8NysU4hV0FlaSjFDhiIWnABPoRdAzLFCGYRS+8OyyjDPrGJLw1vX wLKQOugMk9/Wam3epoARxT930fARAdQ8syeZnt0PxJoaCf+vEpG8Q3kgg6yxWcOIuDfV QNfU8e/LSyogVle/Bew8hfOxwlOYMyORW2XyU+dz112/2GR6llDZ0eWxBrYcKualkGip 8sqEMi+izkwwCe75/rwMzqx9tBm/RP5vwXDUN1NqsCqx0mWFUk+dX5wcoyTEt7QMNpTK IFCHgpv1mOYiuWY3URKcadbCdKFl/ev/WyieWgRC6IjOymHfa1cFRBfV+jrPe4KNyKG+ uyZw==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@swupdate.org header.s=s1-ionos header.b=yjwHw7dV; spf=pass (google.com: domain of stefano.babic@swupdate.org designates 212.227.126.131 as permitted sender) smtp.mailfrom=stefano.babic@swupdate.org Received: from mout.kundenserver.de (mout.kundenserver.de. [212.227.126.131]) by gmr-mx.google.com with ESMTPS id bl5-20020a056402210500b00564647bdc98si209626edb.1.2024.02.21.00.22.25 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 21 Feb 2024 00:22:25 -0800 (PST) Received-SPF: pass (google.com: domain of stefano.babic@swupdate.org designates 212.227.126.131 as permitted sender) client-ip=212.227.126.131; X-UI-Sender-Class: 55c96926-9e95-11ee-ae09-1f7a4046a0f6 Received: from paperino.fritz.box ([88.217.136.221]) by mrelayeu.kundenserver.de (mreue011 [213.165.67.97]) with ESMTPSA (Nemesis) id 1MF3Y8-1rjGOX1Jvc-00FXFS; Wed, 21 Feb 2024 09:22:25 +0100 From: Stefano Babic To: swupdate@googlegroups.com Cc: Stefano Babic Subject: [swupdate] [PATCH 12/13] doc: explain Lua and shell script handlers Date: Wed, 21 Feb 2024 09:22:20 +0100 Message-Id: <20240221082221.11997-13-stefano.babic@swupdate.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240221082221.11997-1-stefano.babic@swupdate.org> References: <20240221082221.11997-1-stefano.babic@swupdate.org> MIME-Version: 1.0 X-Provags-ID: V03:K1:H1g/QBIvYHzZ0PJJrpNSZthFQ//F9g4BWbsaOfXgALhLlpXVQLO hRXjTO+HTh+oniRu9Itb7wmC6YjKDMhNbXPVclgaWtCqDR/6d/d86cc1CNXtipmK/ho50+R f8qhjKW/Vr4zGTd3SA4SI3Y/MRdx04lwq2xWoJLwp5NcZfIAC3TMjR66EXZvk/M2os0g/fq I/ijOfwOgdvsfQjEcoq0g== X-Spam-Flag: NO UI-OutboundReport: notjunk:1;M01:P0:6IU1mLCs7kI=;2Cp06qh3oDyMKAike3nSQgTErA+ ORjPNbfsOWE9mRAzMAVHfWb4CMuf+WUZeb1XYM+rjvVJskMFMmaVqhdvGNMwtOvKxuQhy/btB AZ+l16bYtkk7/fjrs4dlPm1jb+CTGHUpPlZSUEgkZFnLsjXVqyEv88Jnjh9QVJGT9MhUTbdkJ avrmIdNdjSPGo5sPxjr3nntzAnjy4WpH0Yc5si60dN362v+fZg2yM147F/vJbeVmPE7FS7PQB XWJrPVEoMiBjv+PilpMWC3zfJoaGMjxZzUadbBBN6puqmFeXzA5M2DHMU+72o6uMB3X7WepTC e/G5Uk0lowJh5ccuExLE8Z1jk54TVZVWR5DS2nahqjrhxWk9JdkN6DVBJGb0EWY7NOk8wLTkV qCWO1oWgWPeEnRjRJG4VaD/EHCklsMsftvmlMPxgUbjUNZgaPaSg8eYkOUnA9Ra0gvYegDoa7 8UXBYv0l4HweKH1PWakyGrFlaNhOsh8rxtog9EsVpLJDdb8ryOssL/u7hKFfUHiv54/SO8ZCh jcwQ1+Tl5U+oTnbn2L1uscy+hjsCY/jgYwFFnNKtGo5szb8AgdxExbUvMDqxELyFJOzQKCBDT YYZypDC09oIHf28Y3T41wAHVpIxWzJEw/w1HTxiCjsQ1/p965xprWEczBIDJ4G/InbjlwHxKD LU82FQQQLDxaR3pDMx5e3is9l2ADIpDdJTBPYMjWu6zWhsmoVY7HY8gMABq5snQ7rrs5ZBFxr R7vrejQDznwjEW1GPYVYlmeDisASDSicRZQMI7aYDdUBne1Bt+9pxA= X-Original-Sender: stefano.babic@swupdate.org X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@swupdate.org header.s=s1-ionos header.b=yjwHw7dV; spf=pass (google.com: domain of stefano.babic@swupdate.org designates 212.227.126.131 as permitted sender) smtp.mailfrom=stefano.babic@swupdate.org Precedence: list Mailing-list: list swupdate@googlegroups.com; contact swupdate+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: swupdate@googlegroups.com X-Google-Group-Id: 605343134186 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Signed-off-by: Stefano Babic --- doc/source/handlers.rst | 86 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 4 deletions(-) -- 2.34.1 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: ( {