Merge pull request #7061 from netbox-community/feature

v3.0 release prep

Author: jeremystretch

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -25,7 +25,6 @@ body:
       label: Python version
       description: What version of Python are you currently running?
       options:
-        - 3.6
         - 3.7
         - 3.8
         - 3.9

.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,13 @@ 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](docs/media/home-light.png "Main Page")
 
-![Screenshot of rack elevation](docs/media/screenshot2.png "Rack elevation")
+![Screenshot of Rack Elevation](docs/media/rack-dark.png "Rack Elevation")
 
-![Screenshot of prefix hierarchy](docs/media/screenshot3.png "Prefix hierarchy")
+![Screenshot of Prefix Hierarchy](docs/media/prefixes-light.png "Prefix Hierarchy")
+
+![Screenshot of Cable Tracing](docs/media/cable-dark.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 @@
 # 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.
 
 ---
 
@@ -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)

docs/core-functionality/secrets.md

@@ -1,8 +1,8 @@
 # Custom Links
 
-Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside of NetBox. For example, you might create a custom link on the device view which links to the current device in a network monitoring system.
+Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a network monitoring system.
 
-Custom links are created under the admin UI. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link is assigned text and a URL, both of which support Jinja2 templating. The text and URL are rendered with the context variable `obj` representing the current object.
+Custom links are created by navigating to Customization > Custom Links. Each link is associated with a particular NetBox object type (site, device, prefix, etc.) and will be displayed on relevant views. Each link is assigned text and a URL, both of which support Jinja2 templating. The text and URL are rendered with the context variable `obj` representing the current object.
 
 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 at 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.
 
 !!! 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.