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

> Сборка pfSense из исходников, среда разработки, структура репозиториев, System Patches, gitsync, отправка pull request и участие в разработке

Source: https://opennix.org/docs/pfsense/development/pfsense-building-from-source/


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

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

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

| Репозиторий | Содержимое | Назначение |
|---|---|---|
| [pfSense/pfSense](https://github.com/pfsense/pfSense) | GUI-код, скрипты сборки | Веб-интерфейс, PHP-логика, утилиты |
| [pfSense/FreeBSD-src](https://github.com/pfsense/FreeBSD-src) | Исходный код ОС | Ядро и базовая система FreeBSD |
| [pfSense/FreeBSD-ports](https://github.com/pfsense/FreeBSD-ports) | Порты и пакеты | Сборочная информация для ПО, пакеты pfSense |

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

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

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

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

- FreeBSD версии, соответствующей целевому релизу pfSense (см. [таблицу соответствия](https://docs.netgate.com/pfsense/en/latest/development/freebsd-version.html))
- Установленный poudriere для сборки портов
- Достаточное дисковое пространство (минимум 50 ГБ для полной сборки)
- Git для работы с репозиториями

```bash
# Установка необходимых инструментов на 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 из исходников:

```bash
# Клонирование основного репозитория
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 консоли):

```bash
pfSsh.php playback gitsync master
```

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

```bash
pfSsh.php playback gitsync RELENG_2_8_1
```

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

```bash
pkg install git
```

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

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

## Отправка pull request

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

1. Создайте запись об ошибке или функции в [Redmine pfSense](https://redmine.pfsense.org) (исключение - мелкие исправления опечаток)
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 предоставляет пакет с отладочными символами:

```bash
pkg install pfSense-kernel-debug
```

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

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

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

- Проверьте, воспроизводится ли проблема на чистой FreeBSD соответствующей версии
- Если проблема воспроизводится на FreeBSD - сообщите о ней в [баг-трекер FreeBSD](https://bugs.freebsd.org/)
- Если проблема специфична для pfSense - создайте запись в Redmine pfSense

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

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

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

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

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

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

Запросы новых функций также создаются в Redmine. Опишите предлагаемую функциональность, обоснование и потенциальные варианты реализации. Технические вопросы по разработке обсуждаются на [форуме Netgate](https://forum.netgate.com).

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

- [Разработка пакетов pfSense](/docs/pfsense/development/pfsense-package-development/) - создание собственных пакетов, структура порта, XML-манифест
- [Пользовательские скрипты pfSense](/docs/pfsense/development/pfsense-custom-scripts/) - скрипты автоматизации, Shellcmd и Cron
- [API и автоматизация](/docs/pfsense/development/pfsense-api-automation/) - программное управление через REST API