Skip to content

Commit f3de2e1

Browse files
alainabbasalainabbas
committed
first commit
1 parent 03a73a0 commit f3de2e1

6 files changed

Lines changed: 708 additions & 2 deletions

File tree

‎README.fr.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# pbs_backup — Fichier de configuration d'un job
2+
3+
*[English version](README.md)*
4+
5+
`pbs_backup_orchestrator.py` exécute des sauvegardes [Proxmox Backup Server
6+
(PBS)](https://pbs.proxmox.com/) pour des machines distantes. Pour chaque
7+
machine à sauvegarder, il lit un **fichier de configuration** (un "job"),
8+
génère un script bash, le pousse via SSH sur la machine cible et l'exécute
9+
avec `proxmox-backup-client`.
10+
11+
Ce document décrit le format de ce fichier de configuration.
12+
13+
## Emplacement et nommage
14+
15+
- Les fichiers de job vivent dans le répertoire de configuration
16+
(`CONF_DIR`, par défaut `/etc/pbs-backup/conf.d`).
17+
- Formats acceptés : `.yaml` / `.yml` ou `.json`.
18+
- **Le nom du job est le nom du fichier, sans extension.** Par exemple
19+
`web01.yaml` définit le job `web01`.
20+
- Si deux fichiers définissent le même nom de job (ex: `web01.json` et
21+
`web01.yaml`), le second est ignoré avec un avertissement.
22+
- Ces fichiers peuvent contenir des secrets (mot de passe / token PBS) :
23+
appliquer `chmod 600`.
24+
25+
Des exemples commentés sont fournis dans `conf.d/example.yaml.sample` et
26+
`conf.d/example.json.sample`.
27+
28+
## Structure
29+
30+
Le fichier est un objet/mapping avec cinq sections : `ssh`, `pbs`, `backup`,
31+
`nobackup_marker` et `hooks`.
32+
33+
### `ssh` — accès à la machine cible
34+
35+
| Clé | Type | Obligatoire | Défaut | Description |
36+
|--------|--------|-------------|--------|-------------------------------------------------|
37+
| `host` | string | oui | — | Hôte SSH de la machine à sauvegarder |
38+
| `port` | int | non | `22` | Port SSH |
39+
| `user` | string | non | `root` | Utilisateur SSH |
40+
| `key` | string | non | — | Chemin de la clé privée SSH (`ssh -i`) |
41+
42+
La connexion se fait en mode `BatchMode=yes` (pas de prompt interactif) :
43+
l'authentification par clé doit être déjà en place.
44+
45+
### `pbs` — cible Proxmox Backup Server
46+
47+
| Clé | Type | Obligatoire | Défaut | Description |
48+
|-----------------|--------|-------------|--------|----------------------------------------------------------------------|
49+
| `repository` | string | oui | — | Dépôt PBS, format `user@realm!token@host:datastore` |
50+
| `password` | string | non | — | Secret PBS (mot de passe ou valeur du token) en clair |
51+
| `password_file` | string | non | — | Fichier contenant le secret PBS (alternative à `password`) |
52+
| `fingerprint` | string | non | — | Empreinte TLS du serveur PBS |
53+
| `namespace` | string | non | — | Namespace PBS cible |
54+
55+
Un **token API** est recommandé plutôt qu'un mot de passe utilisateur.
56+
Si `password_file` est renseigné, il est préféré à `password` (le fichier
57+
est lu au moment de l'exécution, ce qui évite de stocker le secret en clair
58+
dans le fichier de config). Ces valeurs sont exportées comme variables
59+
d'environnement (`PBS_REPOSITORY`, `PBS_PASSWORD`, `PBS_FINGERPRINT`,
60+
`PBS_NAMESPACE`) dans le script exécuté sur la machine cible.
61+
62+
### `backup` — sources à sauvegarder
63+
64+
| Clé | Type | Obligatoire | Défaut | Description |
65+
|------------------|---------------|-------------|-----------------------|----------------------------------------------------------------------|
66+
| `sources` | liste[string] | oui | — | Sources à sauvegarder, format `nom-archive.pxar:/chemin` (ou `nom.img:/dev/xxx` pour un disque) |
67+
| `backup_id` | string | non | — | Identifiant de sauvegarde passé à `--backup-id` |
68+
| `extra_opts` | liste[string] | non | `[]` | Options supplémentaires ajoutées telles quelles à la commande `proxmox-backup-client backup` |
69+
| `remote_tmp_dir` | string | non | `/root/.pbs-backup` | Répertoire temporaire sur la machine cible pour y déposer le script généré |
70+
71+
`sources` doit contenir au moins une entrée.
72+
73+
### `nobackup_marker` — exclusion par fichier marqueur
74+
75+
| Clé | Type | Obligatoire | Défaut | Description |
76+
|-----------|--------|-------------|--------------|----------------------------------------------------------------------------|
77+
| `enabled` | bool | non | `true` | Si activé, tout répertoire contenant ce fichier marqueur est exclu |
78+
| `name` | string | non | `.nobackup` | Nom du fichier marqueur recherché sur la machine cible |
79+
80+
La recherche est effectuée sur la machine cible au moment de la sauvegarde,
81+
pour chaque chemin source déclaré dans `backup.sources`.
82+
83+
### `hooks` — commandes pré/post sauvegarde
84+
85+
| Clé | Type | Obligatoire | Défaut | Description |
86+
|---------------|--------|-------------|--------|-----------------------------------------------------|
87+
| `pre_backup` | string | non | — | Commande exécutée avant la sauvegarde (`bash -c`) |
88+
| `post_backup` | string | non | — | Commande exécutée après la sauvegarde (`bash -c`) |
89+
90+
- `pre_backup` doit réussir pour que la sauvegarde démarre.
91+
- `post_backup` s'exécute **toujours** (succès ou échec de la sauvegarde ou
92+
du hook `pre_backup`) et n'affecte pas le code de sortie du job.
93+
94+
Ces commandes sont exécutées **sur la machine cible**, pas sur la machine
95+
qui héberge l'orchestrateur.
96+
97+
## Exemple minimal (YAML)
98+
99+
```yaml
100+
ssh:
101+
host: web01.example.com
102+
key: /root/.ssh/id_pbs_backup
103+
104+
pbs:
105+
repository: "backup@pbs!token@pbs.example.com:datastore1"
106+
password_file: /etc/pbs-backup/secrets/web01.token
107+
fingerprint: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
108+
109+
backup:
110+
sources:
111+
- "root.pxar:/"
112+
- "etc.pxar:/etc"
113+
extra_opts:
114+
- "--exclude /var/tmp"
115+
- "--exclude /tmp"
116+
```
117+
118+
## Utilisation
119+
120+
```bash
121+
# Exécuter tous les jobs du répertoire de config
122+
pbs-backup-orchestrator
123+
124+
# Ne traiter qu'un job précis
125+
pbs-backup-orchestrator --job web01
126+
127+
# Générer les scripts sans les pousser/exécuter (vérification)
128+
pbs-backup-orchestrator --dry-run
129+
130+
# Utiliser un autre répertoire de configuration
131+
pbs-backup-orchestrator --conf-dir /chemin/vers/conf.d
132+
```
133+
134+
Voir `install.sh` pour l'installation sur Debian (venv Python dédié,
135+
lanceur `/usr/local/bin/pbs-backup-orchestrator`).

