DeviceRole field to CollectDiffScriptStatus field to CollectDiffScriptConfigDiffScript does not create empty changelog entriesIn navbar serach for Config Diff Plugin menu
Add PlatformSetting objects for your platforms in NetBox. This model contains info about how to connect and what to collect from device.
+Define:
+With regexps you can exclude big parts of the configuration and compare tiny configuration pieces (only ntp configuration).
+You can test regexp on the site regex101.com.
+
Plugin adds a custom script ConfigDiffScript that runs all logic about diff calculations and connections to devices.
+You can find scripts list in navbar Customization -> Scripts.
In the script, you can define a site or role, on which devices run compliance, or devices.
+ If you define all fields, script will run only on devices from Devices field
Warning
+Script runs only on devices with assigned Primary IP, Platform and PlatformSetting
+If you have configs in NetBox DataSource, you can define it, the script instead of connecting to devices will find configs in DataSource by device's names.
+Warning
+Be sure that DataSource is synced and has the latest data
+Note
+Only synced DataSources are acceptable
+If in your DataSource config names are different from the hostnames of the devices, you can specify config name with Jinja2 template in Name template field.
+ Reference device with {{ object }} variable.
For example, config name is virtual chassis name plus config (switchname-config) and your devices names are switchname1, switchname2 and etc.
You can define Jinja2 template with logic to use virtual chassis name if device is in chassis, else use device name:
+{% if object.virtual_chassis %}{{ object.virtual_chassis.name }}-config{% else %}{{ object.name }}{% endif %}
+
After script is done you can find results in Config Compliances menu. Each device has its own result.
Also result is storing rendered and actual configurations from devices.
+With the help of netutils library plugin stores missing and extra config lines.
+
Supported platforms for missing/extra lines:
+Compliance finished with error
+
Render diff between configurations
+
No diff
+
With plugin you can push rendered configuration from NetBox to devices.
+Supported platforms:
+arista_eoscisco_iosxecisco_iosxrcisco_nxosjuniper_junosPlugin using scrapli-cfg for this feature.
+Warning
+If you use Juniper and render config in set commands, please read next info.
+Plugin uses load override command to load config to a device, set commands load with load set.
+With load set commnad you can't replace all config, because this command uses merge action.
+So, please, be careful when using set commands in rendering config and pushig it with plugin, it can have unexpected side effects.
If you render not full configuration, it is acceptable to pull missing config sections from the actual configuration to render full configuration.
+Note
+If you render full configuration in NetBox, you can proceed to Configuration Request part
To do that you should create substitute.
+Substitutes is a "tag" that needs to be replaced with output from the real device, and a regex pattern that "pulls" this section from the actual device itself.
+
In screenshot below we add substitute for Arista PlatformSetting
+Name jinja2 variable in config templateIn example substitute ethernet_interfaces section will be replaced with whatever the provided pattern finds from the real device.
This pattern matches all ethernet interfaces on a Arista device.
+To correctly render substitute in config template you have two options:
+{{ "{{ ethernet_interfaces }}" }}
+or
+{% raw %}{{ ethernet_interfaces }}{% endraw %}
+Config template will look like:
+
And rendered config template with substitute
+
Now you let's create Configuration Request with devices you want to configure.
Warning
+For request only accepts devices with Active status and assigned Platform, Primary IP, and PlatformSetting
Find Configuration Requests in navbar.
Now collect diffs for devices pressing Collecting diffs button.
On tab Diffs you can review diffs for devices.
To continue approve request by pressing Approve button.
Also you can cancel approve after that.
+
After approval you can see by whom configuration request is approved.
+
At this moment you can schedule job that will push rendered configuration to devices in configuration request by pressing schedule button.
+
After that you can see by whom configuration request is scheduled and time.
+
Also you can cancel scheduled job by pressing Unschedule button.
Warning
+Approve and Schedule buttons is accessable only to user with netbox_config_diff.approve_configurationrequest
+permission
Warning
+If you unapprove scheduled configuration request, scheduled job will be canceled
+After scheduled job is completed you can job logs on configuration request page.
+
Note
+Completed configuration requests can't be edited.
+If an error occurs while executing a job that pushes configurations to devices then all configured devices will be rollbacked to the previous version of the configuration.
+ + + + + + +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given.
+You can contribute in many ways:
+Report bugs at https://github.com/miaow2/netbox-config-diff/issues.
+If you are reporting a bug, please include:
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help +wanted" is open to whoever wants to implement it.
+Look through the GitHub issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it.
+NetBox Config Diff Plugin could always use more documentation, whether as part of the +official NetBox Config Diff Plugin docs, in docstrings, or even on the web in blog posts, +articles, and such.
+The best way to send feedback is to file an issue at https://github.com/miaow2/netbox-config-diff/issues.
+If you are proposing a feature:
+Ready to contribute? Here's how to set up netbox-config-diff for local development.
netbox-config-diff repo on GitHub.Clone your fork locally
+$ git clone git@github.com:your_name_here/netbox-config-diff.git
Install dependencies and start your virtualenv:
+$ poetry install -E test -E doc -E dev
Create a branch for local development:
+$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
+When you're done making changes, check that your changes pass the + tests, including testing other Python versions, with tox:
+$ poetry run tox
Commit your changes and push your branch to GitHub:
+$ git add .
+$ git commit -m "Your detailed description of your changes."
+$ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
+Before you submit a pull request, check that it meets these guidelines:
+A reminder for the maintainers on how to deploy. +Make sure all your changes are committed (including an entry in CHANGELOG.md). +Then run:
+$ poetry run bump2version patch # possible: major / minor / patch
+$ git push
+$ git push --tags
+GitHub Actions will then deploy to PyPI if tests pass.
+ + + + + + +With this plugin you can find diff between the rendered configuration for a device to its actual configuration, retrieved from the device itself, or stored in DataSource. +Read about DataSources for further details.
+Device configuration renders natively in NetBox. This feature was introduced in 3.5 version. + NetBox Labs blog post about it.
+Plugin supports a wide list of vendors (Cisco, Juniper, Huawei, MicroTik etc.) with the help of Scrapli. Read Scrapli and scrapli-community documentations to find full list of vendors.
+Also you can push rendered configuration from NetBox to device and apply it.
+Supported platforms:
+arista_eoscisco_iosxecisco_iosxrcisco_nxosjuniper_junosThis is possible thanks to the scrapli_cfg. Read Scrapli documentation for more info.
+ + + + +For adding to a NetBox Docker setup see +the general instructions for using netbox-docker with plugins.
+Install with pip:
+pip install netbox-config-diff
+Add to local_requirements.txt:
echo netbox-config-diff >> local_requirements.txt
+Enable the plugin in /opt/netbox/netbox/netbox/configuration.py,
+ or if you use netbox-docker, your /configuration/plugins.py file,
+ and define credentials for devices connection:
PLUGINS = [
+ "netbox_config_diff",
+]
+
+PLUGINS_CONFIG = {
+ "netbox_config_diff": {
+ "USERNAME": "foo",
+ "PASSWORD": "bar",
+ "AUTH_SECONDARY": "foobar", # define here password for accessing Privileged EXEC mode, this variable is optional
+ },
+}
+Run database migrations:
+python manage.py migrate
+
+Collect static from the plugin:
+python manage.py collectstatic --noinput
+Restart NetBox service:
+systemctl restart netbox netbox-rq
+Read this doc about collecting diffs, for configuration management read this
+My presention about plugin at October NetBox community call (19.10.2023).
+
Also result is storing rendered and actual configurations from device.
+Compliance finished with error
+
Render diff between configurations
+
No diff
+
With this plugin you can find diff between the rendered configuration for a device to its actual configuration, retrieved from the device itself, or stored in DataSource. Read about DataSources for further details.
Device configuration renders natively in NetBox. This feature was introduced in 3.5 version. NetBox Labs blog post about it.
Plugin supports a wide list of vendors (Cisco, Juniper, Huawei, MicroTik etc.) with the help of Scrapli. Read Scrapli and scrapli-community documentations to find full list of vendors.
"},{"location":"#pushing-configuration","title":"Pushing configuration","text":"Also you can push rendered configuration from NetBox to device and apply it.
Supported platforms:
arista_eoscisco_iosxecisco_iosxrcisco_nxosjuniper_junosThis is possible thanks to the scrapli_cfg. Read Scrapli documentation for more info.
"},{"location":"#installing","title":"Installing","text":"For adding to a NetBox Docker setup see the general instructions for using netbox-docker with plugins.
Install with pip:
pip install netbox-config-diff\nAdd to local_requirements.txt:
echo netbox-config-diff >> local_requirements.txt\nEnable the plugin in /opt/netbox/netbox/netbox/configuration.py, or if you use netbox-docker, your /configuration/plugins.py file, and define credentials for devices connection:
PLUGINS = [\n \"netbox_config_diff\",\n]\n\nPLUGINS_CONFIG = {\n \"netbox_config_diff\": {\n \"USERNAME\": \"foo\",\n \"PASSWORD\": \"bar\",\n \"AUTH_SECONDARY\": \"foobar\", # define here password for accessing Privileged EXEC mode, this variable is optional\n },\n}\nRun database migrations:
python manage.py migrate\n\nCollect static from the plugin:
python manage.py collectstatic --noinput\nRestart NetBox service:
systemctl restart netbox netbox-rq\nRead this doc about collecting diffs, for configuration management read this
"},{"location":"#video","title":"Video","text":"My presention about plugin at October NetBox community call (19.10.2023).
"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#220-2024-02-06","title":"2.2.0 (2024-02-06)","text":"DeviceRole field to CollectDiffScriptStatus field to CollectDiffScriptConfigDiffScript does not create empty changelog entriesIn navbar serach for Config Diff Plugin menu
Add PlatformSetting objects for your platforms in NetBox. This model contains info about how to connect and what to collect from device.
Define:
With regexps you can exclude big parts of the configuration and compare tiny configuration pieces (only ntp configuration).
You can test regexp on the site regex101.com.
"},{"location":"colliecting-diffs/#script","title":"Script","text":"Plugin adds a custom script ConfigDiffScript that runs all logic about diff calculations and connections to devices. You can find scripts list in navbar Customization -> Scripts.
In the script, you can define a site or role, on which devices run compliance, or devices. If you define all fields, script will run only on devices from Devices field
Warning
Script runs only on devices with assigned Primary IP, Platform and PlatformSetting
If you have configs in NetBox DataSource, you can define it, the script instead of connecting to devices will find configs in DataSource by device's names.
Warning
Be sure that DataSource is synced and has the latest data
Note
Only synced DataSources are acceptable
If in your DataSource config names are different from the hostnames of the devices, you can specify config name with Jinja2 template in Name template field. Reference device with {{ object }} variable.
For example, config name is virtual chassis name plus config (switchname-config) and your devices names are switchname1, switchname2 and etc.
You can define Jinja2 template with logic to use virtual chassis name if device is in chassis, else use device name:
{% if object.virtual_chassis %}{{ object.virtual_chassis.name }}-config{% else %}{{ object.name }}{% endif %}\nAfter script is done you can find results in Config Compliances menu. Each device has its own result.
Also result is storing rendered and actual configurations from devices.
With the help of netutils library plugin stores missing and extra config lines.
Supported platforms for missing/extra lines:
Compliance finished with error
Render diff between configurations
No diff
"},{"location":"configuratiom-management/","title":"Usage","text":"With plugin you can push rendered configuration from NetBox to devices.
Supported platforms:
arista_eoscisco_iosxecisco_iosxrcisco_nxosjuniper_junosPlugin using scrapli-cfg for this feature.
Warning
If you use Juniper and render config in set commands, please read next info. Plugin uses load override command to load config to a device, set commands load with load set. With load set commnad you can't replace all config, because this command uses merge action. So, please, be careful when using set commands in rendering config and pushig it with plugin, it can have unexpected side effects.
If you render not full configuration, it is acceptable to pull missing config sections from the actual configuration to render full configuration.
Note
If you render full configuration in NetBox, you can proceed to Configuration Request part
To do that you should create substitute.
Substitutes is a \"tag\" that needs to be replaced with output from the real device, and a regex pattern that \"pulls\" this section from the actual device itself.
In screenshot below we add substitute for Arista PlatformSetting
Name jinja2 variable in config templateIn example substitute ethernet_interfaces section will be replaced with whatever the provided pattern finds from the real device.
This pattern matches all ethernet interfaces on a Arista device.
To correctly render substitute in config template you have two options:
{{ \"{{ ethernet_interfaces }}\" }}\nor
{% raw %}{{ ethernet_interfaces }}{% endraw %}\nConfig template will look like:
And rendered config template with substitute
"},{"location":"configuratiom-management/#configuration-request","title":"Configuration Request","text":"Now you let's create Configuration Request with devices you want to configure.
Warning
For request only accepts devices with Active status and assigned Platform, Primary IP, and PlatformSetting
Find Configuration Requests in navbar.
Now collect diffs for devices pressing Collecting diffs button.
On tab Diffs you can review diffs for devices.
To continue approve request by pressing Approve button.
Also you can cancel approve after that.
After approval you can see by whom configuration request is approved.
At this moment you can schedule job that will push rendered configuration to devices in configuration request by pressing schedule button.
After that you can see by whom configuration request is scheduled and time.
Also you can cancel scheduled job by pressing Unschedule button.
Warning
Approve and Schedule buttons is accessable only to user with netbox_config_diff.approve_configurationrequest permission
Warning
If you unapprove scheduled configuration request, scheduled job will be canceled
After scheduled job is completed you can job logs on configuration request page.
Note
Completed configuration requests can't be edited.
"},{"location":"configuratiom-management/#rollback","title":"Rollback","text":"If an error occurs while executing a job that pushes configurations to devices then all configured devices will be rollbacked to the previous version of the configuration.
"},{"location":"contributing/","title":"Contributing","text":"Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
"},{"location":"contributing/#types-of-contributions","title":"Types of Contributions","text":""},{"location":"contributing/#report-bugs","title":"Report Bugs","text":"Report bugs at https://github.com/miaow2/netbox-config-diff/issues.
If you are reporting a bug, please include:
Look through the GitHub issues for bugs. Anything tagged with \"bug\" and \"help wanted\" is open to whoever wants to implement it.
"},{"location":"contributing/#implement-features","title":"Implement Features","text":"Look through the GitHub issues for features. Anything tagged with \"enhancement\" and \"help wanted\" is open to whoever wants to implement it.
"},{"location":"contributing/#write-documentation","title":"Write Documentation","text":"NetBox Config Diff Plugin could always use more documentation, whether as part of the official NetBox Config Diff Plugin docs, in docstrings, or even on the web in blog posts, articles, and such.
"},{"location":"contributing/#submit-feedback","title":"Submit Feedback","text":"The best way to send feedback is to file an issue at https://github.com/miaow2/netbox-config-diff/issues.
If you are proposing a feature:
Ready to contribute? Here's how to set up netbox-config-diff for local development.
netbox-config-diff repo on GitHub.Clone your fork locally
$ git clone git@github.com:your_name_here/netbox-config-diff.git
Install dependencies and start your virtualenv:
$ poetry install -E test -E doc -E dev
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you're done making changes, check that your changes pass the tests, including testing other Python versions, with tox:
$ poetry run tox
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m \"Your detailed description of your changes.\" $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Before you submit a pull request, check that it meets these guidelines:
A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in CHANGELOG.md). Then run:
$ poetry run bump2version patch # possible: major / minor / patch\n$ git push\n$ git push --tags\nGitHub Actions will then deploy to PyPI if tests pass.
"},{"location":"screenshots/","title":"Screenshots","text":"Also result is storing rendered and actual configurations from device.
Compliance finished with error
Render diff between configurations
No diff
"},{"location":"secrets/","title":"Integration with NetBox secrets plugin","text":"You can store credentials for devices authentification in NetBox secrets plugin.
Read NetBox secrets docs for more info.
In plugin variables define secrets roles for username (USER_SECRET_ROLE), password (PASSWORD_SECRET_ROLE) and password (SECOND_AUTH_SECRET_ROLE) for Privileged EXEC mode.
Default values for this variables are:
PLUGINS_CONFIG = {\n \"netbox_config_diff\": {\n \"USER_SECRET_ROLE\": \"Username\",\n \"PASSWORD_SECRET_ROLE\": \"Password\",\n \"SECOND_AUTH_SECRET_ROLE\": \"Second Auth\",\n },\n}\nScript will find secrets with these roles attached to the device and use them as credentials.
If something goes wrong, then credentials from PLUGINS_CONFIG will be used.
You can store credentials for devices authentification in NetBox secrets plugin.
+Read NetBox secrets docs for more info.
+In plugin variables define secrets roles for username (USER_SECRET_ROLE), password (PASSWORD_SECRET_ROLE) and
+ password (SECOND_AUTH_SECRET_ROLE) for Privileged EXEC mode.
Default values for this variables are:
+PLUGINS_CONFIG = {
+ "netbox_config_diff": {
+ "USER_SECRET_ROLE": "Username",
+ "PASSWORD_SECRET_ROLE": "Password",
+ "SECOND_AUTH_SECRET_ROLE": "Second Auth",
+ },
+}
+Script will find secrets with these roles attached to the device and use them as credentials.
+If something goes wrong, then credentials from PLUGINS_CONFIG will be used.