# 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.