‎README.md‎

Lines changed: 135 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,135 @@
1-
# pbs-clients-orchestrator
2-
save with proxmox backup servers bare-metal hosts or hosts who are not on a proxmox VE
1+
# pbs_backup — Job configuration file
2+
3+
*[Version française](README.fr.md)*
4+
5+
`pbs_backup_orchestrator.py` runs [Proxmox Backup Server
6+
(PBS)](https://pbs.proxmox.com/) backups for remote machines. For each
7+
machine to back up, it reads a **configuration file** (a "job"), generates
8+
a bash script, pushes it over SSH to the target machine, and runs it with
9+
`proxmox-backup-client`.
10+
11+
This document describes the format of that configuration file.
12+
13+
## Location and naming
14+
15+
- Job files live in the configuration directory (`CONF_DIR`, default
16+
`/etc/pbs-backup/conf.d`).
17+
- Accepted formats: `.yaml` / `.yml` or `.json`.
18+
- **The job name is the file name without its extension.** For example,
19+
`web01.yaml` defines the job `web01`.
20+
- If two files define the same job name (e.g. `web01.json` and
21+
`web01.yaml`), the second one is skipped with a warning.
22+
- These files may contain secrets (PBS password / token): apply
23+
`chmod 600`.
24+
25+
Commented examples are provided in `conf.d/example.yaml.sample` and
26+
`conf.d/example.json.sample`.
27+
28+
## Structure
29+
30+
The file is an object/mapping with five sections: `ssh`, `pbs`, `backup`,
31+
`nobackup_marker`, and `hooks`.
32+
33+
### `ssh` — access to the target machine
34+
35+
| Key | Type | Required | Default | Description |
36+
|--------|--------|----------|---------|--------------------------------------------|
37+
| `host` | string | yes | — | SSH host of the machine to back up |
38+
| `port` | int | no | `22` | SSH port |
39+
| `user` | string | no | `root` | SSH user |
40+
| `key` | string | no | — | Path to the SSH private key (`ssh -i`) |
41+
42+
The connection uses `BatchMode=yes` (no interactive prompt): key-based
43+
authentication must already be set up.
44+
45+
### `pbs` — Proxmox Backup Server target
46+
47+
| Key | Type | Required | Default | Description |
48+
|-----------------|--------|----------|---------|----------------------------------------------------------------------|
49+
| `repository` | string | yes | — | PBS repository, format `user@realm!token@host:datastore` |
50+
| `password` | string | no | — | PBS secret (password or token value) stored in plain text |
51+
| `password_file` | string | no | — | File containing the PBS secret (alternative to `password`) |
52+
| `fingerprint` | string | no | — | TLS fingerprint of the PBS server |
53+
| `namespace` | string | no | — | Target PBS namespace |
54+
55+
An **API token** is recommended over a user password. If `password_file`
56+
is set, it takes precedence over `password` (the file is read at
57+
execution time, avoiding storing the secret in clear text in the config
58+
file). These values are exported as environment variables
59+
(`PBS_REPOSITORY`, `PBS_PASSWORD`, `PBS_FINGERPRINT`, `PBS_NAMESPACE`) in
60+
the script run on the target machine.
61+
62+
### `backup` — sources to back up
63+
64+
| Key | Type | Required | Default | Description |
65+
|------------------|--------------|----------|----------------------|----------------------------------------------------------------------------|
66+
| `sources` | list[string] | yes | — | Sources to back up, format `archive-name.pxar:/path` (or `name.img:/dev/xxx` for a disk) |
67+
| `backup_id` | string | no | — | Backup identifier passed to `--backup-id` |
68+
| `extra_opts` | list[string] | no | `[]` | Extra options appended as-is to the `proxmox-backup-client backup` command |
69+
| `remote_tmp_dir` | string | no | `/root/.pbs-backup` | Temporary directory on the target machine to drop the generated script |
70+
71+
`sources` must contain at least one entry.
72+
73+
### `nobackup_marker` — exclusion via marker file
74+
75+
| Key | Type | Required | Default | Description |
76+
|-----------|--------|----------|--------------|--------------------------------------------------------------------------|
77+
| `enabled` | bool | no | `true` | If enabled, any directory containing this marker file is excluded |
78+
| `name` | string | no | `.nobackup` | Name of the marker file looked for on the target machine |
79+
80+
The lookup runs on the target machine at backup time, for each source
81+
path declared in `backup.sources`.
82+
83+
### `hooks` — pre/post backup commands
84+
85+
| Key | Type | Required | Default | Description |
86+
|---------------|--------|----------|---------|---------------------------------------------------|
87+
| `pre_backup` | string | no | — | Command run before the backup (`bash -c`) |
88+
| `post_backup` | string | no | — | Command run after the backup (`bash -c`) |
89+
90+
- `pre_backup` must succeed for the backup to start.
91+
- `post_backup` **always** runs (whether the backup or the `pre_backup`
92+
hook succeeded or failed) and does not affect the job's exit code.
93+
94+
These commands are executed **on the target machine**, not on the machine
95+
hosting the orchestrator.
96+
97+
## Minimal example (YAML)
98+
99+
```yaml
100+
ssh:
101+
host: web01.example.com
102+
key: /root/.ssh/id_pbs_backup
103+
104+
pbs:
105+
repository: "backup@pbs!token@pbs.example.com:datastore1"
106+
password_file: /etc/pbs-backup/secrets/web01.token
107+
fingerprint: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
108+
109+
backup:
110+
sources:
111+
- "root.pxar:/"
112+
- "etc.pxar:/etc"
113+
extra_opts:
114+
- "--exclude /var/tmp"
115+
- "--exclude /tmp"
116+
```
117+
118+
## Usage
119+
120+
```bash
121+
# Run all jobs in the config directory
122+
pbs-backup-orchestrator
123+
124+
# Run only one job
125+
pbs-backup-orchestrator --job web01
126+
127+
# Generate the scripts without pushing/running them (dry check)
128+
pbs-backup-orchestrator --dry-run
129+
130+
# Use a different configuration directory
131+
pbs-backup-orchestrator --conf-dir /path/to/conf.d
132+
```
133+
134+
See `install.sh` for installation on Debian (dedicated Python venv,
135+
`/usr/local/bin/pbs-backup-orchestrator` launcher).

‎conf.d/example.json.sample‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"_comment": "Copier ce fichier sous CONF_DIR/<nom-du-job>.json (ex: web01.json) et chmod 600 (contient potentiellement un mot de passe / token). Le nom du job = nom du fichier sans l'extension .json.",
3+
4+
"ssh": {
5+
"host": "web01.example.com",
6+
"port": 22,
7+
"user": "root",
8+
"key": "/root/.ssh/id_pbs_backup"
9+
},
10+
11+
"pbs": {
12+
"_comment": "Cible Proxmox Backup Server. Préférer un token API plutôt qu'un mot de passe utilisateur.",
13+
"repository": "backup@pbs!token@pbs.example.com:datastore1",
14+
"password": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
15+
"password_file": "",
16+
"fingerprint": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
17+
"namespace": ""
18+
},
19+
20+
"backup": {
21+
"_comment": "Une entrée par source, format 'nom-archive.pxar:/chemin' (ou 'nom.img:/dev/xxx' pour un disque)",
22+
"sources": [
23+
"root.pxar:/",
24+
"etc.pxar:/etc"
25+
],
26+
"backup_id": "",
27+
"extra_opts": [
28+
"--exclude /var/tmp",
29+
"--exclude /tmp",
30+
"--exclude /var/cache"
31+
],
32+
"remote_tmp_dir": "/root/.pbs-backup"
33+
},
34+
35+
"nobackup_marker": {
36+
"_comment": "Exclut automatiquement tout répertoire contenant ce fichier marqueur (recherché sur la machine cible, au moment de la sauvegarde).",
37+
"enabled": true,
38+
"name": ".nobackup"
39+
},
40+
41+
"hooks": {
42+
"_comment": "Commandes exécutées sur la machine cible, via 'bash -c'. pre_backup doit réussir pour que la sauvegarde démarre. post_backup s'exécute toujours (succès, échec de la sauvegarde ou du hook pre_backup) et n'affecte pas le code de sortie du job.",
43+
"pre_backup": "",
44+
"post_backup": ""
45+
}
46+
}

