PVE-Backup-Report/docs/en/configuration.md

Configuration

Version francaise

Environment Variables

Recommended minimal configuration:

PVE_API_URL=https://pve.example.invalid:8006
PVE_API_TOKEN_ID=
PVE_API_TOKEN_SECRET=
REPORT_OUTPUT_DIR=/reports
REPORT_TIMEZONE=Europe/Paris
REPORT_LANGUAGE=fr

A .env.example file is provided as a template. The real .env file must not be committed.

Optional configuration:

PVE_VERIFY_TLS=false
PVE_CA_BUNDLE=
PVE_TIMEOUT_SECONDS=30
PVE_BACKUP_JOBS_ENDPOINT=/cluster/backup
PVE_TASK_HISTORY_LIMIT=500
PBS_HOSTNAMES=backup.example.invalid=display-name
LOG_LEVEL=INFO
REPORT_FILENAME_PREFIX=rapport-sauvegardes-pve

Variable Description

Variable	Required	Description
PVE_API_URL	Yes	Proxmox VE API URL, with scheme and port.
PVE_API_TOKEN_ID	Yes	Full PVE API token identifier.
PVE_API_TOKEN_SECRET	Yes	PVE API token secret.
REPORT_OUTPUT_DIR	No	PDF report output directory. Application default: reports/. With Docker Compose, use /reports.
REPORT_TIMEZONE	No	Time zone used for report dates. Default: Europe/Paris.
REPORT_LANGUAGE	No	PDF report language. Supported values: fr or en. Default: fr.
PVE_VERIFY_TLS	No	Enables TLS verification. Default: true.
PVE_CA_BUNDLE	No	Path to an internal CA mounted in the container.
PVE_TIMEOUT_SECONDS	No	HTTP timeout. Default: 30.
PVE_BACKUP_JOBS_ENDPOINT	No	Endpoint listing scheduled backup jobs. Default: /cluster/backup. Keep this value except for specific cases.
PVE_TASK_HISTORY_LIMIT	No	Number of recent PVE tasks inspected to find the latest backup. Default: 500.
PVE_TASK_LOG_LIMIT	No	Number of lines retrieved per vzdump task log. Default: 5000.
PBS_HOSTNAMES	No	Manual IP/DNS to display-name mapping for PBS servers.
PBS<number>_NAME	No	Display name of the configured PBS server, for example PBS01_NAME. Default: the PBS<number> prefix.
PBS<number>_API_URL	No	PBS API URL, for example https://backup.example.invalid:8007. Enables collection when the token is also set.
PBS<number>_API_TOKEN_ID	No	Full PBS API token identifier.
PBS<number>_API_TOKEN_SECRET	No	PBS API token secret.
PBS<number>_VERIFY_TLS	No	Enables TLS verification for this PBS server. Default: PVE_VERIFY_TLS value.
PBS<number>_CA_BUNDLE	No	Path to an internal CA for this PBS server.
PBS<number>_TIMEOUT_SECONDS	No	HTTP timeout for this PBS server. Default: PVE_TIMEOUT_SECONDS or 30.
LOG_LEVEL	No	Log level. Default: INFO.
REPORT_FILENAME_PREFIX	No	PDF filename prefix.

Docker Compose Example

services:
  pve-backup-report:
    build: .
    env_file:
      - .env
    volumes:
      - ./reports:/reports
    restart: "no"

With this mount, Docker configuration must contain:

REPORT_OUTPUT_DIR=/reports

Reports are then written to ./reports/ on the host.

PBS Name Mapping

PBS_HOSTNAMES displays a host name in parentheses in the PBS server column.

Format:

PBS_HOSTNAMES=backup.example.invalid=display-name

Rendered output:

backup.example.invalid (display-name)

PBS Collection

PBS collection is optional. For each PBS server, it is active only when API URL, token ID and token secret are all provided.

A PBS block follows the PBS<number>_* pattern. Collection and display order follow numeric prefix order: PBS01, PBS02, PBS10, etc.

PBS01_NAME=display-name
PBS01_API_URL=https://backup.example.invalid:8007
PBS01_API_TOKEN_ID=
PBS01_API_TOKEN_SECRET=

To add more PBS servers, duplicate the block and increment the prefix number:

PBS02_NAME=secondary-display-name
PBS02_API_URL=https://backup-secondary.example.invalid:8007
PBS02_API_TOKEN_ID=
PBS02_API_TOKEN_SECRET=

PBS10_NAME=tenth-display-name
PBS10_API_URL=https://backup-extra.example.invalid:8007
PBS10_API_TOKEN_ID=
PBS10_API_TOKEN_SECRET=

The PBS token is sent with the PBSAPIToken authentication scheme as TOKENID:TOKENSECRET.

PBS collection is active only when URL, token ID and token secret are all set. A URL alone does not block startup, but no collection is run for that PBS.

The Docker service launches pve-backup-report. To produce a report, pass --generate-pdf explicitly.

To test API connectivity:

docker compose run --rm pve-backup-report --check-api

To generate the PDF:

docker compose run --rm pve-backup-report --generate-pdf

PVE Token Permissions

The token must be limited to read-only access.

Expected permissions according to the implementation:

• read cluster configuration;
• read storages;
• read VM/CT resources;
• read backup jobs.

For testing the backup jobs endpoint, PVE may require the Sys.Audit privilege on /.

If --check-api returns:

<endpoint>: HTTP 403 - Permission check failed (/, Sys.Audit)

add this privilege to the token role, or use an existing read-only role that contains it.

In the observed project state, /cluster/backup exists and the expected error for insufficient permissions is 403, not 404.

Effective Token Permission Diagnostics

A PVE token can use separated privileges. In that mode, effective token permissions are the intersection of the parent user's permissions and the token's own ACLs.

Check the token first:

pveum user token permissions <user@realm> <tokenid> --path /

Example:

pveum user token permissions backup-report@pve report --path /

Then check ACLs:

pveum acl list

To explicitly add PVEAuditor to the token on /:

pveum acl modify / --tokens 'backup-report@pve!report' --roles PVEAuditor --propagate 1

If the token uses separated privileges, the parent user must also have compatible access:

pveum acl modify / --users backup-report@pve --roles PVEAuditor --propagate 1

Another, less restrictive option is to create or modify the token with full privileges (privsep=0). In that case, the token inherits permissions from its parent user. This option is less granular and must be chosen deliberately.

Avoid global administrator privileges.

TLS

TLS verification can be explicitly disabled for local connections:

PVE_VERIFY_TLS=false
PVE_CA_BUNDLE=

When PVE_VERIFY_TLS=false, PVE_CA_BUNDLE is ignored even if set.

When this option is explicitly used, the application logs a single warning and hides repeated urllib3 warnings to keep logs readable.

If the internal CA is not trusted by the container, prefer a mounted volume and set PVE_CA_BUNDLE.

Example:

volumes:
  - ./reports:/reports
  - /etc/ssl/local/pve-ca.pem:/etc/ssl/local/pve-ca.pem:ro

Then:

PVE_CA_BUNDLE=/etc/ssl/local/pve-ca.pem

Output Directory

The output directory must be persistent.

With Docker, mount a host volume:

volumes:
  - /srv/pve-backup-report/reports:/reports

And configure:

REPORT_OUTPUT_DIR=/reports

The container must be allowed to write to this directory.

Reports must not be produced in an ephemeral path if they are required for audit retention.