docs(extra-files) add howto

docs/cli.md

@@ -36,8 +36,8 @@ Options:
 * --stop-after-disko
   exit after disko formatting, you can then proceed to install manually or some other way
 * --extra-files <path>
-  path to a directory to copy into the root of the new nixos installation.
-  Copied files will be owned by root.
+  contents of local <path> are recursively copied and overwrites root (/) of the new NixOS installation.
+  Copied files will be owned by root. See documentation for details.
 * --disk-encryption-keys <remote_path> <local_path>
   copy the contents of the file or pipe in local_path to remote_path in the installer environment,
   after kexec but before installation. Can be repeated.

docs/howtos/INDEX.md

@@ -10,6 +10,8 @@
 
 [Installing on a machine with no operating system](./no-os.md)
 
+[Copying files to the new installation](./extra-files.md)
+
 [Using your own kexec image](./custom-kexec.md)
 
 [Repair installations without wiping data](./disko-modes.md)

docs/howtos/extra-files.md

@@ -0,0 +1,118 @@
+# Copying files to the new installation
+
+The `--extra-files <path>` option allows copying files to the target host after
+installation.
+
+The contents of the `<path>` is recursively copied and overwrites the targets
+root (/).  The contents *must* be in a structure and permissioned as it
+should be on the target.
+
+In this way, there is no need to repeatedly pass arguments (eg: a fictional
+argument: `--copy <source> <dest>`) to `nixos-anywhere` to complete the intended
+outcome.
+
+The path and directory structure passed to `--extra-files` should be prepared
+beforehand.
+
+This allows a simple programmatic invocation of `nixos-anywhere` for multiple
+hosts.
+
+## Simple Example
+
+You want `/etc/ssh/ssh_host_*` and `/persist` from the local system on the
+target.  The `<path>` contents will look like this:
+
+```console
+$ cd /tmp
+$ root=$(mktemp -d)
+$ sudo cp --verbose --archive --link --parents /etc/ssh/ssh_host_* ${root}
+$ cp --verbose --archive --link /persist ${root} # --parents not needed for a full path
+$ lsd --tree --long ${root}
+drwx------ myuser1 users   20  tmp.d6nx5QUwPN
+drwxr-xr-x root    root     6  ├── etc
+drwx------ myuser1 users  160  │   └── ssh
+.rw------- root    root   399  │       ├── ssh_host_ed25519_key
+.rw-r--r-- root    root    91  │       ├── ssh_host_ed25519_key.pub
+drwxr-xr-x myuser1 users   22  └── persist
+drwxr-xr-x myuser1 users   14      ├── all
+drwxr-xr-x myuser1 users   22      │   ├── my
+.rw-r--r-- myuser1 users    6      │   │   ├── test3
+drwxr-xr-x myuser1 users   10      │   │   └── things
+.rw-r--r-- myuser1 users    6      │   │       └── test4
+.rw-r--r-- myuser1 users    6      │   └── test2
+drwxr-xr-x myuser1 users    0      ├── blah
+.rw-r--r-- myuser1 users    6      └── test
+```
+
+**NOTE**: Permissions will be copied, but ownership on the target will be root.
+
+Then pass $root like:
+> nixos-anywhere --flake ".#" --extra-files $root --target-host root@newhost
+
+## Programmatic Example
+
+```sh
+for host in host1 host2 host3; do
+    root="target/${host}"
+    install -d -m755 ${root}/etc/ssh
+    ssh-keygen -A -C root@${host} -f ${root}
+    nixos-anywhere --extra-files "${root}" --flake ".#${host}" --target-host "root@${host}"
+done
+```
+
+## Considerations
+
+### Ownership
+
+The new system may have differing UNIX user and group id's for users created
+during installation.
+
+When the files are extracted on the remote the copied data will be owned by
+root.
+
+### Soft links
+
+Do not create soft links to reference data to copy.
+
+GNU `tar` is used to do the copy over ssh.  It is an archival tool used to
+re/store directory structures as is.  Thus `tar` copies soft links (aka:
+symbolic links, symlinks) created with `ln -s` by default.  It does not follow
+them to copy the underlying file.
+
+### Hard links
+
+**NOTE**: hard links can only be created on the same filesystem.
+
+GNU `tar` will copy data referenced by hard links created with `ln`.  A hard
+link does not create another copy the data.  It creates another file path that
+points to the same data.
+
+To copy a directory tree to the new target you can use the `cp` command with the
+`--link` option which creates hard links.
+
+#### Example
+
+```sh
+cd /tmp
+root=$(mktemp -d)
+cp --verbose --archive --link --parents /etc/ssh/ssh_host* ${root}
+```
+
+`--parents` will create the directory structure of the source at the
+destination.
+
+### Copy on Write (COW) file systems
+
+**NOTE**: COW only works on the same underlying filesystem (zpool on zfs).
+
+If the source file system supports copy on write (btrfs, zfs, xfs), you can copy
+the files and directories to a containing *path* (while preserving the
+structure) to pass to `--extra-files`.  This will not use more storage.
+
+#### Example
+
+```console
+mkdir target
+cp --verbose --archive --parents /etc/ssh/ssh_host* target
+```
+

docs/reference.md

@@ -48,8 +48,8 @@ Options:
 * --copy-host-keys
   copy over existing /etc/ssh/ssh_host_* host keys to the installation
 * --extra-files <path>
-  path to a directory to copy into the root of the new nixos installation.
-  Copied files will be owned by root.
+  contents of local <path> are recursively copied and overwrites root (/) of the new NixOS installation.
+  Copied files will be owned by root. See documentation for details.
 * --disk-encryption-keys <remote_path> <local_path>
   copy the contents of the file or pipe in local_path to remote_path in the installer environment,
   after kexec but before installation. Can be repeated.

src/nixos-anywhere.sh

@@ -96,8 +96,8 @@ Options:
 * --copy-host-keys
   copy over existing /etc/ssh/ssh_host_* host keys to the installation
 * --extra-files <path>
-  path to a directory to copy into the root of the new nixos installation.
-  Copied files will be owned by root.
+  contents of local <path> are recursively copied and overwrites root (/) of the new NixOS installation.
+  Copied files will be owned by root. See documentation for details.
 * --disk-encryption-keys <remote_path> <local_path>
   copy the contents of the file or pipe in local_path to remote_path in the installer environment,
   after kexec but before installation. Can be repeated.