[PATCH] host/rootfs: add mount-userdata command

[PATCH] host/rootfs: add mount-userdata command

[Alyssa Ross]

We shouldn't leave it to the user to manually mount user data
partitions.  We want to ensure restrictive mount flags are set, and be
able to do other operations around the mounting.  It's also nice to
have a single place where all user data partitions can be mounted.
I've taken inspiration from the FHS in using /media for this.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
---
 .../development/persistent-storage.adoc       | 19 ++++++++++-----
 .../using-spectrum/creating-custom-vms.adoc   |  5 ++--
 .../using-spectrum/vm-file-access.adoc        |  4 ++--
 host/rootfs/Makefile                          |  2 +-
 host/rootfs/file-list.mk                      |  1 +
 host/rootfs/image/etc/fstab                   | 11 +++++----
 host/rootfs/image/usr/bin/mount-userdata      | 24 +++++++++++++++++++
 7 files changed, 50 insertions(+), 16 deletions(-)
 create mode 100755 host/rootfs/image/usr/bin/mount-userdata

diff --git a/Documentation/development/persistent-storage.adoc b/Documentation/development/persistent-storage.adoc
index 12426b46..c4bcc163 100644
--- a/Documentation/development/persistent-storage.adoc
+++ b/Documentation/development/persistent-storage.adoc
@@ -2,7 +2,7 @@
 :page-parent: Development
 :page-nav_order: 2
 
-// SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
 Spectrum's root filesystem is immutable, so if you want to be able to
@@ -10,8 +10,15 @@ persist data between sessions, you'll need to create a persistent
 storage partition.  Spectrum comes with `cryptsetup`, and in future is
 likely to assume that btrfs-specific features are available.
 
