Merge pull request #7069 from netbox-community/develop

Release v3.0.0

Author: jeremystretch

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -17,15 +17,14 @@ body:
         What version of NetBox are you currently running? (If you don't have access to the most
         recent NetBox release, consider testing on our [demo instance](https://demo.netbox.dev/)
         before opening a bug report to see if your issue has already been addressed.)
-      placeholder: v2.11.12
+      placeholder: v3.0.0
     validations:
       required: true
   - type: dropdown
     attributes:
       label: Python version
       description: What version of Python are you currently running?
       options:
-        - 3.6
         - 3.7
         - 3.8
         - 3.9

.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: v2.11.12
+      placeholder: v3.0.0
     validations:
       required: true
   - type: dropdown

.github/workflows/ci.yml

@@ -5,7 +5,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
+        node-version: [14.x]
     services:
       redis:
         image: redis
@@ -33,15 +34,30 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v2
+      with:
+        node-version: ${{ matrix.node-version }}
+
     - name: Install dependencies & set up configuration
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         pip install pycodestyle coverage
         ln -s configuration.testing.py netbox/netbox/configuration.py
+        yarn --cwd netbox/project-static
+
+    - name: Build documentation
+      run: mkdocs build
+
+    - name: Collect static files
+      run: python netbox/manage.py collectstatic --no-input
 
     - name: Check PEP8 compliance
-      run: pycodestyle --ignore=W504,E501 netbox/
+      run: pycodestyle --ignore=W504,E501 --exclude=node_modules netbox/
+
+    - name: Check UI ESLint, TypeScript, and Prettier Compliance
+      run: yarn --cwd netbox/project-static validate
 
     - name: Run tests
       run: coverage run --source="netbox/" netbox/manage.py test netbox/

.gitignore

@@ -1,5 +1,12 @@
 *.pyc
 *.swp
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+/netbox/project-static/.cache
+/netbox/project-static/docs/*
+!/netbox/project-static/docs/.info
 /netbox/netbox/configuration.py
 /netbox/netbox/ldap_config.py
 /netbox/project-static/.cache

README.md

@@ -54,11 +54,15 @@ our [contributing guide](CONTRIBUTING.md) prior to beginning any work.
 
 ### Screenshots
 
-![Screenshot of main page](docs/media/screenshot1.png "Main page")
+![Screenshot of main page (light mode)](docs/media/screenshots/home-light.png "Main page (light mode)")
 
-![Screenshot of rack elevation](docs/media/screenshot2.png "Rack elevation")
+![Screenshot of main page (dark mode)](docs/media/screenshots/home-dark.png "Main page (dark mode)")
 
-![Screenshot of prefix hierarchy](docs/media/screenshot3.png "Prefix hierarchy")
+![Screenshot of rack elevation](docs/media/screenshots/rack.png "Rack elevation")
+
+![Screenshot of prefixes hierarchy](docs/media/screenshots/prefixes-list.png "Prefixes hierarchy")
+
+![Screenshot of cable trace](docs/media/screenshots/cable-trace.png "Cable tracing")
 
 ### Related projects
 

base_requirements.txt

@@ -2,10 +2,6 @@
 # https://github.com/django/django
 Django
 
-# Django caching using Redis
-# https://github.com/Suor/django-cacheops
-django-cacheops
-
 # Django middleware which permits cross-domain API requests
 # https://github.com/OttoYiu/django-cors-headers
 django-cors-headers
@@ -18,6 +14,10 @@ django-debug-toolbar
 # https://github.com/carltongibson/django-filter
 django-filter
 
+# Django debug toolbar extension with support for GraphiQL
+# https://github.com/flavors/django-graphiql-debug-toolbar/
+django-graphiql-debug-toolbar
+
 # Modified Preorder Tree Traversal (recursive nesting of objects)
 # https://github.com/django-mptt/django-mptt
 django-mptt
@@ -30,6 +30,10 @@ django-pglocks
 # https://github.com/korfuri/django-prometheus
 django-prometheus
 
+# Django chaching backend using Redis
+# https://github.com/jazzband/django-redis
+django-redis
+
 # Django integration for RQ (Reqis queuing)
 # https://github.com/rq/django-rq
 django-rq
@@ -54,6 +58,10 @@ djangorestframework
 # https://github.com/axnsan12/drf-yasg
 drf-yasg[validation]
 
+# Django wrapper for Graphene (GraphQL support)
+# https://github.com/graphql-python/graphene-django
+graphene_django
+
 # WSGI HTTP server
 # https://gunicorn.org/
 gunicorn
@@ -66,6 +74,14 @@ Jinja2
 # https://github.com/Python-Markdown/markdown
 Markdown
 
+# File inclusion plugin for Python-Markdown
+# https://github.com/cmacmackin/markdown-include
+markdown-include
+
+# MkDocs Material theme (for documentation build)
+# https://github.com/squidfunk/mkdocs-material
+mkdocs-material
+
 # Library for manipulating IP prefixes and addresses
 # https://github.com/drkjam/netaddr
 netaddr

contrib/netbox-housekeeping.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# This shell script invokes NetBox's housekeeping management command, which
+# intended to be run nightly. This script can be copied into your system's
+# daily cron directory (e.g. /etc/cron.daily), or referenced directly from
+# within the cron configuration file.
+#
+# If NetBox has been installed into a nonstandard location, update the paths
+# below.
+/opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py housekeeping

contrib/netbox-rq.service

@@ -11,7 +11,7 @@ User=netbox
 Group=netbox
 WorkingDirectory=/opt/netbox
 
-ExecStart=/opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py rqworker
+ExecStart=/opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py rqworker high default low
 
 Restart=on-failure
 RestartSec=30

docs/additional-features/caching.md

@@ -1,6 +1,6 @@
 # NAPALM
 
-NetBox supports integration with the [NAPALM automation](https://napalm-automation.net/) library. NAPALM allows NetBox to serve a proxy for operational data, fetching live data from network devices and returning it to a requester via its REST API. Note that NetBox does not store any NAPALM data locally.
+NetBox supports integration with the [NAPALM automation](https://github.com/napalm-automation/napalm) library. NAPALM allows NetBox to serve a proxy for operational data, fetching live data from network devices and returning it to a requester via its REST API. Note that NetBox does not store any NAPALM data locally.
 
 The NetBox UI will display tabs for status, LLDP neighbors, and configuration under the device view if the following conditions are met:
 

docs/additional-features/napalm.md

@@ -1,6 +1,6 @@
 # Webhooks
 
-A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are configured in the admin UI under Extras > Webhooks.
+A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks.
 
 !!! warning
     Webhooks support the inclusion of user-submitted code to generate custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.

docs/additional-features/webhooks.md

@@ -0,0 +1,10 @@
+# Housekeeping
+
+NetBox includes a `housekeeping` management command that should be run nightly. This command handles:
+
+* Clearing expired authentication sessions from the database
+* Deleting changelog records older than the configured [retention time](../configuration/optional-settings.md#changelog_retention)
+
+This command can be invoked directly, or by using the shell script provided at `/opt/netbox/contrib/netbox-housekeeping.sh`. This script can be copied into your cron scheduler's daily jobs directory (e.g. `/etc/cron.daily`) or referenced directly within the cron configuration file.
+
+The `housekeeping` command can also be run manually at any time: Running the command outside of scheduled execution times will not interfere with its operation.

docs/administration/housekeeping.md

@@ -11,7 +11,7 @@ This will launch a lightly customized version of [the built-in Django shell](htt
 ```
 $ ./manage.py nbshell
 ### NetBox interactive shell (localhost)
-### Python 3.6.9 | Django 2.2.11 | NetBox 2.7.10
+### Python 3.7.10 | Django 3.2.5 | NetBox 3.0
 ### lsmodels() will show available models. Use help(<model>) for more info.
 ```
 
@@ -194,7 +194,7 @@ To delete multiple objects at once, call `delete()` on a filtered queryset. It's
 >>> Device.objects.filter(name__icontains='test').count()
 27
 >>> Device.objects.filter(name__icontains='test').delete()
-(35, {'dcim.DeviceBay': 0, 'secrets.Secret': 0, 'dcim.InterfaceConnection': 4,
+(35, {'dcim.DeviceBay': 0, 'dcim.InterfaceConnection': 4,
 'extras.ImageAttachment': 0, 'dcim.Device': 27, 'dcim.Interface': 4,
 'dcim.ConsolePort': 0, 'dcim.PowerPort': 0})
 ```

docs/administration/netbox-shell.md

@@ -52,14 +52,6 @@ BASE_PATH = 'netbox/'
 
 ---
 
-## CACHE_TIMEOUT
-
-Default: 0 (disabled)
-
-The number of seconds that cached database queries will be retained before expiring.
-
----
-
 ## CHANGELOG_RETENTION
 
 Default: 90
@@ -96,6 +88,22 @@ CORS_ORIGIN_WHITELIST = [
 
 ---
 
+## 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': (
+        Validator1,
+        Validator2,
+        Validator3
+    )
+}
+```
+
+---
+
 ## DEBUG
 
 Default: False
@@ -144,7 +152,7 @@ In order to send email, NetBox needs an email server configured. The following i
 !!! note
     The `USE_SSL` and `USE_TLS` parameters are mutually exclusive.
 
-Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) fuction accessible within the NetBox shell:
+Email is sent from NetBox only for critical events or if configured for [logging](#logging). If you would like to test the email server configuration, Django provides a convenient [send_mail()](https://docs.djangoproject.com/en/stable/topics/email/#send-mail) function accessible within the NetBox shell:
 
 ```no-highlight
 # python ./manage.py nbshell
@@ -195,6 +203,14 @@ EXEMPT_VIEW_PERMISSIONS = ['*']
 
 ---
 
+## GRAPHQL_ENABLED
+
+Default: True
+
+Setting this to False will disable the GraphQL API.
+
+---
+
 ## HTTP_PROXIES
 
 Default: None
@@ -271,7 +287,7 @@ Note that enabling this setting causes NetBox to update a user's session in the
 
 Default: False
 
-Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox (excluding secrets) but not make any changes.
+Setting this to True will permit only authenticated users to access any part of NetBox. By default, anonymous users are permitted to access most data in NetBox but not make any changes.
 
 ---
 
@@ -327,7 +343,7 @@ Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Pr
 
 ## NAPALM_PASSWORD
 
-NetBox will use these credentials when authenticating to remote devices via the [NAPALM library](https://napalm-automation.net/), if installed. Both parameters are optional.
+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.
@@ -482,19 +498,11 @@ When remote user authentication is in use, this is the name of the HTTP header w
 
 ---
 
-## RELEASE_CHECK_TIMEOUT
-
-Default: 86,400 (24 hours)
-
-The number of seconds to retain the latest version that is fetched from the GitHub API before automatically invalidating it and fetching it from the API again. This must be set to at least one hour (3600 seconds).
-
----
-
 ## RELEASE_CHECK_URL
 
 Default: None (disabled)
 
-This parameter defines the URL of the repository that will be checked periodically for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks.
+This parameter defines the URL of the repository that will be checked for new NetBox releases. When a new release is detected, a message will be displayed to administrative users on the home page. This can be set to the official repository (`'https://api.github.com/repos/netbox-community/netbox/releases'`) or a custom fork. Set this to `None` to disable automatic update checks.
 
 !!! note
     The URL provided **must** be compatible with the [GitHub REST API](https://docs.github.com/en/rest).
@@ -505,7 +513,7 @@ This parameter defines the URL of the repository that will be checked periodical
 
 Default: `$INSTALL_ROOT/netbox/reports/`
 
-The file path to the location where custom reports will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path.
+The file path to the location where [custom reports](../customization/reports.md) will be kept. By default, this is the `netbox/reports/` directory within the base NetBox installation path.
 
 ---
 
@@ -521,7 +529,7 @@ The maximum execution time of a background task (such as running a custom script
 
 Default: `$INSTALL_ROOT/netbox/scripts/`
 
-The file path to the location where custom scripts will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path.
+The file path to the location where [custom scripts](../customization/custom-scripts.md) will be kept. By default, this is the `netbox/scripts/` directory within the base NetBox installation path.
 
 ---
 

docs/configuration/optional-settings.md

@@ -10,6 +10,7 @@
 
 ---
 
+{!docs/models/ipam/iprange.md!}
 {!docs/models/ipam/ipaddress.md!}
 
 ---

docs/core-functionality/ipam.md

@@ -8,7 +8,7 @@ Within the database, custom fields are stored as JSON data directly alongside ea
 
 ## Creating Custom Fields
 
-Custom fields must be created through the admin UI under Extras > Custom Fields. NetBox supports six types of custom field:
+Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field:
 
 * Text: Free-form text (up to 255 characters)
 * Integer: A whole number (positive or negative)