netbox/docs/features/configuration-rendering.md

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, NetBox can render complete configuration files for each device on your network.

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, 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.

{% 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.

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

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.

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.