netbox-administration

NetBox 管理

NetBox の管理に関する情報は古くなっている可能性があります。 設定、認証バックエンド、権限モデルはリリースごとに変更されます。事前学習済みの知識より、情報を取得して確認してください。

情報の取得元

情報源	URL / 方法	用途
インストールのドキュメント	https://netboxlabs.com/docs/netbox/installation/	セットアップ、依存関係、アップグレード
設定のドキュメント	https://netboxlabs.com/docs/netbox/configuration/	すべての設定項目
認証のドキュメント	https://netboxlabs.com/docs/netbox/administration/authentication/overview/	LDAP、SAML、OIDC、SSO
NetBox リポジトリ	https://github.com/netbox-community/netbox	ソースコード、リリースノート
NetBox MCP サーバー	設定済みの場合 — インスタンスのステータスとユーザー権限を確認	現在の設定状態の確認

NetBox サーバーのインストールを設定、保護、保守、トラブルシューティングする必要がある場合は、このスキルを使用してください。API の利用パターンについては、netbox-api-integration を参照してください。

クイックリファレンス

サービス管理

sudo systemctl restart netbox netbox-rq   # After config changes
sudo systemctl status netbox netbox-rq     # Check health

基本的な管理コマンド

コマンド	用途
python manage.py nbshell	NetBox の対話型シェル
python manage.py reindex	検索インデックスを再構築
python manage.py trace_paths	ケーブル経路のトレースを再構築
python manage.py rebuild_prefixes	プレフィックス階層を再構築
python manage.py runscript	カスタムスクリプトを実行（コアスクリプトは 4.7 で非推奨、5.0 で削除 — netbox-custom-scripts を参照）
python manage.py rebuild_config_context_cache [--force]	(4.7) レンダリング済みの設定コンテキストキャッシュを生成します。--force を指定すると、シグナルを回避した書き込み後に、生成済みのエントリーを再レンダリングします
python manage.py rebuild_ltree_paths [--check] [app.Model ...]	(4.7) 古い階層 path／sort_path 列を検出（--check、ロックなし）または修復します

ハウスキーピング：4.4 以降、ハウスキーピングは組み込みのシステムジョブによって自動的に実行されます。housekeeping の cron ジョブは削除してください。手動の python manage.py housekeeping コマンドは 4.7 で削除されます。4.6 では引き続き実行できますが、FutureWarning が出力されます。

主なファイルの場所

ファイル	用途
netbox/netbox/configuration.py	メイン設定（Python モジュール）
netbox/netbox/ldap_config.py	LDAP 設定（使用する場合）
local_requirements.txt	追加の Python パッケージ
gunicorn.py	WSGI サーバーの設定

設定

設定は Python モジュールである configuration.py に記述されています。NETBOX_CONFIGURATION 環境変数でパスを上書きできます。変更後は、sudo systemctl restart netbox で再起動してください。

必須パラメーター

パラメーター	用途
ALLOWED_HOSTS	Host ヘッダー検証用の FQDN／IP
DATABASES	PostgreSQL 接続
REDIS	Redis 設定 — tasks と caching には必ず別々の DB IDを使用してください
SECRET_KEY	Django のシークレット（50 文字以上、絶対に公開しないでください）
API_TOKEN_PEPPERS	v2 トークンのハッシュ化に使用するペッパー辞書（4.5 以降）

動的パラメーターと静的パラメーター

一部のパラメーターは動的で、再起動せずに Admin > System > Configuration で編集できます。configuration.py にハードコードされた値は、UI で設定された値より常に優先されます。

動的パラメーターには、CHANGELOG_RETENTION、CHANGELOG_RETAIN_CREATE_LAST_UPDATE（4.6 — 古いレコードを整理する際、各オブジェクトの作成時のレコードと最新の更新レコードを保持します）、JOB_RETENTION、MAINTENANCE_MODE、MAX_PAGE_SIZE、BANNER_*、GRAPHQL_ENABLED、CUSTOM_VALIDATORS、PROTECTION_RULES などがあります。

NetBox 4.7 の設定変更 — アップグレードする前に、これらを configuration.py で修正してください。

