NetBox 4.5 пишет API_TOKEN_PEPPERS is not defined: что настроить для новых API-токенов

После обновления на NetBox 4.5 интерфейс открывается нормально, а при попытке выпустить новый API-токен сервер падает с ValueError: API_TOKEN_PEPPERS is not defined. Это не опечатка в конфиге, а отдельный параметр, обязательный для новой системы v2-токенов — показываю, где он должен быть прописан, как его сгенерировать правильно и что именно чинили в патче 4.5.1.

Симптом: интерфейс работает, а токен для автоматизации выпустить нельзя

Заявку от трастовой компании «Доверительный дом» (28 рабочих мест) я получил в конце января 2026 года: их системный администратор обновил NetBox с 4.4 до свежей на тот момент 4.5.0, всё проверил глазами — сайты, устройства, IP-адреса на месте, вход по логину работает, — и решил, что апгрейд прошёл чисто. Проблема всплыла через два дня, когда понадобилось выпустить новый API-токен для скрипта, который каждую ночь сверяет данные NetBox с Zabbix. Форма создания токена в разделе учётной записи открывалась нормально, но по нажатию «Create» сервер отвечал ошибкой 500 без внятного текста в интерфейсе. Мы делаем внедрение NetBox под ключ как раз для того, чтобы такие вещи не всплывали на проде без предупреждения, поэтому клиент обратился к нам с логами вместо того, чтобы гадать самостоятельно.

В логе контейнера netbox (или, если у вас установка из архива — в выводе journalctl -u netbox) ошибка выглядела однозначно: <class 'ValueError'> и следом API_TOKEN_PEPPERS is not defined. Первая мысль администратора была здравая — полезли в configuration.py, но там всё выглядело как обычно: SECRET_KEY на месте, база данных подключена, Redis отвечает. Про параметр API_TOKEN_PEPPERS в старом конфиге не было ни строчки — и это правильно, потому что в версиях до 4.5 такого параметра не существовало вообще. Разбираться пришлось не с опечаткой, а с новой обязательной настройкой, которая появилась вместе с целой системой v2-токенов.

Что изменилось с v2-токенами в NetBox 4.5

NetBox 4.5 (релиз 6 января 2026 года) переработал систему API-токенов с нуля — в официальном анонсе беты это описано как «rebuilt API token system with proper credential hashing and enable/disable controls». До этой версии токен (назовём его теперь v1) хранился в базе данных открытым текстом: любой, кто получил доступ к таблице users_token, читал значение токена напрямую, без всякого перебора. Для внутренней CMDB с десятками интеграций это всегда было слабым местом — я сам не раз видел, как токен «для Zabbix» несколько лет назад давали разработчику подрядчика на словах, а потом никто не вспоминал его отозвать, потому что не было даже поля «включён/выключен».

