Merge #196

196: doc: enact bootstrapping section r=nrdxp a=blaggacao

closes: #193

Co-authored-by: David Arnold <dar@xoe.solutions>

SUMMARY.md

@@ -3,6 +3,7 @@
 - [Introduction](./README.md)
 - [Quick Start](./doc/start/index.md)
   - [ISO](./doc/start/iso.md)
+  - [Bootstrapping](./doc/start/bootstrapping.md)
   - [From NixOS](./doc/start/from-nixos.md)
 - [Layout](./doc/layout.md)
   - [Cachix](./cachix/README.md)

doc/integrations/deploy.md

@@ -44,6 +44,6 @@ deploy "flk#hostName" --hostname host.example.com
 ```
 
 > ##### _Note:_
-> Your user will need sudo access
+> Your user will need **passwordless** sudo access
 
 [d-rs]: https://github.com/serokell/deploy-rs

doc/start/bootstrapping.md

@@ -0,0 +1,99 @@
+# Bootstrapping
+
+This will help you boostrap a bare host with the help of the 
+[bespoke iso](./iso) live installer.
+
+_Note: nothing prevents you from remotely executing the boostrapping 
+process. See below._
+
+Once your target host has booted into the live iso, you need to partion
+and format your disk according to the [official manual][manual].
+
+## Mount partitions
+
+Then properly mount the formatted partitions at `/mnt`, so that you can
+install your system to those new partitions.
+
+Mount `nixos` partition to `/mnt` and — for UEFI — `boot` 
+partition to `/mnt/boot`:
+
+```console
+$ mount /dev/disk/by-label/nixos /mnt
+$ mkdir -p /mnt/boot && mount /dev/disk/by-label/boot /mnt/boot # UEFI only
+$ swapon /dev/$your_swap_partition
+```
+
+## Install
+
+Install using the `flk` wrapper baked into the iso off of a copy of devos 
+from the time the iso was built:
+
+```console
+$ cd /iso/devos
+$ nix develop
+$ flk install NixOS --impure # use same host as above
+```
+
+<!-- TODO: find out why --impure is necesary / PRs welcome! -->
+
+## Notes of interest
+
+### Remote access to the live installer
+
+The iso live installer comes preconfigured with a network configuration
+which announces it's hostname via [MulticastDNS][mDNS] as `hostname.local`, 
+that is `NixOS.local` in the [iso example](./iso).
+
+In the rare case that [MulticastDNS][mDNS] is not availabe or turned off
+in your network, there is a static link-local IPv6 address configured to
+`fe80::47`(mnemonic from the letter's position in the english alphabet:
+`n=14 i=9 x=24; 47 = n+i+x`).
+
+Provided that you have added your public key to the authorized keys of the
+`root` user _(hint: [`deploy-rs`](../integrations/deploy) needs passwordless
+sudo access)_:
+
+```nix
+{ ... }:
+{
+  users.users.root.openssh.authorizedKeys.keyFiles = [
+    ../secrets/path/to/key.pub
+  ];
+}
+```
+
+You can then ssh into the live installer through one of the 
+following options:
+
+```console
+ssh root@NixOS.local
+
+ssh root@fe80::47%eno1  # where eno1 is your network interface on which you are linked to the target
+```
+
+_Note: the [static link-local IPv6 address][staticLLA] and [MulticastDNS][mDNS] is only
+configured on the live installer. If you wish to enable [MulticastDNS][mDNS]
+for your environment, you ought to configure that in a regular [profile](../../profiles)._
+
+### EUI-64 LLA & Host Identity
+
+The iso's IPv6 Link Local Address (LLA) is configured with a static 64-bit Extended
+Unique Identifiers (EUI-64) that is derived from the host interface's Message
+Authentication Code (MAC) address.
+
+After a little while (a few seconds), you can remotely discover this unique and host
+specific address over [NDP][NDP] for example with:
+
+```console
+ip -6 neigh show # also shows fe80::47
+```
+
+***This LLA is stable for the host, unless you need to swap that particular network card.*** 
+Under this reservation, though, you may use this EUI-64 to wire up a specific
+(cryptographic) host identity.
+
+
+[manual]: https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
+[mDNS]: https://en.wikipedia.org/wiki/Multicast_DNS
+[NDP]: https://en.wikipedia.org/wiki/Neighbor_Discovery_Protocol
+[staticLLA]: https://tools.ietf.org/html/rfc7404

doc/start/index.md

@@ -34,6 +34,7 @@ In addition, the [binary cache](../../cachix) is added for faster deployment.
 
 ## Next Steps:
 - [Make installable ISO](./iso.md)
+- [Bootstrap Host](./bootstrapping.md)
 - [Already on NixOS](./from-nixos.md)
 
 

doc/start/iso.md

@@ -10,42 +10,6 @@ dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
 
 This works for any file matching `hosts/*.nix` excluding `default.nix`.
 
-## Remote access to the live installer
-
-The iso live installer comes preconfigured with a network configuration
-which announces it's hostname via [MulticastDNS][mDNS] as `hostname.local`, 
-that is `NixOS.local` in the above example.
-
-In the rare case that [MulticastDNS][mDNS] is not availabe or turned off
-in your network, there is a static link-local IPv6 address configured to
-`fe80::47`(mnemonic from the letter's position in the english alphabet:
-`n=14 i=9 x=24; 47 = n+i+x`).
-
-Provided that you have added your public key to the authorized keys of the
-`nixos` user:
-
-```nix
-{ ... }:
-{
-  users.users.nixos.openssh.authorizedKeys.keyFiles = [
-    ../secrets/path/to/key.pub
-  ];
-}
-```
-
-You can then ssh into the live installer through one of the 
-following options:
-
-```console
-ssh nixos@NixOS.local
-
-ssh nixos@fe80::47%eno1  # where eno1 is your network interface on which you are linked to the target
-```
-
-_Note: the [static link-local IPv6 address][staticLLA] and [MulticastDNS][mDNS] is only
-configured on the live installer. If you wish to enable [MulticastDNS][mDNS]
-for your environment, you ought to configure that in a regular [profile](../../profiles)._
-
 ## ISO image nix store & cache
 
 The iso image holds the store to the live environment and _also_ acts as a binay cache
@@ -58,58 +22,3 @@ those local cache hits.
 For hosts that don't differ too much, a common usb stick might be ok, whereas when
 there are bigger differences, a bespoke usb stick will be considerably faster.
 
-## EUI-64 LLA & Host Identity
-
-The iso's IPv6 Link Local Address (LLA) is configured with a static 64-bit Extended
-Unique Identifiers (EUI-64) that is derived from the host interface's Message
-Authentication Code (MAC) address.
-
-After a little while (a few seconds), you can remotely disvover this unique and host
-specific address over [NDP][NDP] for example with:
-
-```console
-ip -6 neigh show # also shows fe80::47
-```
-
-***This LLA is stable for the host, unless you need to swap that particular network card.*** 
-Under this reservation, though, you may use this EUI-64 to wire up a specific
-(cryptographic) host identity.
-
-## Bootstrap Target Machine
-
-_Note: nothing prevents you from remotely exceuting the boostrapping process._
-
-Once your target host has booted into the live iso, you need to partion
-and format your disk according to the [official manual][manual].
-
-### Mount partitions
-
-Then properly mount the formatted partitions at `/mnt`, so that you can
-install your system to those new partitions.
-
-Mount `nixos` partition to `/mnt` and — for UEFI — `boot` 
-partition to `/mnt/boot`:
-
-```console
-$ mount /dev/disk/by-label/nixos /mnt
-$ mkdir -p /mnt/boot && mount /dev/disk/by-label/boot /mnt/boot # UEFI only
-$ swapon /dev/$your_swap_partition
-```
-
-### Install
-
-Install using the `flk` wrapper baked into the iso off of a copy of devos 
-from the time the iso was built:
-
-```console
-$ cd /iso/devos
-$ nix develop
-$ flk install NixOS --impure # use same host as above
-```
-
-<!-- TODO: find out why --impure is necesary / PRs welcome! -->
-
-[manual]: https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
-[mDNS]: https://en.wikipedia.org/wiki/Multicast_DNS
-[NDP]: https://en.wikipedia.org/wiki/Neighbor_Discovery_Protocol
-[staticLLA]: https://tools.ietf.org/html/rfc7404