# pfSense API и автоматизация управления

> Настройка REST API pfSense, аутентификация по API-ключам и JWT, автоматизация через Ansible и Terraform, xmlrpc и программное управление конфигурацией

Source: https://opennix.org/docs/pfsense/development/pfsense-api-automation/


REST API превращает pfSense из автономного межсетевого экрана в программно управляемый компонент инфраструктуры. Вместо ручной настройки через веб-интерфейс администратор получает возможность выполнять операции через HTTP-запросы, интегрировать pfSense в системы оркестрации и реализовывать подход Infrastructure as Code. Это критически важно в средах с десятками устройств, где ручная настройка каждого файрвола нецелесообразна.

## Пакет pfSense REST API

pfSense не имеет встроенного REST API. Для программного доступа используется community-пакет [pfSense-api](https://github.com/jaredhendrickson13/pfsense-api), который добавляет более 200 эндпоинтов для управления системой.

### Установка

Пакет устанавливается из командной строки pfSense:

```bash
pkg-static add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.7.2-pkg-RESTAPI.pkg
```

После установки настройки API доступны через **System > REST API** в веб-интерфейсе.

### Аутентификация

API поддерживает три метода аутентификации:

| Метод | Заголовок | Срок действия | Рекомендация |
|---|---|---|---|
| Basic Auth | `Authorization: Basic <base64>` | Постоянный | Только для тестирования |
| API Key | `X-API-Key: <key>` | Постоянный | Скрипты и автоматизация |
| JWT | `Authorization: Bearer <token>` | Ограниченный | Интерактивные приложения |

#### Получение JWT-токена

```bash
curl -X POST -H "Content-Type: application/json" \
  -u admin:pfsense \
  https://pfsense.example.com/api/v2/auth/jwt
```

Ответ содержит токен, который затем передается в заголовке:

```bash
curl -H "Authorization: Bearer <token>" \
  https://pfsense.example.com/api/v2/firewall/rules
```

#### Аутентификация по API-ключу

API-ключи создаются в веб-интерфейсе (**System > REST API > Settings**) и привязываются к учетной записи пользователя. Привилегии ключа наследуются от учетной записи.

```bash
curl -H "X-API-Key: <your-api-key>" \
  https://pfsense.example.com/api/v2/system/info
```

## Обзор эндпоинтов API

### Системная информация

```bash
# Получение информации о системе
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/system/info

# Статус версии и обновлений
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/system/version
```

### Правила файрвола

```bash
# Получение списка правил
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/firewall/rules

# Создание нового правила
curl -X POST -H "Content-Type: application/json" \
  -H "X-API-Key: <key>" \
  -d '{
    "type": "pass",
    "interface": "wan",
    "ipprotocol": "inet",
    "protocol": "tcp",
    "source": "any",
    "destination": "any",
    "dstport": "443",
    "descr": "Allow HTTPS inbound"
  }' \
  https://pfsense.example.com/api/v2/firewall/rules

# Применение изменений (обязательно после модификации правил)
curl -X POST -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/firewall/apply
```

### Управление интерфейсами

```bash
# Список сетевых интерфейсов
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/interface

# Обновление конфигурации интерфейса
curl -X PUT -H "Content-Type: application/json" \
  -H "X-API-Key: <key>" \
  -d '{"if": "em1", "descr": "DMZ", "enable": true}' \
  https://pfsense.example.com/api/v2/interface
```

### Управление VPN

```bash
# Список OpenVPN-серверов
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/vpn/openvpn/server

# Список IPsec-туннелей
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/vpn/ipsec/phase1
```

## Автоматизация с Ansible

Коллекция [pfsensible.core](https://galaxy.ansible.com/pfsensible/core) предоставляет модули для декларативного управления pfSense через Ansible. Коллекция взаимодействует с pfSense через xmlrpc и PHP-интерфейс, не требуя установки дополнительных пакетов.

### Установка коллекции

```bash
ansible-galaxy collection install pfsensible.core
```

### Пример плейбука

```yaml
- name: Configure pfSense firewall
  hosts: pfsense_firewalls
  gather_facts: false
  collections:
    - pfsensible.core

  tasks:
    - name: Create alias for web servers
      pfsense_alias:
        name: web_servers
        type: host
        address: "10.0.1.10 10.0.1.11 10.0.1.12"
        descr: "Production web servers"
        state: present

    - name: Allow HTTPS to web servers
      pfsense_rule:
        name: "Allow HTTPS to web servers"
        interface: WAN
        action: pass
        protocol: tcp
        source: any
        destination: web_servers
        destination_port: 443
        state: present

    - name: Configure DNS resolver
      pfsense_dns_resolver:
        enable: true
        dnssec: true
        forwarding: true
```

### Настройка inventory

```ini
[pfsense_firewalls]
fw01 ansible_host=192.168.1.1

[pfsense_firewalls:vars]
ansible_connection=httpapi
ansible_httpapi_use_ssl=true
ansible_httpapi_validate_certs=false
ansible_user=admin
ansible_password=pfsense
ansible_network_os=pfsensible.core.pfsense
```

## Автоматизация с Terraform

Неофициальный [Terraform-провайдер для pfSense](https://registry.terraform.io/providers/sjafferern/pfsense/) позволяет управлять конфигурацией через декларативные HCL-файлы.

```hcl
terraform {
  required_providers {
    pfsense = {
      source  = "sjafferern/pfsense"
      version = "~> 0.1"
    }
  }
}

provider "pfsense" {
  url      = "https://192.168.1.1"
  user     = "admin"
  password = var.pfsense_password
  insecure = true
}

resource "pfsense_firewall_alias" "blocked_countries" {
  name        = "blocked_countries"
  type        = "network"
  description = "Blocked country subnets"
  entries     = ["10.99.0.0/16", "10.98.0.0/16"]
}
```

Провайдер находится на ранней стадии разработки. Перед использованием в рабочей среде рекомендуется тщательное тестирование.

## PHP Shell для программного доступа

pfSense включает PHP-оболочку разработчика, доступную через консоль (опция 12) или SSH. Оболочка позволяет напрямую читать и изменять конфигурацию системы.

### Доступ к PHP Shell

```text
Enter an option: 12

Starting the pfSense developer shell....
pfSense shell:
```

### Типовые операции

```php
// Чтение текущей конфигурации
parse_config(true);
print_r($config['interfaces']);
exec

// Изменение конфигурации
$config['system']['hostname'] = "fw-prod-01";
write_config("Updated hostname via PHP shell");
exec
```

### Playback-скрипты

Предопределенные скрипты для типовых задач запускаются из командной строки:

```bash
# Из SSH или консольного shell
pfSsh.php playback enablesshd
pfSsh.php playback changepassword
pfSsh.php playback installpkg "Some Package"
pfSsh.php playback listpkg
```

## xmlrpc для управления конфигурацией

pfSense использует xmlrpc для синхронизации конфигурации между узлами в кластере высокой доступности (CARP). Этот же механизм может использоваться для программного чтения и записи конфигурации.

xmlrpc доступен по адресу `https://<pfsense-ip>/xmlrpc.php` и принимает стандартные XML-RPC вызовы с Basic-аутентификацией.

Коллекция pfsensible.core использует xmlrpc как основной транспорт для взаимодействия с pfSense.

## Резервное копирование через API

REST API позволяет автоматизировать создание резервных копий конфигурации:

```bash
# Скачивание конфигурации через API
curl -H "X-API-Key: <key>" \
  https://pfsense.example.com/api/v2/system/config \
  -o config-backup-$(date +%Y%m%d).xml
```

### Скрипт автоматического бэкапа

```bash
#!/bin/sh
# Ежедневный бэкап конфигурации pfSense через API
PFSENSE_HOST="https://192.168.1.1"
API_KEY="your-api-key"
BACKUP_DIR="/backups/pfsense"
DATE=$(date +%Y%m%d-%H%M)

curl -sk -H "X-API-Key: ${API_KEY}" \
  "${PFSENSE_HOST}/api/v2/system/config" \
  -o "${BACKUP_DIR}/config-${DATE}.xml"

# Удаление бэкапов старше 30 дней
find "${BACKUP_DIR}" -name "config-*.xml" -mtime +30 -delete
```

## Сценарии использования

### Массовое развертывание

При развертывании нескольких устройств pfSense Ansible-плейбук применяет единую конфигурацию ко всем узлам. Типичный сценарий:

1. Базовая установка pfSense на каждое устройство
2. Настройка SSH-доступа и учетных данных
3. Применение плейбука с общими правилами файрвола, VPN-конфигурацией и DNS-настройками
4. Применение device-specific переменных (IP-адреса, имена хостов)

### CI/CD для правил файрвола

Правила файрвола хранятся в Git-репозитории как YAML-файлы. При merge в основную ветку CI-пайплайн применяет изменения через API или Ansible:

```yaml
# .gitlab-ci.yml
deploy_firewall_rules:
  stage: deploy
  script:
    - ansible-playbook -i inventory/production firewall-rules.yml
  only:
    - main
  when: manual
```

### Автоматизированное тестирование

После применения изменений автоматические проверки верифицируют корректность конфигурации:

```bash
# Проверка доступности после изменения правил
curl -sf -o /dev/null https://pfsense.example.com/api/v2/system/info \
  -H "X-API-Key: <key>" && echo "API accessible" || echo "API unreachable"
```

## Устранение неполадок

| Проблема | Причина | Решение |
|---|---|---|
| 401 Unauthorized | Неверные учетные данные или истекший JWT | Проверить ключ API или запросить новый токен |
| 403 Forbidden | Недостаточно привилегий у пользователя API | Назначить необходимые привилегии в **System > User Manager** |
| Connection refused на порту API | Пакет REST API не установлен или не запущен | Проверить установку пакета и статус сервиса |
| Изменения не применяются | Не вызван `/api/v2/firewall/apply` | Выполнить apply после модификации правил |
| xmlrpc timeout | Слишком большой config.xml или сетевые проблемы | Увеличить таймаут, проверить сетевую связность |
| Ansible-модуль не находит pfSense | Неверный `ansible_network_os` | Указать `pfsensible.core.pfsense` |

## Связанные разделы

- [Пользовательские скрипты pfSense](/docs/pfsense/development/pfsense-custom-scripts/) - shellcmd, cron-задачи и PHP-скрипты для локальной автоматизации
- [Резервное копирование pfSense](/docs/pfsense/backup/pfsense-backup-recovery/) - ручные и автоматические бэкапы конфигурации
- [Высокая доступность pfSense](/docs/pfsense/high-availability/) - xmlrpc-синхронизация конфигурации между узлами CARP-кластера