Skip to content

First boot

A new box needs a config before it does anything useful, and the person setting it up needs a way in. That is the box's own network: the box may be the first router there, so its WAN address (if it gets one) is of no use for reaching it, and the UI is never offered on the WAN.

strongholdd does this once, on the first start with a config that has no ports. It records it in /var/lib/stronghold/first-boot-done and never does it again; after that, ports are only ever changed by the config.

A config given with the install

If /etc/stronghold/config/ holds a config directory (with its stronghold.yaml), it becomes the box's first config: applied and committed at once ("Initial config from /etc/stronghold/config"), without a confirm window. It can come from:

  • kickstart: a %post that writes the files.
  • bootc image builder: [[customizations.files]] in its config.toml (not tried in the lab yet).
  • cloud-init: write_files (the image has cloud-init; it only delivers files and users, its network config is off). strongholdd starts after cloud-init's network stage, which writes them.
  • a derived image: COPY config/ /etc/stronghold/config/.
# kickstart
%post
mkdir -p /etc/stronghold/config
cat > /etc/stronghold/config/stronghold.yaml <<'EOF'
version: 1
EOF
cat > /etc/stronghold/config/interfaces.yaml <<'EOF'
...
EOF
%end

If it isn't valid, the box sets up a LAN port as below, so it can still be reached, and the log says why.

No config: the first-boot LAN

  1. Every port with a link tries DHCP (NetworkManager's automatic profiles).
  2. A port that gets an address is not a LAN port, whichever port it is. It faces a network that already has a DHCP server: the ISP's, or a data centre's. A port with an address from the install (kickstart's network line) is left alone too.
  3. Of the other ports with a link, the first (by PCI address) becomes the LAN, once it has had its link for 30 seconds without a DHCP answer: an earlier port that may still get one is waited for, so the cable order doesn't matter. A port that comes up later is checked the same way, so the box can be turned on before the laptop is plugged in.

The LAN gets 192.168.73.1/24 (or 10.73.73.1/24, then 172.31.73.1/24, if the box already has an address in it), a DHCP pool (.100–.199) and a DNS resolver. Plug a laptop in and open https://192.168.73.1:9090.

The first config is a normal config, committed as "First boot: lan on enp2s0, wan on enp1s0 (it got an address by DHCP)":

  • lan (zone lan) on the chosen port; it may reach the WAN and the box's DNS, DHCP, NTP, ping, SSH and Cockpit.
  • wan (zone wan, DHCP, outbound NAT) on the first port that got its address by DHCP, if any. Nothing is allowed in from it. IPv6 too, where the ISP has it: an address, and a delegated prefix whose /64 number 1 is the LAN's, next to the site's new ULA prefix (docs/interfaces.md, "IPv6").
  • Other ports aren't in it, and keep what they have until they are added (the UI lists them as not configured).

One port and Wi-Fi: an open setup network

A box with one Ethernet port and a Wi-Fi interface that can be an access point (iw phy lists AP) is set up differently, at once:

  • The Ethernet port is the WAN, whether or not it gets an address (no cable yet, an ISP that needs a static address or PPPoE): the LAN can't be there.
  • The Wi-Fi is an open network, Stronghold- and the last four digits of its MAC (Stronghold-ABCD), with the LAN subnet and DHCP. It is in the zone setup, which reaches only the box's DHCP, DNS, ping and Cockpit: no internet, no SSH.
  • The UI's overview asks for a network name and a password (WPA2, 8 to 63 characters). That is POST /v1/setup/finish (the API): the access point becomes a WPA2 network, its network moves to the zone lan (internet, management), and the setup zone goes. Like any change it rolls back unless kept within 60 seconds, so connect to the secured network and keep it from there; if that fails, the open setup network comes back.
  • Until then strongholdd takes no other change: one that keeps the open network is refused ("finish setup first"). An open network is only allowed as the setup network (security: open needs setup: true).

Anyone in range can join the setup network until it is secured; they reach only Cockpit's login.

Ports without addresses

The number of ports doesn't matter. A box with one port that gets no address sets that port up as the LAN. Only when every port with a link gets an address is there no LAN to set up; the box is then reached only on its console.

Nothing is open on the WAN, before the first config or after it: the image's default firewall zone allows only the DHCPv6 client (answers to the box's own requests), and the first config drops everything from the WAN.

Lab

See docs/lab.md, "First boot".