From patchwork Wed Nov 20 17:02:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Kiszka X-Patchwork-Id: 3950 Return-Path: Received: from shymkent.ilbers.de ([unix socket]) by shymkent (Cyrus 2.5.10-Debian-2.5.10-3+deb9u2) with LMTPA; Wed, 20 Nov 2024 18:03:13 +0100 X-Sieve: CMU Sieve 2.4 Received: from mail-oa1-f64.google.com (mail-oa1-f64.google.com [209.85.160.64]) by shymkent.ilbers.de (8.15.2/8.15.2/Debian-8+deb9u1) with ESMTPS id 4AKH3BWS006891 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Wed, 20 Nov 2024 18:03:11 +0100 Received: by mail-oa1-f64.google.com with SMTP id 586e51a60fabf-29683b5dc58sf5017fac.2 for ; Wed, 20 Nov 2024 09:03:11 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1732122185; cv=pass; d=google.com; s=arc-20240605; b=N8+nPs0aKTwCNdSQ18iQbwu1zj/TkuucQoykGBaxfWiM1N3R/nbDr89RyX3+PlWrkh DAoab2kjIdk4TGiY05oTB8hT98IWeR/SxeVgEto5WmZmZRWh5Aw1j1sUDqvaw5Cyw+II sTs0CPzUMiWu1p3cmRQMTB+jJrW64YtYQl7hQ1edtcQ4//abxXmBPg4clUP2L5VedjAh qm5din+N6Qc78jAIkMi4By875ZcDsYn1QRywrY1AeWnVuVu5boN+d4GVLICNToOAr0fo MaB+Z7N7tFiaFlh+A/26t0dZjZEt64/pWlfBRy/GqFpTyQUhn36vSyX9IgyAs9tY3b6V /hLw== 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=CQ752KkHo7czABHpD7P26TBcdh7fW3ep8nqsK6ACXbs=; fh=oHdgX+p0AvLCkrKJuDkye3YV+QSMizlRymSRQ2Zdm3U=; b=Q1y13iHj5SyNTazmljui/1IBDToGaxLLCarYMoD6ZC9RS9B5RrCvT3RPzuZDeoylVD i2wiaSBxeLUEdWDnKzrblJDdxYe5sy+WSHBJ5ensM415B4USDIKJ53yD2+sEItNr8HSs SKZZrFjK5FDGkV9jBhqUyJByDj8Yi8McN5Azu7PvnHhMaFGzmwcBcBxuszdOBvsXxViI R5pJ+eh8Uwm4demOs/UmEHA987Spi606fLgulqdf11mSBX53FnxFHO6qakLyDBXy3mD/ YUAPFBUi602Pelp+kMJLhu3eXMm0kS2U7SqC/w83icUT4sOKe6lJokRwnNiYOQfGVFbc 3V1g==; darn=isar-build.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b="Ny/Q4+7n"; spf=pass (google.com: domain of fm-294854-20241120170302413b85933058203d75-t399yn@rts-flowmailer.siemens.com designates 185.136.64.225 as permitted sender) smtp.mailfrom=fm-294854-20241120170302413b85933058203d75-t399Yn@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=1732122185; x=1732726985; 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=CQ752KkHo7czABHpD7P26TBcdh7fW3ep8nqsK6ACXbs=; b=dA/XwpUkZR/jYAGwK7EoI7oZF9tM2iYjtzuHFnMro5vnWcTjL8wrsHc4I0hMsMdZ0u nZ2v1lYi9r8MQlrYoFWzpVpc1zcZB4QRFQus/Ud/6zNex5LrfUVx9VB6WtG5II/0Uy+b FsETjZEjqGyAAE3BR+ZXCDdRIik9n1HV8m8pu/oVtbxqjKllzVtnFzKcP6P86uWLb/4T rvuCuODeiwvEolUvGh5ACzaP27xRWXFbBbg049lAFf/JQtndLMv54Qozl7EX9crC1a27 wSHwRucyTinwZvAs6nnVitN5U4d5Wk40kfHudc1Idg2NCXu5TqjwLoFg4/OF7BHZo+jP dYMQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1732122185; x=1732726985; 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=CQ752KkHo7czABHpD7P26TBcdh7fW3ep8nqsK6ACXbs=; b=KR2deGwXhbZR1gDfCsFcykT4r+jYyYg335DLOwqQLSN/t4ol7HlXtW5K9VBF9q1mz+ J+R4DdU+iEPTadhjsQ52EcktWKnUwGQF8Tmp0fyUQyWXbJpRmxNUVUQBdZlo31liLpb8 czGrSsFlAmF9Sydzd00HrF4X5uozzSV1rM6v5iewaOz/dLUKSErISMETIYe31zTzBb6S 0J6X/YtMl/XftRG3iGildRqNA537NGGR1eTA3RKBeukleuhYDXAb69mBwZD6unQLJ+56 W4w5NgsSdOLFJ8Ai1+7Tuk+oLZt0v3tgGYSdLOMgIXrebShE/XDZCuXfiCExDRfsVb5x ulDQ== X-Forwarded-Encrypted: i=2; AJvYcCWUZQKgBT09x/8t/cDTvf95/VWe4hwHCLHkPFVvT3h/oZXqRvo7M7yviVDVPCinoLbPJkzJ22I=@isar-build.org X-Gm-Message-State: AOJu0YwYCTO8qNdrbnbERvQlBACNIC+Q9QOBZQI8sPOdyonvLusEZF4H 89qw63SMyhYn/x2jL7gWrsStXe7Ctqnb9MoIOSAhoAptd+dtFMsF X-Google-Smtp-Source: AGHT+IFM4PzV74mbJLJR2q768fCn7t0AOXu73Mj/8QGsgS2GYqlSoHIOMm7ZO6y3/3bqjhmFY5z12A== X-Received: by 2002:a05:6870:9898:b0:296:e0f7:d690 with SMTP id 586e51a60fabf-296e0f7d91fmr2196967fac.3.1732122185484; Wed, 20 Nov 2024 09:03:05 -0800 (PST) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a05:6870:aa87:b0:288:5cb4:680 with SMTP id 586e51a60fabf-296fcbf8280ls23470fac.1.-pod-prod-07-us; Wed, 20 Nov 2024 09:03:04 -0800 (PST) X-Received: by 2002:a05:6870:20a:b0:296:cdee:f7de with SMTP id 586e51a60fabf-296d9c025a2mr3086592fac.21.1732122184421; Wed, 20 Nov 2024 09:03:04 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1732122184; cv=none; d=google.com; s=arc-20240605; b=Lkuv3mLFKVMzQ2LHaCCPProaZsYzXV9VAcomnigk+53vBFJ4kJla2WZknFEaochoP/ /UmXOLES6p4NLJeOE5MuZCrBUXvCKyE2JpDf9Ya8dZtJa/xTfxxqu7J9eC8rPsPQJSmq eQUw4FmaFtiKcmwyqHNrmuG+7Eby/jAm/VJu6kMWsoR/4Kg+SM+ZgNyE1fJ6pvjsKIsn ljD0QNANCbVZTHvu3XwfmTdtZrhVc/2wDCLFuocXR4MH04+aWlAWriX/yLmJKRYEFLg3 Qt3yT2sOJPuWVe+5dNOJvQ8Q6AshdDrVwo+trKY33+H8DTCnSSsYSdNS237SQgjgM3lP MCKQ== 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=QQMS82QvwYSc+U6k/DHJN8/W8srN8wb3/sW85AmsiYo=; fh=TWGwN84gUgHIe5O4CbyH9KISyeWwGbvUX7cnJPxVD70=; b=QFtNKkZO479liJlWwk3NWvIo8M9cWWU8qeLbSudH0ghH+7QODWQCdgG79clJGz+6a0 3W7Mf3Eo8/VjOfXfLwNlw1ZA4VBiivbdMk2wptTVai9AcWwqpqGScFxE+RSKLPFMaUFC 46L/dU5ORJFlBTVGg7TuTZrXMlhvegXUNIT0TI/rMSCPqsR8QbkI6d1aubuHWumDk6Hb 7MzvhvewiJpZNVVOxgE9kf5KeecY4VLJaRn6rkNUxnE5B16PcGRqnKSzD1oKgP37a8fA jj5brs+lCn4twM/taAa87rV/Ah4SI5LgnXKdUEGxPpBNfZfHdFFByqahkBomfXVOxtaO 2jRw==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b="Ny/Q4+7n"; spf=pass (google.com: domain of fm-294854-20241120170302413b85933058203d75-t399yn@rts-flowmailer.siemens.com designates 185.136.64.225 as permitted sender) smtp.mailfrom=fm-294854-20241120170302413b85933058203d75-t399Yn@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from mta-64-225.siemens.flowmailer.net (mta-64-225.siemens.flowmailer.net. [185.136.64.225]) by gmr-mx.google.com with ESMTPS id 586e51a60fabf-29651a04bd8si460913fac.1.2024.11.20.09.03.04 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 20 Nov 2024 09:03:04 -0800 (PST) Received-SPF: pass (google.com: domain of fm-294854-20241120170302413b85933058203d75-t399yn@rts-flowmailer.siemens.com designates 185.136.64.225 as permitted sender) client-ip=185.136.64.225; Received: by mta-64-225.siemens.flowmailer.net with ESMTPSA id 20241120170302413b85933058203d75 for ; Wed, 20 Nov 2024 18:03:02 +0100 X-Patchwork-Original-From: "'Jan Kiszka' via isar-users" From: Jan Kiszka To: isar-users Cc: Quirin Gylstorff Subject: [PATCH v5 2/7] doc: Describe initramfs customizations Date: Wed, 20 Nov 2024 18:02:56 +0100 Message-ID: <3e9a467f3d939ff03091b5fcd0ceca54c6fdceb5.1732122181.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=fm2 header.b="Ny/Q4+7n"; spf=pass (google.com: domain of fm-294854-20241120170302413b85933058203d75-t399yn@rts-flowmailer.siemens.com designates 185.136.64.225 as permitted sender) smtp.mailfrom=fm-294854-20241120170302413b85933058203d75-t399Yn@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 | 58 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/doc/user_manual.md b/doc/user_manual.md index 8f745214..1e505c66 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -1611,3 +1611,61 @@ 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(s). + +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`. +If you do not benefit from the script header with its static `SCRIPT_PREREQ`, +you may instead provide `init-top-complete`, `init-premount-complete` etc. to +still use automatic installation while defining the boot script completely +yourself. + +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.