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.

Retrieval Sources

Use this skill when you need to configure, secure, maintain, or troubleshoot a NetBox server installation. For API consumption patterns, see [netbox-api-integration](../netbox-api-integration/SKILL.md).

Quick Reference

Service Management

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

Essential Management Commands

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

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

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: CHANGELOGRETENTION, CHANGELOGRETAINCREATELASTUPDATE (4.6 — keep each object's original create + latest update record when pruning), JOBRETENTION, MAINTENANCEMODE, MAXPAGESIZE, BANNER*, GRAPHQLENABLED, CUSTOMVALIDATORS, PROTECTION_RULES, and others.

See [references/configuration-guide.md](references/configuration-guide.md) for the complete parameter catalog.

Authentication

NetBox supports multiple authentication backends, tried in order. Configure via REMOTEAUTHBACKEND (string or list).

Backend Options

Common Auth Gotchas

1. Gunicorn header stripping — gunicorn v22.0+ silently drops HTTP headers with underscores. Add header_map = dangerous to gunicorn config for remote auth headers.
2. LOGINFORMHIDDEN lockout — If SSO breaks and the login form is hidden, there's no way to log in. Must edit config and restart.
3. Backend order matters — Backends are tried in sequence; first success wins. Ensure intentional ordering when combining LDAP + local.
4. Client IP behind a proxy (NetBox 4.6.1+) — HTTPCLIENTIPHEADERS controls which request headers determine the client IP (default ('HTTPXREALIP', 'HTTPXFORWARDEDFOR', 'REMOTEADDR')). Set it to match your reverse proxy so IP-based token restrictions (allowed_ips) and logging see the real client address, not the proxy.
5. LOGINREQUIRED is deprecated (4.6, removal in v5.0). Don't recommend it for new 4.6 deployments; anonymous access is governed by DEFAULTPERMISSIONS / EXEMPTVIEWPERMISSIONS.

See [references/authentication-backends.md](references/authentication-backends.md) for setup details.

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 APITOKEN_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.

Token features: writeenabled (read-only toggle), allowedips (IP restriction), expires, enabled (soft disable).

Critical: DEFAULT_PERMISSIONS

DEFAULTPERMISSIONS applies to all authenticated users. The default grants token self-management. Setting custom DEFAULTPERMISSIONS erases these defaults — you must reproduce token permissions if desired.

See [references/permissions-guide.md](references/permissions-guide.md) for complete details.

Operations

Backup Checklist

1. Database: pg_dump --username netbox netbox > netbox.sql

- Exclude changelog for smaller backups: --exclude-table-data=core_objectchange

1. Media: tar -czf netbox_media.tar.gz netbox/media/
2. Config files: configuration.py, ldapconfig.py, localrequirements.txt, gunicorn.py
3. Custom scripts: SCRIPTS_ROOT directory
4. Secrets: SECRETKEY and APITOKEN_PEPPERS if stored externally

See [references/backup-restore.md](references/backup-restore.md) for restore procedures.

Upgrade Process

1. Review all release notes between current and target version
2. Back up database and media
3. Check version compatibility (Python, PostgreSQL, Redis)
4. Cannot skip major versions — upgrade to latest minor of current major first
5. Extract/checkout new version, copy config files
6. Run sudo ./upgrade.sh
7. Restart services: sudo systemctl restart netbox netbox-rq

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.

See [references/upgrade-procedures.md](references/upgrade-procedures.md) for step-by-step instructions.

Performance Tuning

Key Parameters

Redis: Separate DBs Required

Always use different Redis DB IDs for tasks and caching. Flushing the cache DB will destroy queued background jobs if they share the same DB.

PostgreSQL Tuning

For large deployments, tune at the PostgreSQL level:

• shared_buffers — 25% of RAM
• work_mem — 4-16MB depending on query complexity
• effectivecachesize — 50-75% of RAM
• Monitor core_objectchange table size — it grows fastest

Anti-Patterns