Organize documentation by language
This commit is contained in:
@@ -0,0 +1,251 @@
|
||||
# Configuration
|
||||
|
||||
[English version](../en/configuration.md)
|
||||
|
||||
## Variables d'environnement
|
||||
|
||||
Configuration minimale recommandee :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Un fichier `.env.example` est fourni comme modele. Le fichier `.env` reel ne doit pas etre commite.
|
||||
|
||||
Configuration optionnelle :
|
||||
|
||||
```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=nom-affiche
|
||||
LOG_LEVEL=INFO
|
||||
REPORT_FILENAME_PREFIX=rapport-sauvegardes-pve
|
||||
```
|
||||
|
||||
## Description des variables
|
||||
|
||||
| Variable | Obligatoire | Description |
|
||||
| --- | --- | --- |
|
||||
| `PVE_API_URL` | Oui | URL de l'API Proxmox VE, avec schema et port. |
|
||||
| `PVE_API_TOKEN_ID` | Oui | Identifiant complet du token API PVE. |
|
||||
| `PVE_API_TOKEN_SECRET` | Oui | Secret du token API PVE. |
|
||||
| `REPORT_OUTPUT_DIR` | Non | Repertoire de sortie des rapports PDF. Defaut applicatif : `reports/`. En Docker Compose, utiliser `/reports`. |
|
||||
| `REPORT_TIMEZONE` | Non | Fuseau horaire utilise pour les dates du rapport. Defaut : `Europe/Paris`. |
|
||||
| `REPORT_LANGUAGE` | Non | Langue du rapport PDF. Valeurs supportees : `fr` ou `en`. Defaut : `fr`. |
|
||||
| `PVE_VERIFY_TLS` | Non | Active la verification TLS. Defaut : `true`. |
|
||||
| `PVE_CA_BUNDLE` | Non | Chemin vers une CA interne montee dans le conteneur. |
|
||||
| `PVE_TIMEOUT_SECONDS` | Non | Timeout HTTP. Defaut : `30`. |
|
||||
| `PVE_BACKUP_JOBS_ENDPOINT` | Non | Endpoint qui liste les jobs de sauvegarde planifies. Defaut : `/cluster/backup`. A conserver sauf cas particulier. |
|
||||
| `PVE_TASK_HISTORY_LIMIT` | Non | Nombre de taches PVE recentes inspectees pour trouver la derniere sauvegarde. Defaut : `500`. |
|
||||
| `PVE_TASK_LOG_LIMIT` | Non | Nombre de lignes recuperees par log de tache `vzdump`. Defaut : `5000`. |
|
||||
| `PBS_HOSTNAMES` | Non | Mapping manuel IP/DNS PBS vers nom d'hote affiche dans le rapport. |
|
||||
| `PBS<number>_NAME` | Non | Nom affiche du serveur PBS configure, par exemple `PBS01_NAME`. Defaut : le prefixe `PBS<number>`. |
|
||||
| `PBS<number>_API_URL` | Non | URL API du serveur PBS, par exemple `https://backup.example.invalid:8007`. Active la collecte si le token est aussi renseigne. |
|
||||
| `PBS<number>_API_TOKEN_ID` | Non | Identifiant complet du token API PBS. |
|
||||
| `PBS<number>_API_TOKEN_SECRET` | Non | Secret du token API PBS. |
|
||||
| `PBS<number>_VERIFY_TLS` | Non | Active la verification TLS pour ce serveur PBS. Defaut : valeur de `PVE_VERIFY_TLS`. |
|
||||
| `PBS<number>_CA_BUNDLE` | Non | Chemin vers une CA interne pour ce serveur PBS. |
|
||||
| `PBS<number>_TIMEOUT_SECONDS` | Non | Timeout HTTP pour ce serveur PBS. Defaut : valeur de `PVE_TIMEOUT_SECONDS` ou `30`. |
|
||||
| `LOG_LEVEL` | Non | Niveau de log. Defaut : `INFO`. |
|
||||
| `REPORT_FILENAME_PREFIX` | Non | Prefixe du fichier PDF. |
|
||||
|
||||
## Exemple Docker Compose
|
||||
|
||||
```yaml
|
||||
services:
|
||||
pve-backup-report:
|
||||
build: .
|
||||
env_file:
|
||||
- .env
|
||||
volumes:
|
||||
- ./reports:/reports
|
||||
restart: "no"
|
||||
```
|
||||
|
||||
Avec ce montage, la configuration Docker doit contenir :
|
||||
|
||||
```env
|
||||
REPORT_OUTPUT_DIR=/reports
|
||||
```
|
||||
|
||||
Les rapports sont alors ecrits dans `./reports/` sur l'hote.
|
||||
|
||||
## Mapping des noms PBS
|
||||
|
||||
Le champ `PBS_HOSTNAMES` permet d'afficher le nom d'hote entre parentheses dans la colonne `Serveur PBS`.
|
||||
|
||||
Format :
|
||||
|
||||
```env
|
||||
PBS_HOSTNAMES=backup.example.invalid=nom-affiche
|
||||
```
|
||||
|
||||
Rendu dans le rapport :
|
||||
|
||||
```text
|
||||
backup.example.invalid (nom-affiche)
|
||||
```
|
||||
|
||||
## Collecte PBS
|
||||
|
||||
La collecte PBS est optionnelle. Pour chaque serveur PBS, elle est active uniquement si les trois variables API URL, token ID et token secret sont renseignees.
|
||||
|
||||
Un bloc PBS suit le motif `PBS<number>_*`. L'ordre de collecte et d'affichage suit l'ordre numerique des prefixes : `PBS01`, `PBS02`, `PBS10`, etc.
|
||||
|
||||
```env
|
||||
PBS01_NAME=nom-affiche
|
||||
PBS01_API_URL=https://backup.example.invalid:8007
|
||||
PBS01_API_TOKEN_ID=
|
||||
PBS01_API_TOKEN_SECRET=
|
||||
```
|
||||
|
||||
Pour ajouter d'autres serveurs PBS, dupliquer le bloc et incrementer le numero du prefixe :
|
||||
|
||||
```env
|
||||
PBS02_NAME=nom-affiche-secondaire
|
||||
PBS02_API_URL=https://backup-secondary.example.invalid:8007
|
||||
PBS02_API_TOKEN_ID=
|
||||
PBS02_API_TOKEN_SECRET=
|
||||
|
||||
PBS10_NAME=nom-affiche-dixieme
|
||||
PBS10_API_URL=https://backup-extra.example.invalid:8007
|
||||
PBS10_API_TOKEN_ID=
|
||||
PBS10_API_TOKEN_SECRET=
|
||||
```
|
||||
|
||||
Le token PBS est transmis avec le schema d'authentification `PBSAPIToken` sous la forme `TOKENID:TOKENSECRET`.
|
||||
|
||||
La collecte d'un PBS est active uniquement lorsque l'URL, le token ID et le token secret sont tous renseignes. Une URL seule ne bloque pas le demarrage, mais aucune collecte n'est lancee pour ce PBS.
|
||||
|
||||
Le service Docker lance la commande `pve-backup-report`. Pour produire un rapport, passer explicitement l'argument `--generate-pdf`.
|
||||
|
||||
Pour tester la connexion API :
|
||||
|
||||
```sh
|
||||
docker compose run --rm pve-backup-report --check-api
|
||||
```
|
||||
|
||||
Pour generer le PDF :
|
||||
|
||||
```sh
|
||||
docker compose run --rm pve-backup-report --generate-pdf
|
||||
```
|
||||
|
||||
## Permissions du token PVE
|
||||
|
||||
Le token doit etre limite a la lecture.
|
||||
|
||||
Permissions attendues selon l'implementation :
|
||||
|
||||
- lecture de la configuration du cluster ;
|
||||
- lecture des stockages ;
|
||||
- lecture des ressources VM/CT ;
|
||||
- lecture des jobs de sauvegarde.
|
||||
|
||||
Pour le test de l'endpoint des jobs de sauvegarde, PVE peut exiger le privilege `Sys.Audit` sur le chemin `/`.
|
||||
|
||||
Si `--check-api` retourne :
|
||||
|
||||
```text
|
||||
<endpoint>: HTTP 403 - Permission check failed (/, Sys.Audit)
|
||||
```
|
||||
|
||||
ajouter ce privilege au role du token utilise, ou utiliser un role de lecture existant qui le contient.
|
||||
|
||||
Dans l'etat observe du projet, `/cluster/backup` existe bien et l'erreur attendue en cas de droit insuffisant est un `403`, pas un `404`.
|
||||
|
||||
### Diagnostic des droits effectifs du token
|
||||
|
||||
Un token PVE peut etre en mode privileges separes. Dans ce mode, les droits effectifs du token sont l'intersection des droits de l'utilisateur et des ACL propres au token.
|
||||
|
||||
Verifier d'abord le token :
|
||||
|
||||
```sh
|
||||
pveum user token permissions <user@realm> <tokenid> --path /
|
||||
```
|
||||
|
||||
Exemple :
|
||||
|
||||
```sh
|
||||
pveum user token permissions backup-report@pve report --path /
|
||||
```
|
||||
|
||||
Verifier ensuite les ACL :
|
||||
|
||||
```sh
|
||||
pveum acl list
|
||||
```
|
||||
|
||||
Pour ajouter explicitement `PVEAuditor` au token sur `/` :
|
||||
|
||||
```sh
|
||||
pveum acl modify / --tokens 'backup-report@pve!report' --roles PVEAuditor --propagate 1
|
||||
```
|
||||
|
||||
Si le token est en privileges separes, l'utilisateur parent doit aussi avoir un droit compatible :
|
||||
|
||||
```sh
|
||||
pveum acl modify / --users backup-report@pve --roles PVEAuditor --propagate 1
|
||||
```
|
||||
|
||||
Autre option, moins restrictive : creer ou modifier le token en privileges complets (`privsep=0`). Dans ce cas, le token reprend les droits de son utilisateur parent. Cette option est moins fine et doit etre choisie volontairement.
|
||||
|
||||
Eviter les privileges d'administration globaux.
|
||||
|
||||
## TLS
|
||||
|
||||
La verification TLS peut etre desactivee explicitement pour les connexions locales :
|
||||
|
||||
```env
|
||||
PVE_VERIFY_TLS=false
|
||||
PVE_CA_BUNDLE=
|
||||
```
|
||||
|
||||
Lorsque `PVE_VERIFY_TLS=false`, `PVE_CA_BUNDLE` est ignore meme s'il est renseigne.
|
||||
|
||||
Quand cette option est utilisee explicitement, l'application journalise un avertissement unique et masque les avertissements repetes de `urllib3` pour conserver des logs lisibles.
|
||||
|
||||
Si la CA interne n'est pas reconnue par le conteneur, preferer un volume monte et renseigner `PVE_CA_BUNDLE`.
|
||||
|
||||
Exemple :
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./reports:/reports
|
||||
- /etc/ssl/local/pve-ca.pem:/etc/ssl/local/pve-ca.pem:ro
|
||||
```
|
||||
|
||||
Puis :
|
||||
|
||||
```env
|
||||
PVE_CA_BUNDLE=/etc/ssl/local/pve-ca.pem
|
||||
```
|
||||
|
||||
## Repertoire de sortie
|
||||
|
||||
Le repertoire de sortie doit etre persistant.
|
||||
|
||||
Dans Docker, monter un volume hote :
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /srv/pve-backup-report/reports:/reports
|
||||
```
|
||||
|
||||
Et configurer :
|
||||
|
||||
```env
|
||||
REPORT_OUTPUT_DIR=/reports
|
||||
```
|
||||
|
||||
Le conteneur doit avoir le droit d'ecrire dans ce repertoire.
|
||||
|
||||
Les rapports ne doivent pas etre produits dans un chemin ephemere si leur conservation est requise pour l'audit.
|
||||
Reference in New Issue
Block a user