Panel & access

The master isn’t reachable at all after flashing (no SSH, no panel)

What it means: If the master is powered on and its own log shows the panel’s service running, but neither SSH nor the browser can reach it, the machine almost certainly has no IPv4 address yet. This isn’t a Buddy problem, it’s the network link. A fe80::… address on the wired interface is only an IPv6 link-local address; it does not mean the machine has connectivity.

Fix: Connect a keyboard and monitor (or a serial cable) to the master and check the wired link directly:

ip -br a                                   # eth0 should show an IPv4, e.g. 192.168.x.y
systemctl is-active systemd-networkd       # must be 'active'

If there’s no IPv4 address listed, bring the link up by hand:

sudo systemctl enable --now systemd-networkd   # persistent + start now
sudo netplan apply
sleep 3 && ip -br a

Then open the panel at the IP address shown: connect by IP, not by hostname; the image has no mDNS, so a name like buddy-master.local won’t resolve.

Images built before the wired-network fix could fail to get a DHCP lease on the very first boot: a plain sudo reboot worked around it on those. Current images bake in a fixed network configuration and a persistent network service, so the wired link comes up on the first boot. Wireless isn’t configured out of the box; use a wired connection, or add your network’s details to the machine’s network configuration file by hand.

If that didn’t work: Confirm the machine is actually plugged into the same network as the computer you’re browsing from, and that the router shows it in its list of connected devices. If it still doesn’t appear, the machine’s own console output during boot is the next thing to read.

The panel won’t open

What it means: The address, port or certificate is wrong, or the panel’s own service isn’t running.

Fix:

1. Confirm you’re using the master’s correct IP address and HTTPS on port 8443: https://<master-ip>:8443/.
2. The certificate is self-signed the first time: your browser will warn about it once; proceed past that warning.
3. Check the panel’s service is up:

   systemctl status buddy-server
   sudo journalctl -u buddy-server -n 50

4. Confirm something is actually listening on the port: sudo ss -ltnp | grep 8443.

If that didn’t work: If the service won’t start, its log is the next thing to read in full — sudo journalctl -u buddy-server -f — for the specific error it’s failing on.

I don’t know the admin password

What it means: The admin password only ever grants first-access enrolment: setting up your authenticator app. It does not sign you in on its own, and once you’ve completed enrolment it stops working entirely. A random password is generated and written to the master’s own log once, on its first start.

Fix: Read it from the log:

sudo journalctl -u buddy-server | grep -i "admin password"

To set your own instead, do it before your first sign-in. An already-enrolled admin’s authenticator app is what signs in from then on, the password can’t be reset from the panel itself:

echo 'BUDDY_ADMIN_PASSWORD=your-strong-password' | sudo tee -a /etc/buddy/server.env
sudo systemctl restart buddy-server

If that didn’t work: If you’ve already completed enrolment and simply can’t remember your authenticator app, that’s a different situation. See “I lost access to my authenticator app” below, not this one.

I lost access to my authenticator app

What it means: Losing the phone or app that generates your 6-digit codes doesn’t lock you out. There’s a recovery path built into the sign-in screen.

Fix: Click “Lost your authenticator?” on the sign-in screen. This doesn’t disable your current authenticator by itself; it mints a single-use recovery code and writes it to the master’s log, reachable the same way as the original setup password:

sudo journalctl -u buddy-server | grep -i "recovery"

Enter that code on the next screen to set up a fresh authenticator: a new QR code and secret, confirmed the same way as your first sign-in.

If that didn’t work: The recovery code is single-use and short-lived; if it expires before you enter it, click “Lost your authenticator?” again to mint a new one. Starting recovery repeatedly is harmless. Only entering a correct code actually replaces your authenticator, so nothing is lost by trying again.

Every login says “Too many incorrect codes”

What it means: Five wrong 6-digit codes in a row lock the account for 5 minutes. This is deliberate: since sign-in relies on the code alone, this lockout is what stands in for a second factor.

Fix: Wait out the countdown shown on the sign-in screen (or in the panel once you’re back in), then try again. If your authenticator’s clock has drifted, most apps re-sync it automatically; correcting the drift usually fixes repeated failures before you hit the lockout again.

If that didn’t work: If codes keep failing even right after the lockout clears and your authenticator’s clock looks correct, use “Lost your authenticator?” to set up a fresh one rather than continuing to guess.