mirror of
https://github.com/netbox-community/netbox.git
synced 2026-04-26 18:58:54 +02:00
133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# Configuration Rendering
|
|
|
|
One of the critical aspects of operating a network is ensuring that every network node is configured correctly. By leveraging configuration templates and [context data](./context-data.md), NetBox can render complete configuration files for each device on your network.
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
ConfigContext & ConfigTemplate --> Config{{Rendered configuration}}
|
|
|
|
click ConfigContext "../../models/extras/configcontext/"
|
|
click ConfigTemplate "../../models/extras/configtemplate/"
|
|
```
|
|
|
|
## Configuration Templates
|
|
|
|
Configuration templates are written in the [Jinja2 templating language](https://jinja.palletsprojects.com/), and may be automatically populated from remote data sources. Context data is applied to a template during rendering to output a complete configuration file. Below is an example Jinja2 template which renders a simple network switch configuration file.
|
|
|
|
```jinja2
|
|
{% extends 'base.j2' %}
|
|
|
|
{% block content %}
|
|
system {
|
|
host-name {{ device.name }};
|
|
domain-name example.com;
|
|
time-zone UTC;
|
|
authentication-order [ password radius ];
|
|
ntp {
|
|
{% for server in ntp_servers %}
|
|
server {{ server }};
|
|
{% endfor %}
|
|
}
|
|
}
|
|
{% for interface in device.interfaces.all() %}
|
|
{% include 'common/interface.j2' %}
|
|
{% endfor %}
|
|
{% endblock %}
|
|
```
|
|
|
|
When rendered for a specific NetBox device, the template's `device` variable will be populated with the device instance, and `ntp_servers` will be pulled from the device's available context data. The resulting output will be a valid configuration segment that can be applied directly to a compatible network device.
|
|
|
|
### Context Data
|
|
|
|
The object for which the configuration is being rendered is made available as template context as `device` or `virtualmachine` for devices and virtual machines, respectively. Additionally, NetBox model classes can be accessed by the app or plugin in which they reside. For example:
|
|
|
|
```
|
|
There are {{ dcim.Site.objects.count() }} sites.
|
|
```
|
|
|
|
## Rendering Templates
|
|
|
|
### Device Configurations
|
|
|
|
NetBox provides a REST API endpoint specifically for rendering the default configuration template for a specific device. This is accomplished by sending a POST request to the device's unique URL, optionally including additional context data.
|
|
|
|
```no-highlight
|
|
curl -X POST \
|
|
-H "Authorization: Token $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json; indent=4" \
|
|
http://netbox:8000/api/dcim/devices/123/render-config/ \
|
|
--data '{
|
|
"extra_data": "abc123"
|
|
}'
|
|
```
|
|
|
|
This request will trigger resolution of the device's preferred config template in the following order:
|
|
|
|
* The config template assigned to the individual device
|
|
* The config template assigned to the device's role
|
|
* The config template assigned to the device's platform
|
|
|
|
If no config template has been assigned to any of these three objects, the request will fail.
|
|
|
|
The configuration can be rendered as JSON or as plaintext by setting the `Accept:` HTTP header. For example:
|
|
|
|
* `Accept: application/json`
|
|
* `Accept: text/plain`
|
|
|
|
### Overriding the Config Template
|
|
|
|
To render a specific config template against a device's context data - rather than the template resolved via the fallback chain above — include `config_template_id` in the request body:
|
|
|
|
```no-highlight
|
|
curl -X POST \
|
|
-H "Authorization: Token $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json; indent=4" \
|
|
http://netbox:8000/api/dcim/devices/123/render-config/ \
|
|
--data '{
|
|
"config_template_id": 42
|
|
}'
|
|
```
|
|
|
|
This is useful for rendering partial or alternative templates against a device's assembled context without changing any stored assignments. Any additional keys in the request body are passed into the template as context variables alongside the device's own config context data, as with standard rendering:
|
|
|
|
```no-highlight
|
|
--data '{
|
|
"config_template_id": 42,
|
|
"environment": "staging"
|
|
}'
|
|
```
|
|
|
|
!!! note "Permissions"
|
|
Overriding the config template requires the requesting user to have `view` permission for the "Extras > Config Template" object type in addition to the `render_config` permission on the device.
|
|
|
|
The same override is available in the UI by appending `config_template_id` as a query parameter to the device's render config URL:
|
|
|
|
```no-highlight
|
|
/dcim/devices/123/render-config/?config_template_id=42
|
|
```
|
|
|
|
### General Purpose Use
|
|
|
|
NetBox config templates can also be rendered without being tied to any specific device, using a separate general purpose REST API endpoint. Any data included with a POST request to this endpoint will be passed as context data for the template.
|
|
|
|
```no-highlight
|
|
curl -X POST \
|
|
-H "Authorization: Token $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-H "Accept: application/json; indent=4" \
|
|
http://netbox:8000/api/extras/config-templates/123/render/ \
|
|
--data '{
|
|
"foo": "abc",
|
|
"bar": 123
|
|
}'
|
|
```
|
|
|
|
!!! note "Permissions"
|
|
Rendering configuration templates via the REST API requires appropriate permissions for the relevant object type:
|
|
|
|
* To render a device's configuration via `/api/dcim/devices/{id}/render-config/`, assign a permission for "DCIM > Device" with the `render_config` action.
|
|
* To render a virtual machine's configuration via `/api/virtualization/virtual-machines/{id}/render-config/`, assign a permission for "Virtualization > Virtual Machine" with the `render_config` action.
|
|
* To render a config template directly via `/api/extras/config-templates/{id}/render/`, assign a permission for "Extras > Config Template" with the `render` action.
|