Merge pull request #13614 from netbox-community/develop

Release v3.6.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.5.9
+      placeholder: v3.6.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.5.9
+      placeholder: v3.6.0
     validations:
       required: true
   - type: dropdown

base_requirements.txt

@@ -2,13 +2,9 @@
 # https://github.com/mozilla/bleach/blob/main/CHANGES
 bleach
 
-# Python client for Amazon AWS API
-# https://github.com/boto/boto3/blob/develop/CHANGELOG.rst
-boto3
-
 # The Python web framework on which NetBox is built
 # https://docs.djangoproject.com/en/stable/releases/
-Django<4.2
+Django<5.0
 
 # Django middleware which permits cross-domain API requests
 # https://github.com/adamchainz/django-cors-headers/blob/main/CHANGELOG.rst
@@ -74,10 +70,6 @@ drf-spectacular
 # https://github.com/tfranzel/drf-spectacular-sidecar
 drf-spectacular-sidecar
 
-# Git client for file sync
-# https://github.com/jelmer/dulwich/releases
-dulwich
-
 # RSS feed parser
 # https://github.com/kurtmckee/feedparser/blob/develop/CHANGELOG.rst
 feedparser
@@ -121,8 +113,8 @@ netaddr
 Pillow
 
 # PostgreSQL database adapter for Python
-# https://www.psycopg.org/docs/news.html
-psycopg2-binary
+# https://github.com/psycopg/psycopg/blob/master/docs/news.rst
+psycopg[binary,pool]
 
 # YAML rendering library
 # https://github.com/yaml/pyyaml/blob/master/CHANGES

docs/administration/permissions.md

@@ -68,8 +68,13 @@ When defining a permission constraint, administrators may use the special token
 
 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.
 
+### Default Permissions
 
