| 1 |
# 3. Installing |
| 2 |
|
| 3 |
Boot the USB stick you wrote in chapter 2. The live system starts the Alloy |
| 4 |
installer by itself; there is nothing to type at a prompt and no desktop to |
| 5 |
find it in. On an already-installed machine the same unit is inert, so the |
| 6 |
installer cannot fire by accident. |
| 7 |
|
| 8 |
The installer is `alloy install`, a wizard over `bootc install to-disk`. bootc |
| 9 |
does the real work: partitioning, the ostree deploy, and the bootloader. The |
| 10 |
wizard asks four questions, shows you what it is about to run, and runs it. |
| 11 |
|
| 12 |
## The six screens |
| 13 |
|
| 14 |
**1. Disk.** Every disk the machine can see, with its size and model. This is |
| 15 |
the one answer nothing later recovers from, so it comes first: if the disk you |
| 16 |
expect is not listed, stop here rather than after typing a password. |
| 17 |
|
| 18 |
**2. Hostname.** What the machine is called on your network and in your |
| 19 |
prompt. |
| 20 |
|
| 21 |
**3. Account.** Your username, your password, and an SSH public key. Alloy |
| 22 |
creates one account and does not enable a root login. The key is optional at |
| 23 |
this screen and it is not optional if you ever want to reach this machine over |
| 24 |
the network; see "Signing in over SSH" below. On a medium you minted with a key |
| 25 |
baked in, this field arrives already filled with that key. |
| 26 |
|
| 27 |
**4. Encryption.** Optional, and if you say yes you type a passphrase and then |
| 28 |
see a recovery phrase. Read the next section before deciding. |
| 29 |
|
| 30 |
**5. Summary.** Every command the installer is about to run, in order, before |
| 31 |
any of them runs. Nothing is hidden behind a progress bar. |
| 32 |
|
| 33 |
**6. Credits.** What Alloy ships, each project's license, and its URL. It is |
| 34 |
the only screen that asks nothing, and the install starts from here rather than |
| 35 |
from the summary: the last screen before a disk is erased should be the one |
| 36 |
naming whose work is about to be written to it. |
| 37 |
|
| 38 |
Then the install runs, streaming its output, for the several minutes bootc |
| 39 |
takes. |
| 40 |
|
| 41 |
## Encryption and the recovery phrase |
| 42 |
|
| 43 |
Choosing encryption sets up LUKS on the root filesystem and binds it to the |
| 44 |
machine's TPM, so the disk unlocks at boot without a password prompt. |
| 45 |
|
| 46 |
That binding has one failure mode that ends in permanent data loss: the TPM |
| 47 |
stops answering. Clearing it, replacing the board, or moving the disk to |
| 48 |
another machine all do that. So Alloy enrolls two ways in rather than one: |
| 49 |
|
| 50 |
- **Your passphrase**, the one you typed. |
| 51 |
- **A recovery phrase**, eight words the installer generates and shows you |
| 52 |
once. |
| 53 |
|
| 54 |
Write the recovery phrase down on paper. It is not stored anywhere you can read |
| 55 |
it back from later, it is never rotated, and it is what stands between a dead |
| 56 |
TPM and a lost disk. Words rather than a random key string because this is a |
| 57 |
phrase a person reads off one screen and types into another, months later. |
| 58 |
|
| 59 |
If you skip encryption, none of this applies and the disk is readable by anyone |
| 60 |
holding it. |
| 61 |
|
| 62 |
## After the install |
| 63 |
|
| 64 |
Reboot and remove the medium. You land on the greeter (tuigreet on VT1), sign |
| 65 |
in with the account you made, and sway starts. |
| 66 |
|
| 67 |
A machine installed from a locally built medium has its update timer disabled. |
| 68 |
It will never poll anything. Chapter 8 covers what updating means instead. |
| 69 |
|
| 70 |
## Signing in over SSH |
| 71 |
|
| 72 |
Alloy accepts a key and nothing else. `PasswordAuthentication` is off, the |
| 73 |
keyboard-interactive path that can authenticate a password behind it is off, |
| 74 |
and root is key-only. That is the policy for every install, both profiles, and |
| 75 |
it is set in `/etc/ssh/sshd_config.d/10-alloy.conf` rather than left to |
| 76 |
whatever the Fedora base happens to default to. |
| 77 |
|
| 78 |
The account screen is where a key gets onto the machine. Paste the public half |
| 79 |
of a keypair you already hold, usually the contents of `~/.ssh/id_ed25519.pub` |
| 80 |
on the machine you will connect from. The installer checks it is a public key |
| 81 |
sshd will actually read, writes it to the new account's |
| 82 |
`~/.ssh/authorized_keys`, and sets the modes sshd insists on. |
| 83 |
|
| 84 |
You may finish an install without a key, and for a desktop that is a reasonable |
| 85 |
answer: you are sitting at the greeter, so you log in on the console and add a |
| 86 |
key afterwards. The installer says so on the summary and again on the gate |
| 87 |
before it writes the disk, because from the far side of a reboot there is no |
| 88 |
way to tell a machine you did that to from a broken one. |
| 89 |
|
| 90 |
On a machine with no screen it is not a reasonable answer, and there is nothing |
| 91 |
to recover with. Put a key on the account screen. |
| 92 |
|
| 93 |
### Adding a key after the fact |
| 94 |
|
| 95 |
From a console session on the machine: |
| 96 |
|
| 97 |
``` |
| 98 |
mkdir -p ~/.ssh |
| 99 |
chmod 700 ~/.ssh |
| 100 |
cat >> ~/.ssh/authorized_keys # paste the key, then Ctrl+D |
| 101 |
chmod 600 ~/.ssh/authorized_keys |
| 102 |
``` |
| 103 |
|
| 104 |
The modes are not decoration. sshd refuses to read an `authorized_keys` that |
| 105 |
anyone but its owner can write, and it refuses silently as far as the client is |
| 106 |
concerned: you get "permission denied" and the reason goes only to the server's |
| 107 |
journal. |
| 108 |
|
| 109 |
## Installing without a screen |
| 110 |
|
| 111 |
`alloy install` needs a terminal, and on a machine with no display that |
| 112 |
terminal comes over the network. Mint the medium with a key and a hostname |
| 113 |
baked in, boot it, and continue from another machine: |
| 114 |
|
| 115 |
``` |
| 116 |
ssh installer@<hostname>.local |
| 117 |
``` |
| 118 |
|
| 119 |
The connection lands in the installer itself rather than in a shell, so there |
| 120 |
is no command to get wrong. The key you connect with is also what the account |
| 121 |
screen offers you for the machine being installed, so you are not pasting back |
| 122 |
the credential you are already holding. |
| 123 |
|
| 124 |
Two things make that flow work and both are worth knowing. The `installer` |
| 125 |
account exists only on the live medium, so an installed machine has no such |
| 126 |
user and no way to reach `alloy install` over SSH. And the machine is found by |
| 127 |
mDNS, which means the LAN it is on and not Tailscale; a freshly booted medium |
| 128 |
has joined no mesh. |
| 129 |
|
| 130 |
Chapter 2, "Baking in a key and a hostname", covers minting such a medium. |
| 131 |
|