NAPALM Documentation

NAPALM can be integrated into several major automation frameworks:

• Ansible: Use the napalm-ansible modules to leverage the NAPALM API within Ansible playbooks.
• SaltStack: NAPALM is natively integrated into SaltStack (since release Carbon). For setup recommendations, refer to napalm-salt.
• StackStorm: Use the stackstorm-napalm integration pack to use NAPALM within StackStorm workflows.

Depending on your use case (especially if you are working with virtualized network environments), you may need the following tools installed on your system:

• Python: The core programming language.
• pip: The recommended tool for installing Python packages.
• VirtualBox: A software virtualization tool used for running virtual machines.
• Vagrant: A command-line utility for managing the lifecycle of virtual machines (useful for setting up lab environments).

The mock driver determines which file to read based on the function name and its position in the call stack.

Call Stack Rules:

• device.open() counts as the first command in the stack.
• Subsequent method calls start numbering from 1.
• For standard methods, the filename pattern is {method_name}.{call_index}.
• For device.cli(commands) calls, the pattern is cli.{call_index}.{sanitized_command}.{command_index}.

Data Formats:

• Standard methods expect a JSON file containing the desired return value.
• cli commands expect a plain text file containing the raw command output.
• To simulate errors, provide a JSON file defining the exception type and its arguments.

Merges in the NXOS driver are implemented by applying configuration lines one by one. Unlike configuration replacement, merges do not use the checkpoint/rollback functionality and are therefore not atomic.

Diffs for merges are generated using the Netutils library to compare the candidate configuration against the running configuration offline. The resulting diff consists of the lines present in the merge candidate config.

Because custom methods are not part of the base NAPALM driver classes, attempting to call a custom method on an OS that does not implement it will result in an ungraceful failure. To handle this, you should explicitly raise NotImplementedError in your custom driver implementations for operating systems where the method is not supported.

from napalm.ios.ios import IOSDriver

class CustomIOSDriver(IOSDriver):
    """Custom NAPALM Cisco IOS Handler."""
    def get_my_banner(self):
        raise NotImplementedError

To enable the 'Configuration Rollback Confirmed Change' feature (auto-rollback on error), the IOS archive functionality must be enabled and configured to use a local filesystem (e.g., flash: or bootflash:).

Example configuration on the device:

archive
  path flash:archive
  write-memory

If you wish to explicitly disable auto-rollback, pass auto_rollback_on_error=False as an optional argument when initializing the driver.

EOS configuration is loaded via pyeapi.eapilib.Node.run_commands(), which does not natively handle multi-line commands (e.g., banner motd).

NAPALM's EOSDriver._load_config() helper function mitigates this by attempting to detect HEREDOC commands in the input configuration and converting them into a dictionary format that the eAPI understands.

The rollback feature in NAPALM for EOS is supported only when committing via the API.

Internal Mechanism:

1. During a commit operation, the API executes: copy startup-config flash:rollback-0.
2. During a rollback operation, the API executes: configure replace flash:rollback-0.

Warning: Because rollback relies on these specific API-driven file operations, if you perform configuration changes outside of the NAPALM API, you must manually mark your last rollback point to ensure consistency.

NAPALM can be used to automate the validation of network state, ensuring that deployments match expected configurations.

Common use cases include:

• Automated Verification: Checking that BGP neighbors are configured and in the correct state (e.g., 'up').
• Inventory-Driven Validation: Building validator files dynamically from inventory data to verify network state against expectations without human intervention.
• Pre/Post Maintenance Validation: Writing manual validation files based on gathered network data and expectations before a maintenance window, then running them after changes to ensure the network state is exactly as intended. This replaces manual checks and one-off scripts.

NAPALM uses a centralized testing framework to ensure consistent functionality across all vendor drivers. The framework relies on shared tests defined in napalm.base/test/getters.py and uses mocked data to validate driver outputs.

Key Features:

• Shared Tests: The same test suite is applied across all vendors.
• Multiple Test Cases: A single test function can run multiple scenarios (e.g., 'normal', 'no_peers', 'lots_of_peers') by looking up specific subdirectories in the mocked data folder.
• Automatic Skipping: Methods marked as NotImplemented are automatically skipped by the framework.
• Output Validation: The framework compares the actual driver output against expected results stored in the mocked data.
• Configurable Targets: You can switch between running against mocked data or a live device using environment variables.