252 lines
7.1 KiB
Markdown
252 lines
7.1 KiB
Markdown
# Configuration
|
|
|
|
[Version francaise](../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
|
|
```
|
|
|
|
## 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
|
|
|
|
```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.
|