-#### Example Constraint Definitions
+!!! info "This feature was introduced in NetBox v3.6."
+
+While permissions are typically assigned to specific groups and/or users, it is also possible to define a set of default permissions that are applied to _all_ authenticated users. This is done using the [`DEFAULT_PERMISSIONS`](../configuration/security.md#default_permissions) configuration parameter. Note that statically configuring permissions for specific users or groups is **not** supported.
+
+### Example Constraint Definitions
 
 | Constraints | Description |
 | ----------- | ----------- |

docs/administration/replicating-netbox.md

@@ -54,7 +54,7 @@ pg_dump --username netbox --password --host localhost -s netbox > netbox_schema.
 By default, NetBox stores uploaded files (such as image attachments) in its media directory. To fully replicate an instance of NetBox, you'll need to copy both the database and the media files.
 
 !!! note
-    These operations are not necessary if your installation is utilizing a [remote storage backend](../../configuration/optional-settings/#storage_backend).
+    These operations are not necessary if your installation is utilizing a [remote storage backend](../configuration/system.md#storage_backend).
 
 ### Archive the Media Directory
 

docs/configuration/plugins.md

@@ -4,7 +4,7 @@
 
 Default: Empty
 
-A list of installed [NetBox plugins](../../plugins/) to enable. Plugins will not take effect unless they are listed here.
+A list of installed [NetBox plugins](../plugins/index.md) to enable. Plugins will not take effect unless they are listed here.
 
 !!! warning
     Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled.

docs/configuration/required-parameters.md

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

docs/configuration/security.md

@@ -4,7 +4,7 @@
 
 Default: True
 
-If disabled, the values of API tokens will not be displayed after each token's initial creation. A user **must** record the value of a token immediately upon its creation, or it will be lost. Note that this affects _all_ users, regardless of assigned permissions.
+If disabled, the values of API tokens will not be displayed after each token's initial creation. A user **must** record the value of a token prior to its creation, or it will be lost. Note that this affects _all_ users, regardless of assigned permissions.
 
 ---
 
@@ -90,6 +90,38 @@ CSRF_TRUSTED_ORIGINS = (
 
 ---
 
+## DEFAULT_PERMISSIONS
+
+!!! info "This parameter was introduced in NetBox v3.6."
+
+Default:
+
+```python
+{
+    'users.view_token': ({'user': '$user'},),
+    'users.add_token': ({'user': '$user'},),
+    'users.change_token': ({'user': '$user'},),
+    'users.delete_token': ({'user': '$user'},),
+}
+```
+
+This parameter defines object permissions that are applied automatically to _any_ authenticated user, regardless of what permissions have been defined in the database. By default, this parameter is defined to allow all users to manage their own API tokens, however it can be overriden for any purpose.
+
+For example, to allow all users to create a device role beginning with the word "temp," you could configure the following:
+
+```python
+DEFAULT_PERMISSIONS = {
+    'dcim.add_devicerole': (
+        {'name__startswith': 'temp'},
+    )
+}
+```
+
+!!! warning
+    Setting a custom value for this parameter will overwrite the default permission mapping shown above. If you want to retain the default mapping, be sure to reproduce it in your custom configuration.
+
+---
+
 ## EXEMPT_VIEW_PERMISSIONS
 
 Default: Empty list

docs/customization/custom-fields.md

@@ -60,7 +60,7 @@ NetBox supports limited custom validation for custom field values. Following are
 
 ### Custom Selection Fields
 
-Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible.
+Each custom selection field must designate a [choice set](../models/extras/customfieldchoiceset.md) containing at least two choices. These are specified as a comma-separated list.
 
 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.
 

docs/customization/custom-scripts.md

@@ -390,7 +390,7 @@ class NewBranchScript(Script):
                 name=f'{site.slug}-switch{i}',
                 site=site,
                 status=DeviceStatusChoices.STATUS_PLANNED,
-                device_role=switch_role
+                role=switch_role
             )
             switch.full_clean()
             switch.save()

docs/development/application-registry.md

@@ -8,6 +8,10 @@ The registry can be inspected by importing `registry` from `extras.registry`.
 
 ## Stores
 
+### `counter_fields`
+
+A dictionary mapping of models to foreign keys with which cached counter fields are associated.
+
 ### `data_backends`
 
 A dictionary mapping data backend types to their respective classes. These are used to interact with [remote data sources](../models/core/datasource.md).

docs/development/internationalization.md

@@ -0,0 +1,123 @@
+# Internationalization
+
+Beginning with NetBox v4.0, NetBox will leverage [Django's automatic translation](https://docs.djangoproject.com/en/stable/topics/i18n/translation/) to support languages other than English. This page details the areas of the project which require special attention to ensure functioning translation support. Briefly, these include:
+
+* The `verbose_name` and `verbose_name_plural` Meta attributes for each model
+* The `verbose_name` and (if defined) `help_text` for each model field
+* The `label` for each form field
+* Headers for `fieldsets` on each form class
+* The `verbose_name` for each table column
+* All human-readable strings within templates must be wrapped with `{% trans %}` or `{% blocktrans %}`
+
+The rest of this document elaborates on each of the items above.
+
+## General Guidance
+
+* Wrap human-readable strings with Django's `gettext()` or `gettext_lazy()` utility functions to enable automatic translation. Generally, `gettext_lazy()` is preferred (and sometimes required) to defer translation until the string is displayed.
+
+* By convention, the preferred translation function is typically imported as an underscore (`_`) to minimize boilerplate code. Thus, you will often see translation as e.g. `_("Some text")`. It is still an option to import and use alternative translation functions (e.g. `pgettext()` and `ngettext()`) normally as needed.
+
+* Avoid passing markup and other non-natural language where possible. Everything wrapped by a translation function gets exported to a messages file for translation by a human.
+
+* Where the intended meaning of the translated string may not be obvious, use `pgettext()` or `pgettext_lazy()` to include assisting context for the translator. For example:
+
+    ```python
+    # Context, string
+    pgettext("month name", "May")
+    ```
+
+* **Format strings do not support translation.** Avoid "f" strings for messages that must support translation. Instead, use `format()` to accomplish variable replacement:
+
+    ```python
+    # Translation will not work
+    f"There are {count} objects"
+
+    # Do this instead
+    "There are {count} objects".format(count=count)
+    ```
+
+## Models
+
+1. Import `gettext_lazy` as `_`.
+2. Ensure both `verbose_name` and `verbose_name_plural` are defined under the model's `Meta` class and wrapped with the `gettext_lazy()` shortcut.
+3. Ensure each model field specifies a `verbose_name` wrapped with `gettext_lazy()`.
+4. Ensure any `help_text` attributes on model fields are also wrapped with `gettext_lazy()`.
+
+```python
+from django.utils.translation import gettext_lazy as _
+
+class Circuit(PrimaryModel):
+    commit_rate = models.PositiveIntegerField(
+        ...
+        verbose_name=_('commit rate (Kbps)'),
+        help_text=_("Committed rate")
+    )
+
+    class Meta:
+        verbose_name = _('circuit')
+        verbose_name_plural = _('circuits')
+```
+
+## Forms
+
+1. Import `gettext_lazy` as `_`.
+2. All form fields must specify a `label` wrapped with `gettext_lazy()`.
+3. All headers under a form's `fieldsets` property must be wrapped with `gettext_lazy()`.
+
+```python
+from django.utils.translation import gettext_lazy as _
+
+class CircuitBulkEditForm(NetBoxModelBulkEditForm):
+    description = forms.CharField(
+        label=_('Description'),
+        ...
+    )
+
+    fieldsets = (
+        (_('Circuit'), ('provider', 'type', 'status', 'description')),
+    )
+```
+
+## Tables
+
+1. Import `gettext_lazy` as `_`.
+2. All table columns must specify a `verbose_name` wrapped with `gettext_lazy()`.
+
+```python
+from django.utils.translation import gettext_lazy as _
+
+class CircuitTable(TenancyColumnsMixin, ContactsColumnMixin, NetBoxTable):
+    provider = tables.Column(
+        verbose_name=_('Provider'),
+        ...
+    )
+```
+
+## Templates
+
+1. Ensure translation support is enabled by including `{% load i18n %}` at the top of the template.
+2. Use the [`{% trans %}`](https://docs.djangoproject.com/en/stable/topics/i18n/translation/#translate-template-tag) tag (short for "translate") to wrap short strings.
+3. Longer strings may be enclosed between [`{% blocktrans %}`](https://docs.djangoproject.com/en/stable/topics/i18n/translation/#blocktranslate-template-tag) and `{% endblocktrans %}` tags to improve readability and to enable variable replacement.
+4. Avoid passing HTML within translated strings where possible, as this can complicate the work needed of human translators to develop message maps.
+
+```
+{% load i18n %}
+
+{# A short string #}
+<h5 class="card-header">{% trans "Circuit List" %}</h5>
+
+{# A longer string with a context variable #}
+{% blocktrans with count=object.circuits.count %}
+  There are {count} circuits. Would you like to continue?
+{% endblocktrans %}
+```
+
+!!! warning
+    The `{% blocktrans %}` tag supports only **limited variable replacement**, comparable to the `format()` method on Python strings. It does not permit access to object attributes or the use of other template tags or filters inside it. Ensure that any necessary context is passed as simple variables.
+
+!!! info
+    The `{% trans %}` and `{% blocktrans %}` support the inclusion of contextual hints for translators using the `context` argument:
+
+    ```nohighlight
+    {% trans "May" context "month name" %}
+    ```

docs/features/configuration-rendering.md

@@ -1,7 +1,5 @@
 # Configuration Rendering
 
-!!! info "This feature was introduced in NetBox v3.5."
-
 One of the critical aspects of operating a network is ensuring that every network node is configured correctly. By leveraging configuration templates and [context data](./context-data.md), NetBox can render complete configuration files for each device on your network.
 
 ```mermaid
@@ -39,6 +37,14 @@ Configuration templates are written in the [Jinja2 templating language](https://
 
 When rendered for a specific NetBox device, the template's `device` variable will be populated with the device instance, and `ntp_servers` will be pulled from the device's available context data. The resulting output will be a valid configuration segment that can be applied directly to a compatible network device.
 
+### Context Data
+
+The objet for which the configuration is being rendered is made available as template context as `device` or `virtualmachine` for devices and virtual machines, respectively. Additionally, NetBox model classes can be accessed by the app or plugin in which they reside. For example:
+
+```
+There are {{ dcim.Site.objects.count() }} sites.
+```
+
 ## Rendering Templates
 
 ### Device Configurations

docs/features/customization.md

@@ -18,6 +18,12 @@ The `tag` filter can be specified multiple times to match only objects which hav
 GET /api/dcim/devices/?tag=monitored&tag=deprecated
 ```
 
+## Bookmarks
+
+!!! info "This feature was introduced in NetBox v3.6."
+
+Users can bookmark their most commonly visited objects for convenient access. Bookmarks are listed under a user's profile, and can be displayed with custom filtering and ordering on the user's personal dashboard.
+
 ## Custom Fields
 
 While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs.

docs/features/synchronized-data.md

@@ -1,7 +1,5 @@
 # Synchronized Data
 
-!!! info "This feature was introduced in NetBox v3.5."
-
 Several models in NetBox support the automatic synchronization of local data from a designated remote source. For example, [configuration templates](./configuration-rendering.md) defined in NetBox can source their content from text files stored in a remote git repository. This accomplished using the core [data source](../models/core/datasource.md) and [data file](../models/core/datafile.md) models.
 
 To enable remote data synchronization, the NetBox administrator first designates one or more remote data sources. NetBox currently supports the following source types:
@@ -12,6 +10,10 @@ To enable remote data synchronization, the NetBox administrator first designates
 
 (Local disk paths are considered "remote" in this context as they exist outside NetBox's database. These paths could also be mapped to external network shares.)
 
+
+!!! info
+    Data backends which connect to external sources typically require the installation of one or more supporting Python libraries. The Git backend requires the [`dulwich`](https://www.dulwich.io/) package, and the S3 backend requires the [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) package. These must be installed within NetBox's environment to enable these backends.
+
 Each type of remote source has its own configuration parameters. For instance, a git source will ask the user to specify a branch and authentication credentials. Once the source has been created, a synchronization job is run to automatically replicate remote files in the local database.
 
 The following NetBox models can be associated with replicated data files:

docs/installation/1-postgresql.md

@@ -2,8 +2,8 @@
 
 This section entails the installation and configuration of a local PostgreSQL database. If you already have a PostgreSQL database service in place, skip to [the next section](2-redis.md).
 
-!!! warning "PostgreSQL 11 or later required"
-    NetBox requires PostgreSQL 11 or later. Please note that MySQL and other relational databases are **not** supported.
+!!! warning "PostgreSQL 12 or later required"
+    NetBox requires PostgreSQL 12 or later. Please note that MySQL and other relational databases are **not** supported.
 
 ## Installation
 
@@ -35,7 +35,7 @@ This section entails the installation and configuration of a local PostgreSQL da
     sudo systemctl enable postgresql
     ```
 
-Before continuing, verify that you have installed PostgreSQL 11 or later:
+Before continuing, verify that you have installed PostgreSQL 12 or later:
 
 ```no-highlight
 psql -V

docs/installation/3-netbox.md

@@ -211,6 +211,22 @@ By default, NetBox will use the local filesystem to store uploaded files. To use
 sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"
 ```
 
+### Remote Data Sources
+
+NetBox supports integration with several remote data sources via configurable backends. Each of these requires the installation of one or more additional libraries.
+
+* Amazon S3: [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
+* Git: [`dulwich`](https://www.dulwich.io/)
+
+For example, to enable the Amazon S3 backend, add `boto3` to your local requirements file:
+
+```no-highlight
+sudo sh -c "echo 'boto3' >> /opt/netbox/local_requirements.txt"
+```
+
+!!! info
+    These packages were previously required in NetBox v3.5 but now are optional.
+
 ## Run the Upgrade Script
 
 Once NetBox has been configured, we're ready to proceed with the actual installation. We'll run the packaged upgrade script (`upgrade.sh`) to perform the following actions: