docs: Document finding deployments in install-to-existing-root

cgwalters · cgwalters · commit 99123ba27cd2 · 2025-11-21T16:38:26.000-05:00
Users doing `bootc install to-existing-root` previously had no easy way to find the ostree deployment before rebooting in order to inject configuration files. This addresses that gap. Key changes: - Document using `ostree admin --print-current-dir` to find the newly created deployment path before rebooting - Clarify the two distinct scenarios: injecting new configuration before reboot vs. migrating old data after reboot - Add examples for both file-based configuration and kernel arguments (via `systemd.mount-extra`) - Cross-link documentation between general install docs and the to-existing-root man page - Fix typo in path structure documentation Related: #531 Assisted-by: Claude Code (Sonnet 4.5) Signed-off-by: Colin Walters <walters@verbum.org>
diff --git a/docs/src/bootc-install.md b/docs/src/bootc-install.md
@@ -166,6 +166,11 @@ an `/etc/hostname` into the target root. At the current time, bootc does
 not offer a direct API to do this. However, the backend for bootc is
 ostree, and it is possible to enumerate the deployments via ostree APIs.
 
+You can use `ostree admin --sysroot=/path/to/target --print-current-dir` to
+find the newly created deployment directory. For detailed examples and usage,
+see the [Injecting configuration before first boot](#before-reboot-injecting-new-configuration)
+section under `to-existing-root` documentation below.
+
 We hope to provide a bootc-supported method to find the deployment in
 the future.
 
@@ -216,22 +221,106 @@ It is assumed in this command that the target rootfs is pased via `-v /:/target`
 
 As noted above, the data in `/boot` will be wiped, but everything else in the existing
 operating `/` is **NOT** automatically cleaned up.  This can
-be useful, because it allows the new image to automatically import data from the previous
-host system!  For example, container images, database, user home directory data, config
-files in `/etc` are all available after the subsequent reboot in `/sysroot` (which
+be useful, because it allows the new image to access data from the previous
+host system.  For example, container images, database, user home directory data, and
+config files in `/etc` are all available after the subsequent reboot in `/sysroot` (which
 is the "physical root").
 
 However, previous mount points or subvolumes will not be automatically
 mounted in the new system, e.g. a btrfs subvolume for /home will not be automatically mounted to
 /sysroot/home. These filesystems will persist and can be handled any way you want like manually
 mounting them or defining the mount points as part of the bootc image.
 
-A special case of this trick is using the `--root-ssh-authorized-keys` flag to inherit
-root's SSH keys (which may have been injected from e.g. cloud instance userdata
-via a tool like `cloud-init`).  To do this, just add
-`--root-ssh-authorized-keys /target/root/.ssh/authorized_keys`
-to the above.
+#### Managing configuration: before and after reboot
+
+There are two distinct scenarios for managing configuration with `to-existing-root`:
+
+**Before rebooting (injecting new configuration):** You can inject new configuration
+files into the newly installed deployment before the first boot. This is useful for
+adding custom `/etc/fstab` entries, systemd mount units, or other fresh configuration
+that the new system should have from the start.
+
+**After rebooting (migrating old configuration):** You can copy or migrate configuration
+and data from the old system (now accessible at `/sysroot`) to the new system. This is
+useful for preserving network settings, user accounts, or application data from the
+previous installation.
+
+##### Before reboot: Injecting new configuration
+
+After running `bootc install to-existing-root`, you may want to inject
+configuration files (such as `/etc/fstab`, systemd units, or other configuration)
+into the newly installed system before rebooting. The new deployment is located
+in the ostree repository structure at:
+
+`/target/ostree/deploy/<stateroot>/deploy/<checksum>.<serial>/`
+
+Where `<stateroot>` defaults to `default` unless specified via `--stateroot`.
 
+To find and modify the newly installed deployment:
+
+```bash
+# Get the deployment path
+DEPLOY_PATH=$(ostree admin --sysroot=/target --print-current-dir)
+
+# Add a systemd mount unit
+cat > ${DEPLOY_PATH}/etc/systemd/system/data.mount <<EOF
+[Unit]
+Description=Data partition
+
+[Mount]
+What=UUID=...
+Where=/data
+Type=xfs
+
+[Install]
+WantedBy=local-fs.target
+EOF
+```
+
+###### Injecting kernel arguments for local state
+
+An alternative approach is to key machine-local configuration from kernel arguments
+via the `--karg` option to `bootc install to-existing-root`.
+
+For example with filesystem mounts, systemd offers a `systemd.mount-extra` that
+can be used instead of `/etc/fstab`:
+
+```bash
+bootc install to-existing-root \
+  --karg="systemd.mount-extra=UUID=<uuid>:/data:xfs:defaults"
+```
+
+The `systemd.mount-extra` syntax is: `source:path:type:options`
+
+##### After reboot: Migrating data from the old system
+
+After rebooting into the new bootc system, the previous root filesystem is
+mounted at `/sysroot`. You can then migrate configuration and data from the
+old system to the new one.
+
+**Important:** Any data from `/etc` that you want to use in the new system must be
+manually copied from `/sysroot/etc` to `/etc` after rebooting into the new system.
+There is currently no automated mechanism for migrating this configuration data.
+This applies to network configurations, user accounts, application settings, and other
+system configuration stored in `/etc`.
+
+For example, after rebooting:
+
+```bash
+# Copy network configuration from the old system
+cp /sysroot/etc/sysconfig/network-scripts/ifcfg-eth0 /etc/sysconfig/network-scripts/
+
+# Copy application configuration
+cp -r /sysroot/etc/myapp /etc/
+```
+
+A special case is using the `--root-ssh-authorized-keys` flag during installation
+to automatically inherit root's SSH keys (which may have been injected from e.g.
+cloud instance userdata via a tool like `cloud-init`). To do this, add
+`--root-ssh-authorized-keys /target/root/.ssh/authorized_keys` to the install command.
+
+See also the [bootc-install-to-existing-root(8)](man/bootc-install-to-existing-root.8.md)
+man page for more details.
 
 ### Using `system-reinstall-bootc`
 
