Files
Homelab-manager/agent/linux/install.sh
T
bobbanandClaude Sonnet 5.5 540ab704b7 Export CSV on every table, edit recurring maintenance, runs-on nothing, and run package checks outside the agent sandbox
- Export CSV for the small tables that had none (reads the table as shown)
- Servers page shows a skeleton while loading instead of "No servers registered yet"
- Recurring maintenance schedules can be edited (PUT /schedules/:id)
- A server can be set to run on nothing (servers.no_parent, migration 0028)
- Linux agent v3: package-manager question runs in ExecStartPre=-+ outside the sandbox,
  with --prepare-updates and --check-updates modes
- Docs: README, DATABASE, AGENT_UPDATE

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

157 lines
6.0 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
# Asking dnf or zypper what is waiting still writes to /var and /run, which the sandbox below makes read-only, so this one step runs
# first and outside it (the + does that; the - lets the report go ahead whatever happens). It only reads what the package manager
# knows and leaves the answer in the unit's private directory, which goes away when the run ends.
ExecStartPre=-+$INSTALL_DIR/homelab-manager-agent.sh --prepare-updates
RuntimeDirectory=homelab-manager-agent
RuntimeDirectoryMode=0700
TimeoutStartSec=420
# 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