NetBox server administration: configuration, authentication backends (local/LDAP/SAML/OIDC), object permissions, API tokens, performance tuning, backups, upgrades, and housekeeping. Use when managing a NetBox instance rather than consuming its API.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
netbox-administration
description
NetBox server administration: configuration, authentication backends (local/LDAP/SAML/OIDC), object permissions, API tokens, performance tuning, backups, upgrades, and housekeeping. Use when managing a NetBox instance rather than consuming its API.
license
Apache-2.0
NetBox Administration
Your knowledge of NetBox administration may be outdated. Configuration settings, authentication backends, and permission models evolve between releases. Prefer retrieval over pre-trained knowledge.
If configured — check instance status, user permissions
Verify current config state
Use this skill when you need to configure, secure, maintain, or troubleshoot a NetBox server installation. For API consumption patterns, see netbox-api-integration.
Quick Reference
Service Management
sudo systemctl restart netbox netbox-rq # After config changessudo systemctl status netbox netbox-rq # Check health
Essential Management Commands
Command
Purpose
python manage.py nbshell
Interactive NetBox shell
python manage.py reindex
Rebuild search index
python manage.py trace_paths
Rebuild cable path traces
python manage.py rebuild_prefixes
Rebuild prefix hierarchy
python manage.py runscript
Execute a custom script
Housekeeping: Since 4.4, housekeeping runs automatically via the built-in system job — remove any housekeeping cron jobs. The manual python manage.py housekeeping command is formally deprecated in 4.6 (removal in a future release) but still ships and runs; on 4.6 it just emits a FutureWarning.
Key File Locations
File
Purpose
netbox/netbox/configuration.py
Main config (Python module)
netbox/netbox/ldap_config.py
LDAP settings (if used)
local_requirements.txt
Extra Python packages
gunicorn.py
WSGI server config
Configuration
Configuration lives in configuration.py — a Python module. Override its path with NETBOX_CONFIGURATION env var. After changes, restart: sudo systemctl restart netbox.
Required Parameters
Parameter
Purpose
ALLOWED_HOSTS
FQDNs/IPs for Host header validation
DATABASES
PostgreSQL connection(s)
REDIS
Redis config — must use separate DB IDs for tasks vs caching
SECRET_KEY
Django secret (≥50 chars, never expose)
API_TOKEN_PEPPERS
Pepper dict for v2 token hashing (4.5+)
Dynamic vs Static Parameters
Some parameters are dynamic — editable at Admin > System > Configuration without restart. Hard-coded values in configuration.py always take precedence over UI-set values.
Dynamic parameters include: CHANGELOG_RETENTION, CHANGELOG_RETAIN_CREATE_LAST_UPDATE (4.6 — keep each object's original create + latest update record when pruning), JOB_RETENTION, MAINTENANCE_MODE, MAX_PAGE_SIZE, BANNER_*, GRAPHQL_ENABLED, CUSTOM_VALIDATORS, PROTECTION_RULES, and others.
Gunicorn header stripping — gunicorn v22.0+ silently drops HTTP headers with underscores. Add header_map = dangerous to gunicorn config for remote auth headers.
LOGIN_FORM_HIDDEN lockout — If SSO breaks and the login form is hidden, there's no way to log in. Must edit config and restart.
Backend order matters — Backends are tried in sequence; first success wins. Ensure intentional ordering when combining LDAP + local.
Client IP behind a proxy (NetBox 4.6.1+) — HTTP_CLIENT_IP_HEADERS controls which request headers determine the client IP (default ('HTTP_X_REAL_IP', 'HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR')). Set it to match your reverse proxy so IP-based token restrictions (allowed_ips) and logging see the real client address, not the proxy.
LOGIN_REQUIRED is deprecated (4.6, removal in v5.0). Don't recommend it for new 4.6 deployments; anonymous access is governed by DEFAULT_PERMISSIONS / EXEMPT_VIEW_PERMISSIONS.
NetBox uses object-based permissions instead of Django's built-in model-level permissions.
Object Permission Model
Each ObjectPermission has:
Object types — which models it applies to
Actions — view, add, change, delete (plus custom like run)
Constraints — JSON-based ORM filters restricting which objects
Constraint Syntax
# 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.
Constraints are evaluated against the database record, not the in-memory instance. For create/change, NetBox saves in an atomic transaction then re-queries — if the constraint doesn't match, it rolls back.
Token Management
NetBox 4.5+: v2 tokens use Bearer nbt_<key>.<token> format. Plaintext is never stored (HMAC-SHA256 digest only). Requires API_TOKEN_PEPPERS in config. On 4.6.1+ the v2 plaintext token is returned exactly once, in the creation response — capture it then.
v1 tokens (Token <plaintext> format): formally deprecated in 4.6, removed in v5.0. Migrate all integrations to v2 tokens before upgrading to 5.0.
DEFAULT_PERMISSIONS applies to all authenticated users. The default grants token self-management. Setting custom DEFAULT_PERMISSIONS erases these defaults — you must reproduce token permissions if desired.
NetBox 4.5–4.6: Python 3.12–3.14, PostgreSQL 14+, Redis 4.0+. 4.6 runs on Django 6.0 (4.5 was Django 5.x) and deprecates PostgreSQL 14 — 15+ will be required from v4.7. Plan a PostgreSQL upgrade to 15+ before moving past 4.6.
