151 lines
3.2 KiB
Markdown
151 lines
3.2 KiB
Markdown
# pfSense API scripts
|
|
|
|
Scripts Bash pour interagir avec pfSense via le paquet REST API v2.
|
|
|
|
## Arborescence
|
|
|
|
```text
|
|
pfsense-api/
|
|
├── AGENTS.md
|
|
├── README.md
|
|
├── .gitignore
|
|
├── .env.example
|
|
└── scripts/
|
|
├── add-ip-alias.sh
|
|
├── add-port-forward.sh
|
|
├── manage-port-forwards.sh
|
|
└── test-api-connection.sh
|
|
```
|
|
|
|
## Prerequis
|
|
|
|
- pfSense avec le paquet REST API v2 installe et active.
|
|
- Authentification Basic active cote API.
|
|
- Un utilisateur pfSense ayant acces a l'endpoint de test.
|
|
- `curl` installe localement.
|
|
- `jq` installe localement pour generer 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-signe :
|
|
|
|
```bash
|
|
PFSENSE_INSECURE=true
|
|
```
|
|
|
|
## Tester la connexion API
|
|
|
|
```bash
|
|
./scripts/test-api-connection.sh
|
|
```
|
|
|
|
Par defaut, 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
|
|
```
|
|
|
|
## Creer 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, regle firewall associee 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 defaut, le script :
|
|
|
|
- cree la regle sur l'interface `wan`;
|
|
- utilise la destination `wan:ip`, c'est-a-dire l'adresse WAN pfSense;
|
|
- cree une regle firewall associee avec `associated_rule_id=new`;
|
|
- applique explicitement les changements via `/api/v2/firewall/apply`.
|
|
|
|
Pour creer la regle sans appliquer tout de suite :
|
|
|
|
```bash
|
|
./scripts/add-port-forward.sh \
|
|
--external-port 2222 \
|
|
--target 192.168.1.20 \
|
|
--target-port 22 \
|
|
--no-apply
|
|
```
|
|
|
|
## Creer 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 entrees :
|
|
|
|
```bash
|
|
./scripts/add-ip-alias.sh \
|
|
--name SERVEURS_WEB \
|
|
--addresses 192.168.1.50,192.168.1.51 \
|
|
--details "web-01,web-02"
|
|
```
|
|
|
|
Par defaut, le script cree un alias de type `host` et applique explicitement
|
|
les changements via `/api/v2/firewall/apply`.
|
|
|
|
## Gerer les redirections NAT
|
|
|
|
Lister les redirections NAT, puis en selectionner 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 regles,
|
|
puis `/api/v2/firewall/nat/port_forward` en `PATCH` ou `DELETE` selon l'action
|
|
choisie. Les changements sont appliques via `/api/v2/firewall/apply`, sauf avec
|
|
`--no-apply`.
|