# NetBox Documentation
> NetBox is an open source web application for managing and documenting network infrastructure.
These are docs for LLMs for NetBox 4.3.0.
## Documentation Index
- [index.md](https://netboxlabs.com/docs/netbox/en/stable/index/)
- [Introduction](https://netboxlabs.com/docs/netbox/en/stable/introduction/)
- Features
- [Facilities](https://netboxlabs.com/docs/netbox/en/stable/features/facilities/)
- [Devices & Cabling](https://netboxlabs.com/docs/netbox/en/stable/features/devices-cabling/)
- [Power Tracking](https://netboxlabs.com/docs/netbox/en/stable/features/power-tracking/)
- [IPAM](https://netboxlabs.com/docs/netbox/en/stable/features/ipam/)
- [VLAN Management](https://netboxlabs.com/docs/netbox/en/stable/features/vlan-management/)
- [L2VPN & Overlay](https://netboxlabs.com/docs/netbox/en/stable/features/l2vpn-overlay/)
- [Circuits](https://netboxlabs.com/docs/netbox/en/stable/features/circuits/)
- [Wireless](https://netboxlabs.com/docs/netbox/en/stable/features/wireless/)
- [Virtualization](https://netboxlabs.com/docs/netbox/en/stable/features/virtualization/)
- [VPN Tunnels](https://netboxlabs.com/docs/netbox/en/stable/features/vpn-tunnels/)
- [Tenancy](https://netboxlabs.com/docs/netbox/en/stable/features/tenancy/)
- [Contacts](https://netboxlabs.com/docs/netbox/en/stable/features/contacts/)
- [Search](https://netboxlabs.com/docs/netbox/en/stable/features/search/)
- [Context Data](https://netboxlabs.com/docs/netbox/en/stable/features/context-data/)
- [Configuration Rendering](https://netboxlabs.com/docs/netbox/en/stable/features/configuration-rendering/)
- [Synchronized Data](https://netboxlabs.com/docs/netbox/en/stable/features/synchronized-data/)
- [Change Logging](https://netboxlabs.com/docs/netbox/en/stable/features/change-logging/)
- [Journaling](https://netboxlabs.com/docs/netbox/en/stable/features/journaling/)
- [Event Rules](https://netboxlabs.com/docs/netbox/en/stable/features/event-rules/)
- [Notifications](https://netboxlabs.com/docs/netbox/en/stable/features/notifications/)
- [Background Jobs](https://netboxlabs.com/docs/netbox/en/stable/features/background-jobs/)
- [Auth & Permissions](https://netboxlabs.com/docs/netbox/en/stable/features/authentication-permissions/)
- [API & Integration](https://netboxlabs.com/docs/netbox/en/stable/features/api-integration/)
- [Customization](https://netboxlabs.com/docs/netbox/en/stable/features/customization/)
- Installation & Upgrade
- [Installing NetBox](https://netboxlabs.com/docs/netbox/en/stable/installation/index/)
- [1. PostgreSQL](https://netboxlabs.com/docs/netbox/en/stable/installation/1-postgresql/)
- [2. Redis](https://netboxlabs.com/docs/netbox/en/stable/installation/2-redis/)
- [3. NetBox](https://netboxlabs.com/docs/netbox/en/stable/installation/3-netbox/)
- [4a. Gunicorn](https://netboxlabs.com/docs/netbox/en/stable/installation/4a-gunicorn/)
- [4b. uWSGI](https://netboxlabs.com/docs/netbox/en/stable/installation/4b-uwsgi/)
- [5. HTTP Server](https://netboxlabs.com/docs/netbox/en/stable/installation/5-http-server/)
- [6. LDAP (Optional)](https://netboxlabs.com/docs/netbox/en/stable/installation/6-ldap/)
- [Upgrading NetBox](https://netboxlabs.com/docs/netbox/en/stable/installation/upgrading/)
- Getting Started
- [Planning](https://netboxlabs.com/docs/netbox/en/stable/getting-started/planning/)
- [Populating Data](https://netboxlabs.com/docs/netbox/en/stable/getting-started/populating-data/)
- Configuration
- [Configuring NetBox](https://netboxlabs.com/docs/netbox/en/stable/configuration/index/)
- [Required Parameters](https://netboxlabs.com/docs/netbox/en/stable/configuration/required-parameters/)
- [System](https://netboxlabs.com/docs/netbox/en/stable/configuration/system/)
- [Security](https://netboxlabs.com/docs/netbox/en/stable/configuration/security/)
- [GraphQL API](https://netboxlabs.com/docs/netbox/en/stable/configuration/graphql-api/)
- [Remote Authentication](https://netboxlabs.com/docs/netbox/en/stable/configuration/remote-authentication/)
- [Data & Validation](https://netboxlabs.com/docs/netbox/en/stable/configuration/data-validation/)
- [Default Values](https://netboxlabs.com/docs/netbox/en/stable/configuration/default-values/)
- [Error Reporting](https://netboxlabs.com/docs/netbox/en/stable/configuration/error-reporting/)
- [Plugins](https://netboxlabs.com/docs/netbox/en/stable/configuration/plugins/)
- [Miscellaneous](https://netboxlabs.com/docs/netbox/en/stable/configuration/miscellaneous/)
- [Development](https://netboxlabs.com/docs/netbox/en/stable/configuration/development/)
- Customization
- [Custom Fields](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-fields/)
- [Custom Links](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-links/)
- [Custom Validation](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-validation/)
- [Export Templates](https://netboxlabs.com/docs/netbox/en/stable/customization/export-templates/)
- [Reports](https://netboxlabs.com/docs/netbox/en/stable/customization/reports/)
- [Custom Scripts](https://netboxlabs.com/docs/netbox/en/stable/customization/custom-scripts/)
- Integrations
- [REST API](https://netboxlabs.com/docs/netbox/en/stable/integrations/rest-api/)
- [GraphQL API](https://netboxlabs.com/docs/netbox/en/stable/integrations/graphql-api/)
- [Webhooks](https://netboxlabs.com/docs/netbox/en/stable/integrations/webhooks/)
- [Synchronized Data](https://netboxlabs.com/docs/netbox/en/stable/integrations/synchronized-data/)
- [Prometheus Metrics](https://netboxlabs.com/docs/netbox/en/stable/integrations/prometheus-metrics/)
- Plugins
- [About Plugins](https://netboxlabs.com/docs/netbox/en/stable/plugins/index/)
- [Installing a Plugin](https://netboxlabs.com/docs/netbox/en/stable/plugins/installation/)
- [Removing a Plugin](https://netboxlabs.com/docs/netbox/en/stable/plugins/removal/)
- Developing Plugins
- [Getting Started](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/index/)
- [Models](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/models/)
- [Views](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/views/)
- [Navigation](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/navigation/)
- [Templates](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/templates/)
- [Tables](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/tables/)
- [Forms](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/forms/)
- [Filters & Filter Sets](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/filtersets/)
- [Search](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/search/)
- [Event Types](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/event-types/)
- [Data Backends](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/data-backends/)
- [REST API](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/rest-api/)
- [GraphQL API](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/graphql-api/)
- [Background Jobs](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/background-jobs/)
- [Dashboard Widgets](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/dashboard-widgets/)
- [Exceptions](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/exceptions/)
- [Migrating to v4.0](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/migration-v4/)
- Administration
- Authentication
- [Overview](https://netboxlabs.com/docs/netbox/en/stable/administration/authentication/overview/)
- [Google](https://netboxlabs.com/docs/netbox/en/stable/administration/authentication/google/)
- [Microsoft Entra ID](https://netboxlabs.com/docs/netbox/en/stable/administration/authentication/microsoft-entra-id/)
- [Okta](https://netboxlabs.com/docs/netbox/en/stable/administration/authentication/okta/)
- [Permissions](https://netboxlabs.com/docs/netbox/en/stable/administration/permissions/)
- [Error Reporting](https://netboxlabs.com/docs/netbox/en/stable/administration/error-reporting/)
- [Housekeeping](https://netboxlabs.com/docs/netbox/en/stable/administration/housekeeping/)
- [Replicating NetBox](https://netboxlabs.com/docs/netbox/en/stable/administration/replicating-netbox/)
- [NetBox Shell](https://netboxlabs.com/docs/netbox/en/stable/administration/netbox-shell/)
- Data Model
- Circuits
- [Circuit](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/circuit/)
- [CircuitGroup](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/circuitgroup/)
- [CircuitGroupAssignment](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/circuitgroupassignment/)
- [Circuit Termination](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/circuittermination/)
- [Circuit Type](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/circuittype/)
- [Provider](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/provider/)
- [Provider Account](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/provideraccount/)
- [Provider Network](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/providernetwork/)
- [Virtual Circuit](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/virtualcircuit/)
- [Virtual Circuit Termination](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/virtualcircuittermination/)
- [Virtual Circuit Type](https://netboxlabs.com/docs/netbox/en/stable/models/circuits/virtualcircuittype/)
- Core
- [DataFile](https://netboxlabs.com/docs/netbox/en/stable/models/core/datafile/)
- [DataSource](https://netboxlabs.com/docs/netbox/en/stable/models/core/datasource/)
- [Job](https://netboxlabs.com/docs/netbox/en/stable/models/core/job/)
- DCIM
- [Cable](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/cable/)
- [ConsolePort](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/consoleport/)
- [ConsolePortTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/consoleporttemplate/)
- [ConsoleServerPort](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/consoleserverport/)
- [ConsoleServerPortTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/consoleserverporttemplate/)
- [Device](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/device/)
- [DeviceBay](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/devicebay/)
- [DeviceBayTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/devicebaytemplate/)
- [DeviceRole](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/devicerole/)
- [DeviceType](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/devicetype/)
- [FrontPort](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/frontport/)
- [FrontPortTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/frontporttemplate/)
- [Interface](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/interface/)
- [InterfaceTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/interfacetemplate/)
- [InventoryItem](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/inventoryitem/)
- [InventoryItemRole](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/inventoryitemrole/)
- [InventoryItemTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/inventoryitemtemplate/)
- [Location](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/location/)
- [MACAddress](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/macaddress/)
- [Manufacturer](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/manufacturer/)
- [Module](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/module/)
- [ModuleBay](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/modulebay/)
- [ModuleBayTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/modulebaytemplate/)
- [ModuleType](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/moduletype/)
- [ModuleTypeProfile](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/moduletypeprofile/)
- [Platform](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/platform/)
- [PowerFeed](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/powerfeed/)
- [PowerOutlet](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/poweroutlet/)
- [PowerOutletTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/poweroutlettemplate/)
- [PowerPanel](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/powerpanel/)
- [PowerPort](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/powerport/)
- [PowerPortTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/powerporttemplate/)
- [Rack](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/rack/)
- [RackReservation](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/rackreservation/)
- [RackRole](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/rackrole/)
- [RackType](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/racktype/)
- [RearPort](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/rearport/)
- [RearPortTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/rearporttemplate/)
- [Region](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/region/)
- [Site](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/site/)
- [SiteGroup](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/sitegroup/)
- [VirtualChassis](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/virtualchassis/)
- [VirtualDeviceContext](https://netboxlabs.com/docs/netbox/en/stable/models/dcim/virtualdevicecontext/)
- Extras
- [Bookmark](https://netboxlabs.com/docs/netbox/en/stable/models/extras/bookmark/)
- [ConfigContext](https://netboxlabs.com/docs/netbox/en/stable/models/extras/configcontext/)
- [ConfigTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/extras/configtemplate/)
- [CustomField](https://netboxlabs.com/docs/netbox/en/stable/models/extras/customfield/)
- [CustomFieldChoiceSet](https://netboxlabs.com/docs/netbox/en/stable/models/extras/customfieldchoiceset/)
- [CustomLink](https://netboxlabs.com/docs/netbox/en/stable/models/extras/customlink/)
- [EventRule](https://netboxlabs.com/docs/netbox/en/stable/models/extras/eventrule/)
- [ExportTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/extras/exporttemplate/)
- [ImageAttachment](https://netboxlabs.com/docs/netbox/en/stable/models/extras/imageattachment/)
- [JournalEntry](https://netboxlabs.com/docs/netbox/en/stable/models/extras/journalentry/)
- [Notification](https://netboxlabs.com/docs/netbox/en/stable/models/extras/notification/)
- [NotificationGroup](https://netboxlabs.com/docs/netbox/en/stable/models/extras/notificationgroup/)
- [SavedFilter](https://netboxlabs.com/docs/netbox/en/stable/models/extras/savedfilter/)
- [Subscription](https://netboxlabs.com/docs/netbox/en/stable/models/extras/subscription/)
- [TableConfig](https://netboxlabs.com/docs/netbox/en/stable/models/extras/tableconfig/)
- [Tag](https://netboxlabs.com/docs/netbox/en/stable/models/extras/tag/)
- [Webhook](https://netboxlabs.com/docs/netbox/en/stable/models/extras/webhook/)
- IPAM
- [ASN](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/asn/)
- [ASNRange](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/asnrange/)
- [Aggregate](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/aggregate/)
- [FHRPGroup](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/fhrpgroup/)
- [FHRPGroupAssignment](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/fhrpgroupassignment/)
- [IPAddress](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/ipaddress/)
- [IPRange](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/iprange/)
- [Prefix](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/prefix/)
- [RIR](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/rir/)
- [Role](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/role/)
- [RouteTarget](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/routetarget/)
- [Service](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/service/)
- [ServiceTemplate](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/servicetemplate/)
- [VLAN](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/vlan/)
- [VLANGroup](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/vlangroup/)
- [VLANTranslationPolicy](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/vlantranslationpolicy/)
- [VLANTranslationRule](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/vlantranslationrule/)
- [VRF](https://netboxlabs.com/docs/netbox/en/stable/models/ipam/vrf/)
- Tenancy
- [Contact](https://netboxlabs.com/docs/netbox/en/stable/models/tenancy/contact/)
- [ContactGroup](https://netboxlabs.com/docs/netbox/en/stable/models/tenancy/contactgroup/)
- [ContactRole](https://netboxlabs.com/docs/netbox/en/stable/models/tenancy/contactrole/)
- [Tenant](https://netboxlabs.com/docs/netbox/en/stable/models/tenancy/tenant/)
- [TenantGroup](https://netboxlabs.com/docs/netbox/en/stable/models/tenancy/tenantgroup/)
- Virtualization
- [Cluster](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/cluster/)
- [ClusterGroup](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/clustergroup/)
- [ClusterType](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/clustertype/)
- [VMInterface](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/vminterface/)
- [VirtualDisk](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/virtualdisk/)
- [VirtualMachine](https://netboxlabs.com/docs/netbox/en/stable/models/virtualization/virtualmachine/)
- VPN
- [IKEPolicy](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/ikepolicy/)
- [IKEProposal](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/ikeproposal/)
- [IPSecPolicy](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/ipsecpolicy/)
- [IPSecProfile](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/ipsecprofile/)
- [IPSecProposal](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/ipsecproposal/)
- [L2VPN](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/l2vpn/)
- [L2VPNTermination](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/l2vpntermination/)
- [Tunnel](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/tunnel/)
- [TunnelGroup](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/tunnelgroup/)
- [TunnelTermination](https://netboxlabs.com/docs/netbox/en/stable/models/vpn/tunneltermination/)
- Wireless
- [WirelessLAN](https://netboxlabs.com/docs/netbox/en/stable/models/wireless/wirelesslan/)
- [WirelessLANGroup](https://netboxlabs.com/docs/netbox/en/stable/models/wireless/wirelesslangroup/)
- [WirelessLink](https://netboxlabs.com/docs/netbox/en/stable/models/wireless/wirelesslink/)
- Reference
- [Filtering](https://netboxlabs.com/docs/netbox/en/stable/reference/filtering/)
- [Conditions](https://netboxlabs.com/docs/netbox/en/stable/reference/conditions/)
- [Markdown](https://netboxlabs.com/docs/netbox/en/stable/reference/markdown/)
- Development
- [Introduction](https://netboxlabs.com/docs/netbox/en/stable/development/index/)
- [Getting Started](https://netboxlabs.com/docs/netbox/en/stable/development/getting-started/)
- [Style Guide](https://netboxlabs.com/docs/netbox/en/stable/development/style-guide/)
- [Models](https://netboxlabs.com/docs/netbox/en/stable/development/models/)
- [Adding Models](https://netboxlabs.com/docs/netbox/en/stable/development/adding-models/)
- [Extending Models](https://netboxlabs.com/docs/netbox/en/stable/development/extending-models/)
- [Signals](https://netboxlabs.com/docs/netbox/en/stable/development/signals/)
- [Search](https://netboxlabs.com/docs/netbox/en/stable/development/search/)
- [Application Registry](https://netboxlabs.com/docs/netbox/en/stable/development/application-registry/)
- [User Preferences](https://netboxlabs.com/docs/netbox/en/stable/development/user-preferences/)
- [Web UI](https://netboxlabs.com/docs/netbox/en/stable/development/web-ui/)
- [Internationalization](https://netboxlabs.com/docs/netbox/en/stable/development/internationalization/)
- [Translations](https://netboxlabs.com/docs/netbox/en/stable/development/translations/)
- [Release Checklist](https://netboxlabs.com/docs/netbox/en/stable/development/release-checklist/)
- [git Cheat Sheet](https://netboxlabs.com/docs/netbox/en/stable/development/git-cheat-sheet/)
- Release Notes
- [Summary](https://netboxlabs.com/docs/netbox/en/stable/release-notes/index/)
- [Version 4.3](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-4.3/)
- [Version 4.2](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-4.2/)
- [Version 4.1](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-4.1/)
- [Version 4.0](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-4.0/)
- [Version 3.7](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.7/)
- [Version 3.6](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.6/)
- [Version 3.5](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.5/)
- [Version 3.4](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.4/)
- [Version 3.3](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.3/)
- [Version 3.2](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.2/)
- [Version 3.1](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.1/)
- [Version 3.0](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-3.0/)
- [Version 2.11](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.11/)
- [Version 2.10](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.10/)
- [Version 2.9](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.9/)
- [Version 2.8](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.8/)
- [Version 2.7](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.7/)
- [Version 2.6](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.6/)
- [Version 2.5](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.5/)
- [Version 2.4](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.4/)
- [Version 2.3](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.3/)
- [Version 2.2](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.2/)
- [Version 2.1](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.1/)
- [Version 2.0](https://netboxlabs.com/docs/netbox/en/stable/release-notes/version-2.0/)
## Embedded Documentation
URL: https://netboxlabs.com/docs/netbox/en/stable/index/
=== BEGIN FILE ===
# The Premier Network Source of Truth
NetBox is a solution for modeling and documenting networks, integrating IP address management (IPAM) and datacenter infrastructure management (DCIM) with APIs and extensions. It serves as a "source of truth" for network automation, utilized by organizations globally.
## Built for Networks
NetBox features a specialized data model for network engineers, offering various object types for infrastructure design and documentation, including:
* Hierarchical regions, sites, and locations
* Racks, devices, and device components
* Cables and wireless connections
* Power distribution tracking
* Data circuits and providers
* Virtual machines and clusters
* IP prefixes, ranges, and addresses
* VRFs and route targets
* FHRP groups (VRRP, HSRP, etc.)
* AS numbers
* VLANs and scoped VLAN groups
* L2VPN overlays
* Tenancy assignments
* Contact management
## Customizable & Extensible
NetBox allows extensive customization through:
* Custom fields
* Custom model validation
* Export templates
* Event rules
* Plugins
* REST & GraphQL APIs
## Always Open
NetBox is open source under the Apache 2 license, ensuring code accessibility and community-driven development. Contributions can be made via the [GitHub repository](https://github.com/netbox-community/netbox).
## Powered by Python
Built on the Django framework, NetBox enables users to extend its functionality using Python scripts and plugins.
## Getting Started
* Try the [public demo](https://demo.netbox.dev/)
* Follow the [installation guide](./installation/index.md) for deployment
* Use the community [Docker image](https://github.com/netbox-community/netbox-docker) for easy setup
* Explore [NetBox Cloud](https://netboxlabs.com/netbox-cloud) for a managed solution by [NetBox Labs](https://netboxlabs.com/)
=== END FILE ===
**Introduction**
URL: https://netboxlabs.com/docs/netbox/en/stable/introduction/
=== BEGIN FILE ===
# Introduction to NetBox
## Origin Story
NetBox was developed by Jeremy Stretch at DigitalOcean in 2015 to automate network provisioning and was released as an open source project in June 2016. It has since been adopted by many organizations as a central network source of truth, managed by NetBox Labs and community maintainers, with numerous plugins available.
## Key Features
NetBox serves network engineers and operators with core features including:
* IP address management (IPAM) with full IPv4/IPv6 parity
* Automatic provisioning of next available prefix/IP
* VRFs with import & export route targets
* VLANs with variably-scoped groups
* AS number (ASN) management
* Rack elevations with SVG rendering
* Device modeling using pre-defined types
* Virtual chassis and device contexts
* Network, power, and console cabling with SVG traces
* Breakout cables
* Power distribution modeling
* Data circuit and provider tracking
* Wireless LAN and point-to-point links
* VPN tunnels
* IKE & IPSec policies
* Layer 2 VPN overlays
* FHRP groups (VRRP, HSRP, etc.)
* Application service bindings
* Virtual machines & clusters
* Flexible hierarchy for sites and locations
* Tenant ownership assignment
* Device & VM configuration contexts for advanced configuration rendering
* Custom fields for data model extension
* Custom validation & protection rules
* Custom reports & scripts executable directly within the UI
* Extensive plugin framework for adding custom functionality
* Single sign-on (SSO) authentication
* Robust object-based permissions
* Detailed, automatic change logging
* Global search engine
* Event-driven scripts & webhooks
## What NetBox Is Not
NetBox does not provide:
* Network monitoring
* DNS server
* RADIUS server
* Configuration management
* Facilities management
However, it can effectively populate external tools with necessary data.
## Design Philosophy
NetBox's design is based on:
### Replicate the Real World
The data model reflects a real-world network, assigning IP addresses to interfaces rather than devices.
### Serve as a "Source of Truth"
NetBox represents the desired state of a network, discouraging automated imports of live data to ensure integrity.
### Keep it Simple
NetBox favors simple solutions to maintain a lean codebase and low learning curve.
## Application Stack
NetBox is built on the Django framework and uses a PostgreSQL database, running as a WSGI service behind an HTTP server.
| Function | Component |
|--------------------|-------------------|
| HTTP service | nginx or Apache |
| WSGI service | gunicorn or uWSGI |
| Application | Django/Python |
| Database | PostgreSQL 14+ |
| Task queuing | Redis/django-rq |
=== END FILE ===
**Features**
**Facilities**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/facilities/
=== BEGIN FILE ===
# Facilities
NetBox enables modeling of a network's presence from global regions to individual equipment racks using various models.
## Regions
Regions represent geographic domains for network presence, such as countries or cities, and can be nested hierarchically. Example hierarchy:
* Europe
* France
* Germany
* Spain
* North America
* Canada
* United States
* California
* New York
* Texas
Regions are listed alphabetically and have no maximum nesting depth.
## Site Groups
Site groups allow for functional grouping of sites in a recursive hierarchy, distinguishing between corporate, branch, or customer sites, complementing the geographic organization of regions.
## Sites
A site represents a building within a region/site group, assigned an operational status, mailing address, and GPS coordinates.
## Locations
Locations are logical subdivisions within a building (e.g., floors or rooms) and can be nested hierarchically. Each location has an operational status.
## Rack Types
Rack types define unique specifications for racks, including weight, height, and unit ordering, allowing for the creation of new racks in NetBox.
## Racks
Racks are discrete objects within a site/location for device installation, each with an operational status, type, facility ID, and inventory attributes. Racks must define height and width, and can track space in half-unit increments.
!!! tip "Devices"
A device can be installed within a site, location, or rack, providing flexibility in organization.
=== END FILE ===
**Devices & Cabling**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/devices-cabling/
=== BEGIN FILE ===
# Devices & Cabling
NetBox is a tool for modeling network infrastructure, with the device object being crucial. A device represents physical hardware like servers, routers, or switches, which can be mounted in racks. Resources like network interfaces and console ports are modeled as components, which can be grouped into modules.
Device types represent unique real-world models, allowing users to define a type and replicate device instances easily.
## Manufacturers
Manufacturers represent organizations producing hardware devices, defined by users to reflect actual entities.
## Device Types
A device type combines manufacturer and hardware model, mapping to real-world devices. Components like network interfaces and device bays are created on device types, allowing for easy replication when new devices are added.
* Components that can be modeled:
* Interfaces
* Console ports
* Console server ports
* Power ports
* Power outlets
* Pass-through ports
* Module bays
* Device bays
Example of a Juniper EX4300-48T device type components:
* Console port ("Console")
* Power ports ("PSU0", "PSU1")
* 1GE interfaces ("ge-0/0/0" to "ge-0/0/47")
* 10GE interfaces ("xe-0/2/0" to "xe-0/2/3")
Component instantiation occurs only at device creation; changes to device types do not retroactively affect existing devices.
## Devices
A device represents actual hardware installed in the real world, with attributes like operational status and software platform. Components are instantiated from the assigned device type.
### Virtual Chassis
Virtual chassis model multiple devices sharing a management plane, with one device as the chassis master.
### Virtual Device Contexts
VDCs are logical partitions within a device, operating autonomously while sharing resources.
## Module Types & Modules
Module types instantiate discrete modules within devices, which can have child components. Device bays hold hardware with its own management plane, while module bays hold modules that do not operate independently.
Modules can have templated components automatically renamed based on their module bay.
## Cables
Cables in NetBox model connections among device components, with attributes like type, color, length, and label. Basic checks prevent invalid connections, such as connecting a network interface to a power outlet.
=== END FILE ===
**Power Tracking**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/power-tracking/
=== BEGIN FILE ===
# Power Tracking
NetBox's DCIM feature allows modeling facility power through discrete power panels and feeds, primarily for data centers but applicable to other environments.
## Power Panels
- Represents the upstream power element, typically a power distribution or breaker panel.
- Splits facility power into multiple circuits modeled as feeds.
- Associated with a site and optionally a specific location.
- No limit on the number of feeds per panel, but should reflect real-world objects.
## Power Feeds
- Represents a discrete power circuit from a power panel.
- Can have a name, operational status, and electrical characteristics (supply type, voltage, amperage).
- A device power port connects to a power feed via a cable, with only one port per feed.
- Multiple devices on one feed require a power distribution unit (PDU) to connect to multiple outlets.
!!! tip "Primary and Redundant Power"
- Each power feed is designated as primary or redundant for modeling power distribution topologies. Use primary for single, non-redundant supplies.
=== END FILE ===
**IPAM**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/ipam/
=== BEGIN FILE ===
# IP Address Management
IP address management (IPAM) is a key feature of NetBox, supporting IP4 and IPv6, VRF assignment, and automatic hierarchy formation.
## IP Hierarchy
NetBox uses various object types for IP resource hierarchy:
* **Aggregate** - Represents a large block of address space assigned to an RIR.
* **Prefix** - A subnet within an aggregate, which can have functional roles and operational statuses.
* **IP Range** - A range of IP addresses within a prefix, often used for DHCP scopes.
* **IP Address** - An individual IP address with its subnet mask, organized under its parent prefix.
Automatic hierarchy construction is managed by NetBox, eliminating manual assignments.
Example hierarchy:
* 100.64.0.0/10 (aggregate)
* 100.64.0.0/20 (prefix)
* 100.64.16.0/20 (prefix)
* 100.64.16.0/24 (prefix)
* 100.64.16.1/24 (address)
* 100.64.16.2/24 (address)
* 100.64.16.3/24 (address)
* 100.64.19.0/24 (prefix)
* 100.64.32.0/20 (prefix)
* 100.64.32.1/24 (address)
* 100.64.32.10-99/24 (range)
## Utilization Stats
Utilization rates for prefixes are calculated based on their status. _Container_ prefixes' rates depend on child prefixes, while other prefixes' rates depend on child IP addresses and ranges. Aggregate utilization is based on child prefixes.
## VRF Tracking
NetBox models VRF instances for multiple routing tables, allowing assignment of IP objects to specific VRFs, which maintain isolated IP hierarchies. Each VRF can enforce unique IP space, providing flexibility in modeling.
## AS Numbers
NetBox tracks autonomous system (AS) numbers, supporting both 16- and 32-bit ASNs, assigned to an authoritative RIR.
## Service Mapping
NetBox models network applications as service objects linked to devices or virtual machines, optionally with specific IP addresses. Services can be defined using templates for easier instantiation or created manually.
=== END FILE ===
**VLAN Management**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/vlan-management/
=== BEGIN FILE ===
# VLAN Management
NetBox tracks VLAN information to assist with layer two network configurations, defining VLANs per IEEE 802.1Q standards. VLANs can be assigned to groups and functional roles.
## VLAN Groups
- A VLAN group is a collection of VLANs within a specific scope.
- Each group can be associated with a site, location, or rack, designating a minimum and maximum VLAN ID (default: 1 to 4094).
- Each VLAN within a group must have a unique ID and name, with no limit on the number of groups per scope.
## VLANs
- VLANs are modeled with a 12-bit VLAN ID and a name, along with an operational status and optional function role.
- VLANs can be assigned to a VLAN group or site.
- VLANs can be associated with device and virtual machine interfaces, with each interface supporting an 802.1Q mode (access or tagged) for applying relevant VLANs as tagged or untagged.
=== END FILE ===
**L2VPN & Overlay**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/l2vpn-overlay/
=== BEGIN FILE ===
# L2VPN & Overlay
L2VPN and overlay networks (VXLAN, EVPN) can be defined in NetBox, linking to interfaces and VLANs for tracking overlay assets and their relationships with underlay resources.
- Each L2VPN instance has a type and optional unique identifier.
- L2VPNs can have import and export route targets assigned.
- Terminations can be created to assign VLANs and/or device and virtual machine interfaces to the overlay.
=== END FILE ===
**Circuits**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/circuits/
=== BEGIN FILE ===
# Circuits
NetBox is designed for managing network transit and peering providers and circuits, allowing for the modeling of physical circuits in data center and enterprise environments. It enables direct connections of circuits to device interfaces via cables.
## Providers
- A provider is any organization offering Internet or private connectivity, typically large carriers, regional providers, or internal services.
- Each provider can have account and contact details, and one or more AS numbers.
- Provider networks can be modeled as "black box" networks for circuits, often represented with cloud icons in topology diagrams, such as MPLS networks connecting multiple sites.
## Circuits
- A circuit is a physical connection between two points, installed and maintained by an external provider (e.g., a fiber optic Internet connection).
- Each circuit is linked to a provider and has a unique circuit ID, user-defined type, operational status, and other characteristics.
- Provider accounts can categorize circuits by business units or technologies.
- Circuits can have up to two terminations (A and Z), associated with a site or provider network, allowing for physical connectivity mapping via cables.
!!! warning "Physical vs. Virtual Circuits"
The circuit model in NetBox represents **physical** connections. Don't confuse these with _virtual_ circuits offered by providers overlaid on physical infrastructure. If you can't point to it, it's not a physical circuit.
=== END FILE ===
**Wireless**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/wireless/
=== BEGIN FILE ===
# Wireless
NetBox supports modeling both wireless LANs and point-to-point links alongside physical cable plants.
## Wireless LANs
A wireless LAN is a multi-access network for multiple clients, identified by an SSID and authentication parameters. They can be organized into self-nesting groups and optionally bound to a VLAN. Authentication attributes include:
* **Type** - Open, WEP, WPA, etc.
* **Cipher** - Auto, TKIP, or AES
* **Pre-shared key (PSK)** - The secret key for clients
Defining authentication parameters is optional.
## Wireless Links
A wireless link is a point-to-point connection between two stations, resembling cables but modeling wireless communications. Wireless links also have an SSID and optional authentication attributes.
=== END FILE ===
**Virtualization**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/virtualization/
=== BEGIN FILE ===
# Virtualization
Virtual machines and clusters can be modeled in NetBox alongside physical infrastructure, allowing for seamless integration between physical and virtual networks.
## Clusters
- A cluster consists of one or more physical host devices for running virtual machines.
- Each cluster must have a type and operational status, and may be assigned to a user-defined group.
- Designating one or more devices as hosts is optional.
## Virtual Machines
- A virtual machine is a virtualized compute instance, similar to device objects but without physical attributes.
- VMs can have interfaces with assigned IP addresses and VLANs, but cannot be connected via cables.
- Each VM can define its compute, memory, and storage resources.
=== END FILE ===
**VPN Tunnels**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/vpn-tunnels/
=== BEGIN FILE ===
# Tunnels
NetBox can model private tunnels among virtual termination points in a network, including implementations like GRE, IP-in-IP, and IPSec. Tunnels can terminate at two or more device or virtual machine interfaces and can be organized into user-defined groups.
# IPSec & IKE
NetBox supports modeling IPSec & IKE policies, which define encryption and authentication parameters for IPSec tunnels.
=== END FILE ===
**Tenancy**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/tenancy/
=== BEGIN FILE ===
# Tenancy
Most core objects within NetBox's data model support _tenancy_, which associates an object with a tenant to convey ownership or dependency. For example, enterprises may represent internal business units as tenants, while managed services providers may create tenants for each customer.
## Tenant Groups
Tenants can be grouped based on any logic required, with the ability to nest groups recursively. For instance, a "Customers" group can have child groups like "Current" and "Past." A tenant can be assigned to any level within this hierarchy.
## Tenants
The tenant model typically represents a customer or internal organization but can be adapted for various needs. Most core objects in NetBox can be assigned to a tenant, facilitating ownership correlation across object types. For example, customers can have their own racks, devices, IP addresses, circuits, etc., all tracked via tenant assignment.
The following objects can be assigned to tenants:
* Sites
* Racks
* Rack reservations
* Devices
* VRFs
* Prefixes
* IP addresses
* VLANs
* Circuits
* Clusters
* Virtual machines
Tenant assignment signifies ownership in NetBox, with each object owned by a single tenant. For example, a firewall dedicated to a customer would be assigned to that customer's tenant, while a firewall serving multiple customers would not have a specific tenant assignment.
=== END FILE ===
**Contacts**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/contacts/
=== BEGIN FILE ===
# Contacts
Contact assignment in NetBox allows tracking of resource ownership. A contact is an individual responsible for a resource within its assigned role.
## Contact Groups
Contacts can be grouped into a recursive hierarchy, with assignments possible at any level.
## Contact Roles
Contact roles define the relationship of a contact to an assigned object, such as administrative, operational, and emergency roles.
## Contacts
Each contact represents an individual or permanent point of contact, requiring a name and optionally including a title, phone number, email address, and related details. Contacts are unique and can be assigned to multiple NetBox objects without limit.
The following models support contact assignments:
* circuits.Circuit
* circuits.Provider
* circuits.ProviderAccount
* dcim.Device
* dcim.Location
* dcim.Manufacturer
* dcim.PowerPanel
* dcim.Rack
* dcim.Region
* dcim.Site
* dcim.SiteGroup
* tenancy.Tenant
* virtualization.Cluster
* virtualization.ClusterGroup
* virtualization.VirtualMachine
=== END FILE ===
**Search**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/search/
=== BEGIN FILE ===
# Search
## Global Search
NetBox features a global search engine that allows users to search across its data model. Relevant fields are indexed by precedence for optimal results. The search index updates in real-time upon object creation or modification. Users can specify lookup types like exact or partial match, with matching portions highlighted in results. Custom fields with search weights and plugin models can also be included in search results.
Note: Static choice fields are not indexed.
## Saved Filters
NetBox provides extensive filters for each object type, enabling complex queries. Users can save frequently used filters for future use. For instance, a query to find planned devices can be saved as:
```
?status=planned&device_type_id=78®ion_id=12
```
and reused as:
```
?filter=my-custom-filter
```
These saved filters are applicable in both the UI and API queries.
=== END FILE ===
**Context Data**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/context-data/
=== BEGIN FILE ===
# Context Data
Configuration context data (or "config contexts") allows users to define arbitrary data for devices and virtual machines based on specific characteristics. For example, syslog servers can be defined for devices in a region using a config context instance.
```json
{
"syslog-servers": [
"192.168.43.107",
"192.168.48.112"
]
}
```
This data can be accessed by remote API clients or used in configuration templates.
Config contexts can be computed based on various criteria:
| Type | Devices | Virtual Machines |
|---------------|------------------|------------------|
| Region | Yes | Yes |
| Site group | Yes | Yes |
| Site | Yes | Yes |
| Location | Yes | |
| Device type | Yes | |
| Role | Yes | Yes |
| Platform | Yes | Yes |
| Cluster type | | Yes |
| Cluster group | | Yes |
| Cluster | | Yes |
| Tenant group | Yes | Yes |
| Tenant | Yes | Yes |
| Tag | Yes | Yes |
Data can be stored in JSON format without restrictions.
## Hierarchical Rendering
Context data can be merged and overridden using multiple instances. For instance, different syslog servers can be defined for a device role with a higher-weight context overriding lower-weight data.
Example of a config context for a region:
```json
{
"ntp-servers": [
"172.16.10.22",
"172.16.10.33"
],
"syslog-servers": [
"172.16.9.100",
"172.16.9.101"
]
}
```
If a site within the region requires a local syslog server, a second config context with a higher weight can be created:
```json
{
"syslog-servers": [
"192.168.43.107"
]
}
```
The rendered context data for a device at this site would be:
```json
{
"ntp-servers": [
"172.16.10.22",
"172.16.10.33"
],
"syslog-servers": [
"192.168.43.107"
]
}
```
Higher-weight context data overwrites conflicting lower-weight data while preserving non-conflicting data.
## Local Context Data
Devices and virtual machines can have local context data, which always takes precedence over other config contexts. This is useful for specific deviations in data for particular objects.
Warning: If local context data is frequently defined for many devices or VMs, consider using custom fields for a more effective solution.
=== END FILE ===
**Configuration Rendering**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/configuration-rendering/
=== BEGIN FILE ===
# Configuration Rendering
NetBox enables the rendering of complete configuration files for network devices using configuration templates and context data.
## Configuration Templates
Templates are written in Jinja2 and can be populated from remote data sources. An example template for a network switch configuration is provided:
```jinja2
{% extends 'base.j2' %}
{% block content %}
system {
host-name {{ device.name }};
domain-name example.com;
time-zone UTC;
authentication-order [ password radius ];
ntp {
{% for server in ntp_servers %}
server {{ server }};
{% endfor %}
}
}
{% for interface in device.interfaces.all() %}
{% include 'common/interface.j2' %}
{% endfor %}
{% endblock %}
```
The `device` variable is populated with the device instance, and `ntp_servers` is sourced from context data.
### Context Data
The configuration rendering context includes the object as `device` or `virtualmachine`. NetBox model classes can also be accessed, e.g., `There are {{ dcim.Site.objects.count() }} sites.`
## Rendering Templates
### Device Configurations
NetBox offers a REST API endpoint for rendering the default configuration template for a device via a POST request:
```no-highlight
curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox:8000/api/dcim/devices/123/render-config/ \
--data '{
"extra_data": "abc123"
}'
```
The configuration template is resolved in the following order:
* Device-specific template
* Role-specific template
* Platform-specific template
If none are assigned, the request fails. The output format can be specified as JSON or plaintext.
### General Purpose Use
Templates can also be rendered without a specific device using a general-purpose REST API endpoint:
```no-highlight
curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox:8000/api/extras/config-templates/123/render/ \
--data '{
"foo": "abc",
"bar": 123
}'
```
=== END FILE ===
**Synchronized Data**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/synchronized-data/
=== BEGIN FILE ===
# Synchronized Data
NetBox supports automatic synchronization of local data from designated remote sources, such as configuration templates sourced from text files in a remote git repository. This is done using the core data source and data file models.
To enable synchronization, the NetBox administrator designates remote data sources, which can be:
* Git repository
* Amazon S3 bucket (or compatible product)
* Local disk path
(Local disk paths are considered "remote" as they exist outside NetBox's database.)
Data backends connecting to external sources may require additional Python libraries. The Git backend needs the `dulwich` package, while the S3 backend requires `boto3`. If using Git with `HTTP_PROXIES` configured for SOCKS, the `python_socks` library is also needed.
Each remote source type has specific configuration parameters, such as branch and authentication for git sources. After creating a source, a synchronization job replicates remote files into the local database.
Replicated data files can be associated with:
* Config contexts
* Config templates
* Export templates
When data is designated for a local instance, it replaces the local content. If the replicated file is updated, the local instance is flagged as out-of-date, allowing users to synchronize individually or in bulk. This two-stage process prevents immediate effects on production data.
A user must have the `core.sync_datasource` permission to synchronize local files from a remote data source.
=== END FILE ===
**Change Logging**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/change-logging/
=== BEGIN FILE ===
# Change Logging
Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object is saved to the database along with metadata such as the current time and the user associated with the change. These records create a persistent log of changes for each object and for NetBox overall, accessible via Other > Change Log.
A serialized representation of the modified instance is included in JSON format, similar to the REST API, but without nested representations. For example, the `tenant` field of a site records only the tenant's ID.
When a request is made, a UUID is generated and attached to change records from that request. Editing three objects in bulk will create three separate change records, all associated with the same UUID for easy identification.
Change records are available in the API at the read-only endpoint `/api/extras/object-changes/` and can be exported via the web UI in CSV format.
## Correlating Changes by Request
Each request to NetBox is assigned a unique ID to correlate change records. For instance, changing the status of three sites using the bulk edit feature results in three new change records, all referencing the same request ID, indicating they were made as part of the same request.
=== END FILE ===
**Journaling**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/journaling/
=== BEGIN FILE ===
# Journaling
All primary and organizational models in NetBox support journaling, which is a collection of human-generated notes and comments about an object for historical context. It supplements the change log by providing additional information about changes or events outside NetBox. Unlike the change log, journal entries persist for the life of their associated object.
Each journal entry includes:
- A selectable kind (info, success, warning, or danger)
- A user-populated `comments` field
- Automatic recording of the date, time, and associated user upon creation
=== END FILE ===
**Event Rules**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/event-rules/
=== BEGIN FILE ===
# Event Rules
NetBox can automatically perform functions in response to internal events, including:
* Executing a [custom script](../customization/custom-scripts.md)
* Sending a [webhook](../integrations/webhooks.md)
* Generating [user notifications](../features/notifications.md)
For instance, to configure a monitoring system to start monitoring a device when its operational status changes to active, a webhook can be created and associated with an event rule. This webhook will be sent automatically by NetBox when the specified conditions are met.
Each event must be linked to at least one NetBox object type and one event (e.g., create, update, delete).
## Conditional Event Rules
Event rules can include conditional logic in JSON to determine if an event triggers for a specific object. For example, to trigger an event for devices only when the `status` field is "active":
```json
{
"and": [
{
"attr": "status.value",
"value": "active"
}
]
}
```
Refer to the documentation for NetBox's [conditional logic](../reference/conditions.md) for more details.
## Event Rule Processing
Detected changes result in events being placed into a Redis queue for processing, allowing user requests to complete without waiting. Events are processed by the `rqworker` process, and the current event queue and any failed events can be viewed under System > Background Tasks.
=== END FILE ===
**Notifications**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/notifications/
=== BEGIN FILE ===
# Notifications
NetBox has a user notification system that allows users to mark notifications as read or delete them. Notifications can be generated through two main mechanisms:
* Users can subscribe to an object, receiving notifications when that object is modified.
* An [event rule](./event-rules.md) can be set up to automatically notify one or more users about specific system events.
Plugins in NetBox can also create their own notifications.
=== END FILE ===
**Background Jobs**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/background-jobs/
=== BEGIN FILE ===
# Background Jobs
NetBox allows execution of certain functions as background tasks, including:
* Report execution
* Custom script execution
* Synchronization of remote data sources
Plugins can enqueue their own background tasks using the Job model. Background tasks are executed by the `rqworker` process(es).
## Scheduled Jobs
Background jobs can be configured to run immediately or at a future time, with options for repeating at set intervals.
=== END FILE ===
**Auth & Permissions**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/authentication-permissions/
=== BEGIN FILE ===
# Authentication & Permissions
## Object-Based Permissions
NetBox features a comprehensive permissions system that surpasses the model-based permissions of Django. Key aspects of assigning permissions include:
* Types of objects the permission applies to
* Users/groups granted permissions
* Actions permitted (e.g., view, add, change)
* Constraints limiting permissions to specific object subsets
Constraints allow for per-object permissions, enabling users to interact with specific objects based on attributes. For example, a user may only view prefixes or IP addresses within a specific VRF. Constraints are defined in JSON format, similar to Django ORM queries. An example constraint for reserved VLANs with IDs between 100 and 199 is:
```json
[
{
"vid__gte": 100,
"vid__lt": 200
},
{
"status": "reserved"
}
]
```
Refer to the [permissions documentation](../administration/permissions.md) for further details.
## LDAP Authentication
NetBox supports LDAP authentication for user verification against a remote LDAP server. More information can be found in the [installation documentation](../installation/6-ldap.md).
## Single Sign-On (SSO)
NetBox utilizes the open source [python-social-auth](https://github.com/python-social-auth) library for SSO authentication, offering various options including:
* Cognito
* GitHub & GitHub Enterprise
* GitLab
* Google
* Hashicorp Vault
* Keycloak
* Microsoft Entra ID
* Microsoft Graph
* Okta
* OIDC
Custom backends can also be created using python-social-auth's base classes. Examples of SSO configuration in NetBox are available in the [authentication documentation](../administration/authentication/overview.md).
=== END FILE ===
**API & Integration**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/api-integration/
=== BEGIN FILE ===
# API & Integration
NetBox offers various features for integration with network tools.
## REST API
NetBox's REST API, using the Django REST Framework, allows for creating, modifying, and deleting objects via HTTP and JSON. It supports token-based authentication and is documented with OpenAPI. Example usage:
```no-highlight
curl -s -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
http://netbox/api/ipam/prefixes/ \
--data '{"prefix": "192.0.2.0/24", "site": {"name": "Branch 12"}}'
```
API client libraries are available for Python and Go. More details can be found in the [REST API documentation](../integrations/rest-api.md).
## GraphQL API
NetBox provides a GraphQL API for complex queries, allowing clients to retrieve specific data. It is read-only and also uses token-based authentication. Further information is available in the [GraphQL API documentation](../integrations/graphql-api.md).
## Webhooks
Webhooks notify external systems of changes in NetBox, such as device status updates. Users can create a webhook with a remote receiver and define an event rule to trigger it. This facilitates event-based automation. More details can be found in the [webhooks documentation](../integrations/webhooks.md).
## Prometheus Metrics
NetBox features a `/metrics` view for Prometheus scrapers, supported by the django-prometheus library. Additional information is available in the [Prometheus metrics documentation](../integrations/prometheus-metrics.md).
=== END FILE ===
**Customization**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/customization/
=== BEGIN FILE ===
# Customization
NetBox allows extensive customization to cater to unique user environments. Key features include:
## Tags
- User-created tags for organization and filtering.
- Tags can be filtered in API requests:
```no-highlight
GET /api/dcim/devices/?tag=monitored
```
- Multiple tags can be specified:
```no-highlight
GET /api/dcim/devices/?tag=monitored&tag=deprecated
```
## Bookmarks
- Users can bookmark frequently visited objects.
- Bookmarks can be filtered and ordered on personal dashboards.
## Custom Fields
- Administrators can create custom fields for additional data.
- Supports various data types, including strings, integers, and JSON.
- Custom fields are stored with the object and accessible via the REST API.
## Custom Links
- Reference external resources related to NetBox objects.
- Templatized links can be created, e.g.:
```no-highlight
http://server.local/vms/?name={{ object.name }}
```
## Custom Validation
- Enforce additional rules for object creation/modification.
- Example configuration:
```python
CUSTOM_VALIDATORS = {
"dcim.device": [
{
"name": {
"regex": "[a-z]+\d{3}"
},
"asset_tag": {
"required": True
}
}
]
}
```
## Export Templates
- Bulk export objects in CSV or custom formats using Jinja2 templates.
- Templates can output in various character-based formats.
## Reports
- Custom Python scripts for evaluating NetBox objects against rules.
- Can be executed via UI, REST API, or CLI, and can be scheduled.
## Custom Scripts
- More powerful than reports, allowing user input and task automation.
- Full Python environment available for advanced scripting capabilities.
=== END FILE ===
**Installation & Upgrade**
**Installing NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/index/
=== BEGIN FILE ===
# Installation
Check out the [NetBox Cloud Free Plan](https://netboxlabs.com/free-netbox-cloud/) to skip the installation process and get a preconfigured NetBox Cloud instance for free.
The installation instructions are tested on Ubuntu 22.04, and commands for other distributions may vary. Consult your distribution's documentation for errors.
### Setup Steps
1. [PostgreSQL database](1-postgresql.md)
2. [Redis](2-redis.md)
3. [NetBox components](3-netbox.md)
4. [Gunicorn](4a-gunicorn.md) or [uWSGI](4b-uwsgi.md)
5. [HTTP server](5-http-server.md)
6. [LDAP authentication](6-ldap.md) (optional)
### Requirements
| Dependency | Supported Versions |
|------------|--------------------|
| Python | 3.10, 3.11, 3.12 |
| PostgreSQL | 14+ |
| Redis | 4.0+ |
For upgrading from an existing installation, consult the [upgrading guide](upgrading.md).
=== END FILE ===
**1. PostgreSQL**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/1-postgresql/
=== BEGIN FILE ===
# PostgreSQL Database Installation
This section covers the installation and configuration of a local PostgreSQL database, specifically requiring PostgreSQL 14 or later for NetBox.
## Installation
```no-highlight
sudo apt update
sudo apt install -y postgresql
```
Verify the installation:
```no-highlight
psql -V
```
## Database Creation
Create a database for NetBox and assign a username and password:
```no-highlight
sudo -u postgres psql
```
In the PostgreSQL shell, execute:
```postgresql
CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'J5brHrAXFLQSif0K';
ALTER DATABASE netbox OWNER TO netbox;
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;
```
**Important Notes:**
- Use a strong password.
- Ensure the database uses `UTF8` encoding. Check with `\l`.
Exit the shell with `\q`.
## Verify Service Status
Test authentication with:
```no-highlight
$ psql --username netbox --password --host localhost netbox
```
If successful, you will see a `netbox` prompt. Use `\conninfo` to confirm the connection or `\q` to exit.
=== END FILE ===
**2. Redis**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/2-redis/
=== BEGIN FILE ===
# Redis Installation
## Install Redis
Redis is an in-memory key-value store used by NetBox for caching and queuing. This section covers the installation and configuration of a local Redis instance. If a Redis service is already available, proceed to the next section.
```no-highlight
sudo apt install -y redis-server
```
Verify that the installed version of Redis is at least v4.0:
```no-highlight
redis-server -v
```
You can modify the Redis configuration at `/etc/redis.conf` or `/etc/redis/redis.conf`, but the default configuration is usually sufficient.
## Verify Service Status
Use the `redis-cli` utility to check if the Redis service is operational:
```no-highlight
redis-cli ping
```
A successful response will return `PONG` from the server.
=== END FILE ===
**3. NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/3-netbox/
=== BEGIN FILE ===
# NetBox Installation
This section discusses installing and configuring the NetBox application.
## Install System Packages
Install required system packages for NetBox:
```bash
sudo apt install -y python3 python3-pip python3-venv python3-dev \
build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
libssl-dev zlib1g-dev
```
Check Python version:
```bash
python3 -V
```
## Download NetBox
Two options for installation: from a release archive or from the git repository.
### Option A: Download a Release Archive
Download the latest stable release:
```bash
sudo wget https://github.com/netbox-community/netbox/archive/refs/tags/vX.Y.Z.tar.gz
sudo tar -xzf vX.Y.Z.tar.gz -C /opt
sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox
```
### Option B: Clone the Git Repository
Create the base directory:
```bash
sudo mkdir -p /opt/netbox/
cd /opt/netbox/
```
Install git if not already installed:
```bash
sudo apt install -y git
```
Clone the repository:
```bash
sudo git clone https://github.com/netbox-community/netbox.git .
```
Check out the desired release tag:
```bash
sudo git checkout vX.Y.Z
```
## Create the NetBox System User
Create a system user account named `netbox`:
```bash
sudo adduser --system --group netbox
sudo chown --recursive netbox /opt/netbox/netbox/media/
sudo chown --recursive netbox /opt/netbox/netbox/reports/
sudo chown --recursive netbox /opt/netbox/netbox/scripts/
```
## Configuration
Copy the configuration example:
```bash
cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py
```
Edit `configuration.py` for required parameters:
* `ALLOWED_HOSTS`
* `DATABASES`
* `REDIS`
* `SECRET_KEY`
### ALLOWED_HOSTS
```python
ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
```
### DATABASES
```python
DATABASES = {
'default': {
'NAME': 'netbox',
'USER': 'netbox',
'PASSWORD': 'J5brHrAXFLQSif0K',
'HOST': 'localhost',
'PORT': '',
'CONN_MAX_AGE': 300,
}
}
```
### REDIS
```python
REDIS = {
'tasks': {
'HOST': 'localhost',
'PORT': 6379,
'PASSWORD': '',
'DATABASE': 0,
'SSL': False,
},
'caching': {
'HOST': 'localhost',
'PORT': 6379,
'PASSWORD': '',
'DATABASE': 1,
'SSL': False,
}
}
```
### SECRET_KEY
Generate a secret key:
```bash
python3 ../generate_secret_key.py
```
## Optional Requirements
Install optional packages in `local_requirements.txt`.
### Remote File Storage
```bash
sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
```
### Remote Data Sources
Add `boto3` for Amazon S3:
```bash
sudo sh -c "echo 'boto3' >> /opt/netbox/local_requirements.txt"
```
### Sentry Integration
```bash
sudo sh -c "echo 'sentry-sdk' >> /opt/netbox/local_requirements.txt"
```
## Run the Upgrade Script
Run the upgrade script:
```bash
sudo /opt/netbox/upgrade.sh
```
For Python version specification:
```bash
sudo PYTHON=/usr/bin/python3.10 /opt/netbox/upgrade.sh
```
## Create a Super User
Activate the virtual environment:
```bash
source /opt/netbox/venv/bin/activate
```
Create a superuser:
```bash
cd /opt/netbox/netbox
python3 manage.py createsuperuser
```
## Schedule the Housekeeping Task
Link the housekeeping script:
```bash
sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
```
## Test the Application
Run the development server:
```bash
python3 manage.py runserver 0.0.0.0:8000 --insecure
```
Open in a browser at .
```bash
firewall-cmd --zone=public --add-port=8000/tcp
```
**Not for production use.**
=== END FILE ===
**4a. Gunicorn**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/4a-gunicorn/
=== BEGIN FILE ===
# Gunicorn
This page provides instructions for setting up the [gunicorn](http://gunicorn.org/) WSGI server for NetBox, which runs as a WSGI application behind an HTTP server.
## Configuration
NetBox includes a default configuration file for gunicorn. To use it, copy the file:
```
sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
```
You may edit this file for changes to the bound IP address, port number, or performance adjustments. Refer to [the Gunicorn documentation](https://docs.gunicorn.org/en/stable/configure.html) for configuration parameters.
## systemd Setup
Use systemd to control gunicorn and NetBox's background worker process. Copy the service files:
```
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
```
Start and enable the services:
```
sudo systemctl enable --now netbox netbox-rq
```
Verify the WSGI service is running:
```
systemctl status netbox.service
```
Expected output includes:
```
● netbox.service - NetBox WSGI Service
Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
Docs: https://docs.netbox.dev/
Main PID: 1140492 (gunicorn)
...
```
If the service fails to start, check logs with:
```
journalctl -eu netbox
```
Note that there is a bug in gunicorn v21.2.0 causing 502 errors under heavy load. Users may downgrade to gunicorn v20.1.0 if needed, but this version does not officially support Python 3.11.
=== END FILE ===
**4b. uWSGI**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/4b-uwsgi/
=== BEGIN FILE ===
# uWSGI
This document provides instructions for setting up the uWSGI WSGI server for NetBox, which runs as a WSGI application behind an HTTP server.
## Installation
Activate the Python virtual environment and install the `pyuwsgi` package:
```no-highlight
source /opt/netbox/venv/bin/activate
pip3 install pyuwsgi
```
Add the package to `local_requirements.txt`:
```no-highlight
sudo sh -c "echo 'pyuwsgi' >> /opt/netbox/local_requirements.txt"
```
## Configuration
Copy the default configuration file for uWSGI:
```no-highlight
sudo cp /opt/netbox/contrib/uwsgi.ini /opt/netbox/uwsgi.ini
```
Edit this file for any necessary changes, such as IP address or port number. Refer to the uWSGI documentation for configuration parameters.
## systemd Setup
Copy the service files to the systemd directory:
```no-highlight
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
```
Update the `netbox.service` file to replace the `ExecStart` line for gunicorn with the appropriate uWSGI command.
Check user and group assignments in the service files. Reload the service:
```no-highlight
sudo systemctl daemon-reload
```
Start and enable the services:
```no-highlight
sudo systemctl enable --now netbox netbox-rq
```
Verify the WSGI service is running:
```no-highlight
systemctl status netbox.service
```
If the service fails to start, check logs with:
```no-highlight
journalctl -eu netbox
```
## HTTP Server Installation
Follow the NetBox HTTP Server Setup guide. After copying the configuration file, edit the `location` section to uncomment the uWSGI parameters:
```no-highlight
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:8001;
uwsgi_param Host $host;
uwsgi_param X-Real-IP $remote_addr;
uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto;
}
```
=== END FILE ===
**5. HTTP Server**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/5-http-server/
=== BEGIN FILE ===
# HTTP Server Setup
This documentation provides example configurations for both [nginx](https://www.nginx.com/resources/wiki/) and [Apache](https://httpd.apache.org/docs/current/), applicable to any HTTP server supporting WSGI, with a focus on Ubuntu 20.04.
## Obtain an SSL Certificate
To enable HTTPS for NetBox, obtain a valid SSL certificate from a commercial provider, [Let's Encrypt](https://letsencrypt.org/getting-started/), or generate a self-signed certificate. The public certificate and private key must be installed on the NetBox server.
To generate a self-signed certificate:
```no-highlight
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/netbox.key \
-out /etc/ssl/certs/netbox.crt
```
## HTTP Server Installation
### Option A: nginx
Install nginx:
```no-highlight
sudo apt install -y nginx
```
Copy the NetBox configuration file:
```no-highlight
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
```
Delete the default site and create a symlink:
```no-highlight
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
```
Restart nginx:
```no-highlight
sudo systemctl restart nginx
```
### Option B: Apache
Install Apache:
```no-highlight
sudo apt install -y apache2
```
Copy the configuration file:
```no-highlight
sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf
```
Enable required modules and site, then restart Apache:
```no-highlight
sudo a2enmod ssl proxy proxy_http headers rewrite
sudo a2ensite netbox
sudo systemctl restart apache2
```
## Confirm Connectivity
You should be able to connect to the HTTPS service at the provided server name or IP address. Adjust configurations as necessary for production environments.
## Troubleshooting
If unable to connect, check:
* Nginx/Apache is running and listening on the correct port.
* No firewall is blocking access.
For a 502 error, verify:
* WSGI worker processes (gunicorn) are running.
* Nginx/Apache is configured to connect to the correct port.
* SELinux is not blocking connections; allow with `setsebool -P httpd_can_network_connect 1`.
=== END FILE ===
**6. LDAP (Optional)**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/6-ldap/
=== BEGIN FILE ===
# LDAP Configuration
This guide details the implementation of LDAP authentication with a fallback to Django's built-in users.
## Install Requirements
### Install System Packages
```
sudo apt install -y libldap2-dev libsasl2-dev libssl-dev
```
### Install django-auth-ldap
Activate the Python virtual environment and install the `django-auth-ldap` package:
```
source /opt/netbox/venv/bin/activate
pip3 install django-auth-ldap
```
Add the package to `local_requirements.txt`:
```
sudo sh -c "echo 'django-auth-ldap' >> /opt/netbox/local_requirements.txt"
```
## Configuration
Enable the LDAP authentication backend in `configuration.py`:
```python
REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend'
```
Create `ldap_config.py` in the same directory as `configuration.py` and define the required parameters.
### General Server Configuration
```python
import ldap
AUTH_LDAP_SERVER_URI = "ldaps://ad.example.com"
AUTH_LDAP_CONNECTION_OPTIONS = {
ldap.OPT_REFERRALS: 0
}
AUTH_LDAP_BIND_DN = "CN=NETBOXSA, OU=Service Accounts,DC=example,DC=com"
AUTH_LDAP_BIND_PASSWORD = "demo"
LDAP_IGNORE_CERT_ERRORS = True
LDAP_CA_CERT_DIR = '/etc/ssl/certs'
LDAP_CA_CERT_FILE = '/path/to/example-CA.crt'
```
### User Authentication
```python
from django_auth_ldap.config import LDAPSearch
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=Users,dc=example,dc=com",
ldap.SCOPE_SUBTREE,
"(sAMAccountName=%(user)s)")
AUTH_LDAP_USER_DN_TEMPLATE = "uid=%(user)s,ou=users,dc=example,dc=com"
AUTH_LDAP_USER_ATTR_MAP = {
"first_name": "givenName",
"last_name": "sn",
"email": "mail"
}
```
### User Groups for Permissions
```python
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType
AUTH_LDAP_GROUP_SEARCH = LDAPSearch("dc=example,dc=com", ldap.SCOPE_SUBTREE,
"(objectClass=group)")
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()
AUTH_LDAP_REQUIRE_GROUP = "CN=NETBOX_USERS,DC=example,DC=com"
AUTH_LDAP_MIRROR_GROUPS = True
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
"is_active": "cn=active,ou=groups,dc=example,dc=com",
"is_staff": "cn=staff,ou=groups,dc=example,dc=com",
"is_superuser": "cn=superuser,ou=groups,dc=example,dc=com"
}
AUTH_LDAP_FIND_GROUP_PERMS = True
AUTH_LDAP_CACHE_TIMEOUT = 3600
```
### Authenticating with Active Directory
Modify `AUTH_LDAP_USER_SEARCH`:
```python
AUTH_LDAP_USER_SEARCH = LDAPSearch(
"ou=Users,dc=example,dc=com",
ldap.SCOPE_SUBTREE,
"(|(userPrincipalName=%(user)s)(sAMAccountName=%(user)s))"
)
```
Set `AUTH_LDAP_USER_DN_TEMPLATE` to `None` and update `AUTH_LDAP_USER_ATTR_MAP`:
```python
AUTH_LDAP_USER_ATTR_MAP = {
"username": "sAMAccountName",
"email": "mail",
"first_name": "givenName",
"last_name": "sn",
}
```
Add `AUTH_LDAP_USER_QUERY_FIELD`:
```python
AUTH_LDAP_USER_QUERY_FIELD = "username"
```
### Example Configuration
```python
import ldap
from django_auth_ldap.config import LDAPSearch, NestedGroupOfNamesType
AUTH_LDAP_SERVER_URI = "ldaps://ad.example.com:3269"
AUTH_LDAP_CONNECTION_OPTIONS = {
ldap.OPT_REFERRALS: 0
}
AUTH_LDAP_BIND_DN = "CN=NETBOXSA,OU=Service Accounts,DC=example,DC=com"
AUTH_LDAP_BIND_PASSWORD = "demo"
LDAP_IGNORE_CERT_ERRORS = False
LDAP_CA_CERT_DIR = '/etc/ssl/certs'
LDAP_CA_CERT_FILE = '/path/to/example-CA.crt'
AUTH_LDAP_USER_SEARCH = LDAPSearch(
"ou=Users,dc=example,dc=com",
ldap.SCOPE_SUBTREE,
"(|(userPrincipalName=%(user)s)(sAMAccountName=%(user)s))"
)
AUTH_LDAP_USER_DN_TEMPLATE = None
AUTH_LDAP_USER_ATTR_MAP = {
"username": "sAMAccountName",
"email": "mail",
"first_name": "givenName",
"last_name": "sn",
}
AUTH_LDAP_USER_QUERY_FIELD = "username"
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
"dc=example,dc=com",
ldap.SCOPE_SUBTREE,
"(objectClass=group)"
)
AUTH_LDAP_GROUP_TYPE = NestedGroupOfNamesType()
AUTH_LDAP_REQUIRE_GROUP = "CN=NETBOX_USERS,DC=example,DC=com"
AUTH_LDAP_MIRROR_GROUPS = True
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
"is_active": "cn=active,ou=groups,dc=example,dc=com",
"is_staff": "cn=staff,ou=groups,dc=example,dc=com",
"is_superuser": "cn=superuser,ou=groups,dc=example,dc=com"
}
AUTH_LDAP_FIND_GROUP_PERMS = True
AUTH_LDAP_CACHE_TIMEOUT = 3600
AUTH_LDAP_ALWAYS_UPDATE_USER = True
```
## Troubleshooting LDAP
Restart the NetBox service with:
```
systemctl restart netbox
```
For logging configuration:
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'netbox_auth_log': {
'level': 'DEBUG',
'class': 'logging.handlers.RotatingFileHandler',
'filename': '/opt/netbox/local/logs/django-ldap-debug.log',
'maxBytes': 1024 * 500,
'backupCount': 5,
},
},
'loggers': {
'django_auth_ldap': {
'handlers': ['netbox_auth_log'],
'level': 'DEBUG',
},
},
}
```
=== END FILE ===
**Upgrading NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/upgrading/
=== BEGIN FILE ===
# Upgrading to a New NetBox Release
Upgrading NetBox is straightforward, but users should review release notes and back up their current deployment before proceeding. Upgrades can typically be done directly to newer releases, except for major version increments, which require upgrading from the latest minor release of the current major version.
!!! warning "Perform a Backup"
Always be sure to save a backup of your current NetBox deployment prior to starting the upgrade process.
## 1. Review the Release Notes
Review all [release notes](../release-notes/index.md) published since your current version to identify any breaking changes.
## 2. Update Dependencies to Required Versions
NetBox requires the following dependencies:
| Dependency | Supported Versions |
|------------|--------------------|
| Python | 3.10, 3.11, 3.12 |
| PostgreSQL | 14+ |
| Redis | 4.0+ |
### Version History
| NetBox Version | Python min | Python max | PostgreSQL min | Redis min | Documentation |
|:--------------:|:----------:|:----------:|:--------------:|:---------:|:-------------------------------------------------------------------------------------------------:|
| 4.3 | 3.10 | 3.12 | 14 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.3.0/docs/installation/index.md) |
| 4.2 | 3.10 | 3.12 | 13 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.2.0/docs/installation/index.md) |
| 4.1 | 3.10 | 3.12 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.1.0/docs/installation/index.md) |
| 4.0 | 3.10 | 3.12 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v4.0.0/docs/installation/index.md) |
| 3.7 | 3.8 | 3.11 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.7.0/docs/installation/index.md) |
| 3.6 | 3.8 | 3.11 | 12 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.6.0/docs/installation/index.md) |
| 3.5 | 3.8 | 3.10 | 11 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.5.0/docs/installation/index.md) |
| 3.4 | 3.8 | 3.10 | 11 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.4.0/docs/installation/index.md) |
| 3.3 | 3.8 | 3.10 | 10 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.3.0/docs/installation/index.md) |
| 3.2 | 3.8 | 3.10 | 10 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.2.0/docs/installation/index.md) |
| 3.1 | 3.7 | 3.9 | 10 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.1.0/docs/installation/index.md) |
| 3.0 | 3.7 | 3.9 | 9.6 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v3.0.0/docs/installation/index.md) |
| 2.11 | 3.6 | 3.9 | 9.6 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v2.11.0/docs/installation/index.md) |
| 2.10 | 3.6 | 3.8 | 9.6 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v2.10.0/docs/installation/index.md) |
| 2.9 | 3.6 | 3.8 | 9.5 | 4.0 | [Link](https://github.com/netbox-community/netbox/blob/v2.9.0/docs/installation/index.md) |
| 2.8 | 3.6 | 3.8 | 9.5 | 3.4 | [Link](https://github.com/netbox-community/netbox/blob/v2.8.0/docs/installation/index.md) |
| 2.7 | 3.5 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.7.0/docs/installation/index.md) |
| 2.6 | 3.5 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.6.0/docs/installation/index.md) |
| 2.5 | 3.5 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.5.0/docs/installation/index.md) |
| 2.4 | 3.4 | 3.7 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.4.0/docs/installation/index.md) |
| 2.3 | 2.7 | 3.6 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.3.0/docs/installation/postgresql.md) |
| 2.2 | 2.7 | 3.6 | 9.4 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.2.0/docs/installation/postgresql.md) |
| 2.1 | 2.7 | 3.6 | 9.3 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.1.0/docs/installation/postgresql.md) |
| 2.0 | 2.7 | 3.6 | 9.3 | - | [Link](https://github.com/netbox-community/netbox/blob/v2.0.0/docs/installation/postgresql.md) |
| 1.9 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.9.0-r1/docs/installation/postgresql.md) |
| 1.8 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.8.0/docs/installation/postgresql.md) |
| 1.7 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.7.0/docs/installation/postgresql.md) |
| 1.6 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.6.0/docs/installation/postgresql.md) |
| 1.5 | 2.7 | 3.5 | 9.2 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.5.0/docs/installation/postgresql.md) |
| 1.4 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.4.0/docs/installation/postgresql.md) |
| 1.3 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.3.0/docs/installation/postgresql.md) |
| 1.2 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.2.0/docs/installation/postgresql.md) |
| 1.1 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/v1.1.0/docs/getting-started.md) |
| 1.0 | 2.7 | 3.5 | 9.1 | - | [Link](https://github.com/netbox-community/netbox/blob/1.0.0/docs/getting-started.md) |
## 3. Install the Latest Release
Upgrade NetBox by downloading the latest release package or checking out the latest production release from the git repository.
!!! warning
Use the same method as you used to install NetBox originally.
Check installation method with:
```
ls -ld /opt/netbox /opt/netbox/.git
```
### Option A: Download a Release
Download the [latest stable release](https://github.com/netbox-community/netbox/releases) and extract it:
```no-highlight
# Set $NEWVER to the NetBox version being installed
NEWVER=3.5.0
wget https://github.com/netbox-community/netbox/archive/v$NEWVER.tar.gz
sudo tar -xzf v$NEWVER.tar.gz -C /opt
sudo ln -sfn /opt/netbox-$NEWVER/ /opt/netbox
```
Copy necessary files from the current installation:
```no-highlight
# Set $OLDVER to the NetBox version currently installed
OLDVER=3.4.9
sudo cp /opt/netbox-$OLDVER/local_requirements.txt /opt/netbox/
sudo cp /opt/netbox-$OLDVER/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-$OLDVER/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/
```
Replicate uploaded media:
```no-highlight
sudo cp -pr /opt/netbox-$OLDVER/netbox/media/ /opt/netbox/netbox/
```
Copy custom scripts and reports:
```no-highlight
sudo cp -r /opt/netbox-$OLDVER/netbox/scripts /opt/netbox/netbox/
sudo cp -r /opt/netbox-$OLDVER/netbox/reports /opt/netbox/netbox/
```
Copy gunicorn configuration if applicable:
```no-highlight
sudo cp /opt/netbox-$OLDVER/gunicorn.py /opt/netbox/
```
### Option B: Check Out a Git Release
Determine the latest release:
```
git ls-remote --tags https://github.com/netbox-community/netbox.git \
| grep -o 'refs/tags/v[0-9]*\.[0-9]*\.[0-9]*$' \
| tail -n 1 \
| sed 's|refs/tags/||'
```
Check out the desired release:
```
sudo git checkout v4.2.7
```
## 4. Run the Upgrade Script
Verify optional Python packages in `local_requirements.txt` and run the upgrade script:
```no-highlight
sudo ./upgrade.sh
```
!!! warning
If the default Python version is not at least 3.10, specify the path to a supported version:
```no-highlight
sudo PYTHON=/usr/bin/python3.10 ./upgrade.sh
```
This script performs several actions, including rebuilding the Python virtual environment and applying database migrations.
## 5. Restart the NetBox Services
!!! warning
Update systemd service files if upgrading from a non-virtual environment installation.
Restart the services:
```no-highlight
sudo systemctl restart netbox netbox-rq
```
## 6. Verify Housekeeping Scheduling
Check for a cron task for nightly housekeeping if upgrading from a release prior to NetBox v3.0:
```shell
sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
```
Refer to the [housekeeping documentation](../administration/housekeeping.md) for more details.
=== END FILE ===
**Getting Started**
**Planning**
URL: https://netboxlabs.com/docs/netbox/en/stable/getting-started/planning/
=== BEGIN FILE ===
# Planning Your Move
This guide provides steps for planning a migration to NetBox, applicable for both new installations and adding data to existing deployments.
## Identify Current Sources of Truth
Understand your existing sources of truth, which are authoritative data repositories. Challenges may include:
* **Multiple conflicting sources**
* **Sources with no domain defined**
* **Inaccessible data formatting**
* **No source of truth exists**
Identify each domain of infrastructure data and its source of truth before determining what to move to NetBox.
## Determine What to Move
Data should be moved to NetBox if a model exists for it. NetBox allows for:
* Custom fields for additional data
* Plugins for new models and API endpoints
Consider whether to migrate certain data domains or integrate with other sources of truth. NetBox is continually developed, so future support for additional objects may be available.
## Validate Existing Data
Validation is crucial before migrating data. Tips for ensuring valid data include:
* Start with complete, well-formatted data (JSON or CSV recommended)
* Define custom validation rules in NetBox
* Use custom scripts for automatic data population
## Order of Operations
Recommended order for creating or importing NetBox objects:
1. Tenant groups and tenants
2. Regions, site groups, sites, and locations
3. Rack roles and racks
4. Manufacturers, device types, and module types
5. Platforms and device roles
6. Devices and modules
7. Providers, provider accounts, and provider networks
8. Circuit types and circuits
9. Wireless LAN groups and wireless LANs
10. Route targets and VRFs
11. RIRs and aggregates
12. IP/VLAN roles
13. Prefixes, IP ranges, and IP addresses
14. VLAN groups and VLANs
15. Cluster types, cluster groups, and clusters
16. Virtual machines and VM interfaces
This order aids in a smooth workflow, though it is not mandatory.
=== END FILE ===
**Populating Data**
URL: https://netboxlabs.com/docs/netbox/en/stable/getting-started/populating-data/
=== BEGIN FILE ===
# Populating Data
This section covers the mechanisms available to populate data in NetBox.
## Manual Object Creation
The simplest way to populate data in NetBox is through the object creation forms in the user interface.
- **Warning**: Not ideal for large imports; creating objects one at a time does not scale well.
- To create a new object, find the object type in the navigation menu and click the green "Add" button.
- **Info**: If the "add" button is missing, check permissions with your NetBox administrator. Some object types must be created within a parent object context.
## Bulk Import (CSV/YAML)
NetBox supports bulk import of new and existing objects using CSV-formatted data.
- CSV data can be imported as raw text or by uploading a properly formatted CSV file.
- The CSV import form pre-populates headers for required columns, with a "CSV Field Options" table listing all supported columns.
- Adding an "id" field updates existing records instead of importing new objects.
- Some models (e.g., device types) do not support CSV import and require YAML-formatted data.
## Scripting
Data can sometimes be populated using a custom script, especially when a pattern exists.
- **Tip**: Scripts can help reconstruct existing data without manual verification, ensuring data validity.
## REST API
The REST API allows programmatic control over object creation, adhering to the same validation rules as UI forms, and supports bulk creation of multiple objects in a single request. For more information, see the [REST API documentation](../integrations/rest-api.md).
=== END FILE ===
**Configuration**
**Configuring NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/index/
=== BEGIN FILE ===
# NetBox Configuration
## Configuration File
NetBox's configuration file controls parameters like database settings, security controls, and user preferences. The default configuration is usually sufficient, but some [required parameters](./required-parameters.md) must be defined during installation. The configuration file is located at `$INSTALL_ROOT/netbox/netbox/configuration.py`, with an example provided at `configuration_example.py`. A configuration file is mandatory for NetBox to run.
A custom configuration can be specified using the `NETBOX_CONFIGURATION` environment variable, pointing to a Python module. The documentation refers to the configuration file as `configuration.py`. Some parameters can be defined in either `configuration.py` or the UI, with hard-coded settings in the file taking precedence.
## Dynamic Configuration Parameters
Certain parameters are managed via the admin interface (Admin > Extras > Configuration Revisions) and can be overridden in `configuration.py`. Supported parameters include:
* [`ALLOWED_URL_SCHEMES`](./security.md#allowed_url_schemes)
* [`BANNER_BOTTOM`](./miscellaneous.md#banner_bottom)
* [`BANNER_LOGIN`](./miscellaneous.md#banner_login)
* [`BANNER_TOP`](./miscellaneous.md#banner_top)
* [`CHANGELOG_RETENTION`](./miscellaneous.md#changelog_retention)
* [`CUSTOM_VALIDATORS`](./data-validation.md#custom_validators)
* [`DEFAULT_USER_PREFERENCES`](./default-values.md#default_user_preferences)
* [`ENFORCE_GLOBAL_UNIQUE`](./miscellaneous.md#enforce_global_unique)
* [`GRAPHQL_ENABLED`](./graphql-api.md#graphql_enabled)
* [`JOB_RETENTION`](./miscellaneous.md#job_retention)
* [`MAINTENANCE_MODE`](./miscellaneous.md#maintenance_mode)
* [`MAPS_URL`](./miscellaneous.md#maps_url)
* [`MAX_PAGE_SIZE`](./miscellaneous.md#max_page_size)
* [`PAGINATE_COUNT`](./default-values.md#paginate_count)
* [`POWERFEED_DEFAULT_AMPERAGE`](./default-values.md#powerfeed_default_amperage)
* [`POWERFEED_DEFAULT_MAX_UTILIZATION`](./default-values.md#powerfeed_default_max_utilization)
* [`POWERFEED_DEFAULT_VOLTAGE`](./default-values.md#powerfeed_default_voltage)
* [`PREFER_IPV4`](./miscellaneous.md#prefer_ipv4)
* [`RACK_ELEVATION_DEFAULT_UNIT_HEIGHT`](./default-values.md#rack_elevation_default_unit_height)
* [`RACK_ELEVATION_DEFAULT_UNIT_WIDTH`](./default-values.md#rack_elevation_default_unit_width)
## Modifying the Configuration
The configuration file can be modified at any time, but the WSGI service (e.g., Gunicorn) must be restarted for changes to take effect:
```
$ sudo systemctl restart netbox
```
Dynamic parameters modified via the UI take effect immediately.
=== END FILE ===
**Required Parameters**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/required-parameters/
=== BEGIN FILE ===
# Required Configuration Settings
## ALLOWED_HOSTS
A list of valid fully-qualified domain names (FQDNs) and/or IP addresses for accessing the NetBox service. Must be defined as a list or tuple. This setting also configures `CSRF_TRUSTED_ORIGINS`. Example:
```
ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
```
Wildcard option:
```
ALLOWED_HOSTS = ['*']
```
---
## DATABASE
!!! warning "Legacy Configuration Parameter"
The `DATABASE` parameter is deprecated. Use `DATABASES` instead.
---
## DATABASES
NetBox requires PostgreSQL 14 or later. Databases are defined as named dictionaries:
```python
DATABASES = {
'default': {...},
'external1': {...},
'external2': {...},
}
```
Required parameters for each database:
* `NAME`
* `USER`
* `PASSWORD`
* `HOST`
* `PORT`
* `CONN_MAX_AGE`
* `ENGINE`
Example:
```python
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'netbox',
'USER': 'netbox',
'PASSWORD': 'J5brHrAXFLQSif0K',
'HOST': 'localhost',
'PORT': '',
'CONN_MAX_AGE': 300,
}
}
```
!!! warning
The `ENGINE` parameter must specify a PostgreSQL-compatible backend.
---
## REDIS
NetBox uses Redis for background task queuing. Configuration settings include:
* `HOST`
* `PORT`
* `USERNAME`
* `PASSWORD`
* `DATABASE`
* `SSL`
* `INSECURE_SKIP_TLS_VERIFY`
Example configuration:
```python
REDIS = {
'tasks': {
'HOST': 'redis.example.com',
'PORT': 1234,
'USERNAME': 'netbox',
'PASSWORD': 'foobar',
'DATABASE': 0,
'SSL': False,
},
'caching': {
'HOST': 'localhost',
'PORT': 6379,
'DATABASE': 1,
'SSL': False,
}
}
```
### UNIX Socket Support
Example using a UNIX socket:
```python
REDIS = {
'tasks': {
'URL': 'unix:///run/redis-netbox/redis.sock?db=0'
},
'caching': {
'URL': 'unix:///run/redis-netbox/redis.sock?db=1'
},
}
```
### Using Redis Sentinel
Configuration for Redis Sentinel:
* `SENTINELS`
* `SENTINEL_SERVICE`
* `SENTINEL_TIMEOUT`
Example:
```python
REDIS = {
'tasks': {
'SENTINELS': [('mysentinel.redis.example.com', 6379)],
'SENTINEL_SERVICE': 'netbox',
'SENTINEL_TIMEOUT': 10,
'DATABASE': 0,
'SSL': False,
},
'caching': {
'SENTINELS': [
('mysentinel.redis.example.com', 6379),
('othersentinel.redis.example.com', 6379)
],
'SENTINEL_SERVICE': 'netbox',
'DATABASE': 1,
'SSL': False,
}
}
```
---
## SECRET_KEY
A secret, pseudorandom string for cryptographic hashes. Must be at least 50 characters and contain a mix of letters, digits, and symbols. Use `$INSTALL_ROOT/netbox/generate_secret_key.py` to generate a key. Changing the key invalidates existing user sessions. All nodes in a multi-node deployment must share the same key.
=== END FILE ===
**System**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/system/
=== BEGIN FILE ===
# System Parameters
## BASE_PATH
Default: `None`
Base URL path for accessing NetBox, e.g., `BASE_PATH = 'netbox/'`.
---
## DATABASE_ROUTERS
Default: `[]`
Iterable of database routers for selecting appropriate databases in multi-database configurations.
---
## DEFAULT_LANGUAGE
Default: `en-us`
Default language/locale for requests without a specified language.
---
## DOCS_ROOT
Default: `$INSTALL_ROOT/docs/`
Filesystem path to NetBox's documentation, defaulting to the `docs/` directory.
---
## EMAIL
Configuration for sending email, including:
* `SERVER`
* `PORT` (default: `25`)
* `USERNAME`
* `PASSWORD`
* `USE_SSL` (default: `False`)
* `USE_TLS` (default: `False`)
* `SSL_CERTFILE`
* `SSL_KEYFILE`
* `TIMEOUT` (default: `10`)
* `FROM_EMAIL`
Note: `USE_SSL` and `USE_TLS` are mutually exclusive.
Example to test email configuration:
```python
# python ./manage.py nbshell
>>> from django.core.mail import send_mail
>>> send_mail(
'Test Email Subject',
'Test Email Body',
'noreply-netbox@example.com',
['users@example.com'],
fail_silently=False
)
```
---
## HTTP_PROXIES
Default: `None`
Dictionary of HTTP proxies for outbound requests, e.g.,
```python
HTTP_PROXIES = {
'http': 'http://10.10.1.10:3128',
'https': 'http://10.10.1.10:1080',
}
```
---
## INTERNAL_IPS
Default: `('127.0.0.1', '::1')`
List of internal IPs for controlling debugging output visibility.
---
## ISOLATED_DEPLOYMENT
Default: `False`
Set to True for deployments without Internet access.
---
## JINJA2_FILTERS
Default: `{}`
Dictionary of custom Jinja2 filters, e.g.,
```python
def uppercase(x):
return str(x).upper()
JINJA2_FILTERS = {
'uppercase': uppercase,
}
```
---
## LOGGING
Default logging configuration logs INFO and higher messages to the console. Example for logging to a file:
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'file': {
'level': 'INFO',
'class': 'logging.FileHandler',
'filename': '/var/log/netbox.log',
},
},
'loggers': {
'django': {
'handlers': ['file'],
'level': 'INFO',
},
},
}
```
### Available Loggers
* `netbox..`
* `netbox.auth.*`
* `netbox.api.views.*`
* `netbox.reports.*`
* `netbox.scripts.*`
* `netbox.views.*`
---
## MEDIA_ROOT
Default: `$INSTALL_ROOT/netbox/media/`
File path for storing media files.
---
## PROXY_ROUTERS
Default: `["utilities.proxy.DefaultProxyRouter"]`
List of classes for determining proxy servers for outbound HTTP requests.
---
## REPORTS_ROOT
Default: `$INSTALL_ROOT/netbox/reports/`
File path for custom reports.
---
## SCRIPTS_ROOT
Default: `$INSTALL_ROOT/netbox/scripts/`
File path for custom scripts.
---
## SEARCH_BACKEND
Default: `'netbox.search.backends.CachedValueSearchBackend'`
Dotted path to the search backend class.
---
## STORAGES
Default configuration for file storage:
```python
STORAGES = {
"default": {
"BACKEND": "django.core.files.storage.FileSystemStorage",
},
"staticfiles": {
"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
},
"scripts": {
"BACKEND": "extras.storage.ScriptFileSystemStorage",
},
}
```
Example for S3 storage:
```python
STORAGES = {
"scripts": {
"BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
"OPTIONS": {
'access_key': 'access key',
'secret_key': 'secret key',
}
},
}
```
---
## TIME_ZONE
Default: `"UTC"`
Recommended to use UTC for date and time handling.
---
## TRANSLATION_ENABLED
Default: `True`
Enables language translation for the user interface.
=== END FILE ===
**Security**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/security/
=== BEGIN FILE ===
# Security & Authentication Parameters
## ALLOW_TOKEN_RETRIEVAL
Default: `False`
The default value changed from true to false in NetBox v4.3.0. If disabled, API token values will not be displayed after creation, requiring users to record them beforehand.
---
## ALLOWED_URL_SCHEMES
Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')`
Permitted URL schemes for rendering links within NetBox. Custom schemes must replicate all default values.
---
## AUTH_PASSWORD_VALIDATORS
Default configuration:
```python
AUTH_PASSWORD_VALIDATORS = [
{
"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
"OPTIONS": {
"min_length": 12,
},
},
{
"NAME": "utilities.password_validation.AlphanumericPasswordValidator",
},
]
```
Criteria enforced:
* Minimum length of 12 characters.
* At least one uppercase letter, one lowercase letter, and one numeric digit.
Can be disabled by setting `AUTH_PASSWORD_VALIDATORS = []`.
---
## CORS_ORIGIN_ALLOW_ALL
Default: `False`
If True, accepts CORS requests from all origins; if False, a whitelist is used.
---
## CORS_ORIGIN_WHITELIST
## CORS_ORIGIN_REGEX_WHITELIST
Settings for authorized origins for cross-site API requests. Example:
```python
CORS_ORIGIN_WHITELIST = [
'https://example.com',
]
```
---
## CSRF_COOKIE_NAME
Default: `csrftoken`
Name of the cookie for CSRF authentication token.
---
## CSRF_COOKIE_SECURE
Default: `False`
If true, CSRF protection cookie is marked secure for HTTPS only.
---
## CSRF_TRUSTED_ORIGINS
Default: `[]`
List of trusted origins for unsafe requests. Example:
```python
CSRF_TRUSTED_ORIGINS = (
'http://netbox.local',
'https://netbox.local',
)
```
---
## DEFAULT_PERMISSIONS
Default:
```python
{
'users.view_token': ({'user': '$user'},),
'users.add_token': ({'user': '$user'},),
'users.change_token': ({'user': '$user'},),
'users.delete_token': ({'user': '$user'},),
}
```
Defines object permissions for authenticated users. Custom values will overwrite defaults.
---
## EXEMPT_VIEW_PERMISSIONS
Default: `[]`
List of models exempt from view permissions. Example:
```python
EXEMPT_VIEW_PERMISSIONS = [
'dcim.site',
'dcim.region',
'ipam.prefix',
]
```
To exempt all models, set:
```python
EXEMPT_VIEW_PERMISSIONS = ['*']
```
---
## LOGIN_PERSISTENCE
Default: `False`
If true, resets authentication session lifetime upon each valid request.
---
## LOGIN_REQUIRED
Default: `True`
Only authenticated users can access NetBox. Disabling allows unauthenticated access.
---
## LOGIN_TIMEOUT
Default: `1209600` seconds (14 days)
Lifetime of the authentication cookie.
---
## LOGIN_FORM_HIDDEN
Default: `False`
Hides the login form when only SSO authentication is used.
---
## LOGOUT_REDIRECT_URL
Default: `'home'`
Redirect URL after logout.
---
## SECURE_HSTS_INCLUDE_SUBDOMAINS
Default: `False`
If true, includes `includeSubDomains` in HSTS header.
---
## SECURE_HSTS_PRELOAD
Default: `False`
If true, includes `preload` in HSTS header.
---
## SECURE_HSTS_SECONDS
Default: `0`
Sets HSTS header if non-zero value is provided.
---
## SECURE_SSL_REDIRECT
Default: `False`
If true, redirects non-HTTPS requests to HTTPS.
---
## SESSION_COOKIE_NAME
Default: `sessionid`
Name for the session cookie.
---
## SESSION_COOKIE_SECURE
Default: `False`
If true, marks session cookie as secure for HTTPS only.
---
## SESSION_FILE_PATH
Default: `None`
Specifies path for storing session data as files instead of in the database.
=== END FILE ===
**GraphQL API**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/graphql-api/
=== BEGIN FILE ===
# GraphQL API Parameters
## GRAPHQL_ENABLED
Default: `True`
Setting this to False will disable the GraphQL API.
---
## GRAPHQL_MAX_ALIASES
Default: `10`
The maximum number of queries that a GraphQL API request may contain.
=== END FILE ===
**Remote Authentication**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/remote-authentication/
=== BEGIN FILE ===
# Remote Authentication Settings
The configuration parameters for remote authentication in NetBox require `REMOTE_AUTH_ENABLED` to be true for activation.
## REMOTE_AUTH_AUTO_CREATE_GROUPS
- Default: `False`
- Automatically creates groups from `REMOTE_AUTH_GROUP_HEADER` if they don't exist.
## REMOTE_AUTH_AUTO_CREATE_USER
- Default: `False`
- Automatically creates local accounts for users authenticated via a remote service.
## REMOTE_AUTH_BACKEND
- Default: `'netbox.authentication.RemoteUserBackend'`
- Specifies the Django authentication backend for external user authentication. Options include:
* `netbox.authentication.RemoteUserBackend`
* `netbox.authentication.LDAPBackend`
## REMOTE_AUTH_DEFAULT_GROUPS
- Default: `[]`
- Groups assigned to new user accounts created via remote authentication.
## REMOTE_AUTH_DEFAULT_PERMISSIONS
- Default: `{}`
- Mapping of permissions for new user accounts created via remote authentication.
## REMOTE_AUTH_ENABLED
- Default: `False`
- Enables remote user authentication via HTTP headers set by a reverse proxy.
## REMOTE_AUTH_GROUP_HEADER
- Default: `'HTTP_REMOTE_USER_GROUP'`
- HTTP header name for the authenticated user's groups.
## REMOTE_AUTH_GROUP_SEPARATOR
- Default: `|`
- Separator for splitting `REMOTE_AUTH_GROUP_HEADER` into individual groups.
## REMOTE_AUTH_GROUP_SYNC_ENABLED
- Default: `False`
- Enables syncing of remote user groups via HTTP headers.
## REMOTE_AUTH_HEADER
- Default: `'HTTP_REMOTE_USER'`
- HTTP header name for the authenticated user.
## REMOTE_AUTH_USER_EMAIL
- Default: `'HTTP_REMOTE_USER_EMAIL'`
- HTTP header name for the authenticated user's email address.
## REMOTE_AUTH_USER_FIRST_NAME
- Default: `'HTTP_REMOTE_USER_FIRST_NAME'`
- HTTP header name for the authenticated user's first name.
## REMOTE_AUTH_USER_LAST_NAME
- Default: `'HTTP_REMOTE_USER_LAST_NAME'`
- HTTP header name for the authenticated user's last name.
## REMOTE_AUTH_SUPERUSER_GROUPS
- Default: `[]`
- Groups that promote a remote user to Superuser on login.
## REMOTE_AUTH_SUPERUSERS
- Default: `[]`
- Users promoted to Superuser on login.
## REMOTE_AUTH_STAFF_GROUPS
- Default: `[]`
- Groups that promote a remote user to Staff on login.
## REMOTE_AUTH_STAFF_USERS
- Default: `[]`
- Users promoted to Staff on login.
=== END FILE ===
**Data & Validation**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/data-validation/
=== BEGIN FILE ===
# Data & Validation Parameters
## CUSTOM_VALIDATORS
This is a mapping of models to custom validators defined locally for custom validation logic. Example:
```python
CUSTOM_VALIDATORS = {
"dcim.site": [
{
"name": {
"min_length": 5,
"max_length": 30
}
},
"my_plugin.validators.Validator1"
],
"dim.device": [
"my_plugin.validators.Validator1"
]
}
```
## FIELD_CHOICES
Static choice fields on models can be configured with custom values by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice must have a database value and a human-friendly label, and may specify a color.
Choices can replace or append to stock choices. To replace, specify the app, model, and field name (e.g., `dcim.Site.status`). To extend, append a plus sign (e.g., `dcim.Site.status+`).
Example to replace choices:
```python
FIELD_CHOICES = {
'dcim.Site.status': (
('foo', 'Foo', 'red'),
('bar', 'Bar', 'green'),
('baz', 'Baz', 'blue'),
)
}
```
Example to append choices:
```python
FIELD_CHOICES = {
'dcim.Site.status+': (
...
)
}
```
Supported model fields for configurable choices include:
* `circuits.Circuit.status`
* `dcim.Device.status`
* `dcim.Location.status`
* `dcim.Module.status`
* `dcim.PowerFeed.status`
* `dcim.Rack.status`
* `dcim.Site.status`
* `dcim.VirtualDeviceContext.status`
* `extras.JournalEntry.kind`
* `ipam.IPAddress.status`
* `ipam.IPRange.status`
* `ipam.Prefix.status`
* `ipam.VLAN.status`
* `virtualization.Cluster.status`
* `virtualization.VirtualMachine.status`
* `wireless.WirelessLAN.status`
Supported colors:
* `blue`
* `indigo`
* `purple`
* `pink`
* `red`
* `orange`
* `yellow`
* `green`
* `teal`
* `cyan`
* `gray`
* `black`
* `white`
## PROTECTION_RULES
This is a mapping of models to custom validators evaluated before an object's deletion. If validation fails, the object is not deleted. Example:
```python
PROTECTION_RULES = {
"dcim.site": [
{
"status": {
"eq": "decommissioning"
}
},
"my_plugin.validators.Validator1",
]
}
```
=== END FILE ===
**Default Values**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/default-values/
=== BEGIN FILE ===
# Default Value Parameters
## DEFAULT_DASHBOARD
This parameter controls the content and layout of the user's default dashboard, allowing customization of widgets. It must specify an iterable of dictionaries for each widget with the following attributes:
* `widget`: Dotted path to the Python class (required)
* `width`: Default widget width (1-12)
* `height`: Default widget height, in rows
* `title`: Widget title
* `color`: Color of the widget's title bar
* `config`: Dictionary of widget configuration parameters
Example configuration:
```python
DEFAULT_DASHBOARD = [
{
'widget': 'extras.ObjectCountsWidget',
'width': 4,
'height': 3,
'title': 'Organization',
'config': {
'models': [
'dcim.site',
'tenancy.tenant',
'tenancy.contact',
]
}
},
{
'widget': 'extras.ObjectCountsWidget',
'width': 4,
'height': 3,
'title': 'IPAM',
'color': 'blue',
'config': {
'models': [
'ipam.prefix',
'ipam.iprange',
'ipam.ipaddress',
]
}
},
]
```
## DEFAULT_USER_PREFERENCES
This dictionary defines default preferences for newly-created user accounts. Example for setting default page size:
```python
DEFAULT_USER_PREFERENCES = {
"pagination": {
"per_page": 100
}
}
```
For a complete list of preferences, refer to `/user/preferences/`.
---
## PAGINATE_COUNT
Default: `50`
The maximum number of objects displayed per page.
---
## POWERFEED_DEFAULT_AMPERAGE
Default: `15`
Default value for the `amperage` field when creating new power feeds.
---
## POWERFEED_DEFAULT_MAX_UTILIZATION
Default: `80`
Default percentage for the `max_utilization` field when creating new power feeds.
---
## POWERFEED_DEFAULT_VOLTAGE
Default: `120`
Default value for the `voltage` field when creating new power feeds.
---
## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT
Default: `22`
Default height (in pixels) of a unit within a rack elevation.
---
## RACK_ELEVATION_DEFAULT_UNIT_WIDTH
Default: `220`
Default width (in pixels) of a unit within a rack elevation.
=== END FILE ===
**Error Reporting**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/error-reporting/
=== BEGIN FILE ===
# Error Reporting Settings
## SENTRY_DSN
Defines a Sentry data source name (DSN) for automated error reporting. `SENTRY_ENABLED` must be True for this parameter to take effect. Example:
```
SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
```
---
## SENTRY_ENABLED
Set to True to enable automatic error reporting via Sentry. The `sentry-sdk` Python package is required.
---
## SENTRY_SAMPLE_RATE
The sampling rate for errors, must be between 0 (disabled) and 1.0 (report on all errors). Default is `1.0`.
---
## SENTRY_SEND_DEFAULT_PII
Maps to the Sentry SDK's `send_default_pii` parameter. If enabled, certain personally identifiable information (PII) is added. Be aware that sensitive data such as cookies and authentication tokens will be logged.
---
## SENTRY_TAGS
An optional dictionary of tag names and values for Sentry error reports. Example:
```
SENTRY_TAGS = {
"custom.foo": "123",
"custom.bar": "abc",
}
```
Avoid using tag names that begin with `netbox.`, as this prefix is reserved.
---
## SENTRY_TRACES_SAMPLE_RATE
The sampling rate for transactions, must be between 0 (disabled) and 1.0 (report on all transactions). Default is `0`. A high sampling rate can induce performance penalties; a low sample rate of 10% to 20% is recommended.
=== END FILE ===
**Plugins**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/plugins/
=== BEGIN FILE ===
# Plugin Parameters
## PLUGINS
Default: `[]`
A list of installed NetBox plugins to enable. Plugins will not take effect unless they are listed here.
Warning: Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make no guarantees about the integrity or security of your installation with plugins enabled.
---
## PLUGINS_CONFIG
Default: `[]`
This parameter holds configuration settings for individual NetBox plugins, defined as a dictionary with each key using the name of an installed plugin. The specific parameters supported are unique to each plugin. An example configuration is shown below:
```python
PLUGINS_CONFIG = {
'plugin1': {
'foo': 123,
'bar': True
},
'plugin2': {
'foo': 456,
},
}
```
Note that a plugin must be listed in `PLUGINS` for its configuration to take effect.
---
## PLUGINS_CATALOG_CONFIG
Default: `{}` (Empty)
This parameter controls how individual plugins are displayed in the plugins catalog under Admin > System > Plugins. Adding a plugin to the `hidden` list will omit that plugin from the catalog. Adding a plugin to the `static` list will display the plugin, but not link to the plugin details or upgrade instructions.
An example configuration is shown below:
```python
PLUGINS_CATALOG_CONFIG = {
'hidden': [
'plugin1',
],
'static': [
'plugin2',
],
}
```
=== END FILE ===
**Miscellaneous**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/miscellaneous/
=== BEGIN FILE ===
# Miscellaneous Parameters
## ADMINS
NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example:
```python
ADMINS = [
['Hank Hill', 'hhill@example.com'],
['Dale Gribble', 'dgribble@example.com'],
]
```
## BANNER_BOTTOM
Sets content for the bottom banner in the user interface.
## BANNER_LOGIN
This defines custom content to be displayed on the login page above the login form. HTML is allowed.
## BANNER_MAINTENANCE
This adds a banner to the top of every page when maintenance mode is enabled. HTML is allowed.
## BANNER_TOP
Sets content for the top banner in the user interface.
If you'd like the top and bottom banners to match, set the following:
```python
BANNER_TOP = 'Your banner text'
BANNER_BOTTOM = BANNER_TOP
```
## CENSUS_REPORTING_ENABLED
Default: `True`
Enables anonymous census reporting. To opt out of census reporting, set this to False.
## CHANGELOG_RETENTION
Default: `90`
The number of days to retain logged changes. Set this to `0` to retain changes indefinitely.
## CHANGELOG_SKIP_EMPTY_CHANGES
Default: `True`
If enabled, a change log record will not be created when an object is updated without changes.
## DATA_UPLOAD_MAX_MEMORY_SIZE
Default: `2621440` (2.5 MB)
The maximum size of an incoming HTTP request. Requests exceeding this size will raise a `RequestDataTooBig` exception.
## ENFORCE_GLOBAL_UNIQUE
Default: `True`
Prevents the creation of duplicate prefixes and IP addresses in the global table. Disable by setting to False.
## EVENTS_PIPELINE
Default: `['extras.events.process_event_queue',]`
NetBox will call functions listed here for events on models.
## FILE_UPLOAD_MAX_MEMORY_SIZE
Default: `2621440` (2.5 MB)
The maximum amount of uploaded data held in memory before being written to the filesystem.
## JOB_RETENTION
Default: `90`
The number of days to retain job results. Set this to `0` for indefinite retention.
## MAINTENANCE_MODE
Default: `False`
Setting this to True will display a maintenance mode banner and stop updating a user's "last active" time.
## MAPS_URL
Default: `https://maps.google.com/?q=`
Specifies the URL for presenting a map of a location. Set to `None` to disable the "map it" button.
## MAX_PAGE_SIZE
Default: `1000`
Defines the maximum acceptable limit for objects requested via URL.
## METRICS_ENABLED
Default: `False`
Toggle the availability of Prometheus-compatible metrics at `/metrics`.
## PREFER_IPV4
Default: `False`
When determining the primary IP address for a device, IPv6 is preferred. Set to True to prefer IPv4.
## QUEUE_MAPPINGS
Allows changing which queues are used for background tasks.
```python
QUEUE_MAPPINGS = {
'webhook': 'low',
'report': 'high',
'script': 'high',
}
```
## RELEASE_CHECK_URL
Default: `None`
Defines the URL for checking new NetBox releases. Set to `None` to disable checks.
## RQ_DEFAULT_TIMEOUT
Default: `300`
The maximum execution time of a background task, in seconds.
## RQ_RETRY_INTERVAL
Default: `60`
Controls how frequently a failed job is retried.
## RQ_RETRY_MAX
Default: `0`
The maximum number of times a background task will be retried before being marked as failed.
## DISK_BASE_UNIT
Default: `1000`
The base unit for disk sizes. Set to `1024` for binary prefixes.
## RAM_BASE_UNIT
Default: `1000`
The base unit for RAM sizes. Set to `1024` for binary prefixes.
=== END FILE ===
**Development**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/development/
=== BEGIN FILE ===
# Development Parameters
## DEBUG
Default: `False`
Enables debugging during development or troubleshooting. Only clients from recognized internal IP addresses will see debugging tools.
Warning: Never enable debugging in production, as it can expose sensitive data and degrade performance.
---
## DEVELOPER
Default: `False`
Prevents potentially dangerous actions like generating new database schema migrations. Disables the debug warning banner in the UI. Set to `True` only during active development of the NetBox code base.
=== END FILE ===
**Customization**
**Custom Fields**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/custom-fields/
=== BEGIN FILE ===
# Custom Fields
Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. Custom fields allow users to store additional attributes that are not part of the core schema, stored as JSON data alongside each object.
## Creating Custom Fields
Custom fields can be created via Customization > Custom Fields. Supported types include:
* Text
* Long text
* Integer
* Decimal
* Boolean
* Date
* Date & time
* URL
* JSON
* Selection
* Multiple selection
* Object
* Multiple object
Each custom field must have a name, a human-friendly label, a weight, and can be marked as required or have a default value. Custom fields must be assigned to one or more object types.
### Filtering
Filter logic can be set to loose (default) or exact matching, with an option to disable filtering.
### Grouping
Custom fields can be grouped by assigning the same group name, which will appear under a group heading in the UI.
### Visibility & Editing
Display conditions for custom fields include:
* Always (default)
* If Set
* Hidden
Editing conditions include:
* Yes (default)
* No
* Hidden
### Validation
Validation types include:
* Text: Regular expression (optional)
* Integer: Minimum/maximum value (optional)
* Selection: Must match prescribed choices
### Custom Selection Fields
Selection fields require a choice set with at least two choices. Default values must match provided choices.
### Custom Object Fields
Object fields refer to specific NetBox objects and must define an `object_type`. Filtering options are available via `query_params`.
## Custom Fields in Templates
Custom field data can be accessed in Jinja2 templates using the `cf` property.
## Custom Fields and the REST API
Custom data is included in the `custom_fields` attribute when retrieving objects via the REST API. Example JSON output shows how to set or change custom field values.
=== END FILE ===
**Custom Links**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/custom-links/
=== BEGIN FILE ===
# Custom Links
Custom links enable users to display hyperlinks to external content within NetBox object views, facilitating cross-referencing with external systems. They are created via Customization > Custom Links and are associated with specific NetBox object types (site, device, prefix, etc.). Each link includes display text and a URL, with the option to incorporate data from the viewed NetBox item using Jinja template code through the variable `object` and custom fields via `object.cf`.
Example link definition:
* Text: `View NMS`
* URL: `https://nms.example.com/nodes/?name={{ object.name }}`
For a device named Router4, the link renders as:
```no-highlight
View NMS
```
Links appear as buttons in the top right corner, can be ordered using numeric weighting, and can be individually enabled or disabled.
!!! warning
Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users.
## Context Data
Available context data for rendering custom link text or URL:
| Variable | Description |
|-----------|-------------------------------------------------------------------------------------------------------------------|
| `object` | The NetBox object being displayed |
| `debug` | A boolean indicating whether debugging is enabled |
| `request` | The current WSGI request |
| `user` | The current user (if authenticated) |
| `perms` | The permissions assigned to the user |
The `object` variable will be an instance of the specific object being viewed, and different models have varying fields and properties. Checking the REST API representation of an object or the NetBox source code can help identify available attributes.
## Conditional Rendering
Links with non-empty text are included on the page. Conditional Jinja2 logic can control link rendering. For example, to display a link for active devices:
```jinja2
{% if object.status == 'active' %}View NMS{% endif %}
```
To show links for a specific manufacturer:
```jinja2
{% if object.device_type.manufacturer.name == 'Cisco' %}View NMS{% endif %}
```
## Link Groups
Links can be organized into groups, rendering as a dropdown menu beneath a single button with the group name.
## Table Columns
Custom links can be included in object tables, rendering as hyperlinks for corresponding objects. When exported (e.g., as CSV), only the URL is displayed.
=== END FILE ===
**Custom Validation**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/custom-validation/
=== BEGIN FILE ===
# Custom Validation
NetBox validates objects before database writing to ensure data integrity, but custom validation rules can be added. Custom validation rules map object attributes to specific rules.
## Custom Validation Rules
Example of a custom validator:
```json
{
"name": {
"min_length": 5,
"max_length": 30
}
}
```
This checks that the `name` attribute is between 5 and 30 characters long, executed after NetBox's internal validation.
### Validation Types
The `CustomValidator` class supports:
* `min`: Minimum value
* `max`: Maximum value
* `min_length`: Minimum string length
* `max_length`: Maximum string length
* `regex`: Regular expression
* `required`: Value must be specified
* `prohibited`: Value must not be specified
* `eq`: Value must equal specified value
* `neq`: Value must not equal specified value
### Custom Validation Logic
For more complex validation, extend `CustomValidator` and override `validate()`:
```python
from extras.validators import CustomValidator
class MyValidator(CustomValidator):
def validate(self, instance, request):
if instance.status == 'active' and not instance.description:
self.fail("Active sites must have a description set!", field='status')
```
## Assigning Custom Validators
Custom validators are linked to NetBox models via the `CUSTOM_VALIDATORS` configuration parameter. Three methods to define rules:
1. Plain JSON mapping
2. Dotted path to a custom validator class
3. Direct reference to a custom validator class
### Plain Data
Example of plain JSON validation rules:
```python
CUSTOM_VALIDATORS = {
"dcim.site": [
{
"name": {
"min_length": 5,
"max_length": 30,
}
}
],
"dcim.device": [
{
"platform": {
"required": True,
}
}
]
}
```
#### Referencing Related Object Attributes
Reference attributes of related objects using a dotted path:
```python
CUSTOM_VALIDATORS = {
"dcim.site": [
{
"region.name": {
"neq": "New York"
}
}
]
}
```
#### Validating Request Parameters
Custom validators can validate request parameters:
```json
{
"request.user.username": {
"eq": "admin"
}
}
```
### Dotted Path to Class
Reference a custom validator class by its Python path:
```python
CUSTOM_VALIDATORS = {
'dcim.site': (
'my_validators.Validator1',
'my_validators.Validator2',
),
'dcim.device': (
'my_validators.Validator3',
)
}
```
### Direct Class Reference
Import classes directly in the configuration file:
```python
from my_validators import Validator1, Validator2, Validator3
CUSTOM_VALIDATORS = {
'dcim.site': (
Validator1(),
Validator2(),
),
'dcim.device': (
Validator3(),
)
}
```
=== END FILE ===
**Export Templates**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/export-templates/
=== BEGIN FILE ===
# Export Templates
NetBox enables users to create custom export templates for various object types via Customization > Export Templates. Each template must have a name and can optionally specify a MIME type and/or file extension. Templates are written in Jinja2.
- The name `table` is reserved for internal use.
- Export templates can pose security risks; only trusted users should modify them.
The `queryset` variable contains the list of objects for rendering, typically iterated with a `for` loop. Object properties can be accessed by name:
```jinja2
{% for rack in queryset %}
Rack: {{ rack.name }}
Site: {{ rack.site.name }}
Height: {{ rack.u_height }}U
{% endfor %}
```
Custom fields are accessed using the `cf` attribute, e.g., `{{ obj.cf.color }}`. To use config context data, utilize `get_config_context`:
```
{% for server in queryset %}
{% set data = server.get_config_context() %}
{{ data.syslog }}
{% endfor %}
```
The `as_attachment` attribute determines if the content is downloadable or displayed in the browser, with a default MIME type of `text/plain`.
## REST API Integration
For authentication, render templates via the REST API by making a `GET` request to the model's list endpoint with the `export` parameter:
```
GET /api/dcim/sites/?export=MyTemplateName
```
The response will contain only the rendered content.
## Example
An example device export template for generating Nagios configuration:
```
{% for device in queryset %}{% if device.status and device.primary_ip %}define host{
use generic-switch
host_name {{ device.name }}
address {{ device.primary_ip.address.ip }}
}
{% endif %}{% endfor %}
```
Sample output:
```
define host{
use generic-switch
host_name switch1
address 192.0.2.1
}
define host{
use generic-switch
host_name switch2
address 192.0.2.2
}
define host{
use generic-switch
host_name switch3
address 192.0.2.3
}
```
=== END FILE ===
**Reports**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/reports/
=== BEGIN FILE ===
# NetBox Reports
Reports are deprecated in NetBox v4.0, merging functionality with custom scripts. Users should convert legacy reports to custom scripts soon, as support for legacy reports will be removed in future releases.
## Converting Reports to Scripts
### Step 1: Update Class Definition
Change the parent class from `Report` to `Script`:
```python title="Old code"
from extras.reports import Report
class MyReport(Report):
```
```python title="New code"
from extras.scripts import Script
class MyReport(Script):
```
### Step 2: Update Logging Calls
Update logging methods as their signatures differ. Replace the generic `log()` method with `log_info()`.
| Report (old) | Script (New) |
|-------------------------------|-----------------------------|
| `log(message)` | `log_info(message)` |
| `log_debug(obj, message)`[^1] | `log_debug(message, obj)` |
| `log_info(obj, message)` | `log_info(message, obj)` |
| `log_success(obj, message)` | `log_success(message, obj)` |
| `log_warning(obj, message)` | `log_warning(message, obj)` |
| `log_failure(obj, message)` | `log_failure(message, obj)` |
[^1]: `log_debug()` was added to the Report class in v4.0 to avoid confusion with the same method on Script
```python title="Old code"
self.log_failure(
console_port.device,
f"No console connection defined for {console_port.name}"
)
```
```python title="New code"
self.log_failure(
f"No console connection defined for {console_port.name}",
obj=console_port.device,
)
```
### Other Notes
Reports will convert to scripts automatically upon upgrading to NetBox v4.0, retaining job history. The `pre_run()` and `post_run()` methods from Report are carried over to Script. The `is_valid()` method on Report has been removed.
=== END FILE ===
**Custom Scripts**
URL: https://netboxlabs.com/docs/netbox/en/stable/customization/custom-scripts/
=== BEGIN FILE ===
# Custom Scripts
Custom scripting in NetBox allows users to execute custom logic within the UI, enabling data manipulation for tasks like:
* Automatically populating devices and cables for new site deployments
* Creating reserved prefixes or IP addresses
* Importing data from external sources
* Updating objects with invalid data
Scripts can validate data integrity, checking conditions such as:
* Console connections for top-of-rack switches
* Loopback interfaces for routers
* Standard format for interface descriptions
* Minimum VLANs for sites
* Parent prefixes for IP addresses
Custom scripts are Python code outside the NetBox code base, allowing updates without affecting the core installation. However, they have unrestricted database access and should only be installed from trusted sources.
## Writing Custom Scripts
Scripts must inherit from the `extras.scripts.Script` base class and consist of variables and a `run()` method. The `run()` method accepts:
* `data` - Dictionary of variable data
* `commit` - Boolean for database changes
Example structure:
```python
from extras.scripts import Script
class MyScript(Script):
var1 = StringVar(...)
var2 = IntegerVar(...)
def run(self, data, commit):
...
```
Scripts are ordered alphabetically by default, but can be customized using the `script_order` variable.
## Script Attributes
Attributes are defined in a `Meta` class and include:
### `name`
Human-friendly name of the script.
### `description`
Description of the script's functionality.
### `field_order`
Defines the order of script variables.
### `fieldsets`
Groups and orders variables in the form.
### `commit_default`
Sets the default state of the commit checkbox.
### `scheduling_enabled`
Enables or disables script scheduling.
### `job_timeout`
Sets maximum runtime for the script.
## Accessing Request Data
Request details are available via `self.request`, allowing access to the user and client IP address.
## Reading Data from Files
Scripts can read data using `load_yaml` and `load_json`, though these methods are deprecated in future versions.
## Logging
Scripts can log messages at various severity levels:
* `log_debug`
* `log_success`
* `log_info`
* `log_warning`
* `log_failure`
## Test Methods
Scripts can define test methods prefixed with `test_` to check conditions automatically during execution.
### Example
```python
class DeviceConnectionsReport(Script):
description = "Validate minimum physical connections for each device"
def test_console_connection(self):
...
```
## Change Logging
To log changes, take a snapshot of the object before modifications:
```python
if obj.pk and hasattr(obj, 'snapshot'):
obj.snapshot()
```
## Error Handling
Use `AbortScript` to cleanly abort execution without reporting a stack trace.
## Variable Reference
### Default Options
All variables support options like `default`, `description`, `label`, `required`, and `widget`.
### Variable Types
* `StringVar`
* `TextVar`
* `IntegerVar`
* `BooleanVar`
* `ChoiceVar`
* `MultiChoiceVar`
* `ObjectVar`
* `MultiObjectVar`
* `FileVar`
* `IPAddressVar`
* `DateVar`
* `DateTimeVar`
## Running Custom Scripts
Users must have permissions to run scripts. Scripts can be executed via:
### Web UI
Navigate to the script and run it.
### API
Use a POST request to the script's endpoint.
### CLI
Invoke the management command:
```
python3 manage.py runscript .