‎conf.d/example.yaml.sample‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Copier ce fichier sous CONF_DIR/<nom-du-job>.yaml (ex: web01.yaml) et
2+
# chmod 600 (contient potentiellement un mot de passe / token).
3+
# Le nom du job = nom du fichier sans l'extension .yaml/.yml
4+
5+
ssh:
6+
host: web01.example.com
7+
port: 22
8+
user: root
9+
key: /root/.ssh/id_pbs_backup
10+
11+
pbs:
12+
# Cible Proxmox Backup Server. Préférer un token API plutôt qu'un mot de
13+
# passe utilisateur.
14+
repository: "backup@pbs!token@pbs.example.com:datastore1"
15+
password: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
16+
# Alternative pour ne pas stocker le secret en clair dans ce fichier:
17+
# password_file: /etc/pbs-backup/secrets/web01.token
18+
fingerprint: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
19+
namespace: ""
20+
21+
backup:
22+
# Une entrée par source, format "nom-archive.pxar:/chemin"
23+
# (ou "nom.img:/dev/xxx" pour un disque)
24+
sources:
25+
- "root.pxar:/"
26+
- "etc.pxar:/etc"
27+
backup_id: ""
28+
extra_opts:
29+
- "--exclude /var/tmp"
30+
- "--exclude /tmp"
31+
- "--exclude /var/cache"
32+
remote_tmp_dir: /root/.pbs-backup
33+
34+
nobackup_marker:
35+
# Exclut automatiquement tout répertoire contenant ce fichier marqueur
36+
# (recherché sur la machine cible, au moment de la sauvegarde).
37+
enabled: true
38+
name: .nobackup
39+
40+
hooks:
41+
# Commandes exécutées sur la machine cible, via "bash -c". pre_backup doit
42+
# réussir pour que la sauvegarde démarre. post_backup s'exécute toujours
43+
# (succès, échec de la sauvegarde ou du hook pre_backup) et n'affecte pas
44+
# le code de sortie du job.
45+
pre_backup: ""
46+
post_backup: ""

0 commit comments

Comments
 (0)