Документация
Документация pfSense - руководства по настройке и администрированию
Разработка и автоматизация pfSense
Сборка pfSense из исходного кода

Сборка pfSense из исходного кода

pfSense CE - проект с открытым исходным кодом на базе FreeBSD. Исходный код размещен на GitHub и включает три основных репозитория: базовую систему с GUI, модифицированные исходники FreeBSD и коллекцию портов. Разработчики могут собирать pfSense из исходников, вносить исправления через System Patches без полной пересборки или участвовать в развитии проекта через pull request.

Репозитории исходного кода

Разработка pfSense CE ведется в трех репозиториях на GitHub:

РепозиторийСодержимоеНазначение
pfSense/pfSenseGUI-код, скрипты сборкиВеб-интерфейс, PHP-логика, утилиты
pfSense/FreeBSD-srcИсходный код ОСЯдро и базовая система FreeBSD
pfSense/FreeBSD-portsПорты и пакетыСборочная информация для ПО, пакеты pfSense

Основная ветка разработки - master для репозитория pfSense/pfSense и devel для FreeBSD-ports. Релизные ветки именуются по схеме RELENG_2_8_1.

Требования к среде сборки

Для сборки pfSense из исходного кода необходима среда на базе FreeBSD соответствующей версии. pfSense использует poudriere для сборки пакетов и формирования установочных образов.

Минимальные требования:

  • FreeBSD версии, соответствующей целевому релизу pfSense (см. таблицу соответствия )
  • Установленный poudriere для сборки портов
  • Достаточное дисковое пространство (минимум 50 ГБ для полной сборки)
  • Git для работы с репозиториями
# Установка необходимых инструментов на FreeBSD
pkg install git poudriere

Структура репозитория pfSense

Репозиторий pfSense/pfSense содержит:

  • src/ - PHP-файлы веб-интерфейса, конфигурационные скрипты
  • tools/ - скрипты сборки и утилиты разработчика
  • src/etc/inc/ - основные PHP-модули (config.inc, util.inc, interfaces.inc)
  • src/usr/local/www/ - страницы веб-интерфейса
  • src/etc/phpshellskel/ - скрипты PHP Shell

Сборка из исходного кода

Процесс сборки pfSense CE из исходников:

# Клонирование основного репозитория
git clone https://github.com/pfsense/pfSense.git
cd pfSense

# Переключение на нужную ветку (например, RELENG_2_8_1)
git checkout RELENG_2_8_1

# Запуск сборки (требуется настроенная среда poudriere)
./build.sh

Полная сборка включает компиляцию ядра FreeBSD, сборку всех портов через poudriere и формирование установочного ISO-образа. Процесс занимает значительное время и требует правильной настройки среды.

System Patches - патчи без пересборки

Пакет System Patches позволяет применять исправления к pfSense без полной пересборки системы. Патчи могут быть получены из официального репозитория, вставлены вручную или загружены из сторонних источников.

Установка

Установите пакет через System > Package Manager > Available Packages, найдя System Patches.

Использование

После установки пакет доступен через System > Patches. Он предоставляет:

  • Получение рекомендованных патчей от Netgate с возможностью автоприменения
  • Добавление пользовательских патчей из URL, текста или файла
  • Применение и откат патчей через веб-интерфейс
  • Тестирование исправлений из pull request до их включения в релиз

System Patches особенно полезен для проверки исправлений из GitHub перед обновлением до следующей версии pfSense.

gitsync - обновление между снимками

Утилита gitsync синхронизирует PHP-код из Git-репозитория pfSense CE, позволяя получить исправления между официальными релизами без установки нового снимка.

Ограничения

  • Работает только с pfSense CE, не совместим с pfSense Plus
  • Синхронизирует только PHP-файлы - бинарные изменения не применяются
  • Некоторые PHP-изменения требуют соответствующих бинарных обновлений, доступных только через полный снимок
  • Рекомендуется использовать только по указанию разработчиков или при глубоком понимании процесса разработки

Запуск gitsync

Из меню консоли pfSense выберите пункт 12 (developer shell):

> playback gitsync master

Или из стандартной оболочки (пункт 8 консоли):

pfSsh.php playback gitsync master

Для синхронизации с конкретной веткой релиза замените master на имя ветки:

pfSsh.php playback gitsync RELENG_2_8_1

Если Git не установлен, установите его вручную:

pkg install git

