Release v3.2.0-beta2

Closes #8823: Add plugin support for REST API components

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -13,11 +13,8 @@ body:
   - type: input
     attributes:
       label: NetBox version
-      description: >
-        What version of NetBox are you currently running? (If you don't have access to the most
-        recent NetBox release, consider testing on our [demo instance](https://demo.netbox.dev/)
-        before opening a bug report to see if your issue has already been addressed.)
-      placeholder: v3.0.3
+      description: What version of NetBox are you currently running?
+      placeholder: v3.1.9
     validations:
       required: true
   - type: dropdown
@@ -25,9 +22,9 @@ body:
       label: Python version
       description: What version of Python are you currently running?
       options:
-        - 3.7
-        - 3.8
-        - 3.9
+        - "3.7"
+        - "3.8"
+        - "3.9"
     validations:
       required: true
   - type: textarea

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -14,7 +14,7 @@ body:
     attributes:
       label: NetBox version
       description: What version of NetBox are you currently running?
-      placeholder: v3.0.3
+      placeholder: v3.1.9
     validations:
       required: true
   - type: dropdown

.github/workflows/ci.yml

@@ -3,10 +3,12 @@ on: [push, pull_request]
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      NETBOX_CONFIGURATION: netbox.configuration_testing
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9]
-        node-version: [14.x]
+        python-version: ['3.8', '3.9', '3.10']
+        node-version: ['14.x']
     services:
       redis:
         image: redis
@@ -38,14 +40,25 @@ jobs:
       uses: actions/setup-node@v2
       with:
         node-version: ${{ matrix.node-version }}
+    
+    - name: Install Yarn Package Manager
+      run: npm install -g yarn
+    
+    - name: Setup Node.js with Yarn Caching
+      uses: actions/setup-node@v2
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: yarn
+        cache-dependency-path: netbox/project-static/yarn.lock
+    
+    - name: Install Frontend Dependencies
+      run: yarn --cwd netbox/project-static
 
     - name: Install dependencies & set up configuration
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         pip install pycodestyle coverage
-        ln -s configuration.testing.py netbox/netbox/configuration.py
-        yarn --cwd netbox/project-static
 
     - name: Build documentation
       run: mkdocs build
@@ -63,7 +76,7 @@ jobs:
       run: scripts/verify-bundles.sh
 
     - name: Run tests
-      run: coverage run --source="netbox/" netbox/manage.py test netbox/
+      run: coverage run --source="netbox/" netbox/manage.py test netbox/ --parallel
 
     - name: Show coverage report
       run: coverage report --skip-covered --omit *migrations*

.gitignore

@@ -8,6 +8,7 @@ yarn-error.log*
 !/netbox/project-static/docs/.info
 /netbox/netbox/configuration.py
 /netbox/netbox/ldap_config.py