• SENTRY_DSN、SENTRY_SAMPLE_RATE、SENTRY_SEND_DEFAULT_PII、SENTRY_TRACES_SAMPLE_RATE は削除されました — これらは SENTRY_CONFIG のキー（dsn、sample_rate など）として設定してください。SENTRY_CONFIG に dsn がない状態で SENTRY_ENABLED = True にすると、起動に失敗します。
• JINJA2_FILTERS は JINJA_FILTERS に名称が変更されました（旧名称は 5.0 まで DeprecationWarning とともに使用できます）。
• メールを送信するには EMAIL['SERVER'] が必須です — 省略すると、起動時ではなく送信時に InvalidMailer が発生します。
• 新しい WEBHOOK_DEFAULT_TIMEOUT（デフォルトは 60 s）は、RQ_DEFAULT_TIMEOUT より小さくする必要があります。そうでない場合、NetBox は起動に失敗します — RQ_DEFAULT_TIMEOUT を 60 以下に設定している場合は、明示的に設定してください。
• 新しい BULK_UPDATE_CHUNK_SIZE（デフォルトは 5000）は、一括 UPDATE の行数を制限します。この数を超えるオブジェクトに対する、デフォルト値付きのカスタムフィールドの作成や削除は、バックグラウンドジョブに移されます。

パラメーターの全カタログについては、references/configuration-guide.md を参照してください。

認証

NetBox は複数の認証バックエンドに対応しており、順番に試行します。REMOTE_AUTH_BACKEND（文字列またはリスト）で設定します。

バックエンドのオプション

バックエンド	用途	設定場所
ローカル（デフォルト）	小規模なチーム、中央 IdP がない環境	configuration.py（AUTH_PASSWORD_VALIDATORS）
LDAP	Active Directory / OpenLDAP 環境	ldap_config.py（別ファイル）
リモートユーザー	リバースプロキシ認証（nginx/Apache）	configuration.py（REMOTE_AUTH_*）
ソーシャル認証	SAML、OIDC、OAuth2（Azure AD、Okta、Keycloak など）	configuration.py（SOCIAL_AUTH_*）

認証に関するよくある注意点

1. Gunicorn によるヘッダーの削除 — gunicorn v22.0+ はアンダースコアを含む HTTP ヘッダーを警告なしに破棄します。リモート認証ヘッダーを使う場合は、gunicorn の設定に header_map = dangerous を追加してください。
2. LOGIN_FORM_HIDDEN によるログイン不能 — SSO が機能せず、ログインフォームが非表示になっている場合、ログインする方法がありません。設定を編集して再起動する必要があります。
3. バックエンドの順序が重要 — バックエンドは順番に試行され、最初に成功したものが使用されます。LDAP とローカル認証を併用する場合は、意図した順序になっていることを確認してください。
4. プロキシ経由のクライアント IP（NetBox 4.6.1+）— HTTP_CLIENT_IP_HEADERS は、クライアント IP の判定に使うリクエストヘッダーを制御します（デフォルトは ('HTTP_X_REAL_IP', 'HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR')）。IP ベースのトークン制限（allowed_ips）やログで、プロキシではなく実際のクライアントアドレスが使われるよう、リバースプロキシに合わせて設定してください。
5. LOGIN_REQUIRED は非推奨です（4.6、v5.0 で削除予定）。新規デプロイでの使用は推奨しないでください。匿名アクセスは DEFAULT_PERMISSIONS / EXEMPT_VIEW_PERMISSIONS で制御します。
6. 4.7 での SSO ライブラリのメジャーアップデート — social-auth-app-django 6.0 / social-auth-core 5.1。アップグレード前に、本番以外の 4.7 インスタンスですべての SAML/OIDC バックエンドをテストしてください。検証が完了するまで、ローカル認証情報を持つ管理者と LOGIN_FORM_HIDDEN = False を維持してください。

設定の詳細については、references/authentication-backends.md を参照してください。

権限

NetBox は、Django に組み込まれたモデルレベルの権限ではなく、オブジェクトベースの権限を使用します。

オブジェクト権限モデル

各 ObjectPermission には、次の要素があります。

• オブジェクトタイプ — 適用対象となるモデル
• アクション — view、add、change、delete（および run などのカスタムアクション）
• 制約 — 対象オブジェクトを制限する JSON ベースの ORM フィルター

制約の構文

# AND — single dict
{"status": "active", "region__name": "US"}

# OR — list of dicts
[{"vid__gte": 100}, {"status": "reserved"}]

# Current user reference
{"created_by": "$user"}

