mirror of
https://github.com/netbox-community/netbox.git
synced 2025-12-12 19:39:35 -06:00
5bbab7eb47
Some checks failed
CI / build (20.x, 3.12) (push) Has been cancelled
CI / build (20.x, 3.13) (push) Has been cancelled
CodeQL / Analyze (${{ matrix.language }}) (none, actions) (push) Has been cancelled
CodeQL / Analyze (${{ matrix.language }}) (none, javascript-typescript) (push) Has been cancelled
CodeQL / Analyze (${{ matrix.language }}) (none, python) (push) Has been cancelled
* Closes #16681: Introduce render_config permission for configuration rendering Add a new custom permission action `render_config` for rendering device and virtual machine configurations via the REST API. This allows users to render configurations without requiring the `add` permission. Changes: - Add permission check to RenderConfigMixin.render_config() for devices and VMs - Update API tests to use render_config permission instead of add - Add tests verifying permission enforcement (403 without render_config) - Document new permission requirement in configuration-rendering.md Note: Currently requires both render_config AND add permissions due to the automatic POST='add' filter in BaseViewSet.initial(). Removing the add requirement will be addressed in a follow-up commit. * Correct permission denied message and enable translation * Remove add permission requirement for render_config endpoint Remove the add permission requirement from the render-config API endpoint while maintaining token write_enabled enforcement as specified in #16681. Changes: - Add TokenWritePermission class to check token write ability without requiring specific model permissions - Override get_permissions() in RenderConfigMixin to use TokenWritePermission instead of TokenPermissions for render_config action - Replace queryset restriction: use render_config instead of add - Remove add permissions from tests - render_config permission now sufficient - Update tests to expect 404 when permission denied (NetBox standard pattern) Per #16681: 'requirement for write permission makes sense for API calls (because we're accepting and processing arbitrary user data), the specific permission for creating devices does not' * Add render_config permission to ConfigTemplate render endpoint Extend render_config permission requirement to the ConfigTemplate render endpoint per issue comments. Changes: - Add TokenWritePermission check via get_permissions() override in ConfigTemplateViewSet - Restrict queryset to render_config permission in render() method - Add explicit render_config permission check - Add tests for ConfigTemplate.render() with and without permission - Update documentation to include ConfigTemplate endpoint * Address PR feedback on render_config permissions Remove redundant permission checks, add view permission enforcement via chained restrict() calls, and rename ConfigTemplate permission action from render_config to render for consistency. * Address second round of PR feedback on render_config permissions - Remove ConfigTemplate view permission check from render_config endpoint - Add sanity check to TokenWritePermission for non-token auth - Use named URL patterns instead of string concatenation in tests - Remove extras.view_configtemplate from test permissions - Add token write_enabled enforcement tests for all render endpoints * Misc cleanup --------- Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
100 lines
4.2 KiB
Markdown
100 lines
4.2 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`
|
|
|
|
### 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.
|