Add Proxmox snapshots: list, take, roll back, delete
A guest's drawer on the Proxmox page now has a Snapshots section. Everyone signed in sees them, operators take them, administrators roll back and delete (each behind a confirmation). Proxmox does each as a task, followed for up to 20 seconds. Audit log and change log entries for all three. An http:// Proxmox address is now allowed. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
12e9fee7af
commit
97df28c6dc
11 files changed
+733
-11
No files matched your search
@@ -19,8 +19,12 @@
|
||||
*
|
||||
* Proxmox commonly runs with a self-signed certificate in homelab setups, so
|
||||
* (like the cPanel DNS adapter) this uses node:https directly rather than
|
||||
* fetch, to support an "insecure" opt-out of certificate verification.
|
||||
* fetch, to support an "insecure" opt-out of certificate verification (an address that says http:// is spoken to over plain HTTP, as for a proxy in front of it).
|
||||
*
|
||||
* Snapshots: GET/POST /nodes/{node}/{qemu,lxc}/{vmid}/snapshot, POST …/snapshot/{name}/rollback and DELETE …/snapshot/{name} (VM.Audit to list, VM.Snapshot to take or delete, VM.Snapshot.Rollback
|
||||
* to roll back). Each of the last three answers with a task id (UPID), which is followed with GET /nodes/{node}/tasks/{upid}/status until it has stopped.
|
||||
*/
|
||||
import * as http from "node:http";
|
||||
import * as https from "node:https";
|
||||
import { withDiagLogging } from "../../services/diagLog.js";
|
||||
import { ID_PATTERNS, InvalidIdentifierError, numericSegment, pathSegment } from "../../utils/pathSegment.js";
|
||||
@@ -113,6 +117,28 @@ export interface ProxmoxBackupJob {
|
||||
exclude: string | null;
|
||||
}
|
||||
|
||||
/** One snapshot of a guest, as Proxmox lists it (its "current" line, which is the guest as it is now, is not one). */
|
||||
export interface ProxmoxSnapshot {
|
||||
name: string;
|
||||
description: string;
|
||||
/** ISO; null when Proxmox did not say. */
|
||||
takenAt: string | null;
|
||||
/** A VM's snapshot that includes its memory, so a rollback brings it back running. */
|
||||
withRam: boolean;
|
||||
/** The snapshot this one was taken after; null for the first. */
|
||||
parent: string | null;
|
||||
}
|
||||
|
||||
/** How a task ended: whether it has stopped, and if so whether it worked and what Proxmox said. */
|
||||
export interface ProxmoxTaskResult {
|
||||
/** True once the task has stopped (it may still be running when the wait ran out). */
|
||||
done: boolean;
|
||||
ok: boolean | null;
|
||||
/** Proxmox's own word for how it ended ("OK", or the error). */
|
||||
message: string | null;
|
||||
upid: string;
|
||||
}
|
||||
|
||||
export interface ProxmoxBackupTask {
|
||||
node: string;
|
||||
upid: string;
|
||||
@@ -164,6 +190,12 @@ export interface ProxmoxAdapter {
|
||||
restartGuest(node: string, type: ProxmoxGuestType, vmid: number): Promise<void>;
|
||||
/** Graceful shutdown (ACPI power event for a VM, SIGTERM-then-wait for a container) — unlike stopGuest, this asks the guest OS to shut itself down. */
|
||||
shutdownGuest(node: string, type: ProxmoxGuestType, vmid: number): Promise<void>;
|
||||
listSnapshots(node: string, type: ProxmoxGuestType, vmid: number): Promise<ProxmoxSnapshot[]>;
|
||||
/** Takes a snapshot; answers with the task that makes it (followed for a while, so it says how it went when it was quick). */
|
||||
createSnapshot(node: string, type: ProxmoxGuestType, vmid: number, options: { name: string; description?: string; includeRam?: boolean }, waitMs?: number): Promise<ProxmoxTaskResult>;
|
||||
/** Rolls a guest back to a snapshot: everything since it was taken is lost. */
|
||||
rollbackSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs?: number): Promise<ProxmoxTaskResult>;
|
||||
deleteSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs?: number): Promise<ProxmoxTaskResult>;
|
||||
listBackupJobs(): Promise<ProxmoxBackupJob[]>;
|
||||
/** Most recent vzdump task runs across every online node, newest first. */
|
||||
listRecentBackupTasks(limitPerNode?: number): Promise<ProxmoxBackupTask[]>;
|
||||
@@ -196,17 +228,23 @@ interface RawResponse {
|
||||
text: () => string;
|
||||
}
|
||||
|
||||
function request(url: string, insecure: boolean, options: { method?: string; headers?: Record<string, string> } = {}): Promise<RawResponse> {
|
||||
function request(url: string, insecure: boolean, options: { method?: string; headers?: Record<string, string>; body?: string } = {}): Promise<RawResponse> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const parsed = new URL(url);
|
||||
const req = https.request(
|
||||
const plain = parsed.protocol === "http:";
|
||||
const headers: Record<string, string | number> = { ...(options.headers || {}) };
|
||||
if (options.body !== undefined) {
|
||||
headers["Content-Type"] = "application/x-www-form-urlencoded";
|
||||
headers["Content-Length"] = Buffer.byteLength(options.body);
|
||||
}
|
||||
const req = (plain ? http : https).request(
|
||||
{
|
||||
hostname: parsed.hostname,
|
||||
port: parsed.port || 8006,
|
||||
port: parsed.port || (plain ? 80 : 8006),
|
||||
path: parsed.pathname + parsed.search,
|
||||
method: options.method || "GET",
|
||||
headers: options.headers || {},
|
||||
rejectUnauthorized: !insecure,
|
||||
headers,
|
||||
...(plain ? {} : { rejectUnauthorized: !insecure }),
|
||||
},
|
||||
(res) => {
|
||||
let body = "";
|
||||
@@ -218,7 +256,7 @@ function request(url: string, insecure: boolean, options: { method?: string; hea
|
||||
},
|
||||
);
|
||||
req.on("error", reject);
|
||||
req.end();
|
||||
req.end(options.body);
|
||||
});
|
||||
}
|
||||
|
||||
@@ -244,8 +282,9 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
|
||||
};
|
||||
}
|
||||
|
||||
async function api(method: string, path: string): Promise<any> {
|
||||
const res = await request(`${base()}/api2/json${path}`, insecure, { method, headers: headers() });
|
||||
async function api(method: string, path: string, params?: Record<string, string | number>): Promise<any> {
|
||||
const body = params && Object.keys(params).length > 0 ? new URLSearchParams(Object.entries(params).map(([k, v]) => [k, String(v)])).toString() : undefined;
|
||||
const res = await request(`${base()}/api2/json${path}`, insecure, { method, headers: headers(), body });
|
||||
let data: any = null;
|
||||
try {
|
||||
data = res.text() ? JSON.parse(res.text()) : null;
|
||||
@@ -537,6 +576,64 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
|
||||
const restartGuest = (node: string, type: ProxmoxGuestType, vmid: number) => statusAction(node, type, vmid, "reboot");
|
||||
const shutdownGuest = (node: string, type: ProxmoxGuestType, vmid: number) => statusAction(node, type, vmid, "shutdown");
|
||||
|
||||
const guestPath = (node: string, type: ProxmoxGuestType, vmid: number) => `/nodes/${nodeSeg(node)}/${typeSeg(type)}/${vmidSeg(vmid)}`;
|
||||
const snapSeg = (name: string) => pathSegment(name, "snapshot name", ID_PATTERNS.proxmoxSnapshot);
|
||||
const taskSeg = (upid: string) => pathSegment(upid, "task id", ID_PATTERNS.proxmoxTask);
|
||||
|
||||
async function listSnapshots(node: string, type: ProxmoxGuestType, vmid: number): Promise<ProxmoxSnapshot[]> {
|
||||
const data = await api("GET", `${guestPath(node, type, vmid)}/snapshot`);
|
||||
return (Array.isArray(data) ? data : [])
|
||||
.filter((s: any) => typeof s?.name === "string" && s.name !== "current")
|
||||
.map((s: any) => ({
|
||||
name: s.name as string,
|
||||
description: typeof s.description === "string" ? s.description.trim() : "",
|
||||
takenAt: typeof s.snaptime === "number" && s.snaptime > 0 ? new Date(s.snaptime * 1000).toISOString() : null,
|
||||
withRam: s.vmstate === 1 || s.vmstate === "1",
|
||||
parent: typeof s.parent === "string" && s.parent !== "" ? s.parent : null,
|
||||
}))
|
||||
.sort((a, b) => (a.takenAt ?? "").localeCompare(b.takenAt ?? "") || a.name.localeCompare(b.name));
|
||||
}
|
||||
|
||||
/** Follows a task until it has stopped, or for as long as it is allowed to, and says how it stands. */
|
||||
async function followTask(node: string, upid: string, waitMs: number, everyMs = 1000): Promise<ProxmoxTaskResult> {
|
||||
const until = Date.now() + waitMs;
|
||||
for (;;) {
|
||||
const status = await api("GET", `/nodes/${nodeSeg(node)}/tasks/${taskSeg(upid)}/status`);
|
||||
if (status?.status === "stopped") {
|
||||
const exit = typeof status.exitstatus === "string" ? status.exitstatus : null;
|
||||
return { done: true, ok: exit === "OK", message: exit, upid };
|
||||
}
|
||||
if (Date.now() >= until) return { done: false, ok: null, message: null, upid };
|
||||
await new Promise((r) => setTimeout(r, Math.min(everyMs, Math.max(0, until - Date.now()))));
|
||||
}
|
||||
}
|
||||
|
||||
/** A call that starts a task answers with the task's id. */
|
||||
const upidOf = (data: unknown): string => {
|
||||
if (typeof data !== "string" || !ID_PATTERNS.proxmoxTask.test(data)) throw new Error("Proxmox did not say which task it started.");
|
||||
return data;
|
||||
};
|
||||
|
||||
async function createSnapshot(node: string, type: ProxmoxGuestType, vmid: number, options: { name: string; description?: string; includeRam?: boolean }, waitMs = 0): Promise<ProxmoxTaskResult> {
|
||||
snapSeg(options.name);
|
||||
const params: Record<string, string | number> = { snapname: options.name };
|
||||
if (options.description?.trim()) params.description = options.description.trim();
|
||||
// Memory can only be kept for a virtual machine (a container has none to keep).
|
||||
if (options.includeRam && type === "qemu") params.vmstate = 1;
|
||||
const upid = upidOf(await api("POST", `${guestPath(node, type, vmid)}/snapshot`, params));
|
||||
return followTask(node, upid, waitMs);
|
||||
}
|
||||
|
||||
async function rollbackSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs = 0): Promise<ProxmoxTaskResult> {
|
||||
const upid = upidOf(await api("POST", `${guestPath(node, type, vmid)}/snapshot/${snapSeg(name)}/rollback`));
|
||||
return followTask(node, upid, waitMs);
|
||||
}
|
||||
|
||||
async function deleteSnapshot(node: string, type: ProxmoxGuestType, vmid: number, name: string, waitMs = 0): Promise<ProxmoxTaskResult> {
|
||||
const upid = upidOf(await api("DELETE", `${guestPath(node, type, vmid)}/snapshot/${snapSeg(name)}`));
|
||||
return followTask(node, upid, waitMs);
|
||||
}
|
||||
|
||||
async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> {
|
||||
const start = Date.now();
|
||||
try {
|
||||
@@ -556,6 +653,10 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
|
||||
stopGuest,
|
||||
restartGuest,
|
||||
shutdownGuest,
|
||||
listSnapshots,
|
||||
createSnapshot,
|
||||
rollbackSnapshot,
|
||||
deleteSnapshot,
|
||||
listBackupJobs,
|
||||
listRecentBackupTasks,
|
||||
});
|
||||
|
||||
@@ -871,6 +871,86 @@ integrationsRouter.get("/:id/proxmox/backups", asyncHandler(async (req, res) =>
|
||||
}
|
||||
}));
|
||||
|
||||
// ── Proxmox snapshots ─────────────────────────────────────────────────────
|
||||
// Listing is for everyone signed in (like the guests); taking one is an operator's; rolling back and deleting one are an administrator's — a rollback throws away everything the guest has done since.
|
||||
|
||||
/** How long a request waits for Proxmox's task to finish before saying it is still going (the page then looks again). */
|
||||
export const SNAPSHOT_WAIT_MS = 20_000;
|
||||
/** The wait, which a test (or a very slow storage) can change with PROXMOX_TASK_WAIT_MS. */
|
||||
const snapshotWaitMs = () => (Number(process.env.PROXMOX_TASK_WAIT_MS) > 0 ? Number(process.env.PROXMOX_TASK_WAIT_MS) : SNAPSHOT_WAIT_MS);
|
||||
|
||||
const snapshotBody = z.object({
|
||||
name: z.string().trim().regex(ID_PATTERNS.proxmoxSnapshot, "A snapshot name starts with a letter, then letters, digits, - and _, at most 40 characters.").optional(),
|
||||
description: z.string().trim().max(200).optional(),
|
||||
includeRam: z.boolean().optional(),
|
||||
});
|
||||
|
||||
/** A snapshot name made from the time, when none was given. */
|
||||
export const autoSnapshotName = (now: Date = new Date()): string => `hlm-${now.toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")}`;
|
||||
|
||||
/** The guest a request is about, checked before anything is asked of Proxmox; null (and a refusal sent) when it is not one. */
|
||||
function guestFromParams(req: Request, res: Response): { node: string; type: "qemu" | "lxc"; vmid: number } | null {
|
||||
if (!isValidId(req.params.node, ID_PATTERNS.proxmoxNode)) return (rejectInvalidId(res, "node name"), null);
|
||||
const vmid = Number(req.params.vmid);
|
||||
if (!Number.isInteger(vmid) || vmid < 1) return (res.status(400).json({ error: "invalid_vmid" }), null);
|
||||
const type = req.params.type;
|
||||
if (type !== "qemu" && type !== "lxc") return (res.status(400).json({ error: "invalid_type" }), null);
|
||||
return { node: req.params.node, type, vmid };
|
||||
}
|
||||
|
||||
integrationsRouter.get("/:id/proxmox/nodes/:node/:type/:vmid/snapshots", asyncHandler(async (req, res) => {
|
||||
const found = await requireProxmoxAdapter(req, res);
|
||||
if (!found) return;
|
||||
const guest = guestFromParams(req, res);
|
||||
if (!guest) return;
|
||||
try {
|
||||
res.json({ snapshots: await found.adapter.listSnapshots(guest.node, guest.type, guest.vmid) });
|
||||
} catch (err) {
|
||||
res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
|
||||
}
|
||||
}));
|
||||
|
||||
/** Runs one snapshot task, writes it down, and says how it went: a task that ended badly is an error with what Proxmox said, one that is still going is said to be. */
|
||||
async function snapshotTask(req: Request, res: Response, what: "create" | "rollback" | "delete", run: (found: NonNullable<Awaited<ReturnType<typeof requireProxmoxAdapter>>>, guest: { node: string; type: "qemu" | "lxc"; vmid: number }) => Promise<{ done: boolean; ok: boolean | null; message: string | null; upid: string }>, snapshot: string, extra: Record<string, unknown> = {}) {
|
||||
const found = await requireProxmoxAdapter(req, res);
|
||||
if (!found) return;
|
||||
const guest = guestFromParams(req, res);
|
||||
if (!guest) return;
|
||||
let result;
|
||||
try {
|
||||
result = await run(found, guest);
|
||||
} catch (err) {
|
||||
return res.status(502).json({ error: err instanceof Error ? err.message : String(err) });
|
||||
}
|
||||
await recordAudit({
|
||||
actor: req.currentUser!,
|
||||
category: "integration",
|
||||
action: `${what}_snapshot`,
|
||||
targetType: "proxmox_guest",
|
||||
targetId: guest.vmid,
|
||||
detail: { integrationId: found.integration.id, node: guest.node, vmid: guest.vmid, guestType: guest.type, snapshot, done: result.done, ok: result.ok, ...extra },
|
||||
});
|
||||
if (result.done && !result.ok) return res.status(502).json({ error: `Proxmox: ${result.message ?? "the task failed"}`, snapshot, upid: result.upid });
|
||||
res.json({ snapshot, done: result.done, ok: result.ok, upid: result.upid });
|
||||
}
|
||||
|
||||
integrationsRouter.post("/:id/proxmox/nodes/:node/:type/:vmid/snapshots", requireRole("operator"), asyncHandler(async (req, res) => {
|
||||
const parsed = snapshotBody.safeParse(req.body ?? {});
|
||||
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: parsed.error.issues[0]?.message ?? "That is not a snapshot." });
|
||||
const name = parsed.data.name ?? autoSnapshotName();
|
||||
await snapshotTask(req, res, "create", (f, g) => f.adapter.createSnapshot(g.node, g.type, g.vmid, { name, description: parsed.data.description, includeRam: parsed.data.includeRam }, snapshotWaitMs()), name, { withRam: parsed.data.includeRam === true && req.params.type === "qemu" });
|
||||
}));
|
||||
|
||||
integrationsRouter.post("/:id/proxmox/nodes/:node/:type/:vmid/snapshots/:name/rollback", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
if (!isValidId(req.params.name, ID_PATTERNS.proxmoxSnapshot)) return rejectInvalidId(res, "snapshot name");
|
||||
await snapshotTask(req, res, "rollback", (f, g) => f.adapter.rollbackSnapshot(g.node, g.type, g.vmid, req.params.name, snapshotWaitMs()), req.params.name);
|
||||
}));
|
||||
|
||||
integrationsRouter.delete("/:id/proxmox/nodes/:node/:type/:vmid/snapshots/:name", requireRole("admin"), asyncHandler(async (req, res) => {
|
||||
if (!isValidId(req.params.name, ID_PATTERNS.proxmoxSnapshot)) return rejectInvalidId(res, "snapshot name");
|
||||
await snapshotTask(req, res, "delete", (f, g) => f.adapter.deleteSnapshot(g.node, g.type, g.vmid, req.params.name, snapshotWaitMs()), req.params.name);
|
||||
}));
|
||||
|
||||
const proxmoxActions = ["start", "stop", "restart", "shutdown"] as const;
|
||||
|
||||
for (const action of proxmoxActions) {
|
||||
|
||||
@@ -123,6 +123,13 @@ function settingsSummary(detail: Record<string, unknown>): string | null {
|
||||
}
|
||||
|
||||
/** What is left of the detail once the name and what is already in the sentence are taken out. */
|
||||
/** "guest 105 on pve1", from what an audit entry about a Proxmox guest says. */
|
||||
function guestWords(detail: Record<string, unknown>): string {
|
||||
const id = typeof detail.vmid === "number" ? ` ${detail.vmid}` : "";
|
||||
const node = typeof detail.node === "string" ? ` on ${detail.node}` : "";
|
||||
return `guest${id}${node}`;
|
||||
}
|
||||
|
||||
function genericSummary(detail: Record<string, unknown>, skip: string[] = []): string | null {
|
||||
const parts = Object.entries(detail)
|
||||
.filter(([k, v]) => !["name", "message", ...skip].includes(k) && v !== null && v !== undefined && v !== "" && !(Array.isArray(v) && v.length === 0))
|
||||
@@ -195,6 +202,12 @@ export function describeChange(category: string, action: string, detail: Record<
|
||||
return { title: `${typeof detail.changed === "number" ? detail.changed : "Several"} snoozed alert${detail.changed === 1 ? "" : "s"} woken at once`, tone: "neutral", detail: null };
|
||||
case "inventory/bulk_change":
|
||||
return { title: detail.change === "undo" ? "A change to several pieces of hardware was undone" : `${typeof detail.changed === "number" ? detail.changed : "Several"} piece${detail.changed === 1 ? "" : "s"} of hardware changed at once`, tone: "neutral", detail: genericSummary(detail, ["ids", "changed", "change"]) };
|
||||
case "integration/create_snapshot":
|
||||
return { title: `A snapshot was taken of ${guestWords(detail)}`, tone: "neutral", detail: str(detail.snapshot) ? `${str(detail.snapshot)}${detail.withRam ? " (with memory)" : ""}` : null };
|
||||
case "integration/rollback_snapshot":
|
||||
return { title: `${guestWords(detail)[0].toUpperCase()}${guestWords(detail).slice(1)} was rolled back to a snapshot`, tone: "bad", detail: str(detail.snapshot) };
|
||||
case "integration/delete_snapshot":
|
||||
return { title: `A snapshot was deleted from ${guestWords(detail)}`, tone: "neutral", detail: str(detail.snapshot) };
|
||||
case "notification/resend":
|
||||
return { title: "A notification was sent again", tone: "neutral", detail: null };
|
||||
case "webhook/retry":
|
||||
|
||||
@@ -23,6 +23,10 @@ export const ID_PATTERNS = {
|
||||
tailscaleDevice: /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/,
|
||||
/** Proxmox node names are hostnames. */
|
||||
proxmoxNode: /^[A-Za-z0-9][A-Za-z0-9.-]{0,62}$/,
|
||||
/** A Proxmox snapshot name: starts with a letter, then letters, digits, "-" and "_", at most 40 characters (Proxmox's own rule). */
|
||||
proxmoxSnapshot: /^[A-Za-z][A-Za-z0-9_-]{0,39}$/,
|
||||
/** A Proxmox task id (a "UPID"): UPID:node:hex:hex:hex:type:id:user: — letters, digits and the few marks it is made of. */
|
||||
proxmoxTask: /^UPID:[A-Za-z0-9._@!:-]{1,250}$/,
|
||||
/** Gitea user/organisation and repository names. */
|
||||
giteaName: /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/,
|
||||
/** Docker container IDs and names. */
|
||||
|
||||
Reference in new issue
Block a user