# Django lookups supported: __in, __gte, __lt, __startswith, __isnull, etc.

制約はメモリ上のインスタンスではなく、データベースレコードに対して評価されます。作成または変更時には、NetBox はアトミックトランザクション内で保存した後に再クエリを実行します。制約に一致しない場合、ロールバックされます。

トークン管理

NetBox 4.5 以降：v2 トークンは Bearer nbt_<key>.<token> 形式を使用します。平文は保存されません（HMAC-SHA256 ダイジェストのみ）。設定に API_TOKEN_PEPPERS が必要です。4.6.1 以降では、v2 の平文トークンは作成レスポンスで一度だけ返されます。その際に取得してください。 v1 トークン（Token <plaintext> 形式）：正式に4.6 で非推奨となり、v5.0 で削除されます。5.0 にアップグレードする前に、すべての連携を v2 トークンに移行してください。

NetBox 4.7 以降：token フィールドはREST での作成時に読み取り専用となり、クライアントは平文を選択できなくなりました（指定した値は無視されます）。REST 経由でカスタムスクリプトを実行するには、write_enabled = true のトークンが必要です。4.7.0／4.7.1 では、?background=true の一括リクエストで作成されたトークンの平文がジョブ結果に記録されていました（ジョブを表示できる人なら誰でも読み取れます）。≥4.7.3 を実行し（4.7.3 では、ブランチに対応したバックグラウンド書き込みと config-context omit 最適化も追加されています）、その方法で作成されたトークンをすべて置き換えてください。

トークンの機能：write_enabled（読み取り専用の切り替え。(4.7) では REST スクリプトの実行も制御）、allowed_ips（IP 制限）、expires、enabled（ソフト無効化）。

重要：DEFAULT_PERMISSIONS

DEFAULT_PERMISSIONS は、認証済みユーザー全員に適用されます。デフォルトでは、トークンの自己管理が許可されます。カスタムの DEFAULT_PERMISSIONS を設定すると、これらのデフォルトが消去されるため、必要に応じてトークンの権限を再設定する必要があります。

詳細は、references/permissions-guide.md を参照してください。

運用

バックアップのチェックリスト

1. データベース：pg_dump --username netbox netbox > netbox.sql
   • バックアップのサイズを小さくするには、変更履歴を除外します：--exclude-table-data=core_objectchange
2. メディア：tar -czf netbox_media.tar.gz netbox/media/
3. 設定ファイル：configuration.py、ldap_config.py、local_requirements.txt、gunicorn.py
4. カスタムスクリプト：SCRIPTS_ROOT ディレクトリ
5. シークレット：外部に保存している場合は、SECRET_KEY と API_TOKEN_PEPPERS
6. 復元：psql -v ON_ERROR_STOP=1（または pg_restore --exit-on-error）を使用し、終了ステータスを確認してください。通常の psql は、部分的な復元でも成功を報告します。この方法で復元した 4.7.0 のダンプでは、ltree のカスケードトリガーが通知なく失われます（4.7.1 で修正済み）。4.7.0 から復元またはアップグレードした後は、python manage.py rebuild_ltree_paths --check を実行してください。

復元手順については、references/backup-restore.md を参照してください。

アップグレード手順

1. 現在のバージョンから対象バージョンまでのすべてのリリースノートを確認し、すべてのプラグインが対象リリースをサポートしていることを確認します
2. データベースとメディアをバックアップします
3. 参照先の互換性マトリクスに照らして、バージョンの互換性（Python、PostgreSQL、Redis）を確認します
4. メジャーバージョンはスキップできません — まず現在のメジャーバージョンの最新のマイナーバージョンにアップグレードします
5. ワーカーを停止する前に、RQ キューが空になるまで待ちます（Admin > Background Tasks）
6. 新しいバージョンを展開／チェックアウトし、設定ファイルをコピーします
7. sudo ./upgrade.sh を実行します
8. サービスを再起動します：sudo systemctl restart netbox netbox-rq

