Merge pull request #9354 from netbox-community/develop

Release v3.2.3

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -14,7 +14,7 @@ body:
     attributes:
       label: NetBox version
       description: What version of NetBox are you currently running?
-      placeholder: v3.1.7
+      placeholder: v3.2.3
     validations:
       required: true
   - type: dropdown
@@ -22,9 +22,9 @@ body:
       label: Python version
       description: What version of Python are you currently running?
       options:
-        - "3.7"
         - "3.8"
         - "3.9"
+        - "3.10"
     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.1.7
+      placeholder: v3.2.3
     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
+        pip install pycodestyle coverage tblib
 
     - 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*

.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

CHANGELOG.md

@@ -1 +1 @@
-The changelog has been moved to the [project release notes](https://netbox.readthedocs.io/en/stable/release-notes/).
+The changelog has been moved to the [project release notes](https://docs.netbox.dev/en/stable/release-notes/).

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/).
@@ -106,7 +99,7 @@ appropriate labels will be applied for categorization.
 ## Submitting Pull Requests
 
 * If you're interested in contributing to NetBox, be sure to check out our
-[getting started](https://netbox.readthedocs.io/en/stable/development/getting-started/)
+[getting started](https://docs.netbox.dev/en/stable/development/getting-started/)
 documentation for tips on setting up your development environment.
 
 * Be sure to open an issue **before** starting work on a pull request, and
@@ -178,7 +171,7 @@ an effort to circumvent the bot: Doing so will not remove the stale label.
   the understanding that all contributions are submitted under the Apache 2.0
   license and that your employer may not make claim to any contributions.
   Contributions include code work, issue management, and community support. All
-  development must be in accordance with our [development guidance](https://netbox.readthedocs.io/en/stable/development/).
+  development must be in accordance with our [development guidance](https://docs.netbox.dev/en/stable/development/).
 
 * Maintainers are expected to attend (where feasible) our biweekly ~30-minute
   sync to review agenda items. This meeting provides opportunity to present and

README.md

@@ -49,7 +49,7 @@ 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).
 
-The complete documentation for NetBox can be found at [Read the Docs](https://netbox.readthedocs.io/en/stable/). A public demo instance is available at https://demo.netbox.dev.
+The complete documentation for NetBox can be found at [docs.netbox.dev](https://docs.netbox.dev/). A public demo instance is available at https://demo.netbox.dev.
 
 <div align="center">
   <h4>Thank you to our sponsors!</h4>
@@ -60,6 +60,8 @@ The complete documentation for NetBox can be found at [Read the Docs](https://ne
   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
   [![NS1](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/ns1.png)](https://ns1.com/)
   <br />
+  [![Sentry](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/sentry.png)](https://sentry.io/)
+  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
   [![Stellar Technologies](https://raw.githubusercontent.com/wiki/netbox-community/netbox/images/sponsors/stellar.png)](https://stellar.tech/)
 
 </div>
@@ -68,11 +70,10 @@ 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
 
-Please see [the documentation](https://netbox.readthedocs.io/en/stable/) for
+Please see [the documentation](https://docs.netbox.dev/) for
 instructions on installing NetBox. To upgrade NetBox, please download the
 [latest release](https://github.com/netbox-community/netbox/releases) and
 run `upgrade.sh`.

SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## No Warranty
+
+Per the terms of the Apache 2 license, NetBox is offered "as is" and without any guarantee or warranty pertaining to its operation. While every reasonable effort is made by its maintainers to ensure the product remains free of security vulnerabilities, users are ultimately responsible for conducting their own evaluations of each software release.
+
+## Recommendations
+
+Administrators are encouraged to adhere to industry best practices concerning the secure operation of software, such as:
+
+* Do not expose your NetBox installation to the public Internet
+* Do not permit multiple users to share an account
+* Enforce minimum password complexity requirements for local accounts
+* Prohibit access to your database from clients other than the NetBox application
+* Keep your deployment updated to the most recent stable release
+
+## Reporting a Suspected Vulnerability
+
+If you believe you've uncovered a security vulnerability and wish to report it confidentially, you may do so via email. Please note that any reported vulnerabilities **MUST** meet all the following conditions:
+
+* Affects the most recent stable release of NetBox, or a current beta release
+* Affects a NetBox instance installed and configured per the official documentation
+* Is reproducible following a prescribed set of instructions
+
+Please note that we **DO NOT** accept reports generated by automated tooling which merely suggest that a file or file(s) _may_ be vulnerable under certain conditions, as these are most often innocuous.
+
+If you believe that you've found a vulnerability which meets all of these conditions, please email a brief description of the suspected bug and instructions for reproduction to **security@netbox.dev**. For any security concerns regarding NetBox deployed via Docker, please see the [netbox-docker](https://github.com/netbox-community/netbox-docker) project.
+
+### Bug Bounties
+
+As NetBox is provided as free open source software, we do not offer any monetary compensation for vulnerability or bug reports, however your contributions are greatly appreciated.

base_requirements.txt

@@ -1,6 +1,6 @@
 # The Python web framework on which NetBox is built
 # https://github.com/django/django
-Django<4.0
+Django
 
 # Django middleware which permits cross-domain API requests
 # https://github.com/OttoYiu/django-cors-headers
@@ -82,8 +82,12 @@ markdown-include
 # https://github.com/squidfunk/mkdocs-material
 mkdocs-material
 
+# Introspection for embedded code
+# https://github.com/mkdocstrings/mkdocstrings
+mkdocstrings[python-legacy]
+
 # Library for manipulating IP prefixes and addresses
-# https://github.com/drkjam/netaddr
+# https://github.com/netaddr/netaddr
 netaddr
 
 # Fork of PIL (Python Imaging Library) for image processing
@@ -98,6 +102,10 @@ psycopg2-binary
 # https://github.com/yaml/pyyaml
 PyYAML
 
+# Sentry SDK
+# https://github.com/getsentry/sentry-python
+sentry-sdk
+
 # Social authentication framework
 # https://github.com/python-social-auth/social-core
 social-auth-core
@@ -113,3 +121,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

contrib/netbox-rq.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=NetBox Request Queue Worker
-Documentation=https://netbox.readthedocs.io/en/stable/
+Documentation=https://docs.netbox.dev/
 After=network-online.target
 Wants=network-online.target
 

contrib/netbox.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=NetBox WSGI Service
-Documentation=https://netbox.readthedocs.io/en/stable/
+Documentation=https://docs.netbox.dev/
 After=network-online.target
 Wants=network-online.target
 

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

@@ -0,0 +1,88 @@
+# Microsoft Azure AD
+
+This guide explains how to configure single sign-on (SSO) support for NetBox using [Microsoft Azure Active Directory (AD)](https://azure.microsoft.com/en-us/services/active-directory/) as an authentication backend.
+
+## Azure AD Configuration
+
+### 1. Create a test user (optional)
+
+Create a new user in AD to be used for testing. You can skip this step if you already have a suitable account created.
+
+### 2. Create an app registration
+
+Under the Azure Active Directory dashboard, navigate to **Add > App registration**.
+
+![Add an app registration](../../media/authentication/azure_ad_add_app_registration.png)
+
+Enter a name for the registration (e.g. "NetBox") and ensure that the "single tenant" option is selected.
+
+Under "Redirect URI", select "Web" for the platform and enter the path to your NetBox installation, ending with `/oauth/complete/azuread-oauth2/`. Note that this URI **must** begin with `https://` unless you are referencing localhost (for development purposes).
+
+![App registration parameters](../../media/authentication/azure_ad_app_registration.png)
+
+Once finished, make note of the application (client) ID; this will be used when configuring NetBox.
+
+![Completed app registration](../../media/authentication/azure_ad_app_registration_created.png)
+
+!!! tip "Multitenant authentication"
+    NetBox also supports multitenant authentication via Azure AD, however it requires a different backend and an additional configuration parameter. Please see the [`python-social-auth` documentation](https://python-social-auth.readthedocs.io/en/latest/backends/azuread.html#tenant-support) for details concerning multitenant authentication.
+
+### 3. Create a secret
+
+When viewing the newly-created app registration, click the "Add a certificate or secret" link under "Client credentials". Under the "Client secrets" tab, click the "New client secret" button.
+
+![Add a client secret](../../media/authentication/azure_ad_add_client_secret.png)
+
+You can optionally specify a description and select a lifetime for the secret.
+
+![Client secret parameters](../../media/authentication/azure_ad_client_secret.png)
+
+Once finished, make note of the secret value (not the secret ID); this will be used when configuring NetBox.
+
+![Client secret parameters](../../media/authentication/azure_ad_client_secret_created.png)
+
+## NetBox Configuration
+
+### 1. Enter configuration parameters
+
+Enter the following configuration parameters in `configuration.py`, substituting your own values:
+
+```python
+REMOTE_AUTH_BACKEND = 'social_core.backends.azuread.AzureADOAuth2'
+SOCIAL_AUTH_AZUREAD_OAUTH2_KEY = '{APPLICATION_ID}'
+SOCIAL_AUTH_AZUREAD_OAUTH2_SECRET = '{SECRET_VALUE}'
+```
+
+### 2. Restart NetBox
+
+Restart the NetBox services so that the new configuration takes effect. This is typically done with the command below:
+
+```no-highlight
+sudo systemctl restart netbox
+```
+
+## Testing
+
+Log out of NetBox if already authenticated, and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using Azure AD. Click that link.
+
+![NetBox Azure AD login form](../../media/authentication/netbox_azure_ad_login.png)
+
+You should be redirected to Microsoft's authentication portal. Enter the username/email and password of your test account to continue. You may also be prompted to grant this application access to your account.
+
+![NetBox Azure AD login form](../../media/authentication/azure_ad_login_portal.png)
+
+If successful, you will be redirected back to the NetBox UI, and will be logged in as the AD user. You can verify this by navigating to your profile (using the button at top right).
+
+This user account has been replicated locally to NetBox, and can now be assigned groups and permissions within the NetBox admin UI.
+
+## Troubleshooting
+
+### Redirect URI does not Match
+
+Azure requires that the authenticating client request a redirect URI that matches what you've configured for the app in step two. This URI **must** begin with `https://` (unless using `localhost` for the domain).
+
+If Azure complains that the requested URI starts with `http://` (not HTTPS), it's likely that your HTTP server is misconfigured or sitting behind a load balancer, so NetBox is not aware that HTTPS is being use. To force the use of an HTTPS redirect URI, set `SOCIAL_AUTH_REDIRECT_IS_HTTPS = True` in `configuration.py` per the [python-social-auth docs](https://python-social-auth.readthedocs.io/en/latest/configuration/settings.html#processing-redirects-and-urlopen).
+
+### Not Logged in After Authenticating
+
+If you are redirected to the NetBox UI after authenticating successfully, but are _not_ logged in, double-check the configured backend and app registration. The instructions in this guide pertain only to the `azuread.AzureADOAuth2` backend using a single-tenant app registration.

docs/administration/authentication/okta.md

@@ -0,0 +1,70 @@
+# Okta
+
+This guide explains how to configure single sign-on (SSO) support for NetBox using [Okta](https://www.okta.com/) as an authentication backend.
+
+## Okta Configuration
+
+!!! tip "Okta developer account"
+    Okta offers free developer accounts at <https://developer.okta.com/>.
+
+### 1. Create a test user (optional)
+
+Create a new user in the Okta admin portal to be used for testing. You can skip this step if you already have a suitable account created.
+
+### 2. Create an app registration
+
+Within the Okta administration dashboard, navigate to  **Applications > Applications**, and click the "Create App Integration" button. Select "OIDC" as the sign-in method, and "Web application" for the application type.
+
+![Create an app registration](../../media/authentication/okta_create_app_registration.png)
+
+On the next page, give the app integration a name (e.g. "NetBox") and specify the sign-in and sign-out URIs. These URIs should follow the formats below:
+
+* Sign-in URI: `https://{netbox}/oauth/complete/okta-openidconnect/`
+* Sign-out URI: `https://{netbox}/oauth/disconnect/okta-openidconnect/`
+
+![Web app integration](../../media/authentication/okta_web_app_integration.png)
+
+Under "Assignments," select the controlled access setting most appropriate for your organization. Click "Save" to complete the creation.
+
+Once finished, note the following parameters. These will be used to configured NetBox.
+
+* Client ID
+* Client secret
+* Okta domain
+
+![Okta integration parameters](../../media/authentication/okta_integration_parameters.png)
+
+## NetBox Configuration
+
+### 1. Enter configuration parameters
+
+Enter the following configuration parameters in `configuration.py`, substituting your own values:
+
+```python
+REMOTE_AUTH_BACKEND = 'social_core.backends.okta_openidconnect.OktaOpenIdConnect'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_KEY = '{Client ID}'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_SECRET = '{Client secret}'
+SOCIAL_AUTH_OKTA_OPENIDCONNECT_API_URL = 'https://{Okta domain}/oauth2/'
+```
+
+### 2. Restart NetBox
+
+Restart the NetBox services so that the new configuration takes effect. This is typically done with the command below:
+
+```no-highlight
+sudo systemctl restart netbox
+```
+
+## Testing
+
+Log out of NetBox if already authenticated, and click the "Log In" button at top right. You should see the normal login form as well as an option to authenticate using Okta. Click that link.
+
+![NetBox Okta login form](../../media/authentication/netbox_okta_login.png)
+
+You should be redirected to Okta's authentication portal. Enter the username/email and password of your test account to continue. You may also be prompted to grant this application access to your account.
+
+![Okta login portal](../../media/authentication/okta_login_portal.png)
+
+If successful, you will be redirected back to the NetBox UI, and will be logged in as the Okta user. You can verify this by navigating to your profile (using the button at top right).
+
+This user account has been replicated locally to NetBox, and can now be assigned groups and permissions within the NetBox admin UI.

docs/administration/authentication/overview.md

@@ -4,7 +4,7 @@
 
 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.
+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
 
@@ -16,7 +16,7 @@ NetBox may be configured to provide user authenticate via a remote backend in ad
 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.
+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
 

docs/administration/error-reporting.md

@@ -0,0 +1,46 @@
+# Error Reporting
+
+## Sentry
+
+### Enabling Error Reporting
+
+NetBox v3.2.3 and later support native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, simply set `SENTRY_ENABLED` to True in `configuration.py`. Errors will be sent to a Sentry ingestor maintained by the NetBox team for analysis.
+
+```python
+SENTRY_ENABLED = True
+```
+
+### Using a Custom DSN
+
+If you prefer instead to use your own Sentry ingestor, you'll need to first create a new project under your Sentry account to represent your NetBox deployment and obtain its corresponding data source name (DSN). This looks like a URL similar to the example below:
+
+```
+https://examplePublicKey@o0.ingest.sentry.io/0
+```
+
+Once you have obtained a DSN, configure Sentry in NetBox's `configuration.py` file with the following parameters:
+
+```python
+SENTRY_ENABLED = True
+SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
+```
+
+### Assigning Tags
+
+You can optionally attach one or more arbitrary tags to the outgoing error reports if desired by setting the `SENTRY_TAGS` parameter:
+
+```python
+SENTRY_TAGS = {
+    "custom.foo": "123",
+    "custom.bar": "abc",
+}
+```
+
+!!! warning "Reserved tag prefixes"
+    Avoid using any tag names which begin with `netbox.`, as this prefix is reserved by the NetBox application.
+
+### Testing
+
+Once the configuration has been saved, restart the NetBox service.
+
+To test Sentry operation, try generating a 404 (page not found) error by navigating to an invalid URL, such as `https://netbox/404-error-testing`. (Be sure that debug mode has been disabled.) After receiving a 404 response from the NetBox server, you should see the issue appear shortly in Sentry.

docs/administration/housekeeping.md

@@ -4,6 +4,7 @@ NetBox includes a `housekeeping` management command that should be run nightly.
 
 * Clearing expired authentication sessions from the database
 * Deleting changelog records older than the configured [retention time](../configuration/dynamic-settings.md#changelog_retention)
+* Deleting job result records older than the configured [retention time](../configuration/dynamic-settings.md#jobresult_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 linked from your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file.
 

docs/configuration/dynamic-settings.md

@@ -43,6 +43,18 @@ changes in the database indefinitely.
 
 ---
 
+## JOBRESULT_RETENTION
+
+Default: 90
+
+The number of days to retain job results (scripts and reports). Set this to `0` to retain
+job results in the database indefinitely.
+
+!!! warning
+    If enabling indefinite job results 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:
@@ -66,6 +78,22 @@ CUSTOM_VALIDATORS = {
 
 ---
 
+## 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

docs/configuration/error-reporting.md

@@ -0,0 +1,54 @@
+# Error Reporting Settings
+
+## SENTRY_DSN
+
+Default: None
+
+Defines a Sentry data source name (DSN) for automated error reporting. `SENTRY_ENABLED` must be True for this parameter to take effect. For example:
+
+```
+SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0"
+```
+
+---
+
+## SENTRY_ENABLED
+
+Default: False
+
+Set to True to enable automatic error reporting via [Sentry](https://sentry.io/).
+
+---
+
+## SENTRY_SAMPLE_RATE
+
+Default: 1.0 (all)
+
+The sampling rate for errors. Must be a value between 0 (disabled) and 1.0 (report on all errors).
+
+---
+
+## SENTRY_TAGS
+
+An optional dictionary of tag names and values to apply to Sentry error reports.For example:
+
+```
+SENTRY_TAGS = {
+    "custom.foo": "123",
+    "custom.bar": "abc",
+}
+```
+
+!!! warning "Reserved tag prefixes"
+    Avoid using any tag names which begin with `netbox.`, as this prefix is reserved by the NetBox application.
+
+---
+
+## SENTRY_TRACES_SAMPLE_RATE
+
+Default: 0 (disabled)
+
+The sampling rate for transactions. Must be a value between 0 (disabled) and 1.0 (report on all transactions).
+
+!!! warning "Consider performance implications"
+    A high sampling rate for transactions can induce significant performance penalties. If transaction reporting is desired, it is recommended to use a relatively low sample rate of 10% to 20% (0.1 to 0.2).

docs/configuration/index.md

@@ -1,6 +1,11 @@
 # 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.  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.
+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.
+
+!!! 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.
 

docs/configuration/optional-settings.md

@@ -13,6 +13,23 @@ ADMINS = [
 
 ---
 
+## AUTH_PASSWORD_VALIDATORS
+
+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
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'OPTIONS': {
+            'min_length': 10,
+        }
+    },
+]
+```
+
+---
+
 ## BASE_PATH
 
 Default: None
@@ -49,6 +66,21 @@ CORS_ORIGIN_WHITELIST = [
 
 ---
 
+## CSRF_TRUSTED_ORIGINS
+
+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
+CSRF_TRUSTED_ORIGINS = (
+    'http://netbox.local',
+    'https://netbox.local',
+)
+```
+
+---
+
 ## DEBUG
 
 Default: False
@@ -140,6 +172,66 @@ EXEMPT_VIEW_PERMISSIONS = ['*']
 
 ---
 
+## FIELD_CHOICES
+
+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.)
+
+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`
+* `extras.JournalEntry.kind`
+* `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`
+
+---
+
 ## HTTP_PROXIES
 
 Default: None

docs/configuration/remote-authentication.md

@@ -35,7 +35,7 @@ The list of groups to assign a new user account when created using remote authen
 
 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`.)
+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.)
 
 ---
 
@@ -43,7 +43,7 @@ A mapping of permissions to assign a new user account when created using remote
 
 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.)
+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 disabled)
 
 ---
 

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!}
 

docs/core-functionality/ipam.md

@@ -21,6 +21,7 @@
 ---
 
 {!models/ipam/fhrpgroup.md!}
+{!models/ipam/fhrpgroupassignment.md!}
 
 ---
 

docs/core-functionality/modules.md

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

docs/core-functionality/services.md

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

docs/customization/custom-scripts.md

@@ -89,6 +89,12 @@ The checkbox to commit database changes when executing a script is checked by de
 commit_default = False
 ```
 
+### `job_timeout`
+
+Set the maximum allowed runtime for the script. If not set, `RQ_DEFAULT_TIMEOUT` will be used.
+
+!!! info "This feature was introduced in v3.2.1"
+
 ## Accessing Request Data
 
 Details of the current HTTP request (the one being made to execute the script) are available as the instance attribute `self.request`. This can be used to infer, for example, the user executing the script and the client IP address:

docs/customization/custom-validation.md

@@ -105,11 +105,11 @@ from my_validators import Validator1, Validator2, Validator3
 
 CUSTOM_VALIDATORS = {
     'dcim.site': (
-        Validator1,
-        Validator2,
+        Validator1(),
+        Validator2(),
     ),
     'dcim.device': (
-        Validator3,
+        Validator3(),
     )
 }
 ```

docs/customization/reports.md

@@ -85,6 +85,20 @@ As you can see, reports are completely customizable. Validation logic can be as
 !!! warning
     Reports should never alter data: If you find yourself using the `create()`, `save()`, `update()`, or `delete()` methods on objects within reports, stop and re-evaluate what you're trying to accomplish. Note that there are no safeguards against the accidental alteration or destruction of data.
 
+## Report Attributes
+
+### `description`
+
+A human-friendly description of what your report does.
+
+### `job_timeout`
+
+Set the maximum allowed runtime for the report. If not set, `RQ_DEFAULT_TIMEOUT` will be used.
+
+!!! info "This feature was introduced in v3.2.1"
+
+## Logging
+
 The following methods are available to log results within a report:
 
 * log(message)
@@ -95,7 +109,7 @@ 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.
 

docs/development/adding-models.md

@@ -2,7 +2,7 @@
 
 ## 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:
 

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,7 @@ 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).
 
@@ -60,7 +68,7 @@ $ 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 "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.
+    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:
 
@@ -85,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
@@ -99,12 +107,13 @@ Within the `netbox/netbox/` directory, copy `configuration.example.py` to `confi
 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.
 ```
@@ -122,24 +131,36 @@ The demo data is provided in JSON format and loaded into an empty database using
 
 ## Running Tests
 
-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. 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.
+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
+$ 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 manage.py test --keepdb
 ```
 
-You can also limit the command to running only a specific subset of tests. For example, to run only IPAM and DCIM view tests:
+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 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.

docs/development/index.md

@@ -7,9 +7,8 @@ NetBox is maintained as a [GitHub project](https://github.com/netbox-community/n
 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 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.
+* [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
 

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/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/index.md

@@ -54,7 +54,7 @@ NetBox is built on the [Django](https://djangoproject.com/) Python framework and
 
 ## 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
 

docs/installation/3-netbox.md

@@ -6,8 +6,8 @@ This section of the documentation discusses installing and configuring the NetBo
 
 Begin by installing all system packages required by NetBox and its dependencies.
 
-!!! warning "Python 3.7 or later required"
-    NetBox v3.0 and v3.1 require Python 3.7, 3.8, or 3.9. It is recommended to install at least Python v3.8, as this will become the minimum supported Python version in NetBox v3.2.
+!!! warning "Python 3.8 or later required"
+    NetBox v3.2 requires Python 3.8, 3.9, or 3.10.
 
 === "Ubuntu"
 
@@ -17,16 +17,11 @@ Begin by installing all system packages required by NetBox and its dependencies.
 
 === "CentOS"
 
-    !!! warning
-        CentOS 8 does not provide Python 3.7 or later via its native package manager. You will need to install it via some other means. [Here is an example](https://tecadmin.net/install-python-3-7-on-centos-8/) of installing Python 3.7 from source.
-
-    Once you have Python 3.7 or later installed, install the remaining system packages:
-
     ```no-highlight
     sudo yum install -y gcc libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config
     ```
 
-Before continuing, check that your installed Python version is at least 3.7:
+Before continuing, check that your installed Python version is at least 3.8:
 
 ```no-highlight
 python3 -V
@@ -117,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:
@@ -234,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 is set to a lesser version,  pass the path to the supported installation as an environment variable named `PYTHON`. (Note that the environment variable must be passed _after_ the `sudo` command.)
+Note that **Python 3.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

docs/installation/4-gunicorn.md

@@ -40,7 +40,7 @@ You should see output similar to the following:
 ● netbox.service - NetBox WSGI Service
      Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
      Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
-       Docs: https://netbox.readthedocs.io/en/stable/
+       Docs: https://docs.netbox.dev/
    Main PID: 1140492 (gunicorn)
       Tasks: 19 (limit: 4683)
      Memory: 666.2M

docs/installation/index.md

@@ -11,15 +11,11 @@ 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 v3.0 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             |
+| Python     | 3.8             |
 | PostgreSQL | 10              |
 | Redis      | 4.0             |
 

docs/installation/migrating-to-systemd.md

@@ -39,7 +39,7 @@ You can use the command `systemctl status netbox` to verify that the WSGI servic
 ● netbox.service - NetBox WSGI Service
    Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
    Active: active (running) since Sat 2020-10-24 19:23:40 UTC; 25s ago
-     Docs: https://netbox.readthedocs.io/en/stable/
+     Docs: https://docs.netbox.dev/
  Main PID: 11993 (gunicorn)
     Tasks: 6 (limit: 2362)
    CGroup: /system.slice/netbox.service

docs/installation/upgrading.md

@@ -6,11 +6,11 @@ Prior to upgrading your NetBox instance, be sure to carefully review all [releas
 
 ## Update Dependencies to Required Versions
 
-NetBox v3.0 and later requires the following:
+NetBox v3.0 and later require the following:
 
 | Dependency | Minimum Version |
 |------------|-----------------|
-| Python     | 3.7             |
+| Python     | 3.8             |
 | PostgreSQL | 10              |
 | Redis      | 4.0             |
 
@@ -67,6 +67,11 @@ sudo git checkout master
 sudo git pull origin master
 ```
 
+!!! info "Checking out an older release"
+    If you need to upgrade to an older version rather than the current stable release, you can check out any valid [git tag](https://github.com/netbox-community/netbox/tags), each of which represents a release. For example, to checkout the code for NetBox v2.11.11, do:
+
+        sudo git checkout v2.11.11
+
 ## Run the Upgrade Script
 
 Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script:
@@ -76,10 +81,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:

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/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,13 +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.

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/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/virtualchassis.md

@@ -2,7 +2,8 @@
 
 A virtual chassis represents a set of devices which share a common control plane. A common example of this is a stack of switches which are connected and configured to operate as a single device. A virtual chassis must be assigned a name and may be assigned a domain.
 
-Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. One of the devices may be designated as the VC master: This device will typically be assigned a name, services, and other attributes related to managing the VC.
+Each device in the virtual chassis is referred to as a VC member, and assigned a position and (optionally) a priority. VC member devices commonly reside within the same rack, though this is not a requirement. One of the devices may be designated as the VC master: This device will typically be assigned a name, services, virtual interfaces, and other attributes related to managing the VC.
+If a VC master is defined, interfaces from all VC members are displayed when navigating to its device interfaces view. This does not include other members interfaces declared as management-only.
 
 !!! note
     It's important to recognize the distinction between a virtual chassis and a chassis-based device. A virtual chassis is **not** suitable for modeling a chassis-based switch with removable line cards (such as the Juniper EX9208), as its line cards are _not_ physically autonomous devices.

docs/models/extras/customfield.md

@@ -19,6 +19,8 @@ Custom fields may be created by navigating to Customization > Custom Fields. Net
 * 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.
 
@@ -41,3 +43,7 @@ NetBox supports limited custom validation for custom field values. Following are
 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

@@ -2,7 +2,7 @@
 
 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 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`.
+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,18 @@ 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 |
+
+While most of the context variables listed above will have consistent attributes, the object will be an instance of the specific object being viewed when the link is rendered. Different models have different fields and properties, so you may need to some research to determine the attributes available for use within your template for a specific object type.
+
+Checking the REST API representation of an object is generally a convenient way to determine what attributes are available. You can also reference the NetBox source code directly for a comprehensive list.
 
 ## Conditional Rendering
 

docs/models/extras/webhook.md

@@ -3,7 +3,7 @@
 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 custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
+    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
 
@@ -12,7 +12,7 @@ A webhook is a mechanism for conveying to some external system a change that too
 * **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.
+* **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.)
@@ -23,7 +23,7 @@ A webhook is a mechanism for conveying to some external system a change that too
 
 ## 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.
+[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:
 

docs/models/ipam/fhrpgroup.md

@@ -8,9 +8,3 @@ A first-hop redundancy protocol (FHRP) enables multiple physical interfaces to p
 * 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/fhrpgroupassignment.md

@@ -0,0 +1,5 @@
+# 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/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/users/token.md

@@ -3,7 +3,7 @@
 A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile.
 
 !!! note
-    The creation and modification of API tokens can be restricted per user by an administrator. If you don't see an option to create an API token, ask an administrator to grant you access.
+    All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts.
 
 Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation.
 

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/plugins/development.md

@@ -1,432 +0,0 @@
-# Plugin Development
-
-!!! info "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).
-
-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,216 @@
+# Forms
+
+## Form Classes
+
+NetBox provides several base form classes for use by plugins.
+
+| Form Class                | Purpose                              |
+|---------------------------|--------------------------------------|
+| `NetBoxModelForm`         | Create/edit individual objects       |
+| `NetBoxModelCSVForm`      | Bulk import objects from CSV data    |
+| `NetBoxModelBulkEditForm` | Edit multiple objects simultaneously |
+| `NetBoxModelFilterSetForm` | Filter objects within a list view   |
+
+### `NetBoxModelForm`
+
+This is the base form for creating and editing NetBox models. It extends Django's ModelForm to add support for tags and custom fields.
+
+| Attribute   | Description                                                 |
+|-------------|-------------------------------------------------------------|
+| `fieldsets` | A tuple of two-tuples defining the form's layout (optional) |
+
+**Example**
+
+```python
+from dcim.models import Site
+from netbox.forms import NetBoxModelForm
+from utilities.forms.fields import CommentField, DynamicModelChoiceField
+from .models import MyModel
+
+class MyModelForm(NetBoxModelForm):
+    site = DynamicModelChoiceField(
+        queryset=Site.objects.all()
+    )
+    comments = CommentField()
+    fieldsets = (
+        ('Model Stuff', ('name', 'status', 'site', 'tags')),
+        ('Tenancy', ('tenant_group', 'tenant')),
+    )
+
+    class Meta:
+        model = MyModel
+        fields = ('name', 'status', 'site', 'comments', 'tags')
+```
+
+!!! tip "Comment fields"
+    If your form has a `comments` field, there's no need to list it; this will always appear last on the page.
+
+### `NetBoxModelCSVForm`
+
+This form facilitates the bulk import of new objects from CSV data. As with model forms, you'll need to declare a `Meta` subclass specifying the associated `model` and `fields`. NetBox also provides several form fields suitable for import various types of CSV data, listed below.
+
+**Example**
+
+```python
+from dcim.models import Site
+from netbox.forms import NetBoxModelCSVForm
+from utilities.forms import CSVModelChoiceField
+from .models import MyModel
+
+class MyModelCSVForm(NetBoxModelCSVForm):
+    site = CSVModelChoiceField(
+        queryset=Site.objects.all(),
+        to_field_name='name',
+        help_text='Assigned site'
+    )
+
+    class Meta:
+        model = MyModel
+        fields = ('name', 'status', 'site', 'comments')
+```
+
+### `NetBoxModelBulkEditForm`
+
+This form facilitates editing multiple objects in bulk. Unlike a model form, this form does not have a child `Meta` class, and must explicitly define each field. All fields in a bulk edit form are generally declared with `required=False`.
+
+| Attribute         | Description                                                                                 |
+|-------------------|---------------------------------------------------------------------------------------------|
+| `model`           | The model of object being edited                                                            |
+| `fieldsets`       | A tuple of two-tuples defining the form's layout (optional)                                 |
+| `nullable_fields` | A tuple of fields which can be nullified (set to empty) using the bulk edit form (optional) |
+
+**Example**
+
+```python
+from django import forms
+from dcim.models import Site
+from netbox.forms import NetBoxModelCSVForm
+from utilities.forms import CommentField, DynamicModelChoiceField
+from .models import MyModel, MyModelStatusChoices
+
+class MyModelEditForm(NetBoxModelCSVForm):
+    name = forms.CharField(
+        required=False
+    )
+    status = forms.ChoiceField(
+        choices=MyModelStatusChoices,
+        required=False
+    )
+    site = DynamicModelChoiceField(
+        queryset=Site.objects.all(),
+        required=False
+    )
+    comments = CommentField()
+
+    model = MyModel
+    fieldsets = (
+        ('Model Stuff', ('name', 'status', 'site')),
+    )
+    nullable_fields = ('site', 'comments')
+```
+
+### `NetBoxModelFilterSetForm`
+
+This form class is used to render a form expressly for filtering a list of objects. Its fields should correspond to filters defined on the model's filter set.
+
+| Attribute         | Description                                                 |
+|-------------------|-------------------------------------------------------------|
+| `model`           | The model of object being edited                            |
+| `fieldsets`       | A tuple of two-tuples defining the form's layout (optional) |
+
+**Example**
+
+```python
+from dcim.models import Site
+from netbox.forms import NetBoxModelFilterSetForm
+from utilities.forms import DynamicModelMultipleChoiceField, MultipleChoiceField
+from .models import MyModel, MyModelStatusChoices
+
+class MyModelFilterForm(NetBoxModelFilterSetForm):
+    site_id = DynamicModelMultipleChoiceField(
+        queryset=Site.objects.all(),
+        required=False
+    )
+    status = MultipleChoiceField(
+        choices=MyModelStatusChoices,
+        required=False
+    )
+
+    model = MyModel
+```
+
+## General Purpose Fields
+
+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.
+
+::: 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
+
+## Choice Fields
+
+::: utilities.forms.ChoiceField
+    selection:
+      members: false
+
+::: utilities.forms.MultipleChoiceField
+    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,52 @@
+# 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.types import NetBoxObjectType
+from netbox.graphql.fields import ObjectField, ObjectListField
+from . import filtersets, models
+
+class MyModelType(NetBoxObjectType):
+
+    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,171 @@
+# Plugins Development
+
+!!! tip "Plugins Development Tutorial"
+    Just getting started with plugins? Check out our [**NetBox Plugin Tutorial**](https://github.com/netbox-community/netbox-plugin-tutorial) on GitHub! This in-depth guide will walk you through the process of creating an entire plugin from scratch. It even includes a companion [demo plugin repo](https://github.com/netbox-community/netbox-plugin-demo) to ensure you can jump in at any step along the way. This will get you up and running with plugins in no time!
+
+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/
+      - __init__.py
+      - serializers.py
+      - urls.py
+      - views.py
+    - migrations/
+      - __init__.py
+      - 0001_initial.py
+      - ...
+    - templates/
+      - plugin_name/
+        - *.html
+    - __init__.py
+    - filtersets.py
+    - graphql.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,185 @@
+# 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'),
+    ]
+```
+
+!!! warning
+    For dynamic configuration to work properly, `CHOICES` must be a mutable list, rather than a tuple.
+
+```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,117 @@
+# 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.
+
+## Code Layout
+
+The recommended approach is to separate API serializers, views, and URLs into separate modules under the `api/` directory to keep things tidy, particularly for larger projects. The file at `api/__init__.py` can import the relevant components from each submodule to allow import all API components directly from elsewhere. However, this is merely a convention and not strictly required.
+
+```no-highlight
+project-name/
+  - plugin_name/
+    - api/
+      - __init__.py
+      - serializers.py
+      - urls.py
+      - views.py
+    ...
+```
+
+## Serializers
+
+### Model 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. It is generally advisable to include a `url` attribute on each serializer. This will render the direct link to access the object being rendered.
+
+```python
+# api/serializers.py
+from rest_framework import serializers
+from netbox.api.serializers import NetBoxModelSerializer
+from my_plugin.models import MyModel
+
+class MyModelSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:myplugin-api:mymodel-detail'
+    )
+
+    class Meta:
+        model = MyModel
+        fields = ('id', 'foo', 'bar', 'baz')
+```
+
+### Nested Serializers
+
+There are two cases where it is generally desirable to show only a minimal representation of an object:
+
+1. When displaying an object related to the one being viewed (for example, the region to which a site is assigned)
+2. Listing many objects using "brief" mode
+
+To accommodate these, it is recommended to create nested serializers accompanying the "full" serializer for each model. NetBox provides the `WritableNestedSerializer` class for just this purpose. This class accepts a primary key value on write, but displays an object representation for read requests. It also includes a read-only `display` attribute which conveys the string representation of the object.
+
+#### Example
+
+```python
+# api/serializers.py
+from rest_framework import serializers
+from netbox.api.serializers import WritableNestedSerializer
+from my_plugin.models import MyModel
+
+class NestedMyModelSerializer(WritableNestedSerializer):
+    url = serializers.HyperlinkedIdentityField(
+        view_name='plugins-api:myplugin-api:mymodel-detail'
+    )
+
+    class Meta:
+        model = MyModel
+        fields = ('id', 'display', 'foo')
+```
+
+## 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 netbox.api.routers import NetBoxRouter
+from .views import MyModelViewSet
+
+router = NetBoxRouter()
+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,247 @@
+# 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/).
+
+## Template File Structure
+
+Plugin templates should live in the `templates/<plugin-name>/` path within the plugin root. For example if your plugin's name is `my_plugin` and you create a template named `foo.html`, it should be saved to `templates/my_plugin/foo.html`. (You can of course use subdirectories below this point as well.) This ensures that Django's template engine can locate the template for rendering.
+
+## 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.linkify
+
+::: 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/release-notes/index.md

@@ -10,6 +10,18 @@ Minor releases are published in April, August, and December of each calendar yea
 
 This page contains a history of all major and minor releases since NetBox v2.0. For more detail on a specific patch release, please see the release notes page for that specific minor release.
 
+#### [Version 3.2](./version-3.2.md) (April 2022)
+
+* Plugins Framework Extensions ([#8333](https://github.com/netbox-community/netbox/issues/8333))
+* Modules & Module Types ([#7844](https://github.com/netbox-community/netbox/issues/7844))
+* Custom Object Fields ([#7006](https://github.com/netbox-community/netbox/issues/7006))
+* Custom Status Choices ([#8054](https://github.com/netbox-community/netbox/issues/8054))
+* Improved User Preferences ([#7759](https://github.com/netbox-community/netbox/issues/7759))
+* Inventory Item Roles ([#3087](https://github.com/netbox-community/netbox/issues/3087))
+* Inventory Item Templates ([#8118](https://github.com/netbox-community/netbox/issues/8118))
+* Service Templates ([#1591](https://github.com/netbox-community/netbox/issues/1591))
+* Automatic Provisioning of Next Available VLANs ([#2658](https://github.com/netbox-community/netbox/issues/2658))
+
 #### [Version 3.1](./version-3.1.md) (December 2021)
 
 * Contact Objects ([#1344](https://github.com/netbox-community/netbox/issues/1344))

docs/release-notes/version-2.1.md

@@ -121,7 +121,7 @@ A new API endpoint has been added at `/api/ipam/prefixes/<pk>/available-ips/`. A
 
 #### NAPALM Integration ([#1348](https://github.com/netbox-community/netbox/issues/1348))
 
-The [NAPALM automation](https://github.com/napalm-automation/napalm) library provides an abstracted interface for pulling live data (e.g. uptime, software version, running config, LLDP neighbors, etc.) from network devices. The NetBox API has been extended to support executing read-only NAPALM methods on devices defined in NetBox. To enable this functionality, ensure that NAPALM has been installed (`pip install napalm`) and the `NETBOX_USERNAME` and `NETBOX_PASSWORD` [configuration parameters](https://netbox.readthedocs.io/en/stable/configuration/optional-settings/#netbox_username) have been set in configuration.py.
+The [NAPALM automation](https://github.com/napalm-automation/napalm) library provides an abstracted interface for pulling live data (e.g. uptime, software version, running config, LLDP neighbors, etc.) from network devices. The NetBox API has been extended to support executing read-only NAPALM methods on devices defined in NetBox. To enable this functionality, ensure that NAPALM has been installed (`pip install napalm`) and the `NETBOX_USERNAME` and `NETBOX_PASSWORD` [configuration parameters](https://docs.netbox.dev/en/stable/configuration/optional-settings/#netbox_username) have been set in configuration.py.
 
 ### Enhancements
 

docs/release-notes/version-2.2.md

@@ -196,7 +196,7 @@ Our second-most popular feature request has arrived! NetBox now supports the cre
 
 #### Custom Validation Reports ([#1511](https://github.com/netbox-community/netbox/issues/1511))
 
-Users can now create custom reports which are run to validate data in NetBox. Reports work very similar to Python unit tests: Each report inherits from NetBox's Report class and contains one or more test method. Reports can be run and retrieved via the web UI, API, or CLI. See [the docs](https://netbox.readthedocs.io/en/stable/miscellaneous/reports/) for more info.
+Users can now create custom reports which are run to validate data in NetBox. Reports work very similar to Python unit tests: Each report inherits from NetBox's Report class and contains one or more test method. Reports can be run and retrieved via the web UI, API, or CLI. See [the docs](https://docs.netbox.dev/en/stable/miscellaneous/reports/) for more info.
 
 ### Enhancements
 

docs/release-notes/version-2.5.md

@@ -295,7 +295,7 @@ This release upgrades the Django framework to version 2.2.
 
 #### Python 3 Required
 
-As promised, Python 2 support has been completed removed. Python 3.5 or higher is now required to run NetBox. Please see [our Python 3 migration guide](https://netbox.readthedocs.io/en/stable/installation/migrating-to-python3/) for assistance with upgrading.
+As promised, Python 2 support has been completed removed. Python 3.5 or higher is now required to run NetBox. Please see [our Python 3 migration guide](https://docs.netbox.dev/en/stable/installation/migrating-to-python3/) for assistance with upgrading.
 
 #### Removed Deprecated User Activity Log
 

docs/release-notes/version-2.6.md

@@ -218,7 +218,7 @@
 
 #### Custom Scripts ([#3415](https://github.com/netbox-community/netbox/issues/3415))
 
-Custom scripts allow for the execution of arbitrary code via the NetBox UI. They can be used to automatically create, manipulate, or clean up objects or perform other tasks within NetBox. Scripts are defined as Python files which contain one or more subclasses of `extras.scripts.Script`. Variable fields can be defined within scripts, which render as form fields within the web UI to prompt the user for input data. Scripts are executed and information is logged via the web UI. Please see [the docs](https://netbox.readthedocs.io/en/stable/customization/custom-scripts/) for more detail.
+Custom scripts allow for the execution of arbitrary code via the NetBox UI. They can be used to automatically create, manipulate, or clean up objects or perform other tasks within NetBox. Scripts are defined as Python files which contain one or more subclasses of `extras.scripts.Script`. Variable fields can be defined within scripts, which render as form fields within the web UI to prompt the user for input data. Scripts are executed and information is logged via the web UI. Please see [the docs](https://docs.netbox.dev/en/stable/customization/custom-scripts/) for more detail.
 
 Note: There are currently no API endpoints for this feature. These are planned for the upcoming v2.7 release.
 

docs/release-notes/version-2.7.md

@@ -67,7 +67,7 @@
 
 ## v2.7.9 (2020-03-06)
 
-**Note:** This release will deploy a Python virtual environment on upgrade in the `venv/` directory. This will require modifying the paths to your Python and gunicorn executables in the systemd service files. For more detail, please see the [upgrade instructions](https://netbox.readthedocs.io/en/stable/installation/upgrading/).
+**Note:** This release will deploy a Python virtual environment on upgrade in the `venv/` directory. This will require modifying the paths to your Python and gunicorn executables in the systemd service files. For more detail, please see the [upgrade instructions](https://docs.netbox.dev/en/stable/installation/upgrading/).
 
 ### Enhancements
 
@@ -418,7 +418,7 @@ to another source before upgrading NetBox to v2.7, as any existing topology maps
 
 #### Supervisor Replaced with systemd ([#2902](https://github.com/netbox-community/netbox/issues/2902))
 
-The NetBox [installation documentation](https://netbox.readthedocs.io/en/stable/installation/) has been updated to
+The NetBox [installation documentation](https://docs.netbox.dev/en/stable/installation/) has been updated to
 provide instructions for managing the WSGI and RQ services using systemd instead of supervisor. This removes the need to
 install supervisor and simplifies administration of the processes.
 

docs/release-notes/version-2.8.md

@@ -235,14 +235,14 @@ This release introduces support for custom plugins, which can be used to extend
 * Introduce new API endpoints
 * Add custom request/response middleware
 
-For NetBox plugins to be recognized, they must be installed and added by name to the `PLUGINS` configuration parameter. (Plugin support is disabled by default.) Plugins can be configured under the `PLUGINS_CONFIG` parameter. More information can be found the in the [plugins documentation](https://netbox.readthedocs.io/en/stable/plugins/).
+For NetBox plugins to be recognized, they must be installed and added by name to the `PLUGINS` configuration parameter. (Plugin support is disabled by default.) Plugins can be configured under the `PLUGINS_CONFIG` parameter. More information can be found the in the [plugins documentation](https://docs.netbox.dev/en/stable/plugins/).
 
 ### Enhancements
 
 * [#1754](https://github.com/netbox-community/netbox/issues/1754) - Added support for nested rack groups
 * [#3939](https://github.com/netbox-community/netbox/issues/3939) - Added support for nested tenant groups
 * [#4078](https://github.com/netbox-community/netbox/issues/4078) - Standardized description fields across all models
-* [#4195](https://github.com/netbox-community/netbox/issues/4195) - Enabled application logging (see [logging configuration](https://netbox.readthedocs.io/en/stable/configuration/optional-settings/#logging))
+* [#4195](https://github.com/netbox-community/netbox/issues/4195) - Enabled application logging (see [logging configuration](https://docs.netbox.dev/en/stable/configuration/optional-settings/#logging))
 
 ### Bug Fixes
 

docs/release-notes/version-3.1.md

@@ -1,5 +1,104 @@
 # NetBox v3.1
 
+## v3.1.11 (2022-04-05)
+
+### Enhancements
+
+* [#8163](https://github.com/netbox-community/netbox/issues/8163) - Show bridge interface members under interface view
+* [#8365](https://github.com/netbox-community/netbox/issues/8365) - Enable filtering child devices by parent device ID
+* [#8785](https://github.com/netbox-community/netbox/issues/8785) - Permit wildcard values in IP address DNS names
+* [#8790](https://github.com/netbox-community/netbox/issues/8790) - Include site and prefixes columns in VLAN group VLANs table
+* [#8830](https://github.com/netbox-community/netbox/issues/8830) - Add Checkpoint ClusterXL protocol for FHRP groups
+* [#8974](https://github.com/netbox-community/netbox/issues/8974) - Use monospace font for text areas in config revision form
+* [#9012](https://github.com/netbox-community/netbox/issues/9012) - Linkify circuits count in providers list
+* [#9036](https://github.com/netbox-community/netbox/issues/9036) - Add bulk edit capability for site contact fields
+
+### Bug Fixes
+
+* [#8866](https://github.com/netbox-community/netbox/issues/8866) - Prevent exception when searching for a rack position with no rack specified under device edit view
+* [#9009](https://github.com/netbox-community/netbox/issues/9009) - Fix device count for racks in global search results
+
+---
+
+## v3.1.10 (2022-03-25)
+
+### Enhancements
+
+* [#8232](https://github.com/netbox-community/netbox/issues/8232) - Use a different color for 100% utilization bars
+* [#8457](https://github.com/netbox-community/netbox/issues/8457) - Enable adding non-racked devices from site & location views
+* [#8553](https://github.com/netbox-community/netbox/issues/8553) - Add missing object types to global search form
+* [#8575](https://github.com/netbox-community/netbox/issues/8575) - Add rack columns to cables list
+* [#8645](https://github.com/netbox-community/netbox/issues/8645) - Enable filtering objects by assigned contacts & contact roles
+* [#8926](https://github.com/netbox-community/netbox/issues/8926) - Add device type, role columns to device bay table
+
+### Bug Fixes
+
+* [#8696](https://github.com/netbox-community/netbox/issues/8696) - Fix help link under FHRP group assigment creation view
+* [#8813](https://github.com/netbox-community/netbox/issues/8813) - Retain global search bar query after submitting
+* [#8820](https://github.com/netbox-community/netbox/issues/8820) - Fix navbar background color in dark mode
+* [#8850](https://github.com/netbox-community/netbox/issues/8850) - Show airflow field on device REST API serializer when config context data is included
+* [#8905](https://github.com/netbox-community/netbox/issues/8905) - Disable ordering by assigned tags to prevent erroneous results
+* [#8919](https://github.com/netbox-community/netbox/issues/8919) - Fix filtering of VLAN groups by site under prefix edit form
+* [#8924](https://github.com/netbox-community/netbox/issues/8924) - Improve load time of custom script list
+* [#8932](https://github.com/netbox-community/netbox/issues/8932) - Fix error when setting null value for interface `rf_role` via REST API
+* [#8935](https://github.com/netbox-community/netbox/issues/8935) - Correct ordering of next/previous racks to use naturalized names
+* [#8947](https://github.com/netbox-community/netbox/issues/8947) - Retain filter parameters when handling an export template exception
+* [#8951](https://github.com/netbox-community/netbox/issues/8951) - Allow changing device type & platform to different manufacturer simultaneously
+* [#8952](https://github.com/netbox-community/netbox/issues/8952) - Device images in rear rack elevations should be hyperlinked
+
+---
+
+## v3.1.9 (2022-03-07)
+
+### Enhancements
+
+* [#8594](https://github.com/netbox-community/netbox/issues/8594) - Enable filtering by exact description match for all applicable models
+* [#8629](https://github.com/netbox-community/netbox/issues/8629) - Add description to tag table search function
+* [#8664](https://github.com/netbox-community/netbox/issues/8664) - Show assigned ASNs/sites under list views
+* [#8736](https://github.com/netbox-community/netbox/issues/8736) - Add PC and UPC fiber end faces for LC/SC/LSH port types
+* [#8758](https://github.com/netbox-community/netbox/issues/8758) - Allow empty string substitution when renaming objects in bulk
+* [#8762](https://github.com/netbox-community/netbox/issues/8762) - Link to rack elevations list from site view
+* [#8766](https://github.com/netbox-community/netbox/issues/8766) - Add SCTP to service protocols list
+
+### Bug Fixes
+
+* [#8546](https://github.com/netbox-community/netbox/issues/8546) - Fix bulk import to restrict bridge, parent, and LAG to device interfaces
+* [#8633](https://github.com/netbox-community/netbox/issues/8633) - Prevent navigation sidebar pin from disappearing at certain breakpoints
+* [#8674](https://github.com/netbox-community/netbox/issues/8674) - Fix rendering of tabbed content in documentation
+* [#8710](https://github.com/netbox-community/netbox/issues/8710) - Fix dynamic scope selection form fields when creating a VLAN group
+* [#8713](https://github.com/netbox-community/netbox/issues/8713) - Restore missing "add" button on services list view
+* [#8715](https://github.com/netbox-community/netbox/issues/8715) - Avoid returning multiple objects when restricting querysets using multiple tags in permissions
+* [#8717](https://github.com/netbox-community/netbox/issues/8717) - Fix redirection after bulk edit/delete of prefixes from aggregate view
+* [#8724](https://github.com/netbox-community/netbox/issues/8724) - Fix exception during device import with invalid device type
+* [#8807](https://github.com/netbox-community/netbox/issues/8807) - Correct REST API URL for FHRP group assignments
+* [#8808](https://github.com/netbox-community/netbox/issues/8808) - Fix members count under FHRP group list
+
+---
+
+## v3.1.8 (2022-02-15)
+
+### Enhancements
+
+* [#7150](https://github.com/netbox-community/netbox/issues/7150) - Linkify devices on the far side of a rack elevation
+* [#8398](https://github.com/netbox-community/netbox/issues/8398) - Embiggen configuration form fields for banner message content
+* [#8556](https://github.com/netbox-community/netbox/issues/8556) - Add full username column to changelog table
+* [#8620](https://github.com/netbox-community/netbox/issues/8620) - Enable tab completion for `nbshell`
+
+### Bug Fixes
+
+* [#8331](https://github.com/netbox-community/netbox/issues/8331) - Implement `replaceAll` string utility function to improve browser compatibility
+* [#8391](https://github.com/netbox-community/netbox/issues/8391) - Null date columns should return empty strings during CSV export
+* [#8548](https://github.com/netbox-community/netbox/issues/8548) - Fix display of VC members when position is zero
+* [#8561](https://github.com/netbox-community/netbox/issues/8561) - Include option to connect a rear port to a console port
+* [#8564](https://github.com/netbox-community/netbox/issues/8564) - Fix errant table configuration key `available_columns`
+* [#8577](https://github.com/netbox-community/netbox/issues/8577) - Show contact assignment counts in global search results
+* [#8578](https://github.com/netbox-community/netbox/issues/8578) - Object change log tables should honor user's configured preferences
+* [#8604](https://github.com/netbox-community/netbox/issues/8604) - Fix tag filter on config context list filter form
+* [#8609](https://github.com/netbox-community/netbox/issues/8609) - Display validation error when attempting to assign VLANs to interface with no mode during bulk edit
+* [#8611](https://github.com/netbox-community/netbox/issues/8611) - Fix bulk editing for certain custom link, webhook, and journal entry fields
+
+---
+
 ## v3.1.7 (2022-02-03)
 
 ### Enhancements

docs/release-notes/version-3.2.md

@@ -0,0 +1,314 @@
+# NetBox v3.2
+
+## v3.2.3 (2022-05-12)
+
+### Enhancements
+
+* [#8805](https://github.com/netbox-community/netbox/issues/8805) - Add "mixed" option for device airflow indication
+* [#8894](https://github.com/netbox-community/netbox/issues/8894) - Include full names when listing users
+* [#8998](https://github.com/netbox-community/netbox/issues/8998) - Enable filtering racks & reservations by site group
+* [#9122](https://github.com/netbox-community/netbox/issues/9122) - Introduce `clearcache` management command & clear cache during upgrade
+* [#9221](https://github.com/netbox-community/netbox/issues/9221) - Add definition list support for Markdown
+* [#9260](https://github.com/netbox-community/netbox/issues/9260) - Apply user preferences to tables under object detail views
+* [#9278](https://github.com/netbox-community/netbox/issues/9278) - Linkify device types count under manufacturers list
+* [#9280](https://github.com/netbox-community/netbox/issues/9280) - Allow adopting existing components when installing a module
+* [#9314](https://github.com/netbox-community/netbox/issues/9314) - Add device and VM filters for FHRP group assignments
+* [#9340](https://github.com/netbox-community/netbox/issues/9340) - Introduce support for error reporting via Sentry
+* [#9343](https://github.com/netbox-community/netbox/issues/9343) - Add Ubiquiti SmartPower power outlet type
+
+### Bug Fixes
+
+* [#9190](https://github.com/netbox-community/netbox/issues/9190) - Prevent exception when attempting to instantiate module components which already exist on the parent device
+* [#9267](https://github.com/netbox-community/netbox/issues/9267) - Remove invalid entry in IP address role choices
+* [#9296](https://github.com/netbox-community/netbox/issues/9296) - Improve Markdown link sanitization
+* [#9306](https://github.com/netbox-community/netbox/issues/9306) - Include VC master interfaces when selecting a LAG/bridge for a VC member interface
+* [#9311](https://github.com/netbox-community/netbox/issues/9311) - Permit creating contact assignment without a priority via the REST API
+* [#9313](https://github.com/netbox-community/netbox/issues/9313) - Remove HTML code from CSV output of many-to-many relationships
+* [#9330](https://github.com/netbox-community/netbox/issues/9330) - Add missing `module_type` field to REST API serializers for modular device component templates
+
+---
+
+## v3.2.2 (2022-04-28)
+
+### Enhancements
+
+* [#9060](https://github.com/netbox-community/netbox/issues/9060) - Add device type filters for device bays, module bays, and inventory items
+* [#9152](https://github.com/netbox-community/netbox/issues/9152) - Annotate related object type under custom field view
+* [#9192](https://github.com/netbox-community/netbox/issues/9192) - Add Ubiquiti SmartPower connector type
+* [#9214](https://github.com/netbox-community/netbox/issues/9214) - Linkify cluster counts in cluster type & group tables
+
+### Bug Fixes
+
+* [#4264](https://github.com/netbox-community/netbox/issues/4264) - Treat 0th IP as unusable for IPv6 prefixes (excluding /127s)
+* [#8941](https://github.com/netbox-community/netbox/issues/8941) - Fix dynamic dropdown behavior when browser is zoomed
+* [#8959](https://github.com/netbox-community/netbox/issues/8959) - Prevent exception when refreshing scripts list (avoid race condition)
+* [#9132](https://github.com/netbox-community/netbox/issues/9132) - Limit location options by selected site when creating a wireless link
+* [#9133](https://github.com/netbox-community/netbox/issues/9133) - Upgrade script should require Python 3.8 or later
+* [#9138](https://github.com/netbox-community/netbox/issues/9138) - Avoid inadvertent form submission when utilizing quick search field on object lists
+* [#9151](https://github.com/netbox-community/netbox/issues/9151) - Child prefix counts not annotated on aggregates list under RIR view
+* [#9156](https://github.com/netbox-community/netbox/issues/9156) - Fix loading UserConfig data from fixtures
+* [#9158](https://github.com/netbox-community/netbox/issues/9158) - Do not list tags field for CSV forms which do not support tag assignment
+* [#9194](https://github.com/netbox-community/netbox/issues/9194) - Support position assignment when add module bays to multiple devices
+* [#9206](https://github.com/netbox-community/netbox/issues/9206) - Show header for comments field under module & module type creation views
+* [#9222](https://github.com/netbox-community/netbox/issues/9222) - Fix circuit ID display under cable view
+* [#9227](https://github.com/netbox-community/netbox/issues/9227) - Fix related object assignment when recording change record for interfaces
+
+---
+
+## v3.2.1 (2022-04-14)
+
+### Enhancements
+
+* [#5479](https://github.com/netbox-community/netbox/issues/5479) - Allow custom job timeouts for scripts & reports
+* [#8543](https://github.com/netbox-community/netbox/issues/8543) - Improve filtering for wireless LAN VLAN selection
+* [#8920](https://github.com/netbox-community/netbox/issues/8920) - Limit number of non-racked devices displayed
+* [#8956](https://github.com/netbox-community/netbox/issues/8956) - Retain old script/report results for configured lifetime
+* [#8973](https://github.com/netbox-community/netbox/issues/8973) - Display VLAN group count under site view
+* [#9081](https://github.com/netbox-community/netbox/issues/9081) - Add `fhrpgroup_id` filter for IP addresses
+* [#9099](https://github.com/netbox-community/netbox/issues/9099) - Enable display of installed module serial & asset tag in module bays list
+* [#9110](https://github.com/netbox-community/netbox/issues/9110) - Add Neutrik proprietary power connectors
+* [#9123](https://github.com/netbox-community/netbox/issues/9123) - Improve appearance of SSO login providers
+
+### Bug Fixes
+
+* [#8931](https://github.com/netbox-community/netbox/issues/8931) - Copy assigned tenant when cloning a location
+* [#9055](https://github.com/netbox-community/netbox/issues/9055) - Restore ability to move inventory item to other device
+* [#9057](https://github.com/netbox-community/netbox/issues/9057) - Fix missing instance counts for module types
+* [#9061](https://github.com/netbox-community/netbox/issues/9061) - Fix general search for device components
+* [#9065](https://github.com/netbox-community/netbox/issues/9065) - Min/max VID should not be required when filtering VLAN groups
+* [#9079](https://github.com/netbox-community/netbox/issues/9079) - Fail validation when an inventory item is assigned as its own parent
+* [#9096](https://github.com/netbox-community/netbox/issues/9096) - Remove duplicate filter tag when filtering by "none"
+* [#9100](https://github.com/netbox-community/netbox/issues/9100) - Include position field in module type YAML export
+* [#9116](https://github.com/netbox-community/netbox/issues/9116) - `assigned_to_interface` filter for IP addresses should not match FHRP group assignments
+* [#9118](https://github.com/netbox-community/netbox/issues/9118) - Fix validation error when importing VM child interfaces
+* [#9128](https://github.com/netbox-community/netbox/issues/9128) - Resolve component labels per module bay position when installing modules
+
+---
+
+## v3.2.0 (2022-04-05)
+
+!!! warning "Python 3.8 or Later Required"
+    NetBox v3.2 requires Python 3.8 or later.
+
+!!! warning "Deletion of Legacy Data"
+    This release includes a database migration that will remove the `asn`, `contact_name`, `contact_phone`, and `contact_email` fields from the site model. (These fields have been superseded by the ASN and contact models introduced in NetBox v3.1.) To protect against the accidental destruction of data, the upgrade process **will fail** if any sites still have data in any of these fields. To bypass this safeguard, set the `NETBOX_DELETE_LEGACY_DATA` environment variable when running the upgrade script, which will permit the destruction of legacy data.
+
+!!! tip "Migration Scripts"
+    A set of [migration scripts](https://github.com/netbox-community/migration-scripts) is available to assist with the migration of legacy site data.
+
+### Breaking Changes
+
+* Automatic redirection of legacy slug-based URL paths has been removed. URL-based slugs were changed to use numeric IDs in v2.11.0.
+* The `asn` field has been removed from the site model. Please replicate any site ASN assignments to the ASN model introduced in NetBox v3.1 prior to upgrading.
+* The `asn` query filter for sites now matches against the AS number of assigned ASN objects.
+* The `contact_name`, `contact_phone`, and `contact_email` fields have been removed from the site model. Please replicate any data remaining in these fields to the contact model introduced in NetBox v3.1 prior to upgrading.
+* The `created` field of all change-logged models now conveys a full datetime object, rather than only a date. (Previous date-only values will receive a timestamp of 00:00.) While this change is largely unconcerning, strictly-typed API consumers may need to be updated.
+* A `pre_run()` method has been added to the base Report class. Although unlikely to affect most installations, you may need to alter any reports which already use this name for a method.
+* Webhook URLs now support Jinja2 templating. Although this is unlikely to introduce any issues, it's possible that an unusual URL might trigger a Jinja2 rendering error, in which case the URL would need to be properly escaped.
+
+### New Features
+
+#### Plugins Framework Extensions ([#8333](https://github.com/netbox-community/netbox/issues/8333))
+
+NetBox's plugins framework has been extended considerably in this release. Additions include:
+
+* Officially-supported generic view classes for common CRUD operations:
+    * `ObjectView`
+    * `ObjectEditView`
+    * `ObjectDeleteView`
+    * `ObjectListView`
+    * `BulkImportView`
+    * `BulkEditView`
+    * `BulkDeleteView`
+* The `NetBoxModel` base class, which enables various NetBox features, including:
+    * Change logging
+    * Custom fields
+    * Custom links
+    * Custom validation
+    * Export templates
+    * Journaling
+    * Tags
+    * Webhooks
+* Four base form classes for manipulating objects via the UI:
+    * `NetBoxModelForm`
+    * `NetBoxModelCSVForm`
+    * `NetBoxModelBulkEditForm`
+    * `NetBoxModelFilterSetForm`
+* The `NetBoxModelFilterSet` base class for plugin filter sets
+* The `NetBoxTable` base class for rendering object tables with `django-tables2`, as well as various custom column classes
+* Function-specific templates (for generic views)
+* Various custom template tags and filters
+* `NetBoxModelViewSet` and several base serializer classes now provide enhanced REST API functionality
+* Plugins can now extend NetBox's GraphQL API with their own schema
+
+No breaking changes to previously supported components have been introduced in this release. However, plugin authors are encouraged to audit their existing code for misuse of unsupported components, as much of NetBox's internal code base has been reorganized.
+
+#### Modules & Module Types ([#7844](https://github.com/netbox-community/netbox/issues/7844))
+
+Several new models have been added to represent field-replaceable device modules, such as line cards installed within a chassis-based switch or router. Similar to devices, each module is instantiated from a user-defined module type, and can have components (interfaces, console ports, etc.) associated with it. These components become available to the parent device once the module has been installed within a module bay. This provides a convenient mechanism to effect the addition and deletion of device components as modules are installed and removed.
+
+Automatic renaming of module components is also supported. When a new module is created, any occurrence of the string `{module}` in a component name will be replaced with the position of the module bay into which the module is being installed.
+
+As with device types, the NetBox community offers a selection of curated real-world module type definitions in our [device type library](https://github.com/netbox-community/devicetype-library). These YAML files can be imported directly to NetBox for your convenience.
+
+#### Custom Object Fields ([#7006](https://github.com/netbox-community/netbox/issues/7006))
+
+Two new types of custom field have been introduced: object and multi-object. These can be used to associate an object in NetBox with some other arbitrary object(s) regardless of its type. For example, you might create a custom field named `primary_site` on the tenant model so that each tenant can have particular site designated as its primary. The multi-object custom field type allows for the assignment of multiple objects of the same type.
+
+Custom field object assignment is fully supported in the REST API, and functions similarly to built-in foreign key relations. Nested representations are provided automatically for each custom field object.
+
+#### Custom Status Choices ([#8054](https://github.com/netbox-community/netbox/issues/8054))
+
+Custom choices can be now added to most object status fields in NetBox. This is done by defining the [`FIELD_CHOICES`](../configuration/optional-settings.md#field_choices) configuration parameter to map field identifiers to an iterable of custom choices an (optionally) colors. These choices are populated automatically when NetBox initializes. For example, the following configuration will add three custom choices for the site status field, each with a designated color:
+
+```python
+FIELD_CHOICES = {
+    'dcim.Site.status': (
+        ('foo', 'Foo', 'red'),
+        ('bar', 'Bar', 'green'),
+        ('baz', 'Baz', 'blue'),
+    )
+}
+```
+
+This will replace all default choices for this field with those listed. If instead the intent is to _extend_ the set of default choices, this can be done by appending a plus sign (`+`) to the end of the field identifier. For example, the following will add a single extra choice while retaining the defaults provided by NetBox:
+
+```python
+FIELD_CHOICES = {
+    'dcim.Site.status+': (
+        ('fubar', 'FUBAR', 'red'),
+    )
+}
+```
+
+#### Improved User Preferences ([#7759](https://github.com/netbox-community/netbox/issues/7759))
+
+A robust new mechanism for managing user preferences is included in this release. The user preferences form has been improved for better usability, and administrators can now define default preferences for all users with the [`DEFAULT_USER_PREFERENCES`](../configuration/dynamic-settings.md##default_user_preferences) configuration parameter. For example, this can be used to define the columns which appear by default in a table:
+
+```python
+DEFAULT_USER_PREFERENCES = {
+    'tables': {
+        'IPAddressTable': {
+            'columns': ['address', 'status', 'created', 'description']
+        }
+    }
+}
+```
+
+Users can adjust their own preferences under their user profile. A complete list of supported preferences is available in NetBox's [developer documentation](../development/user-preferences.md).
+
+#### Inventory Item Roles ([#3087](https://github.com/netbox-community/netbox/issues/3087))
+
+A new model has been introduced to represent functional roles for inventory items, similar to device roles. The assignment of roles to inventory items is optional.
+
+#### Inventory Item Templates ([#8118](https://github.com/netbox-community/netbox/issues/8118))
+
+Inventory items can now be templatized on a device type similar to other components (such as interfaces or console ports). This enables users to better pre-model fixed hardware components such as power supplies or hard disks.
+
+Inventory item templates can be arranged hierarchically within a device type, and may be assigned to other templated components. These relationships will be mirrored when instantiating inventory items on a newly-created device (see [#7846](https://github.com/netbox-community/netbox/issues/7846)). For example, if defining an optic assigned to an interface template on a device type, the instantiated device will mimic this relationship between the optic and interface.
+
+#### Service Templates ([#1591](https://github.com/netbox-community/netbox/issues/1591))
+
+A new service template model has been introduced to assist in standardizing the definition and association of applications with devices and virtual machines. As an alternative to manually defining a name, protocol, and port(s) each time a service is created, a user now has the option of selecting a pre-defined template from which these values will be populated.
+
+#### Automatic Provisioning of Next Available VLANs ([#2658](https://github.com/netbox-community/netbox/issues/2658))
+
+A new REST API endpoint has been added at `/api/ipam/vlan-groups/<id>/available-vlans/`. A GET request to this endpoint will return a list of available VLANs within the group. A POST request can be made specifying the name(s) of one or more VLANs to create within the group, and their VLAN IDs will be assigned automatically from the available pool.
+
+Where it is desired to limit the range of available VLANs within a group, users can define a minimum and/or maximum VLAN ID per group (see [#8168](https://github.com/netbox-community/netbox/issues/8168)).
+
+### Enhancements
+
+* [#5429](https://github.com/netbox-community/netbox/issues/5429) - Enable toggling the placement of table pagination controls
+* [#6954](https://github.com/netbox-community/netbox/issues/6954) - Remember users' table ordering preferences
+* [#7650](https://github.com/netbox-community/netbox/issues/7650) - Expose `AUTH_PASSWORD_VALIDATORS` setting to enforce password validation for local accounts
+* [#7679](https://github.com/netbox-community/netbox/issues/7679) - Add actions menu to all object tables
+* [#7681](https://github.com/netbox-community/netbox/issues/7681) - Add `service_id` field for provider networks
+* [#7784](https://github.com/netbox-community/netbox/issues/7784) - Support cluster type assignment for config contexts
+* [#7846](https://github.com/netbox-community/netbox/issues/7846) - Enable associating inventory items with device components
+* [#7852](https://github.com/netbox-community/netbox/issues/7852) - Enable the assignment of interfaces to VRFs
+* [#7853](https://github.com/netbox-community/netbox/issues/7853) - Add `speed` and `duplex` fields to device interface model
+* [#8168](https://github.com/netbox-community/netbox/issues/8168) - Add `min_vid` and `max_vid` fields to VLAN group
+* [#8295](https://github.com/netbox-community/netbox/issues/8295) - Jinja2 rendering is now supported for webhook URLs
+* [#8296](https://github.com/netbox-community/netbox/issues/8296) - Allow disabling custom links
+* [#8307](https://github.com/netbox-community/netbox/issues/8307) - Add `data_type` indicator to REST API serializer for custom fields
+* [#8463](https://github.com/netbox-community/netbox/issues/8463) - Change the `created` field on all change-logged models from date to datetime
+* [#8496](https://github.com/netbox-community/netbox/issues/8496) - Enable assigning multiple ASNs to a provider
+* [#8572](https://github.com/netbox-community/netbox/issues/8572) - Add a `pre_run()` method for reports
+* [#8593](https://github.com/netbox-community/netbox/issues/8593) - Add a `link` field for contacts
+* [#8649](https://github.com/netbox-community/netbox/issues/8649) - Enable customization of configuration module using `NETBOX_CONFIGURATION` environment variable
+* [#9006](https://github.com/netbox-community/netbox/issues/9006) - Enable custom fields, custom links, and tags for journal entries
+
+### Bug Fixes (From Beta2)
+
+* [#8658](https://github.com/netbox-community/netbox/issues/8658) - Fix display of assigned components under inventory item lists
+* [#8838](https://github.com/netbox-community/netbox/issues/8838) - Fix FieldError exception during global search
+* [#8845](https://github.com/netbox-community/netbox/issues/8845) - Correct default ASN formatting in table
+* [#8869](https://github.com/netbox-community/netbox/issues/8869) - Fix NoReverseMatch exception when displaying tag w/assignments
+* [#8872](https://github.com/netbox-community/netbox/issues/8872) - Enable filtering by custom object fields
+* [#8970](https://github.com/netbox-community/netbox/issues/8970) - Permit nested inventory item templates on device types
+* [#8976](https://github.com/netbox-community/netbox/issues/8976) - Add missing `object_type` field on CustomField REST API serializer
+* [#8978](https://github.com/netbox-community/netbox/issues/8978) - Fix instantiation of front ports when provisioning a module
+* [#9007](https://github.com/netbox-community/netbox/issues/9007) - Fix FieldError exception when instantiating a device type with nested inventory items
+
+### Other Changes
+
+* [#7731](https://github.com/netbox-community/netbox/issues/7731) - Require Python 3.8 or later
+* [#7743](https://github.com/netbox-community/netbox/issues/7743) - Remove legacy ASN field from site model
+* [#7748](https://github.com/netbox-community/netbox/issues/7748) - Remove legacy contact fields from site model
+* [#8031](https://github.com/netbox-community/netbox/issues/8031) - Remove automatic redirection of legacy slug-based URLs
+* [#8195](https://github.com/netbox-community/netbox/issues/8195), [#8454](https://github.com/netbox-community/netbox/issues/8454) - Use 64-bit integers for all primary keys
+* [#8509](https://github.com/netbox-community/netbox/issues/8509) - `CSRF_TRUSTED_ORIGINS` is now a discrete configuration parameter (rather than being populated from `ALLOWED_HOSTS`)
+* [#8684](https://github.com/netbox-community/netbox/issues/8684) - Change custom link template context variable `obj` to `object` (backward-compatible)
+
+### REST API Changes
+
+* Added the following endpoints:
+    * `/api/dcim/inventory-item-roles/`
+    * `/api/dcim/inventory-item-templates/`
+    * `/api/dcim/modules/`
+    * `/api/dcim/module-bays/`
+    * `/api/dcim/module-bay-templates/`
+    * `/api/dcim/module-types/`
+    * `/api/ipam/service-templates/`
+    * `/api/ipam/vlan-groups/<id>/available-vlans/`
+* circuits.Provider
+    * Added `asns` field
+* circuits.ProviderNetwork
+    * Added `service_id` field
+* dcim.ConsolePort
+    * Added `module` field
+* dcim.ConsoleServerPort
+    * Added `module` field
+* dcim.FrontPort
+    * Added `module` field
+* dcim.Interface
+    * Added `module`, `speed`, `duplex`, and `vrf` fields
+* dcim.InventoryItem
+    * Added `component_type`, `component_id`, and `role` fields
+    * Added read-only `component` field (GFK)
+* dcim.PowerPort
+    * Added `module` field
+* dcim.PowerOutlet
+    * Added `module` field
+* dcim.RearPort
+    * Added `module` field
+* dcim.Site
+    * Removed the `asn`, `contact_name`, `contact_phone`, and `contact_email` fields
+* extras.ConfigContext
+    * Add `cluster_types` field
+* extras.CustomField
+    * Added `data_type` and `object_type` fields
+* extras.CustomLink
+    * Added `enabled` field
+* extras.JournalEntry
+    * Added `custom_fields` and `tags` fields
+* ipam.ASN
+    * Added `provider_count` field
+* ipam.VLANGroup
+    * Added the `/availables-vlans/` endpoint
+    * Added `min_vid` and `max_vid` fields
+* tenancy.Contact
+    * Added `link` field
+* virtualization.VMInterface
+    * Added `vrf` field