Add migration doc separately so it's less missable

magao-x · Oct 2, 2024 · 66a0b1c · 66a0b1c
1 parent 0c2a4ca
commit 66a0b1c
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 14 deletions.
diff --git a/compute/computer_setup/computer_setup.rst b/compute/computer_setup/computer_setup.rst
@@ -102,6 +102,8 @@ Date & Time
 Partitions
 ~~~~~~~~~~
 
+See :doc:`migration` if you're migrating to a new OS or new drives because you'll probably want to save files relevant to UID/GID maps, keys, tailscale, etc.
+
 -  Select all disks
 -  Select “I will configure partitioning”
 -  On 2x 512 drives:
@@ -624,17 +626,3 @@ Verify bootloader installation / RAID correctness
 -  Ensure boot proceeds without dropping to recovery prompt
 -  Replace all data drives, boot with everything in place
 
-.. _migration:
-
-Migrating data from a previous installation
--------------------------------------------
-
-There are several very important files to retain when reinstalling the operating system.
-
-  - ``/var/lib/tailscale/tailscaled.state`` -- this file allows the machine to keep its name and IP address on the VPN
-  - ``/etc/ssh/ssh_host_*_key*`` -- these files allow clients to connect over SSH without triggering a scary warning and requiring manual intervention
-  - ``/home/xsup/.ssh/{authorized_keys,id_ed25519,id_ed25519.pub,known_hosts}`` -- these files allow ``xsup`` to connect to other MagAO-X machines without prompting for host key verification
-  - ``/etc/{passwd,group,shadow}`` -- these files contain the UID and GID mappings and user passwords to restore
-  - ``/etc/systemd/system/renew_certificates.service.d/override.conf`` -- API credentials used by the ``lego`` command to renew HTTPS certificates used by the web UI
-
-You may additionally want to back up the user home directories to retain their configuration files, though they should store data on the `/data` partition.
diff --git a/compute/migration.rst b/compute/migration.rst
@@ -0,0 +1,12 @@
+Migrating data from a previous installation
+===========================================
+
+There are several very important files to retain when reinstalling the operating system.
+
+  - ``/var/lib/tailscale/tailscaled.state`` -- this file allows the machine to keep its name and IP address on the VPN
+  - ``/etc/ssh/ssh_host_*_key*`` -- these files allow clients to connect over SSH without triggering a scary warning and requiring manual intervention
+  - ``/home/xsup/.ssh/{authorized_keys,id_ed25519,id_ed25519.pub,known_hosts}`` -- these files allow ``xsup`` to connect to other MagAO-X machines without prompting for host key verification
+  - ``/etc/{passwd,group,shadow}`` -- these files contain the UID and GID mappings and user passwords to restore. Manual surgery will be required because new installs come with new system accounts. Generally, we only want to migrate user accounts (UID ≥ 1000).
+  - ``/etc/systemd/system/renew_certificates.service.d/override.conf`` -- API credentials used by the ``lego`` command to renew HTTPS certificates used by the web UI (only on AOC)
+
+You may additionally want to back up the user home directories to retain their configuration files, though they should store data on the `/data` partition.