Merge #196
196: doc: enact bootstrapping section r=nrdxp a=blaggacao closes: #193 Co-authored-by: David Arnold <dar@xoe.solutions>
This commit is contained in:
commit
f3a0fc9cc0
|
@ -3,6 +3,7 @@
|
||||||
- [Introduction](./README.md)
|
- [Introduction](./README.md)
|
||||||
- [Quick Start](./doc/start/index.md)
|
- [Quick Start](./doc/start/index.md)
|
||||||
- [ISO](./doc/start/iso.md)
|
- [ISO](./doc/start/iso.md)
|
||||||
|
- [Bootstrapping](./doc/start/bootstrapping.md)
|
||||||
- [From NixOS](./doc/start/from-nixos.md)
|
- [From NixOS](./doc/start/from-nixos.md)
|
||||||
- [Layout](./doc/layout.md)
|
- [Layout](./doc/layout.md)
|
||||||
- [Cachix](./cachix/README.md)
|
- [Cachix](./cachix/README.md)
|
||||||
|
|
|
@ -44,6 +44,6 @@ deploy "flk#hostName" --hostname host.example.com
|
||||||
```
|
```
|
||||||
|
|
||||||
> ##### _Note:_
|
> ##### _Note:_
|
||||||
> Your user will need sudo access
|
> Your user will need **passwordless** sudo access
|
||||||
|
|
||||||
[d-rs]: https://github.com/serokell/deploy-rs
|
[d-rs]: https://github.com/serokell/deploy-rs
|
||||||
|
|
99
doc/start/bootstrapping.md
Normal file
99
doc/start/bootstrapping.md
Normal file
|
@ -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
|
|
@ -34,6 +34,7 @@ In addition, the [binary cache](../../cachix) is added for faster deployment.
|
||||||
|
|
||||||
## Next Steps:
|
## Next Steps:
|
||||||
- [Make installable ISO](./iso.md)
|
- [Make installable ISO](./iso.md)
|
||||||
|
- [Bootstrap Host](./bootstrapping.md)
|
||||||
- [Already on NixOS](./from-nixos.md)
|
- [Already on NixOS](./from-nixos.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`.
|
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
|
## ISO image nix store & cache
|
||||||
|
|
||||||
The iso image holds the store to the live environment and _also_ acts as a binay 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
|
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.
|
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
|
|
||||||
|
|
Loading…
Reference in a new issue