Skip to content

Commit bf4c0c5

Browse files
phaerphaer
authored
Merge pull request #440 from sedlund/extra-files
docs(extra-files) add howto
2 parents f9d38ca + 51f8a74 commit bf4c0c5

File tree

5 files changed

+114
-6
lines changed

5 files changed

+114
-6
lines changed

‎docs/cli.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,8 @@ Options:
3636
* --stop-after-disko
3737
exit after disko formatting, you can then proceed to install manually or some other way
3838
* --extra-files <path>
39-
path to a directory to copy into the root of the new nixos installation.
40-
Copied files will be owned by root.
39+
contents of local <path> are recursively copied to the root (/) of the new NixOS installation. Existing files are overwritten
40+
Copied files will be owned by root. See documentation for details.
4141
* --disk-encryption-keys <remote_path> <local_path>
4242
copy the contents of the file or pipe in local_path to remote_path in the installer environment,
4343
after kexec but before installation. Can be repeated.

‎docs/howtos/INDEX.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010

1111
[Installing on a machine with no operating system](./no-os.md)
1212

13+
[Copying files to the new installation](./extra-files.md)
14+
1315
[Using your own kexec image](./custom-kexec.md)
1416

1517
[Repair installations without wiping data](./disko-modes.md)

‎docs/howtos/extra-files.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Copying files to the new installation
2+
3+
The `--extra-files <path>` option allows copying files to the target host after
4+
installation.
5+
6+
The contents of the `<path>` is recursively copied and overwrites the targets
7+
root (/). The contents _must_ be in a structure and permissioned as it should be
8+
on the target.
9+
10+
In this way, there is no need to repeatedly pass arguments (eg: a fictional
11+
argument: `--copy <source> <dest>`) to `nixos-anywhere` to complete the intended
12+
outcome.
13+
14+
The path and directory structure passed to `--extra-files` should be prepared
15+
beforehand.
16+
17+
This allows a simple programmatic invocation of `nixos-anywhere` for multiple
18+
hosts.
19+
20+
## Simple Example
21+
22+
You want `/etc/ssh/ssh_host_*` and `/persist` from the local system on the
23+
target. The `<path>` contents will look like this:
24+
25+
```console
26+
$ cd /tmp
27+
$ root=$(mktemp -d)
28+
$ sudo cp --verbose --archive --parents /etc/ssh/ssh_host_* ${root}
29+
$ cp --verbose --archive --link /persist ${root}
30+
```
31+
32+
The directory structure would look like this:
33+
34+
```console
35+
drwx------ myuser1 users 20 tmp.d6nx5QUwPN
36+
drwxr-xr-x root root 6 ├── etc
37+
drwx------ myuser1 users 160 │ └── ssh
38+
.rw------- root root 399 │ ├── ssh_host_ed25519_key
39+
.rw-r--r-- root root 91 │ ├── ssh_host_ed25519_key.pub
40+
drwxr-xr-x myuser1 users 22 └── persist
41+
drwxr-xr-x myuser1 users 14 ├── all
42+
drwxr-xr-x myuser1 users 22 │ ├── my
43+
.rw-r--r-- myuser1 users 6 │ │ ├── test3
44+
drwxr-xr-x myuser1 users 10 │ │ └── things
45+
.rw-r--r-- myuser1 users 6 │ │ └── test4
46+
.rw-r--r-- myuser1 users 6 │ └── test2
47+
drwxr-xr-x myuser1 users 0 ├── blah
48+
.rw-r--r-- myuser1 users 6 └── test
49+
```
50+
51+
**NOTE**: Permissions will be copied, but ownership on the target will be root.
52+
53+
Then pass $root like:
54+
55+
> nixos-anywhere --flake ".#" --extra-files $root --target-host root@newhost
56+
57+
## Programmatic Example
58+
59+
```sh
60+
for host in host1 host2 host3; do
61+
root="target/${host}"
62+
install -d -m755 ${root}/etc/ssh
63+
ssh-keygen -A -C root@${host} -f ${root}
64+
nixos-anywhere --extra-files "${root}" --flake ".#${host}" --target-host "root@${host}"
65+
done
66+
```
67+
68+
## Considerations
69+
70+
### Ownership
71+
72+
The new system may have differing UNIX user and group id's for users created
73+
during installation.
74+
75+
When the files are extracted on the remote the copied data will be owned by
76+
root.
77+
78+
### Symbolic Links
79+
80+
Do not create symbolic links to reference data to copy.
81+
82+
GNU `tar` is used to do the copy over ssh. It is an archival tool used to
83+
re/store directory structures as is. Thus `tar` copies symbolic links created
84+
with `ln -s` by default. It does not follow them to copy the underlying file.
85+
86+
### Hard links
87+
88+
**NOTE**: hard links can only be created on the same filesystem.
89+
90+
If you have larger peristent data to copy to the target. GNU `tar` will copy
91+
data referenced by hard links created with `ln`. A hard link does not create
92+
another copy the data.
93+
94+
To copy a directory tree to the new target you can use the `cp` command with the
95+
`--link` option which creates hard links.
96+
97+
#### Example
98+
99+
```sh
100+
cd /tmp
101+
root=$(mktemp -d)
102+
cp --verbose --archive --link --parents /persist/home/myuser ${root}
103+
```
104+
105+
`--parents` will create the directory structure of the source at the
106+
destination.

‎docs/reference.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ Options:
4848
* --copy-host-keys
4949
copy over existing /etc/ssh/ssh_host_* host keys to the installation
5050
* --extra-files <path>
51-
path to a directory to copy into the root of the new nixos installation.
52-
Copied files will be owned by root.
51+
contents of local <path> are recursively copied to the root (/) of the new NixOS installation. Existing files are overwritten
52+
Copied files will be owned by root. See documentation for details.
5353
* --disk-encryption-keys <remote_path> <local_path>
5454
copy the contents of the file or pipe in local_path to remote_path in the installer environment,
5555
after kexec but before installation. Can be repeated.

‎src/nixos-anywhere.sh

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,8 @@ Options:
9696
* --copy-host-keys
9797
copy over existing /etc/ssh/ssh_host_* host keys to the installation
9898
* --extra-files <path>
99-
path to a directory to copy into the root of the new nixos installation.
100-
Copied files will be owned by root.
99+
contents of local <path> are recursively copied to the root (/) of the new NixOS installation. Existing files are overwritten
100+
Copied files will be owned by root. See documentation for details.
101101
* --disk-encryption-keys <remote_path> <local_path>
102102
copy the contents of the file or pipe in local_path to remote_path in the installer environment,
103103
after kexec but before installation. Can be repeated.

0 commit comments

Comments
 (0)