From 6b5d4ce8f4938c71e146dcd2f33a4467fe24a76c Mon Sep 17 00:00:00 2001 From: David Arnold Date: Tue, 16 Mar 2021 19:19:01 -0500 Subject: [PATCH] doc: enact bootstrapping section closes: #193 --- SUMMARY.md | 1 + doc/integrations/deploy.md | 2 +- doc/start/bootstrapping.md | 99 ++++++++++++++++++++++++++++++++++++++ doc/start/index.md | 1 + doc/start/iso.md | 91 ----------------------------------- 5 files changed, 102 insertions(+), 92 deletions(-) create mode 100644 doc/start/bootstrapping.md diff --git a/SUMMARY.md b/SUMMARY.md index 1f644d9..1f34ee6 100644 --- a/SUMMARY.md +++ b/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) diff --git a/doc/integrations/deploy.md b/doc/integrations/deploy.md index 3a4dde8..710bfbc 100644 --- a/doc/integrations/deploy.md +++ b/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 diff --git a/doc/start/bootstrapping.md b/doc/start/bootstrapping.md new file mode 100644 index 0000000..8e44ce9 --- /dev/null +++ b/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 +``` + + + +## 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 diff --git a/doc/start/index.md b/doc/start/index.md index 2892c9c..48d2b16 100644 --- a/doc/start/index.md +++ b/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) diff --git a/doc/start/iso.md b/doc/start/iso.md index daccfec..5a0ecf3 100644 --- a/doc/start/iso.md +++ b/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 -``` - - - -[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