Токен v2 устроен иначе. Открытый текст видно ровно один раз — в момент создания, — а на сервере остаётся только его HMAC-SHA256-хеш, посчитанный с использованием секретного «перца» (pepper). Восстановить исходное значение токена из базы данных невозможно даже при полном доступе к СУБД, потому что открытый текст там просто не хранится. У модели Token появилось новое поле Key — короткий случайный публичный идентификатор, который виден в интерфейсе постоянно (по нему токен ищут и отзывают), тогда как секретная часть после создания больше нигде не отображается. Добавился и выключатель Enabled (issue #20834): токен можно временно отключить без удаления. Поля Write Enabled (только чтение, GET) и Allowed IPs (список префиксов IPv4/IPv6, с которых токен принимается) были и раньше, но теперь они работают в связке с ключом и хешем. Заодно в 4.5 убрали параметр ALLOW_TOKEN_RETRIEVAL: посмотреть открытый текст уже выпущенного токена больше нельзя ни при каких настройках.

Изменился и заголовок аутентификации. Токен v1 по-прежнему передаётся как Authorization: Token <ключ>, но в v2 схема другая — Authorization: Bearer nbt_<key>.<secret>, где часть до точки — публичный Key из карточки токена, а после точки — секрет, который вы получили один раз при создании и должны сохранить сами (в менеджере паролей, не в текстовом файле рядом со скриптом). Формально v1-токены остаются рабочими, но в официальной документации по REST API прямо написано, что они объявлены устаревшими начиная с 4.6 и будут полностью удалены в 5.0 (в release notes 4.5.0 сначала обещали убрать их уже в 4.7, срок сдвинули в 4.6.1, issue #22128) — так что переезд на v2 не факультативная опция, а вопрос ближайших минорных релизов. Если NetBox у вас опубликован за обратным прокси, держите в уме и смежную проблему: сам заголовок Authorization иногда обрезается на уровне nginx ещё до того, как долетит до приложения — я разбирал похожий случай, когда после переноса API за nginx пропал заголовок X_API_KEY, и причина была не в NetBox, а в настройке underscores_in_headers на прокси.

По сути NetBox сделал с API-токенами то же, что индустрия давно делает с паролями пользователей: не хранить секрет как есть, а хранить только его соленый хеш, по которому нельзя восстановить исходное значение, но можно проверить совпадение при предъявлении. Для CMDB, где токены живут годами и раздаются десяткам интеграций, это не косметическое улучшение. Утечка бэкапа базы данных (а бэкапы NetBox почти всегда лежат на других серверах, с другим набором прав доступа) раньше означала утечку всех API-токенов в открытом виде разом. С v2-схемой такой бэкап без дополнительного перебора не даёт вообще ничего полезного атакующему — только хеши, посчитанные с перцем, которого в самом бэкапе базы нет.

• curl -H «Authorization: Token <v1-токен>» https://netbox.example.com/api/dcim/sites/
• curl -H "Authorization: Bearer nbt_4F9DAouzURLb.zjebxBPzICiPbWz0Wtx0fTL7bCKXKGTYhNzkgC2S" https://netbox.example.com/api/dcim/sites/

Откуда берётся ValueError и что это за баг #21117

Именно эта новая криптографическая схема и требует параметр API_TOKEN_PEPPERS в configuration.py — без него нечем «подсаливать» HMAC-хеш нового токена. Проблема версии 4.5.0 была не в том, что параметр обязателен сам по себе (это ожидаемо и описано в документации), а в том, как система вела себя при его отсутствии: вместо понятного сообщения об ошибке или мягкой блокировки формы создания v2-токена сервер падал с необработанным ValueError, который долетал до пользователя как голая ошибка 500. Это подтверждённый баг сообщества NetBox — issue #21117 в основном репозитории netbox-community/netbox, воспроизведённый ровно на свежей установке 4.5.0 (Python 3.12.3): чистый конфиг без API_TOKEN_PEPPERS, попытка создать v2-токен через веб-форму — и падение с трейсбеком <class 'ValueError'>: API_TOKEN_PEPPERS is not defined.

Issue закрыт как принятый баг (severity — medium, назначен мейнтейнеру jeremystretch) и исправлен в патче 4.5.1, который вышел 20 января 2026 года — через две недели после GA. В описании исправления прямо сказано: «Avoid ValueError exception when API_TOKEN_PEPPERS is not defined» — то есть чинили именно обработку отсутствующего параметра, а не саму логику хеширования. После патча поведение стало предсказуемым и задокументированным: NetBox запускается и работает даже без API_TOKEN_PEPPERS в конфиге, но создание и использование v2-токенов остаётся недоступным, пока параметр не задан — без падения интерфейса, с понятным сообщением вместо трейсбека. В текущем коде модели Token это видно прямо: при сохранении v2-токена без перца NetBox отдаёт ошибку валидации «Unable to save v2 tokens: API_TOKEN_PEPPERS is not defined.», а не роняет запрос.

У «Доверительного дома» в момент обращения стояла версия 4.5.0 — то есть именно тот релиз, где баг ещё не пофикшен. Первым шагом мы не стали городить обходной путь, а обновили инсталляцию до 4.5.1 (позже — до актуальной на тот момент 4.5-ветки), и только вторым шагом добавили сам параметр в конфиг. Обновление NetBox без изменения конфигурации саму проблему не решает — это чинит только поведение при ошибке, а не отсутствие обязательной настройки.

Как правильно задать API_TOKEN_PEPPERS

Формат параметра — словарь Python, где ключ — числовой идентификатор перца, а значение — сама строка-перец. Документация NetBox рекомендует начинать нумерацию с 1 и держать в конфиге хотя бы одну запись (пример — в блоке команд ниже; строку из документации в прод не копируйте, там прямо написано «DO NOT USE THIS EXAMPLE PEPPER IN PRODUCTION»).

Требование к длине жёсткое и явно прописано в документации: pepper должен быть не короче 50 символов. Генерировать его руками или урезанным паролем не стоит — для этого в поставке NetBox есть отдельный скрипт generate_secret_key.py, который лежит в $INSTALL_ROOT/netbox/generate_secret_key.py при установке из архива или git; для установки в виде Python-пакета документация предлагает команду netbox secret-key из виртуального окружения. Тот же скрипт исторически используется и для генерации SECRET_KEY, но это два разных параметра с разным назначением: SECRET_KEY подписывает сессии и служебные токены Django, API_TOKEN_PEPPERS — отдельная сущность, специально выделенная под хеширование v2 API-токенов, и путать их (или использовать один и тот же секрет для обоих) не следует.

Числовой идентификатор перца — не декоративная деталь. Он даёт возможность ротации: у каждого v2-токена в базе хранится pepper_id, а для новых токенов NetBox берёт перец с наибольшим идентификатором. Когда придёт время сменить перец (например, по регламенту ИБ раз в год), добавьте в словарь запись под идентификатором 2, не удаляя 1, — токены, хешированные под старым перцем, продолжат проверяться, а все новые будут использовать актуальный. Удалять старую запись стоит только после того, как все токены, выпущенные под ней, переизданы или отозваны — иначе они перестанут проходить аутентификацию без предупреждения, потому что сервер не найдёт нужный идентификатор перца в словаре.

Отдельно про установку из официального образа netbox-community/netbox-docker — там путь немного другой. Шаблонный configuration/configuration.py этого проекта уже содержит код, который сам собирает словарь API_TOKEN_PEPPERS из переменной окружения: API_TOKEN_PEPPERS.update({1: api_token_pepper}), где значение api_token_pepper читается из API_TOKEN_PEPPER_1 (через _read_secret, то есть подхватится и из Docker-секрета в /run/secrets/, если он у вас настроен именно так). Важная деталь: в стоковом шаблоне зашит только один слот — под идентификатором 1; поддержки API_TOKEN_PEPPER_2 и далее там нет, так что для честной ротации через несколько перцев в Docker-варианте придётся доработать configuration.py руками, а не просто добавить вторую переменную окружения. И ещё деталь: в стоковом docker-compose.yml сервис netbox-worker наследует настройки netbox (включая env_file: env/netbox.env), поэтому переменную API_TOKEN_PEPPER_1 проще всего положить именно в env/netbox.env. Если вы переопределяли окружение сервисов в docker-compose.override.yml по отдельности, проверьте, что конфигурация у netbox и netbox-worker не разъехалась.

• API_TOKEN_PEPPERS = { 1: 'kp7ht*76fiQAhUi5dHfASLlYUE_S^gI^(7J^K5M!LfoH@vl&b_', }
• python3 /opt/netbox/netbox/generate_secret_key.py
• netbox secret-key

Кейс «Доверительный дом»: что я поменял и сколько это заняло

Помимо самого параметра, в «Доверительном доме» пришлось разбираться ещё с одной вещью — старыми v1-токенами, выпущенными до обновления. Их у клиента было девять: пять для интеграций (Zabbix — включая действия с правами system.run, скрипт бэкапа конфигов свитчей, система инвентаризации техники, две учётные интеграции с внутренним порталом) и четыре персональных, заведённых инженерами «на всякий случай» ещё в 2023 году и, как выяснилось при ревизии, забытых. Все девять продолжали работать после апгрейда — это ожидаемо, v1-токены не отключаются автоматически, — но раз уж дошло до полного описания доступа к CMDB, четыре забытых токена мы отозвали сразу, а пять рабочих интеграций переиздали уже в формате v2, обновив у каждой заголовок с Authorization: Token … на Authorization: Bearer nbt_….….

Вся работа заняла один рабочий день: час на диагностику самой ошибки и сверку с issue #21117 на GitHub, два часа на обновление NetBox до патч-версии 4.5.1 с проверкой в тестовом контуре, час на генерацию pepper и добавление API_TOKEN_PEPPERS в конфигурацию, и оставшееся время — на инвентаризацию и переиздание токенов интеграций с проверкой каждой в отдельности (чтобы ночной скрипт сверки с Zabbix не встал молча из-за неверного заголовка). Отдельно зафиксировали дату следующей плановой ротации перца — через 12 месяцев, синхронно с общим циклом смены секретов у клиента.

Пример из практики, который стоит учесть заранее: генерировать pepper и обновлять configuration.py лучше вне часов пиковой нагрузки на API, даже если формально это не требует простоя всего NetBox. Добавление API_TOKEN_PEPPERS не требует миграции базы данных и не перезаписывает существующие v1-токены — но применяется только после перезапуска процессов NetBox (в контейнерной установке — netbox и netbox-worker), а на время перезапуска API временно недоступен для всех интеграций, не только для новых v2-токенов.

Чек-лист миграции с v1 на v2 и сроки, на которые ориентироваться

Прежде чем переиздавать токены массово, я рекомендую пройти по короткому списку, который снимает большинство сюрпризов. Во-первых, обновиться минимум до 4.5.1, если вы ещё на 4.5.0 — баг с ValueError исправлен именно там, и продолжать работать на версии с открытым падением формы токенов бессмысленно. Во-вторых, задать API_TOKEN_PEPPERS с одним перцем не короче 50 символов, сгенерированным через generate_secret_key.py или netbox secret-key, а не подобранным вручную. В-третьих, провести инвентаризацию действующих v1-токенов — как правило, забытые токены обнаруживаются у любого клиента, у которого NetBox прожил больше года.

Дальше — переиздать в v2 те токены, что реально используются интеграциями, обновив заголовок Authorization в каждом клиенте API (скрипты, Zabbix, системы мониторинга, собственные дашборды), и отозвать те, что не используются вовсе. Держать в уме дедлайн: v1-токены официально устарели с версии 4.6 (релиз — май 2026 года) и будут полностью удалены в 5.0. Если для интеграций вы публикуете REST API NetBox через отдельный маршрут в reverse-прокси, заодно проверьте сам путь — лишний или пропущенный слеш в proxy_pass ломает запросы точно так же исправно, как неверный заголовок токена, просто с другим кодом ответа. Конкретной даты выхода 5.0 в опубликованных release notes на сегодняшний день (23 сентября 2026 года, актуальная версия — 4.7 от начала сентября) нет, но откладывать миграцию до последнего момента — плохая идея: чем больше интеграций держится на v1, тем больнее переключаться разом, когда deprecation превратится в удаление.

Отдельно стоит завести регламент ротации перца — как с любым долгоживущим секретом. Раз в год (а для более чувствительных сред — раз в квартал) генерировать новую запись в API_TOKEN_PEPPERS под следующим идентификатором, переиздавать активные токены под новым перцем и только после этого убирать старую запись из словаря. Это тот же принцип, что я закладываю при любом аудите информационной безопасности: секрет без плана ротации рано или поздно становится секретом, который никто не помнит, зачем менять.

Частые вопросы