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
+3
-2
@@ -43,9 +43,10 @@ It is for the readers written from documentation (see "Not verified" on each int
|
|||||||
|
|
||||||
- **Config fields:** Proxmox URL, API token ID, API token secret, allow self-signed certificate
|
- **Config fields:** Proxmox URL, API token ID, API token secret, allow self-signed certificate
|
||||||
- **Auth:** `PVEAPIToken=<tokenId>=<tokenSecret>` header
|
- **Auth:** `PVEAPIToken=<tokenId>=<tokenSecret>` header
|
||||||
- **Actions used:** list nodes/VMs/LXCs, read guest config and live status, read node host stats and storage usage, start/stop/reboot/shutdown a guest, read backup job schedules and recent `vzdump` task history
|
- **Actions used:** list nodes/VMs/LXCs, read guest config and live status, read node host stats and storage usage, start/stop/reboot/shutdown a guest, **list, take, roll back to and delete a guest's snapshots**, read backup job schedules and recent `vzdump` task history
|
||||||
- **Required access:** A dedicated API token (Datacenter → Permissions → API Tokens) with a role granting **VM.Audit + VM.PowerMgmt** (e.g. `PVEVMAdmin`) on the VMs/LXCs to manage, **plus Sys.Audit and Datastore.Audit** on the node(s) for the host CPU/RAM/storage cards to populate. A token scoped to VM management only will still work for the guest list and power actions — it'll just show an error on the per-node hardware card instead of failing outright. Backup job schedules and run history need that same **Sys.Audit** — no separate permission to grant if the node-stats card already works.
|
- **Required access:** A dedicated API token (Datacenter → Permissions → API Tokens) with a role granting **VM.Audit + VM.PowerMgmt** (e.g. `PVEVMAdmin`) on the VMs/LXCs to manage, **plus Sys.Audit and Datastore.Audit** on the node(s) for the host CPU/RAM/storage cards to populate. A token scoped to VM management only will still work for the guest list and power actions — it'll just show an error on the per-node hardware card instead of failing outright. Backup job schedules and run history need that same **Sys.Audit** — no separate permission to grant if the node-stats card already works.
|
||||||
- **Notes:** self-signed certificates are supported via the "Allow self-signed certificate" checkbox — common for an internal PVE host.
|
- **Snapshots** (Infrastructure → Proxmox → click a guest → *Snapshots*): everyone signed in sees a guest's snapshots (oldest first, a branch indented, *with memory* marked); an **operator** can take one (a name — or one made from the time, `hlm-YYYYMMDD-HHMMSS` — a description, and for a running VM whether to keep its memory so a rollback brings it back running); **rolling back and deleting are an administrator's**, each behind a confirmation, because a rollback throws away everything the guest has done since and Proxmox removes the snapshots taken after the one chosen. Proxmox does each as a task: the page waits up to 20 s and says how it went, or that it is still going and looks again. Every one is in the audit log and the change log (*A snapshot was taken of guest 100 on pve1*). The token needs **VM.Snapshot** (take, delete) and **VM.Snapshot.Rollback** (roll back) as well as VM.Audit — the `PVEVMAdmin` role has them; a token without them lists the snapshots and gets Proxmox's own refusal when it tries the rest. Checked against Proxmox's published API description and a pretend Proxmox, not a live host.
|
||||||
|
- **Notes:** self-signed certificates are supported via the "Allow self-signed certificate" checkbox — common for an internal PVE host. An address that says `http://` (a reverse proxy in front of Proxmox) is spoken to over plain HTTP.
|
||||||
|
|
||||||
### Synology DSM
|
### Synology DSM
|
||||||
|
|
||||||
|
|||||||
@@ -898,6 +898,8 @@ admin's dashboard shows a checklist (an integration, a server and agent, DNS, a
|
|||||||
secret, notifications, a second user) whose ticks come from what actually
|
secret, notifications, a second user) whose ticks come from what actually
|
||||||
exists; it can be hidden, and brought back from the search box.
|
exists; it can be hidden, and brought back from the search box.
|
||||||
|
|
||||||
|
**Proxmox snapshots.** Click a guest on Infrastructure → Proxmox and its drawer has a **Snapshots** section: what there is (oldest first, a branch indented, *with memory* marked), **Take a snapshot** for operators (a name or one from the time, a description, and for a running VM whether to keep its memory), and **Roll back…** and **Delete…** for administrators, each behind a confirmation that says what is lost. Proxmox does each as a task, followed for up to 20 seconds; each is in the audit log and the change log. The API token needs VM.Snapshot and VM.Snapshot.Rollback (the PVEVMAdmin role has them). The guest actions (start, shut down, restart, stop) were there already.
|
||||||
|
|
||||||
**Accessibility.** There is a skip-to-content link, labelled landmarks, visible
|
**Accessibility.** There is a skip-to-content link, labelled landmarks, visible
|
||||||
keyboard focus, and page changes are announced to screen readers; sortable table
|
keyboard focus, and page changes are announced to screen readers; sortable table
|
||||||
headings are real buttons; every form field is tied to its label; status is
|
headings are real buttons; every form field is tied to its label; status is
|
||||||
|
|||||||
@@ -19,8 +19,12 @@
|
|||||||
*
|
*
|
||||||
* Proxmox commonly runs with a self-signed certificate in homelab setups, so
|
* Proxmox commonly runs with a self-signed certificate in homelab setups, so
|
||||||
* (like the cPanel DNS adapter) this uses node:https directly rather than
|
* (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 * as https from "node:https";
|
||||||
import { withDiagLogging } from "../../services/diagLog.js";
|
import { withDiagLogging } from "../../services/diagLog.js";
|
||||||
import { ID_PATTERNS, InvalidIdentifierError, numericSegment, pathSegment } from "../../utils/pathSegment.js";
|
import { ID_PATTERNS, InvalidIdentifierError, numericSegment, pathSegment } from "../../utils/pathSegment.js";
|
||||||
@@ -113,6 +117,28 @@ export interface ProxmoxBackupJob {
|
|||||||
exclude: string | null;
|
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 {
|
export interface ProxmoxBackupTask {
|
||||||
node: string;
|
node: string;
|
||||||
upid: string;
|
upid: string;
|
||||||
@@ -164,6 +190,12 @@ export interface ProxmoxAdapter {
|
|||||||
restartGuest(node: string, type: ProxmoxGuestType, vmid: number): Promise<void>;
|
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. */
|
/** 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>;
|
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[]>;
|
listBackupJobs(): Promise<ProxmoxBackupJob[]>;
|
||||||
/** Most recent vzdump task runs across every online node, newest first. */
|
/** Most recent vzdump task runs across every online node, newest first. */
|
||||||
listRecentBackupTasks(limitPerNode?: number): Promise<ProxmoxBackupTask[]>;
|
listRecentBackupTasks(limitPerNode?: number): Promise<ProxmoxBackupTask[]>;
|
||||||
@@ -196,17 +228,23 @@ interface RawResponse {
|
|||||||
text: () => string;
|
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) => {
|
return new Promise((resolve, reject) => {
|
||||||
const parsed = new URL(url);
|
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,
|
hostname: parsed.hostname,
|
||||||
port: parsed.port || 8006,
|
port: parsed.port || (plain ? 80 : 8006),
|
||||||
path: parsed.pathname + parsed.search,
|
path: parsed.pathname + parsed.search,
|
||||||
method: options.method || "GET",
|
method: options.method || "GET",
|
||||||
headers: options.headers || {},
|
headers,
|
||||||
rejectUnauthorized: !insecure,
|
...(plain ? {} : { rejectUnauthorized: !insecure }),
|
||||||
},
|
},
|
||||||
(res) => {
|
(res) => {
|
||||||
let body = "";
|
let body = "";
|
||||||
@@ -218,7 +256,7 @@ function request(url: string, insecure: boolean, options: { method?: string; hea
|
|||||||
},
|
},
|
||||||
);
|
);
|
||||||
req.on("error", reject);
|
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> {
|
async function api(method: string, path: string, params?: Record<string, string | number>): Promise<any> {
|
||||||
const res = await request(`${base()}/api2/json${path}`, insecure, { method, headers: headers() });
|
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;
|
let data: any = null;
|
||||||
try {
|
try {
|
||||||
data = res.text() ? JSON.parse(res.text()) : null;
|
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 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 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 }> {
|
async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> {
|
||||||
const start = Date.now();
|
const start = Date.now();
|
||||||
try {
|
try {
|
||||||
@@ -556,6 +653,10 @@ export function createProxmoxAdapter(config: ProxmoxConfig): ProxmoxAdapter {
|
|||||||
stopGuest,
|
stopGuest,
|
||||||
restartGuest,
|
restartGuest,
|
||||||
shutdownGuest,
|
shutdownGuest,
|
||||||
|
listSnapshots,
|
||||||
|
createSnapshot,
|
||||||
|
rollbackSnapshot,
|
||||||
|
deleteSnapshot,
|
||||||
listBackupJobs,
|
listBackupJobs,
|
||||||
listRecentBackupTasks,
|
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;
|
const proxmoxActions = ["start", "stop", "restart", "shutdown"] as const;
|
||||||
|
|
||||||
for (const action of proxmoxActions) {
|
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. */
|
/** 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 {
|
function genericSummary(detail: Record<string, unknown>, skip: string[] = []): string | null {
|
||||||
const parts = Object.entries(detail)
|
const parts = Object.entries(detail)
|
||||||
.filter(([k, v]) => !["name", "message", ...skip].includes(k) && v !== null && v !== undefined && v !== "" && !(Array.isArray(v) && v.length === 0))
|
.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 };
|
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":
|
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"]) };
|
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":
|
case "notification/resend":
|
||||||
return { title: "A notification was sent again", tone: "neutral", detail: null };
|
return { title: "A notification was sent again", tone: "neutral", detail: null };
|
||||||
case "webhook/retry":
|
case "webhook/retry":
|
||||||
|
|||||||
@@ -23,6 +23,10 @@ export const ID_PATTERNS = {
|
|||||||
tailscaleDevice: /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/,
|
tailscaleDevice: /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/,
|
||||||
/** Proxmox node names are hostnames. */
|
/** Proxmox node names are hostnames. */
|
||||||
proxmoxNode: /^[A-Za-z0-9][A-Za-z0-9.-]{0,62}$/,
|
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. */
|
/** Gitea user/organisation and repository names. */
|
||||||
giteaName: /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/,
|
giteaName: /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,100}$/,
|
||||||
/** Docker container IDs and names. */
|
/** Docker container IDs and names. */
|
||||||
|
|||||||
@@ -0,0 +1,310 @@
|
|||||||
|
/**
|
||||||
|
* Proxmox snapshots: listing them, taking one (with or without memory), rolling back and deleting, each a Proxmox task that is followed until it stops; what is refused before Proxmox is asked,
|
||||||
|
* who may do which, and that every one is written in the audit log. Against a pretend Proxmox.
|
||||||
|
*
|
||||||
|
* Run with: npm test --workspace server
|
||||||
|
*/
|
||||||
|
import { test, describe, before, after, beforeEach } from "node:test";
|
||||||
|
import assert from "node:assert/strict";
|
||||||
|
import { createServer as createHttpServer, type Server } from "node:http";
|
||||||
|
import { mkdtempSync, rmSync } from "node:fs";
|
||||||
|
import { tmpdir } from "node:os";
|
||||||
|
import { join } from "node:path";
|
||||||
|
import type { AddressInfo } from "node:net";
|
||||||
|
|
||||||
|
const dir = mkdtempSync(join(tmpdir(), "hm-pvesnap-"));
|
||||||
|
process.env.DATABASE_PATH = join(dir, "test.sqlite");
|
||||||
|
process.env.SESSION_DIR = join(dir, "sessions");
|
||||||
|
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
|
||||||
|
process.env.PROXMOX_TASK_WAIT_MS = "300";
|
||||||
|
|
||||||
|
const express = (await import("express")).default;
|
||||||
|
const { db } = await import("../src/db/client.js");
|
||||||
|
const { users, integrations, auditLog } = await import("../src/db/schema.js");
|
||||||
|
const { runMigrations } = await import("../src/db/migrate.js");
|
||||||
|
const { createProxmoxAdapter } = await import("../src/integrations/proxmox/adapter.js");
|
||||||
|
const { integrationsRouter, autoSnapshotName } = await import("../src/routes/integrations.js");
|
||||||
|
const { ID_PATTERNS } = await import("../src/utils/pathSegment.js");
|
||||||
|
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
|
||||||
|
const { snapshotDepths } = await import("../../web/src/utils/proxmoxSnapshots.js");
|
||||||
|
|
||||||
|
await runMigrations();
|
||||||
|
|
||||||
|
const UPID = "UPID:pve1:00001A2B:0003C4D5:67890ABC:qmsnapshot:100:root@pam:";
|
||||||
|
let seen: { method: string; path: string; body: string; auth: string }[] = [];
|
||||||
|
/** How the task ends: how many times it answers "running" first, and the exit status once it has stopped (null: it never stops). */
|
||||||
|
let task: { runningFirst: number; exit: string | null } = { runningFirst: 0, exit: "OK" };
|
||||||
|
let polls = 0;
|
||||||
|
let listAnswer: unknown[] = [];
|
||||||
|
let apiFailure: number | null = null;
|
||||||
|
let badUpid = false;
|
||||||
|
|
||||||
|
let pve: Server;
|
||||||
|
let pveUrl = "";
|
||||||
|
before(async () => {
|
||||||
|
pve = createHttpServer((req, res) => {
|
||||||
|
let body = "";
|
||||||
|
req.on("data", (c) => (body += c));
|
||||||
|
req.on("end", () => {
|
||||||
|
const u = new URL(req.url ?? "", "http://x");
|
||||||
|
seen.push({ method: req.method ?? "", path: u.pathname, body, auth: String(req.headers.authorization ?? "") });
|
||||||
|
const send = (status: number, json: unknown) => {
|
||||||
|
res.writeHead(status, { "content-type": "application/json" });
|
||||||
|
res.end(JSON.stringify(json));
|
||||||
|
};
|
||||||
|
if (apiFailure !== null) return send(apiFailure, { errors: { snapname: "bad" }, message: "no good" });
|
||||||
|
if (/\/tasks\/[^/]+\/status$/.test(u.pathname)) {
|
||||||
|
polls++;
|
||||||
|
return send(200, { data: polls <= task.runningFirst || task.exit === null ? { status: "running" } : { status: "stopped", exitstatus: task.exit } });
|
||||||
|
}
|
||||||
|
if (/\/snapshot$/.test(u.pathname) && req.method === "GET") return send(200, { data: listAnswer });
|
||||||
|
if (/\/snapshot(\/[^/]+(\/rollback)?)?$/.test(u.pathname)) return send(200, { data: badUpid ? { not: "a task" } : UPID });
|
||||||
|
send(404, { message: "no such thing" });
|
||||||
|
});
|
||||||
|
});
|
||||||
|
await new Promise<void>((resolve) => pve.listen(0, "127.0.0.1", resolve));
|
||||||
|
pveUrl = `http://127.0.0.1:${(pve.address() as AddressInfo).port}`;
|
||||||
|
});
|
||||||
|
beforeEach(() => {
|
||||||
|
seen = [];
|
||||||
|
polls = 0;
|
||||||
|
task = { runningFirst: 0, exit: "OK" };
|
||||||
|
apiFailure = null;
|
||||||
|
badUpid = false;
|
||||||
|
listAnswer = [];
|
||||||
|
});
|
||||||
|
after(() => {
|
||||||
|
pve.close();
|
||||||
|
});
|
||||||
|
|
||||||
|
const adapter = () => createProxmoxAdapter({ url: pveUrl, tokenId: "root@pam!lab", tokenSecret: "s3cret", insecure: true });
|
||||||
|
|
||||||
|
describe("listing", () => {
|
||||||
|
test("the snapshots of a guest, oldest first, without the line that is the guest as it is now", async () => {
|
||||||
|
listAnswer = [
|
||||||
|
{ name: "after-update", description: " after the update ", snaptime: 1_760_000_100, vmstate: 1, parent: "before-update" },
|
||||||
|
{ name: "current", description: "You are here!", parent: "after-update" },
|
||||||
|
{ name: "before-update", description: "", snaptime: 1_760_000_000, vmstate: 0 },
|
||||||
|
];
|
||||||
|
const list = await adapter().listSnapshots("pve1", "qemu", 100);
|
||||||
|
assert.deepEqual(list.map((s) => [s.name, s.description, s.withRam, s.parent]), [["before-update", "", false, null], ["after-update", "after the update", true, "before-update"]]);
|
||||||
|
assert.equal(list[0].takenAt, new Date(1_760_000_000_000).toISOString());
|
||||||
|
assert.deepEqual(seen.map((s) => [s.method, s.path, s.auth]), [["GET", "/api2/json/nodes/pve1/qemu/100/snapshot", "PVEAPIToken=root@pam!lab=s3cret"]]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a guest with none, a time Proxmox did not give, and an answer that is not a list", async () => {
|
||||||
|
assert.deepEqual(await adapter().listSnapshots("pve1", "lxc", 200), []);
|
||||||
|
listAnswer = [{ name: "odd" }];
|
||||||
|
assert.equal((await adapter().listSnapshots("pve1", "lxc", 200))[0].takenAt, null);
|
||||||
|
listAnswer = {} as never;
|
||||||
|
assert.deepEqual(await adapter().listSnapshots("pve1", "qemu", 1), [], "an answer that is not a list is none");
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("taking one", () => {
|
||||||
|
test("the name goes as a form, with the description, and the memory only for a virtual machine that asked for it", async () => {
|
||||||
|
await adapter().createSnapshot("pve1", "qemu", 100, { name: "before-upgrade", description: " before the upgrade ", includeRam: true });
|
||||||
|
assert.equal(seen[0].method, "POST");
|
||||||
|
assert.equal(seen[0].path, "/api2/json/nodes/pve1/qemu/100/snapshot");
|
||||||
|
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "before-upgrade", description: "before the upgrade", vmstate: "1" });
|
||||||
|
seen = [];
|
||||||
|
await adapter().createSnapshot("pve1", "qemu", 100, { name: "plain" });
|
||||||
|
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "plain" });
|
||||||
|
seen = [];
|
||||||
|
await adapter().createSnapshot("pve1", "lxc", 200, { name: "ct", includeRam: true, description: " " });
|
||||||
|
assert.deepEqual(Object.fromEntries(new URLSearchParams(seen[0].body)), { snapname: "ct" }, "a container has no memory to keep, and a blank description is none");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("with no time to wait it answers with the task and says it has not finished; with time it follows it to the end", async () => {
|
||||||
|
task = { runningFirst: 2, exit: "OK" };
|
||||||
|
const quick = await adapter().createSnapshot("pve1", "qemu", 100, { name: "a" });
|
||||||
|
assert.deepEqual([quick.done, quick.ok, quick.upid], [false, null, UPID]);
|
||||||
|
polls = 0;
|
||||||
|
const waited = await adapter().createSnapshot("pve1", "qemu", 100, { name: "b" }, 5000);
|
||||||
|
assert.deepEqual([waited.done, waited.ok, waited.message], [true, true, "OK"]);
|
||||||
|
assert.ok(polls >= 3, "it asked more than once");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a task that ends badly says what Proxmox said; one that never ends is left running when the wait is over", async () => {
|
||||||
|
task = { runningFirst: 0, exit: "snapshot feature is not available" };
|
||||||
|
const bad = await adapter().createSnapshot("pve1", "qemu", 100, { name: "c" }, 2000);
|
||||||
|
assert.deepEqual([bad.done, bad.ok, bad.message], [true, false, "snapshot feature is not available"]);
|
||||||
|
task = { runningFirst: 0, exit: null };
|
||||||
|
const slow = await adapter().createSnapshot("pve1", "qemu", 100, { name: "d" }, 150);
|
||||||
|
assert.deepEqual([slow.done, slow.ok], [false, null]);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("rolling back and deleting", () => {
|
||||||
|
test("a rollback is a POST to the snapshot's rollback, a deletion a DELETE of it, each followed as a task", async () => {
|
||||||
|
const back = await adapter().rollbackSnapshot("pve1", "lxc", 200, "before-upgrade", 2000);
|
||||||
|
const gone = await adapter().deleteSnapshot("pve1", "lxc", 200, "before-upgrade", 2000);
|
||||||
|
assert.deepEqual([back.ok, gone.ok], [true, true]);
|
||||||
|
const calls = seen.filter((s) => !/\/tasks\//.test(s.path)).map((s) => [s.method, s.path]);
|
||||||
|
assert.deepEqual(calls, [["POST", "/api2/json/nodes/pve1/lxc/200/snapshot/before-upgrade/rollback"], ["DELETE", "/api2/json/nodes/pve1/lxc/200/snapshot/before-upgrade"]]);
|
||||||
|
assert.ok(seen.some((s) => s.path.includes("/tasks/UPID%3Apve1") && s.path.endsWith("/status")), "and the task was asked after");
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("what is refused before Proxmox is asked", () => {
|
||||||
|
test("a snapshot name that Proxmox would not take, or that is a path, never goes out", async () => {
|
||||||
|
for (const bad of ["1starts-with-digit", "../../x", "a b", "a/b", "", "x".repeat(41), "name?x=1", "%2e%2e", "-dash"]) {
|
||||||
|
await assert.rejects(() => adapter().createSnapshot("pve1", "qemu", 100, { name: bad }), /snapshot name/, JSON.stringify(bad));
|
||||||
|
await assert.rejects(() => adapter().rollbackSnapshot("pve1", "qemu", 100, bad), /snapshot name/);
|
||||||
|
await assert.rejects(() => adapter().deleteSnapshot("pve1", "qemu", 100, bad), /snapshot name/);
|
||||||
|
}
|
||||||
|
assert.deepEqual(seen, []);
|
||||||
|
for (const ok of ["a", "Before_upgrade-2", "x".repeat(40)]) assert.match(ok, ID_PATTERNS.proxmoxSnapshot);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a node, a guest type and a number are checked as for the power actions; an answer with no task is an error", async () => {
|
||||||
|
await assert.rejects(() => adapter().listSnapshots("../etc", "qemu", 1), /node name/);
|
||||||
|
await assert.rejects(() => adapter().listSnapshots("pve1", "vm" as never, 1), /guest type/);
|
||||||
|
await assert.rejects(() => adapter().listSnapshots("pve1", "qemu", 1.5), /VM ID/);
|
||||||
|
assert.deepEqual(seen, []);
|
||||||
|
badUpid = true;
|
||||||
|
await assert.rejects(() => adapter().createSnapshot("pve1", "qemu", 100, { name: "z" }), /did not say which task/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("an error from Proxmox is the error: what it said", async () => {
|
||||||
|
apiFailure = 403;
|
||||||
|
await assert.rejects(() => adapter().listSnapshots("pve1", "qemu", 100), /snapname|no good/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("how the page indents them", () => {
|
||||||
|
const snap = (name: string, parent: string | null) => ({ name, parent });
|
||||||
|
test("a chain, each taken after the one before, is all at the left edge", () => {
|
||||||
|
assert.deepEqual(snapshotDepths([snap("a", null), snap("b", "a"), snap("c", "b")]), { a: 0, b: 0, c: 0 });
|
||||||
|
});
|
||||||
|
test("a branch — two taken after the same one — is indented, and what follows it with it", () => {
|
||||||
|
const d = snapshotDepths([snap("a", null), snap("b", "a"), snap("c", "a"), snap("d", "c")]);
|
||||||
|
assert.deepEqual(d, { a: 0, b: 1, c: 1, d: 1 });
|
||||||
|
});
|
||||||
|
test("a parent that is not in the list is the top, and a loop cannot hang it", () => {
|
||||||
|
assert.deepEqual(snapshotDepths([snap("x", "gone")]), { x: 0 });
|
||||||
|
assert.deepEqual(snapshotDepths([snap("a", "b"), snap("b", "a")]), { a: 0, b: 0 });
|
||||||
|
assert.deepEqual(snapshotDepths([]), {});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("through the routes", () => {
|
||||||
|
let app: Server;
|
||||||
|
let base = "";
|
||||||
|
let who = "operator";
|
||||||
|
let id = 0;
|
||||||
|
const call = (method: string, path: string, body?: unknown) =>
|
||||||
|
fetch(`${base}/${id}/proxmox/nodes/pve1/qemu/100/snapshots${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
|
||||||
|
const audits = async (action: string) => (await db.select().from(auditLog)).filter((e) => e.action === action);
|
||||||
|
|
||||||
|
before(async () => {
|
||||||
|
await db.insert(users).values([
|
||||||
|
{ oidcSub: "admin", name: "Ada", role: "admin" },
|
||||||
|
{ oidcSub: "operator", name: "Olle", role: "operator" },
|
||||||
|
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
|
||||||
|
]);
|
||||||
|
id = (await db.insert(integrations).values({ type: "proxmox", name: "pve", baseUrl: pveUrl, config: JSON.stringify({ url: pveUrl, tokenId: "root@pam!lab", tokenSecret: "s3cret", insecure: true }) }).returning({ id: integrations.id }))[0].id;
|
||||||
|
const a = express();
|
||||||
|
a.use(express.json());
|
||||||
|
a.use((req, _res, next) => {
|
||||||
|
(req as unknown as { session: unknown }).session = { user: { sub: who } };
|
||||||
|
next();
|
||||||
|
});
|
||||||
|
a.use("/api/integrations", integrationsRouter);
|
||||||
|
app = await new Promise<Server>((resolve) => {
|
||||||
|
const s = a.listen(0, "127.0.0.1", () => resolve(s));
|
||||||
|
});
|
||||||
|
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/integrations`;
|
||||||
|
});
|
||||||
|
after(() => {
|
||||||
|
app.close();
|
||||||
|
try {
|
||||||
|
rmSync(dir, { recursive: true, force: true });
|
||||||
|
} catch {
|
||||||
|
// Windows keeps the database file locked until the process exits.
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test("anyone signed in can list; the list is what the adapter read", async () => {
|
||||||
|
who = "viewer";
|
||||||
|
listAnswer = [{ name: "one", snaptime: 1_760_000_000 }];
|
||||||
|
const res = await call("GET", "");
|
||||||
|
assert.equal(res.status, 200);
|
||||||
|
assert.deepEqual(((await res.json()) as { snapshots: { name: string }[] }).snapshots.map((s) => s.name), ["one"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("an operator takes one: it is named from the time when no name is given, checked when it is, done, and written down; a viewer may not", async () => {
|
||||||
|
who = "viewer";
|
||||||
|
assert.equal((await call("POST", "", {})).status, 403);
|
||||||
|
assert.deepEqual(seen, []);
|
||||||
|
who = "operator";
|
||||||
|
const res = await call("POST", "", { description: "before the upgrade", includeRam: true });
|
||||||
|
assert.equal(res.status, 200);
|
||||||
|
const body = (await res.json()) as { snapshot: string; done: boolean; ok: boolean };
|
||||||
|
assert.match(body.snapshot, /^hlm-\d{8}-\d{6}$/);
|
||||||
|
assert.deepEqual([body.done, body.ok], [true, true]);
|
||||||
|
assert.equal(new URLSearchParams(seen.find((s) => s.method === "POST" && s.path.endsWith("/snapshot"))!.body).get("snapname"), body.snapshot);
|
||||||
|
const [entry] = await audits("create_snapshot");
|
||||||
|
const detail = JSON.parse(entry.detail ?? "{}");
|
||||||
|
assert.deepEqual([entry.category, entry.targetType, entry.targetId, detail.snapshot, detail.vmid, detail.node, detail.withRam, detail.ok], ["integration", "proxmox_guest", "100", body.snapshot, 100, "pve1", true, true]);
|
||||||
|
assert.match(autoSnapshotName(new Date("2026-11-10T12:34:56Z")), /^hlm-20261110-123456$/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a name that is not one is refused with why, and a description that is too long; nothing is asked of Proxmox", async () => {
|
||||||
|
who = "operator";
|
||||||
|
seen = [];
|
||||||
|
const name = await call("POST", "", { name: "1bad" });
|
||||||
|
assert.equal(name.status, 400);
|
||||||
|
assert.match(((await name.json()) as { message: string }).message, /starts with a letter/);
|
||||||
|
assert.equal((await call("POST", "", { description: "x".repeat(201) })).status, 400);
|
||||||
|
assert.deepEqual(seen, []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a task that is slow is said to be still going; one that fails is an error with what Proxmox said", async () => {
|
||||||
|
who = "operator";
|
||||||
|
task = { runningFirst: 0, exit: null };
|
||||||
|
const slow = (await (await call("POST", "", { name: "slow" })).json()) as { done: boolean; ok: boolean | null; upid: string };
|
||||||
|
assert.deepEqual([slow.done, slow.ok, slow.upid], [false, null, UPID]);
|
||||||
|
task = { runningFirst: 0, exit: "VM is locked (backup)" };
|
||||||
|
const failed = await call("POST", "", { name: "locked" });
|
||||||
|
assert.equal(failed.status, 502);
|
||||||
|
assert.match(((await failed.json()) as { error: string }).error, /Proxmox: VM is locked \(backup\)/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("rolling back and deleting are an administrator's, each checked, done and written down", async () => {
|
||||||
|
who = "operator";
|
||||||
|
assert.equal((await call("POST", "/before-upgrade/rollback")).status, 403);
|
||||||
|
assert.equal((await call("DELETE", "/before-upgrade")).status, 403);
|
||||||
|
who = "admin";
|
||||||
|
seen = [];
|
||||||
|
assert.equal((await call("POST", "/1bad/rollback")).status, 400);
|
||||||
|
assert.equal((await call("DELETE", "/..%2Fx")).status, 400);
|
||||||
|
assert.deepEqual(seen, [], "nothing was asked of Proxmox");
|
||||||
|
assert.equal((await call("POST", "/before-upgrade/rollback")).status, 200);
|
||||||
|
assert.equal((await call("DELETE", "/before-upgrade")).status, 200);
|
||||||
|
assert.equal((await audits("rollback_snapshot")).length, 1);
|
||||||
|
assert.equal(JSON.parse((await audits("delete_snapshot"))[0].detail ?? "{}").snapshot, "before-upgrade");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a guest that is not one, and an integration of another kind, are refused", async () => {
|
||||||
|
who = "admin";
|
||||||
|
seen = [];
|
||||||
|
for (const path of ["/nodes/..%2Fx/qemu/100/snapshots", "/nodes/pve1/vm/100/snapshots", "/nodes/pve1/qemu/abc/snapshots", "/nodes/pve1/qemu/0/snapshots"]) {
|
||||||
|
const res = await fetch(`${base}/${id}/proxmox${path}`);
|
||||||
|
assert.equal(res.status, 400, path);
|
||||||
|
}
|
||||||
|
assert.deepEqual(seen, []);
|
||||||
|
const other = (await db.insert(integrations).values({ type: "gitea", name: "g", baseUrl: "http://g", config: JSON.stringify({}) }).returning({ id: integrations.id }))[0].id;
|
||||||
|
assert.equal((await fetch(`${base}/${other}/proxmox/nodes/pve1/qemu/100/snapshots`)).status, 400);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the change log says what happened in words, and the maintenance key is not involved", async () => {
|
||||||
|
const { describeChange } = await import("../src/services/changeLog.js");
|
||||||
|
const sentence = (action: string) => describeChange("integration", action, { vmid: 100, node: "pve1", snapshot: "s1", withRam: true });
|
||||||
|
assert.equal(sentence("create_snapshot").title, "A snapshot was taken of guest 100 on pve1");
|
||||||
|
assert.match(sentence("create_snapshot").detail ?? "", /s1 \(with memory\)/);
|
||||||
|
assert.equal(sentence("rollback_snapshot").title, "Guest 100 on pve1 was rolled back to a snapshot");
|
||||||
|
assert.equal(sentence("delete_snapshot").title, "A snapshot was deleted from guest 100 on pve1");
|
||||||
|
assert.equal(subjectOfConditionKey("not-a-snapshot-key"), null);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -3524,6 +3524,25 @@ export interface ProxmoxGuest {
|
|||||||
uptime: number | null;
|
uptime: number | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** One snapshot of a Proxmox guest. */
|
||||||
|
export interface ProxmoxSnapshot {
|
||||||
|
name: string;
|
||||||
|
description: string;
|
||||||
|
takenAt: string | null;
|
||||||
|
/** A VM's snapshot that kept its memory. */
|
||||||
|
withRam: boolean;
|
||||||
|
/** The snapshot it was taken after. */
|
||||||
|
parent: string | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** How a snapshot task went: done and worked, still going (done false), or an error (the request fails with what Proxmox said). */
|
||||||
|
export interface ProxmoxSnapshotResult {
|
||||||
|
snapshot: string;
|
||||||
|
done: boolean;
|
||||||
|
ok: boolean | null;
|
||||||
|
upid: string;
|
||||||
|
}
|
||||||
|
|
||||||
export interface ProxmoxGuestsResponse {
|
export interface ProxmoxGuestsResponse {
|
||||||
guests: ProxmoxGuest[];
|
guests: ProxmoxGuest[];
|
||||||
summary: { total: number; running: number };
|
summary: { total: number; running: number };
|
||||||
@@ -4447,6 +4466,14 @@ export const api = {
|
|||||||
request<void>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/restart`, { method: "POST" }),
|
request<void>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/restart`, { method: "POST" }),
|
||||||
shutdown: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number) =>
|
shutdown: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number) =>
|
||||||
request<void>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/shutdown`, { method: "POST" }),
|
request<void>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/shutdown`, { method: "POST" }),
|
||||||
|
snapshots: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number) =>
|
||||||
|
request<{ snapshots: ProxmoxSnapshot[] }>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/snapshots`),
|
||||||
|
createSnapshot: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number, body: { name?: string; description?: string; includeRam?: boolean }) =>
|
||||||
|
request<ProxmoxSnapshotResult>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/snapshots`, { method: "POST", body: JSON.stringify(body) }),
|
||||||
|
rollbackSnapshot: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number, name: string) =>
|
||||||
|
request<ProxmoxSnapshotResult>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/snapshots/${encodeURIComponent(name)}/rollback`, { method: "POST" }),
|
||||||
|
deleteSnapshot: (integrationId: number, node: string, type: ProxmoxGuestType, vmid: number, name: string) =>
|
||||||
|
request<ProxmoxSnapshotResult>(`/api/integrations/${integrationId}/proxmox/nodes/${node}/${type}/${vmid}/snapshots/${encodeURIComponent(name)}`, { method: "DELETE" }),
|
||||||
},
|
},
|
||||||
synology: {
|
synology: {
|
||||||
storage: (integrationId: number) => request<SynologyStorageResponse>(`/api/integrations/${integrationId}/synology/storage`),
|
storage: (integrationId: number) => request<SynologyStorageResponse>(`/api/integrations/${integrationId}/synology/storage`),
|
||||||
|
|||||||
@@ -0,0 +1,157 @@
|
|||||||
|
import { useCallback, useEffect, useRef, useState } from "react";
|
||||||
|
import { api, type ProxmoxGuest, type ProxmoxSnapshot, type ProxmoxSnapshotResult } from "../api/client";
|
||||||
|
import { confirmDialog } from "../utils/dialogs";
|
||||||
|
import { readableError } from "../utils/errors";
|
||||||
|
import { toast } from "../utils/toast";
|
||||||
|
import { snapshotDepths } from "../utils/proxmoxSnapshots";
|
||||||
|
import { ErrorNotice } from "./Notice";
|
||||||
|
import TimeAgo from "./TimeAgo";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The snapshots of one guest: what there is (in the order they were taken, each indented under the one it was taken after), a way to take one (an operator's), and to roll back to one or
|
||||||
|
* delete one (an administrator's, because a rollback throws away everything the guest has done since). Proxmox does each as a task: the answer says how it went, or that it is still going, and the list
|
||||||
|
* is looked at again a little later.
|
||||||
|
*/
|
||||||
|
export default function ProxmoxSnapshots({ integrationId, guest, canTake, canRoll }: { integrationId: number; guest: ProxmoxGuest; canTake: boolean; canRoll: boolean }) {
|
||||||
|
const [snapshots, setSnapshots] = useState<ProxmoxSnapshot[] | null>(null);
|
||||||
|
const [error, setError] = useState<string | null>(null);
|
||||||
|
const [name, setName] = useState("");
|
||||||
|
const [description, setDescription] = useState("");
|
||||||
|
const [includeRam, setIncludeRam] = useState(false);
|
||||||
|
const [busy, setBusy] = useState<string | null>(null);
|
||||||
|
const timers = useRef<number[]>([]);
|
||||||
|
const key = `${guest.node}:${guest.type}:${guest.vmid}`;
|
||||||
|
const kind = guest.type === "qemu" ? "VM" : "container";
|
||||||
|
|
||||||
|
const load = useCallback(() => {
|
||||||
|
api.integrations.proxmox
|
||||||
|
.snapshots(integrationId, guest.node, guest.type, guest.vmid)
|
||||||
|
.then((res) => {
|
||||||
|
setSnapshots(res.snapshots);
|
||||||
|
setError(null);
|
||||||
|
})
|
||||||
|
.catch((err) => setError(readableError(err)));
|
||||||
|
}, [integrationId, guest.node, guest.type, guest.vmid]);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
setSnapshots(null);
|
||||||
|
load();
|
||||||
|
const pending = timers.current;
|
||||||
|
return () => pending.forEach((t) => window.clearTimeout(t));
|
||||||
|
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||||
|
}, [key, integrationId]);
|
||||||
|
|
||||||
|
/** What was done, in words; a task Proxmox is still working on is looked at again in a few seconds, twice. */
|
||||||
|
function report(done: string, result: ProxmoxSnapshotResult) {
|
||||||
|
if (result.done) toast.success(done);
|
||||||
|
else {
|
||||||
|
toast.info("Proxmox is still working on it — the list is looked at again in a moment.");
|
||||||
|
timers.current.push(window.setTimeout(load, 4000), window.setTimeout(load, 12000));
|
||||||
|
}
|
||||||
|
load();
|
||||||
|
}
|
||||||
|
|
||||||
|
async function run(what: string, job: () => Promise<ProxmoxSnapshotResult>, done: string) {
|
||||||
|
setBusy(what);
|
||||||
|
try {
|
||||||
|
report(done, await job());
|
||||||
|
} catch (err) {
|
||||||
|
toast.error(readableError(err));
|
||||||
|
} finally {
|
||||||
|
setBusy(null);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function take(e: React.FormEvent) {
|
||||||
|
e.preventDefault();
|
||||||
|
await run("take", () => api.integrations.proxmox.createSnapshot(integrationId, guest.node, guest.type, guest.vmid, { name: name.trim() || undefined, description: description.trim() || undefined, includeRam: includeRam && guest.type === "qemu" && guest.status === "running" }), "Snapshot taken.");
|
||||||
|
setName("");
|
||||||
|
setDescription("");
|
||||||
|
}
|
||||||
|
|
||||||
|
async function rollBack(s: ProxmoxSnapshot) {
|
||||||
|
const ok = await confirmDialog({
|
||||||
|
title: `Roll back ${guest.name}`,
|
||||||
|
message: `Roll back ${kind} "${guest.name}" to "${s.name}"? Everything it has done since ${s.takenAt ? new Date(s.takenAt).toLocaleString() : "then"} is lost${s.withRam ? "" : guest.type === "qemu" ? ", and it comes back stopped (this snapshot kept no memory)" : ""}. Snapshots taken after "${s.name}" are removed by Proxmox.`,
|
||||||
|
confirmLabel: "Roll back",
|
||||||
|
danger: true,
|
||||||
|
});
|
||||||
|
if (ok) await run(`roll:${s.name}`, () => api.integrations.proxmox.rollbackSnapshot(integrationId, guest.node, guest.type, guest.vmid, s.name), `Rolled ${guest.name} back to ${s.name}.`);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function remove(s: ProxmoxSnapshot) {
|
||||||
|
const ok = await confirmDialog({ title: "Delete a snapshot", message: `Delete the snapshot "${s.name}" of ${kind} "${guest.name}"? The guest itself is not touched, but you can no longer roll back to it.`, confirmLabel: "Delete", danger: true });
|
||||||
|
if (ok) await run(`del:${s.name}`, () => api.integrations.proxmox.deleteSnapshot(integrationId, guest.node, guest.type, guest.vmid, s.name), `Deleted ${s.name}.`);
|
||||||
|
}
|
||||||
|
|
||||||
|
const depths = snapshots ? snapshotDepths(snapshots) : {};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className="mt-4">
|
||||||
|
<h4>Snapshots</h4>
|
||||||
|
<ErrorNotice error={error} />
|
||||||
|
{canTake && (
|
||||||
|
<form className="row g-2 mb-3" onSubmit={(e) => void take(e)}>
|
||||||
|
<div className="col-sm-5">
|
||||||
|
<input className="form-control form-control-sm" aria-label="Snapshot name" placeholder="Name (leave empty for one from the time)" maxLength={40} pattern="[A-Za-z][A-Za-z0-9_\-]{0,39}" title="Starts with a letter, then letters, digits, - and _" value={name} onChange={(e) => setName(e.target.value)} />
|
||||||
|
</div>
|
||||||
|
<div className="col-sm-7">
|
||||||
|
<input className="form-control form-control-sm" aria-label="Description" placeholder="Why (optional)" maxLength={200} value={description} onChange={(e) => setDescription(e.target.value)} />
|
||||||
|
</div>
|
||||||
|
<div className="col-12 d-flex flex-wrap align-items-center gap-3">
|
||||||
|
{guest.type === "qemu" && guest.status === "running" && (
|
||||||
|
<label className="form-check mb-0">
|
||||||
|
<input type="checkbox" className="form-check-input" checked={includeRam} onChange={(e) => setIncludeRam(e.target.checked)} />
|
||||||
|
<span className="form-check-label">Keep its memory too (a rollback then brings it back running)</span>
|
||||||
|
</label>
|
||||||
|
)}
|
||||||
|
<button className="btn btn-sm btn-primary ms-auto" disabled={busy !== null}>
|
||||||
|
{busy === "take" ? "Taking it…" : "Take a snapshot"}
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</form>
|
||||||
|
)}
|
||||||
|
{snapshots === null && !error && <div className="text-secondary small">Reading them…</div>}
|
||||||
|
{snapshots?.length === 0 && <div className="text-secondary small">None has been taken.</div>}
|
||||||
|
{snapshots && snapshots.length > 0 && (
|
||||||
|
<div className="table-responsive">
|
||||||
|
<table className="table table-sm table-vcenter mb-0">
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Snapshot</th>
|
||||||
|
<th>Taken</th>
|
||||||
|
{canRoll && <th className="w-1" />}
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
{snapshots.map((s) => (
|
||||||
|
<tr key={s.name}>
|
||||||
|
<td>
|
||||||
|
<div style={{ paddingLeft: `${(depths[s.name] ?? 0) * 1}rem` }}>
|
||||||
|
<strong>{s.name}</strong> {s.withRam && <span className="badge bg-blue-lt text-blue">with memory</span>}
|
||||||
|
{s.description && <div className="text-secondary small text-break">{s.description}</div>}
|
||||||
|
</div>
|
||||||
|
</td>
|
||||||
|
<td className="text-nowrap">{s.takenAt ? <TimeAgo value={s.takenAt} /> : "—"}</td>
|
||||||
|
{canRoll && (
|
||||||
|
<td>
|
||||||
|
<div className="btn-list flex-nowrap">
|
||||||
|
<button className="btn btn-sm" disabled={busy !== null} onClick={() => void rollBack(s)}>
|
||||||
|
Roll back…
|
||||||
|
</button>
|
||||||
|
<button className="btn btn-sm btn-outline-danger" disabled={busy !== null} onClick={() => void remove(s)}>
|
||||||
|
Delete…
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</td>
|
||||||
|
)}
|
||||||
|
</tr>
|
||||||
|
))}
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
<div className="text-secondary small mt-2">Proxmox does each of these as a task and can take a while on a large disk. Rolling back needs an administrator.</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -28,6 +28,7 @@ import { useRowDetail } from "../hooks/useRowDetail";
|
|||||||
import { formatDateTime } from "../utils/date";
|
import { formatDateTime } from "../utils/date";
|
||||||
import ExportTableButton from "../components/ExportTableButton";
|
import ExportTableButton from "../components/ExportTableButton";
|
||||||
import { EmptyRow } from "../components/EmptyState";
|
import { EmptyRow } from "../components/EmptyState";
|
||||||
|
import ProxmoxSnapshots from "../components/ProxmoxSnapshots";
|
||||||
|
|
||||||
function proxmoxStatusBadge(status: string) {
|
function proxmoxStatusBadge(status: string) {
|
||||||
return status === "running" ? (
|
return status === "running" ? (
|
||||||
@@ -609,6 +610,7 @@ export default function Proxmox({ user }: { user: CurrentUser }) {
|
|||||||
{detail.selected && (
|
{detail.selected && (
|
||||||
<DetailDrawer title={((g) => g.name)(detail.selected)} subtitle={((g) => `${g.type === "qemu" ? "Virtual machine" : "Container"} ${g.vmid} on ${g.node}`)(detail.selected)} onClose={detail.close}>
|
<DetailDrawer title={((g) => g.name)(detail.selected)} subtitle={((g) => `${g.type === "qemu" ? "Virtual machine" : "Container"} ${g.vmid} on ${g.node}`)(detail.selected)} onClose={detail.close}>
|
||||||
<ObjectDetails data={detail.selected} />
|
<ObjectDetails data={detail.selected} />
|
||||||
|
{selectedId !== null && <ProxmoxSnapshots integrationId={selectedId} guest={detail.selected} canTake={canEdit} canRoll={user.role === "admin"} />}
|
||||||
</DetailDrawer>
|
</DetailDrawer>
|
||||||
)}
|
)}
|
||||||
</>
|
</>
|
||||||
|
|||||||
@@ -0,0 +1,25 @@
|
|||||||
|
import type { ProxmoxSnapshot } from "../api/client";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* How far in each snapshot is drawn: a chain of snapshots, each taken after the one before, is all at the left edge, and only a branch (several taken after the same one) is indented, one step for each
|
||||||
|
* branch it is down. A parent that is not in the list counts as the top. Pure.
|
||||||
|
*/
|
||||||
|
export function snapshotDepths(snapshots: Pick<ProxmoxSnapshot, "name" | "parent">[]): Record<string, number> {
|
||||||
|
const known = new Set(snapshots.map((s) => s.name));
|
||||||
|
const children = new Map<string, number>();
|
||||||
|
for (const s of snapshots) if (s.parent !== null && known.has(s.parent)) children.set(s.parent, (children.get(s.parent) ?? 0) + 1);
|
||||||
|
const parentOf = new Map(snapshots.map((s) => [s.name, s.parent !== null && known.has(s.parent) ? s.parent : null]));
|
||||||
|
const depth: Record<string, number> = {};
|
||||||
|
for (const s of snapshots) {
|
||||||
|
let d = 0;
|
||||||
|
let at: string = s.name;
|
||||||
|
const seen = new Set<string>([at]);
|
||||||
|
for (let parent = parentOf.get(at) ?? null; parent !== null && !seen.has(parent); parent = parentOf.get(at) ?? null) {
|
||||||
|
if ((children.get(parent) ?? 0) > 1) d++;
|
||||||
|
seen.add(parent);
|
||||||
|
at = parent;
|
||||||
|
}
|
||||||
|
depth[s.name] = d;
|
||||||
|
}
|
||||||
|
return depth;
|
||||||
|
}
|
||||||
Reference in new issue
Block a user