При ошибках, связанных с изменением URL репозитория, удалите старый клон:

rm -rf /root/pfsense/
pfSsh.php playback gitsync master

Отправка pull request

Для внесения изменений в pfSense CE через GitHub:

  1. Создайте запись об ошибке или функции в Redmine pfSense (исключение - мелкие исправления опечаток)
  2. Форкните нужный репозиторий:
    • pfSense/pfSense - для изменений базовой системы и GUI
    • pfSense/FreeBSD-ports - для изменений пакетов
  3. Внесите изменения в соответствующую ветку:
    • master - для pfSense/pfSense
    • devel - для FreeBSD-ports
  4. Укажите номер записи Redmine в сообщении коммита
  5. Создайте pull request с описанием и ссылкой на Redmine
  6. Добавьте ссылку на PR в соответствующую запись Redmine

Pull request можно протестировать на действующей системе через пакет System Patches до его принятия в основную ветку.

Руководство по стилю кодирования

pfSense использует стиль K&R BSD KNF. Основные правила:

Форматирование

  • Табуляция для отступов (ширина 8), пробелы запрещены
  • Фигурные скобки обязательны для всех блоков if, for, foreach, даже однострочных
  • Пробел между ключевым словом и скобкой (if (, foreach (), но не между именем функции и аргументами (function_name()
  • Отсутствие пробелов в конце строк

PHP-соглашения

  • Имена переменных в нижнем регистре с подчеркиванием ($my_variable) или camelCase ($myVariable)
  • Не использовать $g как переменную цикла - конфликт с глобальной переменной pfSense $g
  • Использовать elseif вместо else if для совместимости с альтернативным синтаксисом PHP
  • Не использовать устаревшие функции PHP

Безопасность

  • Минимизировать вызовы shell-команд; при необходимости использовать escapeshellarg() для переменных
  • Всегда экранировать пользовательский ввод через htmlspecialchars() при выводе
  • Следовать принципам MVC: разделять логику отображения, валидации и хранения данных

Комментарии

  • Использовать // или /* */, писать на английском языке
  • Метки: TODO: для запланированных доработок, FIXME: для известных проблем, NOTE: для важных пояснений

Рекомендации по PHP 8.x

pfSense перешел на PHP 8.x, что требует внимания при разработке:

  • Строгая типизация: неявные приведения типов вызывают предупреждения
  • Удаленные функции: each(), create_function(), mysql_* недоступны
  • Именованные аргументы: совместимость с именами параметров в функциях
  • Использовать elseif вместо else if - последний вариант некорректно работает с альтернативным синтаксисом

Проверяйте совместимость кода с целевой версией PHP перед отправкой pull request.

Ядро отладки

Для диагностики проблем на уровне ядра pfSense предоставляет пакет с отладочными символами:

pkg install pfSense-kernel-debug

Отладочное ядро содержит символы, необходимые для анализа дампов памяти (core dumps) и трассировки ядра. Используйте его при воспроизведении kernel panic или при подготовке отчета об ошибке, связанной с ядром.

Политика по проблемам FreeBSD

pfSense основан на FreeBSD, и некоторые проблемы относятся к базовой системе FreeBSD, а не к pfSense. При обнаружении ошибки, связанной с ядром, драйверами или базовыми утилитами FreeBSD:

  • Проверьте, воспроизводится ли проблема на чистой FreeBSD соответствующей версии
  • Если проблема воспроизводится на FreeBSD - сообщите о ней в баг-трекер FreeBSD
  • Если проблема специфична для pfSense - создайте запись в Redmine pfSense

Разработчики Netgate не занимаются исправлением проблем в базовой системе FreeBSD, за исключением критических уязвимостей безопасности.

Сообщение об ошибках и запрос функций

Сообщение об ошибках

Для сообщения об ошибке в pfSense:

  1. Проверьте, не описана ли проблема в существующих записях Redmine pfSense
  2. Соберите диагностическую информацию (версия pfSense, версия FreeBSD, логи)
  3. Создайте новую запись с детальным описанием: шаги воспроизведения, ожидаемое и фактическое поведение
  4. Приложите скриншоты, логи и информацию о panic (если применимо)

Запрос функций

Запросы новых функций также создаются в Redmine. Опишите предлагаемую функциональность, обоснование и потенциальные варианты реализации. Технические вопросы по разработке обсуждаются на форуме Netgate .

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

Last updated on
Разработка пакетов для pfSense