Разработка собственного плагина в Jail для TrueNAS CORE: полное руководство

Официальный каталог плагинов TrueNAS CORE не всегда содержит нужное вам специализированное ПО. Создание кастомного Jail — это проверенный способ развернуть любое приложение, будь то уникальный Python-скрипт, внутренний демон или ПО, отсутствующее в репозиториях. Это руководство предоставляет пошаговую, проверенную на практике инструкцию: от создания чистого Jail через веб-интерфейс до настройки автозапуска службы и безопасного доступа к данным на ZFS пулах. Вы получите полный контроль над окружением, что критически важно для интеграции кастомного софта в инфраструктуру хранения без риска для стабильности основной системы.

Процесс основан на механизме Jail — технологии изоляции процессов в FreeBSD, которая лежит в основе TrueNAS CORE. В отличие от виртуальной машины, Jail легковесен, использует ядро хоста и обеспечивает достаточную изоляцию для большинства сервисов. Мы пройдем все этапы: подготовка окружения, установка ПО, настройка автозапуска, обеспечение безопасности и решение типовых проблем.

Подготовка: создание чистого Jail через веб-интерфейс TrueNAS

Работа начинается с веб-интерфейса TrueNAS CORE. Перейдите в раздел Jails и нажмите ADD. Для нашей задачи оптимально выбрать тип Jail «Клонированный Jail» (Clone Jail) с базой «13.2-RELEASE» (или актуальной стабильной версии, совместимой с вашей TrueNAS). Это создаст минимальное окружение, которое мы затем настроим под свои нужды, избегая лишнего софта.

Ключевые параметры при создании Jail: имя, сеть и версия ОС

Каждый параметр в мастере создания важен для последующей стабильной работы.

• Имя Jail (Jail Name): Используйте латиницу без пробелов. Например, custom_app_jail. Это имя будет использоваться во всех командах управления.
• Версия FreeBSD: Выберите стабильную версию, рекомендованную для вашей версии TrueNAS CORE. Например, для TrueNAS CORE 13.0-U6 подойдет 13.2-RELEASE. Использование более новых или экспериментальных версий может привести к несовместимости пакетов.
• Настройки сети: Для серверного применения предпочтительнее статический IP-адрес. Укажите свободный адрес из подсети вашего интерфейса TrueNAS (например, 192.168.1.150), маску подсети (24) и шлюз по умолчанию. Убедитесь, что выбранный IP не конфликтует с другими устройствами в сети. Параметр «VNET» должен быть включен для полной изоляции сети Jail.

Пример корректной конфигурации: Jail my_service, версия 13.2-RELEASE, IPv4 Address: 192.168.1.200/24, Default Router: 192.168.1.1, VNET: включен.

Настройка точек монтирования (NullFS) для доступа к данным

Чтобы приложение внутри Jail могло читать или писать данные на основном пуле ZFS, необходимо настроить точки монтирования через технологию NullFS. Это безопаснее, чем предоставлять прямой доступ ко всей файловой системе.

1. В мастере создания Jail или после его создания в свойствах найдите раздел «Mount Points».
2. Нажмите ADD. В поле Source укажите путь на хосте TrueNAS, например, /mnt/pool/app_data (где pool — имя вашего ZFS пула).
3. В поле Destination укажите путь внутри Jail, куда будет смонтирован каталог, например, /mnt/data.
4. Важно заранее создать исходный каталог на хосте и настроить права доступа. Чтобы избежать ошибок «Permission denied», рекомендуется создать на хосте отдельную группу (например, appgroup), назначить ей права на каталог /mnt/pool/app_data, а затем создать пользователя с таким же GID внутри Jail.

Завершите создание Jail. После запуска (Status станет «Up») вы получите изолированное окружение с доступом к указанным данным.

Установка и настройка ПО внутри кастомного Jail

Для установки ПО войдите в Jail. Это можно сделать через веб-интерфейс (кнопка SHELL в карточке Jail) или по SSH, если он настроен на TrueNAS. Вы окажетесь в командной строке FreeBSD внутри изолированного окружения.

