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>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-17 22:25:18 +02:00
1 parent c17e9aa140
commit 540ab704b7
32 files changed
+3003 -66

No files matched your search

+1
View File
@@ -0,0 +1 @@
ALTER TABLE `servers` ADD `no_parent` integer DEFAULT false NOT NULL;
File diff suppressed because it is too large. Load diff
+7
View File
@@ -197,6 +197,13 @@
"when": 1792260718106,
"tag": "0027_bizarre_magus",
"breakpoints": true
},
{
"idx": 28,
"version": "6",
"when": 1792267930026,
"tag": "0028_thankful_ultron",
"breakpoints": true
}
]
}
+2
View File
@@ -289,6 +289,8 @@ export const servers = sqliteTable("servers", {
// The server this one runs on (a VM on its host), set by an admin. Null means "work it out": a guest linked to a Proxmox node runs on
// the server named after that node. When the parent stops reporting, this server's own offline alert is folded under the parent's.
parentServerId: integer("parent_server_id"),
// An admin said this server runs on nothing, so the automatic guess from its Proxmox node is not used for it.
noParent: integer("no_parent", { mode: "boolean" }).notNull().default(false),
// What the agent says is waiting to be installed, as JSON: {manager, count, security, rebootRequired, reportedAt}. Null until it reports.
pendingUpdates: text("pending_updates"),
+46 -7
View File
@@ -309,23 +309,32 @@ maintenanceRouter.get("/schedules", asyncHandler(async (_req, res) => {
res.json({ schedules: out });
}));
maintenanceRouter.post("/schedules", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = scheduleSchema.safeParse(req.body);
type ScheduleBody = z.infer<typeof scheduleSchema>;
/** Checks a schedule's fields the same way for making one and for changing one: the shape, the time zone, and that what it covers exists (once each). */
async function checkScheduleBody(body: unknown): Promise<{ data: ScheduleBody; targets: ScheduleBody["targets"] } | { status: number; json: object }> {
const parsed = scheduleSchema.safeParse(body);
if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", message: "Name it, choose what it covers, the days, a start time and how long.", details: parsed.error.flatten() });
return { status: 400, json: { error: "invalid_body", message: "Name it, choose what it covers, the days, a start time and how long.", details: parsed.error.flatten() } };
}
const data = parsed.data;
if (!isValidTimeZone(data.timezone)) return res.status(400).json({ error: "invalid_timezone", message: "That isn't a time zone this server knows." });
// Only things that exist, once each.
if (!isValidTimeZone(data.timezone)) return { status: 400, json: { error: "invalid_timezone", message: "That isn't a time zone this server knows." } };
const seen = new Set<string>();
const targets = [];
const targets: ScheduleBody["targets"] = [];
for (const t of data.targets) {
const key = `${t.type}:${t.id}`;
if (seen.has(key)) continue;
seen.add(key);
if (!(await describeTarget(t.type, t.id))) return res.status(400).json({ error: "unknown_target", message: "One of the things chosen doesn't exist any more." });
if (!(await describeTarget(t.type, t.id))) return { status: 400, json: { error: "unknown_target", message: "One of the things chosen doesn't exist any more." } };
targets.push(t);
}
return { data, targets };
}
maintenanceRouter.post("/schedules", requireRole("operator"), asyncHandler(async (req, res) => {
const checked = await checkScheduleBody(req.body);
if ("status" in checked) return res.status(checked.status).json(checked.json);
const { data, targets } = checked;
const actor = req.currentUser!;
const [created] = await db
.insert(maintenanceSchedules)
@@ -345,6 +354,36 @@ maintenanceRouter.post("/schedules", requireRole("operator"), asyncHandler(async
res.status(201).json({ id: created.id, windowsMade: made });
}));
/**
* Changes a schedule's name, days, time, length or what it covers. Windows it made that haven't begun are taken back and made again from the
* new settings; one already under way keeps the times it started with, and ends on its own.
*/
maintenanceRouter.put("/schedules/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = Number(req.params.id);
if (!Number.isInteger(id)) return res.status(400).json({ error: "invalid_id" });
const [row] = await db.select().from(maintenanceSchedules).where(eq(maintenanceSchedules.id, id)).limit(1);
if (!row) return res.status(404).json({ error: "not_found" });
const checked = await checkScheduleBody(req.body);
if ("status" in checked) return res.status(checked.status).json(checked.json);
const { data, targets } = checked;
await db
.update(maintenanceSchedules)
.set({
name: data.name,
reason: data.reason || null,
targets: JSON.stringify(targets),
days: JSON.stringify([...new Set(data.days)].sort()),
startTime: data.startTime,
durationMinutes: data.durationMinutes,
timezone: data.timezone,
})
.where(eq(maintenanceSchedules.id, id));
await removeFutureWindows(id);
const made = row.enabled ? await materializeSchedules(new Date(), undefined, id) : 0;
await recordAudit({ actor: req.currentUser!, category: "maintenance", action: "update_schedule", targetType: "maintenance_schedule", targetId: id, detail: { name: data.name, targets: targets.length, days: data.days, startTime: data.startTime, durationMinutes: data.durationMinutes } });
res.json({ windowsMade: made });
}));
maintenanceRouter.patch("/schedules/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = Number(req.params.id);
const parsed = z.object({ enabled: z.boolean() }).safeParse(req.body);
+7 -2
View File
@@ -120,6 +120,8 @@ const updateServerSchema = z
hideProxmoxLink: z.boolean().optional(),
// The server this one runs on. Null goes back to working it out from the Proxmox node.
parentServerId: z.number().int().nullable().optional(),
// True says it runs on nothing, which also stops the Proxmox-node guess. Choosing a server, or null, turns it off again.
noParent: z.boolean().optional(),
})
.refine(
(data) => {
@@ -166,7 +168,10 @@ serversRouter.patch("/:id", requireRole("admin"), asyncHandler(async (req, res)
}
}
const [updated] = await db.update(servers).set(parsed.data).where(eq(servers.id, id)).returning();
const changes: typeof parsed.data = { ...parsed.data };
if (changes.noParent === true) changes.parentServerId = null;
else if (changes.parentServerId !== undefined) changes.noParent = false;
const [updated] = await db.update(servers).set(changes).where(eq(servers.id, id)).returning();
await recordAudit({
actor: req.currentUser!,
@@ -174,7 +179,7 @@ serversRouter.patch("/:id", requireRole("admin"), asyncHandler(async (req, res)
action: "update",
targetType: "server",
targetId: id,
detail: { name: updated.name, ...(parsed.data.parentServerId !== undefined ? { parentServerId: parsed.data.parentServerId } : {}) },
detail: { name: updated.name, ...(parsed.data.parentServerId !== undefined ? { parentServerId: parsed.data.parentServerId } : {}), ...(parsed.data.noParent !== undefined ? { noParent: parsed.data.noParent } : {}) },
});
const serverOut = publicServer(updated);
+1
View File
@@ -6,6 +6,7 @@
*
* 1 — before the number was reported (so an agent that says nothing is version 1)
* 2 — reports pending updates, and its own version
* 3 — Linux: the package manager is asked outside the systemd sandbox, so dnf and zypper can answer too (Windows stays at 2)
*/
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
+5 -2
View File
@@ -2,7 +2,7 @@
* Which server runs on which: a virtual machine on its Proxmox host, a container on a Docker box. When the host stops reporting, the
* things on it stop too, and seven alerts about seven guests only hide the one that matters — so those alerts are folded under the
* host's. The link is either set by hand ("runs on") or worked out: a server linked to a Proxmox guest runs on the server named after
* that guest's Proxmox node, when there is exactly one such server.
* that guest's Proxmox node, when there is exactly one such server. An admin can also say a server runs on nothing, which stops the guess.
*/
import { db } from "../db/client.js";
import { servers } from "../db/schema.js";
@@ -13,6 +13,8 @@ export interface ParentRow {
hostname: string | null;
parentServerId: number | null;
proxmoxNode: string | null;
/** Said by hand to run on nothing: no link, and no guessing from the Proxmox node. */
noParent?: boolean;
}
export interface ParentLink {
@@ -36,6 +38,7 @@ export function resolveParents(rows: ParentRow[]): Map<number, ParentLink> {
const byId = new Map(rows.map((r) => [r.id, r]));
const out = new Map<number, ParentLink>();
for (const row of rows) {
if (row.noParent) continue;
if (row.parentServerId !== null && row.parentServerId !== row.id && byId.has(row.parentServerId)) {
out.set(row.id, { parentId: row.parentServerId, auto: false });
continue;
@@ -86,6 +89,6 @@ export function wouldLoop(rows: ParentRow[], id: number, parentId: number): bool
export async function loadParentRows(): Promise<ParentRow[]> {
return db
.select({ id: servers.id, name: servers.name, hostname: servers.hostname, parentServerId: servers.parentServerId, proxmoxNode: servers.proxmoxNode })
.select({ id: servers.id, name: servers.name, hostname: servers.hostname, parentServerId: servers.parentServerId, proxmoxNode: servers.proxmoxNode, noParent: servers.noParent })
.from(servers);
}
+20
View File
@@ -358,6 +358,14 @@ describe("Linux agent", () => {
// The two intended expansions, and nothing else turned into something unexpected.
assert.equal(settings.get("EnvironmentFile"), "/etc/homelab-manager-agent.env");
assert.equal(settings.get("ExecStart"), "/usr/local/bin/homelab-manager-agent.sh");
// The one step that runs outside the sandbox (+) is the package-manager question, which may fail without stopping the report (-),
// and it hands its answer over through the unit's own private directory, which is where the script looks for it.
assert.equal(settings.get("ExecStartPre"), "-+/usr/local/bin/homelab-manager-agent.sh --prepare-updates");
assert.equal(rendered.split("\n").filter((l) => /^ExecStartPre=/.test(l.trim())).length, 1, "only that one step is outside the sandbox");
assert.equal(settings.get("RuntimeDirectory"), "homelab-manager-agent");
assert.equal(settings.get("RuntimeDirectoryMode"), "0700");
assert.ok(readFileSync(agentScript, "utf8").includes("/run/homelab-manager-agent/updates.json"), "the script looks where the unit leaves it");
assert.doesNotMatch(rendered, /[`\\]/);
for (const [key, value] of Object.entries({
@@ -389,6 +397,18 @@ describe("Linux agent", () => {
}
});
test("the update check can be run on its own, and what it leaves behind is read back through jq, not trusted", () => {
const text = readFileSync(agentScript, "utf8");
assert.ok(text.includes("--prepare-updates) MODE=prepare"));
assert.ok(text.includes("--check-updates) MODE=check"));
assert.ok(text.includes("use_prepared_updates || collect_updates"), "the report uses the prepared answer first and asks itself otherwise");
assert.ok(text.includes('find "$UPDATES_FILE" -mmin -10'), "an old answer isn't used");
assert.ok(text.includes("jq -ce 'select(type == \"object\""), "the file is re-shaped by jq, so the report only carries the four known fields");
assert.ok(text.includes('mv -f "$UPDATES_FILE.tmp" "$UPDATES_FILE"'), "written whole, then moved into place");
// the two modes must not need a server address or a token
assert.ok(text.includes('[[ "$MODE" == "report" && ( -z "$API_URL" || -z "$API_TOKEN" ) ]]'));
});
test("unit files are made readable by everyone (the umask above them is for the token file)", () => {
const text = readFileSync(installScript, "utf8").replace(/\r\n/g, "\n");
assert.match(text, /chmod 644 "\$SYSTEMD_DIR\/homelab-manager-agent\.service" "\$SYSTEMD_DIR\/homelab-manager-agent\.timer"/);
+33 -1
View File
@@ -168,10 +168,42 @@ describe("the schedules and their windows", () => {
assert.ok((await windowsOf(scheduleId)).length >= 12);
});
test("editing a schedule remakes the windows that haven't begun from the new settings, and keeps what is under way", async () => {
const now = Date.now();
await db.insert(maintenanceWindows).values({ targetType: "server", targetId: a, reason: "x", startedAt: new Date(now - 60_000).toISOString(), endsAt: new Date(now + 600_000).toISOString(), source: `schedule:${scheduleId}:2000-01-02` });
const edited = { ...good, name: "Patch weekend", reason: "", targets: [{ type: "server", id: a }], days: [6], startTime: "01:30", durationMinutes: 90 };
const res = await call("PUT", `/schedules/${scheduleId}`, edited);
assert.equal(res.status, 200);
const future = (await windowsOf(scheduleId)).filter((w) => w.startedAt > new Date().toISOString());
assert.ok(future.length >= 1 && future.length <= 2, `${future.length} Saturdays in the coming week`);
assert.ok(future.every((w) => w.targetId === a && w.reason === "Patch weekend" && new Date(w.startedAt).getUTCDay() === 6 && w.startedAt.includes("T01:30") && Date.parse(w.endsAt) - Date.parse(w.startedAt) === 90 * 60_000));
assert.ok((await windowsOf(scheduleId)).some((w) => w.source.endsWith("2000-01-02")), "the one under way is left alone");
await db.delete(maintenanceWindows).where(eq(maintenanceWindows.source, `schedule:${scheduleId}:2000-01-02`));
const list = await (await call("GET", "/schedules")).json();
assert.equal(list.schedules[0].name, "Patch weekend");
assert.deepEqual(list.schedules[0].days, [6]);
assert.equal(list.schedules[0].reason, null);
assert.equal(list.schedules[0].targets.length, 1);
assert.equal(list.schedules[0].enabled, true);
// a bad edit changes nothing; a schedule that is off stays off and makes nothing
assert.equal((await call("PUT", `/schedules/${scheduleId}`, { ...edited, timezone: "Mars/Olympus" })).status, 400);
assert.equal((await call("PUT", `/schedules/${scheduleId}`, { ...edited, targets: [{ type: "server", id: 99999 }] })).status, 400);
assert.equal((await call("PUT", "/schedules/99999", edited)).status, 404);
assert.equal((await (await call("GET", "/schedules")).json()).schedules[0].name, "Patch weekend");
await call("PATCH", `/schedules/${scheduleId}`, { enabled: false });
assert.equal((await (await call("PUT", `/schedules/${scheduleId}`, { ...edited, days: [0, 1] })).json()).windowsMade, 0);
assert.equal((await windowsOf(scheduleId)).filter((w) => w.startedAt > new Date().toISOString()).length, 0);
assert.equal((await (await call("GET", "/schedules")).json()).schedules[0].enabled, false);
await call("PUT", `/schedules/${scheduleId}`, { ...good, targets: [{ type: "server", id: a }, { type: "server", id: b }] });
await call("PATCH", `/schedules/${scheduleId}`, { enabled: true });
});
test("only operators change schedules; a bad one is refused", async () => {
who = "viewer";
assert.equal((await call("POST", "/schedules", { ...good, targets: [{ type: "server", id: a }] })).status, 403);
assert.equal((await call("PATCH", `/schedules/${scheduleId}`, { enabled: false })).status, 403);
assert.equal((await call("PUT", `/schedules/${scheduleId}`, { ...good, targets: [{ type: "server", id: a }] })).status, 403);
assert.equal((await call("DELETE", `/schedules/${scheduleId}`)).status, 403);
assert.equal((await call("GET", "/schedules")).status, 200, "anyone signed in can see them");
who = "operator";
@@ -197,6 +229,6 @@ describe("the schedules and their windows", () => {
assert.equal((await windowsOf(scheduleId)).filter((w) => w.startedAt > new Date().toISOString()).length, 0);
assert.equal((await call("DELETE", `/schedules/${scheduleId}`)).status, 404);
const actions = (await db.select().from(auditLog)).filter((e) => e.category === "maintenance").map((e) => e.action);
for (const wanted of ["create_schedule", "disable_schedule", "enable_schedule", "delete_schedule"]) assert.ok(actions.includes(wanted), wanted);
for (const wanted of ["create_schedule", "update_schedule", "disable_schedule", "enable_schedule", "delete_schedule"]) assert.ok(actions.includes(wanted), wanted);
});
});
+36
View File
@@ -61,6 +61,14 @@ describe("resolveParents", () => {
assert.equal(parents.get(6), undefined, "not its own parent");
});
test("one said to run on nothing is not guessed at, and a link set by hand clears that", () => {
const rows = [row(1, "pve1"), { ...row(2, "web", { proxmoxNode: "pve1" }), noParent: true }, { ...row(3, "db", { proxmoxNode: "pve1", parentServerId: 1 }), noParent: true }];
const parents = resolveParents(rows);
assert.equal(parents.get(2), undefined, "no guess");
assert.equal(parents.get(3), undefined, "no link either while it is set");
assert.deepEqual(resolveParents([row(1, "pve1"), row(2, "web", { proxmoxNode: "pve1" })]).get(2), { parentId: 1, auto: true }, "unset, it is found again");
});
test("a server is not its own node", () => {
assert.equal(resolveParents([row(1, "pve1", { proxmoxNode: "pve1" })]).size, 0);
});
@@ -297,6 +305,34 @@ describe("the routes", () => {
assert.equal((await (await call("GET", `/servers/${guestId}/detail`)).json()).relations.parent, null, "back to working it out");
});
test("an admin can say a server runs on nothing, even when its Proxmox node would be found, and take that back", async () => {
const detailOf = async () => (await call("GET", `/servers/${guestId}/detail`)).json();
await db.update(servers).set({ proxmoxNode: "rack" }).where(eq(servers.id, guestId));
assert.deepEqual((await detailOf()).relations.parent, { id: hostId, name: "rack", auto: true }, "found from the node");
assert.equal((await call("PATCH", `/servers/${guestId}`, { noParent: true })).status, 200);
let d = await detailOf();
assert.equal(d.relations.parent, null);
assert.equal(d.server.noParent, true);
assert.deepEqual((await (await call("GET", `/servers/${hostId}/detail`)).json()).relations.children, [], "and the host no longer lists it");
// choosing a server by hand ends it; so does going back to automatic
assert.equal((await call("PATCH", `/servers/${guestId}`, { parentServerId: hostId })).status, 200);
d = await detailOf();
assert.equal(d.server.noParent, false);
assert.deepEqual(d.relations.parent, { id: hostId, name: "rack", auto: false });
await call("PATCH", `/servers/${guestId}`, { noParent: true });
assert.equal((await call("PATCH", `/servers/${guestId}`, { parentServerId: null })).status, 200);
d = await detailOf();
assert.equal(d.server.noParent, false);
assert.deepEqual(d.relations.parent, { id: hostId, name: "rack", auto: true });
who = "operator";
assert.equal((await call("PATCH", `/servers/${guestId}`, { noParent: true })).status, 403);
who = "admin";
await db.update(servers).set({ proxmoxNode: null }).where(eq(servers.id, guestId));
});
test("removing the host sets the servers on it free", async () => {
await call("PATCH", `/servers/${guestId}`, { parentServerId: hostId });
assert.equal((await call("DELETE", `/servers/${hostId}`)).status, 204);