Files
Homelab-manager/agent/linux/install.sh
T
bobbanandClaude Sonnet 5.5 5dc6cea69c Host health from the Linux agent, agent self-update, and disk forecast in /metrics
- Linux agent v4: failed systemd services, SMART disk health, ZFS pool state, pacman updates;
  SMART/ZFS and self-update run in the ExecStartPre=-+ step outside the sandbox
- Server: hosts' health stored (servers.host_health, migration 0029), alerts under a new
  "Failing services" kind plus disk/ZFS alerts, Host health card, Prometheus series
- Agent self-update (Linux v4, Windows v3): admin switch on the Servers page, checksum-verified
  download, atomic replace; GET /api/agent/report/update
- homelab_server_disk_days_to_full in /metrics
- Tests (server, real PowerShell against a fake server) and docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-18 00:54:24 +02:00

159 lines
6.3 KiB
Bash

#!/usr/bin/env bash
# Installs the Homelab Manager task-reporting agent as a systemd timer.
#
# Usage (must run as root — if not already root, put sudo right after the
# pipe so it applies to bash, not to curl):
# curl -fsSL https://homelab.example.lan/agent/linux/install.sh | \
# sudo API_URL=https://homelab.example.lan API_TOKEN=hlm_xxx bash
#
# If Homelab Manager is served with a self-signed certificate, also pass
# API_INSECURE=true (skips TLS verification for every request this agent
# makes — only do this on a trusted LAN) AND add -k to the outer curl
# above, since that first fetch of this very script also hits the
# self-signed endpoint before any of this script's logic can run:
# curl -fsSL -k https://homelab.example.lan/agent/linux/install.sh | \
# sudo API_URL=https://homelab.example.lan API_TOKEN=hlm_xxx API_INSECURE=true bash
#
set -euo pipefail
: "${API_URL:?Set API_URL to your Homelab Manager URL, e.g. https://homelab.example.lan}"
: "${API_TOKEN:?Set API_TOKEN to the per-server token generated on the Servers & Tasks page}"
API_INSECURE="${API_INSECURE:-false}"
INSTALL_DIR="/usr/local/bin"
CONFIG_DIR="/etc"
SYSTEMD_DIR="/etc/systemd/system"
INTERVAL_MINUTES="${INTERVAL_MINUTES:-15}"
CURL_INSECURE_FLAG=()
case "${API_INSECURE,,}" in
1|true|yes) CURL_INSECURE_FLAG=(-k) ;;
esac
if [[ "$EUID" -ne 0 ]]; then
echo "This installer must be run as root (it installs a systemd timer)." >&2
echo "If you're piping from curl, put sudo right after the pipe so it elevates bash, not curl:" >&2
echo " curl -fsSL ... | sudo API_URL=... API_TOKEN=... bash" >&2
exit 1
fi
suggest_package_install() {
local pkg="$1"
if command -v apt-get >/dev/null 2>&1; then
echo " sudo apt-get update && sudo apt-get install -y $pkg"
elif command -v dnf >/dev/null 2>&1; then
echo " sudo dnf install -y $pkg"
elif command -v yum >/dev/null 2>&1; then
echo " sudo yum install -y $pkg"
elif command -v apk >/dev/null 2>&1; then
echo " sudo apk add $pkg"
elif command -v pacman >/dev/null 2>&1; then
echo " sudo pacman -S $pkg"
elif command -v zypper >/dev/null 2>&1; then
echo " sudo zypper install -y $pkg"
fi
}
for bin in curl jq; do
if ! command -v "$bin" >/dev/null 2>&1; then
echo "Required dependency '$bin' is not installed. Try:" >&2
suggest_package_install "$bin" >&2
exit 1
fi
done
if ! command -v systemctl >/dev/null 2>&1; then
echo "systemctl was not found — this installer requires a systemd-based Linux distribution." >&2
exit 1
fi
echo "Installing Homelab Manager agent from $API_URL ..."
curl -fsSL "${CURL_INSECURE_FLAG[@]}" "$API_URL/agent/linux/report-tasks.sh" -o "$INSTALL_DIR/homelab-manager-agent.sh"
chmod 755 "$INSTALL_DIR/homelab-manager-agent.sh"
umask 077
cat > "$CONFIG_DIR/homelab-manager-agent.env" <<EOF
API_URL=$API_URL
API_TOKEN=$API_TOKEN
API_INSECURE=$API_INSECURE
EOF
chmod 600 "$CONFIG_DIR/homelab-manager-agent.env"
cat > "$SYSTEMD_DIR/homelab-manager-agent.service" <<EOF
[Unit]
Description=Report scheduled tasks to Homelab Manager
[Service]
Type=oneshot
EnvironmentFile=$CONFIG_DIR/homelab-manager-agent.env
ExecStart=$INSTALL_DIR/homelab-manager-agent.sh
# A few things can't be done inside the sandbox below, so one step runs first and outside it (the + does that; the - lets the report go
# ahead whatever happens): asking dnf or zypper what is waiting (they write to /var and /run even when only asked), reading disk health and
# ZFS pool state (the sandbox closes the devices), and, only if an administrator has switched it on in Homelab Manager, replacing the agent
# script with a newer one (the sandbox keeps /usr read-only). It leaves its answers in the unit's private directory, which goes away when
# the run ends; the one thing kept between runs is the last SMART reading, in /var/lib/homelab-manager-agent.
ExecStartPre=-+$INSTALL_DIR/homelab-manager-agent.sh --prepare
RuntimeDirectory=homelab-manager-agent
RuntimeDirectoryMode=0700
TimeoutStartSec=600
# The agent only reads (crontabs, timers, /proc, listening sockets) and makes one HTTPS request, but it runs as root. These
# keep a bug in it, or in anything it parses, from being able to change the system. It still sees every process, which is
# how it names the program behind each listening port. Directives an older systemd doesn't know are ignored.
#
# Of root's powers it keeps only what it uses: to read every user's crontab (DAC_OVERRIDE, DAC_READ_SEARCH), to run
# the command that lists one user's crontab, which switches user and group (SETUID, SETGID), and to see which program owns each socket (SYS_PTRACE).
# If a change here ever makes a report lose tasks, this line is the first thing to look at.
CapabilityBoundingSet=CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_SYS_PTRACE CAP_SETUID CAP_SETGID
# Not PrivateDevices=: that would also hide /dev/log, which crontab writes to each time the agent reads a crontab. This stops it
# opening hardware devices all the same.
DevicePolicy=closed
UMask=0077
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=read-only
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
MemoryDenyWriteExecute=yes
RestrictSUIDSGID=yes
RestrictRealtime=yes
RestrictNamespaces=yes
LockPersonality=yes
SystemCallArchitectures=native
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
EOF
cat > "$SYSTEMD_DIR/homelab-manager-agent.timer" <<EOF
[Unit]
Description=Periodically report scheduled tasks to Homelab Manager
[Timer]
OnBootSec=2min
OnUnitActiveSec=${INTERVAL_MINUTES}min
Persistent=true
[Install]
WantedBy=timers.target
EOF
# The umask above is for the token file. Unit files hold nothing secret and are meant to be readable (systemctl cat, as any user).
chmod 644 "$SYSTEMD_DIR/homelab-manager-agent.service" "$SYSTEMD_DIR/homelab-manager-agent.timer"
systemctl daemon-reload
systemctl enable --now homelab-manager-agent.timer
echo "Installed. Running an initial report now..."
"$INSTALL_DIR/homelab-manager-agent.sh"
echo "Done. The agent reports every ${INTERVAL_MINUTES} minute(s) via the 'homelab-manager-agent.timer' systemd timer."
if [[ ${#CURL_INSECURE_FLAG[@]} -gt 0 ]]; then
echo "To remove it later: curl -fsSL -k $API_URL/agent/linux/uninstall.sh | sudo bash"
else
echo "To remove it later: curl -fsSL $API_URL/agent/linux/uninstall.sh | sudo bash"
fi