mirror/netbox-community-netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2024-05-10 07:54:54 +00:00
Code Activity

Refreshed extras model documentation

Browse Source
This commit is contained in:
jeremystretch
2022-08-12 16:00:04 -04:00
parent fafc464d93
commit cff6b81f1f
9 changed files with 184 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/models/extras/configcontext.md
View File

@ -1,69 +1,27 @@
# 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:
Context data is made available to [devices](../dcim/device.md) and/or [virtual machines](../virtualization/virtualmachine.md) based on their relationships to other objects in NetBox. For example, context data can be associated only with devices assigned to a particular site, or only to virtual machines in a certain cluster.
* 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
See the [context data documentation](../../features/context-data.md) for more information.
## Hierarchical Rendering
## Fields
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.
### Name
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:
A unique human-friendly name.
```json
{
"ntp-servers": [
"172.16.10.22",
"172.16.10.33"
],
"syslog-servers": [
"172.16.9.100",
"172.16.9.101"
]
}
```
### Weight
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:
A numeric value which influences the order in which context data is merged. Contexts with a lower weight are merged before those with a higher weight.
```json
{
"syslog-servers": [
"192.168.43.107"
]
}
```
### Data
When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
The context data expressed in JSON format.
```json
{
"ntp-servers": [
"172.16.10.22",
"172.16.10.33"
],
"syslog-servers": [
"192.168.43.107"
]
}
```
### Is Active
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.
If not selected, this config context will be excluded from rendering. This can be convenient to temporarily disable a config context.
## Local Context Data
### Object Assignment
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.
Each configuration context may be assigned with any number of objects of the supported types. If no related objects are selected, it will be considered a "global" config context and apply to all devices and virtual machines.

2
docs/models/extras/customfield.md
View File

@ -1,5 +1,7 @@
# Custom Fields
NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the [custom fields documentation](../../customization/custom-fields.md) for more information.
## Fields
### Model(s)

2
docs/models/extras/customlink.md
View File

@ -1,5 +1,7 @@
# Custom Links
Users can add custom links to object views in NetBox to reference external resources. For example, you might create a custom link for devices pointing to a monitoring system. See the [custom links documentation](../../customization/custom-links.md) for more information.
## Fields
### Name

2
docs/models/extras/exporttemplate.md
View File

@ -1,5 +1,7 @@
# Export Templates
Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the [export templates documentation](../../customization/export-templates.md) for more information.
## Fields
### Name

10
docs/models/extras/imageattachment.md
View File

@ -1,3 +1,13 @@
# 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.
## Fields
### Name
The name of the image being attached. If not defined, this will be inferred from the name of the uploaded file.
### Image
The image file to upload. Note that the uploaded file **must** be a supported image type, or validation will fail.

18
docs/models/extras/tag.md
View File

@ -2,16 +2,16 @@
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.
## Fields
Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
### Name
```no-highlight
GET /api/dcim/devices/?tag=monitored
```
A unique human-friendly label for the tag.
The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned:
### Slug
```no-highlight
GET /api/dcim/devices/?tag=monitored&tag=deprecated
```
A unique URL-friendly identifier. (This value will be used for filtering.) This is automatically generated from the tag's name, but can be altered as needed.
### Color
The color to use when displaying the tag in the NetBox UI.

95
docs/models/extras/webhook.md
View File

@ -1,19 +1,84 @@
# 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.
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.
## Model Fields
See the [webhooks documentation](../../integrations/webhooks.md) for more information.
* **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).
## Fields
### Name
A unique human-friendly name.
### Content Types
The type(s) of object in NetBox that will trigger the webhook.
### Enabled
If not selected, the webhook will be inactive.
### Events
The events which will trigger the webhook. At least one event type must be selected.
| Name | Description |
|-----------|--------------------------------------|
| Creations | A new object has been created |
| Updates | An existing object has been modified |
| Deletions | An object has been deleted |
### URL
The URL to which the webhook HTTP request will be made.
### HTTP Method
The type of HTTP request to send. Options are:
* `GET`
* `POST`
* `PUT`
* `PATCH`
* `DELETE`
### HTTP Content Type
The content type to indicate in the outgoing HTTP request header. See [this list](https://www.iana.org/assignments/media-types/media-types.xhtml) of known types for reference.
### Additional Headers
Any additional header to include with the outgoing HTTP request. These should be defined in the format `Name: Value`, with each header on a separate line. Jinja2 templating is supported for this field.
### Body Template
Jinja2 template for a custom request body, if desired. If not defined, NetBox will populate the request body with a raw dump of the webhook context.
### 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.
### SSL Verification
Controls whether validation of the receiver's SSL certificate is enforced when HTTPS is used.
!!! warning
Disabling this can expose your webhooks to man-in-the-middle attacks.
### CA File Path
The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (if not using the system defaults).
## Context Data
The following context variables are available in to the text and link templates.
| Variable | Description |
|--------------|----------------------------------------------------|
| `event` | The event type (`create`, `update`, or `delete`) |
| `timestamp` | The time at which the event occured |
| `model` | The type of object impacted |
| `username` | The name of the user associated with the change |
| `request_id` | The unique request ID |
| `data` | A complete serialized representation of the object |
| `snapshots` | Pre- and post-change snapshots of the object |