150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# 🔧 pfSense API scripts
|
||
|
||
Scripts Bash pour interagir avec pfSense via le paquet REST API v2.
|
||
|
||
## 📁 Arborescence
|
||
|
||
```text
|
||
pfsense-api/
|
||
├── README.md
|
||
├── .gitignore
|
||
├── .env.example
|
||
└── scripts/
|
||
├── add-ip-alias.sh
|
||
├── add-port-forward.sh
|
||
├── manage-port-forwards.sh
|
||
└── test-api-connection.sh
|
||
```
|
||
|
||
## ✅ Prérequis
|
||
|
||
- 🖥️ pfSense avec le paquet REST API v2 installé et activé.
|
||
- 🔑 Authentification Basic activée côté API.
|
||
- 👤 Un utilisateur pfSense ayant accès à l'endpoint de test.
|
||
- 🌐 `curl` installé localement.
|
||
- 🔍 `jq` installé localement pour générer les payloads JSON.
|
||
|
||
## ⚙️ Configuration
|
||
|
||
Copier l'exemple puis adapter les valeurs localement :
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Variables principales :
|
||
|
||
```bash
|
||
PFSENSE_URL="https://pfsense.example.local"
|
||
PFSENSE_USER="api-user"
|
||
PFSENSE_PASSWORD="change-me"
|
||
```
|
||
|
||
Si pfSense utilise un certificat auto-signé :
|
||
|
||
```bash
|
||
PFSENSE_INSECURE=true
|
||
```
|
||
|
||
## 🩺 Tester la connexion API
|
||
|
||
```bash
|
||
./scripts/test-api-connection.sh
|
||
```
|
||
|
||
Par défaut, le script teste :
|
||
|
||
```text
|
||
/api/v2/status/system
|
||
```
|
||
|
||
Pour tester un autre endpoint en lecture seule :
|
||
|
||
```bash
|
||
PFSENSE_ENDPOINT="/api/v2/firewall/rules" ./scripts/test-api-connection.sh
|
||
```
|
||
|
||
## ➕ Créer une redirection de port
|
||
|
||
En mode interactif, lancer simplement :
|
||
|
||
```bash
|
||
./scripts/add-port-forward.sh
|
||
```
|
||
|
||
Le script demandera les valeurs manquantes : port WAN, IP interne, port interne,
|
||
protocole, interface, description, règle firewall associée et application des
|
||
changements.
|
||
|
||
Exemple : exposer le port TCP `8443` de l'adresse WAN pfSense vers le port
|
||
`443` de la machine interne `192.168.1.50` :
|
||
|
||
```bash
|
||
./scripts/add-port-forward.sh \
|
||
--external-port 8443 \
|
||
--target 192.168.1.50 \
|
||
--target-port 443 \
|
||
--protocol tcp \
|
||
--description "WAN 8443 vers serveur web interne"
|
||
```
|
||
|
||
Par défaut, le script :
|
||
|
||
- crée la règle sur l'interface `wan` ;
|
||
- utilise la destination `wan:ip`, c'est-à-dire l'adresse WAN pfSense ;
|
||
- crée une règle firewall associée avec `associated_rule_id=new` ;
|
||
- applique explicitement les changements via `/api/v2/firewall/apply`.
|
||
|
||
Pour créer la règle sans appliquer tout de suite :
|
||
|
||
```bash
|
||
./scripts/add-port-forward.sh \
|
||
--external-port 2222 \
|
||
--target 192.168.1.20 \
|
||
--target-port 22 \
|
||
--no-apply
|
||
```
|
||
|
||
## 🏷️ Créer un alias IP
|
||
|
||
En mode interactif :
|
||
|
||
```bash
|
||
./scripts/add-ip-alias.sh
|
||
```
|
||
|
||
Exemple avec une seule IP :
|
||
|
||
```bash
|
||
./scripts/add-ip-alias.sh \
|
||
--name SRV_WEB \
|
||
--addresses 192.168.1.50 \
|
||
--description "Serveur web interne"
|
||
```
|
||
|
||
Exemple avec plusieurs entrées :
|
||
|
||
```bash
|
||
./scripts/add-ip-alias.sh \
|
||
--name SERVEURS_WEB \
|
||
--addresses 192.168.1.50,192.168.1.51 \
|
||
--details "web-01,web-02"
|
||
```
|
||
|
||
Par défaut, le script crée un alias de type `host` et applique explicitement
|
||
les changements via `/api/v2/firewall/apply`.
|
||
|
||
## 🔀 Gérer les redirections NAT
|
||
|
||
Lister les redirections NAT, puis en sélectionner une pour la modifier ou la
|
||
supprimer :
|
||
|
||
```bash
|
||
./scripts/manage-port-forwards.sh
|
||
```
|
||
|
||
Le script appelle `/api/v2/firewall/nat/port_forwards` pour lister les règles,
|
||
puis `/api/v2/firewall/nat/port_forward` en `PATCH` ou `DELETE` selon l'action
|
||
choisie. Les changements sont appliqués via `/api/v2/firewall/apply`, sauf avec
|
||
`--no-apply`.
|