228 lines
6.7 KiB
Markdown
228 lines
6.7 KiB
Markdown
# Proxmox VE API
|
|
|
|
[Version francaise](../fr/api-pve.md)
|
|
|
|
## Principles
|
|
|
|
The application must use the Proxmox VE REST API in read-only mode.
|
|
|
|
Current state: `pve_client.py` implements the reusable API connection and endpoint checks for `/nodes`, `/storage`, `/cluster` and the configured backup jobs endpoint.
|
|
|
|
Collection of PBS storages, backup jobs, VM/CT and pools is implemented. Coverage computation supports `vmid` values explicitly listed in active jobs, `all=1` jobs and `pool=<name>` jobs.
|
|
|
|
The base URL usually follows this format:
|
|
|
|
```text
|
|
https://<pve-host>:8006/api2/json
|
|
```
|
|
|
|
The script can query any available node in the cluster for global endpoints.
|
|
|
|
## Token Authentication
|
|
|
|
Recommended authentication uses the HTTP `Authorization` header.
|
|
|
|
Format:
|
|
|
|
```text
|
|
Authorization: PVEAPIToken=<token-id>=<token-secret>
|
|
```
|
|
|
|
The token secret must never be logged.
|
|
|
|
In `.env`, set:
|
|
|
|
```env
|
|
PVE_API_TOKEN_ID=backup-report@pve!report
|
|
PVE_API_TOKEN_SECRET=secret-provided-by-pve
|
|
```
|
|
|
|
## Useful Endpoints
|
|
|
|
Exact endpoints must be checked against the target PVE version during implementation.
|
|
|
|
Commonly useful endpoints:
|
|
|
|
| Need | Indicative endpoint |
|
|
| --- | --- |
|
|
| PVE version | `/version` |
|
|
| Cluster resources | `/cluster/resources` |
|
|
| Storage configuration | `/storage` |
|
|
| Cluster index | `/cluster` |
|
|
| Backup jobs | `/cluster/backup` |
|
|
| Pools | `/pools` and `/pools/{poolid}` |
|
|
| Recent backup tasks | `/cluster/tasks` and `/nodes/{node}/tasks` |
|
|
| QEMU VM configuration | `/nodes/{node}/qemu/{vmid}/config` |
|
|
| LXC container configuration | `/nodes/{node}/lxc/{vmid}/config` |
|
|
| Node status | `/nodes` |
|
|
|
|
The nominal value for backup jobs is:
|
|
|
|
```text
|
|
/cluster/backup
|
|
```
|
|
|
|
`PVE_BACKUP_JOBS_ENDPOINT` exists only as a technical override. The expected value remains `/cluster/backup`.
|
|
|
|
Observed privilege for backup jobs:
|
|
|
|
```text
|
|
Sys.Audit on /
|
|
```
|
|
|
|
If the token does not have this privilege, PVE typically returns `HTTP 403 - Permission check failed (/, Sys.Audit)`.
|
|
|
|
With separated-privilege tokens, seeing `PVEAuditor` in the UI is not always enough: check effective token permissions, not only parent user permissions.
|
|
|
|
Manual check:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m pve_backup_report --check-api
|
|
```
|
|
|
|
The command displays only status and returned item counts. It does not log the token secret.
|
|
|
|
Endpoints are tested independently. A failure on the backup jobs endpoint does not prevent displaying the result of `/nodes`, `/storage` and `/cluster`.
|
|
|
|
## PBS Storages
|
|
|
|
A PBS storage is usually identified by a type equivalent to `pbs`.
|
|
|
|
Expected fields to normalize:
|
|
|
|
- `storage` or equivalent ID;
|
|
- `type`;
|
|
- `server`;
|
|
- `datastore`;
|
|
- `namespace`;
|
|
- `username`.
|
|
|
|
Not all fields are necessarily present depending on version or configuration.
|
|
|
|
The report must display an explicit value such as `not specified` when a non-critical field is missing. For active state, PVE usually exposes `disable=1` when a storage is disabled and omits the field when it is active. Missing `disable` must therefore be interpreted as active.
|
|
|
|
Current diagnostic command:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m pve_backup_report --dump-inventory
|
|
```
|
|
|
|
It displays normalized PBS storages without showing secrets.
|
|
|
|
## VM and CT Resources
|
|
|
|
Inventory can be built from `/cluster/resources`.
|
|
|
|
Filter useful types:
|
|
|
|
- `qemu` for VMs;
|
|
- `lxc` for containers.
|
|
|
|
Useful fields:
|
|
|
|
- `vmid`;
|
|
- `name`;
|
|
- `type`;
|
|
- `node`;
|
|
- `status`.
|
|
|
|
VM/CT notes are collected from each guest configuration on its current node:
|
|
|
|
- QEMU VM: `/nodes/{node}/qemu/{vmid}/config`;
|
|
- LXC container: `/nodes/{node}/lxc/{vmid}/config`.
|
|
|
|
The expected field is `description`. If a VM/CT configuration is unavailable, collection continues, a `guests` anomaly is added, and the note is displayed as `not specified` in the report.
|
|
|
|
Diagnostic command:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m pve_backup_report --dump-coverage
|
|
```
|
|
|
|
Final model preview command:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 -m pve_backup_report --dump-report-data
|
|
```
|
|
|
|
## Latest Completed Backup
|
|
|
|
Latest backup state is inferred from recent PVE tasks retrieved through `/cluster/tasks` and `/nodes/{node}/tasks` without parameters, then locally filtered on type `vzdump`.
|
|
|
|
The number of tasks inspected locally is controlled by `PVE_TASK_HISTORY_LIMIT`.
|
|
The number of lines retrieved for each task log is controlled by `PVE_TASK_LOG_LIMIT`.
|
|
|
|
If task history is unavailable, report generation continues and an anomaly is added.
|
|
|
|
For jobs backing up multiple VM/CT, the per-VM/CT result is extracted from the task log through `/nodes/{node}/tasks/{upid}/log`.
|
|
|
|
Backup duration is primarily extracted from `Finished Backup of ... (HH:MM:SS)` lines, because this value corresponds to the specific VM/CT. As a fallback, for a simple task or a VM/CT explicitly started in the log, it can be computed from `starttime` and `endtime`.
|
|
|
|
The VMID is extracted from log lines `Starting Backup of ...`, `Finished Backup of ...` and `Backup of ... failed`. If the log is unavailable, the script falls back to fields `vmid`, `id`, `guest` or `upid`.
|
|
|
|
If a VM/CT has just been added to a job and has not yet had a completed backup in the available history, no latest backup result can be set.
|
|
|
|
## Backup Jobs
|
|
|
|
PVE backup jobs contain the information required to determine:
|
|
|
|
- whether the job is enabled or disabled;
|
|
- target storage;
|
|
- schedule;
|
|
- VM/CT selection;
|
|
- possible exclusions;
|
|
- backup mode.
|
|
|
|
The implementation must distinguish:
|
|
|
|
- active jobs;
|
|
- disabled jobs;
|
|
- jobs targeting PBS;
|
|
- jobs targeting another storage type.
|
|
|
|
Current state: jobs are normalized with ID, storage, schedule, enabled state, mode, raw selection and raw exclusions.
|
|
|
|
Coverage computation interprets explicit `vmid=...` lists, `all=1` jobs, `pool=<name>` jobs and simple exclusions.
|
|
|
|
If a job references a missing or uncollectable pool, the relevant coverage remains `indetermine`.
|
|
|
|
## Scheduling
|
|
|
|
PVE can express schedules using calendar syntax.
|
|
|
|
The report must display the raw value if complete parsing is not implemented.
|
|
|
|
If a readable interpretation is added, keep the source value too in case of ambiguity.
|
|
|
|
## Collection Anomalies
|
|
|
|
Add an anomaly when:
|
|
|
|
- an endpoint returns an error;
|
|
- a response is incomplete;
|
|
- a job references an unknown storage;
|
|
- a VM selection type is not supported;
|
|
- a field required for analysis is missing.
|
|
|
|
An anomaly must contain:
|
|
|
|
- severity;
|
|
- affected component;
|
|
- short message;
|
|
- non-sensitive technical details.
|
|
|
|
## Client-Handled Errors
|
|
|
|
The client distinguishes:
|
|
|
|
- connection error or timeout;
|
|
- HTTP error with endpoint and return code;
|
|
- invalid JSON response;
|
|
- JSON response without a `data` field.
|
|
|
|
Error messages must never include `PVE_API_TOKEN_SECRET`.
|
|
|
|
## TLS
|
|
|
|
The API connection can be run with `PVE_VERIFY_TLS=false` when the existing CA is incompatible with strict Python/OpenSSL validation and cannot be replaced.
|