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

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

Пакет pfSense REST API

pfSense не имеет встроенного REST API. Для программного доступа используется community-пакет pfSense-api , который добавляет более 200 эндпоинтов для управления системой.

Установка

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

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-токена

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

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

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

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

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

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

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

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

# Получение информации о системе
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

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

# Получение списка правил
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

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

# Список сетевых интерфейсов
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

# Список 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 предоставляет модули для декларативного управления pfSense через Ansible. Коллекция взаимодействует с pfSense через xmlrpc и PHP-интерфейс, не требуя установки дополнительных пакетов.

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

ansible-galaxy collection install pfsensible.core

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

- 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

[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 позволяет управлять конфигурацией через декларативные 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

Enter an option: 12

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

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

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

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

Playback-скрипты

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

# Из 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 позволяет автоматизировать создание резервных копий конфигурации:

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

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

#!/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-плейбук применяет единую конфигурацию ко всем узлам. Типичный сценарий:

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

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

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

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

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

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

# Проверка доступности после изменения правил
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 - shellcmd, cron-задачи и PHP-скрипты для локальной автоматизации
Резервное копирование pfSense - ручные и автоматические бэкапы конфигурации
Высокая доступность pfSense - xmlrpc-синхронизация конфигурации между узлами CARP-кластера

Last updated on 7, апреля 2026

Пользовательские скрипты и задачи pfSense