# 🔧 pfSense API scripts

![Bash](https://img.shields.io/badge/Bash-5.x-4EAA25?logo=gnubash&logoColor=white)
![pfSense](https://img.shields.io/badge/pfSense-REST_API_v2-212121?logo=pfsense&logoColor=white)
![curl](https://img.shields.io/badge/curl-required-073551?logo=curl&logoColor=white)
![jq](https://img.shields.io/badge/jq-required-black)
![License](https://img.shields.io/badge/licence-MIT-blue)

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