# NetBox Documentation
> NetBox is an open source web application for managing and documenting network infrastructure.
These are docs for LLMs for NetBox 4.1.3.
## 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/)
- [Staged Changes](https://netboxlabs.com/docs/netbox/en/stable/plugins/development/staged-changes/)
- [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/)
- 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/)
- [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/)
- [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/)
- [Branch](https://netboxlabs.com/docs/netbox/en/stable/models/extras/branch/)
- [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/)
- [StagedChange](https://netboxlabs.com/docs/netbox/en/stable/models/extras/stagedchange/)
- [Subscription](https://netboxlabs.com/docs/netbox/en/stable/models/extras/subscription/)
- [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/)
- [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.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 data model tailored for network engineers, 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 customization and extension 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 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 allows users to extend its functionality using Python tools through custom 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)
* 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 various 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 populate external tools with necessary data.
## Design Philosophy
NetBox's design is based on:
### Replicate the Real World
The data model reflects real-world networks, 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
A preference for simple solutions ensures 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 12+ |
| Task queuing | Redis/django-rq |
=== END FILE ===
**Features**
**Facilities**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/facilities/
=== BEGIN FILE ===
# Facilities
NetBox allows modeling of a network's presence from global regions to individual equipment racks using purpose-built 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 can also be arranged hierarchically but focus on functional grouping rather than geographic. They can classify sites as corporate, branch, or customer sites.
## Sites
A site represents a building within a region/site group, assigned an operational status and can have a 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 specify unique rack specifications, including weight, height, and unit ordering, which can be replicated in new racks created in NetBox.
## Racks
Racks are discrete objects within a site/location where devices are installed. Each rack has an operational status, type, facility ID, and dimensions. Racks must be associated with a site, and optionally with a location. Custom roles can be assigned to racks, and rack space can be tracked 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 or routers, which can be mounted in racks. Resources within devices, such as network interfaces and console ports, can be grouped into modules.
## Manufacturers
Manufacturers represent organizations producing hardware devices, defined by users to reflect actual entities.
## Device Types
A device type combines manufacturer and hardware model, allowing users to create devices with replicated components. Users can create their own device types or use the community library of pre-defined types.
Components that can be modeled include:
* Interfaces
* Console ports
* Console server ports
* Power ports
* Power outlets
* Pass-through ports
* Module bays
* Device bays
For example, a Juniper EX4300-48T device type might include templates for console ports, power ports, and multiple interfaces.
!!! tip "Component Instantiation is not Retroactive"
Component instantiation occurs at device creation; changes to device types do not 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 a set of devices sharing a management plane, with one device as the master.
### Virtual Device Contexts
VDCs are logical partitions within a device, operating autonomously while sharing resources.
## Module Types & Modules
Module types instantiate modules within devices, which can have their own child components. Device bays hold independently operating hardware, while module bays contain modules that do not operate independently.
!!! tip "Device Bays vs. Module Bays"
Device bays are for hardware with its own management plane; module bays are for components dependent on the parent device.
Modules can have templated components automatically renamed based on their module bay.
## Cables
NetBox models cables as connections among device components, with attributes like type, color, length, and label. Basic checks prevent invalid connections, allowing flexible terminations for cables.
=== 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 power panels and feeds, primarily for data centers but applicable to other environments.
## Power Panels
- Represents the upstream power element, typically a power distribution 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; only one port per feed.
- Multiple devices on the same feed require a power distribution unit (PDU).
!!! tip "Primary and Redundant Power"
- Each power feed is assigned a type: primary or redundant for modeling redundancy.
- For single, non-redundant supplies, all feeds should be marked as primary.
=== 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 both IPv4 and IPv6, advanced VRF assignment, and automatic hierarchy formation.
## IP Hierarchy
NetBox uses several object types to represent IP resource hierarchies:
* **Aggregate** - Represents the root of an addressing hierarchy, typically a large address space allocated to an organization.
* **Prefix** - A subnet within an aggregate, which can have a functional role and operational status.
* **IP Range** - A range of individual 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 without manual assignment.
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' usage, while other prefixes' rates depend on child IP addresses and ranges. Aggregate utilization is based on child prefixes' consumption.
## VRF Tracking
NetBox models VRF instances for multiple routing tables, allowing each IP object to be assigned to a VRF, maintaining 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, each 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 are defined using templates for easy instantiation, though they can also be 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 scope.
- Each group can be associated with a site, location, or rack.
- Designates a minimum and maximum VLAN ID (default: 1 to 4094).
- Each VLAN in a group must have a unique ID and name.
- No limit on the number of groups per scope.
## VLANs
- VLANs are modeled with a 12-bit VLAN ID and a name.
- Each VLAN has an operational status and may have a function role.
- VLANs can be assigned to a VLAN group or site.
- VLANs can be associated with device and virtual machine interfaces.
- Interfaces can be assigned an 802.1Q mode (access or tagged) with relevant VLANs applied 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 (e.g., VXLAN, EVPN) can be defined in NetBox, linking them to interfaces and VLANs for tracking overlay assets and their relationships with underlay resources.
- Each L2VPN instance has:
- A type
- An optional unique identifier
- L2VPNs can have import and export route targets assigned, similar to VRFs.
- 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, offering flexibility for modeling physical circuits in various environments and connecting them to device interfaces via cables.
## Providers
- A provider is any organization offering Internet or private connectivity, typically large carriers, regional providers, or internal services.
- Providers can have account and contact details, and one or more AS numbers.
- Provider networks can be modeled as "black box" networks for circuits to connect, often represented in topology diagrams.
## Circuits
- A circuit is a physical connection between two points, maintained by an external provider, such as a fiber optic Internet connection.
- Each circuit is linked to a provider and has a unique circuit ID, 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.
!!! warning "Physical vs. Virtual Circuits"
The circuit model in NetBox represents **physical** connections, not _virtual_ circuits offered by providers. If it can't be pointed to, 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 wireless clients, identified by a common SSID and authentication parameters. They can be organized into self-nesting groups and optionally bound to a VLAN for mapping to wired networks.
Authentication attributes for wireless LANs include:
* **Type** - Open, WEP, WPA, etc.
* **Cipher** - Auto, TKIP, or AES
* **Pre-shared key (PSK)** - The secret key configured on all participating clients
Defining authentication parameters is optional.
## Wireless Links
A wireless link is a point-to-point connection between two stations, functioning similarly to cables but modeling wireless communications more accurately. 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 requires 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 lacking physical attributes.
- VMs can have interfaces with assigned IP addresses and VLANs, but cannot connect 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 models 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_, associating an object with a particular tenant to convey ownership or dependency. For example, an enterprise might represent its internal business units as tenants, while a managed services provider might create a tenant for each customer.
## Tenant Groups
Tenants can be grouped by any logic required, with recursive nesting for flexibility. For instance, a parent "Customers" group can have child groups "Current" and "Past." A tenant can be assigned to a group at any level in the hierarchy.
## Tenants
The tenant model typically represents a customer or internal organization but can be adapted to various needs. Most core objects in NetBox can be assigned to a tenant, allowing for easy tracking of ownership across object types. 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 tenant assignment.
=== END FILE ===
**Contacts**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/contacts/
=== BEGIN FILE ===
# Contacts
Contact assignment in NetBox allows tracking ownership of resources, with a contact representing an individual responsible for a resource within a specific role.
## Contact Groups
Contacts can be organized into a recursive hierarchy, allowing assignment at any level.
## Contact Roles
Contact roles define the relationship of a contact to an assigned object, such as administrative, operational, or emergency roles.
## Contacts
Each contact must have a name and may include optional details like title, phone number, and email. 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 with object creation or modification. Users can specify lookup types like exact or partial match, with matching portions highlighted in results. Custom fields can be included if configured with a search weight, and plugins can register custom models for search inclusion.
Note: Static choice fields, including custom fields of type "Selection" or "Multiple selection," are not indexed.
## Saved Filters
NetBox provides extensive filters for each object type, enabling complex queries. Users can save frequently used filter sets for future use. For example, 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
```
Saved filters are usable 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 instance, syslog servers can be defined for devices in a certain region using a config context instance.
```json
{
"syslog-servers": [
"192.168.43.107",
"192.168.48.112"
]
}
```
This data can be accessed via remote API clients or used to render 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 example, if different syslog servers are needed for a specific device role, a second config context with a higher weight can be created.
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 can be created:
```json
{
"syslog-servers": [
"192.168.43.107"
]
}
```
The resulting context data for a device at this site will 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 that takes precedence over other config contexts. This is useful for specific deviations in data for individual objects. If local context data is frequently defined, custom fields may be a better 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 specific device instance, and `ntp_servers` is sourced from context data.
### Context Data
The configuration rendering context includes the `device` or `virtualmachine` object. NetBox model classes can also be accessed, e.g., `There are {{ dcim.Site.objects.count() }} sites.`
## Rendering Templates
### Device Configurations
NetBox has 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 rendering order for configuration templates is:
* Device-specific template
* Role-specific template
* Platform-specific template
If none are assigned, the request fails. The output format can be 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 that can source content from remote git repositories. This is achieved 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 typically require supporting Python libraries. The Git backend needs the `dulwich` package, and the S3 backend requires the `boto3` package. If using Git with `HTTP_PROXIES` configured for SOCKS, the `python_socks` library is also necessary.
Each remote source type has specific configuration parameters. For example, a git source requires a branch and authentication credentials. After creating the source, a synchronization job replicates remote files into the local database.
The following NetBox models can be associated with replicated data files:
* Config contexts
* Config templates
* Export templates
Designated data will replace local instance content, and future updates to the replicated file will flag the local instance as out-of-date. Users can synchronize these objects individually or in bulk, ensuring that automated tasks do not immediately affect 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. This creates a persistent record of changes for each object and for NetBox as a whole. The global change log can be viewed by navigating to 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, facilitating the identification of change records from a particular request.
Change records are accessible via the API at the read-only endpoint `/api/extras/object-changes/` and can be exported in CSV format through the web UI.
## Correlating Changes by Request
Every 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 that the changes 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
Each entry automatically records:
- Date
- Time
- 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 status changes to active, a webhook can be created for the device model, and associated with an event rule to trigger automatically under specified conditions.
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 should trigger 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 NetBox's [conditional logic](../reference/conditions.md) documentation 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 v4.1 introduced 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.
* Event rules can be defined to automatically generate notifications for users in response to specific system events.
Plugins in NetBox can also create notifications for their own needs.
=== END FILE ===
**Background Jobs**
URL: https://netboxlabs.com/docs/netbox/en/stable/features/background-jobs/
=== BEGIN FILE ===
# Background Jobs
NetBox allows for the execution of certain functions as background tasks, including:
* [Report](../customization/reports.md) execution
* [Custom script](../customization/custom-scripts.md) execution
* Synchronization of [remote data sources](../integrations/synchronized-data.md)
Plugins can also enqueue their own background tasks using the [Job model](../models/core/job.md). These tasks are executed by the `rqworker` process(es).
## Scheduled Jobs
Background jobs can be set to run immediately or at a specified 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
NetBox features a comprehensive permissions system that surpasses the model-based permissions of Django. Key aspects of assigning permissions include:
* Object types for permissions
* Users/groups receiving permissions
* Permitted actions (e.g., view, add, change)
* Constraints limiting permissions to specific object subsets
These 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 IPs within a certain VRF. Constraints are defined in JSON format, similar to Django ORM queries. An example constraint for reserved VLANs is:
```json
[
{
"vid__gte": 100,
"vid__lt": 200
},
{
"status": "reserved"
}
]
```
For more details, refer to the permissions documentation.
NetBox supports LDAP authentication through a built-in backend for remote LDAP server authentication, with further details in the installation documentation.
Additionally, NetBox integrates with the python-social-auth library for single sign-on (SSO) 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 for configuring SSO are available in the authentication documentation.
=== 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 and resources.
## REST API
NetBox's REST API, built on the Django REST Framework, allows for creating, modifying, and deleting objects using 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.
## 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.
## Webhooks
Webhooks notify external systems of changes in NetBox, such as device status updates. Users can create a webhook with a receiver URL and define an event rule to trigger it. This facilitates event-based automation.
## Prometheus Metrics
NetBox features a `/metrics` view for Prometheus scrapers, utilizing the django-prometheus library.
=== 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, including:
## Tags
- User-created tags can be assigned to most objects for organization and filtering.
- Tags can be filtered in API requests, e.g.:
```no-highlight
GET /api/dcim/devices/?tag=monitored
```
- Multiple tags can be specified to match all assigned tags:
```no-highlight
GET /api/dcim/devices/?tag=monitored&tag=deprecated
```
## Bookmarks
- Users can bookmark frequently visited objects, which are accessible under their profile with custom filtering and ordering.
## Custom Fields
- Administrators can create custom fields for built-in objects to store additional data.
- Supports various data types and can reference other NetBox objects.
- Custom field data is stored alongside the object and accessible via the REST API.
## Custom Links
- Custom links allow referencing external resources related to NetBox objects.
- Links can be templatized, e.g.:
```no-highlight
http://server.local/vms/?name={{ object.name }}
```
## Custom Validation
- Custom validation rules can be configured for object creation and modification.
- Example configuration:
```python
CUSTOM_VALIDATORS = {
"dcim.device": [
{
"name": {
"regex": "[a-z]+\d{3}"
},
"asset_tag": {
"required": True
}
}
]
}
```
## Export Templates
- Objects can be exported in CSV formats or custom formats via export templates using Jinja2 template code.
## Reports
- Custom Python scripts (reports) can be installed to evaluate NetBox objects against rules.
- Reports can be executed via UI, REST API, or CLI and can be scheduled.
## Custom Scripts
- Custom scripts automate tasks and can prompt for user input.
- They have full access to the Python environment and NetBox's internal mechanisms, requiring familiarity with Python and the data model.
=== END FILE ===
**Installation & Upgrade**
**Installing NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/installation/index/
=== BEGIN FILE ===
# Installation
The document provides installation instructions for NetBox as a standalone, self-hosted application, specifically tested on Ubuntu 22.04 and CentOS 8.3. Users are advised to consult their distribution's documentation for dependency installation issues.
The setup process includes the following 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 | 12+ |
| Redis | 4.0+ |
For users upgrading from an existing installation, a reference to the [upgrading guide](upgrading.md) is provided.
=== 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, requiring PostgreSQL 12 or later. If a PostgreSQL service is already in place, proceed to the next section.
## Installation
=== "Ubuntu"
```no-highlight
sudo apt update
sudo apt install -y postgresql
```
=== "CentOS"
```no-highlight
sudo yum install -y postgresql-server
sudo postgresql-setup --initdb
```
Modify `/var/lib/pgsql/data/pg_hba.conf` for MD5 authentication:
```no-highlight
host all all 127.0.0.1/32 md5
host all all ::1/128 md5
```
Start and enable the PostgreSQL service:
```no-highlight
sudo systemctl enable --now postgresql
```
Verify PostgreSQL installation:
```no-highlight
psql -V
```
## Database Creation
Create a database for NetBox and assign a username and password:
```no-highlight
sudo -u postgres psql
```
Within the 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;
```
Use a strong password for security. Exit the shell with `\q`.
## Verify Service Status
Verify authentication with the following command:
```no-highlight
$ psql --username netbox --password --host localhost netbox
```
Confirm successful connection with `\conninfo` or exit with `\q`.
=== 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 in place, proceed to the next section.
=== "Ubuntu"
```no-highlight
sudo apt install -y redis-server
```
=== "CentOS"
```no-highlight
sudo yum install -y redis
sudo systemctl enable --now redis
```
Verify that the installed version of Redis is at least v4.0:
```no-highlight
redis-server -v
```
You may 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 functional:
```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 document outlines the steps for installing and configuring the NetBox application.
## Install System Packages
Install required system packages for NetBox:
!!! warning "Python 3.10 or later required"
NetBox supports Python 3.10, 3.11, and 3.12.
=== "Ubuntu"
```
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
```
=== "CentOS"
```
sudo yum install -y gcc libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config
```
Check Python version:
```
python3 -V
```
## Download NetBox
Two installation options are available: downloading a release archive or cloning the git repository.
### Option A: Download a Release Archive
Download the latest stable release from GitHub:
```
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:
```
sudo mkdir -p /opt/netbox/
cd /opt/netbox/
```
Install `git` if not already installed:
=== "Ubuntu"
```
sudo apt install -y git
```
=== "CentOS"
```
sudo yum install -y git
```
Clone the **master** branch:
```
sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .
```
## Create the NetBox System User
Create a system user account named `netbox`:
=== "Ubuntu"
```
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/
```
=== "CentOS"
```
sudo groupadd --system netbox
sudo adduser --system -g netbox 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:
```
cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py
```
Edit `configuration.py` to set:
* `ALLOWED_HOSTS`
* `DATABASE`
* `REDIS`
* `SECRET_KEY`
### ALLOWED_HOSTS
```python
ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123']
```
### DATABASE
```python
DATABASE = {
'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:
```
python3 ../generate_secret_key.py
```
## Optional Requirements
Install optional packages by adding them to `local_requirements.txt`.
### Remote File Storage
```
sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
```
### Remote Data Sources
Add libraries for integration:
```
sudo sh -c "echo 'boto3' >> /opt/netbox/local_requirements.txt"
```
### Sentry Integration
```
sudo sh -c "echo 'sentry-sdk' >> /opt/netbox/local_requirements.txt"
```
## Run the Upgrade Script
Run the upgrade script:
```
sudo /opt/netbox/upgrade.sh
```
If using a different Python version:
```
sudo PYTHON=/usr/bin/python3.10 /opt/netbox/upgrade.sh
```
## Create a Super User
Activate the virtual environment:
```
source /opt/netbox/venv/bin/activate
```
Create a superuser:
```
cd /opt/netbox/netbox
python3 manage.py createsuperuser
```
## Schedule the Housekeeping Task
Link the housekeeping script:
```
sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
```
## Test the Application
Run the development server:
```
python3 manage.py runserver 0.0.0.0:8000 --insecure
```
Access the application at .
!!! danger "Not for production use"
The development server is for testing only.
=== 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 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 and reload the systemd daemon:
```
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)
Tasks: 19 (limit: 4683)
Memory: 666.2M
CGroup: /system.slice/netbox.service
├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
...
```
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, which 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 running NetBox 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 the configuration file as needed for IP address, port number, or performance adjustments. Refer to the uWSGI documentation for parameters.
## systemd Setup
Copy 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 use uWSGI instead of gunicorn. Ensure user and group assignments are correct.
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 instructions focused 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. Install both public and private key files on the NetBox server, readable by the `netbox` user. Use the following command for 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 nginx 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 default configuration file:
```no-highlight
sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf
```
Enable required modules and the NetBox 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 now be able to connect to the HTTPS service at the specified server name or IP address. Note that configurations are minimal and may require adjustments 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 connects to the correct port (default 8001).
* SELinux allows HTTP network connections 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 using an external server, with a fallback to built-in Django users if authentication fails.
## Install Requirements
### Install System Packages
On Ubuntu:
```
sudo apt install -y libldap2-dev libsasl2-dev libssl-dev
```
On CentOS:
```
sudo yum install -y openldap-devel python3-devel
```
### 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` for username formats:
```python
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"
```
### 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 LDAP queries, add the following 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 requires reviewing release notes and backing up the current deployment. Users can upgrade directly to newer releases, except for major version increments, which require upgrading to the latest minor version first.
## 1. Review the Release Notes
Review all [release notes](../release-notes/index.md) published since the current version to identify any breaking changes.
## 2. Update Dependencies to Required Versions
NetBox dependencies include:
| Dependency | Supported Versions |
|------------|--------------------|
| Python | 3.10, 3.11, 3.12 |
| PostgreSQL | 12+ |
| Redis | 4.0+ |
## 3. Install the Latest Release
Upgrade by downloading the latest release package or cloning the `master` branch. Verify the installation method with:
```
ls -ld /opt/netbox /opt/netbox/.git
```
### Option A: Download a Release
Download the latest stable release:
```no-highlight
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 old version:
```no-highlight
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/
sudo cp -pr /opt/netbox-$OLDVER/netbox/media/ /opt/netbox/netbox/
sudo cp -r /opt/netbox-$OLDVER/netbox/scripts /opt/netbox/netbox/
sudo cp -r /opt/netbox-$OLDVER/netbox/reports /opt/netbox/netbox/
sudo cp /opt/netbox-$OLDVER/gunicorn.py /opt/netbox/
```
### Option B: Clone the Git Repository
If installed at `/opt/netbox`, pull the latest master branch:
```no-highlight
cd /opt/netbox
sudo git checkout master
sudo git pull origin master
```
## 4. Run the Upgrade Script
Verify optional Python packages and run the upgrade script:
```no-highlight
sudo ./upgrade.sh
```
If Python version is below 3.10, specify the path:
```no-highlight
sudo PYTHON=/usr/bin/python3.10 ./upgrade.sh
```
The script performs various tasks including rebuilding the Python virtual environment and applying database migrations.
## 5. Restart the NetBox Services
For installations prior to v2.7.9, update systemd service files before restarting:
```no-highlight
sudo systemctl restart netbox netbox-rq
```
## 6. Verify Housekeeping Scheduling
For upgrades from versions prior to v3.0, ensure a cron task is set for nightly housekeeping:
```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 new installations or adding data to existing deployments.
## Identify Current Sources of Truth
Understand existing authoritative data repositories, termed "sources of truth." These must be agreed upon and well-defined. Challenges may include:
* **Multiple conflicting sources**
* **Sources with no domain defined**
* **Inaccessible data formatting**
* **No source of truth**
Identify infrastructure data domains and their sources to determine what belongs in NetBox.
## Determine What to Move
Data should be moved to NetBox if a model exists for it. NetBox supports custom fields and plugins for extending its data model. Weigh the benefits of migrating data against the effort required. NetBox is continually developed, so future support for additional objects may be possible.
## Validate Existing Data
Validation is crucial before migration. Follow the GIGO principle. Tips for ensuring valid data include:
* Start with complete, well-formatted data (JSON or CSV recommended).
* Define custom validation rules in NetBox prior to import.
* Use custom scripts for patterned data population.
## Order of Operations
A recommended order for creating or importing NetBox objects is as follows:
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 not strictly required.
=== END FILE ===
**Populating Data**
URL: https://netboxlabs.com/docs/netbox/en/stable/getting-started/populating-data/
=== BEGIN FILE ===
# Populating Data
This section discusses methods to populate data in NetBox.
## Manual Object Creation
- Use object creation forms in the user interface.
- Not ideal for large imports; better to use other methods.
- To create a new object, find the type in the navigation menu and click the "Add" button.
- 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)
- Supports bulk import and updating of objects using CSV data.
- CSV can be imported as raw text or by uploading a file.
- Required columns are pre-populated in the import form.
- "id" field updates existing records.
- Some models require YAML-formatted data instead of CSV.
## Scripting
- Use scripts to automate data population based on patterns.
- Scripts ensure data validity and can reconstruct existing data without manual verification.
## REST API
- The REST API allows programmatic control over object creation.
- Supports bulk creation with a single request.
- Refer to the REST API documentation for more details.
=== END FILE ===
**Configuration**
**Configuring NetBox**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/index/
=== BEGIN FILE ===
# NetBox Configuration
NetBox's configuration file controls its functionality, including database settings, security controls, and user preferences. The default configuration is generally sufficient, but certain [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 in `configuration_example.py`. A custom configuration can be specified using the `NETBOX_CONFIGURATION` environment variable.
Some parameters can be defined in either `configuration.py` or the admin UI, with hard-coded settings in the configuration file taking precedence. Dynamic configuration parameters can be managed via the admin interface (Admin > Extras > Configuration Revisions) and may also 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)
The configuration file can be modified at any time, but the WSGI service must be restarted for changes to take effect:
```
$ sudo systemctl restart netbox
```
Dynamic parameters take effect immediately upon modification via the UI.
=== 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
NetBox requires a PostgreSQL 12 or later database. The `DATABASE` dictionary must include:
* `NAME` - Database name
* `USER` - PostgreSQL username
* `PASSWORD` - PostgreSQL password
* `HOST` - Database server address
* `PORT` - TCP port (default is 5432)
* `CONN_MAX_AGE` - Persistent connection lifetime (default is 300)
* `ENGINE` - PostgreSQL-compatible backend
Example:
```python
DATABASE = {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'netbox',
'USER': 'netbox',
'PASSWORD': 'J5brHrAXFLQSif0K',
'HOST': 'localhost',
'PORT': '',
'CONN_MAX_AGE': 300,
}
```
---
## REDIS
NetBox uses Redis for background task queuing. Configuration includes:
* `HOST` - Redis server address
* `PORT` - TCP port (default is 6379)
* `USERNAME` - Redis username (if set)
* `PASSWORD` - Redis password (if set)
* `DATABASE` - Numeric database ID
* `SSL` - Use SSL connection
* `INSECURE_SKIP_TLS_VERIFY` - Disable TLS verification (not recommended)
Example:
```python
REDIS = {
'tasks': {
'HOST': 'redis.example.com',
'PORT': 1234,
'USERNAME': 'netbox',
'PASSWORD': 'foobar',
'DATABASE': 0,
'SSL': False,
},
'caching': {
'HOST': 'localhost',
'PORT': 6379,
'USERNAME': '',
'PASSWORD': '',
'DATABASE': 1,
'SSL': False,
}
}
```
### UNIX Socket Support
Example for UNIX socket connection:
```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 includes:
* `SENTINELS`: List of sentinel instances
* `SENTINEL_SERVICE`: Master/service name
* `SENTINEL_TIMEOUT`: Connection timeout
Example:
```python
REDIS = {
'tasks': {
'SENTINELS': [('mysentinel.redis.example.com', 6379)],
'SENTINEL_SERVICE': 'netbox',
'SENTINEL_TIMEOUT': 10,
'PASSWORD': '',
'DATABASE': 0,
'SSL': False,
},
'caching': {
'SENTINELS': [
('mysentinel.redis.example.com', 6379),
('othersentinel.redis.example.com', 6379)
],
'SENTINEL_SERVICE': 'netbox',
'PASSWORD': '',
'DATABASE': 1,
'SSL': False,
}
}
```
---
## SECRET_KEY
A secret string for cryptographic hashes, at least 50 characters long. Should be unique across multiple nodes. Use `$INSTALL_ROOT/netbox/generate_secret_key.py` to generate a key. Changing this key invalidates existing user sessions.
=== END FILE ===
**System**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/system/
=== BEGIN FILE ===
# System Parameters
## BASE_PATH
Default: None
The base URL path to use when accessing NetBox. Example:
```python
BASE_PATH = 'netbox/'
```
## DEFAULT_LANGUAGE
Default: `en-us`
Defines the default preferred language/locale for requests.
## DOCS_ROOT
Default: `$INSTALL_ROOT/docs/`
The filesystem path to NetBox's documentation.
## EMAIL
Configuration items for sending email:
* `SERVER` - Email server hostname or IP
* `PORT` - TCP port (default: `25`)
* `USERNAME` - Authentication username
* `PASSWORD` - Authentication password
* `USE_SSL` - Use SSL (default: `False`)
* `USE_TLS` - Use TLS (default: `False`)
* `SSL_CERTFILE` - Path to SSL certificate file (optional)
* `SSL_KEYFILE` - Path to SSL private key file (optional)
* `TIMEOUT` - Connection timeout in seconds (default: `10`)
* `FROM_EMAIL` - Sender address
Note: `USE_SSL` and `USE_TLS` are mutually exclusive.
Test email configuration:
```no-highlight
# 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:
```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 IP addresses for debugging output.
## ISOLATED_DEPLOYMENT
Default: False
Set to True for deployments without Internet access.
## JINJA2_FILTERS
Default: `{}`
Dictionary of custom jinja2 filters. Example:
```python
def uppercase(x):
return str(x).upper()
JINJA2_FILTERS = {
'uppercase': uppercase,
}
```
## LOGGING
Default logging configuration logs INFO severity or higher. Example:
```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..` - Model-specific log messages
* `netbox.auth.*` - Authentication events
* `netbox.api.views.*` - REST API views
* `netbox.reports.*` - Report execution
* `netbox.scripts.*` - Custom script execution
* `netbox.views.*` - Web UI views
## MEDIA_ROOT
Default: `$INSTALL_ROOT/netbox/media/`
File path for media files storage.
## REPORTS_ROOT
Default: `$INSTALL_ROOT/netbox/reports/`
File path for custom reports storage.
## SCRIPTS_ROOT
Default: `$INSTALL_ROOT/netbox/scripts/`
File path for custom scripts storage.
## SEARCH_BACKEND
Default: `'netbox.search.backends.CachedValueSearchBackend'`
Path to the desired search backend class.
## STORAGE_BACKEND
Default: None
Backend storage engine for uploaded files. Supports integration with `django-storages` and `django-storage-swift`.
## STORAGE_CONFIG
Default: Empty
Configuration parameters for the storage backend.
## TIME_ZONE
Default: UTC
Time zone for dates and times.
## 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: True
If disabled, API token values will not be displayed after creation. Users must record token values 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 in NetBox. Custom schemes must include all default values.
---
## AUTH_PASSWORD_VALIDATORS
Configures Django's password validators for local user accounts. Default configuration:
```python
AUTH_PASSWORD_VALIDATORS = [
{
"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
"OPTIONS": {
"min_length": 12,
},
},
{
"NAME": "utilities.password_validation.AlphanumericPasswordValidator",
},
]
```
Criteria:
* Minimum length of 12 characters.
* At least one uppercase letter, one lowercase letter, and one numeric digit.
---
## CORS_ORIGIN_ALLOW_ALL
Default: False
If True, accepts CORS requests from all origins.
---
## CORS_ORIGIN_WHITELIST
## CORS_ORIGIN_REGEX_WHITELIST
Define 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 overwrite defaults.
---
## EXEMPT_VIEW_PERMISSIONS
Default: Empty list
Models exempt from view permissions. Example:
```python
EXEMPT_VIEW_PERMISSIONS = [
'dcim.site',
'dcim.region',
'ipam.prefix',
]
```
---
## LOGIN_PERSISTENCE
Default: False
If true, resets user's authentication session lifetime upon each valid request.
---
## LOGIN_REQUIRED
Default: True
Only authenticated users can access NetBox.
---
## LOGIN_TIMEOUT
Default: 1209600 seconds (14 days)
Lifetime of the authentication cookie.
---
## LOGOUT_REDIRECT_URL
Default: `'home'`
Redirect URL after logout.
---
## SECURE_HSTS_INCLUDE_SUBDOMAINS
Default: False
If true, applies HSTS policy to all subdomains.
---
## SECURE_HSTS_PRELOAD
Default: False
If true, includes preload directive in HSTS header.
---
## SECURE_HSTS_SECONDS
Default: 0
Sets HSTS header if non-zero value is specified.
---
## 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, session cookie is marked secure for HTTPS only.
---
## SESSION_FILE_PATH
Default: None
Specifies local file path for session data storage instead of 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 document outlines configuration parameters for remote authentication in NetBox, requiring `REMOTE_AUTH_ENABLED` to be true for effectiveness.
- **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 `{}`. Permissions mapping for new user accounts created via remote authentication.
- **REMOTE_AUTH_ENABLED**: Default `False`. Enables remote user authentication through HTTP headers.
- **REMOTE_AUTH_GROUP_HEADER**: Default `'HTTP_REMOTE_USER_GROUP'`. Name of the HTTP header for authenticated user 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.
- **REMOTE_AUTH_HEADER**: Default `'HTTP_REMOTE_USER'`. Name of the HTTP header for the authenticated user.
- **REMOTE_AUTH_USER_EMAIL**: Default `'HTTP_REMOTE_USER_EMAIL'`. Header for the authenticated user's email.
- **REMOTE_AUTH_USER_FIRST_NAME**: Default `'HTTP_REMOTE_USER_FIRST_NAME'`. Header for the authenticated user's first name.
- **REMOTE_AUTH_USER_LAST_NAME**: Default `'HTTP_REMOTE_USER_LAST_NAME'`. Header 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 section describes a mapping of models to custom validators defined locally for custom validation logic. An example configuration is provided:
```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 includes a database value, a human-friendly label, and may specify a color. Choices can replace or append to existing choices. Examples include:
To replace choices:
```python
FIELD_CHOICES = {
'dcim.Site.status': (
('foo', 'Foo', 'red'),
('bar', 'Bar', 'green'),
('baz', 'Baz', 'blue'),
)
}
```
To append choices:
```python
FIELD_CHOICES = {
'dcim.Site.status+': (
...
)
}
```
Supported model fields 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 include:
* `blue`
* `indigo`
* `purple`
* `pink`
* `red`
* `orange`
* `yellow`
* `green`
* `teal`
* `cyan`
* `gray`
* `black`
* `white`
---
## PROTECTION_RULES
This section outlines a mapping of models to custom validators that evaluate an object before its deletion. If validation fails, the object is not deleted. An example configuration is:
```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 to 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 is a dictionary for default preferences for new user accounts. Example to set default page size:
```python
DEFAULT_USER_PREFERENCES = {
"pagination": {
"per_page": 100
}
}
```
For a complete list of preferences, check `/user/preferences/`.
---
## PAGINATE_COUNT
Default: 50
Maximum number of objects to display 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. For 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 for integration.
---
## SENTRY_SAMPLE_RATE
The sampling rate for errors, must be a value between 0 (disabled) and 1.0 (report on all errors).
---
## SENTRY_SEND_DEFAULT_PII
Maps to the Sentry SDK's `send_default_pii` parameter. If enabled, certain personally identifiable information (PII) is added. Enabling this option may log sensitive data such as cookies and authentication tokens.
---
## SENTRY_TAGS
An optional dictionary of tag names and values for Sentry error reports. For 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 a value between 0 (disabled) and 1.0 (report on all transactions). A high sampling rate can induce performance penalties; a low sample rate of 10% to 20% is recommended for transaction reporting.
=== END FILE ===
**Plugins**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/plugins/
=== BEGIN FILE ===
# Plugin Parameters
## PLUGINS
Default: Empty
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: Empty
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.
=== 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, set this to False.
## CHANGELOG_RETENTION
Default: 90. The number of days to retain logged changes. Set to `0` for indefinite retention.
## 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.
## DJANGO_ADMIN_ENABLED
Default: False. Setting this to True installs the `django.contrib.admin` app.
## ENFORCE_GLOBAL_UNIQUE
Default: True. Prevents the creation of duplicate prefixes and IP addresses globally.
## FILE_UPLOAD_MAX_MEMORY_SIZE
Default: `2621440` (2.5 MB). The maximum amount of uploaded data held in memory.
## JOB_RETENTION
Default: 90. The number of days to retain job results. Set to `0` for indefinite retention.
## MAINTENANCE_MODE
Default: False. Setting this to True displays a maintenance mode banner and stops updating user activity.
## MAPS_URL
Default: `https://maps.google.com/?q=`. Specifies the URL for presenting a map.
## 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.
## PREFER_IPV4
Default: False. Set to True to prefer IPv4 over IPv6 when determining the primary IP address.
## QUEUE_MAPPINGS
Allows changing which queues are used internally 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.
## 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` (retries disabled). The maximum number of times a background task will be retried.
=== END FILE ===
**Development**
URL: https://netboxlabs.com/docs/netbox/en/stable/configuration/development/
=== BEGIN FILE ===
# Development Parameters
## DEBUG
Default: False
This setting enables debugging, which should only be used during development or troubleshooting. Only clients accessing NetBox from a recognized internal IP address will see debugging tools.
!!! warning
Never enable debugging on a production system, as it can expose sensitive data and impact performance.
---
## DEVELOPER
Default: False
This parameter prevents potentially dangerous actions, such as generating new database schema migrations. Enabling this setting also disables the debug warning banner in the UI. Set this to `True` only if actively developing 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, with attributes as columns. 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 requires a name, a human-friendly label, a weight, and can have a description. Fields can be marked as required and can have default values. 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, appearing under a single heading in the UI.
### Visibility & Editing
Display conditions include:
* **Always** (default)
* **If Set**
* **Hidden**
Editing conditions include:
* **Yes** (default)
* **No**
* **Hidden**
### Validation
Limited validation types include:
* Text: Regular expression
* Integer: Min/max value
* Selection: Must match prescribed choices
### Custom Selection Fields
Selection fields require a choice set with at least two choices, and default values must match provided choices.
### Custom Object Fields
These fields refer to specific NetBox objects and must define an `object_type`. Filtering can be applied using `query_params`.
## Custom Fields in Templates
Custom field data can be accessed in Jinja2 templates via 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. To set or change values, include nested JSON data.
=== 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. Each link includes display text and a URL, with the option to incorporate data from the viewed NetBox item using Jinja2 template code.
Example link definition:
* Text: `View NMS`
* URL: `https://nms.example.com/nodes/?name={{ object.name }}`
For a device named Router4, the rendered link would be:
```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 for HTML output, which can pose security risks. Only trusted users should be allowed to create or modify them.
## Context Data
Available context data for rendering custom links includes:
| 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 its attributes can be determined through the REST API representation or the NetBox source code.
## Conditional Rendering
Links with non-empty text are included on the page. Conditional Jinja2 logic can be used to control link rendering. For example, to display a link for active devices:
```jinja2
{% if object.status == 'active' %}View NMS{% endif %}
```
Or to show links for devices from 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 under a single button with the group's name.
## Table Columns
Custom links can be included in object tables by selecting them in the table configuration. Each link will render as a hyperlink, and when exported (e.g., as CSV), only the URL will be 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 entry to ensure data integrity, but custom validation rules can be added. Custom validation rules map object attributes to specific rules. For example:
```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 several validation types:
* `min`: Minimum value
* `max`: Maximum value
* `min_length`: Minimum string length
* `max_length`: Maximum string length
* `regex`: Regular expression application
* `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 the `CustomValidator` class and override the `validate()` method:
```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. They can be defined in three ways:
1. Plain JSON mapping
2. Dotted path to a custom validator class
3. Direct reference to a custom validator class
#### Plain Data
For simple rules, use JSON-compatible objects:
```python
CUSTOM_VALIDATORS = {
"dcim.site": [
{
"name": {
"min_length": 5,
"max_length": 30,
}
}
],
"dcim.device": [
{
"platform": {
"required": True,
}
}
]
}
```
#### Referencing Related Object Attributes
Attributes of related objects can be referenced using a dotted path:
```python
CUSTOM_VALIDATORS = {
"dcim.site": [
{
"region.name": {
"neq": "New York"
}
}
]
}
```
#### Validating Request Parameters
Custom validators can also validate request parameters:
```json
{
"request.user.username": {
"eq": "admin"
}
}
```
### Dotted Path to Class
Custom validator classes can be referenced by their Python path:
```python
CUSTOM_VALIDATORS = {
'dcim.site': (
'my_validators.Validator1',
'my_validators.Validator2',
),
'dcim.device': (
'my_validators.Validator3',
)
}
```
### Direct Class Reference
Classes can be imported 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 allows 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 may 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, export templates should be rendered via the REST API when `LOGIN_REQUIRED` is enabled. Use a `GET` request 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 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 %}
```
Generated 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 starting with NetBox v4.0, merging functionality with [custom scripts](./custom-scripts.md). 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
Logging methods differ between reports and scripts. Replace the generic `log()` method with `log_info()`. Use the following table for reference:
| 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.
Example update:
```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 previous job history. Users should convert legacy reports into custom scripts as soon as possible. The `pre_run()` and `post_run()` methods from Report are carried over to Script and called automatically. 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 various tasks such as:
* Automatically populating devices and cables for new site deployments
* Creating reserved prefixes or IP addresses
* Importing external data into NetBox
* Updating invalid or incomplete data
Scripts can validate data integrity by checking conditions like:
* Console connections for top-of-rack switches
* Loopback interfaces for routers
* Interface description formats
* 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. They have unrestricted access to the database, so only trusted scripts should be installed.
## Writing Custom Scripts
Scripts must inherit from the `extras.scripts.Script` base class, which provides form generation and logging functionality.
```python
from extras.scripts import Script
class MyScript(Script):
...
```
Scripts consist of variables and a `run()` method, which contains the execution logic. The `run()` method accepts:
* `data` - Dictionary of variable data
* `commit` - Boolean for database changes
Output appears under the "output" tab in the UI. Scripts can be ordered using the `script_order` variable.
```python
script_order = (MyCustomScript, AnotherCustomScript)
```
## Script Attributes
Attributes are defined in a `Meta` class and include:
### `name`
Human-friendly script name.
### `description`
Description of script functionality.
### `field_order`
Defines the order of script variables in the form.
### `fieldsets`
Groups and orders variables in the form.
```python
class MyScript(Script):
class Meta:
fieldsets = (
('First group', ('field1', 'field2', 'field3')),
('Second group', ('field4', 'field5')),
)
```
### `commit_default`
Sets default state of the commit checkbox.
### `scheduling_enabled`
Enables or disables script scheduling.
### `job_timeout`
Sets maximum runtime for the script.
## Accessing Request Data
Current HTTP request details are available via `self.request`, allowing access to the executing user and client IP address.
## Reading Data from Files
Use `load_yaml` and `load_json` methods to read data from files.
## Logging
Logging functions include:
* `log_debug(message=None, obj=None)`
* `log_success(message=None, obj=None)`
* `log_info(message=None, obj=None)`
* `log_warning(message=None, obj=None)`
* `log_failure(message=None, obj=None)`
## Test Methods
Define test methods prefixed with `test_` to check conditions during script execution.
### Example
```python
class DeviceConnectionsReport(Script):
description = "Validate the minimum physical connections for each device"
def test_console_connection(self):
...
```
## Change Logging
Take a snapshot of an object before editing to generate change log data.
```python
if obj.pk and hasattr(obj, 'snapshot'):
obj.snapshot()
```
## Error Handling
Use `AbortScript` to cleanly abort execution without a stack trace.
```python
from utilities.exceptions import AbortScript
if some_error:
raise AbortScript("Some meaningful error message")
```
## Variable Reference
### Default Options
All script variables support options like `default`, `description`, `label`, `required`, and `widget`.
### Variable Types
* `StringVar`
* `TextVar`
* `IntegerVar`
* `BooleanVar`
* `ChoiceVar`
* `MultiChoiceVar`
* `ObjectVar`
* `MultiObjectVar`
* `FileVar`
* `IPAddressVar`
* `IPAddressWithMaskVar`
* `IPNetworkVar`
* `DateVar`
* `DateTimeVar`
## Running Custom Scripts
Users must have specific permissions to run scripts.
### Via the Web UI
Run scripts through the UI by completing the form and clicking "run script".
### Via the API
Use a POST request to run a script via the API.
```no-highlight
curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; indent=4" \
http://netbox/api/extras/scripts/example.MyReport/ \
--data '{"data": {"foo": "somevalue", "bar": 123}, "commit": true}'
```
### Via the CLI
Invoke scripts using the management command.
```
python3 manage.py runscript [--commit] [--loglevel {debug,info,warning,error,critical}] [--data ""] .