🔧 pfSense API scripts

Scripts Bash pour interagir avec pfSense via le paquet REST API v2.

📁 Arborescence

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 :

cp .env.example .env

Variables principales :

PFSENSE_URL="https://pfsense.example.local"
PFSENSE_USER="api-user"
PFSENSE_PASSWORD="change-me"

Si pfSense utilise un certificat auto-signé :

PFSENSE_INSECURE=true

🩺 Tester la connexion API

./scripts/test-api-connection.sh

Par défaut, le script teste :

/api/v2/status/system

Pour tester un autre endpoint en lecture seule :

PFSENSE_ENDPOINT="/api/v2/firewall/rules" ./scripts/test-api-connection.sh

➕ Créer une redirection de port

En mode interactif, lancer simplement :

./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 :

./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 :

./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 :

./scripts/add-ip-alias.sh

Exemple avec une seule IP :

./scripts/add-ip-alias.sh \
  --name SRV_WEB \
  --addresses 192.168.1.50 \
  --description "Serveur web interne"

Exemple avec plusieurs entrées :

./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 :

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