Merge pull request #15975 from netbox-community/develop

Release v4.0.0

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -1,7 +1,7 @@
 ---
 name: 🐛 Bug Report
 description: Report a reproducible bug in the current release of NetBox
-labels: ["type: bug"]
+labels: ["type: bug", "status: needs triage"]
 body:
   - type: markdown
     attributes:
@@ -10,16 +10,28 @@ body:
         installation. If you're having trouble with installation or just looking for
         assistance with using NetBox, please visit our
         [discussion forum](https://github.com/netbox-community/netbox/discussions) instead.
+  - type: dropdown
+    attributes:
+      label: Deployment Type
+      description: >
+        How are you running NetBox? (For issues with the Docker image, please go to the
+        [netbox-docker](https://github.com/netbox-community/netbox-docker) repo.)
+      options:
+        - NetBox Cloud
+        - NetBox Enterprise
+        - Self-hosted
+    validations:
+      required: true
   - type: input
     attributes:
-      label: NetBox version
+      label: NetBox Version
       description: What version of NetBox are you currently running?
-      placeholder: v3.6.4
+      placeholder: v4.0.0
     validations:
       required: true
   - type: dropdown
     attributes:
-      label: Python version
+      label: Python Version
       description: What version of Python are you currently running?
       options:
         - "3.8"

.github/ISSUE_TEMPLATE/config.yml

@@ -7,6 +7,9 @@ contact_links:
   - name: ❓ Discussion
     url: https://github.com/netbox-community/netbox/discussions
     about: "If you're just looking for help, try starting a discussion instead."
+  - name: 🌎 Correct a Translation
+    url: https://explore.transifex.com/netbox-community/netbox/
+    about: "Spot an incorrect translation? You can propose a fix on Transifex."
   - name: 💡 Plugin Idea
     url: https://plugin-ideas.netbox.dev
     about: "Have an idea for a plugin? Head over to the ideas board!"

.github/ISSUE_TEMPLATE/documentation_change.yaml

@@ -1,7 +1,7 @@
 ---
 name: 📖 Documentation Change
 description: Suggest an addition or modification to the NetBox documentation
-labels: ["type: documentation"]
+labels: ["type: documentation", "status: needs triage"]
 body:
   - type: dropdown
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -1,7 +1,7 @@
 ---
 name: ✨ Feature Request
 description: Propose a new NetBox feature or enhancement
-labels: ["type: feature"]
+labels: ["type: feature", "status: needs triage"]
 body:
   - type: markdown
     attributes:
@@ -14,7 +14,7 @@ body:
     attributes:
       label: NetBox version
       description: What version of NetBox are you currently running?
-      placeholder: v3.6.4
+      placeholder: v4.0.0
     validations:
       required: true
   - type: dropdown

.github/ISSUE_TEMPLATE/translation.yaml

@@ -0,0 +1,37 @@
+---
+name: 🌍 Translation
+description: Request support for a new language in the user interface
+labels: ["type: translation"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        **NOTE:** This template is used only for proposing the addition of *new* languages. Please do
+        not use it to request changes to existing translations.
+  - type: input
+    attributes:
+      label: Language
+      description: What is the name of the language in English?
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: ISO 639-1 code
+      description: >
+        What is the two-letter [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+        assigned to the language?
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Volunteer
+      description: Are you a fluent speaker of this language **and** willing to contribute a translation map?
+      options:
+        - "Yes"
+        - "No"
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Comments
+      description: Any other notes you would like to share

.github/workflows/auto-assign-issue.yml

@@ -0,0 +1,21 @@
+# auto-assign-issue (https://github.com/marketplace/actions/auto-assign-issue)
+name: Issue assignment
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  auto-assign:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: pozil/auto-assign-issue@v1
+        if: "contains(github.event.issue.labels.*.name, 'status: needs triage')"
+        with:
+          # Weighted assignments
+          assignees: arthanson:3, jeffgdotorg:3, jeremystretch:3, abhi1693, DanSheps
+          numOfAssignee: 1
+          abortIfPreviousAssignees: true

.github/workflows/ci.yml

@@ -9,8 +9,8 @@ jobs:
       NETBOX_CONFIGURATION: netbox.configuration_testing
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.10', '3.11', '3.12']
-        node-version: ['14.x']
+        node-version: ['18.x']
     services:
       redis:
         image: redis
@@ -68,6 +68,9 @@ jobs:
     - name: Collect static files
       run: python netbox/manage.py collectstatic --no-input
 
+    - name: Check for missing migrations
+      run: python netbox/manage.py makemigrations --check
+
     - name: Check PEP8 compliance
       run: pycodestyle --ignore=W504,E501 --exclude=node_modules netbox/
 
@@ -81,4 +84,4 @@ jobs:
       run: coverage run --source="netbox/" netbox/manage.py test netbox/ --parallel
 
     - name: Show coverage report
-      run: coverage report --skip-covered --omit *migrations*
+      run: coverage report --skip-covered --omit '*/migrations/*,*/tests/*'

.github/workflows/close-stale-issues.yml

@@ -1,5 +1,5 @@
 # close-stale-issues (https://github.com/marketplace/actions/close-stale-issues)
-name: 'Close stale issues/PRs'
+name: Close stale issues/PRs
 
 on:
   schedule:
@@ -12,10 +12,9 @@ permissions:
 
 jobs:
   stale:
-
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v8
+      - uses: actions/stale@v9
         with:
           close-issue-message: >
             This issue has been automatically closed due to lack of activity. In an

.github/workflows/lock-threads.yml

@@ -1,5 +1,5 @@
 # lock-threads (https://github.com/marketplace/actions/lock-threads)
-name: 'Lock threads'
+name: Lock threads
 
 on:
   schedule:
@@ -9,13 +9,15 @@ on:
 permissions:
   issues: write
   pull-requests: write
+  discussions: write
 
 jobs:
   lock:
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/lock-threads@v4
+      - uses: dessant/lock-threads@v5
         with:
           issue-inactive-days: 90
           pr-inactive-days: 30
+          discussion-inactive-days: 180
           issue-lock-reason: 'resolved'

.readthedocs.yaml

@@ -1,8 +1,8 @@
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.12"
 mkdocs:
   configuration: mkdocs.yml
 python:

CONTRIBUTING.md

@@ -36,6 +36,8 @@ NetBox users are welcome to participate in either role, on stage or in the crowd
 
 ## :bug: Reporting Bugs
 
+:warning: Bug reports are used to call attention to some unintended or unexpected behavior in NetBox, such as when an error occurs or when the result of taking some action is inconsistent with the documentation. **Bug reports may not be used to suggest new functionality**; please see "feature requests" below if that is your goal.
+
 * First, ensure that you're running the [latest stable version](https://github.com/netbox-community/netbox/releases) of NetBox. If you're running an older version, it's likely that the bug has already been fixed.
 
 * Next, search our [issues list](https://github.com/netbox-community/netbox/issues?q=is%3Aissue) to see if the bug you've found has already been reported. If you come across a bug report that seems to match, please click "add a reaction" in the top right corner of the issue and add a thumbs up (:thumbsup:). This will help draw more attention to it. Any comments you can add to provide additional information or context would also be much appreciated.
@@ -84,12 +86,16 @@ intake policy](https://github.com/netbox-community/netbox/wiki/Issue-Intake-Poli
 
 * In most cases, it is not necessary to add a changelog entry: A maintainer will take care of this when the PR is merged. (This helps avoid merge conflicts resulting from multiple PRs being submitted simultaneously.)
 
-* All code submissions should meet the following criteria (CI will enforce these checks):
+* All code submissions must meet the following criteria (CI will enforce these checks where feasible):
+  * Consist entirely of original work
   * Python syntax is valid
   * All tests pass when run with `./manage.py test`
   * PEP 8 compliance is enforced, with the exception that lines may be
       greater than 80 characters in length
 
+> [!CAUTION]
+> Any contributions which include AI-generated or reproduced content will be rejected.
+
 * Some other tips to keep in mind:
   * If you'd like to volunteer for someone else's issue, please post a comment on that issue letting us know. (This will allow the maintainers to assign it to you.)
   * Check out our [developer docs](https://docs.netbox.dev/en/stable/development/getting-started/) for tips on setting up your development environment.
@@ -115,8 +121,6 @@ We're always looking for motivated individuals to join the maintainers team and
 
 We generally ask that maintainers dedicate around four hours of work to the project each week on average, which includes both hands-on development and project management tasks such as issue triage. Maintainers are also encouraged (but not required) to attend our bi-weekly Zoom call to catch up on recent items.
 
-Many maintainers petition their employer to grant some of their paid time to work on NetBox. In doing so, your employer becomes eligible to be featured as a [NetBox sponsor](https://github.com/netbox-community/netbox/wiki/Sponsorship).
-
 Interested? You can contact our lead maintainer, Jeremy Stretch, at jeremy@netbox.dev or on the [NetDev Community Slack](https://netdev.chat/). We'd love to have you on the team!
 
 ## :heart: Other Ways to Contribute

README.md

@@ -1,86 +1,129 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/netbox-community/netbox/develop/docs/netbox_logo.svg" width="400" alt="NetBox logo" />
-  <p>The premier source of truth powering network automation</p>
+  <p><strong>The cornerstone of every automated network</strong></p>
-  <img src="https://github.com/netbox-community/netbox/workflows/CI/badge.svg?branch=master" alt="CI status" />
+  <a href="https://github.com/netbox-community/netbox/releases"><img src="https://img.shields.io/github/v/release/netbox-community/netbox" alt="Latest release" /></a>
+  <a href="https://github.com/netbox-community/netbox/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache_2.0-blue.svg" alt="License" /></a>
+  <a href="https://github.com/netbox-community/netbox/graphs/contributors"><img src="https://img.shields.io/github/contributors/netbox-community/netbox?color=blue" alt="Contributors" /></a>
+  <a href="https://github.com/netbox-community/netbox/stargazers"><img src="https://img.shields.io/github/stars/netbox-community/netbox?style=flat" alt="GitHub stars" /></a>
+  <a href="https://explore.transifex.com/netbox-community/netbox/"><img src="https://img.shields.io/badge/languages-7-blue" alt="Languages supported" /></a>
+  <a href="https://github.com/netbox-community/netbox/actions/workflows/ci.yml"><img src="https://github.com/netbox-community/netbox/workflows/CI/badge.svg?branch=master" alt="CI status" /></a>
   <p></p>
 </div>
 
-NetBox is the leading solution for modeling and documenting modern networks. By
+NetBox exists to empower network engineers. Since its release in 2016, it has become the go-to solution for modeling and documenting network infrastructure for thousands of organizations worldwide. As a successor to legacy IPAM and DCIM applications, NetBox provides a cohesive, extensive, and accessible data model for all things networked. By providing a single robust user interface and programmable APIs for everything from cable maps to device configurations, NetBox serves as the central source of truth for the modern network.
-combining the traditional disciplines of IP address management (IPAM) and
-datacenter infrastructure management (DCIM) with powerful APIs and extensions,
-NetBox provides the ideal "source of truth" to power network automation.
-Available as open source software under the Apache 2.0 license, NetBox serves
-as the cornerstone for network automation in thousands of organizations.
 
-* **Physical infrastructure:** Accurately model the physical world, from global regions down to individual racks of gear. Then connect everything - network, console, and power!
+<p align="center">
-* **Modern IPAM:** All the standard IPAM functionality you expect, plus VRF import/export tracking, VLAN management, and overlay support.
+  <a href="#netboxs-role">NetBox's Role</a> |
-* **Data circuits:** Confidently manage the delivery of critical circuits from various service providers, modeled seamlessly alongside your own infrastructure.
+  <a href="#why-netbox">Why NetBox?</a> |
-* **Power tracking:** Map the distribution of power from upstream sources to individual feeds and outlets.
+  <a href="#getting-started">Getting Started</a> |
-* **Organization:** Manage tenant and contact assignments natively.
+  <a href="#get-involved">Get Involved</a> |
-* **Powerful search:** Easily find anything you need using a single global search function.
+  <a href="#project-stats">Project Stats</a> |
-* **Comprehensive logging:** Leverage both automatic change logging and user-submitted journal entries to track your network's growth over time.
+  <a href="#screenshots">Screenshots</a>
-* **Endless customization:** Custom fields, custom links, tags, export templates, custom validation, reports, scripts, and more!
+</p>
-* **Flexible permissions:** An advanced permissions systems enables very flexible delegation of permissions.
-* **Integrations:** Easily connect NetBox to your other tooling via its REST & GraphQL APIs.
-* **Plugins:** Not finding what you need in the core application? Try one of many community plugins - or build your own!
 
-![Screenshot of NetBox UI](docs/media/screenshots/netbox-ui.png "NetBox UI")
+<p align="center">
+  <img src="docs/media/screenshots/home-light.png" width="600" alt="NetBox user interface screenshot" />
+</p>
+
+## NetBox's Role
+
+NetBox functions as the **source of truth** for your network infrastructure. Its job is to define and validate the _intended state_ of all network components and resources. NetBox does not interact with network nodes directly; rather, it makes this data available programmatically to purpose-built automation, monitoring, and assurance tools. This separation of duties enables the construction of a robust yet flexible automation system.
+
+<p align="center">
+  <img src="docs/media/misc/reference_architecture.png" alt="Reference network automation architecture" />
+</p>
+
+The diagram above illustrates the recommended deployment architecture for an automated network, leveraging NetBox as the central authority for network state. This approach allows your team to swap out individual tools to meet changing needs while retaining a predictable, modular workflow.
+
+## Why NetBox?
+
+### Comprehensive Data Model
+
+Racks, devices, cables, IP addresses, VLANs, circuits, power, VPNs, and lots more: NetBox is built for networks. Its comprehensive and thoroughly inter-linked data model provides for natural and highly structured modeling of myriad network primitives that just isn't possible using general-purpose tools. And there's no need to waste time contemplating how to build out a database: Everything is ready to go upon installation.
+
+### Focused Development
+
+NetBox strives to meet a singular goal: Provide the best available solution for making network infrastructure programmatically accessible. Unlike "all-in-one" tools which awkwardly bolt on half-baked features in an attempt to check every box, NetBox is committed to its core function. NetBox provides the best possible solution for modeling network infrastructure, and provides rich APIs for integrating with tools that excel in other areas of network automation.
+
+### Extensible and Customizable
+
+No two networks are exactly the same. Users are empowered to extend NetBox's native data model with custom fields and tags to best suit their unique needs. You can even write your own plugins to introduce entirely new objects and functionality!
+
+### Flexible Permissions
+
+NetBox includes a fully customizable permission system, which affords administrators incredible granularity when assigning roles to users and groups. Want to restrict certain users to working only with cabling and not be able to change IP addresses? Or maybe each team should have access only to a particular tenant? NetBox enables you to craft roles as you see fit.
+
+### Custom Validation & Protection Rules
+
+The data you put into NetBox is crucial to network operations. In addition to its robust native validation rules, NetBox provides mechanisms for administrators to define their own custom validation rules for objects. Custom validation can be used both to ensure new or modified objects adhere to a set of rules, and to prevent the deletion of objects which don't meet certain criteria. (For example, you might want to prevent the deletion of a device with an "active" status.)
+
+### Device Configuration Rendering
+
+NetBox can render user-created Jinja2 templates to generate device configurations from its own data. Configuration templates can be uploaded individually or pulled automatically from an external source, such as a git repository. Rendered configurations can be retrieved via the REST API for application directly to network devices via a provisioning tool such as Ansible or Salt.
+
+### Custom Scripts
+
+Complex workflows, such as provisioning a new branch office, can be tedious to carry out via the user interface. NetBox allows you to write and upload custom scripts that can be run directly from the UI. Scripts prompt users for input and then automate the necessary tasks to greatly simplify otherwise burdensome processes.
+
+### Automated Events
+
+Users can define event rules to automatically trigger a custom script or outbound webhook in response to a NetBox event. For example, you might want to automatically update a network monitoring service whenever a new device is added to NetBox, or update a DHCP server when an IP range is allocated.
+
+### Comprehensive Change Logging
+
+NetBox automatically logs the creation, modification, and deletion of all managed objects, providing a thorough change history. Changes can be attributed to the executing user, and related changes are grouped automatically by request ID.
+
+> [!NOTE]
+> A complete list of NetBox's myriad features can be found in [the introductory documentation](https://docs.netbox.dev/en/stable/introduction/).
 
 ## Getting Started
 
-<div align="center">
-
-  [![NetBox logo](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/deploy/deploy1.png)](https://github.com/netbox-community/netbox)
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  [![Docker logo](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/deploy/deploy2.png)](https://github.com/netbox-community/netbox-docker)
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  [![NetBox Labs logo](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/deploy/deploy3.png)](https://netboxlabs.com/netbox-cloud/)
-
-</div>
-
 * Just want to explore? Check out [our public demo](https://demo.netbox.dev/) right now!
 * The [official documentation](https://docs.netbox.dev) offers a comprehensive introduction.
 * Check out [our wiki](https://github.com/netbox-community/netbox/wiki/Community-Contributions) for even more projects to get the most out of NetBox!
 
+<p align="center">
+  <a href="https://netboxlabs.com/netbox-cloud/"><img src="docs/media/misc/netbox_cloud.png" alt="NetBox Cloud" /></a><br />
+  Looking for a managed solution? Check out <strong><a href="https://netboxlabs.com/netbox-cloud/">NetBox Cloud</a></strong> or <strong><a href="https://netboxlabs.com/netbox-enterprise/">NetBox Enterprise</a></strong>!
+</p>
+
 ## Get Involved
 
 * Follow [@NetBoxOfficial](https://twitter.com/NetBoxOfficial) on Twitter!
 * Join the conversation on [the discussion forum](https://github.com/netbox-community/netbox/discussions) and [Slack](https://netdev.chat/)!
 * Already a power user? You can [suggest a feature](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+feature&template=feature_request.yaml) or [report a bug](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+bug&template=bug_report.yaml) on GitHub.
 * Contributions from the community are encouraged and appreciated! Check out our [contributing guide](CONTRIBUTING.md) to get started.
+* [Share your idea](https://plugin-ideas.netbox.dev/) for a new plugin, or [learn how to build one](https://github.com/netbox-community/netbox-plugin-tutorial) yourself!
 
 ## Project Stats
 
-<div align="center">
+<p align="center">
   <a href="https://github.com/netbox-community/netbox/commits"><img src="https://images.repography.com/29023055/netbox-community/netbox/recent-activity/whQtEr_TGD9PhW1BPlhlEQ5jnrgQ0KJpm-LlGtpoGO0/3Kx_iWUSBRJ5-AI4QwJEJWrUDEz3KrX2lvh8aYE0WXY_timeline.svg" alt="Timeline graph"></a>
   <a href="https://github.com/netbox-community/netbox/issues"><img src="https://images.repography.com/29023055/netbox-community/netbox/recent-activity/whQtEr_TGD9PhW1BPlhlEQ5jnrgQ0KJpm-LlGtpoGO0/3Kx_iWUSBRJ5-AI4QwJEJWrUDEz3KrX2lvh8aYE0WXY_issues.svg" alt="Issues graph"></a>
   <a href="https://github.com/netbox-community/netbox/pulls"><img src="https://images.repography.com/29023055/netbox-community/netbox/recent-activity/whQtEr_TGD9PhW1BPlhlEQ5jnrgQ0KJpm-LlGtpoGO0/3Kx_iWUSBRJ5-AI4QwJEJWrUDEz3KrX2lvh8aYE0WXY_prs.svg" alt="Pull requests graph"></a>
   <a href="https://github.com/netbox-community/netbox/graphs/contributors"><img src="https://images.repography.com/29023055/netbox-community/netbox/recent-activity/whQtEr_TGD9PhW1BPlhlEQ5jnrgQ0KJpm-LlGtpoGO0/3Kx_iWUSBRJ5-AI4QwJEJWrUDEz3KrX2lvh8aYE0WXY_users.svg" alt="Top contributors"></a>
   <br />Stats via <a href="https://repography.com">Repography</a>
-</div>
+</p>
-
-## Sponsors
-
-<div align="center">
-
-  [![NetBox Labs](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/netbox_labs.png)](https://netboxlabs.com)
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  [![DigitalOcean](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/digitalocean.png)](https://try.digitalocean.com/developer-cloud)
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  [![Sentry](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/sentry.png)](https://sentry.io)
-  <br />
-  [![Equinix Metal](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/equinix.png)](https://metal.equinix.com)
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  [![OneMind Services](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/onemind_services.png)](https://onemindservices.com)
-
-</div>
 
 ## Screenshots
 
-![Screenshot of main page (dark mode)](docs/media/screenshots/home-dark.png "Main page (dark mode)")
+<p align="center">
-
+  <strong>NetBox Dashboard (Light Mode)</strong><br />
-![Screenshot of rack elevation](docs/media/screenshots/rack.png "Rack elevation")
+  <img src="docs/media/screenshots/home-light.png" width="600" alt="NetBox dashboard (light mode)" />
-
+</p>
-![Screenshot of prefixes hierarchy](docs/media/screenshots/prefixes-list.png "Prefixes hierarchy")
+<p align="center">
-
+  <strong>NetBox Dashboard (Dark Mode)</strong><br />
-![Screenshot of cable trace](docs/media/screenshots/cable-trace.png "Cable tracing")
+  <img src="docs/media/screenshots/home-dark.png" width="600" alt="NetBox dashboard (dark mode)" />
+</p>
+<p align="center">
+  <strong>Prefixes List</strong><br />
+  <img src="docs/media/screenshots/prefixes-list.png" width="600" alt="Prefixes list" />
+</p>
+<p align="center">
+  <strong>Rack View</strong><br />
+  <img src="docs/media/screenshots/rack.png" width="600" alt="Rack view" />
+</p>
+<p align="center">
+  <strong>Cable Trace</strong><br />
+  <img src="docs/media/screenshots/cable-trace.png" width="600" alt="Cable trace" />
+</p>

base_requirements.txt

@@ -1,10 +1,6 @@
-# HTML sanitizer
-# https://github.com/mozilla/bleach/blob/main/CHANGES
-bleach
-
 # The Python web framework on which NetBox is built
 # https://docs.djangoproject.com/en/stable/releases/
-Django<5.0
+Django<5.1
 
 # Django middleware which permits cross-domain API requests
 # https://github.com/adamchainz/django-cors-headers/blob/main/CHANGELOG.rst
@@ -18,14 +14,13 @@ django-debug-toolbar
 # https://github.com/carltongibson/django-filter/blob/main/CHANGES.rst
 django-filter
 
-# Django debug toolbar extension with support for GraphiQL
+# HTMX utilities for Django
-# https://github.com/flavors/django-graphiql-debug-toolbar/blob/main/CHANGES.rst
+# https://django-htmx.readthedocs.io/en/latest/changelog.html
-django-graphiql-debug-toolbar
+django-htmx
 
 # Modified Preorder Tree Traversal (recursive nesting of objects)
-# Pinned to 0.14.0; 0.15.0 requires Python 3.9+
 # https://github.com/django-mptt/django-mptt/blob/main/CHANGELOG.rst
-django-mptt==0.14.0
+django-mptt
 
 # Context managers for PostgreSQL advisory locks
 # https://github.com/Xof/django-pglocks/blob/master/CHANGES.txt
@@ -75,11 +70,6 @@ drf-spectacular-sidecar
 # https://github.com/kurtmckee/feedparser/blob/develop/CHANGELOG.rst
 feedparser
 
-# Django wrapper for Graphene (GraphQL support)
-# https://github.com/graphql-python/graphene-django/releases
-# Pinned to v3.0.0 for GraphiQL UI issue (see #12762)
-graphene_django==3.0.0
-
 # WSGI HTTP server
 # https://docs.gunicorn.org/en/latest/news.html
 gunicorn
@@ -89,9 +79,8 @@ gunicorn
 Jinja2
 
 # Simple markup language for rendering HTML
-# https://python-markdown.github.io/change_log/
+# https://python-markdown.github.io/changelog/
-# mkdocs currently requires Markdown v3.3
+Markdown
-Markdown<3.4
 
 # File inclusion plugin for Python-Markdown
 # https://github.com/cmacmackin/markdown-include
@@ -102,13 +91,17 @@ markdown-include
 mkdocs-material
 
 # Introspection for embedded code
-# https://github.com/mkdocstrings/mkdocstrings/blob/master/CHANGELOG.md
+# https://github.com/mkdocstrings/mkdocstrings/blob/main/CHANGELOG.md
 mkdocstrings[python-legacy]
 
 # Library for manipulating IP prefixes and addresses
-# https://github.com/netaddr/netaddr/blob/master/CHANGELOG
+# https://github.com/netaddr/netaddr/blob/master/CHANGELOG.rst
 netaddr
 
+# Python bindings to the ammonia HTML sanitization library.
+# https://github.com/messense/nh3
+nh3
+
 # Fork of PIL (Python Imaging Library) for image processing
 # https://github.com/python-pillow/Pillow/blob/main/CHANGES.rst
 Pillow
@@ -125,10 +118,6 @@ PyYAML
 # https://github.com/psf/requests/blob/main/HISTORY.md
 requests
 
-# Sentry SDK
-# https://github.com/getsentry/sentry-python/blob/master/CHANGELOG.md
-sentry-sdk
-
 # Social authentication framework
 # https://github.com/python-social-auth/social-core/blob/master/CHANGELOG.md
 social-auth-core
@@ -137,8 +126,16 @@ social-auth-core
 # https://github.com/python-social-auth/social-app-django/blob/master/CHANGELOG.md
 social-auth-app-django
 
+# Strawberry GraphQL
+# https://github.com/strawberry-graphql/strawberry/blob/main/CHANGELOG.md
+strawberry-graphql
+
+# Strawberry GraphQL Django extension
+# https://github.com/strawberry-graphql/strawberry-django/blob/main/CHANGELOG.md
+strawberry-graphql-django
+
 # SVG image rendering (used for rack elevations)
-# hhttps://github.com/mozman/svgwrite/blob/master/NEWS.rst
+# https://github.com/mozman/svgwrite/blob/master/NEWS.rst
 svgwrite
 
 # Tabular dataset library (for table-based exports)

contrib/generated_schema.json

@@ -1,5 +1,7 @@
 {
     "type": "object",
+    "$id": "urn:devicetype-library:generated-schema",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": false,
     "definitions": {
         "airflow": {
@@ -384,7 +386,10 @@
                         "8gfc-sfpp",
                         "16gfc-sfpp",
                         "32gfc-sfp28",
+                        "32gfc-sfpp",
                         "64gfc-qsfpp",
+                        "64gfc-sfpdd",
+                        "64gfc-sfpp",
                         "128gfc-qsfp28",
                         "infiniband-sdr",
                         "infiniband-ddr",

contrib/gunicorn.py

@@ -14,3 +14,7 @@ timeout = 120
 # The maximum number of requests a worker can handle before being respawned
 max_requests = 5000
 max_requests_jitter = 500
+
+# Uncomment this line to accept HTTP headers containing underscores, e.g. for remote
+# authentication support. See https://docs.gunicorn.org/en/stable/settings.html#header-map
+# header-map = 'dangerous'

contrib/netbox.service

@@ -12,8 +12,12 @@ Group=netbox
 PIDFile=/var/tmp/netbox.pid
 WorkingDirectory=/opt/netbox
 
+# Remove the following line if using uWSGI instead of Gunicorn
 ExecStart=/opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
 
+# Uncomment the following line if using uWSGI instead of Gunicorn
+#ExecStart=/opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini
+
 Restart=on-failure
 RestartSec=30
 PrivateTmp=true

contrib/nginx.conf

@@ -14,10 +14,20 @@ server {
     }
 
     location / {
+        # Remove these lines if using uWSGI instead of Gunicorn
         proxy_pass http://127.0.0.1:8001;
         proxy_set_header X-Forwarded-Host $http_host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Uncomment these lines if using uWSGI instead of Gunicorn
+        # 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;
+
     }
 }
 

contrib/uwsgi.ini

@@ -0,0 +1,18 @@
+[uwsgi]
+; bind to the specified UNIX/TCP socket and port (usually localhost)
+socket = 127.0.0.1:8001
+
+; fail to start if any parameter in the configuration file isn’t explicitly understood by uWSGI.
+strict = true
+
+; re-spawn and pre-fork workers
+master = true
+
+; clear environment on exit
+vacuum = true
+
+; exit if no app can be loaded
+need-app = true
+
+; do not use multiple interpreters
+single-interpreter = true

docs/_theme/main.html

@@ -2,8 +2,8 @@
 
 {% block site_meta %}
   {{ super() }}
-  {# Disable search indexing unless we're building for ReadTheDocs (see #10496) #}
+  {# Disable search indexing unless we're building for ReadTheDocs #}
-  {% if page.canonical_url != 'https://docs.netbox.dev/' %}
+  {% if not config.extra.readthedocs %}
     <meta name="robots" content="noindex">
   {% endif %}
 {% endblock %}

docs/administration/authentication/microsoft-azure-ad.md

@@ -73,7 +73,7 @@ You should be redirected to Microsoft's authentication portal. Enter the usernam
 
 If successful, you will be redirected back to the NetBox UI, and will be logged in as the AD user. You can verify this by navigating to your profile (using the button at top right).
 
-This user account has been replicated locally to NetBox, and can now be assigned groups and permissions within the NetBox admin UI.
+This user account has been replicated locally to NetBox, and can now be assigned groups and permissions.
 
 ## Troubleshooting
 

docs/administration/authentication/okta.md

@@ -67,4 +67,4 @@ You should be redirected to Okta's authentication portal. Enter the username/ema
 
 If successful, you will be redirected back to the NetBox UI, and will be logged in as the Okta user. You can verify this by navigating to your profile (using the button at top right).
 
-This user account has been replicated locally to NetBox, and can now be assigned groups and permissions within the NetBox admin UI.
+This user account has been replicated locally to NetBox, and can now be assigned groups and permissions.

docs/administration/authentication/overview.md

@@ -2,9 +2,9 @@
 
 ## Local Authentication
 
-Local user accounts and groups can be created in NetBox under the "Authentication and Authorization" section of the administrative user interface. This interface is available only to users with the "staff" permission enabled.
+Local user accounts and groups can be created in NetBox under the "Authentication" section in the "Admin" menu. This section is available only to users with the "staff" permission enabled.
 
-At a minimum, each user account must have a username and password set. User accounts may also denote a first name, last name, and email address. [Permissions](../permissions.md) may also be assigned to users and/or groups within the admin UI.
+At a minimum, each user account must have a username and password set. User accounts may also denote a first name, last name, and email address. [Permissions](../permissions.md) may also be assigned to individual users and/or groups as needed.
 
 ## Remote Authentication
 
@@ -26,7 +26,10 @@ REMOTE_AUTH_BACKEND = 'netbox.authentication.RemoteUserBackend'
 
 Another option for remote authentication in NetBox is to enable HTTP header-based user assignment. The front end HTTP server (e.g. nginx or Apache) performs client authentication as a process external to NetBox, and passes information about the authenticated user via HTTP headers. By default, the user is assigned via the `REMOTE_USER` header, but this can be customized via the `REMOTE_AUTH_HEADER` configuration parameter.
 
-Optionally, user profile information can be supplied by `REMOTE_USER_FIRST_NAME`, `REMOTE_USER_LAST_NAME` and `REMOTE_USER_EMAIL` headers. These are saved to the users profile during the authentication process. These headers can be customized like the `REMOTE_USER` header.
+Optionally, user profile information can be supplied by `REMOTE_USER_FIRST_NAME`, `REMOTE_USER_LAST_NAME` and `REMOTE_USER_EMAIL` headers. These are saved to the user's profile during the authentication process. These headers can be customized like the `REMOTE_USER` header.
+
+!!! warning Verify Header Compatibility
+    Some WSGI servers may drop headers which contain unsupported characters. For instance, gunicorn v22.0 and later silently drops HTTP headers containing underscores. This behavior can be disabled by changing gunicorn's [`header_map`](https://docs.gunicorn.org/en/stable/settings.html#header-map) setting to `dangerous`.
 
 ### Single Sign-On (SSO)
 

docs/administration/error-reporting.md

@@ -4,27 +4,15 @@
 
 ### Enabling Error Reporting
 
-NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, simply set `SENTRY_ENABLED` to True in `configuration.py`. Errors will be sent to a Sentry ingestor maintained by the NetBox team for analysis.
+NetBox supports native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, set `SENTRY_ENABLED` to True and define your unique [data source name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) in `configuration.py`.
-
-```python
-SENTRY_ENABLED = True
-```
-
-### Using a Custom DSN
-
-If you prefer instead to use your own Sentry ingestor, you'll need to first create a new project under your Sentry account to represent your NetBox deployment and obtain its corresponding data source name (DSN). This looks like a URL similar to the example below:
-
-```
-https://examplePublicKey@o0.ingest.sentry.io/0
-```
-
-Once you have obtained a DSN, configure Sentry in NetBox's `configuration.py` file with the following parameters:
 
 ```python
 SENTRY_ENABLED = True
 SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
 ```
 
+Setting `SENTRY_ENABLED` to False will disable the Sentry integration.
+
 ### Assigning Tags
 
 You can optionally attach one or more arbitrary tags to the outgoing error reports if desired by setting the `SENTRY_TAGS` parameter:

docs/administration/permissions.md

@@ -70,8 +70,6 @@ The `$user` token can be used only as a constraint value, or as an item within a
 
 ### Default Permissions
 
-!!! info "This feature was introduced in NetBox v3.6."
-
 While permissions are typically assigned to specific groups and/or users, it is also possible to define a set of default permissions that are applied to _all_ authenticated users. This is done using the [`DEFAULT_PERMISSIONS`](../configuration/security.md#default_permissions) configuration parameter. Note that statically configuring permissions for specific users or groups is **not** supported.
 
 ### Example Constraint Definitions

docs/configuration/data-validation.md

@@ -87,3 +87,24 @@ The following colors are supported:
 * `gray`
 * `black`
 * `white`
+
+---
+
+## PROTECTION_RULES
+
+!!! tip "Dynamic Configuration Parameter"
+
+This is a mapping of models to [custom validators](../customization/custom-validation.md) against which an object is evaluated immediately prior to its deletion. If validation fails, the object is not deleted. An example is provided below:
+
+```python
+PROTECTION_RULES = {
+    "dcim.site": [
+        {
+            "status": {
+                "eq": "decommissioning"
+            }
+        },
+        "my_plugin.validators.Validator1",
+    ]
+}
+```

docs/configuration/date-time.md

@@ -1,20 +0,0 @@
-# Date & Time Parameters
-
-## TIME_ZONE
-
-Default: UTC
-
-The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-
-## Date and Time Formatting
-
-You may define custom formatting for date and times. For detailed instructions on writing format strings, please see [the Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#date). Default formats are listed below.
-
-```python
-DATE_FORMAT = 'N j, Y'               # June 26, 2016
-SHORT_DATE_FORMAT = 'Y-m-d'          # 2016-06-26
-TIME_FORMAT = 'g:i a'                # 1:23 p.m.
-SHORT_TIME_FORMAT = 'H:i:s'          # 13:23:00
-DATETIME_FORMAT = 'N j, Y g:i a'     # June 26, 2016 1:23 p.m.
-SHORT_DATETIME_FORMAT = 'Y-m-d H:i'  # 2016-06-26 13:23
-```

docs/configuration/error-reporting.md

@@ -18,6 +18,9 @@ Default: False
 
 Set to True to enable automatic error reporting via [Sentry](https://sentry.io/).
 
+!!! note
+    The `sentry-sdk` Python package is required to enable Sentry integration.
+
 ---
 
 ## SENTRY_SAMPLE_RATE

docs/configuration/index.md

@@ -46,4 +46,4 @@ The configuration file may be modified at any time. However, the WSGI service (e
 $ sudo systemctl restart netbox
 ```
 
-Configuration parameters which are set via the admin UI (those listed under "dynamic settings") take effect immediately.
+Dynamic configuration parameters (those which can be modified via the UI) take effect immediately.

docs/configuration/miscellaneous.md

@@ -33,9 +33,6 @@ This defines custom content to be displayed on the login page above the login fo
 
 !!! tip "Dynamic Configuration Parameter"
 
-!!! note
-    This parameter was added in NetBox v3.5.
-
 This adds a banner to the top of every page when maintenance mode is enabled. HTML is allowed.
 
 ---
@@ -80,6 +77,17 @@ changes in the database indefinitely.
 
 ---
 
+## CHANGELOG_SKIP_EMPTY_CHANGES
+
+Default: True
+
+If enabled, a change log record will not be created when an object is updated without any changes to its existing field values.
+
+!!! note
+    The object's `last_updated` field will always reflect the time of the most recent update, regardless of this parameter.
+
+---
+
 ## DATA_UPLOAD_MAX_MEMORY_SIZE
 
 Default: `2621440` (2.5 MB)
@@ -88,13 +96,21 @@ The maximum size (in bytes) of an incoming HTTP request (i.e. `GET` or `POST` da
 
 ---
 
+## DJANGO_ADMIN_ENABLED
+
+Default: False
+
+Setting this to True installs the `django.contrib.admin` app and enables the [Django admin UI](https://docs.djangoproject.com/en/5.0/ref/contrib/admin/). This may be necessary to support older plugins which do not integrate with the native NetBox interface.
+
+---
+
 ## ENFORCE_GLOBAL_UNIQUE
 
 !!! tip "Dynamic Configuration Parameter"
 
-Default: False
+Default: True
 
-By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True.
+By default, NetBox will prevent the creation of duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This validation can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to False.
 
 ---
 
@@ -120,9 +136,6 @@ Setting this to False will disable the GraphQL API.
 
 !!! tip "Dynamic Configuration Parameter"
 
-!!! note
-    This parameter was renamed from `JOBRESULT_RETENTION` in NetBox v3.5.
-
 Default: 90
 
 The number of days to retain job results (scripts and reports). Set this to `0` to retain job results in the database indefinitely.
@@ -217,9 +230,6 @@ The maximum execution time of a background task (such as running a custom script
 
 ## RQ_RETRY_INTERVAL
 
-!!! note
-    This parameter was added in NetBox v3.5.
-
 Default: `60`
 
 This parameter controls how frequently a failed job is retried, up to the maximum number of times specified by `RQ_RETRY_MAX`. This must be either an integer specifying the number of seconds to wait between successive attempts, or a list of such values. For example, `[60, 300, 3600]` will retry the task after 1 minute, 5 minutes, and 1 hour.
@@ -228,9 +238,6 @@ This parameter controls how frequently a failed job is retried, up to the maximu
 
 ## RQ_RETRY_MAX
 
-!!! note
-    This parameter was added in NetBox v3.5.
-
 Default: `0` (retries disabled)
 
 The maximum number of times a background task will be retried before being marked as failed.

docs/configuration/remote-authentication.md

@@ -67,7 +67,7 @@ When remote user authentication is in use, this is the name of the HTTP header w
 
 Default: `|` (Pipe)
 
-The Seperator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+The Separator upon which `REMOTE_AUTH_GROUP_HEADER` gets split into individual Groups. This needs to be coordinated with your authentication Proxy. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
 
 ---
 
@@ -85,6 +85,9 @@ Default: `'HTTP_REMOTE_USER'`
 
 When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User` it needs to be set to `HTTP_X_REMOTE_USER`. (Requires `REMOTE_AUTH_ENABLED`.)
 
+!!! warning Verify Header Compatibility
+    Some WSGI servers may drop headers which contain unsupported characters. For instance, gunicorn v22.0 and later silently drops HTTP headers containing underscores. This behavior can be disabled by changing gunicorn's [`header_map`](https://docs.gunicorn.org/en/stable/settings.html#header-map) setting to `dangerous`.
+
 ---
 
 ## REMOTE_AUTH_USER_EMAIL

docs/configuration/required-parameters.md

@@ -59,10 +59,7 @@ DATABASE = {
 
 ## REDIS
 
-[Redis](https://redis.io/) is an in-memory data store similar to memcached. While Redis has been an optional component of
+[Redis](https://redis.io/) is a lightweight in-memory data store similar to memcached. NetBox employs Redis for background task queuing and other features.
-NetBox since the introduction of webhooks in version 2.4, it is required starting in 2.6 to support NetBox's caching
-functionality (as well as other planned features). In 2.7, the connection settings were broken down into two sections for
-task queuing and caching, allowing the user to connect to different Redis instances/databases per feature.
 
 Redis is configured using a configuration setting similar to `DATABASE` and these settings are the same for both of the `tasks` and `caching` subsections:
 
@@ -81,7 +78,7 @@ REDIS = {
     'tasks': {
         'HOST': 'redis.example.com',
         'PORT': 1234,
-        'USERNAME': 'netbox'
+        'USERNAME': 'netbox',
         'PASSWORD': 'foobar',
         'DATABASE': 0,
         'SSL': False,
@@ -89,7 +86,7 @@ REDIS = {
     'caching': {
         'HOST': 'localhost',
         'PORT': 6379,
-        'USERNAME': ''
+        'USERNAME': '',
         'PASSWORD': '',
         'DATABASE': 1,
         'SSL': False,

docs/configuration/security.md

@@ -92,8 +92,6 @@ CSRF_TRUSTED_ORIGINS = (
 
 ## DEFAULT_PERMISSIONS
 
-!!! info "This parameter was introduced in NetBox v3.6."
-
 Default:
 
 ```python
@@ -183,6 +181,30 @@ The view name or URL to which a user is redirected after logging out.
 
 ---
 
+## SECURE_HSTS_INCLUDE_SUBDOMAINS
+
+Default: False
+
+If true, the `includeSubDomains` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to apply the HSTS policy to all subdomains of the current domain.
+
+---
+
+## SECURE_HSTS_PRELOAD
+
+Default: False
+
+If true, the `preload` directive will be included in the HTTP Strict Transport Security (HSTS) header. This directive instructs the browser to preload the site in HTTPS. Browsers that use the HSTS preload list will force the site to be accessed via HTTPS even if the user types HTTP in the address bar.
+
+---
+
+## SECURE_HSTS_SECONDS
+
+Default: 0
+
+If set to a non-zero integer value, the SecurityMiddleware sets the HTTP Strict Transport Security (HSTS) header on all responses that do not already have it. This will instruct the browser that the website must be accessed via HTTPS, blocking any HTTP request.
+
+---
+
 ## SECURE_SSL_REDIRECT
 
 Default: False

docs/configuration/system.md

@@ -16,10 +16,7 @@ BASE_PATH = 'netbox/'
 
 Default: `en-us` (US English)
 
-Defines the default preferred language/locale for requests that do not specify one. This is used to alter e.g. the display of dates and numbers to fit the user's locale. See [this list](http://www.i18nguy.com/unicode/language-identifiers.html) of standard language codes. (This parameter maps to Django's [`LANGUAGE_CODE`](https://docs.djangoproject.com/en/stable/ref/settings/#language-code) internal setting.)
+Defines the default preferred language/locale for requests that do not specify one. (This parameter maps to Django's [`LANGUAGE_CODE`](https://docs.djangoproject.com/en/stable/ref/settings/#language-code) internal setting.)
-
-!!! note
-    Altering this parameter will *not* change the language used in NetBox. We hope to provide translation support in a future NetBox release.
 
 ---
 
@@ -65,22 +62,6 @@ Email is sent from NetBox only for critical events or if configured for [logging
 
 ---
 
-## ENABLE_LOCALIZATION
-
-Default: False
-
-Determines if localization features are enabled or not. This should only be enabled for development or testing purposes as netbox is not yet fully localized. Turning this on will localize numeric and date formats (overriding what is set for DATE_FORMAT) based on the browser locale as well as translate certain strings from third party modules.
-
----
-
-## GIT_PATH
-
-Default: `git`
-
-The system path to the `git` executable, used by the synchronization backend for remote git repositories.
-
----
-
 ## HTTP_PROXIES
 
 Default: None
@@ -211,3 +192,9 @@ A dictionary of configuration parameters for the storage backend configured as `
 If `STORAGE_BACKEND` is not defined, this setting will be ignored.
 
 ---
+
+## TIME_ZONE
+
+Default: UTC
+
+The time zone NetBox will use when dealing with dates and times. It is recommended to use UTC time unless you have a specific need to use a local time zone. Please see the [list of available time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

docs/customization/custom-fields.md

@@ -40,14 +40,20 @@ Related custom fields can be grouped together within the UI by assigning each th
 
 This parameter has no effect on the API representation of custom field data.
 
-### Visibility
+### Visibility & Editing
 
-When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI.
+When creating a custom field, users can control the conditions under which it may be displayed and edited within the NetBox user interface. The following choices are available for controlling the display of a custom field on an object:
 
-* **Read/write** (default): The custom field is included when viewing and editing objects.
+* **Always** (default): The custom field is included when viewing an object.
-* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.)
+* **If Set**: The custom field is included only if a value has been defined for the object.
 * **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users.
 
+Additionally, the following options are available for controlling whether custom field values can be altered within the NetBox UI:
+
+* **Yes** (default): The custom field's value may be modified when editing an object.
+* **No**: The custom field is displayed for reference when editing an object, but its value may not be modified.
+* **Hidden**: The custom field is not displayed when editing an object.
+
 Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API.
 
 ### Validation

docs/customization/custom-scripts.md

@@ -5,8 +5,17 @@ Custom scripting was introduced to provide a way for users to execute custom log
 * Automatically populate new devices and cables in preparation for a new site deployment
 * Create a range of new reserved prefixes or IP addresses
 * Fetch data from an external source and import it to NetBox
+* Update objects with invalid or incomplete data
 
-Custom scripts are Python code and exist outside of the official NetBox code base, so they can be updated and changed without interfering with the core NetBox installation. And because they're completely custom, there is no inherent limitation on what a script can accomplish.
+They can also be used as a mechanism for validating the integrity of data within NetBox. Script authors can define test to check object against specific rules and conditions. For example, you can write script to check that:
+
+* All top-of-rack switches have a console connection
+* Every router has a loopback interface with an IP address assigned
+* Each interface description conforms to a standard format
+* Every site has a minimum set of VLANs defined
+* All IP addresses have a parent prefix
+
+Custom scripts are Python code which exists outside the NetBox code base, so they can be updated and changed without interfering with the core NetBox installation. And because they're completely custom, there is no inherent limitation on what a script can accomplish.
 
 ## Writing Custom Scripts
 
@@ -135,13 +144,73 @@ These two methods will load data in YAML or JSON format, respectively, from file
 
 The Script object provides a set of convenient functions for recording messages at different severity levels:
 
-* `log_debug`
+* `log_debug(message, object=None)`
-* `log_success`
+* `log_success(message, object=None)`
-* `log_info`
+* `log_info(message, object=None)`
-* `log_warning`
+* `log_warning(message, object=None)`
-* `log_failure`
+* `log_failure(message, object=None)`
 
-Log messages are returned to the user upon execution of the script. Markdown rendering is supported for log messages.
+Log messages are returned to the user upon execution of the script. Markdown rendering is supported for log messages. A message may optionally be associated with a particular object by passing it as the second argument to the logging method.
+
+## Test Methods
+
+A script can define one or more test methods to report on certain conditions. All test methods must have a name beginning with `test_` and accept no arguments beyond `self`.
+
+These methods are detected and run automatically when the script is executed, unless its `run()` method has been overridden. (When overriding `run()`, `run_tests()` can be called to run all test methods present in the script.)
+
+!!! info
+    This functionality was ported from [legacy reports](./reports.md) in NetBox v4.0.
+
+### Example
+
+```
+from dcim.choices import DeviceStatusChoices
+from dcim.models import ConsolePort, Device, PowerPort
+from extras.scripts import Script
+
+
+class DeviceConnectionsReport(Script):
+    description = "Validate the minimum physical connections for each device"
+
+    def test_console_connection(self):
+
+        # Check that every console port for every active device has a connection defined.
+        active = DeviceStatusChoices.STATUS_ACTIVE
+        for console_port in ConsolePort.objects.prefetch_related('device').filter(device__status=active):
+            if not console_port.connected_endpoints:
+                self.log_failure(
+                    f"No console connection defined for {console_port.name}",
+                    console_port.device,
+                )
+            elif not console_port.connection_status:
+                self.log_warning(
+                    f"Console connection for {console_port.name} marked as planned",
+                    console_port.device,
+                )
+            else:
+                self.log_success("Passed", console_port.device)
+
+    def test_power_connections(self):
+
+        # Check that every active device has at least two connected power supplies.
+        for device in Device.objects.filter(status=DeviceStatusChoices.STATUS_ACTIVE):
+            connected_ports = 0
+            for power_port in PowerPort.objects.filter(device=device):
+                if power_port.connected_endpoints:
+                    connected_ports += 1
+                    if not power_port.path.is_active:
+                        self.log_warning(
+                            f"Power connection for {power_port.name} marked as planned",
+                            device,
+                        )
+            if connected_ports < 2:
+                self.log_failure(
+                    f"{connected_ports} connected power supplies found (2 needed)",
+                    device,
+                )
+            else:
+                self.log_success("Passed", device)
+```
 
 ## Change Logging
 
@@ -235,6 +304,7 @@ A particular object within NetBox. Each ObjectVar must specify a particular mode
 
 * `model` - The model class
 * `query_params` - A dictionary of query parameters to use when retrieving available options (optional)
+* `context` - A custom dictionary mapping template context variables to fields, used when rendering `<option>` elements within the dropdown menu (optional; see below)
 * `null_option` - A label representing a "null" or empty choice (optional)
 
 To limit the selections available within the list, additional query parameters can be passed as the `query_params` dictionary. For example, to show only devices with an "active" status:
@@ -262,6 +332,22 @@ site = ObjectVar(
 )
 ```
 
+#### Context Variables
+
+Custom context variables can be passed to override the default attribute names or to display additional information, such as a parent object.
+
+| Name          | Default         | Description                                                                  |
+|---------------|-----------------|------------------------------------------------------------------------------|
+| `value`       | `"id"`          | The attribute which contains the option's value                              |
+| `label`       | `"display"`     | The attribute used as the option's human-friendly label                      |
+| `description` | `"description"` | The attribute to use as a description                                        |
+| `depth`[^1]   | `"_depth"`      | The attribute which indicates an object's depth within a recursive hierarchy |
+| `disabled`    | --              | The attribute which, if true, signifies that the option should be disabled   |
+| `parent`      | --              | The attribute which represents the object's parent object                    |
+| `count`[^1]   | --              | The attribute which contains a numeric count of related objects              |
+
+[^1]: The value of this attribute must be a positive integer
+
 ### MultiObjectVar
 
 Similar to `ObjectVar`, but allows for the selection of multiple objects.
@@ -285,12 +371,20 @@ An IPv4 or IPv6 network with a mask. Returns a `netaddr.IPNetwork` object. Two a
 * `min_prefix_length` - Minimum length of the mask
 * `max_prefix_length` - Maximum length of the mask
 
+### DateVar
+
+A calendar date. Returns a `datetime.date` object.
+
+### DateTimeVar
+
+A complete date & time. Returns a `datetime.datetime` object.
+
 ## Running Custom Scripts
 
 !!! note
-    To run a custom script, a user must be assigned via permissions for `Extras > Script`, `Extras > ScriptModule`, and `Core > ManagedFile` objects. They must also be assigned the `extras.run_script` permission. This is achieved by assigning the user (or group) a permission on the Script object and specifying the `run` action in the admin UI as shown below.
+    To run a custom script, a user must be assigned permissions for `Extras > Script`, `Extras > Script Module`, and `Core > Managed File` objects. They must also be assigned the `extras.run_script` permission. This is achieved by assigning the user (or group) a permission on the Script object and specifying the `run` action in "Permissions" as shown below.
 
-    ![Adding the run action to a permission](../media/admin_ui_run_permission.png)
+    ![Adding the run action to a permission](../media/run_permission.png)
 
 ### Via the Web UI
 

docs/customization/custom-validation.md

@@ -4,7 +4,7 @@ NetBox validates every object prior to it being written to the database to ensur
 
 ## Custom Validation Rules
 
-Custom validation rules are expressed as a mapping of model attributes to a set of rules to which that attribute must conform. For example:
+Custom validation rules are expressed as a mapping of object attributes to a set of rules to which that attribute must conform. For example:
 
 ```json
 {
@@ -17,6 +17,8 @@ Custom validation rules are expressed as a mapping of model attributes to a set
 
 This defines a custom validator which checks that the length of the `name` attribute for an object is at least five characters long, and no longer than 30 characters. This validation is executed _after_ NetBox has performed its own internal validation.
 
+### Validation Types
+
 The `CustomValidator` class supports several validation types:
 
 * `min`: Minimum value
@@ -26,6 +28,8 @@ The `CustomValidator` class supports several validation types:
 * `regex`: Application of a [regular expression](https://en.wikipedia.org/wiki/Regular_expression)
 * `required`: A value must be specified
 * `prohibited`: A value must _not_ be specified
+* `eq`: A value must be equal to the specified value
+* `neq`: A value must _not_ be equal to the specified value
 
 The `min` and `max` types should be defined for numeric values, whereas `min_length`, `max_length`, and `regex` are suitable for character strings (text values). The `required` and `prohibited` validators may be used for any field, and should be passed a value of `True`.
 
@@ -34,14 +38,14 @@ The `min` and `max` types should be defined for numeric values, whereas `min_len
 
 ### Custom Validation Logic
 
-There may be instances where the provided validation types are insufficient. NetBox provides a `CustomValidator` class which can be extended to enforce arbitrary validation logic by overriding its `validate()` method, and calling `fail()` when an unsatisfactory condition is detected.
+There may be instances where the provided validation types are insufficient. NetBox provides a `CustomValidator` class which can be extended to enforce arbitrary validation logic by overriding its `validate()` method, and calling `fail()` when an unsatisfactory condition is detected. The `validate()` method should accept an instance (the object being saved) as well as the current request effecting the change.
 
 ```python
 from extras.validators import CustomValidator
 
 class MyValidator(CustomValidator):
 
-    def validate(self, instance):
+    def validate(self, instance, request):
         if instance.status == 'active' and not instance.description:
             self.fail("Active sites must have a description set!", field='status')
 ```
@@ -80,7 +84,42 @@ CUSTOM_VALIDATORS = {
 }
 ```
 
-### Dotted Path
+#### Referencing Related Object Attributes
+
+!!! info "This feature was introduced in NetBox v4.0."
+
+The attributes of a related object can be referenced by specifying a dotted path. For example, to reference the name of a region to which a site is assigned, use `region.name`:
+
+```python
+CUSTOM_VALIDATORS = {
+    "dcim.site": [
+        {
+            "region.name": {
+                "neq": "New York"
+            }
+        }
+    ]
+}
+```
+
+#### Validating Request Parameters
+
+!!! info "This feature was introduced in NetBox v4.0."
+
+In addition to validating object attributes, custom validators can also match against parameters of the current request (where available). For example, the following rule will permit only the user named "admin" to modify an object:
+
+```json
+{
+  "request.user.username": {
+    "eq": "admin"
+  }
+}
+```
+
+!!! tip
+    Custom validation should generally not be used to enforce permissions. NetBox provides a robust [object-based permissions](../administration/permissions.md) mechanism which should be used for this purpose.
+
+### Dotted Path to Class
 
 In instances where a custom validator class is needed, it can be referenced by its Python path (relative to NetBox's working directory):
 

docs/customization/reports.md

@@ -1,167 +1,63 @@
 # NetBox Reports
 
-A NetBox report is a mechanism for validating the integrity of data within NetBox. Running a report allows the user to verify that the objects defined within NetBox meet certain arbitrary conditions. For example, you can write reports to check that:
-
-* All top-of-rack switches have a console connection
-* Every router has a loopback interface with an IP address assigned
-* Each interface description conforms to a standard format
-* Every site has a minimum set of VLANs defined
-* All IP addresses have a parent prefix
-
-...and so on. Reports are completely customizable, so there's practically no limit to what you can test for.
-
-## Writing Reports
-
-Reports must be saved as files in the [`REPORTS_ROOT`](../configuration/system.md#reports_root) path (which defaults to `netbox/reports/`). Each file created within this path is considered a separate module. Each module holds one or more reports (Python classes), each of which performs a certain function. The logic of each report is broken into discrete test methods, each of which applies a small portion of the logic comprising the overall test.
-
 !!! warning
-    The reports path includes a file named `__init__.py`, which registers the path as a Python module. Do not delete this file.
+    Reports are deprecated beginning with NetBox v4.0, and their functionality has been merged with [custom scripts](./custom-scripts.md). While backward compatibility has been maintained, users are advised to convert legacy reports into custom scripts soon, as support for legacy reports will be removed in a future release.
 
-For example, we can create a module named `devices.py` to hold all of our reports which pertain to devices in NetBox. Within that module, we might define several reports. Each report is defined as a Python class inheriting from `extras.reports.Report`.
+## 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 DeviceConnectionsReport(Report):
+class MyReport(Report):
-    description = "Validate the minimum physical connections for each device"
-
-class DeviceIPsReport(Report):
-    description = "Check that every device has a primary IP address assigned"
 ```
 
-Within each report class, we'll create a number of test methods to execute our report's logic. In DeviceConnectionsReport, for instance, we want to ensure that every live device has a console connection, an out-of-band management connection, and two power connections.
+```python title="New code"
+from extras.scripts import Script
 
-```
+class MyReport(Script):
-from dcim.choices import DeviceStatusChoices
-from dcim.models import ConsolePort, Device, PowerPort
-from extras.reports import Report
-
-
-class DeviceConnectionsReport(Report):
-    description = "Validate the minimum physical connections for each device"
-
-    def test_console_connection(self):
-
-        # Check that every console port for every active device has a connection defined.
-        active = DeviceStatusChoices.STATUS_ACTIVE
-        for console_port in ConsolePort.objects.prefetch_related('device').filter(device__status=active):
-            if not console_port.connected_endpoints:
-                self.log_failure(
-                    console_port.device,
-                    "No console connection defined for {}".format(console_port.name)
-                )
-            elif not console_port.connection_status:
-                self.log_warning(
-                    console_port.device,
-                    "Console connection for {} marked as planned".format(console_port.name)
-                )
-            else:
-                self.log_success(console_port.device)
-
-    def test_power_connections(self):
-
-        # Check that every active device has at least two connected power supplies.
-        for device in Device.objects.filter(status=DeviceStatusChoices.STATUS_ACTIVE):
-            connected_ports = 0
-            for power_port in PowerPort.objects.filter(device=device):
-                if power_port.connected_endpoints:
-                    connected_ports += 1
-                    if not power_port.path.is_active:
-                        self.log_warning(
-                            device,
-                            "Power connection for {} marked as planned".format(power_port.name)
-                        )
-            if connected_ports < 2:
-                self.log_failure(
-                    device,
-                    "{} connected power supplies found (2 needed)".format(connected_ports)
-                )
-            else:
-                self.log_success(device)
 ```
 
-As you can see, reports are completely customizable. Validation logic can be as simple or as complex as needed. Also note that the `description` attribute support markdown syntax. It will be rendered in the report list page.
+### Step 2: Update Logging Calls
 
-!!! warning
+Reports and scripts both provide logging methods, however their signatures differ. All script logging methods accept a message as the first parameter, and accept an object as an optional second parameter.
-    Reports should never alter data: If you find yourself using the `create()`, `save()`, `update()`, or `delete()` methods on objects within reports, stop and re-evaluate what you're trying to accomplish. Note that there are no safeguards against the accidental alteration or destruction of data.
 
-## Report Attributes
+Additionally, the Report class' generic `log()` method is **not** available on Script. Users are advised to replace calls of this method with `log_info()`.
 
-### `description`
+Use the table below as a reference when updating these methods.
 
-A human-friendly description of what your report does.
+| 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)` |
 
-### `scheduling_enabled`
+[^1]: `log_debug()` was added to the Report class in v4.0 to avoid confusion with the same method on Script
 
-By default, a report can be scheduled for execution at a later time. Setting `scheduling_enabled` to False disables this ability: Only immediate execution will be possible. (This also disables the ability to set a recurring execution interval.)
+```python title="Old code"
-
+self.log_failure(
-### `job_timeout`
+    console_port.device,
-
+    f"No console connection defined for {console_port.name}"
-Set the maximum allowed runtime for the report. If not set, `RQ_DEFAULT_TIMEOUT` will be used.
+)
-
-## Logging
-
-The following methods are available to log results within a report:
-
-* log(message)
-* log_success(object, message=None)
-* log_info(object, message)
-* log_warning(object, message)
-* log_failure(object, message)
-
-The recording of one or more failure messages will automatically flag a report as failed. It is advised to log a success for each object that is evaluated so that the results will reflect how many objects are being reported on. (The inclusion of a log message is optional for successes.) Messages recorded with `log()` will appear in a report's results but are not associated with a particular object or status. Log messages also support using markdown syntax and will be rendered on the report result page.
-
-To perform additional tasks, such as sending an email or calling a webhook, before or after a report is run, extend the `pre_run()` and/or `post_run()` methods, respectively.
-
-By default, reports within a module are ordered alphabetically in the reports list page. To return reports in a specific order, you can define the `report_order` variable at the end of your module. The `report_order` variable is a tuple which contains each Report class in the desired order. Any reports that are omitted from this list will be listed last.
-
-```
-from extras.reports import Report
-
-class DeviceConnectionsReport(Report)
-    pass
-
-class DeviceIPsReport(Report)
-    pass
-
-report_order = (DeviceIPsReport, DeviceConnectionsReport)
 ```
 
-Once you have created a report, it will appear in the reports list. Initially, reports will have no results associated with them. To generate results, run the report.
+```python title="New code"
-
+self.log_failure(
-## Running Reports
+    f"No console connection defined for {console_port.name}",
-
+    obj=console_port.device,
-!!! note
+)
-    To run a report, a user must be assigned via permissions for `Extras > Report`, `Extras > ReportModule`, and `Core > ManagedFile` objects. They must also be assigned the `extras.run_report` permission. This is achieved by assigning the user (or group) a permission on the Report object and specifying the `run` action in the admin UI as shown below.
-
-    ![Adding the run action to a permission](../media/admin_ui_run_permission.png)
-
-### Via the Web UI
-
-Reports can be run via the web UI by navigating to the report and clicking the "run report" button at top right. Once a report has been run, its associated results will be included in the report view. It is possible to schedule a report to be executed at specified time in the future. A scheduled report can be canceled by deleting the associated job result object.
-
-### Via the API
-
-To run a report via the API, simply issue a POST request to its `run` endpoint. Reports are identified by their module and class name.
-
-```
-    POST /api/extras/reports/<module>.<name>/run/
 ```
 
-Our example report above would be called as:
+### Other Notes
 
-```
+Existing reports will be converted to scripts automatically upon upgrading to NetBox v4.0, and previous job history will be retained. However, users are advised to convert legacy reports into custom scripts at the earliest opportunity, as support for legacy reports will be removed in a future release.
-    POST /api/extras/reports/devices.DeviceConnectionsReport/run/
-```
 
-Optionally `schedule_at` can be passed in the form data with a datetime string to schedule a script at the specified date and time.
+The `pre_run()` and `post_run()` Report methods have been carried over to Script. These are called automatically by Script's `run()` method. (Note that if you opt to override this method, you are responsible for calling `pre_run()` and `post_run()` where applicable.)
 
-### Via the CLI
+The `is_valid()` method on Report is no longer needed and has been removed.
-
-Reports can be run on the CLI by invoking the management command:
-
-```
-python3 manage.py runreport <module>
-```
-
-where ``<module>`` is the name of the python file in the ``reports`` directory without the ``.py`` extension.  One or more report modules may be specified.

docs/development/application-registry.md

@@ -31,7 +31,7 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
         'dcim': ['site', 'rack', 'devicetype', ...],
         ...
     },
-    'webhooks': {
+    'event_rules': {
         'extras': ['configcontext', 'tag', ...],
         'dcim': ['site', 'rack', 'devicetype', ...],
     },
@@ -41,6 +41,10 @@ A dictionary of particular features (e.g. custom fields) mapped to the NetBox mo
 
 Supported model features are listed in the [features matrix](./models.md#features-matrix).
 
+### `models`
+
+This key lists all models which have been registered in NetBox which are not designated for private use. (Setting `_netbox_private` to True on a model excludes it from this list.) As with individual features under `model_features`, models are organized by app label.
+
 ### `plugins`
 
 This store maintains all registered items for plugins, such as navigation menus, template extensions, etc.
@@ -49,6 +53,10 @@ This store maintains all registered items for plugins, such as navigation menus,
 
 A dictionary mapping each model (identified by its app and label) to its search index class, if one has been registered for it.
 
+### `tables`
+
+A dictionary mapping table classes to lists of extra columns that have been registered by plugins using the `register_table_column()` utility function. Each column is defined as a tuple of name and column instance.
+
 ### `views`
 
 A hierarchical mapping of registered views for each model. Mappings are added using the `register_model_view()` decorator, and URLs paths can be generated from these using `get_model_urls()`.

docs/development/extending-models.md

@@ -2,12 +2,25 @@
 
 Below is a list of tasks to consider when adding a new field to a core model.
 
-## 1. Generate and run database migrations
+## 1. Add the field to the model class
+
+Add the field to the model, taking care to address any of the following conditions.
+
+* When adding a GenericForeignKey field, also add an index under `Meta` for its two concrete fields. For example:
+
+    ```python
+    class Meta:
+        indexes = (
+            models.Index(fields=('object_type', 'object_id')),
+        )
+    ```
+
+## 2. Generate and run database migrations
 
 [Django migrations](https://docs.djangoproject.com/en/stable/topics/migrations/) are used to express changes to the database schema. In most cases, Django can generate these automatically, however very complex changes may require manual intervention. Always remember to specify a short but descriptive name when generating a new migration.
 
 ```
-./manage.py makemigrations <app> -n <name>
+./manage.py makemigrations <app> -n <name> --no-header
 ./manage.py migrate
 ```
 
@@ -16,7 +29,7 @@ Where possible, try to merge related changes into a single migration. For exampl
 !!! warning "Do not alter existing migrations"
     Migrations can only be merged within a release. Once a new release has been published, its migrations cannot be altered (other than for the purpose of correcting a bug).
 
-## 2. Add validation logic to `clean()`
+## 3. Add validation logic to `clean()`
 
 If the new field introduces additional validation requirements (beyond what's included with the field itself), implement them in the model's `clean()` method. Remember to call the model's original method using `super()` before or after your custom validation as appropriate:
 
@@ -31,15 +44,15 @@ class Foo(models.Model):
             raise ValidationError()
 ```
 
-## 3. Update relevant querysets
+## 4. Update relevant querysets
 
 If you're adding a relational field (e.g. `ForeignKey`) and intend to include the data when retrieving a list of objects, be sure to include the field using `prefetch_related()` as appropriate. This will optimize the view and avoid extraneous database queries.
 
-## 4. Update API serializer
+## 5. Update API serializer
 
 Extend the model's API serializer in `<app>.api.serializers` to include the new field. In most cases, it will not be necessary to also extend the nested serializer, which produces a minimal representation of the model.
 
-## 5. Add fields to forms
+## 6. Add fields to forms
 
 Extend any forms to include the new field(s) as appropriate. These are found under the `forms/` directory within each app. Common forms include:
 
@@ -48,23 +61,23 @@ Extend any forms to include the new field(s) as appropriate. These are found und
 * **CSV import** - The form used when bulk importing objects in CSV format
 * **Filter** - Displays the options available for filtering a list of objects (both UI and API)
 
-## 6. Extend object filter set
+## 7. Extend object filter set
 
 If the new field should be filterable, add it to the `FilterSet` for the model. If the field should be searchable, remember to query it in the FilterSet's `search()` method.
 
-## 7. Add column to object table
+## 8. Add column to object table
 
 If the new field will be included in the object list view, add a column to the model's table. For simple fields, adding the field name to `Meta.fields` will be sufficient. More complex fields may require declaring a custom column. Also add the field name to `default_columns` if the column should be present in the table by default.
 
-## 8. Update the SearchIndex
+## 9. Update the SearchIndex
 
 Where applicable, add the new field to the model's SearchIndex for inclusion in global search.
 
-## 9. Update the UI templates
+## 10. Update the UI templates
 
 Edit the object's view template to display the new field. There may also be a custom add/edit form template that needs to be updated.
 
-## 10. Create/extend test cases
+## 11. Create/extend test cases
 
 Create or extend the relevant test cases to verify that the new field and any accompanying validation logic perform as expected. This is especially important for relational fields. NetBox incorporates various test suites, including:
 
@@ -74,8 +87,8 @@ Create or extend the relevant test cases to verify that the new field and any ac
 * Model tests
 * View tests
 
-Be diligent to ensure all of the relevant test suites are adapted or extended as necessary to test any new functionality.
+Be diligent to ensure all the relevant test suites are adapted or extended as necessary to test any new functionality.
 
-## 11. Update the model's documentation
+## 12. Update the model's documentation
 
 Each model has a dedicated page in the documentation, at `models/<app>/<model>.md`. Update this file to include any relevant information about the new field.

docs/development/getting-started.md

@@ -7,7 +7,7 @@ Getting started with NetBox development is pretty straightforward, and should fe
 * A Linux system or compatible environment
 * A PostgreSQL server, which can be installed locally [per the documentation](../installation/1-postgresql.md)
 * A Redis server, which can also be [installed locally](../installation/2-redis.md)
-* Python 3.8 or later
+* Python 3.10 or later
 
 ### 1. Fork the Repo
 

docs/development/internationalization.md

@@ -62,10 +62,11 @@ class Circuit(PrimaryModel):
 
 1. Import `gettext_lazy` as `_`.
 2. All form fields must specify a `label` wrapped with `gettext_lazy()`.
-3. All headers under a form's `fieldsets` property must be wrapped with `gettext_lazy()`.
+3. The name of each FieldSet on a form must be wrapped with `gettext_lazy()`.
 
 ```python
 from django.utils.translation import gettext_lazy as _
+from utilities.forms.rendering import FieldSet
 
 class CircuitBulkEditForm(NetBoxModelBulkEditForm):
     description = forms.CharField(
@@ -74,7 +75,7 @@ class CircuitBulkEditForm(NetBoxModelBulkEditForm):
     )
 
     fieldsets = (
-        (_('Circuit'), ('provider', 'type', 'status', 'description')),
+        FieldSet('provider', 'type', 'status', 'description', name=_('Circuit')),
     )
 ```
 

docs/development/models.md

@@ -10,19 +10,19 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 Depending on its classification, each NetBox model may support various features which enhance its operation. Each feature is enabled by inheriting from its designated mixin class, and some features also make use of the [application registry](./application-registry.md#model_features).
 
-| Feature                                                    | Feature Mixin           | Registry Key       | Description                                                                    |
+| Feature                                                    | Feature Mixin           | Registry Key       | Description                                                                             |
-|------------------------------------------------------------|-------------------------|--------------------|--------------------------------------------------------------------------------|
+|------------------------------------------------------------|-------------------------|--------------------|-----------------------------------------------------------------------------------------|
-| [Change logging](../features/change-logging.md)            | `ChangeLoggingMixin`    | -                  | Changes to these objects are automatically recorded in the change log          |
+| [Change logging](../features/change-logging.md)            | `ChangeLoggingMixin`    | -                  | Changes to these objects are automatically recorded in the change log                   |
-| Cloning                                                    | `CloningMixin`          | -                  | Provides the `clone()` method to prepare a copy                                |
+| Cloning                                                    | `CloningMixin`          | -                  | Provides the `clone()` method to prepare a copy                                         |
-| [Custom fields](../customization/custom-fields.md)         | `CustomFieldsMixin`     | `custom_fields`    | These models support the addition of user-defined fields                       |
+| [Custom fields](../customization/custom-fields.md)         | `CustomFieldsMixin`     | `custom_fields`    | These models support the addition of user-defined fields                                |
-| [Custom links](../customization/custom-links.md)           | `CustomLinksMixin`      | `custom_links`     | These models support the assignment of custom links                            |
+| [Custom links](../customization/custom-links.md)           | `CustomLinksMixin`      | `custom_links`     | These models support the assignment of custom links                                     |
-| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin` | -                  | Supports the enforcement of custom validation rules                            |
+| [Custom validation](../customization/custom-validation.md) | `CustomValidationMixin` | -                  | Supports the enforcement of custom validation rules                                     |
-| [Export templates](../customization/export-templates.md)   | `ExportTemplatesMixin`  | `export_templates` | Users can create custom export templates for these models                      |
+| [Export templates](../customization/export-templates.md)   | `ExportTemplatesMixin`  | `export_templates` | Users can create custom export templates for these models                               |
-| [Job results](../features/background-jobs.md)              | `JobsMixin`             | `jobs`             | Users can create custom export templates for these models                      |
+| [Job results](../features/background-jobs.md)              | `JobsMixin`             | `jobs`             | Users can create custom export templates for these models                               |
-| [Journaling](../features/journaling.md)                    | `JournalingMixin`       | `journaling`       | These models support persistent historical commentary                          |
+| [Journaling](../features/journaling.md)                    | `JournalingMixin`       | `journaling`       | These models support persistent historical commentary                                   |
-| [Synchronized data](../integrations/synchronized-data.md)  | `SyncedDataMixin`       | `synced_data`      | Certain model data can be automatically synchronized from a remote data source |
+| [Synchronized data](../integrations/synchronized-data.md)  | `SyncedDataMixin`       | `synced_data`      | Certain model data can be automatically synchronized from a remote data source          |
-| [Tagging](../models/extras/tag.md)                         | `TagsMixin`             | `tags`             | The models can be tagged with user-defined tags                                |
+| [Tagging](../models/extras/tag.md)                         | `TagsMixin`             | `tags`             | The models can be tagged with user-defined tags                                         |
-| [Webhooks](../integrations/webhooks.md)                    | `WebhooksMixin`         | `webhooks`         | NetBox is capable of generating outgoing webhooks for these objects            |
+| [Event rules](../features/event-rules.md)                  | `EventRulesMixin`       | `event_rules`      | Event rules can send webhooks or run custom scripts automatically in response to events |
 
 ## Models Index
 
@@ -52,7 +52,6 @@ These are considered the "core" application models which are used to model netwo
 * [ipam.FHRPGroup](../models/ipam/fhrpgroup.md)
 * [ipam.IPAddress](../models/ipam/ipaddress.md)
 * [ipam.IPRange](../models/ipam/iprange.md)
-* [ipam.L2VPN](../models/ipam/l2vpn.md)
 * [ipam.Prefix](../models/ipam/prefix.md)
 * [ipam.RouteTarget](../models/ipam/routetarget.md)
 * [ipam.Service](../models/ipam/service.md)
@@ -63,6 +62,13 @@ These are considered the "core" application models which are used to model netwo
 * [tenancy.Tenant](../models/tenancy/tenant.md)
 * [virtualization.Cluster](../models/virtualization/cluster.md)
 * [virtualization.VirtualMachine](../models/virtualization/virtualmachine.md)
+* [vpn.IKEPolicy](../models/vpn/ikepolicy.md)
+* [vpn.IKEProposal](../models/vpn/ikeproposal.md)
+* [vpn.IPSecPolicy](../models/vpn/ipsecpolicy.md)
+* [vpn.IPSecProfile](../models/vpn/ipsecprofile.md)
+* [vpn.IPSecProposal](../models/vpn/ipsecproposal.md)
+* [vpn.L2VPN](../models/vpn/l2vpn.md)
+* [vpn.Tunnel](../models/vpn/tunnel.md)
 * [wireless.WirelessLAN](../models/wireless/wirelesslan.md)
 * [wireless.WirelessLink](../models/wireless/wirelesslink.md)
 
@@ -75,6 +81,7 @@ Organization models are used to organize and classify primary models.
 * [dcim.Manufacturer](../models/dcim/manufacturer.md)
 * [dcim.Platform](../models/dcim/platform.md)
 * [dcim.RackRole](../models/dcim/rackrole.md)
+* [ipam.ASNRange](../models/ipam/asnrange.md)
 * [ipam.RIR](../models/ipam/rir.md)
 * [ipam.Role](../models/ipam/role.md)
 * [ipam.VLANGroup](../models/ipam/vlangroup.md)
@@ -107,11 +114,12 @@ Component models represent individual physical or virtual components belonging t
 * [dcim.PowerOutlet](../models/dcim/poweroutlet.md)
 * [dcim.PowerPort](../models/dcim/powerport.md)
 * [dcim.RearPort](../models/dcim/rearport.md)
+* [virtualization.VirtualDisk](../models/virtualization/virtualdisk.md)
 * [virtualization.VMInterface](../models/virtualization/vminterface.md)
 
 ### Component Template Models
 
-These function as templates to effect the replication of device and virtual machine components. Component template models support a limited feature set, including change logging, custom validation, and webhooks.
+These function as templates to effect the replication of device and virtual machine components. Component template models support a limited feature set, including change logging, custom validation, and event rules.
 
 * [dcim.ConsolePortTemplate](../models/dcim/consoleporttemplate.md)
 * [dcim.ConsoleServerPortTemplate](../models/dcim/consoleserverporttemplate.md)

docs/development/release-checklist.md

@@ -59,7 +59,7 @@ Notify the [`netbox-docker`](https://github.com/netbox-community/netbox-docker)
 * Increases in minimum versions for service dependencies (PostgreSQL, Redis, etc.)
 * Any changes to the reference installation
 
-### Update Requirements
+### Update Python Dependencies
 
 Before each release, update each of NetBox's Python dependencies to its most recent stable version. These are defined in `requirements.txt`, which is updated from `base_requirements.txt` using `pip`. To do this:
 
@@ -70,6 +70,10 @@ Before each release, update each of NetBox's Python dependencies to its most rec
 
 In cases where upgrading a dependency to its most recent release is breaking, it should be constrained to its current minor version in `base_requirements.txt` with an explanatory comment and revisited for the next major NetBox release (see the [Address Constrained Dependencies](#address-constrained-dependencies) section above).
 
+### Update UI Dependencies
+
+Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](http://0.0.0.0:9000/development/web-ui/#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution.
+
 ### Rebuild the Device Type Definition Schema
 
 Run the following command to update the device type definition validation schema:
@@ -80,6 +84,18 @@ Run the following command to update the device type definition validation schema
 
 This will automatically update the schema file at `contrib/generated_schema.json`.
 
+### Update & Compile Translations
+
+Log into [Transifex](https://app.transifex.com/netbox-community/netbox/dashboard/) to download the updated string maps. Download the resource (portable object, or `.po`) file for each language and save them to `netbox/translations/$lang/LC_MESSAGES/django.po`, overwriting the current files. (Be sure to click the **Download for use** link.)
+
+![Transifex download](../media/development/transifex_download.png)
+
+Once the resource files for all languages have been updated, compile the machine object (`.mo`) files using the `compilemessages` management command:
+
+```nohighlight
+./manage.py compilemessages
+```
+
 ### Update Version and Changelog
 
 * Update the `VERSION` constant in `settings.py` to the new release version.
@@ -90,7 +106,7 @@ Commit these changes to the `develop` branch and push upstream.
 
 ### Verify CI Build Status
 
-Ensure that continuous integration testing on the `develop` branch is completing successfully. If it fails, take action to correct the failure before proceding with the release.
+Ensure that continuous integration testing on the `develop` branch is completing successfully. If it fails, take action to correct the failure before proceeding with the release.
 
 ### Submit a Pull Request
 

docs/development/search.md

@@ -17,6 +17,7 @@ class MyModelIndex(SearchIndex):
         ('description', 500),
         ('comments', 5000),
     )
+    display_attrs = ('site', 'device', 'status', 'description')
 ```
 
 A SearchIndex subclass defines both its model and a list of two-tuples specifying which model fields to be indexed and the weight (precedence) associated with each. Guidance on weight assignment for fields is provided below.

docs/development/signals.md

@@ -9,3 +9,27 @@ This signal is sent by models which inherit from `CustomValidationMixin` at the
 ### Receivers
 
 * `extras.signals.run_custom_validators()`
+
+## core.job_start
+
+This signal is sent whenever a [background job](../features/background-jobs.md) is started.
+
+### Receivers
+
+* `extras.signals.process_job_start_event_rules()`
+
+## core.job_end
+
+This signal is sent whenever a [background job](../features/background-jobs.md) is terminated.
+
+### Receivers
+
+* `extras.signals.process_job_end_event_rules()`
+
+## core.pre_sync
+
+This signal is sent when the [DataSource](../models/core/datasource.md) model's `sync()` method is called.
+
+## core.post_sync
+
+This signal is sent when a [DataSource](../models/core/datasource.md) finishes synchronizing.

docs/development/translations.md

@@ -0,0 +1,30 @@
+# Translations
+
+NetBox coordinates all translation work using the [Transifex](https://explore.transifex.com/netbox-community/netbox/) platform. Signing up for a Transifex account is free.
+
+All language translations in NetBox are generated from the source file found at `netbox/translations/en/LC_MESSAGES/django.po`. This file contains the original English strings with empty mappings, and is generated as part of NetBox's release process. Transifex updates source strings from this file on a recurring basis, so new translation strings will appear in the platform automatically as it is updated in the code base.
+
+Reviewers log into Transifex and navigate to their designated language(s) to translate strings. The initial translation for most strings will be machine-generated via the AWS Translate service. Human reviewers are responsible for reviewing these translations and making corrections where necessary.
+
+Immediately prior to each NetBox release, the translation maps for all completed languages will be downloaded from Transifex, compiled, and checked into the NetBox code base by a maintainer.
+
+## Updating Translation Sources
+
+To update the English `.po` file from which all translations are derived, use the `makemessages` management command:
+
+```nohighlight
+./manage.py makemessages -l en
+```
+
+Then, commit the change and push to the `develop` branch on GitHub. After some time, any new strings will appear for translation on Transifex automatically.
+
+## Proposing New Languages
+
+If you'd like to add support for a new language to NetBox, the first step is to [submit a GitHub issue](https://github.com/netbox-community/netbox/issues/new?assignees=&labels=type%3A+translation&projects=&template=translation.yaml) to capture the proposal. While we'd like to add as many languages as possible, we do need to limit the rate at which new languages are added. New languages will be selected according to community interest and the number of volunteers who sign up as translators.
+
+Once a proposed language has been approved, a NetBox maintainer will:
+
+* Add it to the Transifex platform
+* Designate one or more reviewers
+* Create the initial machine-generated translations for review
+* Add it to the list of supported languages

docs/development/user-preferences.md

@@ -11,4 +11,3 @@ The `users.UserConfig` model holds individual preferences for each user in the f
 | pagination.placement     | Where to display the paginator controls relative to the table |
 | tables.${table}.columns  | The ordered list of columns to display when viewing the table |
 | tables.${table}.ordering | A list of column names by which the table should be ordered   |
-| ui.colormode             | Light or dark mode in the user interface                      |

docs/development/web-ui.md

@@ -1,25 +1,37 @@
 # Web UI Development
 
+## Code Structure
+
+Most static resources for the NetBox UI are housed within the `netbox/project-static/` directory.
+
+| Path      | Description                                        |
+|-----------|----------------------------------------------------|
+| `dist/`   | Destination path for installed dependencies        |
+| `docs/`   | Local build path for documentation                 |
+| `img/`    | Image files                                        |
+| `js/`     | Miscellaneous JavaScript resources served directly |
+| `src/`    | TypeScript resources (to be compiled into JS)      |
+| `styles/` | Sass resources (to be compiled into CSS)           |
+
 ## Front End Technologies
 
-The NetBox UI is built on languages and frameworks:
+Front end scripting is written in [TypeScript](https://www.typescriptlang.org/), which is a strongly-typed extension to JavaScript. TypeScript is "transpiled" into JavaScript resources which are served to and executed by the client web browser.
 
-### Styling & HTML Elements
+All UI styling is written in [Sass](https://sass-lang.com/), which is an extension to browser-native [Cascading Stylesheets (CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS). Similar to how TypeScript content is transpiled to JavaScript, Sass resources (`.scss` files) are compiled to CSS.
 
-#### [Bootstrap](https://getbootstrap.com/) 5
+## Dependencies
 
-The majority of the NetBox UI is made up of stock Bootstrap components, with some styling modifications and custom components added on an as-needed basis. Bootstrap uses [Sass](https://sass-lang.com/), and NetBox extends Bootstrap's core Sass files for theming and customization.
+The following software is employed by the NetBox user interface.
 
-### Client-side Scripting
+* [Bootstrap 5](https://getbootstrap.com/) - A popular CSS & JS framework
-
+* [clipboard.js](https://clipboardjs.com/) - A lightweight package for enabling copy-to-clipboard functionality
-#### [TypeScript](https://www.typescriptlang.org/)
+* [flatpickr](https://flatpickr.js.org/) - A lightweight date & time selection widget
-
+* [gridstack.js](https://gridstackjs.com/) - Enables interactive grid layouts (for the dashboard)
-All client-side scripting is transpiled from TypeScript to JavaScript and served by Django. In development, TypeScript is an _extremely_ effective tool for accurately describing and checking the code, which leads to significantly fewer bugs, a better development experience, and more predictable/readable code.
+* [HTMX](https://htmx.org/) - Enables dynamic web interfaces through the use of HTML element attributes
-
+* [Material Design Icons](https://pictogrammers.com/library/mdi/) - An extensive open source collection of graphical icons, delivered as a web font
-As part of the [bundling](#bundling) process, Bootstrap's JavaScript plugins are imported and bundled alongside NetBox's front-end code.
+* [query-string](https://www.npmjs.com/package/query-string) - Assists with parsing URL query strings
-
+* [Tabler](https://tabler.io/) - A web application UI toolkit & theme based on Bootstrap 5
-!!! danger "NetBox is jQuery-free"
+* [Tom Select](https://tom-select.js.org/) - Provides dynamic selection form fields
-    Following the Bootstrap team's deprecation of jQuery in Bootstrap 5, NetBox also no longer uses jQuery in front-end code.
 
 ## Guidance
 
@@ -54,6 +66,41 @@ $ yarn
 !!! warning "Check Your Working Directory"
     You need to be in the `netbox/project-static` directory to run the below `yarn` commands.
 
+### Updating Dependencies
+
+Run `yarn outdated` to identify outdated dependencies.
+
+```
+$ yarn outdated
+yarn outdated v1.22.19
+info Color legend :
+ "<red>"    : Major Update backward-incompatible updates
+ "<yellow>" : Minor Update backward-compatible features
+ "<green>"  : Patch Update backward-compatible bug fixes
+Package                          Current Wanted  Latest Workspace Package Type    URL
+bootstrap                        5.3.1   5.3.1   5.3.3  netbox    dependencies    https://getbootstrap.com/
+```
+
+Run `yarn upgrade --latest` to automatically upgrade these packages to their most recent versions.
+
+```
+$ yarn upgrade bootstrap --latest
+yarn upgrade v1.22.19
+[1/4] Resolving packages...
+[2/4] Fetching packages...
+[3/4] Linking dependencies...
+[4/4] Rebuilding all packages...
+success Saved lockfile.
+success Saved 1 new dependency.
+info Direct dependencies
+└─ bootstrap@5.3.3
+info All dependencies
+└─ bootstrap@5.3.3
+Done in 0.95s.
+```
+
+`package.json` will be updated to reflect the new package versions automatically.
+
 ### Bundling
 
 In order for the TypeScript and Sass (SCSS) source files to be usable by a browser, they must first be transpiled (TypeScript → JavaScript, Sass → CSS), bundled, and minified. After making changes to TypeScript or Sass source files, run `yarn bundle`.

docs/features/api-integration.md

@@ -26,9 +26,9 @@ To learn more about this feature, check out the [GraphQL API documentation](../i
 
 ## Webhooks
 
-A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes.
+A webhook is a mechanism for conveying to some external system a change that has taken place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. To do this, first create a [webhook](../models/extras/webhook.md) identifying the remote receiver (URL), HTTP method, and any other necessary parameters. Then, define an [event rule](../models/extras/eventrule.md) which is triggered by device changes to transmit the webhook.
 
-To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md).
+When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are an excellent mechanism for building event-based automation processes. To learn more about this feature, check out the [webhooks documentation](../integrations/webhooks.md).
 
 ## Prometheus Metrics
 

docs/features/configuration-rendering.md

@@ -39,7 +39,7 @@ When rendered for a specific NetBox device, the template's `device` variable wil
 
 ### Context Data
 
-The objet for which the configuration is being rendered is made available as template context as `device` or `virtualmachine` for devices and virtual machines, respectively. Additionally, NetBox model classes can be accessed by the app or plugin in which they reside. For example:
+The object for which the configuration is being rendered is made available as template context as `device` or `virtualmachine` for devices and virtual machines, respectively. Additionally, NetBox model classes can be accessed by the app or plugin in which they reside. For example:
 
 ```
 There are {{ dcim.Site.objects.count() }} sites.
@@ -70,6 +70,11 @@ This request will trigger resolution of the device's preferred config template i
 
 If no config template has been assigned to any of these three objects, the request will fail.
 
+The configuration can be rendered as JSON or as plaintext by setting the `Accept:` HTTP header. For example:
+
+* `Accept: application/json`
+* `Accept: text/plain`
+
 ### General Purpose Use
 
 NetBox config templates can also be rendered without being tied to any specific device, using a separate general purpose REST API endpoint. Any data included with a POST request to this endpoint will be passed as context data for the template.

docs/features/customization.md

@@ -20,8 +20,6 @@ GET /api/dcim/devices/?tag=monitored&tag=deprecated
 
 ## Bookmarks
 
-!!! info "This feature was introduced in NetBox v3.6."
-
 Users can bookmark their most commonly visited objects for convenient access. Bookmarks are listed under a user's profile, and can be displayed with custom filtering and ordering on the user's personal dashboard.
 
 ## Custom Fields

docs/features/event-rules.md

@@ -0,0 +1,31 @@
+# Event Rules
+
+NetBox includes the ability to execute certain functions in response to internal object changes. These include:
+
+* [Scripts](../customization/custom-scripts.md) execution
+* [Webhooks](../integrations/webhooks.md) execution
+
+For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. You can then associate an event rule with this webhook and the webhook will be sent automatically by NetBox whenever the configured constraints are met.
+
+Each event must be associated with at least one NetBox object type and at least one event (e.g. create, update, or delete).
+
+## Conditional Event Rules
+
+An event rule may include a set of conditional logic expressed in JSON used to control whether an event triggers for a specific object. For example, you may wish to trigger an event for devices only when the `status` field of an object is "active":
+
+```json
+{
+  "and": [
+    {
+      "attr": "status.value",
+      "value": "active"
+    }
+  ]
+}
+```
+
+For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
+
+## Event Rule Processing
+
+When a change is detected, any resulting events are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing event(s) to be processed. The events are then extracted from the queue by the `rqworker` process. The current event queue and any failed events can be inspected under System > Background Tasks.

docs/features/search.md

@@ -8,6 +8,9 @@ When entering a search query, the user can choose a specific lookup type: exact
 
 Custom fields defined by NetBox administrators are also included in search results if configured with a search weight. Additionally, NetBox plugins can register their own custom models for inclusion alongside core models.
 
+!!! note
+    NetBox does not index any static choice field's (including custom fields of type "Selection" or "Multiple selection").
+
 ## Saved Filters
 
 Each type of object in NetBox is accompanied by an extensive set of filters, each tied to a specific attribute, which enable the creation of complex queries. Often you'll find that certain queries are used routinely to apply some set of prescribed conditions to a query. Once a set of filters has been applied, NetBox offers the option to save it for future use.

docs/features/synchronized-data.md

@@ -1,6 +1,6 @@
 # Synchronized Data
 
-Several models in NetBox support the automatic synchronization of local data from a designated remote source. For example, [configuration templates](./configuration-rendering.md) defined in NetBox can source their content from text files stored in a remote git repository. This accomplished using the core [data source](../models/core/datasource.md) and [data file](../models/core/datafile.md) models.
+Several models in NetBox support the automatic synchronization of local data from a designated remote source. For example, [configuration templates](./configuration-rendering.md) defined in NetBox can source their content from text files stored in a remote git repository. This is accomplished using the core [data source](../models/core/datasource.md) and [data file](../models/core/datafile.md) models.
 
 To enable remote data synchronization, the NetBox administrator first designates one or more remote data sources. NetBox currently supports the following source types:
 
@@ -10,7 +10,6 @@ To enable remote data synchronization, the NetBox administrator first designates
 
 (Local disk paths are considered "remote" in this context as they exist outside NetBox's database. These paths could also be mapped to external network shares.)
 
-
 !!! info
     Data backends which connect to external sources typically require the installation of one or more supporting Python libraries. The Git backend requires the [`dulwich`](https://www.dulwich.io/) package, and the S3 backend requires the [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) package. These must be installed within NetBox's environment to enable these backends.
 
@@ -23,3 +22,6 @@ The following NetBox models can be associated with replicated data files:
 * Export templates
 
 Once a data has been designated for a local instance, its data will be replaced with the content of the replicated file. When the replicated file is updated in the future (via synchronization jobs), the local instance will be flagged as having out-of-date data. A user can then synchronize these objects individually or in bulk to effect the update. This two-stage process ensures that automated synchronization tasks do not immediately affect production data.
+
+!!! note "Permissions"
+    A user must be assigned the `core.sync_datasource` permission in order to synchronize local files from a remote data source.

docs/features/vpn-tunnels.md

@@ -0,0 +1,49 @@
+# Tunnels
+
+NetBox can model private tunnels formed among virtual termination points across your network. Typical tunnel implementations include GRE, IP-in-IP, and IPSec. A tunnel may be terminated to two or more device or virtual machine interfaces. For convenient organization, tunnels may be assigned to user-defined groups.
+
+```mermaid
+flowchart TD
+    Termination1[TunnelTermination]
+    Termination2[TunnelTermination]
+    Interface1[Interface]
+    Interface2[Interface]
+    Tunnel --> Termination1 & Termination2
+    Termination1 --> Interface1
+    Termination2 --> Interface2
+    Interface1 --> Device
+    Interface2 --> VirtualMachine
+
+click Tunnel "../../models/vpn/tunnel/"
+click TunnelTermination1 "../../models/vpn/tunneltermination/"
+click TunnelTermination2 "../../models/vpn/tunneltermination/"
+```
+
+# IPSec & IKE
+
+NetBox includes robust support for modeling IPSec & IKE policies. These are used to define encryption and authentication parameters for IPSec tunnels.
+
+```mermaid
+flowchart TD
+    subgraph IKEProposals[Proposals]
+    IKEProposal1[IKEProposal]
+    IKEProposal2[IKEProposal]
+    end
+    subgraph IPSecProposals[Proposals]
+    IPSecProposal1[IPSecProposal]
+    IPSecProposal2[IPSecProposal]
+    end
+    IKEProposals --> IKEPolicy
+    IPSecProposals --> IPSecPolicy
+    IKEPolicy & IPSecPolicy--> IPSecProfile
+    IPSecProfile --> Tunnel
+
+click IKEProposal1 "../../models/vpn/ikeproposal/"
+click IKEProposal2 "../../models/vpn/ikeproposal/"
+click IKEPolicy "../../models/vpn/ikepolicy/"
+click IPSecProposal1 "../../models/vpn/ipsecproposal/"
+click IPSecProposal2 "../../models/vpn/ipsecproposal/"
+click IPSecPolicy "../../models/vpn/ipsecpolicy/"
+click IPSecProfile "../../models/vpn/ipsecprofile/"
+click Tunnel "../../models/vpn/tunnel/"
+```

docs/index.md

@@ -4,7 +4,7 @@
 
 NetBox is the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation. Read on to discover why thousands of organizations worldwide put NetBox at the heart of their infrastructure.
 
-[![NetBox UI](./media/screenshots/netbox-ui.png)](./media/screenshots/netbox-ui.png)
+[![NetBox UI](./media/screenshots/home-light.png)](./media/screenshots/home-light.png)
 
 ## :material-server-network: Built for Networks
 
@@ -32,7 +32,7 @@ In addition to its expansive and robust data model, NetBox offers myriad mechani
 * Custom fields
 * Custom model validation
 * Export templates
-* Webhooks
+* Event rules
 * Plugins
 * REST & GraphQL APIs
 

docs/installation/1-postgresql.md

@@ -31,8 +31,7 @@ This section entails the installation and configuration of a local PostgreSQL da
     Once PostgreSQL has been installed, start the service and enable it to run at boot:
 
     ```no-highlight
-    sudo systemctl start postgresql
+    sudo systemctl enable --now postgresql
-    sudo systemctl enable postgresql
     ```
 
 Before continuing, verify that you have installed PostgreSQL 12 or later:

docs/installation/2-redis.md

@@ -14,8 +14,7 @@
 
     ```no-highlight
     sudo yum install -y redis
-    sudo systemctl start redis
+    sudo systemctl enable --now redis
-    sudo systemctl enable redis
     ```
 
 Before continuing, verify that your installed version of Redis is at least v4.0:

docs/installation/3-netbox.md

@@ -6,8 +6,8 @@ This section of the documentation discusses installing and configuring the NetBo
 
 Begin by installing all system packages required by NetBox and its dependencies.
 
-!!! warning "Python 3.8 or later required"
+!!! warning "Python 3.10 or later required"
-    NetBox requires Python 3.8, 3.9, 3.10 or 3.11.
+    NetBox supports Python 3.10, 3.11, and 3.12.
 
 === "Ubuntu"
 
@@ -21,7 +21,7 @@ Begin by installing all system packages required by NetBox and its dependencies.
     sudo yum install -y gcc libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config
     ```
 
-Before continuing, check that your installed Python version is at least 3.8:
+Before continuing, check that your installed Python version is at least 3.10:
 
 ```no-highlight
 python3 -V
@@ -227,6 +227,17 @@ sudo sh -c "echo 'boto3' >> /opt/netbox/local_requirements.txt"
 !!! info
     These packages were previously required in NetBox v3.5 but now are optional.
 
+### Sentry Integration
+
+NetBox may be configured to send error reports to [Sentry](../administration/error-reporting.md) for analysis. This integration requires installation of the `sentry-sdk` Python library.
+
+```no-highlight
+sudo sh -c "echo 'sentry-sdk' >> /opt/netbox/local_requirements.txt"
+```
+
+!!! info
+    Sentry integration was previously included by default in NetBox v3.6 but is now optional.
+
 ## Run the Upgrade Script
 
 Once NetBox has been configured, we're ready to proceed with the actual installation. We'll run the packaged upgrade script (`upgrade.sh`) to perform the following actions:
@@ -244,10 +255,10 @@ Once NetBox has been configured, we're ready to proceed with the actual installa
 sudo /opt/netbox/upgrade.sh
 ```
 
-Note that **Python 3.8 or later is required** for NetBox v3.2 and later releases. If the default Python installation on your server is set to a lesser version,  pass the path to the supported installation as an environment variable named `PYTHON`. (Note that the environment variable must be passed _after_ the `sudo` command.)
+Note that **Python 3.10 or later is required** for NetBox v4.0 and later releases. If the default Python installation on your server is set to a lesser version,  pass the path to the supported installation as an environment variable named `PYTHON`. (Note that the environment variable must be passed _after_ the `sudo` command.)
 
 ```no-highlight
-sudo PYTHON=/usr/bin/python3.8 /opt/netbox/upgrade.sh
+sudo PYTHON=/usr/bin/python3.10 /opt/netbox/upgrade.sh
 ```
 
 !!! note

docs/installation/4a-gunicorn.md

@@ -1,10 +1,13 @@
 # Gunicorn
 
-Like most Django applications, NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) is a popular alternative.
+!!! tip
+    This page provides instructions for setting up the [gunicorn](http://gunicorn.org/) WSGI server. If you plan to use [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) instead, go [here](./4b-uwsgi.md).
+
+NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [gunicorn](http://gunicorn.org/) (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well.
 
 ## Configuration
 
-NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.)
+NetBox ships with a default configuration file for gunicorn. To use it, copy `/opt/netbox/contrib/gunicorn.py` to `/opt/netbox/gunicorn.py`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten during a future NetBox upgrade.)
 
 ```no-highlight
 sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
@@ -27,8 +30,7 @@ sudo systemctl daemon-reload
 Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time:
 
 ```no-highlight
-sudo systemctl start netbox netbox-rq
+sudo systemctl enable --now netbox netbox-rq
-sudo systemctl enable netbox netbox-rq
 ```
 
 You can use the command `systemctl status netbox` to verify that the WSGI service is running:
@@ -58,3 +60,6 @@ You should see output similar to the following:
     If the NetBox service fails to start, issue the command `journalctl -eu netbox` to check for log messages that may indicate the problem.
 
 Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.
+
+!!! note
+    There is a bug in the current stable release of gunicorn (v21.2.0) where automatic restarts of the worker processes can result in 502 errors under heavy load. (See [gunicorn bug #3038](https://github.com/benoitc/gunicorn/issues/3038) for more detail.) Users who encounter this issue may opt to downgrade to an earlier, unaffected release of gunicorn (`pip install gunicorn==20.1.0`). Note, however, that this earlier release does not officially support Python 3.11.

docs/installation/4b-uwsgi.md

@@ -0,0 +1,104 @@
+# uWSGI
+
+!!! tip
+    This page provides instructions for setting up the [uWSGI](https://uwsgi-docs.readthedocs.io/) WSGI server. If you plan to use [gunicorn](http://gunicorn.org/) instead, go [here](./4a-gunicorn.md).
+
+NetBox runs as a [WSGI application](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface) behind an HTTP server. This documentation shows how to install and configure [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) for this role, however other WSGI servers are available and should work similarly well.
+
+## Installation
+
+Activate the Python virtual environment and install the `pyuwsgi` package using pip:
+
+```no-highlight
+source /opt/netbox/venv/bin/activate
+pip3 install pyuwsgi
+```
+
+Once installed, add the package to `local_requirements.txt` to ensure it is re-installed during future rebuilds of the virtual environment:
+
+```no-highlight
+sudo sh -c "echo 'pyuwgsi' >> /opt/netbox/local_requirements.txt"
+```
+
+## Configuration
+
+NetBox ships with a default configuration file for uWSGI. To use it, copy `/opt/netbox/contrib/uwsgi.ini` to `/opt/netbox/uwsgi.ini`. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten during a future NetBox upgrade.)
+
+```no-highlight
+sudo cp /opt/netbox/contrib/uwsgi.ini /opt/netbox/uwsgi.ini
+```
+
+While the provided configuration should suffice for most initial installations, you may wish to edit this file to change the bound IP address and/or port number, or to make performance-related adjustments. See [the uWSGI documentation](https://uwsgi-docs-additions.readthedocs.io/en/latest/Options.html) for the available configuration parameters and take a minute to review the [Things to know](https://uwsgi-docs.readthedocs.io/en/latest/ThingsToKnow.html) page. Django also provides [additional documentation](https://docs.djangoproject.com/en/5.0/howto/deployment/wsgi/uwsgi/) on configuring uWSGI with a Django app.
+
+## systemd Setup
+
+We'll use systemd to control both uWSGI and NetBox's background worker process. First, copy `contrib/netbox.service` and `contrib/netbox-rq.service` to the `/etc/systemd/system/` directory.
+
+```no-highlight
+sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
+sudo systemctl daemon-reload
+```
+
+The reference configuration assumes that gunicorn is in use, so we need to update it. Edit the `netbox.service` file to remove the line beginning with `ExecStart=/opt/netbox/venv/bin/gunicorn` and uncomment the line below it.
+
+!!! warning "Check user & group assignment"
+    The stock service configuration files packaged with NetBox assume that the service will run with the `netbox` user and group names. If these differ on your installation, be sure to update the service files accordingly.
+
+Once the configuration file has been saved, reload the service:
+
+```no-highlight
+sudo systemctl daemon-reload
+```
+
+Then, start the `netbox` and `netbox-rq` services and enable them to initiate at boot time:
+
+```no-highlight
+sudo systemctl enable --now netbox netbox-rq
+```
+
+You can use the command `systemctl status netbox` to verify that the WSGI service is running:
+
+```no-highlight
+systemctl status netbox.service
+```
+
+You should see output similar to the following:
+
+```no-highlight
+● 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 (uwsgi)
+      Tasks: 19 (limit: 4683)
+     Memory: 666.2M
+     CGroup: /system.slice/netbox.service
+             ├─1061 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini
+             ├─1976 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/uwsgi --ini /opt/netbox/uwsgi.ini
+...
+```
+
+!!! note
+    If the NetBox service fails to start, issue the command `journalctl -eu netbox` to check for log messages that may indicate the problem.
+
+Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.
+
+## HTTP Server Installation
+
+For server installation, you will want to follow the NetBox [HTTP Server Setup](5-http-server.md) guide, however after copying the configuration file, you will need to edit the file and change the `location` section to uncomment the uWSGI parameters:
+
+```no-highlight
+    location / {
+        # proxy_pass http://127.0.0.1:8001;
+        # proxy_set_header X-Forwarded-Host $http_host;
+        # proxy_set_header X-Real-IP $remote_addr;
+        # proxy_set_header X-Forwarded-Proto $scheme;
+        # comment the lines above and uncomment the lines below if using uWSGI
+        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;
+    }
+```

docs/installation/5-http-server.md

@@ -35,6 +35,9 @@ Once nginx is installed, copy the nginx configuration file provided by NetBox to
 sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
 ```
 
+!!! tip "gunicorn vs. uWSGI"
+    The reference nginx configuration file assumes that gunicorn is in use. If using uWSGI instead, you'll need to remove the gunicorn-specific configuration (lines beginning with `proxy_pass` and `proxy_set_header`) and uncomment the uWSGI section below them before proceeding.
+
 Then, delete `/etc/nginx/sites-enabled/default` and create a symlink in the `sites-enabled` directory to the configuration file you just created.
 
 ```no-highlight

docs/installation/index.md

@@ -12,17 +12,17 @@ The following sections detail how to set up a new instance of NetBox:
 1. [PostgreSQL database](1-postgresql.md)
 1. [Redis](2-redis.md)
 3. [NetBox components](3-netbox.md)
-4. [Gunicorn](4-gunicorn.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 | Minimum Version |
+| Dependency | Supported Versions |
-|------------|-----------------|
+|------------|--------------------|
-| Python     | 3.8             |
+| Python     | 3.10, 3.11, 3.12   |
-| PostgreSQL | 12              |
+| PostgreSQL | 12+                |
-| Redis      | 4.0             |
+| Redis      | 4.0+               |
 
 Below is a simplified overview of the NetBox application stack for reference:
 

docs/installation/upgrading.md

@@ -17,11 +17,11 @@ Prior to upgrading your NetBox instance, be sure to carefully review all [releas
 
 NetBox requires the following dependencies:
 
-| Dependency | Minimum Version |
+| Dependency | Supported Versions |
-|------------|-----------------|
+|------------|--------------------|
-| Python     | 3.8             |
+| Python     | 3.10, 3.11, 3.12   |
-| PostgreSQL | 12              |
+| PostgreSQL | 12+                |
-| Redis      | 4.0             |
+| Redis      | 4.0+               |
 
 ## 3. Install the Latest Release
 
@@ -108,10 +108,10 @@ sudo ./upgrade.sh
 ```
 
 !!! warning
-    If the default version of Python is not at least 3.8, you'll need to pass the path to a supported Python version as an environment variable when calling the upgrade script. For example:
+    If the default version of Python is not at least 3.10, you'll need to pass the path to a supported Python version as an environment variable when calling the upgrade script. For example:
 
     ```no-highlight
-    sudo PYTHON=/usr/bin/python3.8 ./upgrade.sh
+    sudo PYTHON=/usr/bin/python3.10 ./upgrade.sh
     ```
 
 This script performs the following actions:

docs/integrations/graphql-api.md

@@ -54,7 +54,11 @@ For more detail on constructing GraphQL queries, see the [Graphene documentation
 The GraphQL API employs the same filtering logic as the UI and REST API. Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only sites within the North Carolina region with a status of active:
 
 ```
-{"query": "query {site_list(region:\"north-carolina\", status:\"active\") {name}}"}
+query {
+  site_list(filters: {region: "us-nc", status: "active"}) {
+    name
+  }
+}
 ```
 In addition, filtering can be done on list of related objects as shown in the following query:
 
@@ -63,7 +67,7 @@ In addition, filtering can be done on list of related objects as shown in the fo
   device_list {
     id
     name
-    interfaces(enabled: true) {
+    interfaces(filters: {enabled: true}) {
       name
     }
   }

docs/integrations/rest-api.md

@@ -85,13 +85,19 @@ Each model generally has two views associated with it: a list view and a detail
 * `/api/dcim/devices/` - List existing devices or create a new device
 * `/api/dcim/devices/123/` - Retrieve, update, or delete the device with ID 123
 
-Lists of objects can be filtered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
+Lists of objects can be filtered and ordered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
 
 ```
 GET /api/dcim/interfaces/?device_id=123
 ```
 
-See the [filtering documentation](../reference/filtering.md) for more details.
+An optional `ordering` parameter can be used to define how to sort the results. Building off the previous example, to sort all the interfaces in reverse order of creation (newest to oldest) for a device with ID 123:
+
+```
+GET /api/dcim/interfaces/?device_id=123&ordering=-created
+```
+
+See the [filtering documentation](../reference/filtering.md) for more details on topics related to filtering, ordering and lookup expressions.
 
 ## Serialization
 
@@ -647,18 +653,20 @@ Note that we are _not_ passing an existing REST API token with this request. If
 {
     "id": 6,
     "url": "https://netbox/api/users/tokens/6/",
-    "display": "3c9cb9 (hankhill)",
+    "display": "**********************************3c9cb9",
     "user": {
         "id": 2,
         "url": "https://netbox/api/users/users/2/",
         "display": "hankhill",
         "username": "hankhill"
     },
-    "created": "2021-06-11T20:09:13.339367Z",
+    "created": "2024-03-11T20:09:13.339367Z",
     "expires": null,
+    "last_used": null,
     "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
     "write_enabled": true,
-    "description": ""
+    "description": "",
+    "allowed_ips": []
 }
 ```
 

docs/integrations/synchronized-data.md

@@ -2,6 +2,9 @@
 
 Some NetBox models support automatic synchronization of certain attributes from remote [data sources](../models/core/datasource.md), such as a git repository hosted on GitHub or GitLab. Data from the authoritative remote source is synchronized locally in NetBox as [data files](../models/core/datafile.md).
 
+!!! note "Permissions"
+    A user must be assigned the `core.sync_datasource` permission in order to synchronize local files from a remote data source. This is accomplished by creating a permission for the "Core > Data Source" object type with the `sync` action, and assigning it to the desired user and/or group.
+
 The following features support the use of synchronized data:
 
 * [Configuration templates](../features/configuration-rendering.md)

docs/integrations/webhooks.md

@@ -1,11 +1,9 @@
 # Webhooks
 
-NetBox can be configured to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.
+NetBox can be configured via [Event Rules](../features/event-rules.md) to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.
 
 For example, suppose you want to automatically configure a monitoring system to start monitoring a device when its operational status is changed to active, and remove it from monitoring for any other status. You can create a webhook in NetBox for the device model and craft its content and destination URL to effect the desired change on the receiving system. Webhooks will be sent automatically by NetBox whenever the configured constraints are met.
 
-Each webhook must be associated with at least one NetBox object type and at least one event (create, update, or delete). Users can specify the receiver URL, HTTP request type (`GET`, `POST`, etc.), content type, and headers. A request body can also be specified; if left blank, this will default to a serialized representation of the affected object.
-
 !!! warning "Security Notice"
     Webhooks support the inclusion of user-submitted code to generate the URL, custom headers, and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
 
@@ -70,28 +68,14 @@ If no body template is specified, the request body will be populated with a JSON
 }
 ```
 
-## Conditional Webhooks
+!!! note
-
+    The setting of conditional webhooks has been moved to [Event Rules](../features/event-rules.md) since NetBox 3.7
-A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active":
-
-```json
-{
-  "and": [
-    {
-      "attr": "status.value",
-      "value": "active"
-    }
-  ]
-}
-```
-
-For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
 
 ## Webhook Processing
 
-When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks.
+Using [Event Rules](../features/event-rules.md), when a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected under System > Background Tasks.
 
-A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI.
+A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be requeued manually under System > Background Tasks.
 
 ## Troubleshooting
 
@@ -122,6 +106,6 @@ Content-Type: application/x-www-form-urlencoded
 ------------
 ```
 
-Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection.
+Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection. If you don't see any output, check that the `rqworker` process is running and that webhook events are being placed into the queue.
 
-Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI).
+Webhook results can be found in the NetBox admin UI under the Background Tasks section. You can see any finished or failed runs, as well as the error log for failed webhooks.

docs/introduction.md

@@ -19,10 +19,13 @@ NetBox was built specifically to serve the needs of network engineers and operat
 * 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
-* L2 VPN overlays
+* VPN tunnels
+* IKE & IPSec policies
+* Layer 2 VPN overlays
 * FHRP groups (VRRP, HSRP, etc.)
 * Application service bindings
 * Virtual machines & clusters
@@ -30,13 +33,14 @@ NetBox was built specifically to serve the needs of network engineers and operat
 * Tenant ownership assignment
 * Device & VM configuration contexts for advanced configuration rendering
 * Custom fields for data model extension
-* Custom validation rules
+* 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
 

docs/models/dcim/device.md

@@ -18,9 +18,9 @@ When a device has one or more interfaces with IP addresses assigned, a primary I
 
 The device's configured name. This field is optional; devices can be unnamed. However, if set, the name must be unique to the assigned site and tenant.
 
-### Device Role
+### Role
 
-The functional [role](./devicerole.md) assigned to this device.
+The functional [device role](./devicerole.md) assigned to this device.
 
 ### Device Type
 

docs/models/dcim/interface.md

@@ -77,6 +77,9 @@ If selected, this component will be treated as if a cable has been connected.
 
 Virtual interfaces can be bound to a physical parent interface. This is helpful for modeling virtual interfaces which employ encapsulation on a physical interface, such as an 802.1Q VLAN-tagged subinterface.
 
+!!! note
+    An interface with one or more child interfaces assigned cannot be deleted until all its child interfaces have been deleted or reassigned.
+
 ### Bridged Interface
 
 Interfaces can be bridged to other interfaces on a device in two manners: symmetric or grouped.

docs/models/dcim/inventoryitem.md

@@ -19,7 +19,7 @@ The parent inventory item to which this item is assigned (optional).
 
 ### Name
 
-The inventory item's name. Must be unique to the parent device.
+The inventory item's name. If the inventory item is assigned to a parent item, its name must be unique among its siblings (all items belonging to the same parent item).
 
 ### Label
 

docs/models/dcim/location.md

@@ -26,3 +26,7 @@ The location's operational status.
 
 !!! tip
     Additional statuses may be defined by setting `Location.status` under the [`FIELD_CHOICES`](../../configuration/data-validation.md#field_choices) configuration parameter.
+
+### Facility
+
+Data center or facility designation for identifying the location.

docs/models/extras/bookmark.md

@@ -1,7 +1,5 @@
 # Bookmarks
 
-!!! info "This feature was introduced in NetBox v3.6."
-
 A user can bookmark individual objects for convenient access. Bookmarks are listed under a user's profile and can be displayed using a dashboard widget.
 
 ## Fields

docs/models/extras/customfield.md

@@ -38,7 +38,7 @@ The type of data this field holds. This must be one of the following:
 | Object             | A single NetBox object of the type defined by `object_type`        |
 | Multiple object    | One or more NetBox objects of the type defined by `object_type`    |
 
-### Object Type
+### Related Object Type
 
 For object and multiple-object fields only. Designates the type of NetBox object being referenced.
 
@@ -64,16 +64,25 @@ Defines how filters are evaluated against custom field values.
 | Loose    | Match any occurrence of the value   |
 | Exact    | Match only the complete field value |
 
-### UI Visibility
+### UI Visible
 
-Controls how and whether the custom field is displayed within the NetBox user interface.
+Controls whether the custom field is displayed for objects within the NetBox user interface.
 
-| Option            | Description                                      |
+| Option | Description                                                    |
-|-------------------|--------------------------------------------------|
+|--------|----------------------------------------------------------------|
-| Read/write        | Display and permit editing (default)             |
+| Always | The field is always displayed when viewing an object (default) |
-| Read-only         | Display field but disallow editing               |
+| If set | The field is displayed only if a value has been defined        |
-| Hidden            | Do not display field in the UI                   |
+| Hidden | The field is not displayed when viewing an object              |
-| Hidden (if unset) | Display in the UI only when a value has been set |
+
+### UI Editable
+
+Controls whether the custom field is editable on objects within the NetBox user interface.
+
+| Option | Description                                                                  |
+|--------|------------------------------------------------------------------------------|
+| Yes    | The field's value may be changed when editing an object (default)            |
+| No     | The field's value is displayed when editing an object but may not be altered |
+| Hidden | The field is not displayed when editing an object                            |
 
 ### Default
 

docs/models/extras/customfieldchoiceset.md

@@ -1,7 +1,5 @@
 # Custom Field Choice Sets
 
-!!! info "This feature was introduced in NetBox v3.6."
-
 Single- and multi-selection [custom fields](../../customization/custom-fields.md) must define a set of valid choices from which the user may choose when defining the field value. These choices are defined as sets that may be reused among multiple custom fields.
 
 A choice set must define a base choice set and/or a set of arbitrary extra choices.

docs/models/extras/eventrule.md

@@ -0,0 +1,35 @@
+# EventRule
+
+An event rule is a mechanism for automatically taking an action (such as running a script or sending a webhook) in response to an event in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating an event for device objects and designating a webhook to be transmitted. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
+
+See the [event rules documentation](../../features/event-rules.md)  for more information.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Content Types
+
+The type(s) of object in NetBox that will trigger the rule.
+
+### Enabled
+
+If not selected, the event rule will not be processed.
+
+### Events
+
+The events which will trigger the rule. At least one event type must be selected.
+
+| Name       | Description                          |
+|------------|--------------------------------------|
+| Creations  | A new object has been created        |
+| Updates    | An existing object has been modified |
+| Deletions  | An object has been deleted           |
+| Job starts | A job for an object starts           |
+| Job ends   | A job for an object terminates       |
+
+### Conditions
+
+A set of [prescribed conditions](../../reference/conditions.md) against which the triggering object will be evaluated. If the conditions are defined but not met by the object, no action will be taken. An event rule that does not define any conditions will _always_ trigger.

docs/models/extras/tag.md

@@ -18,8 +18,6 @@ The color to use when displaying the tag in the NetBox UI.
 
 ### Object Types
 
-!!! info "This feature was introduced in NetBox v3.6."
-
 The assignment of a tag may be limited to a prescribed set of objects. For example, it may be desirable to limit the application of a specific tag to only devices and virtual machines.
 
 If no object types are specified, the tag will be assignable to any type of object.

docs/models/ipam/l2vpntermination.md

@@ -1,18 +0,0 @@
-# L2VPN Termination
-
-A L2VPN termination is the attachment of an [L2VPN](./l2vpn.md) to an [interface](../dcim/interface.md) or [VLAN](./vlan.md). Note that the L2VPNs of the following types may have only two terminations assigned to them:
-
-* VPWS
-* EPL
-* EP-LAN
-* EP-TREE
-
-## Fields
-
-### L2VPN
-
-The [L2VPN](./l2vpn.md) instance.
-
-### VLAN or Interface
-
-The [VLAN](./vlan.md), [device interface](../dcim/interface.md), or [virtual machine interface](../virtualization/virtualmachine.md) attached to the L2VPN.

docs/models/virtualization/virtualdisk.md

@@ -0,0 +1,13 @@
+# Virtual Disks
+
+A virtual disk is used to model discrete virtual hard disks assigned to [virtual machines](./virtualmachine.md).
+
+## Fields
+
+### Name
+
+A human-friendly name that is unique to the assigned virtual machine.
+
+### Size
+
+The allocated disk size, in gigabytes.

docs/models/virtualization/vminterface.md

@@ -16,6 +16,9 @@ The interface's name. Must be unique to the assigned VM.
 
 Identifies the parent interface of a subinterface (e.g. used to employ encapsulation).
 
+!!! note
+    An interface with one or more child interfaces assigned cannot be deleted until all its child interfaces have been deleted or reassigned.
+
 ### Bridged Interface
 
 An interface on the same VM with which this interface is bridged.

docs/models/vpn/ikepolicy.md

@@ -0,0 +1,25 @@
+# IKE Policies
+
+An [Internet Key Exhcnage (IKE)](https://en.wikipedia.org/wiki/Internet_Key_Exchange) policy defines an IKE version, mode, and set of [proposals](./ikeproposal.md) to be used in IKE negotiation. These policies are referenced by [IPSec profiles](./ipsecprofile.md).
+
+## Fields
+
+### Name
+
+The unique user-assigned name for the policy.
+
+### Version
+
+The IKE version employed (v1 or v2).
+
+### Mode
+
+The mode employed (main or aggressive) when IKEv1 is in use. This setting is not supported for IKEv2.
+
+### Proposals
+
+One or more [IKE proposals](./ikeproposal.md) supported for use by this policy.
+
+### Pre-shared Key
+
+A pre-shared secret key associated with this policy (optional).

docs/models/vpn/ikeproposal.md

@@ -0,0 +1,39 @@
+# IKE Proposals
+
+An [Internet Key Exhcnage (IKE)](https://en.wikipedia.org/wiki/Internet_Key_Exchange) proposal defines a set of parameters used to establish a secure bidirectional connection across an untrusted medium, such as the Internet. IKE proposals defined in NetBox can be referenced by [IKE policies](./ikepolicy.md), which are in turn employed by [IPSec profiles](./ipsecprofile.md).
+
+!!! note
+    Some platforms refer to IKE proposals as [ISAKMP](https://en.wikipedia.org/wiki/Internet_Security_Association_and_Key_Management_Protocol), which is a framework for authentication and key exchange which employs IKE.
+
+## Fields
+
+### Name
+
+The unique user-assigned name for the proposal.
+
+### Authentication Method
+
+The strategy employed for authenticating the IKE peer. Available options are listed below.
+
+| Name           |
+|----------------|
+| Pre-shared key |
+| Certificate    |
+| RSA signature  |
+| DSA signature  |
+
+### Encryption Algorithm
+
+The protocol employed for data encryption. Options include DES, 3DES, and various flavors of AES.
+
+### Authentication Algorithm
+
+The mechanism employed to ensure data integrity. Options include MD5 and SHA HMAC implementations. Specifying an authentication algorithm is optional, as some encryption algorithms (e.g. AES-GCM) provide authentication natively.
+
+### Group
+
+The [Diffie-Hellman group](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) supported by the proposal. Group IDs are [managed by IANA](https://www.iana.org/assignments/ikev2-parameters/ikev2-parameters.xhtml#ikev2-parameters-8).
+
+### SA Lifetime
+
+The maximum lifetime for the IKE security association (SA), in seconds.

docs/models/vpn/ipsecpolicy.md

@@ -0,0 +1,17 @@
+# IPSec Policy
+
+An [IPSec](https://en.wikipedia.org/wiki/IPsec) policy defines a set of [proposals](./ikeproposal.md) to be used in the formation of IPSec tunnels. A perfect forward secrecy (PFS) group may optionally also be defined. These policies are referenced by [IPSec profiles](./ipsecprofile.md).
+
+## Fields
+
+### Name
+
+The unique user-assigned name for the policy.
+
+### Proposals
+
+One or more [IPSec proposals](./ipsecproposal.md) supported for use by this policy.
+
+### PFS Group
+
+The [perfect forward secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) group supported by this policy (optional).

docs/models/vpn/ipsecprofile.md

@@ -0,0 +1,21 @@
+# IPSec Profile
+
+An [IPSec](https://en.wikipedia.org/wiki/IPsec) profile defines an [IKE policy](./ikepolicy.md), [IPSec policy](./ipsecpolicy.md), and IPSec mode used for establishing an IPSec tunnel.
+
+## Fields
+
+### Name
+
+The unique user-assigned name for the profile.
+
+### Mode
+
+The IPSec mode employed by the profile: Encapsulating Security Payload (ESP) or Authentication Header (AH).
+
+### IKE Policy
+
+The [IKE policy](./ikepolicy.md) associated with the profile.
+
+### IPSec Policy
+
+The [IPSec policy](./ipsecpolicy.md) associated with the profile.

docs/models/vpn/ipsecproposal.md

@@ -0,0 +1,31 @@
+# IPSec Proposal
+
+An [IPSec](https://en.wikipedia.org/wiki/IPsec) proposal defines a set of parameters used in negotiating security associations for IPSec tunnels. IPSec proposals defined in NetBox can be referenced by [IPSec policies](./ipsecpolicy.md), which are in turn employed by [IPSec profiles](./ipsecprofile.md).
+
+## Fields
+
+### Name
+
+The unique user-assigned name for the proposal.
+
+### Encryption Algorithm
+
+The protocol employed for data encryption. Options include DES, 3DES, and various flavors of AES.
+
+!!! note
+    If an encryption algorithm is not specified, an authentication algorithm must be specified.
+
+### Authentication Algorithm
+
+The mechanism employed to ensure data integrity. Options include MD5 and SHA HMAC implementations.
+
+!!! note
+    If an authentication algorithm is not specified, an encryption algorithm must be specified.
+
+### SA Lifetime (Seconds)
+
+The maximum amount of time for which the security association (SA) may be active, in seconds.
+
+### SA Lifetime (Data)
+
+The maximum amount of data which can be transferred within the security association (SA) before it must be rebuilt, in kilobytes.

docs/models/vpn/l2vpn.md

@@ -1,6 +1,6 @@
 # L2VPN
 
-A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS, or EPL. Each L2VPN can be identified by name as well as by an optional unique identifier (VNI would be an example). Once created, L2VPNs can be terminated to [interfaces](../dcim/interface.md) and [VLANs](./vlan.md).
+A L2VPN object is NetBox is a representation of a layer 2 bridge technology such as VXLAN, VPLS, or EPL. Each L2VPN can be identified by name as well as by an optional unique identifier (VNI would be an example). Once created, L2VPNs can be terminated to [interfaces](../dcim/interface.md) and [VLANs](../ipam/vlan.md).
 
 ## Fields
 
@@ -38,4 +38,4 @@ An optional numeric identifier. This can be used to track a pseudowire ID, for e
 
 ### Import & Export Targets
 
-The [route targets](./routetarget.md) associated with this L2VPN to control the import and export of forwarding information.
+The [route targets](../ipam/routetarget.md) associated with this L2VPN to control the import and export of forwarding information.

docs/models/vpn/l2vpntermination.md

@@ -0,0 +1,18 @@
+# L2VPN Termination
+
+A L2VPN termination is the attachment of an [L2VPN](./l2vpn.md) to an [interface](../dcim/interface.md) or [VLAN](../ipam/vlan.md). Note that the L2VPNs of the following types may have only two terminations assigned to them:
+
+* VPWS
+* EPL
+* EP-LAN
+* EP-TREE
+
+## Fields
+
+### L2VPN
+
+The [L2VPN](./l2vpn.md) instance.
+
+### VLAN or Interface
+
+The [VLAN](../ipam/vlan.md), [device interface](../dcim/interface.md), or [virtual machine interface](../virtualization/virtualmachine.md) attached to the L2VPN.