Using the App¶
This document describes common use-cases and scenarios for this App utilizing the exposed SSoT jobs.
General Usage¶
This App can be used in three general ways.
- Onboard a device with basic information. (Name, Serial, Device Type, Management IP + Interface)
- Take existing devices and enhance the data for each device by syncing in more metadata. (Interface, VLANs, VRFs, Cabling, etc.)
- Both 1 and 2 in conjunction with each other.
Preparation¶
To properly onboard a device, a user needs to provide, at a minimum:
- The Device's Location
- The Device's primary IP address or DNS Name
- Selecting other attributes metadata needed. (Default statuses, roles, etc.)
Note
For DNS Name Resolution to work, the Celery instance of Nautobot must be able to resolve the name of the device to IP address.
If Platform
, Device Type
and/or Role
are not provided, the plugin will try to identify this information automatically and, based on the settings, it can create them in Nautobot as needed.
Note
The SSoT jobs use nornir-netmiko to run the show commands defined in the command mappers.
SSH Autodetect¶
The nautobot-device-onboarding
apps Sync Devices
job recognizes platform types with a Netmiko SSH Autodetect mechanism. The user may need to specify additional information for platforms where Netmiko's ssh_autodetect
feature does not work.
Here is the list of platforms supported by ssh_autodetect
.
For the platforms where SSH auto-detection does not work, the user will need to:
- Select the platform in the job inputs form.
IOS and Junos Auto-Created Platforms¶
The Onboarding App will automatically create Platforms for vendor operating systems where platform auto-detection works. The picture below shows the details of auto-created Platforms for cisco_ios
and juniper_junos
.
Passing Custom Nornir Connection Options¶
Device Onboarding 4.0 uses Netmiko as the automation engine that queries the devices for information; more specifically, nornir-netmiko. To extend the device onboarding app to pass extras
to the connection options the following can be added to nautobot_plugin_nornir
PLUGIN_CONFIG
.
PLUGINS_CONFIG = {
"nautobot_device_onboarding": {},
"nautobot_plugin_nornir": {
"nornir_settings": {
"... omitted ..."},
"connection_options": {
"netmiko": {
"extras": { # <==== passed into the connection setup.
"fast_cli": False,
"read_timeout_override": 30,
},
},
},
},
}
When the on-demand inventory is created for the Sync Device from Network
job, the extras in the netmiko
connection dictionary are added to the connection setup.
Using SSH PubKey Authentication¶
In the case where you want to use SSH Public Key authentication that can be accomplished by adding the additional arguments into Netmiko. This is done using the plugin configuration.
-
Create the ssh key on the Nautobot worker server/container.
-
Add the Netmiko Extras to the configuration.
PLUGINS_CONFIG = {
"nautobot_device_onboarding": {},
"nautobot_ssot": {
"hide_example_jobs": True,
},
"nautobot_plugin_nornir": {
"nornir_settings": {
"credentials": "nautobot_plugin_nornir.plugins.credentials.nautobot_secrets.CredentialsNautobotSecrets",
"runner": {
"plugin": "threaded",
"options": {
"num_workers": 20,
},
},
},
"connection_options": {
"netmiko": {
"extras": {
"use_keys": True,
"key_file": "/root/.ssh/id_rsa",
"disabled_algorithms": {"pubkeys": ["rsa-sha2-256", "rsa-sha2-512"]},
},
},
},
},
}
-
Make a secrets group in Nautobot which has the accurate
username
to use along with the key specified in configuration above. -
Run the jobs and ssh public key authentication will be used.
Using SSH Proxy Jumphost¶
In the case where you want to use a SSH proxy jumphost, it can be accomplished by adding the additional arguments into Netmiko. This is done using the plugin configuration.
- Follow the standard Jumphost proxy setup to create the ssh_config file with the proper settings.
For example:
root@fcdc254e2a36:/source# cat /root/.ssh/config
host jumphost
IdentitiesOnly yes
IdentityFile ~/.ssh/id_rsa
User ntc
HostName 10.1.1.10
host * !jumphost
User admin
KexAlgorithms +diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1
HostKeyAlgorithms +ssh-rsa
ProxyCommand ssh -F /root/.ssh/config -W %h:%p jumphost
- Add the Netmiko Extras to the configuration.
PLUGINS_CONFIG = {
"nautobot_device_onboarding": {},
"nautobot_ssot": {
"hide_example_jobs": True,
},
"nautobot_plugin_nornir": {
"nornir_settings": {
"credentials": "nautobot_plugin_nornir.plugins.credentials.nautobot_secrets.CredentialsNautobotSecrets",
"runner": {
"plugin": "threaded",
"options": {
"num_workers": 20,
},
},
},
"connection_options": {
"netmiko": {
"extras": {
"ssh_config_file": "/root/.ssh/config",
},
},
},
},
}
- Run the jobs and the ssh config will be used and the connection will be proxied through the jumphost.
Use-cases and common workflows¶
Onboarding a Device¶
Onboard a New Device Using Sync Devices From Network Job¶
A new device can be onboarded via :
- A SSoT job execution using the
Sync Devices from Network
job.- Via Jobs menu
- Via SSoT Dashboard
- API, via a
POST
to/api/extras/jobs/SSOTSyncDevices/run
or/api/extras/jobs/{id}/run
Note
The SSoT Job's ID (UUID) will be different per Nautobot instance.
During a successful onboarding process, a new device will be created in Nautobot with its management interface and its primary IP assigned. The management interface will be discovered on the device based on the IP address provided.
This SSoT job supports a bulk CSV execution option to speed up this process.
Example CSV¶
ip_address_host,location_name,device_role_name,namespace,device_status_name,interface_status_name,ip_address_status_name,secrets_group_name,platform_name,set_mgmt_only,update_devices_without_primary_ip,
192.168.1.1,"Test Site",Onboarding,Global,Active,Active,Active,"test secret group",,False,True
Consult the Status of the Sync Network Devices SSoT Job¶
The status of onboarding jobs can be viewed via the UI (Jobs > Job Results) or retrieved via API (/api/extras/job-results/
) with each process corresponding to an individual Job-Result object.
API¶
To run the SSoT Sync Devices Job via the api:
Post to /api/extras/jobs/SSOTSyncDevices/run/
with the relevant onboarding data:
curl -X "POST" <nautobot URL>/api/extras/jobs/SSOTSyncDevices/run/ -H "Content-Type: application/json" -H "Authorization: Token $NAUTOBOT_TOKEN" -d '{"data": {"location": "<valid location UUID>", "ip_address": "<reachable IP to onboard>", "port": 22, "timeout": 30}}
Required Fields: location: Location UUID ip_address: String of IP or CSV of IPs port: Integer timeout: Integer
Optional Fields: credentials: Secret Group UUID platform: Platform UUID role: Role UUID device_type: Device Type UUID continue_on_failure: Boolean
Onboarding Interface, Vlans, IPs Etc.¶
Enhance Existing Device¶
An existing device's data can be expanded to include additional objects by:
- A SSoT job execution.
- Via Jobs menu
- Via SSoT Dashboard
- API, via a
POST
to/api/extras/jobs/SSOTSyncNetworkData/run
or/api/extras/jobs/{id}/run
Note
The SSoT Job's ID (UUID) will be different per Nautobot instance.
During a successful network data sync process, a devices related objects will be created in Nautobot with all interfaces, their IP addresses, and optionally VLANs, and VRFs.
Consult the Status of the Sync Network Data SSoT Job¶
The status of onboarding jobs can be viewed via the UI (Jobs > Job Results) or retrieved via API (/api/extras/job-results/
) with each process corresponding to an individual Job-Result object.
API¶
To run the SSoT Sync Network Data Job via the api:
Post to /api/extras/jobs/SSOTSyncNetworkData/run/
with the relevant onboarding data:
curl -X "POST" <nautobot URL>/api/extras/jobs/SSOTSyncNetworkData/run/ -H "Content-Type: application/json" -H "Authorization: Token $NAUTOBOT_TOKEN" -d '{"data": {"devices": "<valid devices UUID>"}
Required Fields: devices: Location UUID
Using Git(Datasources) to Override the Apps Defaults¶
YAML Overrides¶
By utilizing the Nautobot core feature Datasource
the command mappers, jpaths, post_processors for each platform can be overridden. This also gives an easy way for a user to add platform support without having to get those fixes directly upstreamed into this application.
The format of these YAML files are and how to extend this application is covered in App YAML Overrides.
Parser Templates¶
As this App continues to mature, support has been added to support TTP
; with this addition the ability to add and/or override templates was required. This follows a similar pattern to the YAML overrides.
TTP Parser Extensions¶
Info
To avoid overly complicating the merge logic, the App will always prefer the template files loaded in from the git repository.
File structure:
.
├── README.md
└── onboarding_command_mappers
└── parsers
└── ttp
└── <network_driver>_<command seperated by underscores>.ttp
When loading from a Git Repository this App is expecting a root directory called onboarding_command_mappers
. Parser files should be located in a parsers
directory followed by one additional directory; e.g., ttp
. The template file names must be named <network_driver>_<command_seperated_by_underscores>.ttp
.
Textfsm Parser Extensions¶
Info
To avoid overly complicating the merge logic, the App will always prefer the template files loaded in from the git repository. If a template isn't found in the git repository it will fallback to using native ntc-templates directory.
File structure:
.
├── README.md
└── onboarding_command_mappers
└── parsers
└── textfsm
└── <network_driver>_<command seperated by underscores>.textfsm
└── index
Warn
The repository must have an index file as is always expected with textfsm.
When loading from a Git Repository this App is expecting a root directory called onboarding_command_mappers
. Parser files should be located in a parsers
directory followed by one additional directory; e.g., textfsm
. The template file names must be named <network_driver>_<command_seperated_by_underscores>.ttp
and the index file must exist and must be defined appropriately.
For example:
Where index file is: