Release v2.10.0

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ jobs:
  runs-on: ubuntu-latest
  strategy:
  matrix:
- python-version: [3.6, 3.7]
+ python-version: [3.6, 3.7, 3.8]
  services:
  redis:
  image: redis

CONTRIBUTING.md

@@ -15,8 +15,6 @@ categories for discussions:
 * **Ideas** - Ideas for new functionality that isn't yet ready for a formal
  feature request
 * **Q&A** - Request help with installing or using NetBox
-* **Show and tell** - Share a plugin, script, or something else you've made
- using NetBox
 
 ### Mailing List
 

docs/additional-features/custom-fields.md

@@ -1,26 +1,69 @@
 # Custom Fields
 
-Each object in NetBox is represented in the database as a discrete table, and each attribute of an object exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
+Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the `dcim_site` table, which has columns named `name`, `facility`, `physical_address`, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.
 
-However, some users might want to associate with objects attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number pointing to the support ticket that was opened to have it installed. This is certainly a legitimate use for NetBox, but it's perhaps not a common enough need to warrant expanding the internal data schema. Instead, you can create a custom field to hold this data.
+However, some users might want to store additional object attributes that are somewhat esoteric in nature, and that would not make sense to include in the core NetBox database schema. For instance, suppose your organization needs to associate each device with a ticket number correlating it with an internal support system record. This is certainly a legitimate use for NetBox, but it's not a common enough need to warrant including a field for _every_ NetBox installation. Instead, you can create a custom field to hold this data.
 
-Custom fields must be created through the admin UI under Extras > Custom Fields. To create a new custom field, select the object(s) to which you want it to apply, and the type of field it will be. NetBox supports six field types:
+Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects.
 
-* Free-form text (up to 255 characters)
-* Integer
-* Boolean (true/false)
-* Date
-* URL
-* Selection
+## Creating Custom Fields
 
-Assign the field a name. This should be a simple database-friendly string, e.g. `tps_report`. You may optionally assign the field a human-friendly label (e.g. "TPS report") as well; the label will be displayed on forms. If a description is provided, it will appear beneath the field in a form.
+Custom fields must be created through the admin UI under Extras > Custom Fields. NetBox supports six types of custom field:
 
-Marking the field as required will require the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields. (The default value has no effect for selection fields.)
+* Text: Free-form text (up to 255 characters)
+* Integer: A whole number (positive or negative)
+* Boolean: True or false
+* Date: A date in ISO 8601 format (YYYY-MM-DD)
+* URL: This will be presented as a link in the web UI
+* Selection: A selection of one of several pre-defined custom choices
 
-When creating a selection field, you should create at least two choices. These choices will be arranged first by weight, with lower weights appearing higher in the list, and then alphabetically.
+Each custom field must have a name; this should be a simple database-friendly string, e.g. `tps_report`. 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.
 
-## Using Custom Fields
+Marking a field as required will force the user to provide a value for the field when creating a new object or when saving an existing object. A default value for the field may also be provided. Use "true" or "false" for boolean fields, or the exact value of a choice for selection fields.
 
-When a single object is edited, the form will include any custom fields which have been defined for the object type. These fields are included in the "Custom Fields" panel. On the backend, each custom field value is saved separately from the core object as an independent database call, so it's best to avoid adding too many custom fields per object.
+The filter logic controls how values are matched when filtering objects by the custom field. Loose filtering (the default) matches on a partial value, whereas exact matching requires a complete match of the given string to a field's value. For example, exact filtering with the string "red" will only match the exact value "red", whereas loose filtering will match on the values "red", "red-orange", or "bored". Setting the filter logic to "disabled" disables filtering by the field entirely.
 
-When editing multiple objects, custom field values are saved in bulk. There is no significant difference in overhead when saving a custom field value for 100 objects versus one object. However, the bulk operation must be performed separately for each custom field.
+A custom field must be assigned to one or object types, or models, in NetBox. Once created, custom fields will automatically appear as part of these models in the web UI and REST API. Note that not all models support custom fields.
+
+### Custom Field Validation
+
+NetBox supports limited custom validation for custom field values. Following are the types of validation enforced for each field type:
+
+* Text: Regular expression (optional)
+* Integer: Minimum and/or maximum value (optional)
+* Selection: Must exactly match one of the prescribed choices
+
+### 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.
+
+If a default value is specified for a selection field, it must exactly match one of the provided choices.
+
+## Custom Fields and the REST API
+
+When retrieving an object via the REST API, all of its custom data will be included within the `custom_fields` attribute. For example, below is the partial output of a site with two custom fields defined:
+
+```json
+{
+ "id": 123,
+ "url": "http://localhost:8000/api/dcim/sites/123/",
+ "name": "Raleigh 42",
+ ...
+ "custom_fields": {
+ "deployed": "2018-06-19",
+ "site_code": "US-NC-RAL42"
+ },
+ ...
+```
+
+To set or change these values, simply include nested JSON data. For example:
+
+```json
+{
+ "name": "New Site",
+ "slug": "new-site",
+ "custom_fields": {
+ "deployed": "2019-03-24"
+ }
+}
+```

docs/administration/netbox-shell.md

@@ -185,7 +185,7 @@ To delete an object, simply call `delete()` on its instance. This will return a
 >>> vlan
 <VLAN: 123 (BetterName)>
 >>> vlan.delete()
-(1, {'extras.CustomFieldValue': 0, 'ipam.VLAN': 1})
+(1, {'ipam.VLAN': 1})
 ```
 
 To delete multiple objects at once, call `delete()` on a filtered queryset. It's a good idea to always sanity-check the count of selected objects _before_ deleting them.
@@ -194,9 +194,9 @@ 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, {'extras.CustomFieldValue': 0, 'dcim.DeviceBay': 0, 'secrets.Secret': 0,
-'dcim.InterfaceConnection': 4, 'extras.ImageAttachment': 0, 'dcim.Device': 27,
-'dcim.Interface': 4, 'dcim.ConsolePort': 0, 'dcim.PowerPort': 0})
+(35, {'dcim.DeviceBay': 0, 'secrets.Secret': 0, 'dcim.InterfaceConnection': 4,
+'extras.ImageAttachment': 0, 'dcim.Device': 27, 'dcim.Interface': 4,
+'dcim.ConsolePort': 0, 'dcim.PowerPort': 0})
 ```
 
 !!! warning

docs/configuration/optional-settings.md

@@ -460,7 +460,7 @@ NetBox can be configured to support remote user authentication by inferring user
 
 Default: `'HTTP_REMOTE_USER'`
 
-When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. (Requires `REMOTE_AUTH_ENABLED`.)
+When remote user authentication is in use, this is the name of the HTTP header which informs NetBox of the currently authenticated user. For example, to use the request header `X-Remote-User` it needs to be set to `HTTP_X_REMOTE_USER`. (Requires `REMOTE_AUTH_ENABLED`.)
 
 ---
 

docs/core-functionality/ipam.md

@@ -15,3 +15,4 @@
 ---
 
 {!docs/models/ipam/vrf.md!}
+{!docs/models/ipam/routetarget.md!}

docs/index.md

@@ -55,7 +55,7 @@ NetBox is built on the [Django](https://djangoproject.com/) Python framework and
 
 ## Supported Python Versions
 
-NetBox supports Python 3.6 and 3.7 environments currently. (Support for Python 3.5 was removed in NetBox v2.8.)
+NetBox supports Python 3.6, 3.7, and 3.8 environments currently. (Support for Python 3.5 was removed in NetBox v2.8.)
 
 ## Getting Started
 

docs/installation/1-postgresql.md

@@ -5,30 +5,27 @@ This section entails the installation and configuration of a local PostgreSQL da
 !!! warning
  NetBox requires PostgreSQL 9.6 or higher. Please note that MySQL and other relational databases are **not** currently supported.
 
-The installation instructions provided here have been tested to work on Ubuntu 18.04 and CentOS 7.5. The particular commands needed to install dependencies on other distributions may vary significantly. Unfortunately, this is outside the control of the NetBox maintainers. Please consult your distribution's documentation for assistance with any errors.
-
 ## Installation
 
 #### Ubuntu
 
-If a recent enough version of PostgreSQL is not available through your distribution's package manager, you'll need to install it from an official [PostgreSQL repository](https://wiki.postgresql.org/wiki/Apt).
+Install the PostgreSQL server and client development libraries using `apt`.
 
 ```no-highlight
-# apt-get update
-# apt-get install -y postgresql libpq-dev
+sudo apt update
+sudo apt install -y postgresql libpq-dev
 ```
 
 #### CentOS
 
-CentOS 7 does not ship with a recent enough version of PostgreSQL, so it will need to be installed from an external repository. The instructions below show the installation of PostgreSQL 9.6, however you may opt to install a more recent version.
+PostgreSQL 9.6 and later are available natively on CentOS 8.2. If using an earlier CentOS release, you may need to [install it from an RPM](https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/).
 
 ```no-highlight
-# yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
-# yum install -y postgresql96 postgresql96-server postgresql96-devel
-# /usr/pgsql-9.6/bin/postgresql96-setup initdb
+sudo yum install -y postgresql-server libpq-devel
+sudo postgresql-setup --initdb
 ```
 
-CentOS users should modify the PostgreSQL configuration to accept password-based authentication by replacing `ident` with `md5` for all host entries within `/var/lib/pgsql/9.6/data/pg_hba.conf`. For example:
+CentOS configures ident host-based authentication for PostgreSQL by default. Because NetBox will need to authenticate using a username and password, modify `/var/lib/pgsql/data/pg_hba.conf` to support MD5 authentication by changing `ident` to `md5` for the lines below:
 
 ```no-highlight
 host all all 127.0.0.1/32 md5
@@ -38,8 +35,8 @@ host all all ::1/128 md5
 Then, start the service and enable it to run at boot:
 
 ```no-highlight
-# systemctl start postgresql-9.6
-# systemctl enable postgresql-9.6
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
 ```
 
 ## Database Creation
@@ -50,8 +47,8 @@ At a minimum, we need to create a database for NetBox and assign it a username a
  **Do not use the password from the example.** Choose a strong, random password to ensure secure database authentication for your NetBox installation.
 
 ```no-highlight
-# sudo -u postgres psql
-psql (10.12 (Ubuntu 10.12-0ubuntu0.18.04.1))
+$ sudo -u postgres psql
+psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))
 Type "help" for help.
 
 postgres=# CREATE DATABASE netbox;
@@ -68,13 +65,16 @@ postgres=# \q
 You can verify that authentication works issuing the following command and providing the configured password. (Replace `localhost` with your database server if using a remote database.)
 
 ```no-highlight
-# psql --username netbox --password --host localhost netbox
+$ psql --username netbox --password --host localhost netbox
 Password for user netbox: 
-psql (10.12 (Ubuntu 10.12-0ubuntu0.18.04.1))
+psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))
 SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
 Type "help" for help.
 
+netbox=> \conninfo
+You are connected to database "netbox" as user "netbox" on host "localhost" (address "127.0.0.1") at port "5432".
+SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
 netbox=> \q
 ```
 
-If successful, you will enter a `netbox` prompt. Type `\q` to exit.
+If successful, you will enter a `netbox` prompt. Type `\conninfo` to confirm your connection, or type `\q` to exit.

docs/installation/2-redis.md

@@ -10,16 +10,15 @@
 ### Ubuntu
 
 ```no-highlight
-# apt-get install -y redis-server
+sudo apt install -y redis-server
 ```
 
 ### CentOS
 
 ```no-highlight
-# yum install -y epel-release
-# yum install -y redis
-# systemctl start redis
-# systemctl enable redis
+sudo yum install -y redis
+sudo systemctl start redis
+sudo systemctl enable redis
 ```
 
 You may wish to modify the Redis configuration at `/etc/redis.conf` or `/etc/redis/redis.conf`, however in most cases the default configuration is sufficient.