IOS has no native API to play with, that’s the reason why we used the Netmiko library to interact with it. Having Netmiko installed in your working box is a prerequisite.

Check napalm-ios/requirements.txt for Netmiko version requirement

Full ios driver support requires configuration rollback on error:

Cisco IOS requirements for 'Configuration Rollback Confirmed Change' feature.

Downgraded ios driver support (i.e. no auto rollback on configuration error for replace operation):

Cisco IOS requirements for 'Configuration Replace and Configuration Rollback' feature.

Note, to disable auto rollback you must add the auto_rollback_on_error=False optional argument.


IOSDriver requires that the archive functionality be enabled to perform auto-rollback on error. Make sure it’s enabled and set to a local filesystem (for example ‘flash:’ or ‘bootflash:’:

  path flash:archive

Configuration file

  • IOS requires config file to begin with a version eg. 15.0 and end marker at the end of the file. Otherwise IOS will reject configure replace operation.

  • For the diff to work properly, indentation of your candidate file has to exactly match the indentation in the running config.

  • Finish blocks with ! as with the running config, otherwise, some IOS version might not be able to generate the diff properly.

Self-Signed Certificate (and the hidden tab character)

Cisco IOS adds a tab character into the self-signed certificate. This exists on the quit line:

crypto pki certificate chain TP-self-signed-1429897839
 certificate self-signed 01
  3082022B 30820194 A0030201 02020101 300D0609 2A864886 F70D0101 05050030
  9353BD17 C345E1D7 71AFD125 D23D7940 2DECBE8E 46553314 396ACC63 34839EF7
  3C056A00 7E129168 F0CD3692 F53C62

The quit line reads as follows:

>>> for char in line:
...   print("{}: {}".format(repr(char), ord(char)))
' ': 32     # space
' ': 32     # space
'\t': 9     # tab
'q': 113
'u': 117
'i': 105
't': 116
'\n': 10

This implies that you will not generally be able to copy-and-paste the self-signed certificate. As when you copy-and-paste it, the tab character gets converted to spaces.

You will need to transfer the config file directly from the device (for example, SCP the config file) or you will need to manually construct the quit line exactly right.

Cisco IOS is very particular about the self-signed certificate and will reject replace operations with an invalid certificate. Cisco IOS will also reject replace operations that are missing a certificate (when the current configuration has a self-signed certificate).

File Operation Prompts

By default IOS will prompt for confirmation on file operations. These prompts need to be disabled before the NAPALM-ios driver performs any such operation on the device. This can be controlled using the auto_file_prompt optional argument:

  • auto_file_prompt=True (default): NAPALM will automatically add file prompt quiet to the device configuration before performing file operations, and un-configure it again afterwards. If the device already had the command in its configuration then it will be silently removed as a result, and this change will not show up in the output of compare_config().

  • auto_file_prompt=False: Disable the above automated behaviour. The managed device must have file prompt quiet in its running-config already, otherwise a CommandErrorException will be raised when file operations are attempted.

SCP File Transfers

The NAPALM-ios driver requires SCP to be enabled on the managed device. SCP server functionality is disabled in IOS by default, and is configured using ip scp server enable.

If an operation requiring a file transfer is attempted, but the necessary configuration is not present, a CommandErrorException will be raised.


  • The NAPALM-ios driver supports all Netmiko arguments as either standard arguments (hostname, username, password, timeout) or as optional_args (everything else).