Reorganize documentation

docs/additional-features/webhooks.md

@@ -1,57 +0,0 @@
-{!models/extras/webhook.md!}
-
-## Conditional Webhooks
-
-A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active":
-
-```json
-{
-  "and": [
-    {
-      "attr": "status.value",
-      "value": "active"
-    }
-  ]
-}
-```
-
-For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
-
-## Webhook Processing
-
-When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks.
-
-A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI.
-
-## Troubleshooting
-
-To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory:
-
-```no-highlight
-$ python netbox/manage.py webhook_receiver
-Listening on port http://localhost:9000. Stop with CONTROL-C.
-```
-
-You can test the receiver itself by sending any HTTP request to it. For example:
-
-```no-highlight
-$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}'
-```
-
-The server will print output similar to the following:
-
-```no-highlight
-[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 -
-Host: localhost:9000
-User-Agent: curl/7.58.0
-Accept: */*
-Content-Length: 14
-Content-Type: application/x-www-form-urlencoded
-
-{"foo": "bar"}
-------------
-```
-
-Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection.
-
-Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI).

docs/administration/permissions.md

@@ -1,8 +1,75 @@
-# 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:
+
+* 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
 

docs/configuration/miscellaneous.md

@@ -127,7 +127,7 @@ A web user or API consumer can request an arbitrary number of objects by appendi
 
 Default: False
 
-Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../additional-features/prometheus-metrics.md) documentation for more details.
+Toggle the availability Prometheus-compatible metrics at `/metrics`. See the [Prometheus Metrics](../integrations/prometheus-metrics.md) documentation for more details.
 
 ---
 

docs/configuration/napalm.md

@@ -6,7 +6,7 @@
 
 !!! tip "Dynamic Configuration Parameter"
 
-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.
+NetBox will use these credentials when authenticating to remote devices via the supported [NAPALM integration](../integrations/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.

docs/customization/custom-fields.md

@@ -1,4 +1,77 @@
-{!models/extras/customfield.md!}
+# Custom Fields
+
+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 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.
+
+Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects.
+
+## Creating Custom Fields
+
+Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field:
+
+* Text: Free-form text (intended for single-line use)
+* Long text: Free-form of any length; supports Markdown rendering
+* 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
+* JSON: Arbitrary data stored in JSON format
+* Selection: A selection of one of several pre-defined custom choices
+* Multiple selection: A selection field which supports the assignment of multiple values
+* Object: A single NetBox object of the type defined by `object_type`
+* Multiple object: One or more NetBox objects of the type defined by `object_type`
+
+Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. 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.
+
+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.
+
+A custom field must be assigned to one or more 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.
+
+### Filtering
+
+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.
+
+### Grouping
+
+!!! note
+    This feature was introduced in NetBox v3.3.
+
+Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.)
+
+This parameter has no effect on the API representation of custom field data.
+
+### Visibility
+
+!!! note
+    This feature was introduced in NetBox v3.3.
+
+When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI.
+
+* **Read/write** (default): The custom field is included when viewing and editing objects.
+* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.)
+* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users.
+
+Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API.
+
+### 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. The value of a multiple selection field will always return a list, even if only one value is selected.
+
+### Custom Object Fields
+
+An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point.
+
 
 ## Custom Fields in Templates
 

docs/customization/export-templates.md

@@ -1,4 +1,41 @@
-{!models/extras/exporttemplate.md!}
+# Export Templates
+
+NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.
+
+Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension.
+
+Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/).
+
+!!! note
+    The name `table` is reserved for internal use.
+
+!!! warning
+    Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users.
+
+The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example:
+
+```jinja2
+{% for rack in queryset %}
+Rack: {{ rack.name }}
+Site: {{ rack.site.name }}
+Height: {{ rack.u_height }}U
+{% endfor %}
+```
+
+To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`.
+
+If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example:
+```
+{% for server in queryset %}
+{% set data = server.get_config_context() %}
+{{ data.syslog }}
+{% endfor %}
+```
+
+The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.)
+
+A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`.
+
 
 ## REST API Integration
 

docs/development/models.md

