====== New Machine Setup Playbook ======

Generalized provisioning for a homelab machine. Not every machine needs every section: pick by role.

===== 1. SSH Access (every machine) =====

  * Install ''openssh-server''. On Ubuntu 24.04 it listens via ''ssh.socket''; ''ssh.service'' spawns on demand.
  * Key-only auth, drop-in ''/etc/ssh/sshd_config.d/60-key-only.conf'': ''PasswordAuthentication no'', ''PermitRootLogin no''
  * Keep ''authorized_keys'' curated: record which key belongs to which machine and remove dead keys.
  * Firewall: ''ufw deny incoming'' + ''ufw allow 22/tcp''.

===== 2. Off-LAN Reachability =====

For machines that should be reachable outside the LAN without port forwarding (and immune to routers without hairpin NAT), a Cloudflare tunnel:

<code bash>
curl -L -o ~/.local/bin/cloudflared \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
cloudflared tunnel login                        # browser auth, picks the zone
cloudflared tunnel create <name>                # writes ~/.cloudflared/<id>.json (secret)
cloudflared tunnel route dns <name> <host>      # one route per hostname
</code>

  * Ingress config: ''service: http://127.0.0.1:PORT'' for web, ''service: ssh://localhost:22'' for SSH, always ending with a ''http_status:404'' catch-all.
  * SSH client side: ''ProxyCommand cloudflared access ssh --hostname %h'' under a ''Host'' alias in ''~/.ssh/config''.
  * Cost: ~20-40 MB RAM. ''python3 -m http.server'' is a fine origin for a static ''~/public''.

===== 3. Always-On Duty =====

For a laptop acting as a server:

  * Mask ''sleep/suspend/hibernate/hybrid-sleep'' targets: immediate and needs no logind restart.
  * logind drop-in ''/etc/systemd/logind.conf.d/'': ''HandleLidSwitch=ignore'' for lids (takes effect next boot).
  * UPower: ''IgnoreLid=true''; consider ''CriticalPowerAction=PowerOff'' so a dying battery cleanly shuts down instead of failing a hybrid-sleep.
  * Wi-Fi powersave off for server duty: ''nmcli con mod <ssid> 802-11-wireless.powersave 2'' plus a NetworkManager ''conf.d'' default.
  * Screen blanking is fine to keep: it does not suspend anything.

===== 4. Battery Longevity =====

For laptops on permanent AC: where firmware exposes ''/sys/class/power_supply/BAT*/charge_control_end_threshold'' (recent ThinkPads and many ASUS do), write 75-80 and persist it with a oneshot systemd unit. Undo by setting 100 and disabling the unit.

===== 5. Unattended Credentials =====

Unattended jobs need non-interactive credentials. Never store passphrases in files.

  * Preferred: ''keychain''. Passphrase typed once per boot at an interactive login; cron jobs source ''~/.keychain/<host>-sh'' for ''SSH_AUTH_SOCK''. If the agent is empty after a fresh boot, jobs fail gracefully.
  * Alternative: per-repo deploy keys (read-only, scoped). More secure than an account-wide passphrase-less key; never reuse one across repos.
  * Anti-pattern: a passphrase-less personal key on the account. Do not.

===== 6. Health Checks and Alerts =====

A daily cron script with functional probes, not just ''is-active'': actually ''curl'' the service's own URL to catch running but unresponsive processes.

  * Check connectivity first: do not churn restarts on a dead network.
  * Retries: 2 attempts, 10 seconds apart, all logged. Self-trim the log.
  * Alerts via ''curl -d msg https://ntfy.sh/<topic>'': free, no account. Pick an obscure topic name per machine.
  * Daily git pulls run as the owning user (''runuser -u''), ''--ff-only'', failing gracefully on dirty trees.

===== 7. Lightweight Strip-Down =====

For low-spec or focused machines:

  * Mask unused services: bluetooth, cups, avahi, ModemManager.
  * Hide login autostart entries.
  * ''zram-config'' plus ''vm.swappiness=100'' for small RAM. See [[hosting:hardware:low_memory|Running Linux on Low RAM]].
  * ''snap set system refresh.retain=2'' and drop disabled snap revisions.

===== 8. Git Conventions =====

  * One-line conventional commits: ''type(scope): description''.
  * Automation runs ''git -c commit.gpgsign=false'' so a signing-key passphrase prompt cannot block a cron commit.

===== Checklist =====

<code>
[ ] sshd + key-only auth + authorized_keys
[ ] ufw allows 22
[ ] machine recorded in inventory docs
[ ] (optional) cloudflared tunnel + systemd service
[ ] (optional, laptop) battery threshold + always-on
[ ] keychain wired in ~/.profile
[ ] health-check cron job installed
[ ] ntfy topic chosen + subscribed
</code>

===== See Also =====

  * [[guides:start|Guides Index]]
  * [[guides:add_new_service|Adding a New Service]]
  * [[hosting:networking:security|Security Considerations]]
  * [[terminal:tools:ssh_homelab|SSH: Remote Server]]
  * [[start|Return to wiki home]]