Первым делом обновите репозитории пакетов: pkg update. Система пакетов FreeBSD (pkg) — основной инструмент для установки бинарного ПО. Для компиляции из исходников (если пакета нет) используется ports collection, но это более сложный процесс, требующий установки портов (portsnap fetch extract).

Работа с пакетным менеджером pkg и установка зависимостей

Используйте pkg для быстрого развертывания необходимого стека. Основные команды:

• Поиск пакета: pkg search nginx
• Установка пакета: pkg install nginx
• Установка нескольких пакетов за одну операцию: pkg install python39 py39-pip nginx
• Обновление всех пакетов: pkg upgrade
• Удаление пакета: pkg delete nginx

Пример установки типичного стека для веб-приложения: pkg install python39 py39-pip nginx git. Установка всех зависимостей за один раз экономит время и снижает риск конфликтов.

Настройка среды для Python-скриптов или кастомных демонов

Если ваше приложение — это Python-скрипт, создайте виртуальное окружение для изоляции зависимостей:

python3.9 -m venv /usr/local/myapp_venv
source /usr/local/myapp_venv/bin/activate
pip install flask requests

Для тестирования создайте простой демон. Например, файл /usr/local/myapp/app.py с содержимым на основе Flask:

from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return "Custom app is running in Jail!"

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Запустите его вручную для проверки: python /usr/local/myapp/app.py. Убедитесь, что скрипт слушает порт: выполните из другого терминала на хосте sockstat -l | grep 5000 или проверьте доступность curl http://192.168.1.150:5000 (IP вашего Jail).

Более глубокие аспекты управления Jail, такие как тонкая настройка сети (VNET, мост) и безопасное подключение хранилищ, детально разобраны в нашем проверенном руководстве по созданию кастомного Jail в TrueNAS Core.

Настройка автозапуска службы (демона) при загрузке Jail

Чтобы ваше приложение запускалось автоматически при старте TrueNAS или перезагрузке Jail, необходимо интегрировать его в систему инициализации FreeBSD rc.d. Это обеспечивает надежность работы сервиса.

Система rc.d использует скрипты в каталоге /usr/local/etc/rc.d/. Создайте там скрипт для управления вашим демоном.

Создание и регистрация rc-скрипта в системе FreeBSD

Создайте файл /usr/local/etc/rc.d/my_python_daemon с правами на исполнение:

#!/bin/sh
#
# PROVIDE: my_python_daemon
# REQUIRE: LOGIN
# KEYWORD: shutdown

. /etc/rc.subr

name="my_python_daemon"
rcvar="${name}_enable"

command="/usr/local/myapp_venv/bin/python"
command_args="/usr/local/myapp/app.py"
pidfile="/var/run/${name}.pid"

# Указываем, как запускать процесс в фоне
start_cmd="${command} ${command_args} &"
stop_cmd="pkill -f '${command_args}'"

load_rc_config $name
run_rc_command "$1"

Установите права: chmod 555 /usr/local/etc/rc.d/my_python_daemon.

Затем добавьте службу в автозагрузку: sysrc my_python_daemon_enable="YES". Эта команда добавит соответствующую строку в /etc/rc.conf.

Проверка работы автозапуска и просмотр логов службы

Проверьте работу скрипта вручную:

• Запуск: service my_python_daemon start
• Остановка: service my_python_daemon stop
• Проверка статуса: service my_python_daemon status

Убедитесь, что служба добавлена в автозагрузку: grep my_python_daemon_enable /etc/rc.conf (должно вернуть my_python_daemon_enable="YES").

Для проверки автозапуска перезагрузите Jail через веб-интерфейс или командой iocage restart my_service. После загрузки проверьте, работает ли процесс: pgrep -fl app.py или sockstat -l | grep 5000.

Логи службы можно найти в системном логе: tail -f /var/log/messages. Если ваш демон пишет в собственный лог, проверяйте его путь.

Если вы планируете развертывать популярные сервисы вроде Nextcloud или GitLab, готовые пошаговые инструкции по их настройке в Jail доступны в нашем руководстве по настройке приложений в TrueNAS Jails.