@@ -8,12 +8,12 @@ The Django [content types](https://docs.djangoproject.com/en/stable/ref/contrib/
 
 ### Features Matrix
 
-* [Change logging](../additional-features/change-logging.md) - Changes to these objects are automatically recorded in the change log
-* [Webhooks](../additional-features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects
+* [Change logging](../features/change-logging.md) - Changes to these objects are automatically recorded in the change log
+* [Webhooks](../features/webhooks.md) - NetBox is capable of generating outgoing webhooks for these objects
 * [Custom fields](../customization/custom-fields.md) - These models support the addition of user-defined fields
 * [Export templates](../customization/export-templates.md) - Users can create custom export templates for these models
-* [Tagging](../models/extras/tag.md) - The models can be tagged with user-defined tags
-* [Journaling](../additional-features/journaling.md) - These models support persistent historical commentary
+* [Tagging](../features/tags.md) - The models can be tagged with user-defined tags
+* [Journaling](../features/journaling.md) - These models support persistent historical commentary
 * Nesting - These models can be nested recursively to create a hierarchy
 
 | Type               | Change Logging   | Webhooks         | Custom Fields    | Export Templates | Tags             | Journaling       | Nesting          |

docs/features/circuits.md

@@ -0,0 +1,3 @@
+# Circuits
+
+TODO

docs/features/contacts.md

@@ -0,0 +1,3 @@
+# Contacts
+
+TODO

docs/features/customization.md

@@ -0,0 +1,3 @@
+# Customization
+
+TODO

docs/features/devices-cabling.md

@@ -0,0 +1,3 @@
+# Devices & Cabling
+
+TODO

docs/features/facilities.md

@@ -0,0 +1,3 @@
+# Facilities
+
+TODO

docs/features/ipam.md

@@ -0,0 +1,3 @@
+# IP Address Management
+
+TODO

docs/features/l2vpn-overlay.md

@@ -0,0 +1,3 @@
+# L2VPN & Overlay
+
+TODO

docs/features/permissions.md

@@ -0,0 +1,3 @@
+# Object-Based Permissions
+
+TODO

docs/features/power-tracking.md

@@ -0,0 +1,3 @@
+# Power Tracking
+
+TODO

docs/features/services.md

@@ -0,0 +1,3 @@
+# Services
+
+TODO

docs/features/sso.md

@@ -0,0 +1,3 @@
+# Single Sign-On (SSO)
+
+TODO

docs/features/tenancy.md

@@ -0,0 +1,3 @@
+# Tenancy
+
+TODO

docs/features/vlan-management.md

@@ -0,0 +1,3 @@
+# VLAN Management
+
+TODO

docs/models/extras/webhook.md → docs/features/webhooks.md

@@ -81,3 +81,59 @@ If no body template is specified, the request body will be populated with a JSON
     }
 }
 ```
+
+## Conditional Webhooks
+
+A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active":
+
+```json
+{
+  "and": [
+    {
+      "attr": "status.value",
+      "value": "active"
+    }
+  ]
+}
+```
+
+For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).
+
+## Webhook Processing
+
+When a change is detected, any resulting webhooks are placed into a Redis queue for processing. This allows the user's request to complete without needing to wait for the outgoing webhook(s) to be processed. The webhooks are then extracted from the queue by the `rqworker` process and HTTP requests are sent to their respective destinations. The current webhook queue and any failed webhooks can be inspected in the admin UI under System > Background Tasks.
+
+A request is considered successful if the response has a 2XX status code; otherwise, the request is marked as having failed. Failed requests may be retried manually via the admin UI.
+
+## Troubleshooting
+
+To assist with verifying that the content of outgoing webhooks is rendered correctly, NetBox provides a simple HTTP listener that can be run locally to receive and display webhook requests. First, modify the target URL of the desired webhook to `http://localhost:9000/`. This will instruct NetBox to send the request to the local server on TCP port 9000. Then, start the webhook receiver service from the NetBox root directory:
+
+```no-highlight
+$ python netbox/manage.py webhook_receiver
+Listening on port http://localhost:9000. Stop with CONTROL-C.
+```
+
+You can test the receiver itself by sending any HTTP request to it. For example:
+
+```no-highlight
+$ curl -X POST http://localhost:9000 --data '{"foo": "bar"}'
+```
+
+The server will print output similar to the following:
+
+```no-highlight
+[1] Tue, 07 Apr 2020 17:44:02 GMT 127.0.0.1 "POST / HTTP/1.1" 200 -
+Host: localhost:9000
+User-Agent: curl/7.58.0
+Accept: */*
+Content-Length: 14
+Content-Type: application/x-www-form-urlencoded
+
+{"foo": "bar"}
+------------
+```
+
+Note that `webhook_receiver` does not actually _do_ anything with the information received: It merely prints the request headers and body for inspection.
+
+Now, when the NetBox webhook is triggered and processed, you should see its headers and content appear in the terminal where the webhook receiver is listening. If you don't, check that the `rqworker` process is running and that webhook events are being placed into the queue (visible under the NetBox admin UI).

docs/features/wireless.md

@@ -0,0 +1,3 @@
+# Wireless
+
+TODO

docs/getting-started/populating-data.md

@@ -39,4 +39,4 @@ Sometimes you'll find that data you need to populate in NetBox can be easily red
 
 You can also use the REST API to facilitate the population of data in NetBox. The REST API offers full programmatic control over the creation of objects, subject to the same validation rules enforced by the UI forms. Additionally, the REST API supports the bulk creation of multiple objects using a single request.
 
-For more information about this option, see the [REST API documentation](../rest-api/overview.md).
+For more information about this option, see the [REST API documentation](../integrations/rest-api.md).

docs/installation/3-netbox.md

@@ -201,7 +201,7 @@ All Python packages required by NetBox are listed in `requirements.txt` and will
 
 ### NAPALM
 
-Integration with the [NAPALM automation](../additional-features/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device.
+Integration with the [NAPALM automation](../integrations/napalm.md) library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The `NAPALM_USERNAME` and `NAPALM_PASSWORD` configuration parameters define the credentials to be used when connecting to a device.
 
 ```no-highlight
 sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt"

docs/rest-api/overview.md → docs/integrations/rest-api.md

@@ -91,7 +91,7 @@ Lists of objects can be filtered using a set of query parameters. For example, t
 GET /api/dcim/interfaces/?device_id=123
 ```
 
-See the [filtering documentation](filtering.md) for more details.
+See the [filtering documentation](../reference/filtering.md) for more details.
 
 ## Serialization
 
@@ -269,7 +269,7 @@ The brief format is supported for both lists and individual objects.
 
 ### Excluding Config Contexts
 
-When retrieving devices and virtual machines via the REST API, each will included its rendered [configuration context data](../models/extras/configcontext.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views.
+When retrieving devices and virtual machines via the REST API, each will include its rendered [configuration context data](../features/context-data.md) by default. Users with large amounts of context data will likely observe suboptimal performance when returning multiple objects, particularly with very high page sizes. To combat this, context data may be excluded from the response data by attaching the query parameter `?exclude=config_context` to the request. This parameter works for both list and detail views.
 
 ## Pagination
 
@@ -387,7 +387,7 @@ curl -s -X GET http://netbox/api/ipam/ip-addresses/5618/ | jq '.'
 
 ### Creating a New Object
 
-To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication documentation](authentication.md) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`.
+To create a new object, make a `POST` request to the model's _list_ endpoint with JSON data pertaining to the object being created. Note that a REST API token is required for all write operations; see the [authentication section](#authenticating-to-the-api) for more information. Also be sure to set the `Content-Type` HTTP header to `application/json`.
 
 ```no-highlight
 curl -s -X POST \
@@ -561,3 +561,96 @@ http://netbox/api/dcim/sites/ \
 
 !!! note
     The bulk deletion of objects is an all-or-none operation, meaning that if NetBox fails to delete any of the specified objects (e.g. due a dependency by a related object), the entire operation will be aborted and none of the objects will be deleted.
+
+## Authentication
+
+The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API.
+
+### Tokens
+
+A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile.
+
+!!! note
+    All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts.
+
+Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation.
+
+By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only.
+
+Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox.
+
+#### Client IP Restriction
+
+!!! note
+    This feature was introduced in NetBox v3.3.
+
+Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.)
+
+
+### Authenticating to the API
+
+An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token:
+
+```
+$ curl -H "Authorization: Token $TOKEN" \
+-H "Accept: application/json; indent=4" \
+https://netbox/api/dcim/sites/
+{
+    "count": 10,
+    "next": null,
+    "previous": null,
+    "results": [...]
+}
+```
+
+A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response:
+
+```
+$ curl https://netbox/api/dcim/sites/
+{
+    "detail": "Authentication credentials were not provided."
+}
+```
+
+When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently.
+
+!!! note
+    The "last used" time for tokens will not be updated while maintenance mode is enabled.
+
+### Initial Token Provisioning
+
+Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination.
+
+To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint:
+
+```
+$ curl -X POST \
+-H "Content-Type: application/json" \
+-H "Accept: application/json; indent=4" \
+https://netbox/api/users/tokens/provision/ \
+--data '{
+    "username": "hankhill",
+    "password": "I<3C3H8",
+}'
+```
+
+Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled.
+
+```json
+{
+    "id": 6,
+    "url": "https://netbox/api/users/tokens/6/",
+    "display": "3c9cb9 (hankhill)",
+    "user": {
+        "id": 2,
+        "url": "https://netbox/api/users/users/2/",
+        "display": "hankhill",
+        "username": "hankhill"
+    },
+    "created": "2021-06-11T20:09:13.339367Z",
+    "expires": null,
+    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
+    "write_enabled": true,
+    "description": ""
+}
+```