NetBox 4.7：Python 3.12–3.14、PostgreSQL 15 以降が必須（システムチェックにより、14 では migrate が中止されます）、Redis 6.0 以降が必須、Django 6.1。PostgreSQL の ltree 拡張機能が必要です。NetBox DB ユーザーがデータベースに対する CREATE 権限を持っている場合、マイグレーションによって自動的にインストールされます（GRANT CREATE ON DATABASE netbox TO netbox;）。または、DBA が事前に CREATE EXTENSION IF NOT EXISTS ltree; を実行してインストールできます。アップグレードには長時間かかり、実質的に元に戻せません：MPTT から ltree へのマイグレーションでは、データのバックフィル中に ACCESS EXCLUSIVE ロックが保持され、その後、rebuild_config_context_cache がデバイス／VM ごとに 1 回ずつ UPDATE を実行します。バックアップを取り、メンテナンス時間を計画してください。アップグレード前にキューに入れられた send_webhook ジョブは TypeError で失敗するため、先にキューを空にしてください。4.7.3 以降を実行してください（4.7.0／4.7.1 のトークン平文露出、4.7.0 の pg_dump によるトリガー消失、4.7.3 のブランチセーフなバックグラウンド書き込みと設定コンテキスト省略時のパフォーマンス）。 NetBox 4.5～4.6：Python 3.12～3.14、PostgreSQL 14 以降（14 は 4.6 で非推奨 — 4.7 より前に 15 以降へ移行してください）、Redis 5.0 以降。4.6 は Django 6.0、4.5 は Django 5.x を実行します。

手順については、references/upgrade-procedures.md を参照してください。

パフォーマンスの調整

主なパラメーター

パラメーター	デフォルト	影響
CONN_MAX_AGE（DATABASES 内）	300	DB 接続を維持し、オーバーヘッドを削減します
MAX_PAGE_SIZE	1000	API レスポンスのサイズを制限し、過剰なクエリを防ぎます
LOGIN_PERSISTENCE	False	True の場合、認証済みリクエストごとにDB 書き込みが発生します
CHANGELOG_RETENTION	90 日	最も急速に増大するテーブルである core_objectchange を自動的に整理します
RQ_DEFAULT_TIMEOUT	300	バックグラウンドタスクのタイムアウトです。負荷の高いスクリプトでは増やしてください。(4.7) WEBHOOK_DEFAULT_TIMEOUT より大きくする必要があります
WEBHOOK_DEFAULT_TIMEOUT (4.7)	60	リクエストごとの Webhook タイムアウト（1～3600 s）です。Webhook 自体の timeout フィールドがこの値より優先されます
BULK_UPDATE_CHUNK_SIZE (4.7)	5000	一括 UPDATE ステートメントあたりの行数です。大規模なバックフィルで statement_timeout に達する場合は値を小さくしてください（None を指定するとチャンク化を無効にします）

Redis：DB を分ける必要があります

tasks と caching には必ず異なる Redis DB ID を使用してください。 同じ DB を共有している場合、キャッシュ DB をフラッシュすると、キューに入っているバックグラウンドジョブが消失します。

PostgreSQL の調整

大規模なデプロイでは、PostgreSQL レベルで調整します：

• shared_buffers — RAM の 25%
• work_mem — クエリの複雑さに応じて 4～16MB
• effective_cache_size — RAM の 50～75%
• 最も急速に増大する core_objectchange テーブルのサイズを監視します

アンチパターン

