Using the App¶
This document describes common use-cases and scenarios for this App.
General Usage¶
This app provides import_netbox
management command to import data from NetBox with the following options:
nautobot-server import_netbox --help
usage: nautobot-server import_netbox [-h] [--dry-run] [--update-paths] [--bypass-data-validation]
[--sitegroup-parent-always-region] [--fix-powerfeed-locations] [--print-summary]
[--no-unrack-zero-uheight-devices]
[--save-json-summary-path SAVE_JSON_SUMMARY_PATH]
[--save-text-summary-path SAVE_TEXT_SUMMARY_PATH] [--version] [-v {0,1,2,3}]
[--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color]
[--force-color] [--skip-checks]
json_file
Import a NetBox JSON data dump into Nautobot's database
positional arguments:
json_file URL or path to the JSON file to import.
options:
-h, --help show this help message and exit
--dry-run Do not write any data to the database.
--update-paths Call management command `trace_paths` to update paths after the import.
--bypass-data-validation
Bypass as much of Nautobot's internal data validation logic as possible, allowing the import of
data from NetBox that would be rejected as invalid if entered as-is through the GUI or REST
API. USE WITH CAUTION: it is generally more desirable to *take note* of any data validation
errors, *correct* the invalid data in NetBox, and *re-import* with the corrected data!
--sitegroup-parent-always-region
When importing `dcim.sitegroup` to `dcim.locationtype`, always set the parent of a site group
, to be a `Region` location type. This is a workaround to fix validation errors
`'A Location of type Location may only have a Location of the same type as its parent.'`.
--fix-powerfeed-locations
Fix panel location to match rack location based on powerfeed.
--print-summary Show a summary of the import.
--no-unrack-zero-uheight-devices
Prevents cleaning the `position` field in `dcim.device` instances that fail validation if the
device is in a rack.
--save-json-summary-path SAVE_JSON_SUMMARY_PATH
File path to write the JSON summary to.
--save-text-summary-path SAVE_TEXT_SUMMARY_PATH
File path to write the text summary to.
--trace-issues Show a detailed trace of issues originated from any `Exception` found during the import.
--version show program's version number and exit
-v {0,1,2,3}, --verbosity {0,1,2,3}
Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
--settings SETTINGS The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided,
the DJANGO_SETTINGS_MODULE environment variable will be used.
--pythonpath PYTHONPATH
A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
--traceback Raise on CommandError exceptions
--no-color Don't colorize the command output.
--force-color Force colorization of the command output.
--skip-checks Skip system checks.
Importing Data Into Nautobot¶
This chapter outlines how to import data from NetBox into Nautobot.
Getting a Data Export from NetBox¶
Run the following command from the NetBox root directory to create a JSON file (/tmp/netbox_data.json
) that contains the contents of your NetBox database:
./manage.py dumpdata \
--traceback \
--format=json \
--indent=2 \
--natural-primary \
--natural-foreign \
--exclude=extras.ObjectChange \
--output=/tmp/netbox_data.json
It's possible to exclude other models from the export, but the command provided above is a good starting point. The import_netbox
command will skip models that are not present in the Nautobot database.
Warning
The export command may fail if there are registered content types not present in the database. If you encounter an error message such as:
django.db.utils.ProgrammingError: relation "extras_report" does not exist
LINE 1: SELECT COUNT(*) AS "__count" FROM "extras_report"
--exclude=extras.Report
.
Tip
Change log ObjectChange
records are not included in the export command above because they can contain a massive amount of data. It's possible to import change log records in the next step, as described later in this document.
Dry Run¶
Before importing data into Nautobot, it's a good idea to process a dry run to see what will happen. This will not write any data to the database, but will show you what will happen if you run the import.
nautobot-server import_netbox \
--dry-run \
--bypass-data-validation \
--print-summary \
/tmp/netbox_data.json
The following document describes summary with mapping from NetBox 3.6 to Nautobot 2.1.5. Other versions mappings can vary.
Importing Data into Nautobot¶
Within the Nautobot application environment, run nautobot-server import_netbox <json_file>
; for example: nautobot-server import_netbox /tmp/netbox_data.json
.
Consider using the above-mentioned command options based on a dry run.
Data Validation and Error Handling¶
Note that the importer does apply Nautobot's data validation standards to the data records as it imports them. If any data records fail to meet data validation, you will see detailed error messages. For example, the following error might be generated if your NetBox data contains a rack that is assigned to a different location than the power panel.
0434ed4d-cc76-5051-a38c-b84ed32de2c1 P2-6B | ValidationError | ['Rack R106 (Row 1) and power panel Panel 2 (MDF) are in different locations']
In this case, the import of this Rack into Nautobot will fail, and you may encounter a series of cascading errors as other objects dependent on this Rack (e.g., Devices) also fail due to the absence of the Rack.
Normally, the correct response to this sort of error is to understand the cause of the error, log into your NetBox instance, and correct the invalid data. Then, re-export the data from NetBox and re-run the importer.
If, however, fixing the source data in NetBox is not possible for whatever reason, you can instruct the importer to import the data even if it fails Nautobot's data validation checks, by specifying the --bypass-data-validation
option. This will result in your Nautobot database containing invalid data. As a result, you will want to rectify this in Nautobot as soon as possible to avoid unexpected errors in the future.
When using the --bypass-data-validation
option, data validation checks are still run, but any failures will be logged (rather than causing the import process to throw errors), enabling you to be aware of any issues that will need to be remediated in Nautobot.
To address this specific issue, you can use the --fix-powerfeed-locations
option to adjust panel locations to match rack locations based on the power feed object. Always verify the resulting data, as this option modifies affected panel locations.
Importing Change Log Records¶
Because the database's change log can contain a massive amount of data, and often this historical information does not need to be imported, ObjectChange
records are not included in the database export command above.
To import ObjectChange
records specifically, after the previous NetBox import process has succeeded, you can do the following.
Getting Change Log Only from NetBox¶
From within the NetBox root directory, run the following command to create a JSON file (/tmp/netbox_objectchange.json
).
./manage.py dumpdata \
--traceback \
--format=json \
--natural-primary \
--natural-foreign \
--output=/tmp/netbox_objectchange.json \
contenttypes.ContentType \
extras.ObjectChange
Don't forget to add ContentType
model to the export command above, otherwise importer will not be able to map ObjectChange
records to their corresponding objects.
Importing Change Log into Nautobot¶
From within the Nautobot application environment, run nautobot-server import_netbox <json_file_only_objectchanges>
, for example, nautobot-server import_netbox /tmp/netbox_objectchange.json
. This will skip all object change records that are not possible to map to their corresponding objects.