docs/models/extras/customfield.md

@@ -1,73 +0,0 @@
-# Custom Fields
-
-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 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.
-
-Within the database, custom fields are stored as JSON data directly alongside each object. This alleviates the need for complex queries when retrieving objects.
-
-## Creating Custom Fields
-
-Custom fields may be created by navigating to Customization > Custom Fields. NetBox supports six types of custom field:
-
-* Text: Free-form text (intended for single-line use)
-* Long text: Free-form of any length; supports Markdown rendering
-* 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
-* JSON: Arbitrary data stored in JSON format
-* Selection: A selection of one of several pre-defined custom choices
-* Multiple selection: A selection field which supports the assignment of multiple values
-* Object: A single NetBox object of the type defined by `object_type`
-* Multiple object: One or more NetBox objects of the type defined by `object_type`
-
-Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. 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.
-
-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.
-
-A custom field must be assigned to one or more 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.
-
-### Filtering
-
-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.
-
-### Grouping
-
-!!! note
-    This feature was introduced in NetBox v3.3.
-
-Related custom fields can be grouped together within the UI by assigning each the same group name. When at least one custom field for an object type has a group defined, it will appear under the group heading within the custom fields panel under the object view. All custom fields with the same group name will appear under that heading. (Note that the group names must match exactly, or each will appear as a separate heading.)
-
-This parameter has no effect on the API representation of custom field data.
-
-### Visibility
-
-!!! note
-    This feature was introduced in NetBox v3.3.
-
-When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI.
-
-* **Read/write** (default): The custom field is included when viewing and editing objects.
-* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.)
-* **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users.
-
-Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API.
-
-### 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. The value of a multiple selection field will always return a list, even if only one value is selected.
-
-### Custom Object Fields
-
-An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point.

docs/models/extras/exporttemplate.md

