Reorganize documentation

docs/features/change-logging.md

@@ -0,0 +1,9 @@
+# Change Logging
+
+Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object taken both before and after the change is saved to the database, along with meta data including the current time and the user associated with the change. These records form a persistent record of changes both for each individual object as well as NetBox as a whole. The global change log can be viewed by navigating to Other > Change Log.
+
+A serialized representation of the instance being modified is included in JSON format. This is similar to how objects are conveyed within the REST API, but does not include any nested representations. For instance, the `tenant` field of a site will record only the tenant's ID, not a representation of the tenant.
+
+When a request is made, a UUID is generated and attached to any change records resulting from that request. For example, editing three objects in bulk will create a separate change record for each  (three in total), and each of those objects will be associated with the same UUID. This makes it easy to identify all the change records resulting from a particular request.
+
+Change records are exposed in the API via the read-only endpoint `/api/extras/object-changes/`. They may also be exported via the web UI in CSV format.

docs/features/circuits.md

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

docs/features/contacts.md

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

docs/features/context-data.md

@@ -0,0 +1,69 @@
+# Configuration Contexts
+
+Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments:
+
+* Region
+* Site group
+* Site
+* Location (devices only)
+* Device type (devices only)
+* Role
+* Platform
+* Cluster type (VMs only)
+* Cluster group (VMs only)
+* Cluster (VMs only)
+* Tenant group
+* Tenant
+* Tag
+
+## Hierarchical Rendering
+
+Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.
+
+For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "172.16.9.100",
+        "172.16.9.101"
+    ]
+}
+```
+
+But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:
+
+```json
+{
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.
+
+## Local Context Data
+
+Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.
+
+!!! warning
+    If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution.

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/journaling.md

@@ -0,0 +1,5 @@
+# Journaling
+
+All primary objects in NetBox support journaling. A journal is a collection of human-generated notes and comments about an object maintained for historical context. It supplements NetBox's change log to provide additional information about why changes have been made or to convey events which occur outside NetBox. Unlike the change log, in which records typically expire after a configurable period of time, journal entries persist for the life of their associated object.
+
+Each journal entry has a selectable kind (info, success, warning, or danger) and a user-populated `comments` field. Each entry automatically records the date, time, and associated user upon being created.

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/tags.md

@@ -0,0 +1,17 @@
+# Tags
+
+Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects.
+
+Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose.
+
+Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored
+```
+
+The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned:
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored&tag=deprecated
+```

docs/features/tenancy.md

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

docs/features/vlan-management.md

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

docs/features/webhooks.md

@@ -0,0 +1,139 @@
+# 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 URL, custom headers and payloads, which may pose security risks under certain conditions. Only grant permission to create or modify webhooks to trusted users.
+
+## Configuration
+
+* **Name** - A unique name for the webhook. The name is not included with outbound messages.
+* **Object type(s)** - The type or types of NetBox object that will trigger the webhook.
+* **Enabled** - If unchecked, the webhook will be inactive.
+* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected.
+* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field.
+* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`)
+* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below).
+* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.)
+* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
+* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object.
+* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!)
+* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional).
+
+## Jinja2 Template Support
+
+[Jinja2 templating](https://jinja.palletsprojects.com/) is supported for the `URL`, `additional_headers` and `body_template` fields. This enables the user to convey object data in the request headers as well as to craft a customized request body. Request content can be crafted to enable the direct interaction with external systems by ensuring the outgoing message is in a format the receiver expects and understands.
+
+For example, you might create a NetBox webhook to [trigger a Slack message](https://api.slack.com/messaging/webhooks) any time an IP address is created. You can accomplish this using the following configuration:
+
+* Object type: IPAM > IP address
+* HTTP method: `POST`
+* URL: Slack incoming webhook URL
+* HTTP content type: `application/json`
+* Body template: `{"text": "IP address {{ data['address'] }} was created by {{ username }}!"}`
+
+### Available Context
+
+The following data is available as context for Jinja2 templates:
+
+* `event` - The type of event which triggered the webhook: created, updated, or deleted.
+* `model` - The NetBox model which triggered the change.
+* `timestamp` - The time at which the event occurred (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
+* `username` - The name of the user account associated with the change.
+* `request_id` - The unique request ID. This may be used to correlate multiple changes associated with a single request.
+* `data` - A detailed representation of the object in its current state. This is typically equivalent to the model's representation in NetBox's REST API.
+* `snapshots` - Minimal "snapshots" of the object state both before and after the change was made; provided as a dictionary with keys named `prechange` and `postchange`. These are not as extensive as the fully serialized representation, but contain enough information to convey what has changed.
+
+### Default Request Body
+
+If no body template is specified, the request body will be populated with a JSON object containing the context data. For example, a newly created site might appear as follows:
+
+```json
+{
+    "event": "created",
+    "timestamp": "2021-03-09 17:55:33.968016+00:00",
+    "model": "site",
+    "username": "jstretch",
+    "request_id": "fdbca812-3142-4783-b364-2e2bd5c16c6a",
+    "data": {
+        "id": 19,
+        "name": "Site 1",
+        "slug": "site-1",
+        "status": 
+            "value": "active",
+            "label": "Active",
+            "id": 1
+        },
+        "region": null,
+        ...
+    },
+    "snapshots": {
+        "prechange": null,
+        "postchange": {
+            "created": "2021-03-09",
+            "last_updated": "2021-03-09T17:55:33.851Z",
+            "name": "Site 1",
+            "slug": "site-1",
+            "status": "active",
+            ...
+        }
+    }
+}
+```
+
+## 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