@@ -294,7 +383,11 @@ for legacy `/etc/fstab` references for `/` to use
 Per the [filesystem](filesystem.md) section, `/etc` and `/var` are machine-local
 state by default.  If you want to inject additional content after the installation
 process, at the current time this can be done by manually finding the
-target "deployment root" which will be underneath `/ostree/deploy/<stateroot/deploy/`.
+target "deployment root" which will be underneath `/ostree/deploy/<stateroot>/deploy/`.
+
+You can use `ostree admin --sysroot=/path/to/target --print-current-dir` to find
+the deployment directory. For detailed examples, see
+[Injecting configuration before first boot](#before-reboot-injecting-new-configuration).
 
 Installation software such as [Anaconda](https://github.com/rhinstaller/anaconda)
 do this today to implement generic `%post` scripts and the like.
diff --git a/docs/src/man/bootc-install-to-existing-root.8.md b/docs/src/man/bootc-install-to-existing-root.8.md
@@ -16,6 +16,114 @@ host root filesystem\'s `/boot` partition will be wiped, but the
 content of the existing root will otherwise be retained, and will need
 to be cleaned up if desired when rebooted into the new root.
 
+## Managing configuration: before and after reboot
+
+When using `to-existing-root`, there are two distinct scenarios for managing
+configuration files:
+
+1. **Before rebooting**: Injecting new configuration into the newly installed system
+2. **After rebooting**: Migrating configuration from the old system to the new system
+
+### Before reboot: Injecting new configuration
+
+If you need to inject new configuration files (such as custom `/etc/fstab` entries,
+systemd mount units, or other configuration) into the newly installed system before
+rebooting, you can find the deployment directory in the ostree repository structure.
+The new deployment is located at:
+
+```
+/ostree/deploy/<stateroot>/deploy/<checksum>.<serial>/
+```
+
+Where `<stateroot>` defaults to `default` unless you specified a different
+value with `--stateroot`.
+
+To find the path to the newly installed deployment:
+
+```bash
+# Get the full deployment path directly
+DEPLOY_PATH=$(ostree admin --sysroot=/target --print-current-dir)
+```
+
+This will return the full path, for example:
+`/target/ostree/deploy/default/deploy/807f233831a03d315289a4ba29c1670d8bd326d4569eabee7a84f25327997307.0`
+
+You can then modify files in that deployment. For example, to add systemd mount units:
+
+```bash
+# Get deployment path
+DEPLOY_PATH=$(ostree admin --sysroot=/target --print-current-dir)
+# Add a systemd mount unit
+vi ${DEPLOY_PATH}/etc/systemd/system/data.mount
+```
+
+#### Injecting kernel arguments for local state
+
+A better approach for machine-local configuration like filesystem mounts is to
+inject kernel arguments during installation. Kernel arguments are ideal for
+local/machine-specific state in a bootc system.
+
+For filesystem mounts, use `systemd.mount-extra` instead of `/etc/fstab`:
+
+```bash
+# Add a mount via kernel argument (preferred over /etc/fstab)
+bootc install to-existing-root \
+  --karg="systemd.mount-extra=UUID=<uuid>:/data:xfs:defaults"
+```
+
+The `systemd.mount-extra` syntax is: `source:path:type:options`
+
+You can also inject other local kernel arguments for machine-specific configuration:
+
+```bash
+# Add console settings for serial access
+bootc install to-existing-root --karg="console=ttyS0,115200"
+
+# Add storage-specific options
+bootc install to-existing-root --karg="rootflags=subvol=root"
+```
+
+This approach is cleaner than editing configuration files because kernel arguments
+are explicitly designed for local/machine-specific state in a bootc system.
+
+**Note:** In the future, this functionality will be provided via a dedicated
+bootc API to make finding and modifying the deployment more straightforward.
+
+### After reboot: Migrating data from the old system
+
+After rebooting into the new bootc system, the previous root filesystem data
+is accessible at `/sysroot` (the "physical root"). This allows you to migrate
+data from the old system to the new one.
+
+**Important:** Any configuration data from `/etc` that you want to use in the
+new system must be **manually copied** from `/sysroot/etc` to `/etc` after
+rebooting. There is currently no automated mechanism for migrating this data.
+
+For example, to migrate configuration after rebooting:
+
+```bash
+# After rebooting into the new system
+# Copy network configuration from the old system
+cp /sysroot/etc/sysconfig/network-scripts/ifcfg-eth0 /etc/sysconfig/network-scripts/
+
+# Copy application configuration
+cp -r /sysroot/etc/myapp /etc/
+
+# Selectively merge configuration files
+vi /etc/resolv.conf  # Add nameservers from /sysroot/etc/resolv.conf
+
+# For user accounts, use proper tools
+vipw  # Carefully review and merge users from /sysroot/etc/passwd
+```
+
+This applies to network configurations, user accounts, application settings,
+and other system configuration stored in `/etc`. Review files in `/sysroot/etc`
+and manually copy or merge what you need into `/etc`.
+
+**Note:** For filesystem mounts from `/etc/fstab` in the old system, consider
+using kernel arguments (via `systemd.mount-extra`) injected before reboot instead
+of migrating the fstab entries. See the "Injecting kernel arguments" section above.
+
 # OPTIONS
 
 <!-- BEGIN GENERATED OPTIONS -->