問題	原因	対処方法
v2 トークンを利用できない	API_TOKEN_PEPPERS が設定されていない	pepper 辞書を設定に追加します
SECRET_KEY のローテーションでセッションが壊れる	すべてのセッション／トークンが無効化されます	移行期間を計画します。ユーザーは再認証が必要です
EXEMPT_VIEW_PERMISSIONS = ['*'] では不十分	ワイルドカードは機密性の高いモデルを除外します	必要に応じて、追加のモデルを明示的に列挙します
CHANGELOG_RETENTION = 0	無期限に保持され、データベースが際限なく増大します	0 以外の値を設定します（デフォルトは 90 日です）
読み取り専用スタンバイで認証できない	セッションがデータベースに保存されています	ファイルベースのセッションには SESSION_FILE_PATH を使用します
メトリクスエンドポイントが 404 を返す	METRICS_ENABLED = False	True に設定して再起動します
NetBox 4.6.0 を実行している	テンプレートの environment_params による RCE（CVE-2026-29514）	≥4.6.1 を実行します。ExportTemplate／config-template の編集権限はコード実行と同等の権限として扱い、制限します
NetBox 4.7.0／4.7.1 を実行している	?background=true を使った一括リクエストで作成されたトークンの平文が、ジョブ結果に記録されます	≥4.7.3 を実行します（4.7.3 ではブランチセーフなバックグラウンド書き込みと、config-context の omit 最適化も導入されています）。該当するトークンは漏えいしたものとして扱い、交換します
4.7 へのアップグレード後に NetBox が起動しない（webhook タイムアウトエラー）	デフォルトの WEBHOOK_DEFAULT_TIMEOUT = 60 に対して、RQ_DEFAULT_TIMEOUT が 60 以下です	WEBHOOK_DEFAULT_TIMEOUT を RQ_DEFAULT_TIMEOUT より小さく設定します
NetBox がメールを送信するときに InvalidMailer が発生する（4.7）	EMAIL['SERVER'] が設定されていません	EMAIL = {'SERVER': ..., ...} を設定します。Django の EMAIL_* 設定は、もう設定されません
新規作成または編集したオブジェクトがグローバル検索に表示されない（4.7）	検索インデックスの更新がバックグラウンドジョブに延期されます	netbox-rq が稼働していることを確認します。多少の遅延は想定どおりです（ワーカーが存在しない場合のみ、更新は同期的に行われます）
名前変更または移動したリージョン、ロケーションなどが子孫に反映されない（4.7）	ON_ERROR_STOP を指定せずに 4.7.0 のダンプからデータベースを復元したため、ltree トリガーがありません	≥4.7.1 にアップグレードし、rebuild_ltree_paths --check を実行してから、rebuild_ltree_paths <app.model> を実行します

バージョンに関する注意事項

NetBox 4.7（2026-09-02）

• プラットフォーム：ltree を含む PostgreSQL 15 以降、Redis 6.0 以降、Django 6.1。時間がかかり、実質的に元に戻せないアップグレードです。references/upgrade-procedures.md を参照してください。≥4.7.3 を実行してください（4.7.0／4.7.1 ではトークン漏えいがあり、4.7.3 ではブランチセーフなバックグラウンド書き込みと config-context の omit 最適化が導入されています）。
• 削除：housekeeping 管理コマンド、SENTRY_DSN／SENTRY_SAMPLE_RATE／SENTRY_SEND_DEFAULT_PII／SENTRY_TRACES_SAMPLE_RATE（SENTRY_CONFIG を使用してください）。
• 設定：JINJA2_FILTERS → JINJA_FILTERS、WEBHOOK_DEFAULT_TIMEOUT と BULK_UPDATE_CHUNK_SIZE を追加、EMAIL['SERVER'] が必須、Django の MAILERS が EMAIL_* 設定に置き換わります（EMAIL_HOST などを読み取るプラグインコードや、バックエンドを明示して get_connection() を呼び出すコードは動作しなくなります）。
• セキュリティ：REST トークンの token は作成時に読み取り専用です。REST スクリプトの実行には書き込み可能なトークンが必要です。カスタムリンクの request コンテキストはサニタイズされた一部の値（id、path、path_info、method、GET、user のみ。Cookie、ヘッダー、セッションは含まれません）です。URL カスタムフィールドは ALLOWED_URL_SCHEMES に照らして検証されます（スキームのない値は https:// として保存されます）。
• 動作：グローバル検索インデックスの更新はバックグラウンドジョブに延期されます。BULK_UPDATE_CHUNK_SIZE を超えるオブジェクトに対する、デフォルト値付きのカスタムフィールド作成および削除はジョブに延期されます。config context はデバイス／VM ごとに事前レンダリングされ、キャッシュされます（rebuild_config_context_cache）。
• 非推奨：コアのカスタムスクリプト（4.8 までサポートされ、5.0 で削除）と、それに伴う SCRIPTS_ROOT。netbox-custom-scripts を参照してください。
• インストール方法：NetBox は PyPI で公開されています。Python パッケージによるインストール／アップグレード（netbox upgrade --no-input）は実験的なため、本番環境では使用しないでください。

NetBox 4.6 (2026-05-05)

• Django 6.0；PostgreSQL 14 は非推奨です；housekeeping コマンドは非推奨です（FutureWarning）；LOGIN_REQUIRED は非推奨です；v1 トークンは非推奨です（5.0 で削除）；v2 の平文は作成時に一度だけ返され、HTTP_CLIENT_IP_HEADERS が追加されました（4.6.1+）；CHANGELOG_RETAIN_CREATE_LAST_UPDATE が追加されました。≥4.6.1 を実行してください（CVE-2026-29514）。