@@ -1,37 +0,0 @@
-# Export Templates
-
-NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.
-
-Each export template is associated with a certain type of object. For instance, if you create an export template for VLANs, your custom template will appear under the "Export" button on the VLANs list. Each export template must have a name, and may optionally designate a specific export [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) and/or file extension.
-
-Export templates must be written in [Jinja2](https://jinja.palletsprojects.com/).
-
-!!! note
-    The name `table` is reserved for internal use.
-
-!!! warning
-    Export templates are rendered using user-submitted code, which may pose security risks under certain conditions. Only grant permission to create or modify export templates to trusted users.
-
-The list of objects returned from the database when rendering an export template is stored in the `queryset` variable, which you'll typically want to iterate through using a `for` loop. Object properties can be access by name. For example:
-
-```jinja2
-{% for rack in queryset %}
-Rack: {{ rack.name }}
-Site: {{ rack.site.name }}
-Height: {{ rack.u_height }}U
-{% endfor %}
-```
-
-To access custom fields of an object within a template, use the `cf` attribute. For example, `{{ obj.cf.color }}` will return the value (if any) for a custom field named `color` on `obj`.
-
-If you need to use the config context data in an export template, you'll should use the function `get_config_context` to get all the config context data. For example:
-```
-{% for server in queryset %}
-{% set data = server.get_config_context() %}
-{{ data.syslog }}
-{% endfor %}
-```
-
-The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.)
-
-A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`.

docs/models/extras/imageattachment.md

@@ -1,3 +0,0 @@
-# Image Attachments
-
-Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed.

docs/models/users/objectpermission.md

@@ -1,69 +0,0 @@
-# Object Permissions
-
-A permission in NetBox represents a relationship shared by several components:
-
-* 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.

docs/models/users/token.md

@@ -1,19 +0,0 @@
-## Tokens
-
-A token is a unique identifier mapped to a NetBox user account. Each user may have one or more tokens which he or she can use for authentication when making REST API requests. To create a token, navigate to the API tokens page under your user profile.
-
-!!! note
-    All users can create and manage REST API tokens under the user control panel in the UI. The ability to view, add, change, or delete tokens via the REST API itself is controlled by the relevant model permissions, assigned to users and/or groups in the admin UI. These permissions should be used with great care to avoid accidentally permitting a user to create tokens for other user accounts.
-
-Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation.
-
-By default, a token can be used to perform all actions via the API that a user would be permitted to do via the web UI. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only.
-
-Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox.
-
-### Client IP Restriction
-
-!!! note
-    This feature was introduced in NetBox v3.3.
-
-Each API token can optionally be restricted by client IP address. If one or more allowed IP prefixes/addresses is defined for a token, authentication will fail for any client connecting from an IP address outside the defined range(s). This enables restricting the use a token to a specific client. (By default, any client IP address is permitted.)

docs/release-notes/version-3.0.md

@@ -357,7 +357,7 @@ And the response:
 ...
 ```
 
-All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../graphql-api/overview.md).
+All GraphQL requests are made at the `/graphql` URL (which also serves the GraphiQL UI). The API is currently read-only, however users who wish to disable it until needed can do so by setting the `GRAPHQL_ENABLED` configuration parameter to False. For more detail on NetBox's GraphQL implementation, see [the GraphQL API documentation](../integrations/graphql-api.md).
 
 #### IP Ranges ([#834](https://github.com/netbox-community/netbox/issues/834))
 

docs/rest-api/authentication.md

