PVE-Backup-Report/docs/en/rapport-pdf.md

PDF Report

Version francaise

Objective

The PDF must be readable by an operations team and usable as follow-up evidence during an audit.

It must prioritize clarity, generation date, backup coverage and exceptions.

Current state: PDF generation is implemented with WeasyPrint from an HTML/CSS template. The previous reportlab renderer remains present in the repository as a technical reference, but --generate-pdf uses the WeasyPrint renderer.

The WeasyPrint report language is configurable with REPORT_LANGUAGE=fr or REPORT_LANGUAGE=en. The default value remains fr.

Current WeasyPrint rendering state:

• Complete cover page (break-after page): logo bar on a white background at the top, main title in blue #1f4e79 32pt centered, metadata bar (Generation, Version) anchored at the bottom through a flex spacer.
• Footer present on every page including the cover page: document label on the left, generation date in the center, version on the right, separated from content by a horizontal line.
• Page headers except on the first page: report title on the left, page number over total on the right.
• Table of contents with automatic page numbers (CSS target-counter) and visual hierarchy: group titles in bold blue, indented subsections.
• SVG icons before each section title (bar chart, server, cylinder, clock, gear, warning triangle, shield, archive, cross, grey circle with question mark for unspecified namespace) to identify each part quickly.
• Section headers with blue left border and very light grey background to distinguish titles from content.
• Summary section displayed as KPI cards (7 columns over 2 lines) instead of a table; "Not backed up" and "Anomalies" indicators appear in orange when greater than zero.
• Tables with dark headers, alternating rows, and CSS classes applied to cells by value: green for "Active" and "Success", red/bold for "Inactive" and "Failure", amber for "Undetermined", grey italic for "not specified".
• Warning messages (PBS GC running) and empty messages visually distinct from tables.
• The report remains readable in black-and-white printing: styling relies on bold, italic and left border in addition to color.

The final report data model can be previewed with:

PYTHONPATH=src python3 -m pve_backup_report --dump-report-data

This command produces JSON containing the computed summary, PBS storages, backup jobs, VM/CT coverage and anomalies.

Raw sensitive fields are filtered from this output, but --dump-report-data remains a technical audit output: it contains VM/CT names, VMIDs, PVE notes, servers, datastores, namespaces, PBS users and infrastructure metadata. Treat it as internal data.

PDF generation:

PYTHONPATH=src python3 -m pve_backup_report --generate-pdf

The file is written to REPORT_OUTPUT_DIR with a timestamped name. An existing report is never overwritten.

Filename

Recommended format:

rapport-sauvegardes-pve-YYYY-MM-DD-HHMMSS.pdf

Example:

rapport-sauvegardes-pve-2026-05-07-020000.pdf

The script must refuse to overwrite an existing file or generate a unique alternative name.

Report Structure

Cover Page

Implemented structure (full page, break-after page):

1. Logo bar: Proxmox VE logo (base64 PNG) on a white background, separated by a grey line at the bottom.
2. Title area: {{ title }} in blue #1f4e79 32pt centered, on a white background.
3. Spacer: div with flex: 1 absorbing empty space and pushing the metadata panel to the bottom.
4. Metadata bar: light grey background with blue top border, two centered items - Generation ({{ generated_at }}) and Version ({{ version }}) - separated by a vertical line.

Table of Contents

The table of contents is placed after the cover page. It is automatically fed from report section titles to make navigation in the PDF easier.

Executive Summary

Minimum indicators:

• total VM count;
• total CT count;
• number of VM/CT with a planned backup;
• number of VM/CT without planned backup;
• number of undetermined VM/CT;
• number of PBS storages;
• number of anomalies.

The summary computed in ReportSummary also contains:

• number of active jobs;
• number of inactive jobs;
• number of backups to non-PBS storage;
• number of backups to disabled PBS storage;

PBS Storages Declared in PVE

Expected table:

ID	Username	PBS server	Datastore	Namespace	Enabled

Secrets must never appear. The Enabled column displays yes when the PBS storage is active in PVE. If the PVE disable field is absent, the storage is considered active; disable=1 is displayed as no.

PBS Users - Access Audit

This table is placed immediately after PBS storages declared in PVE.

Expected table:

PBS server	Auth-id	PVE storage	Datastore	Namespace	Enabled	Expiration	Email	Permissions	Comment

Data comes from PVE PBS storage username values, matched with users and effective permissions exposed by configured PBS servers.

If the PVE auth-id is a token of type user@realm!token, the Auth-id column keeps the full value and user metadata is matched with user@realm.

Secrets must never appear. Displayed permissions are only effective active privileges on the target datastore/namespace.

PBS Storage Usage

Expected table:

PBS server	Datastore	Total space	Used space	Free space

Values come from the status of datastores on each configured PBS. Sizes are displayed in readable units (Kio, Mio, Gio, Tio).

VM/CT Backups by Namespace

Backup tables are grouped under a level 1 title VM/CT backups.

VM/CT are displayed in multiple tables, one table per namespace. The title of each table indicates the relevant namespace.

Expected columns:

VMID	Name	Notes	Type	Node	VM state	Backup	PBS server	Storage	Mode	Backup schedule	Last backup

The Notes column contains notes set on the VM or CT in PVE. If no note is set or if it cannot be collected, the displayed value is not specified.

The Backup column displays Active when an active PBS backup is planned, otherwise Inactive.

The Backup schedule column contains the schedules of associated backup jobs, i.e. the value displayed in the Schedule column of the Backup jobs table.

The PBS server column is inferred from the associated PBS storage when known. If PBS_HOSTNAMES contains a mapping, rendering is IP (host-name).

Namespace is not displayed as a column in these tables because it is already carried by the table title.

Tables are sorted alphabetically by namespace, then rows are sorted alphabetically by Backup schedule. VMID is no longer the primary sort criterion.

The Mode column translates the technical PVE job mode:

• snapshot becomes No interruption expected;
• suspend becomes Temporary suspension;
• stop becomes Stopped during backup.

The Last backup column displays state Success, Failure or Undetermined, followed by date, end time and duration of the latest known vzdump task for the VM/CT when this duration is available.

For multi-VM/CT jobs, this information is inferred from the vzdump task log, not only from the global job task.

The value not specified is expected if no completed vzdump task is available in accessible PVE history, for example for a VM/CT recently added to a job before its first effective backup.

Rows without backup must be visually identifiable.

Undetermined rows must be distinct from non-backed-up rows.

VM/CT Backup Retention by PBS and Namespace

Retention tables are grouped under a level 1 title VM/CT backup retention.

Retention data is displayed in multiple tables, split by PBS server then namespace. Each table title indicates the PBS and relevant namespace.

Expected columns:

VMID	VM/CT name	Datastore	PVE state	Version count	Expected version count	Delta	Oldest	Newest	Size

The Datastore column distinguishes two backups in the same namespace on the same PBS but stored in different datastores. The Version count, Oldest, Newest and Size columns are populated from the relevant PBS through the snapshot list for the datastore and namespace. The Expected version count column is computed from the active retention policy matching the same PBS server, datastore and namespace, by summing configured keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly and keep-yearly values. The Delta column displays Version count - Expected version count with a + or - sign except when the delta is zero. If no matching active policy is found, Expected version count and Delta display not specified. The Size column is the size of the newest backup visible on the relevant PBS. The PVE state column indicates whether the VM/CT still exists in the PVE inventory (Active on PVE) or no longer exists (Not active on PVE).

Each PBS server can have multiple tables:

• VM/CT backup retention <PBS server> - <namespace>.

Namespace is not displayed as a column in these tables because it is already carried by the table title.

If the garbage collector of the relevant PBS/datastore is running when the report is generated, a warning is displayed just below the relevant table title. This warning explains that the VM/CT backup version count may appear higher than the configured version count.

Each table lists only VM/CT for which at least one matching snapshot is visible on the relevant PBS. VM/CT still visible on PBS but absent from the PVE inventory remain displayed in the table and are marked Not active on PVE. Snapshots whose namespace does not exist in namespaces declared on PVE are excluded from these tables.

Retention tables are sorted by namespace, then by VM/CT name and VMID when information is available.

Retention Policy

The Retention policy table is populated from configured PBS servers when their *_API_URL, *_API_TOKEN_ID and *_API_TOKEN_SECRET variables are set.

Collection reads PBS prune jobs through /config/prune and displays:

• PBS server;
• datastore;
• namespace;
• schedule;
• active/inactive state;
• columns Last, Hourly, Daily, Weekly, Monthly, Yearly;
• max-depth.

A namespace missing in PBS is displayed as /, meaning the root namespace.

VM/CT Without Backup

This section must include only uncovered workloads.

It must be short and directly actionable.

Anomalies

This section lists collection or interpretation issues.

It can be empty, but must then indicate that no anomaly was detected.

Readability

The report must remain readable in black-and-white printing.

Do not rely only on color to indicate risk.

Use explicit labels:

• Planned backup;
• Not backed up;
• Undetermined.

Timestamp

All displayed dates must use the configured time zone.

The time zone must appear in the report.

Retention

The daily report must be kept in a persistent directory.

Retention policy for generated reports is separate from PBS retention policies and must be documented in operations if added.