Merge pull request #10051 from netbox-community/develop

Release v3.3.0

.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.2.9
+      placeholder: v3.3.0
     validations:
       required: true
   - type: dropdown

.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.2.9
+      placeholder: v3.3.0
     validations:
       required: true
   - type: dropdown

base_requirements.txt

@@ -34,10 +34,14 @@ django-pglocks
 # https://github.com/korfuri/django-prometheus
 django-prometheus
 
-# Django chaching backend using Redis
+# Django caching backend using Redis
 # https://github.com/jazzband/django-redis
 django-redis
 
+# Django extensions for Rich (terminal text rendering)
+# https://github.com/adamchainz/django-rich
+django-rich
+
 # Django integration for RQ (Reqis queuing)
 # https://github.com/rq/django-rq
 django-rq
@@ -48,8 +52,7 @@ django-tables2
 
 # User-defined tags for objects
 # https://github.com/alex/django-taggit
-# Will evaluate v3.0 during NetBox v3.3 beta
-django-taggit>=2.1.0,<3.0
+django-taggit
 
 # A Django field for representing time zones
 # https://github.com/mfogel/django-timezone-field/

docs/_theme/main.html

+{% extends "base.html" %}
+
+{% block site_meta %}
+  {{ super() }}
+  {# Disable search indexing unless we're building for ReadTheDocs #}
+  {% if not config.extra.readthedocs %}
+    <meta name="robots" content="noindex">
+  {% endif %}
+{% endblock %}

docs/administration/housekeeping.md

@@ -3,8 +3,8 @@
 NetBox includes a `housekeeping` management command that should be run nightly. This command handles:
 
 * Clearing expired authentication sessions from the database
-* Deleting changelog records older than the configured [retention time](../configuration/dynamic-settings.md#changelog_retention)
-* Deleting job result records older than the configured [retention time](../configuration/dynamic-settings.md#jobresult_retention)
+* Deleting changelog records older than the configured [retention time](../configuration/miscellaneous.md#changelog_retention)
+* Deleting job result records older than the configured [retention time](../configuration/miscellaneous.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/administration/permissions.md

-# Permissions
+# Object-Based Permissions
 
 NetBox v2.9 introduced a new object-based permissions framework, which replaces Django's built-in permissions model. Object-based permissions enable an administrator to grant users or groups the ability to perform an action on arbitrary subsets of objects in NetBox, rather than all objects of a certain type. For example, it is possible to grant a user permission to view only sites within a particular region, or to modify only VLANs with a numeric ID within a certain range.
 
-{!models/users/objectpermission.md!}
+A permission in NetBox represents a relationship shared by several components:
 
-### Example Constraint Definitions
+* Object type(s) - One or more types of object in NetBox
+* User(s)/Group(s) - One or more users or groups of users
+* Action(s) - The action(s) that can be performed on an object
+* Constraints - An arbitrary filter used to limit the granted action(s) to a specific subset of objects
+
+At a minimum, a permission assignment must specify one object type, one user or group, and one action. The specification of constraints is optional: A permission without any constraints specified will apply to all instances of the selected model(s).
+
+## Actions
+
+There are four core actions that can be permitted for each type of object within NetBox, roughly analogous to the CRUD convention (create, read, update, and delete):
+
+* **View** - Retrieve an object from the database
+* **Add** - Create a new object
+* **Change** - Modify an existing object
+* **Delete** - Delete an existing object
+
+In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `napalm_read` permission on the device model allows a user to execute NAPALM queries on a device via NetBox's REST API. These can be specified when granting a permission in the "additional actions" field.
+
+!!! note
+    Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`.
+
+## Constraints
+
+Constraints are expressed as a JSON object or list representing a [Django query filter](https://docs.djangoproject.com/en/stable/ref/models/querysets/#field-lookups). This is the same syntax that you would pass to the QuerySet `filter()` method when performing a query using the Django ORM. As with query filters, double underscores can be used to traverse related objects or invoke lookup expressions. Some example queries and their corresponding definitions are shown below.
+
+All attributes defined within a single JSON object are applied with a logical AND. For example, suppose you assign a permission for the site model with the following constraints.
+
+```json
+{
+  "status": "active",
+  "region__name": "Americas"
+}
+```
+
+The permission will grant access only to sites which have a status of "active" **and** which are assigned to the "Americas" region.
+
+To achieve a logical OR with a different set of constraints, define multiple objects within a list. For example, if you want to constrain the permission to VLANs with an ID between 100 and 199 _or_ a status of "reserved," do the following:
+
+```json
+[
+  {
+    "vid__gte": 100,
+    "vid__lt": 200
+  },
+  {
+    "status": "reserved"
+  }
+]
+```
+
+Additionally, where multiple permissions have been assigned for an object type, their collective constraints will be merged using a logical "OR" operation.
+
+### User Token
+
+!!! info "This feature was introduced in NetBox v3.3"
+
+When defining a permission constraint, administrators may use the special token `$user` to reference the current user at the time of evaluation. This can be helpful to restrict users to editing only their own journal entries, for example. Such a constraint might be defined as:
+
+```json
+{
+  "created_by": "$user"
+}
+```
+
+The `$user` token can be used only as a constraint value, or as an item within a list of values. It cannot be modified or extended to reference specific user attributes.
+
+
+#### Example Constraint Definitions
 
 | Constraints | Description |
 | ----------- | ----------- |

docs/configuration/data-validation.md

+# Data & Validation Parameters
+
+## CUSTOM_VALIDATORS
+
+!!! tip "Dynamic Configuration Parameter"
+
+This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below:
+
+```python
+CUSTOM_VALIDATORS = {
+    "dcim.site": [
+        {
+            "name": {
+                "min_length": 5,
+                "max_length": 30
+            }
+        },
+        "my_plugin.validators.Validator1"
+    ],
+    "dim.device": [
+        "my_plugin.validators.Validator1"
+    ]
+}
+```
+
+---
+
+## 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.Location.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.Cluster.status`
+* `virtualization.VirtualMachine.status`
+
+The following colors are supported:
+
+* `blue`
+* `indigo`
+* `purple`
+* `pink`
+* `red`
+* `orange`
+* `yellow`
+* `green`
+* `teal`
+* `cyan`
+* `gray`
+* `black`
+* `white`

docs/configuration/date-time.md

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

docs/configuration/default-values.md

+# Default Value Parameters
+
+## DEFAULT_USER_PREFERENCES
+
+!!! tip "Dynamic Configuration Parameter"
+
+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`.
+
+---
+
+## PAGINATE_COUNT
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 50
+
+The default maximum number of objects to display per page within each list of objects.
+
+---
+
+## POWERFEED_DEFAULT_AMPERAGE
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 15
+
+The default value for the `amperage` field when creating new power feeds.
+
+---
+
+## POWERFEED_DEFAULT_MAX_UTILIZATION
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 80
+
+The default value (percentage) for the `max_utilization` field when creating new power feeds.
+
+---
+
+## POWERFEED_DEFAULT_VOLTAGE
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 120
+
+The default value for the `voltage` field when creating new power feeds.
+
+---
+
+## RACK_ELEVATION_DEFAULT_UNIT_HEIGHT
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 22
+
+Default height (in pixels) of a unit within a rack elevation. For best results, this should be approximately one tenth of `RACK_ELEVATION_DEFAULT_UNIT_WIDTH`.
+
+---
+
+## RACK_ELEVATION_DEFAULT_UNIT_WIDTH
+
+!!! tip "Dynamic Configuration Parameter"
+
+Default: 220
+
+Default width (in pixels) of a unit within a rack elevation.

docs/configuration/development.md

+# Development Parameters
+
+## DEBUG
+
+Default: False
+
+This setting enables debugging. Debugging should be enabled only during development or troubleshooting. Note that only
+clients which access NetBox from a recognized [internal IP address](#internal_ips) will see debugging tools in the user
+interface.
+
+!!! warning
+    Never enable debugging on a production system, as it can expose sensitive data to unauthenticated users and impose a
+    substantial performance penalty.
+
+---
+
+## DEVELOPER
+
+Default: False
+
+This parameter serves as a safeguard to prevent some potentially dangerous behavior, such as generating new database schema migrations. Set this to `True` **only** if you are actively developing the NetBox code base.

docs/configuration/index.md

 # NetBox Configuration
 
-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.
+## Configuration File
+
+NetBox's configuration file contains all the important parameters which control how NetBox functions: database settings, security controls, user preferences, and so on. While the default configuration suffices out of the box for most use cases, there are a few [required parameters](./required-parameters.md) which **must** be defined during installation. 
+
+The configuration file is loaded from `$INSTALL_ROOT/netbox/netbox/configuration.py` by default. An example configuration is provided at `configuration_example.py`, which you may copy to use as your default config. Note that a configuration file must be defined; NetBox will not run without one.
 
 !!! 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`.
+    To keep things simple, the NetBox documentation refers to the configuration file simply as `configuration.py`.
 
 Some configuration parameters may alternatively be defined either in `configuration.py` or within the administrative section of the user interface. Settings which are "hard-coded" in the configuration file take precedence over those defined via the UI.
 
-## Configuration Parameters
-
-* [Required settings](required-settings.md)
-* [Optional settings](optional-settings.md)
-* [Dynamic settings](dynamic-settings.md)
-* [Remote authentication settings](remote-authentication.md)
-
-## Changing the Configuration
-
-The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before the changes will take effect:
+## Dynamic Configuration Parameters
+
+Some configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These are noted where applicable in the documentation. These settings may also be overridden in `configuration.py` to prevent them from being modified via the UI. A complete list of supported parameters is provided below:
+
+* [`ALLOWED_URL_SCHEMES`](./security.md#allowed_url_schemes)
+* [`BANNER_BOTTOM`](./miscellaneous.md#banner_bottom)
+* [`BANNER_LOGIN`](./miscellaneous.md#banner_login)
+* [`BANNER_TOP`](./miscellaneous.md#banner_top)
+* [`CHANGELOG_RETENTION`](./miscellaneous.md#changelog_retention)
+* [`CUSTOM_VALIDATORS`](./data-validation.md#custom_validators)
+* [`DEFAULT_USER_PREFERENCES`](./default-values.md#default_user_preferences)
+* [`ENFORCE_GLOBAL_UNIQUE`](./miscellaneous.md#enforce_global_unique)
+* [`GRAPHQL_ENABLED`](./miscellaneous.md#graphql_enabled)
+* [`JOBRESULT_RETENTION`](./miscellaneous.md#jobresult_retention)
+* [`MAINTENANCE_MODE`](./miscellaneous.md#maintenance_mode)
+* [`MAPS_URL`](./miscellaneous.md#maps_url)
+* [`MAX_PAGE_SIZE`](./miscellaneous.md#max_page_size)
+* [`NAPALM_ARGS`](./napalm.md#napalm_args)
+* [`NAPALM_PASSWORD`](./napalm.md#napalm_password)
+* [`NAPALM_TIMEOUT`](./napalm.md#napalm_timeout)
+* [`NAPALM_USERNAME`](./napalm.md#napalm_username)
+* [`PAGINATE_COUNT`](./default-values.md#paginate_count)
+* [`POWERFEED_DEFAULT_AMPERAGE`](./default-values.md#powerfeed_default_amperage)
+* [`POWERFEED_DEFAULT_MAX_UTILIZATION`](./default-values.md#powerfeed_default_max_utilization)
+* [`POWERFEED_DEFAULT_VOLTAGE`](./default-values.md#powerfeed_default_voltage)
+* [`PREFER_IPV4`](./miscellaneous.md#prefer_ipv4)
+* [`RACK_ELEVATION_DEFAULT_UNIT_HEIGHT`](./default-values.md#rack_elevation_default_unit_height)
+* [`RACK_ELEVATION_DEFAULT_UNIT_WIDTH`](./default-values.md#rack_elevation_default_unit_width)
+
+## Modifying the Configuration
+
+The configuration file may be modified at any time. However, the WSGI service (e.g. Gunicorn) must be restarted before these changes will take effect:
 
 ```no-highlight
 $ sudo systemctl restart netbox

docs/configuration/dynamic-settings.md → docs/configuration/miscellaneous.md

-# Dynamic Configuration Settings
+# Miscellaneous Parameters
 
-These configuration parameters are primarily controlled via NetBox's admin interface (under Admin > Extras > Configuration Revisions). These setting may also be overridden in `configuration.py`; this will prevent them from being modified via the UI.
+## ADMINS
 
----
-
-## ALLOWED_URL_SCHEMES
-
-Default: `('file', 'ftp', 'ftps', 'http', 'https', 'irc', 'mailto', 'sftp', 'ssh', 'tel', 'telnet', 'tftp', 'vnc', 'xmpp')`
+NetBox will email details about critical errors to the administrators listed here. This should be a list of (name, email) tuples. For example:
 
-A list of permitted URL schemes referenced when rendering links within NetBox. Note that only the schemes specified in this list will be accepted: If adding your own, be sure to replicate all of the default values as well (excluding those schemes which are not desirable).
+```python
+ADMINS = [
+    ['Hank Hill', 'hhill@example.com'],
+    ['Dale Gribble', 'dgribble@example.com'],
+]
+```
 
 ---
 
-## BANNER_TOP
-
 ## BANNER_BOTTOM
 
-Setting these variables will display custom content in a banner at the top and/or bottom of the page, respectively. HTML is allowed. To replicate the content of the top banner in the bottom banner, set:
+!!! tip "Dynamic Configuration Parameter"
 
-```python
-BANNER_TOP = 'Your banner text'
-BANNER_BOTTOM = BANNER_TOP
-```
+Sets content for the bottom banner in the user interface.
 
 ---
 
 ## BANNER_LOGIN
 
+!!! tip "Dynamic Configuration Parameter"
+
 This defines custom content to be displayed on the login page above the login form. HTML is allowed.
 
 ---
 
-## CHANGELOG_RETENTION
+## BANNER_TOP
 
-Default: 90
+!!! tip "Dynamic Configuration Parameter"
 
-The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain
-changes in the database indefinitely.
+Sets content for the top banner in the user interface.
 
-!!! warning
-    If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity.
+!!! tip
+    If you'd like the top and bottom banners to match, set the following:
+    
+    ```python
+    BANNER_TOP = 'Your banner text'
+    BANNER_BOTTOM = BANNER_TOP
+    ```
 
 ---
 
-## CUSTOM_VALIDATORS
-
-This is a mapping of models to [custom validators](../customization/custom-validation.md) that have been defined locally to enforce custom validation logic. An example is provided below:
-
-```python
-CUSTOM_VALIDATORS = {
-    "dcim.site": [
-        {
-            "name": {
-                "min_length": 5,
-                "max_length": 30
-            }
-        },
-        "my_plugin.validators.Validator1"
-    ],
-    "dim.device": [
-        "my_plugin.validators.Validator1"
-    ]
-}
-```
-
----
+## CHANGELOG_RETENTION
 
-## DEFAULT_USER_PREFERENCES
+!!! tip "Dynamic Configuration Parameter"
 
-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:
+Default: 90
 
-```python
-DEFAULT_USER_PREFERENCES = {
-    "pagination": {
-        "per_page": 100
-    }
-}
-```
+The number of days to retain logged changes (object creations, updates, and deletions). Set this to `0` to retain
+changes in the database indefinitely.
 
-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`.
+!!! warning
+    If enabling indefinite changelog retention, it is recommended to periodically delete old entries. Otherwise, the database may eventually exceed capacity.
 
 ---
 
 ## ENFORCE_GLOBAL_UNIQUE
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: False
 
 By default, NetBox will permit users to create duplicate prefixes and IP addresses in the global table (that is, those which are not assigned to any VRF). This behavior can be disabled by setting `ENFORCE_GLOBAL_UNIQUE` to True.
@@ -92,6 +71,8 @@ By default, NetBox will permit users to create duplicate prefixes and IP address
 
 ## GRAPHQL_ENABLED
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: True
 
 Setting this to False will disable the GraphQL API.
@@ -100,6 +81,8 @@ Setting this to False will disable the GraphQL API.
 
 ## JOBRESULT_RETENTION
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: 90
 
 The number of days to retain job results (scripts and reports). Set this to `0` to retain
@@ -112,6 +95,8 @@ job results in the database indefinitely.
 
 ## MAINTENANCE_MODE
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: False
 
 Setting this to True will display a "maintenance mode" banner at the top of every page. Additionally, NetBox will no longer update a user's "last active" time upon login. This is to allow new logins when the database is in a read-only state. Recording of login times will resume when maintenance mode is disabled.
@@ -120,6 +105,8 @@ Setting this to True will display a "maintenance mode" banner at the top of ever
 
 ## MAPS_URL
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: `https://maps.google.com/?q=` (Google Maps)
 
 This specifies the URL to use when presenting a map of a physical location by street address or GPS coordinates. The URL must accept either a free-form street address or a comma-separated pair of numeric coordinates appended to it.
@@ -128,105 +115,45 @@ This specifies the URL to use when presenting a map of a physical location by st
 
 ## MAX_PAGE_SIZE
 
+!!! tip "Dynamic Configuration Parameter"
+
 Default: 1000
 
 A web user or API consumer can request an arbitrary number of objects by appending the "limit" parameter to the URL (e.g. `?limit=1000`). This parameter defines the maximum acceptable limit. Setting this to `0` or `None` will allow a client to retrieve _all_ matching objects at once with no limit by specifying `?limit=0`.
 
 ---
 
-## NAPALM_USERNAME
-
-## NAPALM_PASSWORD
+## METRICS_ENABLED
 
-NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../additional-features/napalm.md), if installed. Both parameters are optional.
-
-!!! note
-    If SSH public key authentication has been set up on the remote device(s) for the system account under which NetBox runs, these parameters are not needed.
-
----
-
-## NAPALM_ARGS
-
-A dictionary of optional arguments to pass to NAPALM when instantiating a network driver. See the NAPALM documentation for a [complete list of optional arguments](https://napalm.readthedocs.io/en/latest/support/#optional-arguments). An example:
-
-```python
-NAPALM_ARGS = {
-    'api_key': '472071a93b60a1bd1fafb401d9f8ef41',
-    'port': 2222,
-}
-```
-
-Some platforms (e.g. Cisco IOS) require an argument named `secret` to be passed in addition to the normal password. If desired, you can use the configured `NAPALM_PASSWORD` as the value for this argument:
-
-```python
-NAPALM_USERNAME = 'username'
-NAPALM_PASSWORD = 'MySecretPassword'
-NAPALM_ARGS = {
-    'secret': NAPALM_PASSWORD,
-    # Include any additional args here
-}
-```
-
----
-