@@ -1,73 +0,0 @@
-# REST API Authentication
-
-The NetBox REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browsable API.
-
-{!models/users/token.md!}
-
-## Authenticating to the API
-
-An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token:
-
-```
-$ curl -H "Authorization: Token $TOKEN" \
--H "Accept: application/json; indent=4" \
-https://netbox/api/dcim/sites/
-{
-    "count": 10,
-    "next": null,
-    "previous": null,
-    "results": [...]
-}
-```
-
-A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../configuration/security.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response:
-
-```
-$ curl https://netbox/api/dcim/sites/
-{
-    "detail": "Authentication credentials were not provided."
-}
-```
-
-When a token is used to authenticate a request, its `last_updated` time updated to the current time if its last use was recorded more than 60 seconds ago (or was never recorded). This allows users to determine which tokens have been active recently.
-
-!!! note
-    The "last used" time for tokens will not be updated while maintenance mode is enabled.
-
-## Initial Token Provisioning
-
-Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. NetBox provides a special endpoint to provision tokens using a valid username and password combination.
-
-To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/provision/` endpoint:
-
-```
-$ curl -X POST \
--H "Content-Type: application/json" \
--H "Accept: application/json; indent=4" \
-https://netbox/api/users/tokens/provision/ \
---data '{
-    "username": "hankhill",
-    "password": "I<3C3H8",
-}'
-```
-
-Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled.
-
-```json
-{
-    "id": 6,
-    "url": "https://netbox/api/users/tokens/6/",
-    "display": "3c9cb9 (hankhill)",
-    "user": {
-        "id": 2,
-        "url": "https://netbox/api/users/users/2/",
-        "display": "hankhill",
-        "username": "hankhill"
-    },
-    "created": "2021-06-11T20:09:13.339367Z",
-    "expires": null,
-    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
-    "write_enabled": true,
-    "description": ""
-}
-```

mkdocs.yml

@@ -62,6 +62,26 @@ markdown_extensions:
         alternate_style: true
 nav:
     - Introduction: 'introduction.md'
+    - Features:
+        - Facilities: 'features/facilities.md'
+        - Tenancy: 'features/tenancy.md'
+        - Contacts: 'features/contacts.md'
+        - Devices & Cabling: 'features/devices-cabling.md'
+        - Power Tracking: 'features/power-tracking.md'
+        - IPAM: 'features/ipam.md'
+        - VLAN Management: 'features/vlan-management.md'
+        - Service Mapping: 'features/services.md'
+        - L2VPN & Overlay: 'features/l2vpn-overlay.md'
+        - Circuits: 'features/circuits.md'
+        - Wireless: 'features/wireless.md'
+        - Context Data: 'features/context-data.md'
+        - Change Logging: 'features/change-logging.md'
+        - Journaling: 'features/journaling.md'
+        - Webhooks: 'features/webhooks.md'
+        - Tags: 'features/tags.md'
+        - Customization: 'features/customization.md'
+        - Object-Based Permissions: 'features/permissions.md'
+        - Single Sign-On (SSO): 'features/sso.md'
     - Installation & Upgrade:
         - Installing NetBox: 'installation/index.md'
         - 1. PostgreSQL: 'installation/1-postgresql.md'
@@ -90,19 +110,16 @@ nav:
         - Development: 'configuration/development.md'
     - Customization:
         - Custom Fields: 'customization/custom-fields.md'
+        - Custom Links: 'customization/custom-links.md'
         - Custom Validation: 'customization/custom-validation.md'
-        - Custom Links: 'models/extras/customlink.md'
         - Export Templates: 'customization/export-templates.md'
-        - Custom Scripts: 'customization/custom-scripts.md'
         - Reports: 'customization/reports.md'
-    - Additional Features:
-        - Change Logging: 'additional-features/change-logging.md'
-        - Context Data: 'models/extras/configcontext.md'
-        - Journaling: 'additional-features/journaling.md'
-        - NAPALM: 'additional-features/napalm.md'
-        - Prometheus Metrics: 'additional-features/prometheus-metrics.md'
-        - Tags: 'models/extras/tag.md'
-        - Webhooks: 'additional-features/webhooks.md'
+        - Custom Scripts: 'customization/custom-scripts.md'
+    - Integrations:
+        - REST API: 'integrations/rest-api.md'
+        - GraphQL API: 'integrations/graphql-api.md'
+        - NAPALM: 'integrations/napalm.md'
+        - Prometheus Metrics: 'integrations/prometheus-metrics.md'
     - Plugins:
         - Using Plugins: 'plugins/index.md'
         - Developing Plugins:
@@ -128,12 +145,6 @@ nav:
         - Housekeeping: 'administration/housekeeping.md'
         - Replicating NetBox: 'administration/replicating-netbox.md'
         - NetBox Shell: 'administration/netbox-shell.md'
-    - REST API:
-        - Overview: 'rest-api/overview.md'
-        - Filtering & Ordering: 'rest-api/filtering.md'
-        - Authentication: 'rest-api/authentication.md'
-    - GraphQL API:
-        - Overview: 'graphql-api/overview.md'
     - Data Model:
         - Circuits:
             - Circuit: 'models/circuits/circuit.md'
@@ -143,8 +154,6 @@ nav:
             - Provider Network: 'models/circuits/providernetwork.md'
         - DCIM:
             - Cable: 'models/dcim/cable.md'
-            - CablePath: 'models/dcim/cablepath.md'
-            - CableTermination: 'models/dcim/cabletermination.md'
             - ConsolePort: 'models/dcim/consoleport.md'
             - ConsolePortTemplate: 'models/dcim/consoleporttemplate.md'
             - ConsoleServerPort: 'models/dcim/consoleserverport.md'
@@ -203,7 +212,6 @@ nav:
             - VRF: 'models/ipam/vrf.md'
         - Tenancy:
             - Contact: 'models/tenancy/contact.md'
-            - ContactAssignment: 'models/tenancy/contactassignment.md'
             - ContactGroup: 'models/tenancy/contactgroup.md'
             - ContactRole: 'models/tenancy/contactrole.md'
             - Tenant: 'models/tenancy/tenant.md'
@@ -219,6 +227,7 @@ nav:
             - WirelessLANGroup: 'models/wireless/wirelesslangroup.md'
             - WirelessLink: 'models/wireless/wirelesslink.md'
     - Reference:
+        - Filtering: 'reference/filtering.md'
         - Conditions: 'reference/conditions.md'
         - Markdown: 'reference/markdown.md'
     - Development: