olivier/PVE-Backup-Report
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add English documentation

Browse Source
This commit is contained in:
Olivier
2026-05-13 17:31:30 +02:00
parent f440a8e497
commit e77d73d6dc
14 changed files with 1351 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/rapport-pdf.md
+257
View File
@@ -0,0 +1,257 @@
# PDF Report
[Version francaise](../rapport-pdf.md)
## 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:
```sh
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:
```sh
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:
```text
rapport-sauvegardes-pve-YYYY-MM-DD-HHMMSS.pdf
```
Example:
```text
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.