-Conventionally, the persistent storage partition is mounted on /ext
-after booting.  It's not mounted automatically, because generally the
-partition should be encrypted, meaning a key has to be supplied to
-mount it anyway, and because there might be multiple persistent data
-partitions to choose from.
+Persistent storage can be mounted as follows:
+
+[source,shell]
+----
+cryptsetup open /dev/sda1 userdata
+mount-userdata /dev/mapper/userdata
+----
+
+It's not mounted automatically, because generally the partition should
+be encrypted, meaning a key has to be supplied to mount it anyway, and
+because there might be multiple persistent data partitions to choose
+from.
diff --git a/Documentation/using-spectrum/creating-custom-vms.adoc b/Documentation/using-spectrum/creating-custom-vms.adoc
index a397ac50..1eca7f36 100644
--- a/Documentation/using-spectrum/creating-custom-vms.adoc
+++ b/Documentation/using-spectrum/creating-custom-vms.adoc
@@ -13,8 +13,9 @@ configurations are directories under a dedicated parent directory, and
 the name of each configuration directory determines the name of
 the VM.  After mounting the persistent storage partition, the
 configured VMs can be made available by running `vm-import user
-/ext/vms`, replacing /ext/vms with the directory containing the VM
-definitions.
+/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms`, replacing
+/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms with the directory
+containing the VM definitions.
 
 The directory can contain the following files:
 
diff --git a/Documentation/using-spectrum/vm-file-access.adoc b/Documentation/using-spectrum/vm-file-access.adoc
index 1b4fe9a5..a079cfe8 100644
--- a/Documentation/using-spectrum/vm-file-access.adoc
+++ b/Documentation/using-spectrum/vm-file-access.adoc
@@ -48,7 +48,7 @@ can be bind-mounted into it:
 +
 [listing]
 [source,shell]
-echo "Hello, world!" > /ext/example.txt
+echo "Hello, world!" > /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt
 
 2. Create an empty file to bind mount over:
 +
@@ -60,5 +60,5 @@ touch /run/vm/by-name/user.appvm-example/fs/example.txt
 +
 [listing]
 [source,shell]
-mount --rbind /ext/example.txt /run/vm/by-name/user.appvm-example/fs/example.txt
+mount --rbind /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt /run/vm/by-name/user.appvm-example/fs/example.txt
 ====
diff --git a/host/rootfs/Makefile b/host/rootfs/Makefile
index 7bec1259..211fb5dd 100644
--- a/host/rootfs/Makefile
+++ b/host/rootfs/Makefile
@@ -33,8 +33,8 @@ DIRS = \
 	etc/s6-linux-init/run-image/user \
 	etc/s6-linux-init/run-image/vm/by-id \
 	etc/s6-linux-init/run-image/vm/by-name \
-	ext \
 	home \
+	media \
 	proc \
 	run \
 	sys \
diff --git a/host/rootfs/file-list.mk b/host/rootfs/file-list.mk
index f69775d2..6bf40ff8 100644
--- a/host/rootfs/file-list.mk
+++ b/host/rootfs/file-list.mk
@@ -56,6 +56,7 @@ FILES = \
 	image/etc/xdg/weston/weston.ini \
 	image/usr/bin/assign-devices \
 	image/usr/bin/create-vm-dependencies \
+	image/usr/bin/mount-userdata \
 	image/usr/bin/root-terminal \
 	image/usr/bin/run-appimage \
 	image/usr/bin/run-flatpak \
diff --git a/host/rootfs/image/etc/fstab b/host/rootfs/image/etc/fstab
index 5c23a374..18bb5e45 100644
--- a/host/rootfs/image/etc/fstab
+++ b/host/rootfs/image/etc/fstab
@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: CC0-1.0
 # SPDX-FileCopyrightText: 2020-2021, 2025 Alyssa Ross <hi@alyssa.is>
-proc	/proc		proc	nosuid,nodev,noexec		0	0
-devpts	/dev/pts	devpts	nosuid,noexec,gid=5,mode=620	0	0
-tmpfs	/dev/shm	tmpfs	nosuid,nodev			0	0
-sysfs	/sys		sysfs	nosuid,nodev,noexec		0	0
-tmpfs	/tmp		tmpfs	nosuid,nodev			0	0
+proc	/proc		proc	nosuid,nodev,noexec				0	0
+devpts	/dev/pts	devpts	nosuid,noexec,gid=5,mode=620			0	0
+tmpfs	/dev/shm	tmpfs	nosuid,nodev					0	0
+tmpfs	/media		tmpfs	nosuid,nodev,noexec,nosymfollow,mode=755	0	0
+sysfs	/sys		sysfs	nosuid,nodev,noexec				0	0
+tmpfs	/tmp		tmpfs	nosuid,nodev					0	0
diff --git a/host/rootfs/image/usr/bin/mount-userdata b/host/rootfs/image/usr/bin/mount-userdata
new file mode 100755
index 00000000..e4a873c0
--- /dev/null
+++ b/host/rootfs/image/usr/bin/mount-userdata
@@ -0,0 +1,24 @@
+#!/bin/execlineb -W
+# SPDX-License-Identifier: EUPL-1.2+
+# SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
+
+backtick -D "" uuid {
+  importas -Siu 1
+  blkid -o value -s UUID $1
+}
+
+multisubstitute {
+  importas -Siu 0
+  importas -Siu 1
+  importas -Siu uuid
+}
+
+case $uuid {
+  "" {
+    fdmove -c 1 2
+    printf "%s: '%s' does not have a UUID\n" $0 $1
+  }
+}
+
+if { mount -m -o nosuid,nodev,noexec,nosymfollow -- $1 /media/${uuid} }
+printf "%s\n" /media/${uuid}

base-commit: 1afc3a7042ee1c40b6d2e564219be31ea8f1017f
-- 
2.51.0

Re: [PATCH] host/rootfs: add mount-userdata command

[Demi Marie Obenour]

[-- Attachment #1.1.1: Type: text/plain, Size: 7306 bytes --]

On 12/12/25 16:48, Alyssa Ross wrote:
> We shouldn't leave it to the user to manually mount user data
> partitions.  We want to ensure restrictive mount flags are set, and be
> able to do other operations around the mounting.  It's also nice to
> have a single place where all user data partitions can be mounted.
> I've taken inspiration from the FHS in using /media for this.

Yay!  I kept doing this manually and it was annoying.

> Signed-off-by: Alyssa Ross <hi@alyssa.is>
> ---
>  .../development/persistent-storage.adoc       | 19 ++++++++++-----
>  .../using-spectrum/creating-custom-vms.adoc   |  5 ++--
>  .../using-spectrum/vm-file-access.adoc        |  4 ++--
>  host/rootfs/Makefile                          |  2 +-
>  host/rootfs/file-list.mk                      |  1 +
>  host/rootfs/image/etc/fstab                   | 11 +++++----
>  host/rootfs/image/usr/bin/mount-userdata      | 24 +++++++++++++++++++
>  7 files changed, 50 insertions(+), 16 deletions(-)
>  create mode 100755 host/rootfs/image/usr/bin/mount-userdata
> 
> diff --git a/Documentation/development/persistent-storage.adoc b/Documentation/development/persistent-storage.adoc
> index 12426b46..c4bcc163 100644
> --- a/Documentation/development/persistent-storage.adoc
> +++ b/Documentation/development/persistent-storage.adoc
> @@ -2,7 +2,7 @@
>  :page-parent: Development
>  :page-nav_order: 2
>  
> -// SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
> +// SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
>  Spectrum's root filesystem is immutable, so if you want to be able to
> @@ -10,8 +10,15 @@ persist data between sessions, you'll need to create a persistent
>  storage partition.  Spectrum comes with `cryptsetup`, and in future is
>  likely to assume that btrfs-specific features are available.
>  
> -Conventionally, the persistent storage partition is mounted on /ext
> -after booting.  It's not mounted automatically, because generally the
> -partition should be encrypted, meaning a key has to be supplied to
> -mount it anyway, and because there might be multiple persistent data
> -partitions to choose from.
> +Persistent storage can be mounted as follows:
> +
> +[source,shell]
> +----
> +cryptsetup open /dev/sda1 userdata
> +mount-userdata /dev/mapper/userdata
> +----
> +
> +It's not mounted automatically, because generally the partition should
> +be encrypted, meaning a key has to be supplied to mount it anyway, and
> +because there might be multiple persistent data partitions to choose
> +from.
> diff --git a/Documentation/using-spectrum/creating-custom-vms.adoc b/Documentation/using-spectrum/creating-custom-vms.adoc
> index a397ac50..1eca7f36 100644
> --- a/Documentation/using-spectrum/creating-custom-vms.adoc
> +++ b/Documentation/using-spectrum/creating-custom-vms.adoc
> @@ -13,8 +13,9 @@ configurations are directories under a dedicated parent directory, and
>  the name of each configuration directory determines the name of
>  the VM.  After mounting the persistent storage partition, the
>  configured VMs can be made available by running `vm-import user
> -/ext/vms`, replacing /ext/vms with the directory containing the VM
> -definitions.
> +/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms`, replacing
> +/media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/vms with the directory
> +containing the VM definitions.
>  
>  The directory can contain the following files:
>  
> diff --git a/Documentation/using-spectrum/vm-file-access.adoc b/Documentation/using-spectrum/vm-file-access.adoc
> index 1b4fe9a5..a079cfe8 100644
> --- a/Documentation/using-spectrum/vm-file-access.adoc
> +++ b/Documentation/using-spectrum/vm-file-access.adoc
> @@ -48,7 +48,7 @@ can be bind-mounted into it:
>  +
>  [listing]
>  [source,shell]
> -echo "Hello, world!" > /ext/example.txt
> +echo "Hello, world!" > /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt
>  
>  2. Create an empty file to bind mount over:
>  +
> @@ -60,5 +60,5 @@ touch /run/vm/by-name/user.appvm-example/fs/example.txt
>  +
>  [listing]
>  [source,shell]
> -mount --rbind /ext/example.txt /run/vm/by-name/user.appvm-example/fs/example.txt
> +mount --rbind /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt /run/vm/by-name/user.appvm-example/fs/example.txt
>  ====
> diff --git a/host/rootfs/Makefile b/host/rootfs/Makefile
> index 7bec1259..211fb5dd 100644
> --- a/host/rootfs/Makefile
> +++ b/host/rootfs/Makefile
> @@ -33,8 +33,8 @@ DIRS = \
>  	etc/s6-linux-init/run-image/user \
>  	etc/s6-linux-init/run-image/vm/by-id \
>  	etc/s6-linux-init/run-image/vm/by-name \
> -	ext \
>  	home \
> +	media \
>  	proc \
>  	run \
>  	sys \
> diff --git a/host/rootfs/file-list.mk b/host/rootfs/file-list.mk
> index f69775d2..6bf40ff8 100644
> --- a/host/rootfs/file-list.mk
> +++ b/host/rootfs/file-list.mk
> @@ -56,6 +56,7 @@ FILES = \
>  	image/etc/xdg/weston/weston.ini \
>  	image/usr/bin/assign-devices \
>  	image/usr/bin/create-vm-dependencies \
> +	image/usr/bin/mount-userdata \
>  	image/usr/bin/root-terminal \
>  	image/usr/bin/run-appimage \
>  	image/usr/bin/run-flatpak \
> diff --git a/host/rootfs/image/etc/fstab b/host/rootfs/image/etc/fstab
> index 5c23a374..18bb5e45 100644
> --- a/host/rootfs/image/etc/fstab
> +++ b/host/rootfs/image/etc/fstab
> @@ -1,7 +1,8 @@
>  # SPDX-License-Identifier: CC0-1.0
>  # SPDX-FileCopyrightText: 2020-2021, 2025 Alyssa Ross <hi@alyssa.is>
> -proc	/proc		proc	nosuid,nodev,noexec		0	0
> -devpts	/dev/pts	devpts	nosuid,noexec,gid=5,mode=620	0	0
> -tmpfs	/dev/shm	tmpfs	nosuid,nodev			0	0
> -sysfs	/sys		sysfs	nosuid,nodev,noexec		0	0
> -tmpfs	/tmp		tmpfs	nosuid,nodev			0	0
> +proc	/proc		proc	nosuid,nodev,noexec				0	0
> +devpts	/dev/pts	devpts	nosuid,noexec,gid=5,mode=620			0	0
> +tmpfs	/dev/shm	tmpfs	nosuid,nodev					0	0
> +tmpfs	/media		tmpfs	nosuid,nodev,noexec,nosymfollow,mode=755	0	0
> +sysfs	/sys		sysfs	nosuid,nodev,noexec				0	0
> +tmpfs	/tmp		tmpfs	nosuid,nodev					0	0
> diff --git a/host/rootfs/image/usr/bin/mount-userdata b/host/rootfs/image/usr/bin/mount-userdata
> new file mode 100755
> index 00000000..e4a873c0
> --- /dev/null
> +++ b/host/rootfs/image/usr/bin/mount-userdata
> @@ -0,0 +1,24 @@
> +#!/bin/execlineb -W
> +# SPDX-License-Identifier: EUPL-1.2+
> +# SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
> +
> +backtick -D "" uuid {
> +  importas -Siu 1
> +  blkid -o value -s UUID $1

Missing "--"?

> +}
> +
> +multisubstitute {
> +  importas -Siu 0
> +  importas -Siu 1
> +  importas -Siu uuid
> +}
> +
> +case $uuid {
> +  "" {
> +    fdmove -c 1 2
> +    printf "%s: '%s' does not have a UUID\n" $0 $1
> +  }
> +}
> +
> +if { mount -m -o nosuid,nodev,noexec,nosymfollow -- $1 /media/${uuid} }
> +printf "%s\n" /media/${uuid}