+/netbox/local/*
 /netbox/reports/*
 !/netbox/reports/__init__.py
 /netbox/scripts/*

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+mkdocs:
+  configuration: mkdocs.yml
+python:
+   install:
+   - requirements: requirements.txt

CONTRIBUTING.md

@@ -16,13 +16,6 @@ categories for discussions:
   feature request
 * **Q&A** - Request help with installing or using NetBox
 
-### Mailing List
-
-We also have a Google Groups [mailing list](https://groups.google.com/g/netbox-discuss)
-for general discussion, however we're encouraging people to use GitHub
-discussions where possible, as it's much easier for newcomers to review past
-discussions.
-
 ### Slack
 
 For real-time chat, you can join the **#netbox** Slack channel on [NetDev Community](https://netdev.chat/).
@@ -76,14 +69,10 @@ free to add a comment with any additional justification for the feature.
 (However, note that comments with no substance other than a "+1" will be
 deleted. Please use GitHub's reactions feature to indicate your support.)
 
-* Due to a large backlog of feature requests, we are not currently accepting
-any proposals which substantially extend NetBox's functionality beyond its
-current feature set. This includes the introduction of any new views or models
-which have not already been proposed in an existing feature request.
-
-* Before filing a new feature request, consider raising your idea on the
-mailing list first. Feedback you receive there will help validate and shape the
-proposed feature before filing a formal issue.
+* Before filing a new feature request, consider raising your idea in a
+[GitHub discussion](https://github.com/netbox-community/netbox/discussions)
+first. Feedback you receive there will help validate and shape the proposed
+feature before filing a formal issue.
 
 * Good feature requests are very narrowly defined. Be sure to thoroughly
 describe the functionality and data model(s) being proposed. The more effort

README.md

@@ -2,14 +2,51 @@
   <img src="https://raw.githubusercontent.com/netbox-community/netbox/develop/docs/netbox_logo.svg" width="400" alt="NetBox logo" />
 </div>
 
+:loudspeaker: The **[2022 NetBox community survey](https://forms.gle/KR8YbR8GiJ9EYXM28)** is now open! We collect this feedback and demographic data from NetBox users around the world to help shape the project's long-term development goals. Please take a few minutes to share your responses!
+
 ![Master branch build status](https://github.com/netbox-community/netbox/workflows/CI/badge.svg?branch=master)
 
 NetBox is an infrastructure resource modeling (IRM) tool designed to empower
-network automation. Initially conceived by the network engineering team at
+network automation, used by thousands of organizations around the world.
+Initially conceived by the network engineering team at
 [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically
 to address the needs of network and infrastructure engineers. It is intended to
 function as a domain-specific source of truth for network operations.
 
+Myriad infrastructure components can be modeled in NetBox, including:
+
+* Hierarchical regions, site groups, sites, and locations
+* Racks, devices, and device components
+* Cables and wireless connections
+* Power distribution
+* Data circuits and providers
+* Virtual machines and clusters
+* IP prefixes, ranges, and addresses
+* VRFs and route targets
+* FHRP groups (VRRP, HSRP, etc.)
+* AS numbers
+* VLANs and scoped VLAN groups
+* Organizational tenants and contacts
+
+In addition to its extensive built-in models and functionality, NetBox can be
+customized and extended through the use of:
+
+* Custom fields
+* Custom links
+* Configuration contexts
+* Custom model validation rules
+* Reports
+* Custom scripts
+* Export templates
+* Conditional webhooks
+* Plugins
+* Single sign-on (SSO) authentication
+* NAPALM integration
+* Detailed change logging
+
+NetBox also features a complete REST API as well as a GraphQL API for easily
+integrating with other tools and systems.
+
 NetBox runs as a web application atop the [Django](https://www.djangoproject.com/)
 Python framework with a [PostgreSQL](https://www.postgresql.org/) database. For a
 complete list of requirements, see `requirements.txt`. The code is available [on GitHub](https://github.com/netbox-community/netbox).
@@ -33,7 +70,6 @@ The complete documentation for NetBox can be found at [Read the Docs](https://ne
 
 * [GitHub Discussions](https://github.com/netbox-community/netbox/discussions) - Discussion forum hosted by GitHub; ideal for Q&A and other structured discussions
 * [Slack](https://netdev.chat/) - Real-time chat hosted by the NetDev Community; best for unstructured discussion or just hanging out
-* [Google Group](https://groups.google.com/g/netbox-discuss) - Legacy mailing list; slowly being replaced by GitHub discussions
 
 ### Installation
 

base_requirements.txt

@@ -82,6 +82,10 @@ markdown-include
 # https://github.com/squidfunk/mkdocs-material
 mkdocs-material
 
+# Introspection for embedded code
+# https://github.com/mkdocstrings/mkdocstrings
+mkdocstrings
+
 # Library for manipulating IP prefixes and addresses
 # https://github.com/drkjam/netaddr
 netaddr
@@ -94,17 +98,17 @@ Pillow
 # https://github.com/psycopg/psycopg2
 psycopg2-binary
 
-# Extensive cryptographic library (fork of pycrypto)
-# https://github.com/Legrandin/pycryptodome
-pycryptodome
-
 # YAML rendering library
 # https://github.com/yaml/pyyaml
 PyYAML
 
-# In-memory key/value store used for caching and queuing
-# https://github.com/andymccurdy/redis-py
-redis
+# Social authentication framework
+# https://github.com/python-social-auth/social-core
+social-auth-core
+
+# Django app for social-auth-core
+# https://github.com/python-social-auth/social-app-django
+social-auth-app-django
 
 # SVG image rendering (used for rack elevations)
 # https://github.com/mozman/svgwrite
@@ -113,3 +117,7 @@ svgwrite
 # Tabular dataset library (for table-based exports)
 # https://github.com/jazzband/tablib
 tablib
+
+# Timezone data (required by django-timezone-field on Python 3.9+)
+# https://github.com/python/tzdata
+tzdata

docs/additional-features/napalm.md

@@ -29,7 +29,7 @@ GET /api/dcim/devices/1/napalm/?method=get_environment
 
 ## Authentication
 
-By default, the [`NAPALM_USERNAME`](../configuration/optional-settings.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/optional-settings.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers.
+By default, the [`NAPALM_USERNAME`](../configuration/dynamic-settings.md#napalm_username) and [`NAPALM_PASSWORD`](../configuration/dynamic-settings.md#napalm_password) configuration parameters are used for NAPALM authentication. They can be overridden for an individual API call by specifying the `X-NAPALM-Username` and `X-NAPALM-Password` headers.
 
 ```
 $ curl "http://localhost/api/dcim/devices/1/napalm/?method=get_environment" \

docs/additional-features/webhooks.md

@@ -1,86 +1,22 @@
-# Webhooks
+{!models/extras/webhook.md!}
 
-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 managed under Logging > Webhooks.
+## Conditional Webhooks
 
-!!! warning
-    Webhooks support the inclusion of user-submitted code to generate custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
+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":
 
-## Configuration
-
-* **Name** - A unique name for the webhook. The name is not included with outbound messages.
-* **Object type(s)** - The type or types of NetBox object that will trigger the webhook.
-* **Enabled** - If unchecked, the webhook will be inactive.
-* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected.
-* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
-* **URL** - The fuly-qualified URL of the request to be sent. This may specify a destination port number if needed.
-* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`)
-* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below).
-* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.)
-* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
-* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!)
-* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional).
-
-## Jinja2 Template Support
-
-[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands.
-
-For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration:
-
-* Object type: IPAM > IP address
-* HTTP method: `POST`
-* URL: Slack incoming webhook URL
-* HTTP content type: `application/json`
-* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}`
-
-### Available Context
-
-The following data is available as context for Jinja2 templates:
-
-* `event` - The type of event which triggered the webhook: created, updated, or deleted.
-* `model` - The NetBox model which triggered the change.
-* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
-* `username` - The name of the user account associated with the change.
-* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request.
-* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API.
-* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided ass a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed.
-
-### Default Request Body
-
-If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows:
-
-```no-highlight
+```json
 {
-    "event": "created",
-    "timestamp": "2021-03-09 17:55:33.968016+00:00",
-    "model": "site",
-    "username": "jstretch",
-    "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a",
-    "data": {
-        "id": 19,
-        "name": "Site 1",
-        "slug": "site-1",
-        "status": 
-            "value": "active",
-            "label": "Active",
-            "id": 1
-        },
-        "region": null,
-        ...
-    },
-    "snapshots": {
-        "prechange": null,
-        "postchange": {
-            "created": "2021-03-09",
-            "last_updated": "2021-03-09T17:55:33.851Z",
-            "name": "Site 1",
-            "slug": "site-1",
-            "status": "active",
-            ...
-        }
+  "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.

docs/administration/authentication.md

@@ -0,0 +1,37 @@
+# Authentication
+
+## 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.
+
+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.
+
+## Remote Authentication
+
+NetBox may be configured to provide user authenticate via a remote backend in addition to local authentication. This is done by setting the `REMOTE_AUTH_BACKEND` configuration parameter to a suitable backend class. NetBox provides several options for remote authentication.
+
+### LDAP Authentication
+
+```python
+REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend'
+```
+
+NetBox includes an authentication backend which supports LDAP. See the [LDAP installation docs](../installation/6-ldap.md) for more detail about this backend.
+
+### HTTP Header Authentication
+
+```python
+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.
+
+### Single Sign-On (SSO)
+
+```python
+REMOTE_AUTH_BACKEND = 'social_core.backends.google.GoogleOAuth2'
+```
+
+NetBox supports single sign-on authentication via the [python-social-auth](https://github.com/python-social-auth) library. To enable SSO, specify the path to the desired authentication backend within the `social_core` Python package. Please see the complete list of [supported authentication backends](https://github.com/python-social-auth/social-core/tree/master/social_core/backends) for the available options.
+
+Most remote authentication backends require some additional configuration through settings prefixed with `SOCIAL_AUTH_`. These will be automatically imported from NetBox's `configuration.py` file. Additionally, the [authentication pipeline](https://python-social-auth.readthedocs.io/en/latest/pipeline.html) can be customized via the `SOCIAL_AUTH_PIPELINE` parameter.

docs/administration/housekeeping.md

@@ -3,8 +3,15 @@
 NetBox includes a `housekeeping` management command that should be run nightly. This command handles:
 
 * Clearing expired authentication sessions from the database
-* Deleting changelog records older than the configured [retention time](../configuration/optional-settings.md#changelog_retention)
+* Deleting changelog records older than the configured [retention time](../configuration/dynamic-settings.md#changelog_retention)
 
-This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be copied into your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file.
+This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be linked from your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file.
 
-The `housekeeping` command can also be run manually at any time: Running the command outside of scheduled execution times will not interfere with its operation.
+```shell
+sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
+```
+
+!!! note
+    On Debian-based systems, be sure to omit the `.sh` file extension when linking to the script from within a cron directory. Otherwise, the task may not run.
+
+The `housekeeping` command can also be run manually at any time: Running the command outside scheduled execution times will not interfere with its operation.

docs/administration/permissions.md

@@ -1,6 +1,6 @@
 # Permissions
 
-NetBox v2.9 introduced a new object-based permissions framework, which replace's Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
+NetBox v2.9 introduced a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
 
 {!models/users/objectpermission.md!}
 

docs/configuration/dynamic-settings.md

@@ -0,0 +1,196 @@
+# Dynamic Configuration Settings
+
+These configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These setting may also be overridden in `configuration.py`; this will prevent them from being modified via the UI.
+
+---
+
+## ALLOWED_URL_SCHEMES
+
+Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')`
+
+A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all of the default values as well (excluding those schemes which are not desirable).
+
+---
+
+## BANNER_TOP
+
+## BANNER_BOTTOM
+
+Setting these variables will display custom content in a banner at the top and/or bottom of the page, respectively. HTML is allowed. To replicate the content of the top banner in the bottom banner, set:
+
+```python
+BANNER_TOP = 'Your banner text'
+BANNER_BOTTOM = BANNER_TOP
+```
+
+---
+
+## BANNER_LOGIN
+
+This defines custom content to be displayed on the login page above the login form. HTML is allowed.
+
+---
+
+## CHANGELOG_RETENTION
+
+Default: 90
+
+The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain
+changes in the database indefinitely.
+
+!!! warning
+    If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity.
+
+---
+
+## CUSTOM_VALIDATORS
+
+This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below:
+
+```python
+CUSTOM_VALIDATORS = {
+    "dcim.site": [
+        {
+            "name": {
+                "min_length": 5,
+                "max_length": 30
+            }
+        },
+        "my_plugin.validators.Validator1"
+    ],
+    "dim.device": [
+        "my_plugin.validators.Validator1"
+    ]
+}
+```
+
+---
+
+## DEFAULT_USER_PREFERENCES
+
+This is a dictionary defining the default preferences to be set for newly-created user accounts. For example, to set the default page size for all users to 100, define the following:
+
+```python
+DEFAULT_USER_PREFERENCES = {
+    "pagination": {
+        "per_page": 100
+    }
+}
+```
+
+For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`.
+
+---
+
+## ENFORCE_GLOBAL_UNIQUE
+
+Default: False
+
+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.
+
+---
+
+## GRAPHQL_ENABLED
+
+Default: True
+
+Setting this to False will disable the GraphQL API.
+
+---
+
+## MAINTENANCE_MODE
+
+Default: False
+
+Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled.
+
+---
+
+## MAPS_URL
+
+Default: `https://maps.google.com/?q=` (Google Maps)
+
+This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it.
+
+---
+
+## MAX_PAGE_SIZE
+
+Default: 1000
+
+A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`.
+
+---
+
+## NAPALM_USERNAME
+
+## NAPALM_PASSWORD
+
+NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional.
+
+!!! note
+    If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed.
+
+---
+
+## NAPALM_ARGS
+
+A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example:
+
+```python
+NAPALM_ARGS = {
+    'api_key': '472071a93b60a1bd1fafb401d9f8ef41',
+    'port': 2222,
+}
+```
+
+Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument:
+
+```python
+NAPALM_USERNAME = 'username'
+NAPALM_PASSWORD = 'MySecretPassword'
+NAPALM_ARGS = {
+    'secret': NAPALM_PASSWORD,
+    # Include any additional args here
+}
+```
+
+---
+
+## NAPALM_TIMEOUT
+
+Default: 30 seconds
+
+The amount of time (in seconds) to wait for NAPALM to connect to a device.
+
+---
+
+## PAGINATE_COUNT
+
+Default: 50
+
+The default maximum number of objects to display per page within each list of objects.
+
+---
+
+## PREFER_IPV4
+
+Default: False
+
+When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead.
+
+---
+
+## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT
+
+Default: 22
+
+Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`.
+
+---
+
+## RACK_ELEVATION_DEFAULT_UNIT_WIDTH
+
+Default: 220
+
+Default width (in pixels) of a unit within a rack elevation.

docs/configuration/index.md

@@ -1,18 +1,27 @@
 # NetBox Configuration
 
-NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py`. An example configuration is provided as `configuration.example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.
+NetBox's local configuration is stored in `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided as `configuration_example.py`. You may copy or rename the example configuration and make changes as appropriate. NetBox will not run without a configuration file.  While NetBox has many configuration settings, only a few of them must be defined at the time of installation: these are defined under "required settings" below.
 
-While NetBox has many configuration settings, only a few of them must be defined at the time of installation.
+!!! info "Customizing the Configuration Module"
+    A custom configuration module may be specified by setting the `NETBOX_CONFIGURATION` environment variable. This must be a dotted path to the desired Python module. For example, a file named `my_config.py` in the same directory as `settings.py` would be referenced as `netbox.my_config`.
+
+    For the sake of brevity, the NetBox documentation refers to the configuration file simply as `configuration.py`.
+
+Some configuration parameters may alternatively be defined either in `configuration.py` or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI.
 
 ## Configuration Parameters
 
 * [Required settings](required-settings.md)
 * [Optional settings](optional-settings.md)
+* [Dynamic settings](dynamic-settings.md)
+* [Remote authentication settings](remote-authentication.md)
 
 ## Changing the Configuration
 
-Configuration settings may be changed at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before the changes will take effect:
+The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before the changes will take effect:
 
 ```no-highlight
 $ sudo systemctl restart netbox
 ```
+
+Configuration parameters which are set via the admin UI (those listed under "dynamic settings") take effect immediately.

docs/configuration/optional-settings.md

@@ -13,33 +13,23 @@ ADMINS = [
 
 ---
 
-## ALLOWED_URL_SCHEMES
+## AUTH_PASSWORD_VALIDATORS
 
-Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')`
-
-A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all of the default values as well (excluding those schemes which are not desirable).
-
----
-
-## BANNER_TOP
-
-## BANNER_BOTTOM
-
-Setting these variables will display custom content in a banner at the top and/or bottom of the page, respectively. HTML is allowed. To replicate the content of the top banner in the bottom banner, set:
+This parameter acts as a pass-through for configuring Django's built-in password validators for local user accounts. If configured, these will be applied whenever a user's password is updated to ensure that it meets minimum criteria such as length or complexity. An example is provided below. For more detail on the available options, please see [the Django documentation](https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation).
 
 ```python
-BANNER_TOP = 'Your banner text'
-BANNER_BOTTOM = BANNER_TOP
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'OPTIONS': {
+            'min_length': 10,
+        }
+    },
+]
 ```
 
 ---
 
-## BANNER_LOGIN
-
-This defines custom content to be displayed on the login page above the login form. HTML is allowed.
-
----
-
 ## BASE_PATH
 
 Default: None
@@ -52,18 +42,6 @@ BASE_PATH = 'netbox/'
 
 ---
 
-## CHANGELOG_RETENTION
-
-Default: 90
-
-The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain
-changes in the database indefinitely.
-
-!!! warning
-    If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity.
-
----
-
 ## CORS_ORIGIN_ALLOW_ALL
 
 Default: False
@@ -88,18 +66,17 @@ CORS_ORIGIN_WHITELIST = [
 
 ---
 
-## CUSTOM_VALIDATORS
+## CSRF_TRUSTED_ORIGINS
 
-This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below:
+Default: `[]`
+
+Defines a list of trusted origins for unsafe (e.g. `POST`) requests. This is a pass-through to Django's [`CSRF_TRUSTED_ORIGINS`](https://docs.djangoproject.com/en/4.0/ref/settings/#std:setting-CSRF_TRUSTED_ORIGINS) setting. Note that each host listed must specify a scheme (e.g. `http://` or `https://).
 
 ```python
-CUSTOM_VALIDATORS = {
-    'dcim.site': (
-        Validator1,
-        Validator2,
-        Validator3
-    )
-}
+CSRF_TRUSTED_ORIGINS = (
+    'http://netbox.local',
+    'https://netbox.local',
+)
 ```
 
 ---
@@ -168,14 +145,6 @@ Email is sent from NetBox only for critical events or if configured for [logging
 
 ---
 
-## ENFORCE_GLOBAL_UNIQUE
-
-Default: False
-
-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.
-
----
-
 ## EXEMPT_VIEW_PERMISSIONS
 
 Default: Empty list
@@ -203,11 +172,62 @@ EXEMPT_VIEW_PERMISSIONS = ['*']
 
 ---
 
-## GRAPHQL_ENABLED
+## FIELD_CHOICES
 
-Default: True
+Some static choice fields on models can be configured with custom values. This is done by defining `FIELD_CHOICES` as a dictionary mapping model fields to their choices. Each choice in the list must have a database value and a human-friendly label, and may optionally specify a color. (A list of available colors is provided below.)
 
-Setting this to False will disable the GraphQL API.
+The choices provided can either replace the stock choices provided by NetBox, or append to them. To _replace_ the available choices, specify the app, model, and field name separated by dots. For example, the site model would be referenced as `dcim.Site.status`. To _extend_ the available choices, append a plus sign to the end of this string (e.g. `dcim.Site.status+`).
+
+For example, the following configuration would replace the default site status choices with the options Foo, Bar, and Baz:
+
+```python
+FIELD_CHOICES = {
+    'dcim.Site.status': (
+        ('foo', 'Foo', 'red'),
+        ('bar', 'Bar', 'green'),
+        ('baz', 'Baz', 'blue'),
+    )
+}
+```
+
+Appending a plus sign to the field identifier would instead _add_ these choices to the ones already offered:
+
+```python
+FIELD_CHOICES = {
+    'dcim.Site.status+': (
+        ...
+    )
+}
+```
+
+The following model fields support configurable choices:
+
+* `circuits.Circuit.status`
+* `dcim.Device.status`
+* `dcim.PowerFeed.status`
+* `dcim.Rack.status`
+* `dcim.Site.status`
+* `ipam.IPAddress.status`
+* `ipam.IPRange.status`
+* `ipam.Prefix.status`
+* `ipam.VLAN.status`
+* `virtualization.VirtualMachine.status`
+
+The following colors are supported:
+
+* `blue`
+* `indigo`
+* `purple`
+* `pink`
+* `red`
+* `orange`
+* `yellow`
+* `green`
+* `teal`
+* `cyan`
+* `gray`
+* `black`
+* `white`
 
 ---
 
@@ -299,30 +319,6 @@ The lifetime (in seconds) of the authentication cookie issued to a NetBox user u
 
 ---
 
-## MAINTENANCE_MODE
-
-Default: False
-
-Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled.
-
----
-
-## MAPS_URL
-
-Default: `https://maps.google.com/?q=` (Google Maps)
-
-This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it.
-
----
-
-## MAX_PAGE_SIZE
-
-Default: 1000
-
-A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`.
-
----
-
 ## MEDIA_ROOT
 
 Default: $INSTALL_ROOT/netbox/media/
@@ -339,57 +335,6 @@ Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Pr
 
 ---
 
-## NAPALM_USERNAME
-
-## NAPALM_PASSWORD
-
-NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional.
-
-!!! note
-    If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed.
-
----
-
-## NAPALM_ARGS
-
-A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example:
-
-```python
-NAPALM_ARGS = {
-    'api_key': '472071a93b60a1bd1fafb401d9f8ef41',
-    'port': 2222,
-}
-```
-
-Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument:
-
-```python
-NAPALM_USERNAME = 'username'
-NAPALM_PASSWORD = 'MySecretPassword'
-NAPALM_ARGS = {
-    'secret': NAPALM_PASSWORD,
-    # Include any additional args here
-}
-```
-
----
-
-## NAPALM_TIMEOUT
-
-Default: 30 seconds
-
-The amount of time (in seconds) to wait for NAPALM to connect to a device.
-
----
-
-## PAGINATE_COUNT
-
-Default: 50
-
-The default maximum number of objects to display per page within each list of objects.
-
----
-
 ## PLUGINS
 
 Default: Empty
@@ -423,137 +368,6 @@ Note that a plugin must be listed in `PLUGINS` for its configuration to take eff
 
 ---
 
-## PREFER_IPV4
-
-Default: False
-
-When determining the primary IP address for a device, IPv6 is preferred over IPv4 by default. Set this to True to prefer IPv4 instead.
-
----
-
-## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT
-
-Default: 22
-
-Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`.
-
----
-
-## RACK_ELEVATION_DEFAULT_UNIT_WIDTH
-
-Default: 220
-
-Default width (in pixels) of a unit within a rack elevation.
-
----
-
-## REMOTE_AUTH_AUTO_CREATE_USER
-
-Default: `False`
-
-If true, NetBox will automatically create local accounts for users authenticated via a remote service. (Requires `REMOTE_AUTH_ENABLED`.)
-
----
-
-## REMOTE_AUTH_BACKEND
-
-Default: `'netbox.authentication.RemoteUserBackend'`
-
-This is the Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication. NetBox provides two built-in backends (listed below), though custom authentication backends may also be provided by other packages or plugins.
-
-* `netbox.authentication.RemoteUserBackend`
-* `netbox.authentication.LDAPBackend`
-
----
-
-## REMOTE_AUTH_DEFAULT_GROUPS
-
-Default: `[]` (Empty list)
-
-The list of groups to assign a new user account when created using remote authentication. (Requires `REMOTE_AUTH_ENABLED`.)
-
----
-
-## REMOTE_AUTH_DEFAULT_PERMISSIONS
-
-Default: `{}` (Empty dictionary)
-
-A mapping of permissions to assign a new user account when created using remote authentication. Each key in the dictionary should be set to a dictionary of the attributes to be applied to the permission, or `None` to allow all objects. (Requires `REMOTE_AUTH_ENABLED`.)
-
----
-
-## REMOTE_AUTH_ENABLED
-
-Default: `False`
-
-NetBox can be configured to support remote user authentication by inferring user authentication from an HTTP header set by the HTTP reverse proxy (e.g. nginx or Apache). Set this to `True` to enable this functionality. (Local authentication will still take effect as a fallback.)
-
----
-
-## REMOTE_AUTH_GROUP_SYNC_ENABLED
-
-Default: `False`
-
-NetBox can be configured to sync remote user groups by inferring user authentication from an HTTP header set by the HTTP reverse proxy (e.g. nginx or Apache). Set this to `True` to enable this functionality. (Local authentication will still take effect as a fallback.) (Requires `REMOTE_AUTH_ENABLED`.)
-
----
-
-## REMOTE_AUTH_HEADER
-
-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`.)
-
----
-
-## REMOTE_AUTH_GROUP_HEADER
-
-Default: `'HTTP_REMOTE_USER_GROUP'`
-
-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-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
-
----
-
-## REMOTE_AUTH_SUPERUSER_GROUPS
-
-Default: `[]` (Empty list)
-
-The list of groups that promote an remote User to Superuser on Login. If group isn't present on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
-
----
-
-## REMOTE_AUTH_SUPERUSERS
-
-Default: `[]` (Empty list)
-
-The list of users that get promoted to Superuser on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
-
----
-
-## REMOTE_AUTH_STAFF_GROUPS
-
-Default: `[]` (Empty list)
-
-The list of groups that promote an remote User to Staff on Login. If group isn't present on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
-
----
-
-## REMOTE_AUTH_STAFF_USERS
-
-Default: `[]` (Empty list)
-
-The list of users that get promoted to Staff on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
-
----
-
-## REMOTE_AUTH_GROUP_SEPARATOR
-
-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` )
-
----
-
 ## RELEASE_CHECK_URL
 
 Default: None (disabled)

docs/configuration/remote-authentication.md

@@ -0,0 +1,110 @@
+# Remote Authentication Settings
+
+The configuration parameters listed here control remote authentication for NetBox. Note that `REMOTE_AUTH_ENABLED` must be true in order for these settings to take effect.
+
+---
+
+## REMOTE_AUTH_AUTO_CREATE_USER
+
+Default: `False`
+
+If true, NetBox will automatically create local accounts for users authenticated via a remote service. (Requires `REMOTE_AUTH_ENABLED`.)
+
+---
+
+## REMOTE_AUTH_BACKEND
+
+Default: `'netbox.authentication.RemoteUserBackend'`
+
+This is the Python path to the custom [Django authentication backend](https://docs.djangoproject.com/en/stable/topics/auth/customizing/) to use for external user authentication. NetBox provides two built-in backends (listed below), though custom authentication backends may also be provided by other packages or plugins.
+
+* `netbox.authentication.RemoteUserBackend`
+* `netbox.authentication.LDAPBackend`
+
+---
+
+## REMOTE_AUTH_DEFAULT_GROUPS
+
+Default: `[]` (Empty list)
+
+The list of groups to assign a new user account when created using remote authentication. (Requires `REMOTE_AUTH_ENABLED`.)
+
+---
+
+## REMOTE_AUTH_DEFAULT_PERMISSIONS
+
+Default: `{}` (Empty dictionary)
+
+A mapping of permissions to assign a new user account when created using remote authentication. Each key in the dictionary should be set to a dictionary of the attributes to be applied to the permission, or `None` to allow all objects. (Requires `REMOTE_AUTH_ENABLED` as True and `REMOTE_AUTH_GROUP_SYNC_ENABLED` as False.)
+
+---
+
+## REMOTE_AUTH_ENABLED
+
+Default: `False`
+
+NetBox can be configured to support remote user authentication by inferring user authentication from an HTTP header set by the HTTP reverse proxy (e.g. nginx or Apache). Set this to `True` to enable this functionality. (Local authentication will still take effect as a fallback.) (`REMOTE_AUTH_DEFAULT_GROUPS` will not function if `REMOTE_AUTH_ENABLED` is enabled)
+
+---
+
+## REMOTE_AUTH_GROUP_SYNC_ENABLED
+
+Default: `False`
+
+NetBox can be configured to sync remote user groups by inferring user authentication from an HTTP header set by the HTTP reverse proxy (e.g. nginx or Apache). Set this to `True` to enable this functionality. (Local authentication will still take effect as a fallback.) (Requires `REMOTE_AUTH_ENABLED`.)
+
+---
+
+## REMOTE_AUTH_HEADER
+
+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`.)
+
+---
+
+## REMOTE_AUTH_GROUP_HEADER
+
+Default: `'HTTP_REMOTE_USER_GROUP'`
+
+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-Groups` it needs to be set to `HTTP_X_REMOTE_USER_GROUPS`. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+
+---
+
+## REMOTE_AUTH_SUPERUSER_GROUPS
+
+Default: `[]` (Empty list)
+
+The list of groups that promote an remote User to Superuser on Login. If group isn't present on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+
+---
+
+## REMOTE_AUTH_SUPERUSERS
+
+Default: `[]` (Empty list)
+
+The list of users that get promoted to Superuser on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+
+---
+
+## REMOTE_AUTH_STAFF_GROUPS
+
+Default: `[]` (Empty list)
+
+The list of groups that promote an remote User to Staff on Login. If group isn't present on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+
+---
+
+## REMOTE_AUTH_STAFF_USERS
+
+Default: `[]` (Empty list)
+
+The list of users that get promoted to Staff on Login. If user isn't present in list on next Login, the Role gets revoked. (Requires `REMOTE_AUTH_ENABLED` and `REMOTE_AUTH_GROUP_SYNC_ENABLED` )
+
+---
+
+## REMOTE_AUTH_GROUP_SEPARATOR
+
+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` )

docs/configuration/required-settings.md

@@ -25,7 +25,7 @@ ALLOWED_HOSTS = ['*']
 
 ## DATABASE
 
-NetBox requires access to a PostgreSQL 9.6 or later database service to store data. This service can run locally on the NetBox server or on a remote system. The following parameters must be defined within the `DATABASE` dictionary:
+NetBox requires access to a PostgreSQL 10 or later database service to store data. This service can run locally on the NetBox server or on a remote system. The following parameters must be defined within the `DATABASE` dictionary:
 
 * `NAME` - Database name
 * `USER` - PostgreSQL username

docs/core-functionality/contacts.md

@@ -0,0 +1,5 @@
+# Contacts
+
+{!models/tenancy/contact.md!}
+{!models/tenancy/contactgroup.md!}
+{!models/tenancy/contactrole.md!}

docs/core-functionality/device-types.md

@@ -37,4 +37,5 @@ Once component templates have been created, every new device that you create as
 {!models/dcim/interfacetemplate.md!}
 {!models/dcim/frontporttemplate.md!}
 {!models/dcim/rearporttemplate.md!}
+{!models/dcim/modulebaytemplate.md!}
 {!models/dcim/devicebaytemplate.md!}

docs/core-functionality/devices.md

@@ -17,6 +17,7 @@ Device components represent discrete objects within a device which are used to t
 {!models/dcim/interface.md!}
 {!models/dcim/frontport.md!}
 {!models/dcim/rearport.md!}
+{!models/dcim/modulebay.md!}
 {!models/dcim/devicebay.md!}
 {!models/dcim/inventoryitem.md!}
 
@@ -27,3 +28,13 @@ Device components represent discrete objects within a device which are used to t
 ---
 
 {!models/dcim/cable.md!}
+
+In the example below, three individual cables comprise a path between devices A and D:
+
+![Cable path](../media/models/dcim_cable_trace.png)
+
+Traced from Interface 1 on Device A, NetBox will show the following path:
+
+* Cable 1: Interface 1 to Front Port 1
+* Cable 2: Rear Port 1 to Rear Port 2
+* Cable 3: Front Port 2 to Interface 2

docs/core-functionality/ipam.md

@@ -17,3 +17,11 @@
 
 {!models/ipam/vrf.md!}
 {!models/ipam/routetarget.md!}
+
+---
+
+{!models/ipam/fhrpgroup.md!}
+
+---
+
+{!models/ipam/asn.md!}

docs/core-functionality/modules.md

@@ -0,0 +1,4 @@
+# Modules
+
+{!models/dcim/moduletype.md!}
+{!models/dcim/module.md!}

docs/core-functionality/power.md

@@ -5,4 +5,4 @@
 
 # Example Power Topology
 
-![Power distribution model](/media/power_distribution.png)
+![Power distribution model](../media/power_distribution.png)

docs/core-functionality/services.md

@@ -1,3 +1,4 @@
 # Service Mapping
 
+{!models/ipam/servicetemplate.md!}
 {!models/ipam/service.md!}

docs/core-functionality/wireless.md

@@ -0,0 +1,8 @@
+# Wireless Networks
+
+{!models/wireless/wirelesslan.md!}
+{!models/wireless/wirelesslangroup.md!}
+
+---
+
+{!models/wireless/wirelesslink.md!}

docs/customization/custom-fields.md

@@ -1,44 +1,4 @@
-# Custom Fields
-
-Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
-
-However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data.
-
-Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects.
-
-## Creating Custom Fields
-
-Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field:
-
-* Text: Free-form text (up to 255 characters)
-* Integer: A whole number (positive or negative)
-* Boolean: True or false
-* Date: A date in ISO 8601 format (YYYY-MM-DD)
-* URL: This will be presented as a link in the web UI
-* Selection: A selection of one of several pre-defined custom choices
-* Multiple selection: A selection field which supports the assignment of multiple values
-
-Each custom field must have a name; this should be a simple database-friendly string, e.g. `tps_report`. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form.
-
-Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields.
-
-The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely.
-
-A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields.
-
-### Custom Field Validation
-
-NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type:
-
-* Text: Regular expression (optional)
-* Integer: Minimum and/or maximum value (optional)
-* Selection: Must exactly match one of the prescribed choices
-
-### Custom Selection Fields
-
-Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible.
-
-If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected.
+{!models/extras/customfield.md!}
 
 ## Custom Fields in Templates
 

docs/customization/custom-scripts.md

@@ -45,6 +45,20 @@ Defining script variables is optional: You may create a script with only a `run(
 
 Any output generated by the script during its execution will be displayed under the "output" tab in the UI.
 
+By default, scripts within a module are ordered alphabetically in the scripts list page. To return scripts in a specific order, you can define the `script_order` variable at the end of your module. The `script_order` variable is a tuple which contains each Script class in the desired order. Any scripts that are omitted from this list will be listed last.
+
+```python
+from extras.scripts import Script
+
+class MyCustomScript(Script):
+    ...
+
+class AnotherCustomScript(Script):
+    ...
+
+script_order = (MyCustomScript, AnotherCustomScript)
+```
+
 ## Module Attributes
 
 ### `name`
@@ -63,6 +77,10 @@ This is the human-friendly names of your script. If omitted, the class name will
 
 A human-friendly description of what your script does.
 
+### `field_order`
+
+By default, script variables will be ordered in the form as they are defined in the script. `field_order` may be defined as an iterable of field names to determine the order in which variables are rendered. Any fields not included in this iterable be listed last.
+
 ### `commit_default`
 
 The checkbox to commit database changes when executing a script is checked by default. Set `commit_default` to False under the script's Meta class to leave this option unchecked by default.
@@ -226,7 +244,7 @@ An IPv4 or IPv6 network with a mask. Returns a `netaddr.IPNetwork` object. Two a
 !!! note
     To run a custom script, a user must 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.
 
-    ![Adding the run action to a permission](/media/admin_ui_run_permission.png)
+    ![Adding the run action to a permission](../media/admin_ui_run_permission.png)
 
 ### Via the Web UI
 
@@ -245,6 +263,22 @@ http://netbox/api/extras/scripts/example.MyReport/ \
 --data '{"data": {"foo": "somevalue", "bar": 123}, "commit": true}'
 ```
 
+### Via the CLI
+
+Scripts can be run on the CLI by invoking the management command:
+
+```
+python3 manage.py runscript [--commit] [--loglevel {debug,info,warning,error,critical}] [--data "<data>"] <module>.<script> 
+```
+
+The required ``<module>.<script>`` argument is the script to run where ``<module>`` is the name of the python file in the ``scripts`` directory without the ``.py`` extension and ``<script>`` is the name of the script class in the ``<module>`` to run.
+
+The optional ``--data "<data>"`` argument is the data to send to the script
+
+The optional ``--loglevel`` argument is the desired logging level to output to the console.
+
+The optional ``--commit`` argument will commit any changes in the script to the database.
+
 ## Example
 
 Below is an example script that creates new objects for a planned site. The user is prompted for three variables:

docs/customization/custom-validation.md

@@ -1,22 +1,18 @@
 # Custom Validation
 
-NetBox validates every object prior to it being written to the database to ensure data integrity. This validation includes things like checking for proper formatting and that references to related objects are valid. However, you may wish to supplement this validation with some rules of your own. For example, perhaps you require that every site's name conforms to a specific pattern.  This can be done using NetBox's `CustomValidator` class.
+NetBox validates every object prior to it being written to the database to ensure data integrity. This validation includes things like checking for proper formatting and that references to related objects are valid. However, you may wish to supplement this validation with some rules of your own. For example, perhaps you require that every site's name conforms to a specific pattern.  This can be done using custom validation rules.
 
-## CustomValidator
+## Custom Validation Rules
 
-### 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:
 
-A custom validator can be instantiated by passing a mapping of attributes to a set of rules to which that attribute must conform. For example:
-
-```python
-from extras.validators import CustomValidator
-
-CustomValidator({
-    'name': {
-        'min_length': 5,
-        'max_length': 30,
-    }
-})
+```json
+{
+  "name": {
+    "min_length": 5,
+    "max_length": 30
+  }
+}
 ```
 
 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.
@@ -38,12 +34,13 @@ 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. The `CustomValidator` class 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.
 
 ```python
 from extras.validators import CustomValidator
 
 class MyValidator(CustomValidator):
+
     def validate(self, instance):
         if instance.status == 'active' and not instance.description:
             self.fail("Active sites must have a description set!", field='status')
@@ -53,34 +50,69 @@ The `fail()` method may optionally specify a field with which to associate the s
 
 ## Assigning Custom Validators
 
-Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/optional-settings.md#custom_validators) configuration parameter, as such:
+Custom validators are associated with specific NetBox models under the [CUSTOM_VALIDATORS](../configuration/dynamic-settings.md#custom_validators) configuration parameter. There are three manners by which custom validation rules can be defined:
+
+1. Plain JSON mapping (no custom logic)
+2. Dotted path to a custom validator class
+3. Direct reference to a custom validator class
+
+### Plain Data
+
+For cases where custom logic is not needed, it is sufficient to pass validation rules as plain JSON-compatible objects. This approach typically affords the most portability for your configuration. For instance:
+
+```python
+CUSTOM_VALIDATORS = {
+    "dcim.site": [
+        {
+            "name": {
+                "min_length": 5,
+                "max_length": 30,
+            }
+        }
+    ],
+    "dcim.device": [
+        {
+            "platform": {
+                "required": True,
+            }
+        }
+    ]
+}
+```
+
+### Dotted Path
+
+In instances where a custom validator class is needed, it can be referenced by its Python path (relative to NetBox's working directory):
 
 ```python
+CUSTOM_VALIDATORS = {
+    'dcim.site': (
+        'my_validators.Validator1',
+        'my_validators.Validator2',
+    ),
+    'dcim.device': (
+        'my_validators.Validator3',
+    )
+}
+```
+
+### Direct Class Reference
+
+This approach requires each class being instantiated to be imported directly within the Python configuration file.
+
+```python
+from my_validators import Validator1, Validator2, Validator3
+
 CUSTOM_VALIDATORS = {
     'dcim.site': (
         Validator1,
         Validator2,
-        Validator3
+    ),
+    'dcim.device': (
+        Validator3,
     )
 }
 ```
 
 !!! note
     Even if defining only a single validator, it must be passed as an iterable.
-
-When it is not necessary to define a custom `validate()` method, you may opt to pass a `CustomValidator` instance directly:
-
-```python
-from extras.validators import CustomValidator
-
-CUSTOM_VALIDATORS = {
-    'dcim.site': (
-        CustomValidator({
-            'name': {
-                'min_length': 5,
-                'max_length': 30,
-            }
-        }),
-    )
-}
-```

docs/customization/export-templates.md

@@ -1,40 +1,4 @@
-# Export Templates
-
-NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.
-
-Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension.
-
-Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/).
-
-!!! note
-    The name `table` is reserved for internal use.
-
-!!! warning
-    Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users.
-
-The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example:
-
-```jinja2
-{% for rack in queryset %}
-Rack: {{ rack.name }}
-Site: {{ rack.site.name }}
-Height: {{ rack.u_height }}U
-{% endfor %}
-```
-
-To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`.
-
-If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example:
-```
-{% for server in queryset %}
-{% set data = server.get_config_context() %}
-{{ data.syslog }}
-{% endfor %}
-```
-
-The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.)
-
-A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`.
+{!models/extras/exporttemplate.md!}
 
 ## REST API Integration
 

docs/customization/reports.md

@@ -95,7 +95,21 @@ The following methods are available to log results within a report:
 
 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, after a report has been run, extend the `post_run()` method. The status of the report is available as `self.failed` and the results object is `self.result`.
+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. The status of a completed report is available as `self.failed` and the results object is `self.result`.
+
+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.
 

docs/development/adding-models.md

@@ -2,13 +2,13 @@
 
 ## 1. Define the model class
 
-Models within each app are stored in either `models.py` or within a submodule under the `models/` directory. When creating a model, be sure to subclass the [appropriate base model](models.md) from `netbox.models`. This will typically be PrimaryModel or OrganizationalModel. Remember to add the model class to the `__all__` listing for the module.
+Models within each app are stored in either `models.py` or within a submodule under the `models/` directory. When creating a model, be sure to subclass the [appropriate base model](models.md) from `netbox.models`. This will typically be NetBoxModel or OrganizationalModel. Remember to add the model class to the `__all__` listing for the module.
 
 Each model should define, at a minimum:
 
+* A `Meta` class specifying a deterministic ordering (if ordered by fields other than the primary ID)
 * A `__str__()` method returning a user-friendly string representation of the instance
 * A `get_absolute_url()` method returning an instance's direct URL (using `reverse()`)
-* A `Meta` class specifying a deterministic ordering (if ordered by fields other than the primary ID)
 
 ## 2. Define field choices
 
@@ -16,9 +16,9 @@ If the model has one or more fields with static choices, define those choices in
 
 ## 3. Generate database migrations
 
-Once your model definition is complete, generate database migrations by running `manage.py -n $NAME --no-header`. Always specify a short unique name when generating migrations.
+Once your model definition is complete, generate database migrations by running `manage.py makemigrations -n $NAME --no-header`. Always specify a short unique name when generating migrations.
 
-!!! info
+!!! info "Configuration Required"
     Set `DEVELOPER = True` in your NetBox configuration to enable the creation of new migrations.
 
 ## 4. Add all standard views
@@ -37,25 +37,32 @@ Most models will need view classes created in `views.py` to serve the following
 
 Add the relevant URL path for each view created in the previous step to `urls.py`.
 
-## 6. Create the FilterSet
+## 6. Add relevant forms
+
+Depending on the type of model being added, you may need to define several types of form classes. These include:
+
+* A base model form (for creating/editing individual objects)
+* A bulk edit form
+* A bulk import form (for CSV-based import)
+* A filterset form (for filtering the object list view)
+
+## 7. Create the FilterSet
 
 Each model should have a corresponding FilterSet class defined. This is used to filter UI and API queries. Subclass the appropriate class from `netbox.filtersets` that matches the model's parent class.
 
-Every model FilterSet should define a `q` filter to support general search queries.
-
-## 7. Create the table
+## 8. Create the table class
 
 Create a table class for the model in `tables.py` by subclassing `utilities.tables.BaseTable`. Under the table's `Meta` class, be sure to list both the fields and default columns.
 
-## 8. Create the object template
+## 9. Create the object template
 
 Create the HTML template for the object view. (The other views each typically employ a generic template.) This template should extend `generic/object.html`.
 
-## 9. Add the model to the navigation menu
+## 10. Add the model to the navigation menu
 
-For NetBox releases prior to v3.0, add the relevant link(s) to the navigation menu template. For later releases, add the relevant items in `netbox/netbox/navigation_menu.py`.
+Add the relevant navigation menu items in `netbox/netbox/navigation_menu.py`.
 
-## 10. REST API components
+## 11. REST API components
 
 Create the following for each model:
 
@@ -64,13 +71,13 @@ Create the following for each model:
 * API view in `api/views.py`
 * Endpoint route in `api/urls.py`
 
-## 11. GraphQL API components (v3.0+)
+## 12. GraphQL API components
 
 Create a Graphene object type for the model in `graphql/types.py` by subclassing the appropriate class from `netbox.graphql.types`.
 
 Also extend the schema class defined in `graphql/schema.py` with the individual object and object list fields per the established convention.
 
-## 12. Add tests
+## 13. Add tests
 
 Add tests for the following:
 
@@ -78,7 +85,7 @@ Add tests for the following:
 * API views
 * Filter sets
 
-## 13. Documentation
+## 14. Documentation
 
 Create a new documentation page for the model in `docs/models/<app_label>/<model_name>.md`. Include this file under the "features" documentation where appropriate.
 

docs/development/extending-models.md

@@ -4,16 +4,16 @@ Below is a list of tasks to consider when adding a new field to a core model.
 
 ## 1. Generate and run database migrations
 
-Django 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.
+[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 migrate
 ```
 
-Where possible, try to merge related changes into a single migration. For example, if three new fields are being added to different models within an app, these can be expressed in the same migration. You can merge a new migration with an existing one by combining their `operations` lists.
+Where possible, try to merge related changes into a single migration. For example, if three new fields are being added to different models within an app, these can be expressed in a single migration. You can merge a newly generated migration with an existing one by combining their `operations` lists.
 
-!!! note
+!!! 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()`
@@ -24,7 +24,6 @@ If the new field introduces additional validation requirements (beyond what's in
 class Foo(models.Model):
 
     def clean(self):
-
         super().clean()
 
         # Custom validation goes here
@@ -40,9 +39,9 @@ If you're adding a relational field (e.g. `ForeignKey`) and intend to include th
 
 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 field to forms
+## 5. Add fields to forms
 
-Extend any forms to include the new field as appropriate. Common forms include:
+Extend any forms to include the new field(s) as appropriate. These are found under the `forms/` directory within each app. Common forms include:
 
 * **Credit/edit** - Manipulating a single object
 * **Bulk edit** - Performing a change on many objects at once
@@ -51,11 +50,11 @@ Extend any forms to include the new field as appropriate. Common forms include:
 
 ## 6. 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 reference it in the FilterSet's `search()` method.
+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
 
-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.
+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 UI templates
 

docs/development/getting-started.md

@@ -11,17 +11,25 @@ Getting started with NetBox development is pretty straightforward, and should fe
 
 ### Fork the Repo
 
-Assuming you'll be working on your own fork, your first step will be to fork the [official git repository](https://github.com/netbox-community/netbox). (If you're a maintainer who's going to be working directly with the official repo, skip this step.) You can then clone your GitHub fork locally for development:
+Assuming you'll be working on your own fork, your first step will be to fork the [official git repository](https://github.com/netbox-community/netbox). (If you're a maintainer who's going to be working directly with the official repo, skip this step.) Click the "fork" button at top right (be sure that you've logged into GitHub first).
+
+![GitHub fork button](../media/development/github_fork_button.png)
+
+Copy the URL provided in the dialog box.
+
+![GitHub fork dialog](../media/development/github_fork_dialog.png)
+
+You can then clone your GitHub fork locally for development:
 
 ```no-highlight
-$ git clone https://github.com/youruseraccount/netbox.git
+$ git clone https://github.com/$username/netbox.git
 Cloning into 'netbox'...
-remote: Enumerating objects: 231, done.
-remote: Counting objects: 100% (231/231), done.
-remote: Compressing objects: 100% (147/147), done.
-remote: Total 56705 (delta 134), reused 145 (delta 84), pack-reused 56474
-Receiving objects: 100% (56705/56705), 27.96 MiB | 34.92 MiB/s, done.
-Resolving deltas: 100% (44177/44177), done.
+remote: Enumerating objects: 85949, done.
+remote: Counting objects: 100% (4672/4672), done.
+remote: Compressing objects: 100% (1224/1224), done.
+remote: Total 85949 (delta 3538), reused 4332 (delta 3438), pack-reused 81277
+Receiving objects: 100% (85949/85949), 55.16 MiB | 44.90 MiB/s, done.
+Resolving deltas: 100% (68008/68008), done.
 $ ls netbox/
 base_requirements.txt  contrib          docs         mkdocs.yml  NOTICE     requirements.txt  upgrade.sh
 CHANGELOG.md           CONTRIBUTING.md  LICENSE.txt  netbox      README.md  scripts
@@ -33,7 +41,9 @@ The NetBox project utilizes three persistent git branches to track work:
 * `develop` - All development on the upcoming stable release occurs here
 * `feature` - Tracks work on an upcoming major release
 
-Typically, you'll base pull requests off of the `develop` branch, or off of `feature` if you're working on a new major release. **Never** merge pull requests into the `master` branch, which receives merged only from the `develop` branch.
+Typically, you'll base pull requests off of the `develop` branch, or off of `feature` if you're working on a new major release. **Never** merge pull requests into the `master` branch: This branch only ever merges pull requests from the `develop` branch, to effect a new release.
+
+For example, assume that the current NetBox release is v3.1.1. Work applied to the `develop` branch will appear in v3.1.2, and work done under the `feature` branch will be included in the next minor release (v3.2.0).
 
 ### Enable Pre-Commit Hooks
 
@@ -46,7 +56,7 @@ $ ln -s ../../scripts/git-hooks/pre-commit
 
 ### Create a Python Virtual Environment
 
-A [virtual environment](https://docs.python.org/3/tutorial/venv.html) is like a container for a set of Python packages. They allow you to build environments suited to specific projects without interfering with system packages or other projects. When installed per the documentation, NetBox uses a virtual environment in production.
+A [virtual environment](https://docs.python.org/3/tutorial/venv.html) (or "venv" for short) is like a container for a set of Python packages. These allow you to build environments suited to specific projects without interfering with system packages or other projects. When installed per the documentation, NetBox uses a virtual environment in production.
 
 Create a virtual environment using the `venv` Python module:
 
@@ -57,8 +67,8 @@ $ python3 -m venv ~/.venv/netbox
 
 This will create a directory named `.venv/netbox/` in your home directory, which houses a virtual copy of the Python executable and its related libraries and tooling. When running NetBox for development, it will be run using the Python binary at `~/.venv/netbox/bin/python`.
 
-!!! info
-    Keeping virtual environments in `~/.venv/` is a common convention but entirely optional: Virtual environments can be created wherever you please.
+!!! info "Where to Create Your Virtual Environments"
+    Keeping virtual environments in `~/.venv/` is a common convention but entirely optional: Virtual environments can be created almost wherever you please. Also consider using [`virtualenvwrapper`](https://virtualenvwrapper.readthedocs.io/en/stable/) to simplify the management of multiple venvs.
 
 Once created, activate the virtual environment:
 
@@ -83,7 +93,7 @@ Collecting Django==3.1 (from -r requirements.txt (line 1))
 
 ### Configure NetBox
 
-Within the `netbox/netbox/` directory, copy `configuration.example.py` to `configuration.py` and update the following parameters:
+Within the `netbox/netbox/` directory, copy `configuration_example.py` to `configuration.py` and update the following parameters:
 
 * `ALLOWED_HOSTS`: This can be set to `['*']` for development purposes
 * `DATABASE`: PostgreSQL database connection parameters
@@ -94,38 +104,66 @@ Within the `netbox/netbox/` directory, copy `configuration.example.py` to `confi
 
 ### Start the Development Server
 
-Django provides a lightweight, auto-updating HTTP/WSGI server for development use. NetBox extends this slightly to automatically import models and other utilities. Run the NetBox development server with the `nbshell` management command:
+Django provides a lightweight, auto-updating HTTP/WSGI server for development use. It is started with the `runserver` management command:
 
 ```no-highlight
-$ python netbox/manage.py runserver
+$ ./manage.py runserver
+Watching for file changes with StatReloader
 Performing system checks...
 
 System check identified no issues (0 silenced).
-November 18, 2020 - 15:52:31
-Django version 3.1, using settings 'netbox.settings'
+February 18, 2022 - 20:29:57
+Django version 4.0.2, using settings 'netbox.settings'
 Starting development server at http://127.0.0.1:8000/
 Quit the server with CONTROL-C.
 ```
 
 This ensures that your development environment is now complete and operational. Any changes you make to the code base will be automatically adapted by the development server.
 
+!!! info "IDE Integration"
+    Some IDEs, such as PyCharm, will integrate with Django's development server and allow you to run it directly within the IDE. This is strongly encouraged as it makes for a much more convenient development environment.
+
+## Populating Demo Data
+
+Once you have your development environment up and running, it might be helpful to populate some "dummy" data to make interacting with the UI and APIs more convenient. Check out the [netbox-demo-data](https://github.com/netbox-community/netbox-demo-data) repo on GitHub, which houses a collection of sample data that can be easily imported to any new NetBox deployment. (This sample data is used to populate the public demo instance at <https://demo.netbox.dev>.)
+
+The demo data is provided in JSON format and loaded into an empty database using Django's `loaddata` management command. Consult the demo data repo's `README` file for complete instructions on populating the data.
+
 ## Running Tests
 
-Throughout the course of development, it's a good idea to occasionally run NetBox's test suite to catch any potential errors. Tests are run using the `test` management command:
+Prior to committing any substantial changes to the code base, be sure to run NetBox's test suite to catch any potential errors. Tests are run using the `test` management command, which employs Python's [`unittest`](https://docs.python.org/3/library/unittest.html#module-unittest) library. Remember to ensure the Python virtual environment is active before running this command. Also keep in mind that these commands are executed in the `netbox/` directory, not the root directory of the repository.
+
+To avoid potential issues with your local configuration file, set the `NETBOX_CONFIGURATION` to point to the packaged test configuration at `netbox/configuration_testing.py`. This will handle things like ensuring that the dummy plugin is enabled for comprehensive testing.
 
 ```no-highlight
-$ python netbox/manage.py test
+$ export NETBOX_CONFIGURATION=netbox.configuration_testing
+$ cd netbox/
+$ python manage.py test
 ```
 
-In cases where you haven't made any changes to the database (which is most of the time), you can append the `--keepdb` argument to this command to reuse the test database between runs. This cuts down on the time it takes to run the test suite since the database doesn't have to be rebuilt each time. (Note that this argument will cause errors if you've modified any model fields since the previous test run.)
+In cases where you haven't made any changes to the database schema (which is typical), you can append the `--keepdb` argument to this command to reuse the test database between runs. This cuts down on the time it takes to run the test suite since the database doesn't have to be rebuilt each time. (Note that this argument will cause errors if you've modified any model fields since the previous test run.)
 
 ```no-highlight
-$ python netbox/manage.py test --keepdb
+$ python manage.py test --keepdb
 ```
 
+You can also reduce testing time by enabling parallel test execution with the `--parallel` flag. (By default, this will run as many parallel tests as you have processors. To avoid sluggishness, it's a good idea to specify a lower number of parallel tests.) This flag can be combined with `--keepdb`, although if you encounter any strange errors, try running the test suite again with parallelization disabled.
+
+```no-highlight
+$ python manage.py test --parallel <n>
+```
+
+Finally, it's possible to limit the run to a specific set of tests, specified by their Python path. For example, to run only IPAM and DCIM view tests:
+
+```no-highlight
+$ python manage.py test dcim.tests.test_views ipam.tests.test_views
+```
+
+This is handy for instances where just a few tests are failing and you want to re-run them individually.
+
 ## Submitting Pull Requests
 
-Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. When working on a specific issue, be sure to reference it.
+Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. When working on a specific issue, be sure to prefix your commit message with the word "Fixes" or "Closes" and the issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged.
 
 ```no-highlight
 $ git commit -m "Closes #1234: Add IPv5 support"
@@ -136,5 +174,5 @@ Once your fork has the new commit, submit a [pull request](https://github.com/ne
 
 Once submitted, a maintainer will review your pull request and either merge it or request changes. If changes are needed, you can make them via new commits to your fork: The pull request will update automatically.
 
-!!! note
-    Remember, pull requests are entertained only for **accepted** issues. If an issue you want to work on hasn't been approved by a maintainer yet, it's best to avoid risking your time and effort on a change that might not be accepted.
+!!! note "Remember to Open an Issue First"
+    Remember, pull requests are permitted only for **accepted** issues. If an issue you want to work on hasn't been approved by a maintainer yet, it's best to avoid risking your time and effort on a change that might not be accepted. (The one exception to this is trivial changes to the documentation or other non-critical resources.)

docs/development/index.md

@@ -1,25 +1,24 @@
 # NetBox Development
 
-NetBox is maintained as a [GitHub project](https://github.com/netbox-community/netbox) under the Apache 2 license. Users are encouraged to submit GitHub issues for feature requests and bug reports, however we are very selective about pull requests. Please see the `CONTRIBUTING` guide for more direction on contributing to NetBox.
+NetBox is maintained as a [GitHub project](https://github.com/netbox-community/netbox) under the Apache 2 license. Users are encouraged to submit GitHub issues for feature requests and bug reports, however we are very selective about pull requests. Each pull request must be preceded by an **approved** issue. Please see the `CONTRIBUTING` guide for more direction on contributing to NetBox.
 
 ## Communication
 
 There are several official forums for communication among the developers and community members:
 
-* [GitHub issues](https://github.com/netbox-community/netbox/issues) - All feature requests, bug reports, and other substantial changes to the code base **must** be documented in an issue.
-* [GitHub Discussions](https://github.com/netbox-community/netbox/discussions) - The preferred forum for general discussion and support issues. Ideal for shaping a feature request prior to submitting an issue.
+* [GitHub issues](https://github.com/netbox-community/netbox/issues) - All feature requests, bug reports, and other substantial changes to the code base **must** be documented in a GitHub issue.
+* [GitHub discussions](https://github.com/netbox-community/netbox/discussions) - The preferred forum for general discussion and support issues. Ideal for shaping a feature request prior to submitting an issue.
 * [#netbox on NetDev Community Slack](https://netdev.chat/) - Good for quick chats. Avoid any discussion that might need to be referenced later on, as the chat history is not retained long.
-* [Google Group](https://groups.google.com/g/netbox-discuss) - Legacy mailing list; slowly being phased out in favor of GitHub discussions.
 
 ## Governance
 
-NetBox follows the [benevolent dictator](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) model of governance, with [Jeremy Stretch](https://github.com/jeremystretch) ultimately responsible for all changes to the code base. While community contributions are welcomed and encouraged, the lead maintainer's primary role is to ensure the project's long-term maintainability and continued focus on its primary functions (in other words, avoid scope creep).
+NetBox follows the [benevolent dictator](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) model of governance, with [Jeremy Stretch](https://github.com/jeremystretch) ultimately responsible for all changes to the code base. While community contributions are welcomed and encouraged, the lead maintainer's primary role is to ensure the project's long-term maintainability and continued focus on its primary functions.
 
 ## Project Structure
 
-All development of the current NetBox release occurs in the `develop` branch; releases are packaged from the `master` branch. The `master` branch should _always_ represent the current stable release in its entirety, such that installing NetBox by either downloading a packaged release or cloning the `master` branch provides the same code base.
+All development of the current NetBox release occurs in the `develop` branch; releases are packaged from the `master` branch. The `master` branch should _always_ represent the current stable release in its entirety, such that installing NetBox by either downloading a packaged release or cloning the `master` branch provides the same code base. Only pull requests representing new releases should be merged into `master`.
 
-NetBox components are arranged into functional subsections called _apps_ (a carryover from Django vernacular). Each app holds the models, views, and templates relevant to a particular function:
+NetBox components are arranged into Django apps. Each app holds the models, views, and other resources relevant to a particular function:
 
 * `circuits`: Communications circuits and providers (not to be confused with power circuits)
 * `dcim`: Datacenter infrastructure management (sites, racks, and devices)
@@ -29,3 +28,6 @@ NetBox components are arranged into functional subsections called _apps_ (a carr
 * `users`: Authentication and user preferences
 * `utilities`: Resources which are not user-facing (extendable classes, etc.)
 * `virtualization`: Virtual machines and clusters
+* `wireless`: Wireless links and LANs
+
+All core functionality is stored within the `netbox/` subdirectory. HTML templates are stored in a common `templates/` directory, with model- and view-specific templates arranged by app. Documentation is kept in the `docs/` root directory.

docs/development/models.md

@@ -17,12 +17,12 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 * Nesting - These models can be nested recursively to create a hierarchy
 
 | Type               | Change Logging   | Webhooks         | Custom Fields    | Export Templates | Tags             | Journaling       | Nesting          |
-| ------------------ | ---------------- | ---------------- | ---------------- | ---------------- | ---------------- | ---------------- | ---------------- |
+| ------------------ | ---------------- | ---------------- |------------------| ---------------- | ---------------- | ---------------- | ---------------- |
 | Primary            | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |
-| Organizational     | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  |                  |
-| Nested Group       | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  | :material-check: |
+| Organizational     | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  |
+| Nested Group       | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  | :material-check: |
 | Component          | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: |                  |                  |
-| Component Template | :material-check: | :material-check: | :material-check: |                  |                  |                  |                  |
+| Component Template | :material-check: | :material-check: |                  |                  |                  |                  |                  |
 
 ## Models Index
 
@@ -41,15 +41,21 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 * [dcim.Site](../models/dcim/site.md)
 * [dcim.VirtualChassis](../models/dcim/virtualchassis.md)
 * [ipam.Aggregate](../models/ipam/aggregate.md)
+* [ipam.ASN](../models/ipam/asn.md)
+* [ipam.FHRPGroup](../models/ipam/fhrpgroup.md)
 * [ipam.IPAddress](../models/ipam/ipaddress.md)
+* [ipam.IPRange](../models/ipam/iprange.md)
 * [ipam.Prefix](../models/ipam/prefix.md)
 * [ipam.RouteTarget](../models/ipam/routetarget.md)
 * [ipam.Service](../models/ipam/service.md)
 * [ipam.VLAN](../models/ipam/vlan.md)
 * [ipam.VRF](../models/ipam/vrf.md)
+* [tenancy.Contact](../models/tenancy/contact.md)
 * [tenancy.Tenant](../models/tenancy/tenant.md)
 * [virtualization.Cluster](../models/virtualization/cluster.md)
 * [virtualization.VirtualMachine](../models/virtualization/virtualmachine.md)
+* [wireless.WirelessLAN](../models/wireless/wirelesslan.md)
+* [wireless.WirelessLink](../models/wireless/wirelesslink.md)
 
 ### Organizational Models
 
@@ -61,6 +67,7 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 * [ipam.RIR](../models/ipam/rir.md)
 * [ipam.Role](../models/ipam/role.md)
 * [ipam.VLANGroup](../models/ipam/vlangroup.md)
+* [tenancy.ContactRole](../models/tenancy/contactrole.md)
 * [virtualization.ClusterGroup](../models/virtualization/clustergroup.md)
 * [virtualization.ClusterType](../models/virtualization/clustertype.md)
 
@@ -69,7 +76,9 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 * [dcim.Location](../models/dcim/location.md) (formerly RackGroup)
 * [dcim.Region](../models/dcim/region.md)
 * [dcim.SiteGroup](../models/dcim/sitegroup.md)
+* [tenancy.ContactGroup](../models/tenancy/contactgroup.md)
 * [tenancy.TenantGroup](../models/tenancy/tenantgroup.md)
+* [wireless.WirelessLANGroup](../models/wireless/wirelesslangroup.md)
 
 ### Component Models
 

docs/development/release-checklist.md

@@ -8,7 +8,7 @@ Check `base_requirements.txt` for any dependencies pinned to a specific version,
 
 ### Link to the Release Notes Page
 
-Add the release notes (`/docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and point `index.md` to the new file.
+Add the release notes (`/docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and add a summary of the major changes to `index.md`.
 
 ### Manually Perform a New Install
 

docs/development/style-guide.md

@@ -1,6 +1,6 @@
 # Style Guide
 
-NetBox generally follows the [Django style guide](https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/), which is itself based on [PEP 8](https://www.python.org/dev/peps/pep-0008/). [Pycodestyle](https://github.com/pycqa/pycodestyle) is used to validate code formatting, ignoring certain violations. See `scripts/cibuild.sh`.
+NetBox generally follows the [Django style guide](https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/), which is itself based on [PEP 8](https://www.python.org/dev/peps/pep-0008/). [Pycodestyle](https://github.com/pycqa/pycodestyle) is used to validate code formatting, ignoring certain violations. See `scripts/cibuild.sh` for details.
 
 ## PEP 8 Exceptions
 
@@ -30,7 +30,7 @@ pycodestyle --ignore=W504,E501 netbox/
 
 ## Introducing New Dependencies
 
-The introduction of a new dependency is best avoided unless it is absolutely necessary. For small features, it's generally preferable to replicate functionality within the NetBox code base rather than to introduce reliance on an external project. This reduces both the burden of tracking new releases and our exposure to outside bugs and attacks.
+The introduction of a new dependency is best avoided unless it is absolutely necessary. For small features, it's generally preferable to replicate functionality within the NetBox code base rather than to introduce reliance on an external project. This reduces both the burden of tracking new releases and our exposure to outside bugs and supply chain attacks.
 
 If there's a strong case for introducing a new dependency, it must meet the following criteria:
 
@@ -43,7 +43,7 @@ When adding a new dependency, a short description of the package and the URL of
 
 ## General Guidance
 
-* When in doubt, remain consistent: It is better to be consistently incorrect than inconsistently correct. If you notice in the course of unrelated work a pattern that should be corrected, continue to follow the pattern for now and open a bug so that the entire code base can be evaluated at a later point.
+* When in doubt, remain consistent: It is better to be consistently incorrect than inconsistently correct. If you notice in the course of unrelated work a pattern that should be corrected, continue to follow the pattern for now and submit a separate bug report so that the entire code base can be evaluated at a later point.
 
 * Prioritize readability over concision. Python is a very flexible language that typically offers several options for expressing a given piece of logic, but some may be more friendly to the reader than others. (List comprehensions are particularly vulnerable to over-optimization.) Always remain considerate of the future reader who may need to interpret your code without the benefit of the context within which you are writing it.
 

docs/development/user-preferences.md

@@ -4,8 +4,11 @@ The `users.UserConfig` model holds individual preferences for each user in the f
 
 ## Available Preferences
 
-| Name | Description |
-| ---- | ----------- |
-| extras.configcontext.format | Preferred format when rendering config context data (JSON or YAML) |
-| pagination.per_page | The number of items to display per page of a paginated table |
-| tables.TABLE_NAME.columns | The ordered list of columns to display when viewing the table |
+| Name                     | Description                                                   |
+|--------------------------|---------------------------------------------------------------|
+| data_format              | Preferred format when rendering raw data (JSON or YAML)       |
+| pagination.per_page      | The number of items to display per page of a paginated table  |
+| 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/graphql-api/overview.md

@@ -67,4 +67,4 @@ Authorization: Token $TOKEN
 
 ## Disabling the GraphQL API
 
-If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/optional-settings.md#graphql_enabled) configuration parameter to False and restarting NetBox.
+If not needed, the GraphQL API can be disabled by setting the [`GRAPHQL_ENABLED`](../configuration/dynamic-settings.md#graphql_enabled) configuration parameter to False and restarting NetBox.

docs/index.md

@@ -1,5 +1,7 @@
 ![NetBox](netbox_logo.svg "NetBox logo"){style="height: 100px; margin-bottom: 3em"}
 
+:loudspeaker: The **[2022 NetBox community survey](https://forms.gle/KR8YbR8GiJ9EYXM28)** is now open! We collect this feedback and demographic data from NetBox users around the world to help shape the project's long-term development goals. Please take a few minutes to share your responses!
+
 # What is NetBox?
 
 NetBox is an infrastructure resource modeling (IRM) application designed to empower network automation. Initially conceived by the network engineering team at [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically to address the needs of network and infrastructure engineers. NetBox is made available as open source under the Apache 2 license. It encompasses the following aspects of network management:
@@ -48,14 +50,16 @@ NetBox is built on the [Django](https://djangoproject.com/) Python framework and
 | HTTP service       | nginx or Apache   |
 | WSGI service       | gunicorn or uWSGI |
 | Application        | Django/Python     |
-| Database           | PostgreSQL 9.6+   |
+| Database           | PostgreSQL 10+    |
 | Task queuing       | Redis/django-rq   |
-| Live device access | NAPALM            |
+| Live device access | NAPALM (optional) |
 
 ## Supported Python Versions
 
-NetBox supports Python 3.7, 3.8, and 3.9 environments currently. (Support for Python 3.6 was removed in NetBox v3.0.)
+NetBox supports Python 3.8, 3.9, and 3.10 environments.
 
 ## Getting Started
 
-See the [installation guide](installation/index.md) for help getting NetBox up and running quickly.
+Minor NetBox releases (e.g. v3.1) are published three times a year; in April, August, and December. These typically introduce major new features and may contain breaking API changes. Patch releases are published roughly every one to two weeks to resolve bugs and fulfill minor feature requests. These are backward-compatible with previous releases unless otherwise noted. The NetBox maintainers strongly recommend running the latest stable release whenever possible.
+
+Please see the [official installation guide](installation/index.md) for detailed instructions on obtaining and installing NetBox.

docs/installation/1-postgresql.md

@@ -2,8 +2,8 @@
 
 This section entails the installation and configuration of a local PostgreSQL database. If you already have a PostgreSQL database service in place, skip to [the next section](2-redis.md).
 
-!!! warning
-    NetBox requires PostgreSQL 9.6 or higher. Please note that MySQL and other relational databases are **not** currently supported.
+!!! warning "PostgreSQL 10 or later required"
+    NetBox requires PostgreSQL 10 or later. Please note that MySQL and other relational databases are **not** supported.
 
 ## Installation
 
@@ -21,9 +21,6 @@ This section entails the installation and configuration of a local PostgreSQL da
     sudo postgresql-setup --initdb
     ```
 
-    !!! info
-        PostgreSQL 9.6 and later are available natively on CentOS 8.2. If using an earlier CentOS release, you may need to [install it from an RPM](https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/).
-
     CentOS configures ident host-based authentication for PostgreSQL by default. Because NetBox will need to authenticate using a username and password, modify `/var/lib/pgsql/data/pg_hba.conf` to support MD5 authentication by changing `ident` to `md5` for the lines below:
 
     ```no-highlight
@@ -38,6 +35,12 @@ sudo systemctl start postgresql
 sudo systemctl enable postgresql
 ```
 
+Before continuing, verify that you have installed PostgreSQL 10 or later:
+
+```no-highlight
+psql -V
+```
+
 ## Database Creation
 
 At a minimum, we need to create a database for NetBox and assign it a username and password for authentication. Start by invoking the PostgreSQL shell as the system Postgres user.
@@ -54,7 +57,7 @@ CREATE USER netbox WITH PASSWORD 'J5brHrAXFLQSif0K';
 GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
 ```
 
-!!! danger
+!!! danger "Use a strong password"
     **Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation.
 
 Once complete, enter `\q` to exit the PostgreSQL shell.

docs/installation/2-redis.md

@@ -4,7 +4,7 @@
 
 [Redis](https://redis.io/) is an in-memory key-value store which NetBox employs for caching and queuing. This section entails the installation and configuration of a local Redis instance. If you already have a Redis service in place, skip to [the next section](3-netbox.md).
 
-!!! note
+!!! warning "Redis v4.0 or later required"
     NetBox v2.9.0 and later require Redis v4.0 or higher. If your distribution does not offer a recent enough release, you will need to build Redis from source. Please see [the Redis installation documentation](https://github.com/redis/redis) for further details.
 
 === "Ubuntu"
@@ -21,6 +21,12 @@
     sudo systemctl enable redis
     ```
 
+Before continuing, verify that your installed version of Redis is at least v4.0:
+
+```no-highlight
+redis-server -v
+```
+
 You may wish to modify the Redis configuration at `/etc/redis.conf` or `/etc/redis/redis.conf`, however in most cases the default configuration is sufficient.
 
 ## Verify Service Status

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.
 
-!!! note
-    NetBox v3.0 and later require Python 3.7, 3.8, or 3.9.
+!!! warning "Python 3.8 or later required"
+    NetBox v3.2 requires Python 3.8, 3.9, or 3.10.
 
 === "Ubuntu"
 
@@ -18,13 +18,13 @@ Begin by installing all system packages required by NetBox and its dependencies.
 === "CentOS"
 
     ```no-highlight
-    sudo yum install -y gcc python36 python36-devel python3-pip libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config
+    sudo yum install -y gcc libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config
     ```
 
-Before continuing with either platform, update pip (Python's package management tool) to its latest release:
+Before continuing, check that your installed Python version is at least 3.8:
 
 ```no-highlight
-sudo pip3 install --upgrade pip
+python3 -V
 ```
 
 ## Download NetBox
@@ -89,7 +89,7 @@ Resolving deltas: 100% (148/148), done.
 ```
 
 !!! note
-    Installation via git also allows you to easily try out development versions of NetBox. The `develop` branch contains all work underway for the next minor release, and the `feature` branch tracks progress on the next major release. 
+    Installation via git also allows you to easily try out different versions of NetBox. To check out a [specific NetBox release](https://github.com/netbox-community/netbox/releases), use the `git checkout` command with the desired release tag. For example, `git checkout v3.0.8`.
 
 ## Create the NetBox System User
 
@@ -112,11 +112,11 @@ Create a system user account named `netbox`. We'll configure the WSGI and HTTP s
 
 ## Configuration
 
-Move into the NetBox configuration directory and make a copy of `configuration.example.py` named `configuration.py`. This file will hold all of your local configuration parameters.
+Move into the NetBox configuration directory and make a copy of `configuration_example.py` named `configuration.py`. This file will hold all of your local configuration parameters.
 
 ```no-highlight
 cd /opt/netbox/netbox/netbox/
-sudo cp configuration.example.py configuration.py
+sudo cp configuration_example.py configuration.py
 ```
 
 Open `configuration.py` with your preferred editor to begin configuring NetBox. NetBox offers [many configuration parameters](../configuration/index.md), but only the following four are required for new installations:
@@ -190,7 +190,7 @@ A simple Python script named `generate_secret_key.py` is provided in the parent
 python3 ../generate_secret_key.py
 ```
 
-!!! warning
+!!! warning "SECRET_KEY values must match"
     In the case of a highly available installation with multiple web servers, `SECRET_KEY` must be identical among all servers in order to maintain a persistent user session state.
 
 When you have finished modifying the configuration, remember to save the file.
@@ -229,10 +229,10 @@ Once NetBox has been configured, we're ready to proceed with the actual installa
 sudo /opt/netbox/upgrade.sh
 ```
 
-Note that **Python 3.7 or later is required** for NetBox v3.0 and later releases. If the default Python installation on your server does not meet this requirement, you'll need to install Python 3.7 or later separately, and pass the path to the support installation as an environment variable named `PYTHON`. (Note that the environment variable must be passed _after_ the `sudo` command.)
+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.)
 
 ```no-highlight
-sudo PYTHON=/usr/bin/python3.7 /opt/netbox/upgrade.sh
+sudo PYTHON=/usr/bin/python3.8 /opt/netbox/upgrade.sh
 ```
 
 !!! note
@@ -259,10 +259,10 @@ python3 manage.py createsuperuser
 
 NetBox includes a `housekeeping` management command that handles some recurring cleanup tasks, such as clearing out old sessions and expired change records. Although this command may be run manually, it is recommended to configure a scheduled job using the system's `cron` daemon or a similar utility.
 
-A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be copied to your system's daily cron task directory, or included within the crontab directly. (If installing NetBox into a nonstandard path, be sure to update the system paths within this script first.)
+A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be copied to or linked from your system's daily cron task directory, or included within the crontab directly. (If installing NetBox into a nonstandard path, be sure to update the system paths within this script first.)
 
 ```shell
-cp /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/
+sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
 ```
 
 See the [housekeeping documentation](../administration/housekeeping.md) for further details.
@@ -297,7 +297,7 @@ Next, connect to the name or IP of the server (as defined in `ALLOWED_HOSTS`) on
     firewall-cmd --zone=public --add-port=8000/tcp
     ```
 
-!!! danger
+!!! danger "Not for production use"
     The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. **Do not use it in production.**
 
 !!! warning

docs/installation/6-ldap.md

@@ -152,7 +152,7 @@ LOGGING = {
         'netbox_auth_log': {
             'level': 'DEBUG',
             'class': 'logging.handlers.RotatingFileHandler',
-            'filename': '/opt/netbox/logs/django-ldap-debug.log',
+            'filename': '/opt/netbox/local/logs/django-ldap-debug.log',
             'maxBytes': 1024 * 500,
             'backupCount': 5,
         },

docs/installation/index.md

@@ -1,6 +1,6 @@
 # Installation
 
-The installation instructions provided here have been tested to work on Ubuntu 20.04 and CentOS 8.2. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
+The installation instructions provided here have been tested to work on Ubuntu 20.04 and CentOS 8.3. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
 
 The following sections detail how to set up a new instance of NetBox:
 
@@ -11,16 +11,12 @@ The following sections detail how to set up a new instance of NetBox:
 5. [HTTP server](5-http-server.md)
 6. [LDAP authentication](6-ldap.md) (optional)
 
-The video below demonstrates the installation of NetBox v2.10.3 on Ubuntu 20.04 for your reference.
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/7Fpd2-q9_28" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
 ## Requirements
 
 | Dependency | Minimum Version |
 |------------|-----------------|
-| Python     | 3.7             |
-| PostgreSQL | 9.6             |
+| Python     | 3.8             |
+| PostgreSQL | 10              |
 | Redis      | 4.0             |
 
 Below is a simplified overview of the NetBox application stack for reference:

docs/installation/upgrading.md

@@ -10,8 +10,8 @@ NetBox v3.0 and later requires the following:
 
 | Dependency | Minimum Version |
 |------------|-----------------|
-| Python     | 3.7             |
-| PostgreSQL | 9.6             |
+| Python     | 3.8             |
+| PostgreSQL | 10              |
 | Redis      | 4.0             |
 
 ## Install the Latest Release
@@ -76,10 +76,10 @@ sudo ./upgrade.sh
 ```
 
 !!! warning
-    If the default version of Python is not at least 3.7, 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.8, 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.7 ./upgrade.sh
+    sudo PYTHON=/usr/bin/python3.8 ./upgrade.sh
     ```
 
 This script performs the following actions:
@@ -111,10 +111,10 @@ sudo systemctl restart netbox netbox-rq
 
 ## Verify Housekeeping Scheduling
 
-If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled process) has been configured to run NetBox's nightly housekeeping command. A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be copied to your system's daily cron task directory, or included within the crontab directly. (If NetBox has been installed in a nonstandard path, be sure to update the system paths within this script first.)
+If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled process) has been configured to run NetBox's nightly housekeeping command. A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be linked from your system's daily cron task directory, or included within the crontab directly. (If NetBox has been installed in a nonstandard path, be sure to update the system paths within this script first.)
 
 ```shell
-cp /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/
+sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
 ```
 
 See the [housekeeping documentation](../administration/housekeeping.md) for further details.

docs/models/circuits/providernetwork.md

@@ -2,4 +2,4 @@
 
 This model can be used to represent the boundary of a provider network, the details of which are unknown or unimportant to the NetBox user. For example, it might represent a provider's regional MPLS network to which multiple circuits provide connectivity.
 
-Each provider network must be assigned to a provider. A circuit may terminate to either a provider network or to a site.
+Each provider network must be assigned to a provider, and may optionally be assigned an arbitrary service ID. A circuit may terminate to either a provider network or to a site.

docs/models/dcim/cable.md

@@ -22,13 +22,3 @@ Each cable may be assigned a type, label, length, and color. Each cable is also
 ## Tracing Cables
 
 A cable may be traced from either of its endpoints by clicking the "trace" button. (A REST API endpoint also provides this functionality.) NetBox will follow the path of connected cables from this termination across the directly connected cable to the far-end termination. If the cable connects to a pass-through port, and the peer port has another cable connected, NetBox will continue following the cable path until it encounters a non-pass-through or unconnected termination point. The entire path will be displayed to the user.
-
-In the example below, three individual cables comprise a path between devices A and D:
-
-![Cable path](/media/models/dcim_cable_trace.png)
-
-Traced from Interface 1 on Device A, NetBox will show the following path:
-
-* Cable 1: Interface 1 to Front Port 1
-* Cable 2: Rear Port 1 to Rear Port 2
-* Cable 3: Front Port 2 to Interface 2

docs/models/dcim/devicebay.md

@@ -5,4 +5,4 @@ Device bays represent a space or slot within a parent device in which a child de
 Child devices are first-class Devices in their own right: That is, they are fully independent managed entities which don't share any control plane with the parent.  Just like normal devices, child devices have their own platform (OS), role, tags, and components.  LAG interfaces may not group interfaces belonging to different child devices.
 
 !!! note
-    Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, line cards and similarly non-autonomous hardware should be modeled as inventory items within a device, with any associated interfaces or other components assigned directly to the device.
+    Device bays are **not** suitable for modeling line cards (such as those commonly found in chassis-based routers and switches), as these components depend on the control plane of the parent device to operate. Instead, these should be modeled as modules installed within module bays.

docs/models/dcim/devicebaytemplate.md

@@ -1,3 +1,3 @@
 ## Device Bay Templates
 
-A template for a device bay that will be created on all instantiations of the parent device type.
+A template for a device bay that will be created on all instantiations of the parent device type. Device bays hold child devices, such as blade servers.

docs/models/dcim/devicetype.md

@@ -4,11 +4,13 @@ A device type represents a particular make and model of hardware that exists in
 
 Device types are instantiated as devices installed within sites and/or equipment racks. For example, you might define a device type to represent a Juniper EX4300-48T network switch with 48 Ethernet interfaces. You can then create multiple _instances_ of this type named "switch1," "switch2," and so on. Each device will automatically inherit the components (such as interfaces) of its device type at the time of creation. However, changes made to a device type will **not** apply to instances of that device type retroactively.
 
-Some devices house child devices which share physical resources, like space and power, but which functional independently from one another. A common example of this is blade server chassis. Each device type is designated as one of the following:
+Some devices house child devices which share physical resources, like space and power, but which function independently. A common example of this is blade server chassis. Each device type is designated as one of the following:
 
 * A parent device (which has device bays)
 * A child device (which must be installed within a device bay)
 * Neither
 
 !!! note
-    This parent/child relationship is **not** suitable for modeling chassis-based devices, wherein child members share a common control plane. Instead, line cards and similarly non-autonomous hardware should be modeled as inventory items within a device, with any associated interfaces or other components assigned directly to the device.
+    This parent/child relationship is **not** suitable for modeling chassis-based devices, wherein child members share a common control plane. Instead, line cards and similarly non-autonomous hardware should be modeled as modules or inventory items within a device.
+
+A device type may optionally specify an airflow direction, such as front-to-rear, rear-to-front, or passive. Airflow direction may also be set separately per device. If it is not defined for a device at the time of its creation, it will inherit the airflow setting of its device type.

docs/models/dcim/interface.md

@@ -1,6 +1,6 @@
 ## Interfaces
 
-Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. Each interface must be assigned a type, and may optionally be assigned a MAC address, MTU, and IEEE 802.1Q mode (tagged or access). Each interface can also be enabled or disabled, and optionally designated as management-only (for out-of-band management).
+Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. Each interface must be assigned a type, and may optionally be assigned a MAC address, MTU, and IEEE 802.1Q mode (tagged or access). Each interface can also be enabled or disabled, and optionally designated as management-only (for out-of-band management). Additionally, each interface may optionally be assigned to a VRF.
 
 !!! note
     Although devices and virtual machines both can have interfaces, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa.
@@ -11,6 +11,17 @@ Interfaces may be physical or virtual in nature, but only physical interfaces ma
 
 Physical interfaces may be arranged into a link aggregation group (LAG) and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically.
 
+### Wireless Interfaces
+
+Wireless interfaces may additionally track the following attributes:
+
+* **Role** - AP or station
+* **Channel** - One of several standard wireless channels
+* **Channel Frequency** - The transmit frequency
+* **Channel Width** - Channel bandwidth
+
+If a predefined channel is selected, the frequency and width attributes will be assigned automatically. If no channel is selected, these attributes may be defined manually.
+
 ### IP Address Assignment
 
 IP addresses can be assigned to interfaces. VLANs can also be assigned to each interface as either tagged or untagged. (An interface may have only one untagged VLAN.)

docs/models/dcim/inventoryitem.md

@@ -1,7 +1,7 @@
 # Inventory Items
 
-Inventory items represent hardware components installed within a device, such as a power supply or CPU or line card. Inventory items are distinct from other device components in that they cannot be templatized on a device type, and cannot be connected by cables. They are intended to be used primarily for inventory purposes.
+Inventory items represent hardware components installed within a device, such as a power supply or CPU or line card. They are intended to be used primarily for inventory purposes.
 
-Each inventory item can be assigned a manufacturer, part ID, serial number, and asset tag (all optional). A boolean toggle is also provided to indicate whether each item was entered manually or discovered automatically (by some process outside of NetBox).
+Each inventory item can be assigned a functional role, manufacturer, part ID, serial number, and asset tag (all optional). A boolean toggle is also provided to indicate whether each item was entered manually or discovered automatically (by some process outside NetBox).
 
-Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device.
+Inventory items are hierarchical in nature, such that any individual item may be designated as the parent for other items. For example, an inventory item might be created to represent a line card which houses several SFP optics, each of which exists as a child item within the device. An inventory item may also be associated with a specific component within the same device. For example, you may wish to associate a transceiver with an interface.

docs/models/dcim/inventoryitemrole.md

@@ -0,0 +1,3 @@
+# Inventory Item Roles
+
+Inventory items can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for power supplies, fans, interface optics, etc.

docs/models/dcim/inventoryitemtemplate.md

@@ -0,0 +1,3 @@
+# Inventory Item Templates
+
+A template for an inventory item that will be automatically created when instantiating a new device. All attributes of this object will be copied to the new inventory item, including the associations with a parent item and assigned component, if any.

docs/models/dcim/location.md

@@ -2,4 +2,5 @@
 
 Racks and devices can be grouped by location within a site. A location may represent a floor, room, cage, or similar organizational unit. Locations can be nested to form a hierarchy. For example, you may have floors within a site, and rooms within a floor.
 
-The name and facility ID of each rack within a location must be unique. (Racks not assigned to the same location may have identical names and/or facility IDs.)
+Each location must have a name that is unique within its parent site and location, if any.
+

docs/models/dcim/module.md

@@ -0,0 +1,5 @@
+# Modules
+
+A module is a field-replaceable hardware component installed within a device which houses its own child components. The most common example is a chassis-based router or switch.
+
+Similar to devices, modules are instantiated from module types, and any components associated with the module type are automatically instantiated on the new model. Each module must be installed within a module bay on a device, and each module bay may have only one module installed in it. A module may optionally be assigned a serial number and asset tag.

docs/models/dcim/modulebay.md

@@ -0,0 +1,3 @@
+## Module Bays
+
+Module bays represent a space or slot within a device in which a field-replaceable module may be installed. A common example is that of a chassis-based switch such as the Cisco Nexus 9000 or Juniper EX9200. Modules in turn hold additional components that become available to the parent device.

docs/models/dcim/modulebaytemplate.md

@@ -0,0 +1,3 @@
+## Module Bay Templates
+
+A template for a module bay that will be created on all instantiations of the parent device type. Module bays hold installed modules that do not have an independent management plane, such as line cards.

docs/models/dcim/moduletype.md

@@ -0,0 +1,23 @@
+# Module Types
+
+A module type represent a specific make and model of hardware component which is installable within a device and has its own child components. For example, consider a chassis-based switch or router with a number of field-replaceable line cards. Each line card has its own model number and includes a certain set of components such as interfaces. Each module type may have a manufacturer, model number, and part number assigned to it.
+
+Similar to device types, each module type can have any of the following component templates associated with it:
+
+* Interfaces
+* Console ports
+* Console server ports
+* Power ports
+* Power Outlets
+* Front pass-through ports
+* Rear pass-through ports
+
+Note that device bays and module bays may _not_ be added to modules.
+
+## Automatic Component Renaming
+
+When adding component templates to a module type, the string `{module}` can be used to reference the `position` field of the module bay into which an instance of the module type is being installed.
+
+For example, you can create a module type with interface templates named `Gi{module}/0/[1-48]`. When a new module of this type is "installed" to a module bay with a position of "3", NetBox will automatically name these interfaces `Gi3/0/[1-48]`.
+
+Automatic renaming is supported for all modular component types (those listed above).

docs/models/dcim/rack.md

@@ -1,6 +1,6 @@
 # Racks
 
-The rack model represents a physical two- or four-post equipment rack in which devices can be installed. Each rack must be assigned to a site, and may optionally be assigned to a location and/or tenant. Racks can also be organized by user-defined functional roles.
+The rack model represents a physical two- or four-post equipment rack in which devices can be installed. Each rack must be assigned to a site, and may optionally be assigned to a location and/or tenant. Racks can also be organized by user-defined functional roles. The name and facility ID of each rack within a location must be unique.
 
 Rack height is measured in *rack units* (U); racks are commonly between 42U and 48U tall, but NetBox allows you to define racks of arbitrary height. A toggle is provided to indicate whether rack units are in ascending (from the ground up) or descending order.
 

docs/models/dcim/region.md

@@ -1,3 +1,5 @@
 # Regions
 
 Sites can be arranged geographically using regions. A region might represent a continent, country, city, campus, or other area depending on your use case. Regions can be nested recursively to construct a hierarchy. For example, you might define several country regions, and within each of those several state or city regions to which sites are assigned.
+
+Each region must have a name that is unique within its parent region, if any.

docs/models/dcim/sitegroup.md

@@ -1,3 +1,5 @@
 # Site Groups
 
 Like regions, site groups can be used to organize sites. Whereas regions are intended to provide geographic organization, site groups can be used to classify sites by role or function. Also like regions, site groups can be nested to form a hierarchy. Sites which belong to a child group are also considered to be members of any of its parent groups.
+
+Each site group must have a name that is unique within its parent group, if any.

docs/models/extras/customfield.md

@@ -0,0 +1,49 @@
+# Custom Fields
+
+Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
+
+However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data.
+
+Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects.
+
+## Creating Custom Fields
+
+Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field:
+
+* Text: Free-form text (up to 255 characters)
+* Long text: Free-form of any length; supports Markdown rendering
+* Integer: A whole number (positive or negative)
+* Boolean: True or false
+* Date: A date in ISO 8601 format (YYYY-MM-DD)
+* URL: This will be presented as a link in the web UI
+* JSON: Arbitrary data stored in JSON format
+* Selection: A selection of one of several pre-defined custom choices
+* Multiple selection: A selection field which supports the assignment of multiple values
+* 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`
+
+Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form.
+
+Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields.
+
+The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely.
+
+A custom field must be assigned to one or more object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields.
+
+### Custom Field Validation
+
+NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type:
+
+* Text: Regular expression (optional)
+* Integer: Minimum and/or maximum value (optional)
+* Selection: Must exactly match one of the prescribed choices
+
+### Custom Selection Fields
+
+Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible.
+
+If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected.
+
+### Custom Object Fields
+
+An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point.

docs/models/extras/customlink.md

@@ -1,8 +1,8 @@
 # Custom Links
 
-Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a network monitoring system.
+Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS).
 
-Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link is assigned text and a URL, both of which support Jinja2 templating. The text and URL are rendered with the context variable `obj` representing the current object.
+Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link has display text and a URL, and data from the Netbox item being viewed can be included in the link using [Jinja2 template code](https://jinja2docs.readthedocs.io/en/stable/) through the variable `obj`, and custom fields through `obj.cf`.
 
 For example, you might define a link like this:
 
@@ -15,7 +15,7 @@ When viewing a device named Router4, this link would render as:
 <a href="https://nms.example.com/nodes/?name=Router4">View NMS</a>
 ```
 
-Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links.
+Custom links appear as buttons in the top right corner of the page. Numeric weighting can be used to influence the ordering of links, and each link can be enabled or disabled individually.
 
 !!! warning
     Custom links rely on user-created code to generate arbitrary HTML output, which may be dangerous. Only grant permission to create or modify custom links to trusted users.
@@ -24,13 +24,14 @@ Custom links appear as buttons in the top right corner of the page. Numeric weig
 
 The following context data is available within the template when rendering a custom link's text or URL.
 
-| Variable | Description |
-|----------|-------------|
-| `obj`      | The NetBox object being displayed |
-| `debug`    | A boolean indicating whether debugging is enabled |
-| `request`  | The current WSGI request |
-| `user`     | The current user (if authenticated) |
-| `perms`    | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user |
+| Variable  | Description                                                                                                       |
+|-----------|-------------------------------------------------------------------------------------------------------------------|
+| `object`  | The NetBox object being displayed                                                                                 |
+| `obj`     | Same as `object`; maintained for backward compatability until NetBox v3.5                                         |
+| `debug`   | A boolean indicating whether debugging is enabled                                                                 |
+| `request` | The current WSGI request                                                                                          |
+| `user`    | The current user (if authenticated)                                                                               |
+| `perms`   | The [permissions](https://docs.djangoproject.com/en/stable/topics/auth/default/#permissions) assigned to the user |
 
 ## Conditional Rendering
 
@@ -55,3 +56,7 @@ The link will only appear when viewing a device with a manufacturer name of "Cis
 ## Link Groups
 
 Group names can be specified to organize links into groups. Links with the same group name will render as a dropdown menu beneath a single button bearing the name of the group.
+
+## Table Columns
+
+Custom links can also be included in object tables by selecting the desired links from the table configuration form. When displayed, each link will render as a hyperlink for its corresponding object. When exported (e.g. as CSV data), each link render only its URL.

docs/models/extras/exporttemplate.md

@@ -0,0 +1,37 @@
+# Export Templates
+
+NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.
+
+Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension.
+
+Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/).
+
+!!! note
+    The name `table` is reserved for internal use.
+
+!!! warning
+    Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users.
+
+The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example:
+
+```jinja2
+{% for rack in queryset %}
+Rack: {{ rack.name }}
+Site: {{ rack.site.name }}
+Height: {{ rack.u_height }}U
+{% endfor %}
+```
+
+To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`.
+
+If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example:
+```
+{% for server in queryset %}
+{% set data = server.get_config_context() %}
+{{ data.syslog }}
+{% endfor %}
+```
+
+The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.)
+
+A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`.

docs/models/extras/tag.md

@@ -15,6 +15,3 @@ The `tag` filter can be specified multiple times to match only objects which hav
 ```no-highlight
 GET /api/dcim/devices/?tag=monitored&tag=deprecated
 ```
-
-!!! note
-    Tags have changed substantially in NetBox v2.9. They are no longer created on-demand when editing an object, and their representation in the REST API now includes a complete depiction of the tag rather than only its label.

docs/models/extras/webhook.md

@@ -0,0 +1,83 @@
+# 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 managed under Logging > Webhooks.
+
+!!! warning
+    Webhooks support the inclusion of user-submitted code to generate URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
+
+## Configuration
+
+* **Name** - A unique name for the webhook. The name is not included with outbound messages.
+* **Object type(s)** - The type or types of NetBox object that will trigger the webhook.
+* **Enabled** - If unchecked, the webhook will be inactive.
+* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected.
+* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field.
+* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`)
+* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below).
+* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.)
+* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
+* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object.
+* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!)
+* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional).
+
+## Jinja2 Template Support
+
+[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands.
+
+For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration:
+
+* Object type: IPAM > IP address
+* HTTP method: `POST`
+* URL: Slack incoming webhook URL
+* HTTP content type: `application/json`
+* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}`
+
+### Available Context
+
+The following data is available as context for Jinja2 templates:
+
+* `event` - The type of event which triggered the webhook: created, updated, or deleted.
+* `model` - The NetBox model which triggered the change.
+* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
+* `username` - The name of the user account associated with the change.
+* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request.
+* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API.
+* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided ass a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed.
+
+### Default Request Body
+
+If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows:
+
+```json
+{
+    "event": "created",
+    "timestamp": "2021-03-09 17:55:33.968016+00:00",
+    "model": "site",
+    "username": "jstretch",
+    "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a",
+    "data": {
+        "id": 19,
+        "name": "Site 1",
+        "slug": "site-1",
+        "status": 
+            "value": "active",
+            "label": "Active",
+            "id": 1
+        },
+        "region": null,
+        ...
+    },
+    "snapshots": {
+        "prechange": null,
+        "postchange": {
+            "created": "2021-03-09",
+            "last_updated": "2021-03-09T17:55:33.851Z",
+            "name": "Site 1",
+            "slug": "site-1",
+            "status": "active",
+            ...
+        }
+    }
+}
+```

docs/models/ipam/asn.md

@@ -0,0 +1,15 @@
+# ASN
+
+ASN is short for Autonomous System Number.  This identifier is used in the BGP protocol to identify which "autonomous system" a particular prefix is originating and transiting through.
+
+The AS number model within NetBox allows you to model some of this real-world relationship.
+
+Within NetBox:
+
+* AS numbers are globally unique
+* Each AS number must be associated with a RIR (ARIN, RFC 6996, etc)
+* Each AS number can be associated with many different sites
+* Each site can have many different AS numbers
+* Each AS number can be assigned to a single tenant
+
+

docs/models/ipam/fhrpgroup.md

@@ -0,0 +1,16 @@
+# FHRP Group
+
+A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to present a virtual IP address in a redundant manner. Example of such protocols include:
+
+* Hot Standby Router Protocol (HSRP)
+* Virtual Router Redundancy Protocol (VRRP)
+* Common Address Redundancy Protocol (CARP)
+* Gateway Load Balancing Protocol (GLBP)
+
+NetBox models these redundancy groups by protocol and group ID. Each group may optionally be assigned an authentication type and key. (Note that the authentication key is stored as a plaintext value in NetBox.) Each group may be assigned or more virtual IPv4 and/or IPv6 addresses.
+
+## FHRP Group Assignments
+
+Member device and VM interfaces can be assigned to FHRP groups, along with a numeric priority value. For instance, three interfaces, each belonging to a different router, may each be assigned to the same FHRP group to serve a common virtual IP address. Each of these assignments would typically receive a different priority.
+
+Interfaces are assigned to FHRP groups under the interface detail view.

docs/models/ipam/iprange.md

@@ -9,3 +9,6 @@ IP also ranges share the same functional roles as prefixes and VLANs, although t
 * Deprecated - No longer in use
 
 The status of a range does _not_ have any impact on its member IP addresses, which may have their statuses modified separately.
+
+!!! note
+    The maximum supported size of an IP range is 2^32 - 1.

docs/models/ipam/servicetemplate.md

@@ -0,0 +1,3 @@
+# Service Templates
+
+Service templates can be used to instantiate services on devices and virtual machines. A template defines a name, protocol, and port number(s), and may optionally include a description. Services can be instantiated from templates and applied to devices and/or virtual machines, and may be associated with specific IP addresses.

docs/models/ipam/vlangroup.md

@@ -2,4 +2,6 @@
 
 VLAN groups can be used to organize VLANs within NetBox. Each VLAN group can be scoped to a particular region, site group, site, location, rack, cluster group, or cluster. Member VLANs will be available for assignment to devices and/or virtual machines within the specified scope.
 
+A minimum and maximum child VLAN ID must be set for each group. (These default to 1 and 4094 respectively.) VLANs created within a group must have a VID that falls between these values (inclusive).
+
 Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common site). For example, you can create two VLANs with ID 123, but they cannot both be assigned to the same group.

docs/models/tenancy/contact.md

@@ -0,0 +1,31 @@
+# Contacts
+
+A contact represent an individual or group that has been associated with an object in NetBox for administrative reasons. For example, you might assign one or more operational contacts to each site. Contacts can be arranged within nested contact groups.
+
+Each contact must include a name, which is unique to its parent group (if any). The following optional descriptors are also available:
+
+* Title
+* Phone
+* Email
+* Address
+
+## Contact Assignment
+
+Each contact can be assigned to one or more objects, allowing for the efficient reuse of contact information. When assigning a contact to an object, the user may optionally specify a role and/or priority (primary, secondary, tertiary, or inactive) to better convey the nature of the contact's relationship to the assigned object.
+
+The following models support the assignment of contacts:
+
+* circuits.Circuit
+* circuits.Provider
+* dcim.Device
+* dcim.Location
+* dcim.Manufacturer
+* dcim.PowerPanel
+* dcim.Rack
+* dcim.Region
+* dcim.Site
+* dcim.SiteGroup
+* tenancy.Tenant
+* virtualization.Cluster
+* virtualization.ClusterGroup
+* virtualization.VirtualMachine

docs/models/tenancy/contactgroup.md

@@ -0,0 +1,3 @@
+# Contact Groups
+
+Contacts can be organized into arbitrary groups. These groups can be recursively nested for convenience. Each contact within a group must have a unique name, but other attributes can be repeated.

docs/models/tenancy/contactrole.md

@@ -0,0 +1,3 @@
+# Contact Roles
+
+Contacts can be organized by functional roles, which are fully customizable by the user. For example, you might create roles for administrative, operational, or emergency contacts.

docs/models/virtualization/cluster.md

@@ -1,5 +1,5 @@
 # Clusters
 
-A cluster is a logical grouping of physical resources within which virtual machines run. A cluster must be assigned a type (technological classification), and may optionally be assigned to a cluster group, site, and/or tenant.
+A cluster is a logical grouping of physical resources within which virtual machines run. A cluster must be assigned a type (technological classification), and may optionally be assigned to a cluster group, site, and/or tenant. Each cluster must have a unique name within its assigned group and/or site, if any.
 
 Physical devices may be associated with clusters as hosts. This allows users to track on which host(s) a particular virtual machine may reside. However, NetBox does not support pinning a specific VM within a cluster to a particular host device.

docs/models/virtualization/vminterface.md

@@ -1,3 +1,3 @@
 ## Interfaces
 
-Virtual machine interfaces behave similarly to device interfaces, and can be assigned IP addresses, VLANs, and services. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them.
+Virtual machine interfaces behave similarly to device interfaces, and can be assigned to VRFs, and may have IP addresses, VLANs, and services attached to them. However, given their virtual nature, they lack properties pertaining to physical attributes. For example, VM interfaces do not have a physical type and cannot have cables attached to them.

docs/models/wireless/wirelesslan.md

@@ -0,0 +1,11 @@
+# Wireless LANs
+
+A wireless LAN is a set of interfaces connected via a common wireless channel. Each instance must have an SSID, and may optionally be correlated to a VLAN. Wireless LANs can be arranged into hierarchical groups.
+
+An interface may be attached to multiple wireless LANs, provided they are all operating on the same channel. Only wireless interfaces may be attached to wireless LANs.
+
+Each wireless LAN may have authentication attributes associated with it, including:
+
+* Authentication type
+* Cipher
+* Pre-shared key

docs/models/wireless/wirelesslangroup.md

@@ -0,0 +1,3 @@
+# Wireless LAN Groups
+
+Wireless LAN groups can be used to organize and classify wireless LANs. These groups are hierarchical: groups can be nested within parent groups. However, each wireless LAN may assigned only to one group.

docs/models/wireless/wirelesslink.md

@@ -0,0 +1,9 @@
+# Wireless Links
+
+A wireless link represents a connection between exactly two wireless interfaces. It may optionally be assigned an SSID and a description. It may also have a status assigned to it, similar to the cable model.
+
+Each wireless link may have authentication attributes associated with it, including:
+
+* Authentication type
+* Cipher
+* Pre-shared key

docs/plugins/development.md

@@ -1,429 +0,0 @@
-# Plugin Development
-
-This documentation covers the development of custom plugins for NetBox. Plugins are essentially self-contained [Django apps](https://docs.djangoproject.com/en/stable/) which integrate with NetBox to provide custom functionality. Since the development of Django apps is already very well-documented, we'll only be covering the aspects that are specific to NetBox.
-
-Plugins can do a lot, including:
-
-* Create Django models to store data in the database
-* Provide their own "pages" (views) in the web user interface
-* Inject template content and navigation links
-* Establish their own REST API endpoints
-* Add custom request/response middleware
-
-However, keep in mind that each piece of functionality is entirely optional. For example, if your plugin merely adds a piece of middleware or an API endpoint for existing data, there's no need to define any new models.
-
-!!! warning
-    While very powerful, the NetBox plugins API is necessarily limited in its scope. The plugins API is discussed here in its entirety: Any part of the NetBox code base not documented here is _not_ part of the supported plugins API, and should not be employed by a plugin. Internal elements of NetBox are subject to change at any time and without warning. Plugin authors are **strongly** encouraged to develop plugins using only the officially supported components discussed here and those provided by the underlying Django framework so as to avoid breaking changes in future releases. 
-
-## Initial Setup
-
-### Plugin Structure
-
-Although the specific structure of a plugin is largely left to the discretion of its authors, a typical NetBox plugin looks something like this:
-
-```no-highlight
-project-name/
-  - plugin_name/
-    - templates/
-      - plugin_name/
-        - *.html
-    - __init__.py
-    - middleware.py
-    - navigation.py
-    - signals.py
-    - template_content.py
-    - urls.py
-    - views.py
-  - README
-  - setup.py
-```
-
-The top level is the project root, which can have any name that you like. Immediately within the root should exist several items:
-
-* `setup.py` - This is a standard installation script used to install the plugin package within the Python environment.
-* `README` - A brief introduction to your plugin, how to install and configure it, where to find help, and any other pertinent information. It is recommended to write README files using a markup language such as Markdown.
-* The plugin source directory, with the same name as your plugin. This must be a valid Python package name (e.g. no spaces or hyphens).
-
-The plugin source directory contains all the actual Python code and other resources used by your plugin. Its structure is left to the author's discretion, however it is recommended to follow best practices as outlined in the [Django documentation](https://docs.djangoproject.com/en/stable/intro/reusable-apps/). At a minimum, this directory **must** contain an `__init__.py` file containing an instance of NetBox's `PluginConfig` class.
-
-### Create setup.py
-
-`setup.py` is the [setup script](https://docs.python.org/3.7/distutils/setupscript.html) we'll use to install our plugin once it's finished. The primary function of this script is to call the setuptools library's `setup()` function to create a Python distribution package. We can pass a number of keyword arguments to inform the package creation as well as to provide metadata about the plugin. An example `setup.py` is below:
-
-```python
-from setuptools import find_packages, setup
-
-setup(
-    name='netbox-animal-sounds',
-    version='0.1',
-    description='An example NetBox plugin',
-    url='https://github.com/netbox-community/netbox-animal-sounds',
-    author='Jeremy Stretch',
-    license='Apache 2.0',
-    install_requires=[],
-    packages=find_packages(),
-    include_package_data=True,
-    zip_safe=False,
-)
-```
-
-Many of these are self-explanatory, but for more information, see the [setuptools documentation](https://setuptools.readthedocs.io/en/latest/setuptools.html).
-
-!!! note
-    `zip_safe=False` is **required** as the current plugin iteration is not zip safe due to upstream python issue [issue19699](https://bugs.python.org/issue19699)  
-
-### Define a PluginConfig
-
-The `PluginConfig` class is a NetBox-specific wrapper around Django's built-in [`AppConfig`](https://docs.djangoproject.com/en/stable/ref/applications/) class. It is used to declare NetBox plugin functionality within a Python package. Each plugin should provide its own subclass, defining its name, metadata, and default and required configuration parameters. An example is below:
-
-```python
-from extras.plugins import PluginConfig
-
-class AnimalSoundsConfig(PluginConfig):
-    name = 'netbox_animal_sounds'
-    verbose_name = 'Animal Sounds'
-    description = 'An example plugin for development purposes'
-    version = '0.1'
-    author = 'Jeremy Stretch'
-    author_email = 'author@example.com'
-    base_url = 'animal-sounds'
-    required_settings = []
-    default_settings = {
-        'loud': False
-    }
-
-config = AnimalSoundsConfig
-```
-
-NetBox looks for the `config` variable within a plugin's `__init__.py` to load its configuration. Typically, this will be set to the PluginConfig subclass, but you may wish to dynamically generate a PluginConfig class based on environment variables or other factors.
-
-#### PluginConfig Attributes
-
-| Name | Description |
-| ---- | ----------- |
-| `name` | Raw plugin name; same as the plugin's source directory |
-| `verbose_name` | Human-friendly name for the plugin |
-| `version` | Current release ([semantic versioning](https://semver.org/) is encouraged) |
-| `description` | Brief description of the plugin's purpose |
-| `author` | Name of plugin's author |
-| `author_email` | Author's public email address |
-| `base_url` | Base path to use for plugin URLs (optional). If not specified, the project's `name` will be used. |
-| `required_settings` | A list of any configuration parameters that **must** be defined by the user |
-| `default_settings` | A dictionary of configuration parameters and their default values |
-| `min_version` | Minimum version of NetBox with which the plugin is compatible |
-| `max_version` | Maximum version of NetBox with which the plugin is compatible |
-| `middleware` | A list of middleware classes to append after NetBox's build-in middleware |
-| `template_extensions` | The dotted path to the list of template extension classes (default: `template_content.template_extensions`) |
-| `menu_items` | The dotted path to the list of menu items provided by the plugin (default: `navigation.menu_items`) |
-
-All required settings must be configured by the user. If a configuration parameter is listed in both `required_settings` and `default_settings`, the default setting will be ignored.
-
-### Create a Virtual Environment
-
-It is strongly recommended to create a Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) specific to your plugin. This will afford you complete control over the installed versions of all dependencies and avoid conflicting with any system packages. This environment can live wherever you'd like, however it should be excluded from revision control. (A popular convention is to keep all virtual environments in the user's home directory, e.g. `~/.virtualenvs/`.)
-
-```shell
-python3 -m venv /path/to/my/venv
-```
-
-You can make NetBox available within this environment by creating a path file pointing to its location. This will add NetBox to the Python path upon activation. (Be sure to adjust the command below to specify your actual virtual environment path, Python version, and NetBox installation.)
-
-```shell
-cd $VENV/lib/python3.7/site-packages/
-echo /opt/netbox/netbox > netbox.pth
-```
-
-### Install the Plugin for Development
-
-To ease development, it is recommended to go ahead and install the plugin at this point using setuptools' `develop` mode. This will create symbolic links within your Python environment to the plugin development directory. Call `setup.py` from the plugin's root directory with the `develop` argument (instead of `install`):
-
-```no-highlight
-$ python setup.py develop
-```
-
-## Database Models
-
-If your plugin introduces a new type of object in NetBox, you'll probably want to create a [Django model](https://docs.djangoproject.com/en/stable/topics/db/models/) for it. A model is essentially a Python representation of a database table, with attributes that represent individual columns. Model instances can be created, manipulated, and deleted using [queries](https://docs.djangoproject.com/en/stable/topics/db/queries/). Models must be defined within a file named `models.py`.
-
-Below is an example `models.py` file containing a model with two character fields:
-
-```python
-from django.db import models
-
-class Animal(models.Model):
-    name = models.CharField(max_length=50)
-    sound = models.CharField(max_length=50)
-
-    def __str__(self):
-        return self.name
-```
-
-Once you have defined the model(s) for your plugin, you'll need to create the database schema migrations. A migration file is essentially a set of instructions for manipulating the PostgreSQL database to support your new model, or to alter existing models. Creating migrations can usually be done automatically using Django's `makemigrations` management command.
-
-!!! note
-    A plugin must be installed before it can be used with Django management commands. If you skipped this step above, run `python setup.py develop` from the plugin's root directory.
-
-```no-highlight
-$ ./manage.py makemigrations netbox_animal_sounds 
-Migrations for 'netbox_animal_sounds':
-  /home/jstretch/animal_sounds/netbox_animal_sounds/migrations/0001_initial.py
-    - Create model Animal
-```
-
-Next, we can apply the migration to the database with the `migrate` command:
-
-```no-highlight
-$ ./manage.py migrate netbox_animal_sounds
-Operations to perform:
-  Apply all migrations: netbox_animal_sounds
-Running migrations:
-  Applying netbox_animal_sounds.0001_initial... OK
-```
-
-For more background on schema migrations, see the [Django documentation](https://docs.djangoproject.com/en/stable/topics/migrations/).
-
-### Using the Django Admin Interface
-
-Plugins can optionally expose their models via Django's built-in [administrative interface](https://docs.djangoproject.com/en/stable/ref/contrib/admin/). This can greatly improve troubleshooting ability, particularly during development. To expose a model, simply register it using Django's `admin.register()` function. An example `admin.py` file for the above model is shown below:
-
-```python
-from django.contrib import admin
-from .models import Animal
-
-@admin.register(Animal)
-class AnimalAdmin(admin.ModelAdmin):
-    list_display = ('name', 'sound')
-``` 
-
-This will display the plugin and its model in the admin UI. Staff users can create, change, and delete model instances via the admin UI without needing to create a custom view.
-
-![NetBox plugin in the admin UI](../media/plugins/plugin_admin_ui.png)
-
-## Views
-
-If your plugin needs its own page or pages in the NetBox web UI, you'll need to define views. A view is a particular page tied to a URL within NetBox, which renders content using a template. Views are typically defined in `views.py`, and URL patterns in `urls.py`. As an example, let's write a view which displays a random animal and the sound it makes. First, we'll create the view in `views.py`:
-
-```python
-from django.shortcuts import render
-from django.views.generic import View
-from .models import Animal
-
-class RandomAnimalView(View):
-    """
-    Display a randomly-selected animal.
-    """
-    def get(self, request):
-        animal = Animal.objects.order_by('?').first()
-        return render(request, 'netbox_animal_sounds/animal.html', {
-            'animal': animal,
-        })
-```
-
-This view retrieves a random animal from the database and and passes it as a context variable when rendering a template named `animal.html`, which doesn't exist yet. To create this template, first create a directory named `templates/netbox_animal_sounds/` within the plugin source directory. (We use the plugin's name as a subdirectory to guard against naming collisions with other plugins.) Then, create a template named `animal.html` as described below.
-
-### Extending the Base Template
-
-NetBox provides a base template to ensure a consistent user experience, which plugins can extend with their own content. This template includes four content blocks:
-
-* `title` - The page title
-* `header` - The upper portion of the page
-* `content` - The main page body
-* `javascript` - A section at the end of the page for including Javascript code
-
-For more information on how template blocks work, consult the [Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#block).
-
-```jinja2
-{% extends 'base/layout.html' %}
-
-{% block content %}
-    {% with config=settings.PLUGINS_CONFIG.netbox_animal_sounds %}
-        <h2 class="text-center" style="margin-top: 200px">
-            {% if animal %}
-                The {{ animal.name|lower }} says
-                {% if config.loud %}
-                    {{ animal.sound|upper }}!
-                {% else %}
-                    {{ animal.sound }}
-                {% endif %}
-            {% else %}
-                No animals have been created yet!
-            {% endif %}
-        </h2>
-    {% endwith %}
-{% endblock %}
-
-```
-
-The first line of the template instructs Django to extend the NetBox base template and inject our custom content within its `content` block.
-
-!!! note
-    Django renders templates with its own custom [template language](https://docs.djangoproject.com/en/stable/topics/templates/#the-django-template-language). This is very similar to Jinja2, however there are some important differences to be aware of.
-
-Finally, to make the view accessible to users, we need to register a URL for it. We do this in `urls.py` by defining a `urlpatterns` variable containing a list of paths.
-
-```python
-from django.urls import path
-from . import views
-
-urlpatterns = [
-    path('random/', views.RandomAnimalView.as_view(), name='random_animal'),
-]
-```
-
-A URL pattern has three components:
-
-* `route` - The unique portion of the URL dedicated to this view
-* `view` - The view itself
-* `name` - A short name used to identify the URL path internally
-
-This makes our view accessible at the URL `/plugins/animal-sounds/random/`. (Remember, our `AnimalSoundsConfig` class sets our plugin's base URL to `animal-sounds`.) Viewing this URL should show the base NetBox template with our custom content inside it.
-
-## REST API Endpoints
-
-Plugins can declare custom endpoints on NetBox's REST API to retrieve or manipulate models or other data. These behave very similarly to views, except that instead of rendering arbitrary content using a template, data is returned in JSON format using a serializer. NetBox uses the [Django REST Framework](https://www.django-rest-framework.org/), which makes writing API serializers and views very simple.
-
-First, we'll create a serializer for our `Animal` model, in `api/serializers.py`:
-
-```python
-from rest_framework.serializers import ModelSerializer
-from netbox_animal_sounds.models import Animal
-
-class AnimalSerializer(ModelSerializer):
-
-    class Meta:
-        model = Animal
-        fields = ('id', 'name', 'sound')
-```
-
-Next, we'll create a generic API view set that allows basic CRUD (create, read, update, and delete) operations for Animal instances. This is defined in `api/views.py`:
-
-```python
-from rest_framework.viewsets import ModelViewSet
-from netbox_animal_sounds.models import Animal
-from .serializers import AnimalSerializer
-
-class AnimalViewSet(ModelViewSet):
-    queryset = Animal.objects.all()
-    serializer_class = AnimalSerializer
-```
-
-Finally, we'll register a URL for our endpoint in `api/urls.py`. This file **must** define a variable named `urlpatterns`.
-
-```python
-from rest_framework import routers
-from .views import AnimalViewSet
-
-router = routers.DefaultRouter()
-router.register('animals', AnimalViewSet)
-urlpatterns = router.urls
-```
-
-With these three components in place, we can request `/api/plugins/animal-sounds/animals/` to retrieve a list of all Animal objects defined.
-
-![NetBox REST API plugin endpoint](../media/plugins/plugin_rest_api_endpoint.png)
-
-!!! warning
-    This example is provided as a minimal reference implementation only. It does not address authentication, performance, or myriad other concerns that plugin authors should have.
-
-## Navigation Menu Items
-
-To make its views easily accessible to users, a plugin can inject items in NetBox's navigation menu under the "Plugins" header. Menu items are added by defining a list of PluginMenuItem instances. By default, this should be a variable named `menu_items` in the file `navigation.py`. An example is shown below.
-
-```python
-from extras.plugins import PluginMenuButton, PluginMenuItem
-from utilities.choices import ButtonColorChoices
-
-menu_items = (
-    PluginMenuItem(
-        link='plugins:netbox_animal_sounds:random_animal',
-        link_text='Random sound',
-        buttons=(
-            PluginMenuButton('home', 'Button A', 'fa fa-info', ButtonColorChoices.BLUE),
-            PluginMenuButton('home', 'Button B', 'fa fa-warning', ButtonColorChoices.GREEN),
-        )
-    ),
-)
-```
-
-A `PluginMenuItem` has the following attributes:
-
-* `link` - The name of the URL path to which this menu item links
-* `link_text` - The text presented to the user
-* `permissions` - A list of permissions required to display this link (optional)
-* `buttons` - An iterable of PluginMenuButton instances to display (optional)
-
-A `PluginMenuButton` has the following attributes:
-
-* `link` - The name of the URL path to which this button links
-* `title` - The tooltip text (displayed when the mouse hovers over the button)
-* `icon_class` - Button icon CSS class (NetBox currently supports [Font Awesome 4.7](https://fontawesome.com/v4.7.0/icons/))
-* `color` - One of the choices provided by `ButtonColorChoices` (optional)
-* `permissions` - A list of permissions required to display this button (optional)
-
-!!! note
-    Any buttons associated within a menu item will be shown only if the user has permission to view the link, regardless of what permissions are set on the buttons.
-
-## Extending Core Templates
-
-Plugins can inject custom content into certain areas of the detail views of applicable models. This is accomplished by subclassing `PluginTemplateExtension`, designating a particular NetBox model, and defining the desired methods to render custom content. Four methods are available:
-
-* `left_page()` - Inject content on the left side of the page
-* `right_page()` - Inject content on the right side of the page
-* `full_width_page()` - Inject content across the entire bottom of the page
-* `buttons()` - Add buttons to the top of the page
-
-Additionally, a `render()` method is available for convenience. This method accepts the name of a template to render, and any additional context data you want to pass. Its use is optional, however.
-
-When a PluginTemplateExtension is instantiated, context data is assigned to `self.context`. Available data include:
-
-* `object` - The object being viewed
-* `request` - The current request
-* `settings` - Global NetBox settings
-* `config` - Plugin-specific configuration parameters
-
-For example, accessing `{{ request.user }}` within a template will return the current user.
-
-Declared subclasses should be gathered into a list or tuple for integration with NetBox. By default, NetBox looks for an iterable named `template_extensions` within a `template_content.py` file. (This can be overridden by setting `template_extensions` to a custom value on the plugin's PluginConfig.) An example is below.
-
-```python
-from extras.plugins import PluginTemplateExtension
-from .models import Animal
-
-class SiteAnimalCount(PluginTemplateExtension):
-    model = 'dcim.site'
-
-    def right_page(self):
-        return self.render('netbox_animal_sounds/inc/animal_count.html', extra_context={
-            'animal_count': Animal.objects.count(),
-        })
-
-template_extensions = [SiteAnimalCount]
-```
-
-## Background Tasks
-
-By default, Netbox provides 3 differents [RQ](https://python-rq.org/) queues to run background jobs : *high*, *default* and *low*.
-These 3 core queues can be used out-of-the-box by plugins to define background tasks.
-
-Plugins can also define dedicated queues. These queues can be configured under the PluginConfig class `queues` attribute. An example configuration
-is below:
-
-```python
-class MyPluginConfig(PluginConfig):
-    name = 'myplugin'
-    ...
-    queues = [
-        'queue1',
-        'queue2',
-        'queue-whatever-the-name'
-    ]
-```
-
-The PluginConfig above creates 3 queues with the following names: *myplugin.queue1*, *myplugin.queue2*, *myplugin.queue-whatever-the-name*.
-As you can see, the queue's name is always preprended with the plugin's name, to avoid any name clashes between different plugins.
-
-In case you create dedicated queues for your plugin, it is strongly advised to also create a dedicated RQ worker instance. This instance should only listen to the queues defined in your plugin - to avoid impact between your background tasks and netbox internal tasks.
-
-```
-python manage.py rqworker myplugin.queue1 myplugin.queue2 myplugin.queue-whatever-the-name
-```

docs/plugins/development/background-tasks.md

@@ -0,0 +1,30 @@
+# Background Tasks
+
+NetBox supports the queuing of tasks that need to be performed in the background, decoupled from the request-response cycle, using the [Python RQ](https://python-rq.org/) library. Three task queues of differing priority are defined by default:
+
+* High
+* Default
+* Low
+
+Any tasks in the "high" queue are completed before the default queue is checked, and any tasks in the default queue are completed before those in the "low" queue.
+
+Plugins can also add custom queues for their own needs by setting the `queues` attribute under the PluginConfig class. An example is included below:
+
+```python
+class MyPluginConfig(PluginConfig):
+    name = 'myplugin'
+    ...
+    queues = [
+        'foo',
+        'bar',
+    ]
+```
+
+The PluginConfig above creates two custom queues with the following names `my_plugin.foo` and `my_plugin.bar`. (The plugin's name is prepended to each queue to avoid conflicts between plugins.)
+
+!!! warning "Configuring the RQ worker process"
+    By default, NetBox's RQ worker process only services the high, default, and low queues. Plugins which introduce custom queues should advise users to either reconfigure the default worker, or run a dedicated worker specifying the necessary queues. For example:
+    
+    ```
+    python manage.py rqworker my_plugin.foo my_plugin.bar
+    ```

docs/plugins/development/filtersets.md

@@ -0,0 +1,70 @@
+# Filters & Filter Sets
+
+Filter sets define the mechanisms available for filtering or searching through a set of objects in NetBox. For instance, sites can be filtered by their parent region or group, status, facility ID, and so on. The same filter set is used consistently for a model whether the request is made via the UI, REST API, or GraphQL API. NetBox employs the [django-filters2](https://django-tables2.readthedocs.io/en/latest/) library to define filter sets.
+
+## FilterSet Classes
+
+To support additional functionality standard to NetBox models, such as tag assignment and custom field support, the `NetBoxModelFilterSet` class is available for use by plugins. This should be used as the base filter set class for plugin models which inherit from `NetBoxModel`. Within this class, individual filters can be declared as directed by the `django-filters` documentation. An example is provided below.
+
+```python
+# filtersets.py
+import django_filters
+from netbox.filtersets import NetBoxModelFilterSet
+from .models import MyModel
+
+class MyFilterSet(NetBoxModelFilterSet):
+    status = django_filters.MultipleChoiceFilter(
+        choices=(
+            ('foo', 'Foo'),
+            ('bar', 'Bar'),
+            ('baz', 'Baz'),
+        ),
+        null_value=None
+    )
+
+    class Meta:
+        model = MyModel
+        fields = ('some', 'other', 'fields')
+```
+
+### Declaring Filter Sets
+
+To utilize a filter set in a subclass of one of NetBox's generic views (such as `ObjectListView` or `BulkEditView`), define the `filterset` attribute on the view class:
+
+```python
+# views.py
+from netbox.views.generic import ObjectListView
+from .filtersets import MyModelFitlerSet
+from .models import MyModel
+
+class MyModelListView(ObjectListView):
+    queryset = MyModel.objects.all()
+    filterset = MyModelFitlerSet
+```
+
+To enable a filter set on a  REST API endpoint, set the `filterset_class` attribute on the API view:
+
+```python
+# api/views.py
+from myplugin import models, filtersets
+from . import serializers
+
+class MyModelViewSet(...):
+    queryset = models.MyModel.objects.all()
+    serializer_class = serializers.MyModelSerializer
+    filterset_class = filtersets.MyModelFilterSet
+```
+
+## Filter Classes
+
+### TagFilter
+
+The `TagFilter` class is available for all models which support tag assignment (those which inherit from `NetBoxModel` or `TagsMixin`). This filter subclasses django-filter's `ModelMultipleChoiceFilter` to work with NetBox's `TaggedItem` class.
+
+```python
+from django_filters import FilterSet
+from extras.filters import TagFilter
+
+class MyModelFilterSet(FilterSet):
+    tag = TagFilter()
+```

docs/plugins/development/forms.md

@@ -0,0 +1,78 @@
+# Forms
+
+## Form Classes
+
+NetBox provides several base form classes for use by plugins.
+
+* `NetBoxModelForm`
+* `NetBoxModelCSVForm`
+* `NetBoxModelBulkEditForm`
+* `NetBoxModelFilterSetForm`
+
+<!-- TODO: Include forms reference -->
+
+In addition to the [form fields provided by Django](https://docs.djangoproject.com/en/stable/ref/forms/fields/), NetBox provides several field classes for use within forms to handle specific types of data. These can be imported from `utilities.forms.fields` and are documented below.
+
+## General Purpose Fields
+
+::: utilities.forms.ColorField
+    selection:
+      members: false
+
+::: utilities.forms.CommentField
+    selection:
+      members: false
+
+::: utilities.forms.JSONField
+    selection:
+      members: false
+
+::: utilities.forms.MACAddressField
+    selection:
+      members: false
+
+::: utilities.forms.SlugField
+    selection:
+      members: false
+
+## Dynamic Object Fields
+
+::: utilities.forms.DynamicModelChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.DynamicModelMultipleChoiceField
+    selection:
+      members: false
+
+## Content Type Fields
+
+::: utilities.forms.ContentTypeChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.ContentTypeMultipleChoiceField
+    selection:
+      members: false
+
+## CSV Import Fields
+
+::: utilities.forms.CSVChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.CSVMultipleChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.CSVModelChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.CSVContentTypeField
+    selection:
+      members: false
+
+::: utilities.forms.CSVMultipleContentTypeField
+    selection:
+      members: false

docs/plugins/development/graphql-api.md

@@ -0,0 +1,51 @@
+# GraphQL API
+
+## Defining the Schema Class
+
+A plugin can extend NetBox's GraphQL API by registering its own schema class. By default, NetBox will attempt to import `graphql.schema` from the plugin, if it exists. This path can be overridden by defining `graphql_schema` on the PluginConfig instance as the dotted path to the desired Python class. This class must be a subclass of `graphene.ObjectType`.
+
+### Example
+
+```python
+# graphql.py
+import graphene
+from netbox.graphql.fields import ObjectField, ObjectListField
+from . import filtersets, models
+
+class MyModelType(graphene.ObjectType):
+
+    class Meta:
+        model = models.MyModel
+        fields = '__all__'
+        filterset_class = filtersets.MyModelFilterSet
+
+class MyQuery(graphene.ObjectType):
+    mymodel = ObjectField(MyModelType)
+    mymodel_list = ObjectListField(MyModelType)
+
+schema = MyQuery
+```
+
+## GraphQL Objects
+
+NetBox provides two object type classes for use by plugins.
+
+::: netbox.graphql.types.BaseObjectType
+    selection:
+      members: false
+
+::: netbox.graphql.types.NetBoxObjectType
+    selection:
+      members: false
+
+## GraphQL Fields
+
+NetBox provides two field classes for use by plugins.
+
+::: netbox.graphql.fields.ObjectField
+    selection:
+      members: false
+
+::: netbox.graphql.fields.ObjectListField
+    selection:
+      members: false

docs/plugins/development/index.md

@@ -0,0 +1,165 @@
+# Plugins Development
+
+!!! tip "Help Improve the NetBox Plugins Framework!"
+    We're looking for volunteers to help improve NetBox's plugins framework. If you have experience developing plugins, we'd love to hear from you! You can find more information about this initiative [here](https://github.com/netbox-community/netbox/discussions/8338).
+
+NetBox can be extended to support additional data models and functionality through the use of plugins. A plugin is essentially a self-contained [Django app](https://docs.djangoproject.com/en/stable/) which gets installed alongside NetBox to provide custom functionality. Multiple plugins can be installed in a single NetBox instance, and each plugin can be enabled and configured independently.
+
+!!! info "Django Development"
+    Django is the Python framework on which NetBox is built. As Django itself is very well-documented, this documentation covers only the aspects of plugin development which are unique to NetBox.
+
+Plugins can do a lot, including:
+
+* Create Django models to store data in the database
+* Provide their own "pages" (views) in the web user interface
+* Inject template content and navigation links
+* Extend NetBox's REST and GraphQL APIs
+* Add custom request/response middleware
+
+However, keep in mind that each piece of functionality is entirely optional. For example, if your plugin merely adds a piece of middleware or an API endpoint for existing data, there's no need to define any new models.
+
+!!! warning
+    While very powerful, the NetBox plugins API is necessarily limited in its scope. The plugins API is discussed here in its entirety: Any part of the NetBox code base not documented here is _not_ part of the supported plugins API, and should not be employed by a plugin. Internal elements of NetBox are subject to change at any time and without warning. Plugin authors are **strongly** encouraged to develop plugins using only the officially supported components discussed here and those provided by the underlying Django framework to avoid breaking changes in future releases.
+
+## Plugin Structure
+
+Although the specific structure of a plugin is largely left to the discretion of its authors, a typical NetBox plugin might look something like this:
+
+```no-highlight
+project-name/
+  - plugin_name/
+    - api/
+      - serializers.py
+      - urls.py
+      - views.py
+    - templates/
+      - plugin_name/
+        - *.html
+    - __init__.py
+    - filtersets.py
+    - models.py
+    - middleware.py
+    - navigation.py
+    - signals.py
+    - tables.py
+    - template_content.py
+    - urls.py
+    - views.py
+  - README.md
+  - setup.py
+```
+
+The top level is the project root, which can have any name that you like. Immediately within the root should exist several items:
+
+* `setup.py` - This is a standard installation script used to install the plugin package within the Python environment.
+* `README.md` - A brief introduction to your plugin, how to install and configure it, where to find help, and any other pertinent information. It is recommended to write `README` files using a markup language such as Markdown to enable human-friendly display.
+* The plugin source directory. This must be a valid Python package name, typically comprising only lowercase letters, numbers, and underscores.
+
+The plugin source directory contains all the actual Python code and other resources used by your plugin. Its structure is left to the author's discretion, however it is recommended to follow best practices as outlined in the [Django documentation](https://docs.djangoproject.com/en/stable/intro/reusable-apps/). At a minimum, this directory **must** contain an `__init__.py` file containing an instance of NetBox's `PluginConfig` class, discussed below.
+
+## PluginConfig
+
+The `PluginConfig` class is a NetBox-specific wrapper around Django's built-in [`AppConfig`](https://docs.djangoproject.com/en/stable/ref/applications/) class. It is used to declare NetBox plugin functionality within a Python package. Each plugin should provide its own subclass, defining its name, metadata, and default and required configuration parameters. An example is below:
+
+```python
+from extras.plugins import PluginConfig
+
+class FooBarConfig(PluginConfig):
+    name = 'foo_bar'
+    verbose_name = 'Foo Bar'
+    description = 'An example NetBox plugin'
+    version = '0.1'
+    author = 'Jeremy Stretch'
+    author_email = 'author@example.com'
+    base_url = 'foo-bar'
+    required_settings = []
+    default_settings = {
+        'baz': True
+    }
+
+config = FooBarConfig
+```
+
+NetBox looks for the `config` variable within a plugin's `__init__.py` to load its configuration. Typically, this will be set to the PluginConfig subclass, but you may wish to dynamically generate a PluginConfig class based on environment variables or other factors.
+
+### PluginConfig Attributes
+
+| Name                  | Description                                                                                                              |
+|-----------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `name`                | Raw plugin name; same as the plugin's source directory                                                                   |
+| `verbose_name`        | Human-friendly name for the plugin                                                                                       |
+| `version`             | Current release ([semantic versioning](https://semver.org/) is encouraged)                                               |
+| `description`         | Brief description of the plugin's purpose                                                                                |
+| `author`              | Name of plugin's author                                                                                                  |
+| `author_email`        | Author's public email address                                                                                            |
+| `base_url`            | Base path to use for plugin URLs (optional). If not specified, the project's `name` will be used.                        |
+| `required_settings`   | A list of any configuration parameters that **must** be defined by the user                                              |
+| `default_settings`    | A dictionary of configuration parameters and their default values                                                        |
+| `min_version`         | Minimum version of NetBox with which the plugin is compatible                                                            |
+| `max_version`         | Maximum version of NetBox with which the plugin is compatible                                                            |
+| `middleware`          | A list of middleware classes to append after NetBox's build-in middleware                                                |
+| `queues`              | A list of custom background task queues to create                                                                        |
+| `template_extensions` | The dotted path to the list of template extension classes (default: `template_content.template_extensions`)              |
+| `menu_items`          | The dotted path to the list of menu items provided by the plugin (default: `navigation.menu_items`)                      |
+| `graphql_schema`      | The dotted path to the plugin's GraphQL schema class, if any (default: `graphql.schema`)                                 |
+| `user_preferences`    | The dotted path to the dictionary mapping of user preferences defined by the plugin (default: `preferences.preferences`) |
+
+All required settings must be configured by the user. If a configuration parameter is listed in both `required_settings` and `default_settings`, the default setting will be ignored.
+
+## Create setup.py
+
+`setup.py` is the [setup script](https://docs.python.org/3.8/distutils/setupscript.html) used to package and install our plugin once it's finished. The primary function of this script is to call the setuptools library's `setup()` function to create a Python distribution package. We can pass a number of keyword arguments to control the package creation as well as to provide metadata about the plugin. An example `setup.py` is below:
+
+```python
+from setuptools import find_packages, setup
+
+setup(
+    name='my-example-plugin',
+    version='0.1',
+    description='An example NetBox plugin',
+    url='https://github.com/jeremystretch/my-example-plugin',
+    author='Jeremy Stretch',
+    license='Apache 2.0',
+    install_requires=[],
+    packages=find_packages(),
+    include_package_data=True,
+    zip_safe=False,
+)
+```
+
+Many of these are self-explanatory, but for more information, see the [setuptools documentation](https://setuptools.readthedocs.io/en/latest/setuptools.html).
+
+!!! info
+    `zip_safe=False` is **required** as the current plugin iteration is not zip safe due to upstream python issue [issue19699](https://bugs.python.org/issue19699)  
+
+## Create a Virtual Environment
+
+It is strongly recommended to create a Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) for the development of your plugin, as opposed to using system-wide packages. This will afford you complete control over the installed versions of all dependencies and avoid conflict with system packages. This environment can live wherever you'd like, however it should be excluded from revision control. (A popular convention is to keep all virtual environments in the user's home directory, e.g. `~/.virtualenvs/`.)
+
+```shell
+python3 -m venv ~/.virtualenvs/my_plugin
+```
+
+You can make NetBox available within this environment by creating a path file pointing to its location. This will add NetBox to the Python path upon activation. (Be sure to adjust the command below to specify your actual virtual environment path, Python version, and NetBox installation.)
+
+```shell
+echo /opt/netbox/netbox > $VENV/lib/python3.8/site-packages/netbox.pth
+```
+
+## Development Installation
+
+To ease development, it is recommended to go ahead and install the plugin at this point using setuptools' `develop` mode. This will create symbolic links within your Python environment to the plugin development directory. Call `setup.py` from the plugin's root directory with the `develop` argument (instead of `install`):
+
+```no-highlight
+$ python setup.py develop
+```
+
+## Configure NetBox
+
+To enable the plugin in NetBox, add it to the `PLUGINS` parameter in `configuration.py`:
+
+```python
+PLUGINS = [
+    'my_plugin',
+]
+```

docs/plugins/development/models.md

@@ -0,0 +1,182 @@
+# Database Models
+
+## Creating Models
+
+If your plugin introduces a new type of object in NetBox, you'll probably want to create a [Django model](https://docs.djangoproject.com/en/stable/topics/db/models/) for it. A model is essentially a Python representation of a database table, with attributes that represent individual columns. Instances of a model (objects) can be created, manipulated, and deleted using [queries](https://docs.djangoproject.com/en/stable/topics/db/queries/). Models must be defined within a file named `models.py`.
+
+Below is an example `models.py` file containing a model with two character (text) fields:
+
+```python
+from django.db import models
+
+class MyModel(models.Model):
+    foo = models.CharField(max_length=50)
+    bar = models.CharField(max_length=50)
+
+    def __str__(self):
+        return f'{self.foo} {self.bar}'
+```
+
+Every model includes by default a numeric primary key. This value is generated automatically by the database, and can be referenced as `pk` or `id`.
+
+## Enabling NetBox Features
+
+Plugin models can leverage certain NetBox features by inheriting from NetBox's `NetBoxModel` class. This class extends the plugin model to enable features unique to NetBox, including:
+
+* Change logging
+* Custom fields
+* Custom links
+* Custom validation
+* Export templates
+* Journaling
+* Tags
+* Webhooks
+
+This class performs two crucial functions:
+
+1. Apply any fields, methods, and/or attributes necessary to the operation of these features
+2. Register the model with NetBox as utilizing these features
+
+Simply subclass BaseModel when defining a model in your plugin:
+
+```python
+# models.py
+from django.db import models
+from netbox.models import NetBoxModel
+
+class MyModel(NetBoxModel):
+    foo = models.CharField()
+    ...
+```
+
+### Enabling Features Individually
+
+If you prefer instead to enable only a subset of these features for a plugin model, NetBox provides a discrete "mix-in" class for each feature. You can subclass each of these individually when defining your model. (Your model will also need to inherit from Django's built-in `Model` class.)
+
+For example, if we wanted to support only tags and export templates, we would inherit from NetBox's `ExportTemplatesMixin` and `TagsMixin` classes, and from Django's `Model` class. (Inheriting _all_ the available mixins is essentially the same as subclassing `NetBoxModel`.)
+
+```python
+# models.py
+from django.db import models
+from netbox.models.features import ExportTemplatesMixin, TagsMixin
+
+class MyModel(ExportTemplatesMixin, TagsMixin, models.Model):
+    foo = models.CharField()
+    ...
+```
+
+## Database Migrations
+
+Once you have completed defining the model(s) for your plugin, you'll need to create the database schema migrations. A migration file is essentially a set of instructions for manipulating the PostgreSQL database to support your new model, or to alter existing models. Creating migrations can usually be done automatically using Django's `makemigrations` management command. (Ensure that your plugin has been installed and enabled first, otherwise it won't be found.)
+
+!!! note Enable Developer Mode
+    NetBox enforces a safeguard around the `makemigrations` command to protect regular users from inadvertently creating erroneous schema migrations. To enable this command for plugin development, set `DEVELOPER=True` in `configuration.py`.
+
+```no-highlight
+$ ./manage.py makemigrations my_plugin 
+Migrations for 'my_plugin':
+  /home/jstretch/animal_sounds/my_plugin/migrations/0001_initial.py
+    - Create model MyModel
+```
+
+Next, we can apply the migration to the database with the `migrate` command:
+
+```no-highlight
+$ ./manage.py migrate my_plugin
+Operations to perform:
+  Apply all migrations: my_plugin
+Running migrations:
+  Applying my_plugin.0001_initial... OK
+```
+
+For more information about database migrations, see the [Django documentation](https://docs.djangoproject.com/en/stable/topics/migrations/).
+
+## Feature Mixins Reference
+
+!!! warning
+    Please note that only the classes which appear in this documentation are currently supported. Although other classes may be present within the `features` module, they are not yet supported for use by plugins.
+
+::: netbox.models.features.ChangeLoggingMixin
+
+::: netbox.models.features.CustomLinksMixin
+
+::: netbox.models.features.CustomFieldsMixin
+
+::: netbox.models.features.CustomValidationMixin
+
+::: netbox.models.features.ExportTemplatesMixin
+
+::: netbox.models.features.JournalingMixin
+
+::: netbox.models.features.TagsMixin
+
+::: netbox.models.features.WebhooksMixin
+
+## Choice Sets
+
+For model fields which support the selection of one or more values from a predefined list of choices, NetBox provides the `ChoiceSet` utility class. This can be used in place of a regular choices tuple to provide enhanced functionality, namely dynamic configuration and colorization. (See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/models/fields/#choices) on the `choices` parameter for supported model fields.)
+
+To define choices for a model field, subclass `ChoiceSet` and define a tuple named `CHOICES`, of which each member is a two- or three-element tuple. These elements are:
+
+* The database value
+* The corresponding human-friendly label
+* The assigned color (optional)
+
+A complete example is provided below.
+
+!!! note
+    Authors may find it useful to declare each of the database values as constants on the class, and reference them within `CHOICES` members. This convention allows the values to be referenced from outside the class, however it is not strictly required.
+
+### Dynamic Configuration
+
+Some model field choices in NetBox can be configured by an administrator. For example, the default values for the Site model's `status` field can be replaced or supplemented with custom choices. To enable dynamic configuration for a ChoiceSet subclass, define its `key` as a string specifying the model and field name to which it applies. For example:
+
+```python
+from utilities.choices import ChoiceSet
+
+class StatusChoices(ChoiceSet):
+    key = 'MyModel.status'
+```
+
+To extend or replace the default values for this choice set, a NetBox administrator can then reference it under the [`FIELD_CHOICES`](../../configuration/optional-settings.md#field_choices) configuration parameter. For example, the `status` field on `MyModel` in `my_plugin` would be referenced as:
+
+```python
+FIELD_CHOICES = {
+    'my_plugin.MyModel.status': (
+        # Custom choices
+    )
+}
+```
+
+### Example
+
+```python
+# choices.py
+from utilities.choices import ChoiceSet
+
+class StatusChoices(ChoiceSet):
+    key = 'MyModel.status'
+
+    STATUS_FOO = 'foo'
+    STATUS_BAR = 'bar'
+    STATUS_BAZ = 'baz'
+
+    CHOICES = (
+        (STATUS_FOO, 'Foo', 'red'),
+        (STATUS_BAR, 'Bar', 'green'),
+        (STATUS_BAZ, 'Baz', 'blue'),
+    )
+```
+
+```python
+# models.py
+from django.db import models
+from .choices import StatusChoices
+
+class MyModel(models.Model):
+    status = models.CharField(
+        max_length=50,
+        choices=StatusChoices,
+        default=StatusChoices.STATUS_FOO
+    )
+```

docs/plugins/development/navigation.md

@@ -0,0 +1,50 @@
+# Navigation
+
+## Menu Items
+
+To make its views easily accessible to users, a plugin can inject items in NetBox's navigation menu under the "Plugins" header. Menu items are added by defining a list of PluginMenuItem instances. By default, this should be a variable named `menu_items` in the file `navigation.py`. An example is shown below.
+
+!!! tip
+    The path to declared menu items can be modified by setting `menu_items` in the PluginConfig instance.
+
+```python
+from extras.plugins import PluginMenuButton, PluginMenuItem
+from utilities.choices import ButtonColorChoices
+
+menu_items = (
+    PluginMenuItem(
+        link='plugins:netbox_animal_sounds:random_animal',
+        link_text='Random sound',
+        buttons=(
+            PluginMenuButton('home', 'Button A', 'fa fa-info', ButtonColorChoices.BLUE),
+            PluginMenuButton('home', 'Button B', 'fa fa-warning', ButtonColorChoices.GREEN),
+        )
+    ),
+)
+```
+
+A `PluginMenuItem` has the following attributes:
+
+| Attribute     | Required | Description                                          |
+|---------------|----------|------------------------------------------------------|
+| `link`        | Yes      | Name of the URL path to which this menu item links   |
+| `link_text`   | Yes      | The text presented to the user                       |
+| `permissions` | -        | A list of permissions required to display this link  |
+| `buttons`     | -        | An iterable of PluginMenuButton instances to include |
+
+## Menu Buttons
+
+A `PluginMenuButton` has the following attributes:
+
+| Attribute     | Required | Description                                                        |
+|---------------|----------|--------------------------------------------------------------------|
+| `link`        | Yes      | Name of the URL path to which this button links                    |
+| `title`       | Yes      | The tooltip text (displayed when the mouse hovers over the button) |
+| `icon_class`  | Yes      | Button icon CSS class*                                             |
+| `color`       | -        | One of the choices provided by `ButtonColorChoices`                |
+| `permissions` | -        | A list of permissions required to display this button              |
+
+*NetBox supports [Material Design Icons](https://materialdesignicons.com/).
+
+!!! note
+    Any buttons associated within a menu item will be shown only if the user has permission to view the link, regardless of what permissions are set on the buttons.

docs/plugins/development/rest-api.md

@@ -0,0 +1,69 @@
+# REST API
+
+Plugins can declare custom endpoints on NetBox's REST API to retrieve or manipulate models or other data. These behave very similarly to views, except that instead of rendering arbitrary content using a template, data is returned in JSON format using a serializer.
+
+Generally speaking, there aren't many NetBox-specific components to implementing REST API functionality in a plugin. NetBox employs the [Django REST Framework](https://www.django-rest-framework.org/) (DRF) for its REST API, and plugin authors will find that they can largely replicate the same patterns found in NetBox's implementation. Some brief examples are included here for reference.
+
+## Serializers
+
+Serializers are responsible for converting Python objects to JSON data suitable for conveying to consumers, and vice versa. NetBox provides the `NetBoxModelSerializer` class for use by plugins to handle the assignment of tags and custom field data. (These features can also be included ad hoc via the `CustomFieldModelSerializer` and `TaggableModelSerializer` classes.)
+
+### Example
+
+To create a serializer for a plugin model, subclass `NetBoxModelSerializer` in `api/serializers.py`. Specify the model class and the fields to include within the serializer's `Meta` class.
+
+```python
+# api/serializers.py
+from netbox.api.serializers import NetBoxModelSerializer
+from my_plugin.models import MyModel
+
+class MyModelSerializer(NetBoxModelSerializer):
+
+    class Meta:
+        model = MyModel
+        fields = ('id', 'foo', 'bar')
+```
+
+## Viewsets
+
+Just as in the user interface, a REST API view handles the business logic of displaying and interacting with NetBox objects. NetBox provides the `NetBoxModelViewSet` class, which extends DRF's built-in `ModelViewSet` to handle bulk operations and object validation.
+
+Unlike the user interface, typically only a single view set is required per model: This view set handles all request types (`GET`, `POST`, `DELETE`, etc.).
+
+### Example
+
+To create a viewset for a plugin model, subclass `NetBoxModelViewSet` in `api/views.py`, and define the `queryset` and `serializer_class` attributes.
+
+```python
+# api/views.py
+from netbox.api.viewsets import ModelViewSet
+from my_plugin.models import MyModel
+from .serializers import MyModelSerializer
+
+class MyModelViewSet(ModelViewSet):
+    queryset = MyModel.objects.all()
+    serializer_class = MyModelSerializer
+```
+
+## Routers
+
+Routers map URLs to REST API views (endpoints). NetBox does not provide any custom components for this; the [`DefaultRouter`](https://www.django-rest-framework.org/api-guide/routers/#defaultrouter) class provided by DRF should suffice for most use cases.
+
+Routers should be exposed in `api/urls.py`. This file **must** define a variable named `urlpatterns`.
+
+### Example
+
+```python
+# api/urls.py
+from rest_framework import routers
+from .views import MyModelViewSet
+
+router = routers.DefaultRouter()
+router.register('my-model', MyModelViewSet)
+urlpatterns = router.urls
+```
+
+This will make the plugin's view accessible at `/api/plugins/my-plugin/my-model/`.
+
+!!! warning
+    The examples provided here are intended to serve as a minimal reference implementation only. This documentation does not address authentication, performance, or myriad other concerns that plugin authors may need to address.

docs/plugins/development/tables.md

@@ -0,0 +1,88 @@
+# Tables
+
+NetBox employs the [`django-tables2`](https://django-tables2.readthedocs.io/) library for rendering dynamic object tables. These tables display lists of objects, and can be sorted and filtered by various parameters.
+
+## NetBoxTable
+
+To provide additional functionality beyond what is supported by the stock `Table` class in `django-tables2`, NetBox provides the `NetBoxTable` class. This custom table class includes support for:
+
+* User-configurable column display and ordering
+* Custom field & custom link columns
+* Automatic prefetching of related objects
+
+It also includes several default columns:
+
+* `pk` - A checkbox for selecting the object associated with each table row (where applicable)
+* `id` - The object's numeric database ID, as a hyperlink to the object's view (hidden by default)
+* `actions` - A dropdown menu presenting object-specific actions available to the user
+
+### Example
+
+```python
+# tables.py
+import django_tables2 as tables
+from netbox.tables import NetBoxTable
+from .models import MyModel
+
+class MyModelTable(NetBoxTable):
+    name = tables.Column(
+        linkify=True
+    )
+    ...
+
+    class Meta(NetBoxTable.Meta):
+        model = MyModel
+        fields = ('pk', 'id', 'name', ...)
+        default_columns = ('pk', 'name', ...)
+```
+
+### Table Configuration
+
+The NetBoxTable class features dynamic configuration to allow users to change their column display and ordering preferences. To configure a table for a specific request, simply call its `configure()` method and pass the current HTTPRequest object. For example:
+
+```python
+table = MyModelTable(data=MyModel.objects.all())
+table.configure(request)
+```
+
+This will automatically apply any user-specific preferences for the table. (If using a generic view provided by NetBox, table configuration is handled automatically.)
+
+## Columns
+
+The table column classes listed below are supported for use in plugins. These classes can be imported from `netbox.tables.columns`.
+
+::: netbox.tables.BooleanColumn
+    selection:
+      members: false
+
+::: netbox.tables.ChoiceFieldColumn
+    selection:
+      members: false
+
+::: netbox.tables.ColorColumn
+    selection:
+      members: false
+
+::: netbox.tables.ColoredLabelColumn
+    selection:
+      members: false
+
+::: netbox.tables.ContentTypeColumn
+    selection:
+      members: false
+
+::: netbox.tables.ContentTypesColumn
+    selection:
+      members: false
+
+::: netbox.tables.MarkdownColumn
+    selection:
+      members: false
+
+::: netbox.tables.TagColumn
+    selection:
+      members: false
+
+::: netbox.tables.TemplateColumn
+    selection:
+      members: false

docs/plugins/development/templates.md

@@ -0,0 +1,241 @@
+# Templates
+
+Templates are used to render HTML content generated from a set of context data. NetBox provides a set of built-in templates suitable for use in plugin views. Plugin authors can extend these templates to minimize the work needed to create custom templates while ensuring that the content they produce matches NetBox's layout and style. These templates are all written in the [Django Template Language (DTL)](https://docs.djangoproject.com/en/stable/ref/templates/language/).
+
+## Standard Blocks
+
+The following template blocks are available on all templates.
+
+| Name           | Required | Description                                                         |
+|----------------|----------|---------------------------------------------------------------------|
+| `title`        | Yes      | Page title                                                          |
+| `content`      | Yes      | Page content                                                        |
+| `head`         | -        | Content to include in the HTML `<head>` element                     |
+| `footer`       | -        | Page footer content                                                 |
+| `footer_links` | -        | Links section of the page footer                                    |
+| `javascript`   | -        | Javascript content included at the end of the HTML `<body>` element |
+
+!!! note
+    For more information on how template blocks work, consult the [Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#block).
+
+## Base Templates
+
+### layout.html
+
+Path: `base/layout.html`
+
+NetBox provides a base template to ensure a consistent user experience, which plugins can extend with their own content. This is a general-purpose template that can be used when none of the function-specific templates below are suitable.
+
+#### Blocks
+
+| Name      | Required | Description                |
+|-----------|----------|----------------------------|
+| `header`  | -        | Page header                |
+| `tabs`    | -        | Horizontal navigation tabs |
+| `modals`  | -        | Bootstrap 5 modal elements |
+
+#### Example
+
+An example of a plugin template which extends `layout.html` is included below.
+
+```jinja2
+{% extends 'base/layout.html' %}
+
+{% block header %}
+  <h1>My Custom Header</h1>
+{% endblock header %}
+
+{% block content %}
+  <p>{{ some_plugin_context_var }}</p>
+{% endblock content %}
+```
+
+The first line of the template instructs Django to extend the NetBox base template, and the `block` sections inject our custom content within its `header` and `content` blocks.
+
+!!! note
+    Django renders templates with its own custom [template language](https://docs.djangoproject.com/en/stable/topics/templates/#the-django-template-language). This is very similar to Jinja2, however there are some important distinctions of which authors should be aware. Be sure to familiarize yourself with Django's template language before attempting to create new templates.
+
+## Generic View Templates
+
+### object.html
+
+Path: `generic/object.html`
+
+This template is used by the `ObjectView` generic view to display a single object.
+
+#### Blocks
+
+| Name                | Required | Description                                  |
+|---------------------|----------|----------------------------------------------|
+| `breadcrumbs`       | -        | Breadcrumb list items (HTML `<li>` elements) |
+| `object_identifier` | -        | A unique identifier (string) for the object  |
+| `extra_controls`    | -        | Additional action buttons to display         |
+| `extra_tabs`        | -        | Additional tabs to include                   |
+
+#### Context
+
+| Name     | Required | Description                      |
+|----------|----------|----------------------------------|
+| `object` | Yes      | The object instance being viewed |
+
+### object_edit.html
+
+Path: `generic/object_edit.html`
+
+This template is used by the `ObjectEditView` generic view to create or modify a single object.
+
+#### Blocks
+
+| Name             | Required | Description                                           |
+|------------------|----------|-------------------------------------------------------|
+| `form`           | -        | Custom form content (within the HTML `<form>` element |
+| `buttons`        | -        | Form submission buttons                               |
+
+#### Context
+
+| Name         | Required | Description                                                     |
+|--------------|----------|-----------------------------------------------------------------|
+| `object`     | Yes      | The object instance being modified (or none, if creating)       |
+| `form`       | Yes      | The form class for creating/modifying the object                |
+| `return_url` | Yes      | The URL to which the user is redirect after submitting the form |
+
+### object_delete.html
+
+Path: `generic/object_delete.html`
+
+This template is used by the `ObjectDeleteView` generic view to delete a single object.
+
+#### Blocks
+
+None
+
+#### Context
+
+| Name         | Required | Description                                                     |
+|--------------|----------|-----------------------------------------------------------------|
+| `object`     | Yes      | The object instance being deleted                               |
+| `form`       | Yes      | The form class for confirming the object's deletion             |
+| `return_url` | Yes      | The URL to which the user is redirect after submitting the form |
+
+### object_list.html
+
+Path: `generic/object_list.html`
+
+This template is used by the `ObjectListView` generic view to display a filterable list of multiple objects.
+
+#### Blocks
+
+| Name             | Required | Description                                                        |
+|------------------|----------|--------------------------------------------------------------------|
+| `extra_controls` | -        | Additional action buttons                                          |
+| `bulk_buttons`   | -        | Additional bulk action buttons to display beneath the objects list |
+
+#### Context
+
+| Name          | Required | Description                                                                                 |
+|---------------|----------|---------------------------------------------------------------------------------------------|
+| `model`       | Yes      | The object class                                                                            |
+| `table`       | Yes      | The table class used for rendering the list of objects                                      |
+| `permissions` | Yes      | A mapping of add, change, and delete permissions for the current user                       |
+| `actions`     | Yes      | A list of buttons to display (`add`, `import`, `export`, `bulk_edit`, and/or `bulk_delete`) |
+| `filter_form` | -        | The bound filterset form for filtering the objects list                                     |
+| `return_url`  | -        | The return URL to pass when submitting a bulk operation form                                |
+
+### bulk_import.html
+
+Path: `generic/bulk_import.html`
+
+This template is used by the `BulkImportView` generic view to import multiple objects at once from CSV data.
+
+#### Blocks
+
+None
+
+#### Context
+
+| Name         | Required | Description                                                  |
+|--------------|----------|--------------------------------------------------------------|
+| `model`      | Yes      | The object class                                             |
+| `form`       | Yes      | The CSV import form class                                    |
+| `return_url` | -        | The return URL to pass when submitting a bulk operation form |
+| `fields`     | -        | A dictionary of form fields, to display import options       |
+
+### bulk_edit.html
+
+Path: `generic/bulk_edit.html`
+
+This template is used by the `BulkEditView` generic view to modify multiple objects simultaneously.
+
+#### Blocks
+
+None
+
+#### Context
+
+| Name         | Required | Description                                                     |
+|--------------|----------|-----------------------------------------------------------------|
+| `model`      | Yes      | The object class                                                |
+| `form`       | Yes      | The bulk edit form class                                        |
+| `table`      | Yes      | The table class used for rendering the list of objects          |
+| `return_url` | Yes      | The URL to which the user is redirect after submitting the form |
+
+### bulk_delete.html
+
+Path: `generic/bulk_delete.html`
+
+This template is used by the `BulkDeleteView` generic view to delete multiple objects simultaneously.
+
+#### Blocks
+
+| Name            | Required | Description                           |
+|-----------------|----------|---------------------------------------|
+| `message_extra` | -        | Supplementary warning message content |
+
+#### Context
+
+| Name         | Required | Description                                                     |
+|--------------|----------|-----------------------------------------------------------------|
+| `model`      | Yes      | The object class                                                |
+| `form`       | Yes      | The bulk delete form class                                      |
+| `table`      | Yes      | The table class used for rendering the list of objects          |
+| `return_url` | Yes      | The URL to which the user is redirect after submitting the form |
+
+## Tags
+
+The following custom template tags are available in NetBox.
+
+!!! info
+    These are loaded automatically by the template backend: You do _not_ need to include a `{% load %}` tag in your template to activate them.
+
+::: utilities.templatetags.builtins.tags.badge
+
+::: utilities.templatetags.builtins.tags.checkmark
+
+::: utilities.templatetags.builtins.tags.tag
+
+## Filters
+
+The following custom template filters are available in NetBox.
+
+!!! info
+    These are loaded automatically by the template backend: You do _not_ need to include a `{% load %}` tag in your template to activate them.
+
+::: utilities.templatetags.builtins.filters.bettertitle
+
+::: utilities.templatetags.builtins.filters.content_type
+
+::: utilities.templatetags.builtins.filters.content_type_id
+
+::: utilities.templatetags.builtins.filters.meta
+
+::: utilities.templatetags.builtins.filters.placeholder
+
+::: utilities.templatetags.builtins.filters.render_json
+
+::: utilities.templatetags.builtins.filters.render_markdown
+
+::: utilities.templatetags.builtins.filters.render_yaml
+
+::: utilities.templatetags.builtins.filters.split
+
+::: utilities.templatetags.builtins.filters.tzoffset

docs/plugins/development/views.md

@@ -0,0 +1,177 @@
+# Views
+
+## Writing Views
+
+If your plugin will provide its own page or pages within the NetBox web UI, you'll need to define views. A view is a piece of business logic which performs an action and/or renders a page when a request is made to a particular URL. HTML content is rendered using a [template](./templates.md). Views are typically defined in `views.py`, and URL patterns in `urls.py`.
+
+As an example, let's write a view which displays a random animal and the sound it makes. We'll use Django's generic `View` class to minimize the amount of boilerplate code needed.
+
+```python
+from django.shortcuts import render
+from django.views.generic import View
+from .models import Animal
+
+class RandomAnimalView(View):
+    """
+    Display a randomly-selected animal.
+    """
+    def get(self, request):
+        animal = Animal.objects.order_by('?').first()
+        return render(request, 'netbox_animal_sounds/animal.html', {
+            'animal': animal,
+        })
+```
+
+This view retrieves a random Animal instance from the database and passes it as a context variable when rendering a template named `animal.html`. HTTP `GET` requests are handled by the view's `get()` method, and `POST` requests are handled by its `post()` method.
+
+Our example above is extremely simple, but views can do just about anything. They are generally where the core of your plugin's functionality will reside. Views also are not limited to returning HTML content: A view could return a CSV file or image, for instance. For more information on views, see the [Django documentation](https://docs.djangoproject.com/en/stable/topics/class-based-views/).
+
+### URL Registration
+
+To make the view accessible to users, we need to register a URL for it. We do this in `urls.py` by defining a `urlpatterns` variable containing a list of paths.
+
+```python
+from django.urls import path
+from . import views
+
+urlpatterns = [
+    path('random/', views.RandomAnimalView.as_view(), name='random_animal'),
+]
+```
+
+A URL pattern has three components:
+
+* `route` - The unique portion of the URL dedicated to this view
+* `view` - The view itself
+* `name` - A short name used to identify the URL path internally
+
+This makes our view accessible at the URL `/plugins/animal-sounds/random/`. (Remember, our `AnimalSoundsConfig` class sets our plugin's base URL to `animal-sounds`.) Viewing this URL should show the base NetBox template with our custom content inside it.
+
+### View Classes
+
+NetBox provides several generic view classes (documented below) to facilitate common operations, such as creating, viewing, modifying, and deleting objects. Plugins can subclass these views for their own use.
+
+| View Class         | Description                    |
+|--------------------|--------------------------------|
+| `ObjectView`       | View a single object           |
+| `ObjectEditView`   | Create or edit a single object |
+| `ObjectDeleteView` | Delete a single object         |
+| `ObjectListView`   | View a list of objects         |
+| `BulkImportView`   | Import a set of new objects    |
+| `BulkEditView`     | Edit multiple objects          |
+| `BulkDeleteView`   | Delete multiple objects        |
+
+!!! warning
+    Please note that only the classes which appear in this documentation are currently supported. Although other classes may be present within the `views.generic` module, they are not yet supported for use by plugins.
+
+#### Example Usage
+
+```python
+# views.py
+from netbox.views.generic import ObjectEditView
+from .models import Thing
+
+class ThingEditView(ObjectEditView):
+    queryset = Thing.objects.all()
+    template_name = 'myplugin/thing.html'
+    ...
+```
+## Object Views
+
+Below are the class definitions for NetBox's object views. These views handle CRUD actions for individual objects. The view, add/edit, and delete views each inherit from `BaseObjectView`, which is not intended to be used directly.
+
+::: netbox.views.generic.base.BaseObjectView
+
+::: netbox.views.generic.ObjectView
+    selection:
+      members:
+        - get_object
+        - get_template_name
+
+::: netbox.views.generic.ObjectEditView
+    selection:
+      members:
+        - get_object
+        - alter_object
+
+::: netbox.views.generic.ObjectDeleteView
+    selection:
+      members:
+        - get_object
+
+## Multi-Object Views
+
+Below are the class definitions for NetBox's multi-object views. These views handle simultaneous actions for sets objects. The list, import, edit, and delete views each inherit from `BaseMultiObjectView`, which is not intended to be used directly.
+
+::: netbox.views.generic.base.BaseMultiObjectView
+
+::: netbox.views.generic.ObjectListView
+    selection:
+      members:
+        - get_table
+        - export_table
+        - export_template
+
+::: netbox.views.generic.BulkImportView
+    selection:
+      members: false
+
+::: netbox.views.generic.BulkEditView
+    selection:
+      members: false
+
+::: netbox.views.generic.BulkDeleteView
+    selection:
+      members:
+        - get_form
+
+## Feature Views
+
+These views are provided to enable or enhance certain NetBox model features, such as change logging or journaling. These typically do not need to be subclassed: They can be used directly e.g. in a URL path.
+
+::: netbox.views.generic.ObjectChangeLogView
+    selection:
+      members:
+        - get_form
+
+::: netbox.views.generic.ObjectJournalView
+    selection:
+      members:
+        - get_form
+
+## Extending Core Views
+
+Plugins can inject custom content into certain areas of the detail views of applicable models. This is accomplished by subclassing `PluginTemplateExtension`, designating a particular NetBox model, and defining the desired methods to render custom content. Four methods are available:
+
+* `left_page()` - Inject content on the left side of the page
+* `right_page()` - Inject content on the right side of the page
+* `full_width_page()` - Inject content across the entire bottom of the page
+* `buttons()` - Add buttons to the top of the page
+
+Additionally, a `render()` method is available for convenience. This method accepts the name of a template to render, and any additional context data you want to pass. Its use is optional, however.
+
+When a PluginTemplateExtension is instantiated, context data is assigned to `self.context`. Available data include:
+
+* `object` - The object being viewed
+* `request` - The current request
+* `settings` - Global NetBox settings
+* `config` - Plugin-specific configuration parameters
+
+For example, accessing `{{ request.user }}` within a template will return the current user.
+
+Declared subclasses should be gathered into a list or tuple for integration with NetBox. By default, NetBox looks for an iterable named `template_extensions` within a `template_content.py` file. (This can be overridden by setting `template_extensions` to a custom value on the plugin's PluginConfig.) An example is below.
+
+```python
+from extras.plugins import PluginTemplateExtension
+from .models import Animal
+
+class SiteAnimalCount(PluginTemplateExtension):
+    model = 'dcim.site'
+
+    def right_page(self):
+        return self.render('netbox_animal_sounds/inc/animal_count.html', extra_context={
+            'animal_count': Animal.objects.count(),
+        })
+
+template_extensions = [SiteAnimalCount]
+```

docs/reference/conditions.md

@@ -0,0 +1,125 @@
+# Conditions
+
+Conditions are NetBox's mechanism for evaluating whether a set data meets a prescribed set of conditions. It allows the author to convey simple logic by declaring an arbitrary number of attribute-value-operation tuples nested within a hierarchy of logical AND and OR statements.
+
+## Conditions
+
+A condition is expressed as a JSON object with the following keys:
+
+| Key name | Required | Default | Description |
+|----------|----------|---------|-------------|
+| attr     | Yes      | -       | Name of the key within the data being evaluated |
+| value    | Yes      | -       | The reference value to which the given data will be compared |
+| op       | No       | `eq`    | The logical operation to be performed |
+| negate   | No       | False   | Negate (invert) the result of the condition's evaluation |
+
+### Available Operations
+
+* `eq`: Equals
+* `gt`: Greater than
+* `gte`: Greater than or equal to
+* `lt`: Less than
+* `lte`: Less than or equal to
+* `in`: Is present within a list of values
+* `contains`: Contains the specified value
+
+### Accessing Nested Keys
+
+To access nested keys, use dots to denote the path to the desired attribute. For example, assume the following data:
+
+```json
+{
+  "a": {
+    "b": {
+      "c": 123
+    }
+  }
+}
+```
+
+The following condition will evaluate as true:
+
+```json
+{
+  "attr": "a.b.c",
+  "value": 123
+}
+```
+
+### Examples
+
+`name` equals "foo":
+
+```json
+{
+  "attr": "name",
+  "value": "foo"
+}
+```
+
+`name` does not equal "foo"
+
+```json
+{
+  "attr": "name",
+  "value": "foo",
+  "negate": true
+}
+```
+
+`asn` is greater than 65000:
+
+```json
+{
+  "attr": "asn",
+  "value": 65000,
+  "op": "gt"
+}
+```
+
+`status` is not "planned" or "staging":
+
+```json
+{
+  "attr": "status.value",
+  "value": ["planned", "staging"],
+  "op": "in",
+  "negate": true
+}
+```
+
+!!! note "Evaluating static choice fields"
+    Pay close attention when evaluating static choice fields, such as the `status` field above. These fields typically render as a dictionary specifying both the field's raw value (`value`) and its human-friendly label (`label`). be sure to specify on which of these you want to match.
+
+## Condition Sets
+
+Multiple conditions can be combined into nested sets using AND or OR logic. This is done by declaring a JSON object with a single key (`and` or `or`) containing a list of condition objects and/or child condition sets.
+
+### Examples
+
+`status` is "active" and `primary_ip` is defined _or_ the "exempt" tag is applied.
+
+```json
+{
+  "or": [
+    {
+      "and": [
+        {
+          "attr": "status.value",
+          "value": "active"
+        },
+        {
+          "attr": "primary_ip",
+          "value": "",
+          "negate": true
+        }
+      ]
+    },
+    {
+      "attr": "tags",
+      "value": "exempt",
+      "op": "contains"
+    }
+  ]
+}
+```