Безопасный доступ к данным хоста и управление Jail

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

Модель прав доступа и безопасность точек монтирования NullFS

Права доступа (UID/GID) работают прозрачно между хостом и Jail. Если на хосте файл принадлежит пользователю с UID 1001, то внутри Jail пользователь с таким же UID 1001 будет иметь к нему те же права.

Рекомендации по безопасности:

1. Создайте на хосте отдельную группу (например, app_grp, GID 2001) и пользователя для службы.
2. Назначьте этой группе права на каталог с данными: chown -R :app_grp /mnt/pool/app_data и chmod 770 /mnt/pool/app_data.
3. Внутри Jail создайте пользователя и группу с теми же GID/UID (pw groupadd -n app_grp -g 2001; pw useradd -n app_user -u 1001 -g app_grp).
4. Запускайте ваш демон от имени этого пользователя (в rc-скрипте укажите command_interpreter и user).
5. Если приложению не нужна запись, смонтируйте каталог в режиме «только для чтения» (Read-only) в настройках точки монтирования.

Рутинное управление: команды для остановки, обновления и бэкапа

Для ежедневного администрирования используйте команды утилиты iocage или веб-интерфейс.

• Список всех Jail: iocage list
• Запуск Jail: iocage start my_service
• Остановка Jail: iocage stop my_service
• Перезагрузка Jail: iocage restart my_service
• Доступ к консоли: iocage console my_service
• Обновление пакетов внутри Jail: iocage exec my_service pkg upgrade

Для создания резервной копии конфигурации Jail (не данных) используйте экспорт через веб-интерфейс (кнопка EXPORT) или команду: iocage export my_service. Это создаст файл, который можно импортировать в случае сбоя.

Для понимания фундаментальных различий между легковесными Jails и полноценными виртуальными машинами, что поможет выбрать оптимальную технологию для разных задач, обратитесь к нашему практическому сравнению Jails и ВМ в TrueNAS.

Диагностика и решение типовых проблем

Даже при четком следовании инструкциям могут возникнуть проблемы. Этот чек-лист поможет быстро локализовать и устранить неисправность.

Чек-лист: Jail не запускается или нет сети

1. Проверьте статус Jail: iocage get state my_service. Если состояние down, проверьте логи: iocage get all my_service | grep -i error или системный лог хоста tail -f /var/log/messages.
2. Проверьте сеть внутри Jail: Если Jail запущен, но нет сети, войдите в консоль и проверьте:
   ifconfig (должен быть виден интерфейс с вашим IP).
   netstat -rn (должен быть указан шлюз по умолчанию).
   ping 8.8.8.8 (проверка внешнего доступа).
   Если ping до шлюза не проходит, проверьте настройки сети Jail (iocage get ip4_addr my_service) и отсутствие конфликта IP.
3. Фаервол хоста: Убедитесь, что на интерфейсе TrueNAS не блокируются трафик с/на подсеть Jail. Проверьте правила pf или ipfw.

Отладка службы: почему демон не стартует?

1. Запуск вручную: Войдите в Jail и попробуйте запустить команду демона из rc-скрипта вручную, полностью. Все ошибки будут выведены в терминал. Например: /usr/local/myapp_venv/bin/python /usr/local/myapp/app.py.
2. Проверка занятости порта: sockstat -l | grep :5000. Если порт занят другим процессом, измените порт в конфигурации приложения.
3. Анализ логов: При попытке старта через service my_python_daemon start смотрите системный лог в реальном времени: tail -f /var/log/messages в другом терминале.
4. Права и пути: Убедитесь, что в rc-скрипте указаны абсолютные корректные пути к command и command_args. Проверьте права на исполняемые файлы и каталоги с данными.

Если вы столкнулись с проблемами на этапе базовой установки или настройки репозиториев, более широкий контекст по установке приложений в обеих системах — TrueNAS Scale и Core — представлен в нашем полном руководстве по установке приложений в TrueNAS.