Do we really want a mode of 0755?  Also, I believe Spectrum should
use noatime.  This avoids a burst of unsharing of snapshots due to
atime updates.

Should this use ‘-t btrfs’?  I thought Spectrum assumed this.

> base-commit: 1afc3a7042ee1c40b6d2e564219be31ea8f1017f


-- 
Sincerely,
Demi Marie Obenour (she/her/hers)

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 7253 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] host/rootfs: add mount-userdata command

[Alyssa Ross]

[-- Attachment #1: Type: text/plain, Size: 1361 bytes --]

Demi Marie Obenour <demiobenour@gmail.com> writes:

> On 12/12/25 16:48, Alyssa Ross wrote:
>> diff --git a/host/rootfs/image/usr/bin/mount-userdata b/host/rootfs/image/usr/bin/mount-userdata
>> new file mode 100755
>> index 00000000..e4a873c0
>> --- /dev/null
>> +++ b/host/rootfs/image/usr/bin/mount-userdata
>> @@ -0,0 +1,24 @@
>> +#!/bin/execlineb -W
>> +# SPDX-License-Identifier: EUPL-1.2+
>> +# SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
>> +
>> +backtick -D "" uuid {
>> +  importas -Siu 1
>> +  blkid -o value -s UUID $1
>
> Missing "--"?

Will add.

>> +}
>> +
>> +multisubstitute {
>> +  importas -Siu 0
>> +  importas -Siu 1
>> +  importas -Siu uuid
>> +}
>> +
>> +case $uuid {
>> +  "" {
>> +    fdmove -c 1 2
>> +    printf "%s: '%s' does not have a UUID\n" $0 $1
>> +  }
>> +}
>> +
>> +if { mount -m -o nosuid,nodev,noexec,nosymfollow -- $1 /media/${uuid} }
>> +printf "%s\n" /media/${uuid}
>
> Do we really want a mode of 0755?  Also, I believe Spectrum should
> use noatime.  This avoids a burst of unsharing of snapshots due to
> atime updates.

Will applications be okay with that?  What do OpenSUSE/Fedora do?

I'm going to go ahead with the default for now but happy to keep
discussing.

> Should this use ‘-t btrfs’?  I thought Spectrum assumed this.

Yeah, makes sense.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

Re: [PATCH] host/rootfs: add mount-userdata command

[Demi Marie Obenour]

[-- Attachment #1.1.1: Type: text/plain, Size: 1212 bytes --]

On 12/13/25 05:59, Alyssa Ross wrote:
> Demi Marie Obenour <demiobenour@gmail.com> writes:
> 
>> On 12/12/25 16:48, Alyssa Ross wrote:
>>> diff --git a/host/rootfs/image/usr/bin/mount-userdata b/host/rootfs/image/usr/bin/mount-userdata
>>> new file mode 100755
>>> index 00000000..e4a873c0
>>> --- /dev/null
>>> +++ b/host/rootfs/image/usr/bin/mount-userdata

(snip)

>>> +}
>>> +
>>> +multisubstitute {
>>> +  importas -Siu 0
>>> +  importas -Siu 1
>>> +  importas -Siu uuid
>>> +}
>>> +
>>> +case $uuid {
>>> +  "" {
>>> +    fdmove -c 1 2
>>> +    printf "%s: '%s' does not have a UUID\n" $0 $1
>>> +  }
>>> +}
>>> +
>>> +if { mount -m -o nosuid,nodev,noexec,nosymfollow -- $1 /media/${uuid} }
>>> +printf "%s\n" /media/${uuid}
>>
>> Do we really want a mode of 0755?  Also, I believe Spectrum should
>> use noatime.  This avoids a burst of unsharing of snapshots due to
>> atime updates.
> 
> Will applications be okay with that?  What do OpenSUSE/Fedora do?

I'll check.  I suspect they use relatime, but performance-wise I
doubt it's a good fit for snapshots of frequently-accessed volumesthat
rarely get written to.
-- 
Sincerely,
Demi Marie Obenour (she/her/hers)

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 7253 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] host/rootfs: add mount-userdata command

[Alyssa Ross]

This patch has been committed as 09a55b7809407be76cfe145d2f7a1dd1b5b843ec,
which can be viewed online at
https://spectrum-os.org/git/spectrum/commit/?id=09a55b7809407be76cfe145d2f7a1dd1b5b843ec.

This is an automated message.  Send comments/questions/requests to:
Alyssa Ross <hi@alyssa.is>