293 lines
9.1 KiB
Markdown
293 lines
9.1 KiB
Markdown
# Configuration
|
|
|
|
[Version francaise](../fr/configuration.md)
|
|
|
|
## Environment Variables
|
|
|
|
Recommended minimal configuration:
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
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
|
|
REPORT_EMAIL_ENABLED=false
|
|
```
|
|
|
|
## 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. |
|
|
| `REPORT_EMAIL_ENABLED` | No | Enables sending the generated PDF by email. Default: `false`. |
|
|
| `REPORT_EMAIL_SMTP_HOST` | If email enabled | SMTP server. |
|
|
| `REPORT_EMAIL_SMTP_PORT` | No | SMTP port. Default: `587`. |
|
|
| `REPORT_EMAIL_SMTP_STARTTLS` | No | Enables STARTTLS. Default: `true`. Incompatible with `REPORT_EMAIL_SMTP_SSL=true`. |
|
|
| `REPORT_EMAIL_SMTP_SSL` | No | Uses implicit TLS SMTP, often port `465`. Default: `false`. |
|
|
| `REPORT_EMAIL_SMTP_USERNAME` | No | SMTP username. If set, `REPORT_EMAIL_SMTP_PASSWORD` is required. |
|
|
| `REPORT_EMAIL_SMTP_PASSWORD` | No | SMTP password, read only from the environment and never displayed. |
|
|
| `REPORT_EMAIL_FROM` | If email enabled | Message sender address. |
|
|
| `REPORT_EMAIL_TO` | If email enabled | Comma-separated recipients. |
|
|
| `REPORT_EMAIL_SUBJECT` | No | Message subject. Default: `Rapport sauvegardes PVE`. |
|
|
| `REPORT_EMAIL_SMTP_TIMEOUT_SECONDS` | No | SMTP timeout. Default: `30`. |
|
|
|
|
## Email Delivery
|
|
|
|
Email delivery is optional and disabled by default. When `REPORT_EMAIL_ENABLED=true`, the `--generate-pdf` command first writes the timestamped PDF to `REPORT_OUTPUT_DIR`, then sends it as an attachment. If sending fails, the PDF remains on disk and the command returns an error so cron or monitoring can report it.
|
|
|
|
Example with STARTTLS:
|
|
|
|
```env
|
|
REPORT_EMAIL_ENABLED=true
|
|
REPORT_EMAIL_SMTP_HOST=smtp.example.invalid
|
|
REPORT_EMAIL_SMTP_PORT=587
|
|
REPORT_EMAIL_SMTP_STARTTLS=true
|
|
REPORT_EMAIL_SMTP_SSL=false
|
|
REPORT_EMAIL_SMTP_USERNAME=backup-report@example.invalid
|
|
REPORT_EMAIL_SMTP_PASSWORD=
|
|
REPORT_EMAIL_FROM=backup-report@example.invalid
|
|
REPORT_EMAIL_TO=admin@example.invalid,audit@example.invalid
|
|
REPORT_EMAIL_SUBJECT=PVE backup report
|
|
```
|
|
|
|
Example with implicit TLS:
|
|
|
|
```env
|
|
REPORT_EMAIL_SMTP_PORT=465
|
|
REPORT_EMAIL_SMTP_STARTTLS=false
|
|
REPORT_EMAIL_SMTP_SSL=true
|
|
```
|
|
|
|
Do not put SMTP passwords in the Docker image, logs or committed documentation. Use `.env`, a runtime environment variable or a Docker secret mounted at startup.
|
|
|
|
## Docker Compose Example
|
|
|
|
```yaml
|
|
services:
|
|
pve-backup-report:
|
|
build: .
|
|
env_file:
|
|
- .env
|
|
volumes:
|
|
- ./reports:/reports
|
|
restart: "no"
|
|
```
|
|
|
|
With this mount, Docker configuration must contain:
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
PBS_HOSTNAMES=backup.example.invalid=display-name
|
|
```
|
|
|
|
Rendered output:
|
|
|
|
```text
|
|
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.
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --check-api
|
|
```
|
|
|
|
To generate the PDF:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
<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:
|
|
|
|
```sh
|
|
pveum user token permissions <user@realm> <tokenid> --path /
|
|
```
|
|
|
|
Example:
|
|
|
|
```sh
|
|
pveum user token permissions backup-report@pve report --path /
|
|
```
|
|
|
|
Then check ACLs:
|
|
|
|
```sh
|
|
pveum acl list
|
|
```
|
|
|
|
To explicitly add `PVEAuditor` to the token on `/`:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```yaml
|
|
volumes:
|
|
- ./reports:/reports
|
|
- /etc/ssl/local/pve-ca.pem:/etc/ssl/local/pve-ca.pem:ro
|
|
```
|
|
|
|
Then:
|
|
|
|
```env
|
|
PVE_CA_BUNDLE=/etc/ssl/local/pve-ca.pem
|
|
```
|
|
|
|
## Output Directory
|
|
|
|
The output directory must be persistent.
|
|
|
|
With Docker, mount a host volume:
|
|
|
|
```yaml
|
|
volumes:
|
|
- /srv/pve-backup-report/reports:/reports
|
|
```
|
|
|
|
And configure:
|
|
|
|
```env
|
|
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.
|