From nobody Tue Feb 10 00:58:45 2026 Received: from mail.zytor.com (terminus.zytor.com [198.137.202.136]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 70EAF192590; Sat, 24 Jan 2026 00:40:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.136 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769215224; cv=none; b=dUbEolHMJ6fBjqXPEhiXwTOEnZNnH9ZHCsYam4js6MCc6Hl+mv5dW3Tf7srjNeevixanun6f8FmcKYnQdJtEcNHYoCdipmV5rzztoUFVioacbAPpCwoYMNcoaBAnbVbQkW80u8kw+jR3tiyTN8C7tRzJp/6Cn1paCvI9LdIgBCY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769215224; c=relaxed/simple; bh=sxCYWInGWcJQzA2I9jwBu6cloSbClI3rKDeIROS8Aoc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Jb9mvGmglyeenR0HFz9ZuWbwanq6LWOHlHCCpezJnOilAYCOErm6+9HaAbi/YlOPivQ0jN2L7TYAW35K+cKZP/xo5HgLUNIQl+OBj7U4ydaJnwVO9myJdWpoc5Bf2Ryh7oHupuaO923xA6b0IgpDo/bcCo5KXIzX12kvZAKfKA4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=zytor.com; spf=pass smtp.mailfrom=zytor.com; dkim=pass (2048-bit key) header.d=zytor.com header.i=@zytor.com header.b=bn/0m0OP; arc=none smtp.client-ip=198.137.202.136 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=zytor.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=zytor.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=zytor.com header.i=@zytor.com header.b="bn/0m0OP" Received: from mail.zytor.com (c-76-133-66-138.hsd1.ca.comcast.net [76.133.66.138]) (authenticated bits=0) by mail.zytor.com (8.18.1/8.17.1) with ESMTPSA id 60O0dnvY1194278 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Fri, 23 Jan 2026 16:40:00 -0800 DKIM-Filter: OpenDKIM Filter v2.11.0 mail.zytor.com 60O0dnvY1194278 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=zytor.com; s=2025122301; t=1769215201; bh=4va4Vi1oM4mVPAzSfh+07TIDR6BSUY4QxzNfUhSYeE8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bn/0m0OP6ydBZerJ5bYNgIWvCw9jmD6sMeXonaQ5WDZLoLQ15pxI7MFpGS2SaU85Z gAEg+wjx8R5V9kgu6LFGiioqN5RdDkBk5eBJMMwoLdA8Sxg6MYQeGWuqjOeKJMe5UI IGrvwG5uJWTPAArLOf3MDuw7LCtjJCl23CT+QsUIzehyoO8v79/cv1FXDeDjopX4UA 29xh4rGJxZZq6V1QqqquGHEfR+E9/6ZGhDgPelcdf34JWSYWcPKefNrZQGKxzg66ry 37MVPar7XVevksRnGoMnBb17rScoElQx+5RqtfUbf02CxO59Lp+Wl46MLmyJSWgchq y+envHmh7lA/A== From: "H. Peter Anvin" To: Alexander Viro , Christian Brauner , Jan Kara , Jonathan Corbet , "H. Peter Anvin" Cc: linux-fsdevel@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Lennart Poettering , systemd-devel@lists.freedesktop.org Subject: [RFC PATCH 3/3] Documentation/initramfs: document mount points in initramfs Date: Fri, 23 Jan 2026 16:39:36 -0800 Message-ID: <20260124003939.426931-4-hpa@zytor.com> X-Mailer: git-send-email 2.52.0 In-Reply-To: <20260124003939.426931-1-hpa@zytor.com> References: <20260124003939.426931-1-hpa@zytor.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Document how to create mount points in initramfs, using magic "!!!MOUNT!!!" file entries, the format the kernel expects for these files, and their exact semantics. Signed-off-by: H. Peter Anvin (Intel) --- .../early-userspace/buffer-format.rst | 60 ++++++++++++++++++- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/Documentation/driver-api/early-userspace/buffer-format.rst b/D= ocumentation/driver-api/early-userspace/buffer-format.rst index 4597a91100b7..40f86b9eec75 100644 --- a/Documentation/driver-api/early-userspace/buffer-format.rst +++ b/Documentation/driver-api/early-userspace/buffer-format.rst @@ -8,8 +8,8 @@ With kernel 2.5.x, the old "initial ramdisk" protocol was c= omplemented with an "initial ramfs" protocol. The initramfs content is passed using the same memory buffer protocol used by initrd, but the content is different. The initramfs buffer contains an archive which is -expanded into a ramfs filesystem; this document details the initramfs -buffer format. +expanded into a tmpfs or ramfs filesystem; this document details the +initramfs buffer format. =20 The initramfs buffer format is based around the "newc" or "crc" CPIO formats, and can be created with the cpio(1) utility. The cpio @@ -17,6 +17,9 @@ archive can be compressed using gzip(1), or any other alg= orithm provided via CONFIG_DECOMPRESS_*. One valid version of an initramfs buffer is thus a single .cpio.gz file. =20 +In kernel version XXXX the feature to mount additional filesystems +during initramfs expansion was introduced, see below. + The full format of the initramfs buffer is defined by the following grammar, where:: =20 @@ -130,3 +133,56 @@ a) Separate the different file data sources with a "TR= AILER!!!" end-of-archive marker, or =20 b) Make sure c_nlink =3D=3D 1 for all nondirectory entries. + + +Mounting additional filesystems +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +If a regular file with the special name "!!!MOUNT!!!" is encountered +during initramfs processing, the file contents is parsed as a mount +specification in format similar to fstab(5). It should contain of a +single line in one of the following formats:: + + fs_spec fs_vfstype fs_mntops + fs_spec fs_vfstype + fs_vfstype + + +Comment or blank lines are NOT allowed, and the terminating newline is +required. + +The specified filesystem is then mounted onto the directory in which +the !!!MOUNT!!! file is located, for example, if the file is named:: + + dev/!!!MOUNT!!! + + +then the filesystem will be mounted onto the /dev directory, which +must already exist. + +The mount is performed immediately, before processing any further +initramfs entries. + +The c_mode, c_uid, c_gid, and c_mtime (with CONFIG_INITRAMFS_PRESERVE_MTIM= E) +values for the file are applied to the root directory of the newly +mounted filesystem, if that filesystem is writable and allows those +operations. Therefore, the !!!MOUNT!!! file should typically have the +x permission bit set, as a directory would. + +fs_spec or fs_mntops values that require user space support, such as +LABEL=3D or UUID=3D, are not supported. To mount a filesystem that +requires a block device, the appropriate /dev entry need to have +been created, or devtmpfs have been mounted, earlier in the initramfs +image. + +A !!!MOUNT!!! entry in the cpio archive root, or multiple !!!MOUNT!!! +entries for the same path, will cause overmounts. This allows the +initramfs to be expanded into a tmpfs that is separate from the +rootfs, and which therefore, unlike the rootfs, can be unmounted. + +The special name !!!MOUNT!!! was chosen because the sequence !!! +already has special meaning in cpio (the TRAILER!!! entry) and because +! is the lowest-numbered non-blank character in ASCII. Therefore +creating a sorted cpio archive will naturally end up with the +!!!MOUNT!!! entry immediately after the directory itself and before +its contents. --=20 2.52.0