From patchwork Mon Nov 11 20:50:19 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Kiszka X-Patchwork-Id: 3916 Return-Path: Received: from shymkent.ilbers.de ([unix socket]) by shymkent (Cyrus 2.5.10-Debian-2.5.10-3+deb9u2) with LMTPA; Mon, 11 Nov 2024 21:50:39 +0100 X-Sieve: CMU Sieve 2.4 Received: from mail-pl1-f191.google.com (mail-pl1-f191.google.com [209.85.214.191]) by shymkent.ilbers.de (8.15.2/8.15.2/Debian-8+deb9u1) with ESMTPS id 4ABKobAn014854 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Mon, 11 Nov 2024 21:50:38 +0100 Received: by mail-pl1-f191.google.com with SMTP id d9443c01a7336-2112b3f4338sf54696145ad.1 for ; Mon, 11 Nov 2024 12:50:38 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1731358229; cv=pass; d=google.com; s=arc-20240605; b=hTA6SAAmA2VtXdydIxw3PO6dkPz5vNfyZgI42exOaZvjK8CERuWQ8wB0WPZ9lZHdIn QnqmYg4lYX7oqxLAejiHjXTbnCcNn0uhM7JxhqUji7rzpTMJCpsplH5G8jfquSAPEGyE wKqrLZY8lFAZoCtl2m40tfuoqdJRjaAKufVjTevgI91QfNqj0bHL9SIRgFzaNHS0FEvd IUFIuyJdUwAqr0JUDAFtoG7/KxGM8lYqEew02whJd/4LiTE5nhllOj3GB5NztegVCh4u rg5dL1zwq8OPju6wNEwHZ3fkfOj49rOUC9w8p+GlaktPkq5mhohrqK6g6qq4gGmzYrro KPCA== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:reply-to:feedback-id:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=1WyWzHq8f9maBDFBXOegsaoUJEs8lyLb04Q1SPvGIJQ=; fh=GxCIriul0HOPRBM+b1AFlGaPvekLbNIXpVVYoEOGXBY=; b=joM35eTObxiw0L33ny1hpwS31K9lTSNpXMqFFJlGuPPoUUqtylrcUxGoVe547F8sLu Cg9I3/TeB8OMqzMAIVxXpRbasNFPscPkvG3IfV9nt7gtfuVI8t/NCRy6H9WCYzJcE50L hpcQbTMbdsAZlOmwkOKgvIahyvX4GmPojNhG4kdJeg8+8TKgG+JakW9JXyh+BhISQmBl FuBBtPyLgnBFYHlm2HlkUhkAwujoVg7it8WYUQeY9/ZqPeI+jZZS9Rd6o+TYIc9A//ml RN6BnYMhOBHhgOBSsxCqZr9UB0XuSwkhh47zi8fmzWLUKr90G1aDGrpB8Vjs2JFKvgiQ fNnw==; darn=isar-build.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm1 header.b=QIDvwRke; spf=pass (google.com: domain of fm-294854-2024111120502561300d664ba9a22c0d-bzrkfr@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-2024111120502561300d664ba9a22c0d-bZRKFr@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20230601; t=1731358229; x=1731963029; darn=isar-build.org; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:reply-to :x-original-authentication-results:x-original-sender:feedback-id :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=1WyWzHq8f9maBDFBXOegsaoUJEs8lyLb04Q1SPvGIJQ=; b=ODuKeFW4rj/zj0PgU4LT1YRoEA2MPjo5pWUKt9S/ebWvMfR0ZIOYVrCn1kl+sbiYca jEHvp5VTlfpU8oxDsaIkSNLXBfRczWs0I6vH0kaZvrgdDPNj1uuKSDNHmGVhcDwjYInO aZd2YYQNdeI1s8dVLblL+nzp28t/mGX4itxtzHLWOjPbR+nlX5yg5HWIao/wddz2wM3K BA47yCSEr+aCGtjemW2ujQ4rnbuo4uku3fcT3RvSbjiiVCXgDx6keA7P62PF6BV4X1FV BpF8wDeS3MTm06WZQY9M603GcMsBhTHLHy5PbKCcmqT13U1fLO5oZ4ZtiEQ5YVkTlq+d Cmww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731358229; x=1731963029; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :x-spam-checked-in-group:list-id:mailing-list:precedence:reply-to :x-original-authentication-results:x-original-sender:feedback-id :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:x-beenthere:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=1WyWzHq8f9maBDFBXOegsaoUJEs8lyLb04Q1SPvGIJQ=; b=Nyd5wQZAy8DehzKmmoX1w7RHJcwP2qSTnsyAWe7t/4tlmeWKudFnmgt66JXyQUNY9d sPCq9XHm5WftmSO7aldaP0haX08WZGtw5zvBXelETwEoxWdrMzrGIK1fbTYJX4ttlAFB RSJI8OUpOkNjZPNu2C00Ch3PEq37eTsjvxpODiXb9pAJZaiuUwxMQSAEyp/O3RysbcZL 4tYyH8W7pvwa+WrTIgDw6FlTpQhYC7n18Z6P0I3QDioGP5xlimtn+MWKKOM5QwdHkBLL if2aih7l7Wd6HXLOoXpQHW1HkNxGvh1s/ZwD8yWWZY3GW8minKEtR+Sl2vAAPxvoNUML RlGA== X-Forwarded-Encrypted: i=2; AJvYcCVQdtzx/KhuSjj92pDlDNWIFrPmYhUYygMTQ2G+Akxkyai2f/cW7JomaJzqYjkIzXcwSWyI4xM=@isar-build.org X-Gm-Message-State: AOJu0YxtA76u1X4ORLoyj2wwlpGdAoK5BCY5RdDFC5YghHsOnazPRI5i NosJweNAj+lsIPDb+Rx+b4Ze+MPKV24M5e5FyUkQ+ML96N5WBnw7 X-Google-Smtp-Source: AGHT+IF0xQZgZcMzx3NVIPnJiJ0LrAq8oS9dXy2dTlD7tvrUhUVaWiQ9eELXDOt66vnn+os1Z+aPvQ== X-Received: by 2002:a17:903:2391:b0:20c:a1a3:5373 with SMTP id d9443c01a7336-21183e72361mr139663835ad.55.1731358229238; Mon, 11 Nov 2024 12:50:29 -0800 (PST) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a17:903:705:b0:206:935f:fa6 with SMTP id d9443c01a7336-21175212582ls19108155ad.0.-pod-prod-05-us; Mon, 11 Nov 2024 12:50:28 -0800 (PST) X-Received: by 2002:a05:6a20:840d:b0:1db:eb56:be7c with SMTP id adf61e73a8af0-1dc22b1b74fmr20694718637.35.1731358227777; Mon, 11 Nov 2024 12:50:27 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1731358227; cv=none; d=google.com; s=arc-20240605; b=TFGGMAcUlkNKPstKXgDMhiq+OeP+dlP+jeh1EnR6qvsF5lgpnfotGA7CgLy/mDnzkd ej8tU5hONnp4XD+eG6Fg/GgIzxKzqyJbRpEUAH6p6vU394mvrIW3qA/eJ8BvpGHcvXUl mlh6H6WCf13jF7cHNl5bpH7hdJsW5Dou5J20pIFJIu9avHpcE5xzeZKslFvSgzNRvmfk R5fodeOwIq4TKkEzSY598z4Cgg5MNTPiLY748cuUKNFRUkZY6kBAibn1PeYr2PggJqro rhB/xVUGnayB4dNVhf8Z9Zaq4o75J6rW/3xNf1HCF47nb83ysyuPm9BpyFExm/u8kZ4f cX8g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=feedback-id:content-transfer-encoding:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:dkim-signature; bh=n621mkuUmvw8m8MLoY29oSN2pW6Rijv5zGOUEr8NoTY=; fh=TWGwN84gUgHIe5O4CbyH9KISyeWwGbvUX7cnJPxVD70=; b=jeagLzUOjYbLryrxLLIB6VpKIQaXXz1PFiHATC51EoyH/7PtVD95jq2r3FO0rZMOAR JWHbHvU0nXSN7NOdNJuk+hsF8+y+8RCPcSorCGk0lzIXmp199IgxweyJQoJBxIxgLglu VQ/lCInxp9peDCgz+sxLofgJujVJZALQcIfguxwSMFVaIWytNACpyXuxHLddnEJk/PeV q8DTpjOqUUuWxflzh3zn7ChESTurnhqFIg4yKJJe5lRyHACg3sPzokqwMNloR4sf4Aq6 FyyX9yQh11SXrEwKj/v2GQPERBDNg7c3fr+MTpgsRfkBWR2ZvixVIYu/b/uknhRiTSR/ NMfQ==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm1 header.b=QIDvwRke; spf=pass (google.com: domain of fm-294854-2024111120502561300d664ba9a22c0d-bzrkfr@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-2024111120502561300d664ba9a22c0d-bZRKFr@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from mta-65-225.siemens.flowmailer.net (mta-65-225.siemens.flowmailer.net. [185.136.65.225]) by gmr-mx.google.com with ESMTPS id 41be03b00d2f7-7f452cf952csi95856a12.1.2024.11.11.12.50.27 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 11 Nov 2024 12:50:27 -0800 (PST) Received-SPF: pass (google.com: domain of fm-294854-2024111120502561300d664ba9a22c0d-bzrkfr@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) client-ip=185.136.65.225; Received: by mta-65-225.siemens.flowmailer.net with ESMTPSA id 2024111120502561300d664ba9a22c0d for ; Mon, 11 Nov 2024 21:50:25 +0100 X-Patchwork-Original-From: "'Jan Kiszka' via isar-users" From: Jan Kiszka To: isar-users Cc: Quirin Gylstorff Subject: [PATCH 2/7] doc: Describe initramfs customizations Date: Mon, 11 Nov 2024 21:50:19 +0100 Message-ID: <423377b14db0f2acc9534af4f8f436fc862accff.1731358224.git.jan.kiszka@siemens.com> In-Reply-To: References: MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-294854:519-21489:flowmailer X-Original-Sender: jan.kiszka@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm1 header.b=QIDvwRke; spf=pass (google.com: domain of fm-294854-2024111120502561300d664ba9a22c0d-bzrkfr@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-2024111120502561300d664ba9a22c0d-bZRKFr@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com X-Original-From: Jan Kiszka Reply-To: Jan Kiszka Precedence: list Mailing-list: list isar-users@googlegroups.com; contact isar-users+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: isar-users@googlegroups.com X-Google-Group-Id: 914930254986 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , X-Spam-Status: No, score=-4.9 required=5.0 tests=DKIMWL_WL_MED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_MSPIKE_H2,RCVD_IN_RP_CERTIFIED, RCVD_IN_RP_RNBL,RCVD_IN_RP_SAFE,SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on shymkent.ilbers.de X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= From: Jan Kiszka Document to new hook.inc as well as the preexisting initramfs class. Signed-off-by: Jan Kiszka --- doc/user_manual.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/doc/user_manual.md b/doc/user_manual.md index 284847c8..7e04c7e8 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -1600,3 +1600,57 @@ CONTAINER_DELETE_AFTER_LOAD = "1" SRC_URI += "docker://debian;digest=sha256:f528891ab1aa484bf7233dbcc84f3c806c3e427571d75510a9d74bb5ec535b33;tag=bookworm-20240701-slim" ``` + +## Customize the initramfs + +Isar supports the customization of initramfs images by providing an +infrastructure for quickly creating hooks and by allowing to replace the +Debian-generated image with a separately built one. + +### Creating initramfs hooks + +To create an initramfs hook that adds tools or modules to the image and may +also run custom scripts during boot, use the include file +`recipes-initramfs/initramfs-hook/hook.inc`. It is controlled via a number of +variables: + + - `HOOK_PREREQ` defines the prerequisites for running the hook script. + - `HOOK_ADD_MODULES` passes the provided modules names to the + `manual_add_modules` function during initramfs creation. + - `HOOK_COPY_EXECS` identifies the source of the passed executables on the + rootfs that runs mkinitramfs and passes that to `copy_exec`. If an + executable is not found, an error thrown, and the creation fails. + - `SCRIPT_PREREQ` defines the prerequisites for running the boot script. + +If the generated hook script is not sufficient, you can append an own +bottom-half script by providing a `hook` file in `${WORKDIR}`. It will be +appended to the `hook-header` that the helper generates. + +For running a custom script during boot-up, provide a bottom-half file in +`${WORKDIR}`. Its name defines where it is hooked up with the initramfs boot +process: `init-top`, `init-premount`, `local-top`, `nfs-top`, `local-block`, +`local-premount`, `nfs-premount`, `local-bottom`, `nfs-bottom`, `init-bottom` + +See https://manpages.debian.org/stable/initramfs-tools-core/initramfs-tools.7.en.html +for further details. + +The hook recipe should follow the naming convention `initramfs--hook` +so that its scripts will then be called `` in the generated +initramfs. + +See `initramfs-example` for an exemplary hook recipe. + +### Creating an initramfs image aside the rootfs + +To avoid shipping all tools and binaries needed to generate an initramfs, isar +provides the initramfs class. It creates a temporary Debian rootfs with all +those dependencies and generates the initramfs from there, rather than the +target's rootfs. + +This initramfs class should be pulled in by an image recipe. Said recipe +specifies all dependencies of the initramfs via `INITRAMFS_INSTALL` for +self-built packages and `INITRAMFS_PREINSTALL` for prebuilt ones, analogously +to the respective `IMAGE_*` variables. Note that the kernel is automatically +added to `INITRAMFS_INSTALL` if `KERNEL_NAME` is set. + +See `isar-initramfs` for an example recipe.