• 29 Mar 2024
  • Dark
  • PDF


  • Dark
  • PDF

Article summary

Nornir is an automation framework written in Python for use in the development of applications that manage network devices. Nornir has its own inventory system for dealing with host information. It also handles the dispatching of tasks to your devices and provides a common framework to write plugins.

Itential Automation Gateway (IAG) contains a Nornir Module Execution Engine that supports the discovery, decoration, and execution of Nornir modules. IAG also provides support for managing Nornir device inventory files and plugins.

ⓘ Note:

A complete set of REST APIs are available for clients to manage Nornir inventory, module decoration, and execution. See the API Documentation section of the IAG UI for more information.


Before proceeding, ensure that the following prerequisites are met:

  • Familiarity with Nornir is recommended. For more information, refer to the Nornir documentation.
  • Nornir should be installed and configured on the IAG server that it will be connected to.

Example Nornir Components

In the examples presented throughout this guide, Nornir functionality is extended by integrating it with IAG. To do this, IAG interacts with two Nornir components:

  • The Nornir inventory (via its configuration file)
  • Nornir modules

Nornir is installed and configured on the relevant IAG server. The following files are present:

  • Nornir Configuration
  • Nornir Hosts
  • Nornir Groups
  • Nornir Netmiko Module
ⓘ Note:

Some values in the following code blocks, such as username and password, have been abstracted for security reasons. These values are denoted by brackets ({}).

Nornir Configuration File (config.yml)

    plugin: SimpleInventory
        host_file: "/usr/share/nornir/hosts.yml"
        group_file: "/usr/share/nornir/groups.yml"
        defaults_file: "/usr/share/nornir/defaults.yml"
    plugin: threaded
        num_workers: 100

Nornir Hosts File (hosts.yml)

    platform: 'ios'
    username: {USERNAME}
    password: {PASSWORD}
      - ios_group

Nornir Groups File (groups.yml)

    platform: 'ios'

Nornir Netmiko Module (

#!/usr/bin/env python3
import sys
from nornir import InitNornir
from nornir_utils.plugins.functions import print_result
from nornir_netmiko.tasks import netmiko_send_command

command = sys.argv[0]

nr = InitNornir(config_file="/usr/share/nornir/config.yml")

results =, command_string=command)


Configuring IAG to Use Nornir

To use Nornir with IAG, several properties must first be configured in the IAG properties.yml file:

ⓘ Note:

Some values in the following table may vary depending on your environment. These values are denoted by brackets ({}).

Property Required Value Description
nornir_enabled true Enables Nornir functionality in IAG.
nornir_config_file {/usr/share/nornir/config.yml} The path to the Nornir configuration file. IAG automatically discovers the inventory files defined here at startup.
nornir_module_path {/usr/share/nornir/modules} The path to the Nornir module directory. IAG automatically discovers modules in this directory at startup. If multiple module directories exist, a list of paths can be provided.

The IAG service must be restarted for changes to the properties.yml file to take effect.

Editing the IAG Configuration File

In the previous example, you confirmed that the required Nornir components are present on the IAG server. Now, you can configure IAG to use these components:

  1. Open the IAG properties.yml file in a text editor. For example, if using VIM, issue the following command.

    vim /opt/automation-gateway/conf/properties.yml
  2. Locate the Nornir section of the configuration file. This is denoted by the # Nornir # header.

  3. Configure the following properties:

    • Set the value of nornir_enabled to true.
    • Set the value of nornir_config_file to the path of the Nornir configuration file.
    • Set the value of nornir_module_path to the path of the Nornir module directory.
  4. Save your changes to the properties.yml file and exit the text editor.

  5. Restart the IAG service with the following command.

    systemctl restart automation-gateway
  6. Verify that the IAG service has restarted successfully by issuing this command.

      systemctl status automation-gateway

Example Nornir Configuration in the IAG Properties File (properties.yml)

# Nornir #

# A boolean flag that enables Nornir support (default=False if absent/misconfigured).
nornir_enabled: true

# Path to the Nornir configuration file.
# A valid file will allows the use of Nornir External inventory.
nornir_config_file: '/usr/share/nornir/config.yml'

# Discovery behavior for Nornir modules. Determines whether or not to
# recursively search the directories found in the 'nornir_module_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
nornir_module_recursive: true

# Path(s) to the Nornir modules that should be discovered by Automation Gateway.
  # Default location for custom content per the setup script
  - '/usr/share/nornir/modules'

Module Decoration

After IAG has been configured to use Nornir, it will automatically discover any modules present in the designated directory. Discovered modules can be decorated in IAG.

The decoration of Nornir modules within IAG is similar to that of Ansible playbooks. However, instead of decorating the variables within a playbook, users decorate the command line arguments and environment variables used to execute a Nornir module. The decorated parameters are then passed as arguments to the APIs that execute the module. A permanent copy of each module's decoration is stored in a local database that is maintained by IAG.

The same features and functionality provided by IAG for decorating proprietary scripts are available for decorating Nornir modules. See the Script Execution Engine section of the IAG guide for complete instructions on module decoration.

Decorating the Discovered Nornir Module

Now that you have integrated Nornir with IAG, you can use IAG to decorate Nornir modules. In this example, you will decorate the module detailed earlier. This module allows a user to send commands to inventory devices for execution.

Starting from the IAG dashboard:

  1. Select Nornir from the side navigation menu to open Nornir.

  2. Select Modules from the side navigation menu. An accordion menu that lists all discovered Nornir modules expands.

  3. Select from the accordion menu to open the module for decoration.

    Figure 1: Module Decoration (


  4. On the Parameters tab, click the Edit (pencil) icon. A text editor opens that displays a JSON representation of the available module parameters.

    Default Module Parameters

    	"properties": {
    		"argument_list": {
    			"type": "array",
    			"description": "Array of arguments to be passed to the nornir module",
    			"items": {
    				"type": "string"
    		"env_vars": {
    			"type": "object",
    			"description": "Object containing environment variables to be passed to nornir module",
    			"properties": {
    				"env_list": {
    					"type": "array",
    					"description": "Array of environment variable 'name=value' pairs for nornir module",
    					"items": {
    						"type": "string"
    	"script_argument_order": [
  5. Edit the JSON as follows. The module will now have a single parameter, "command".

    Decorated Module Parameters

    	"schema": {
    		"properties": {
    			"command": {
    				"type": "string",
    				"description": "command to run remotely"
    		"script_argument_order": [
    		"title": "",
    		"type": "object"
  6. Click Save to retain your changes.


Nornir modules are executed by issuing a POST {hostname:port}/nornir/{module_name}/execute call to IAG. Executing a module can be done using the IAG UI or by a separate application. Modules are executed on the node on which the IAG server is running.

The desired arguments and environment variables that match the Nornir module's schema are included as execution parameters. The execution parameters are passed to the module as if they were being entered by the user on the command line. Part of the module's execution logic is to parse the contents of the command line accordingly.

By default, modules are executed from the home directory of the user that owns the IAG server process. To change the default execution directory, add the working_dir key to the module's schema outside the properties object. The value of working_dir can be an absolute or a relative directory path.

Hosts and Groups Support

The Nornir module execution API contains support for the hosts and groups parameters. The hosts parameter is an array of Nornir device names that are members of the IAG inventory. Similarly, the groups parameter is an array of Nornir group names that are present in the IAG inventory.

ⓘ Note:

The hosts and groups parameters are not required when executing a Nornir module.

When the hosts or groups parameters are present and their contents are validated, the Nornir Module Execution Engine will pass the contents to the Nornir module as a comma-separated list using the command line arguments --hosts and --groups. The Nornir module itself is responsible for parsing the contents of the --hosts and --groups arguments.


The following fields are contained within the results object returned after execution of the module.

Key Description
status String indicating SUCCESS or FAILURE of script execution.
stdout String buffer containing data the script wrote to standard output.
stderr String buffer containing data the script wrote to standard error.
command Full path of script along with corresponding command line.
env Array showing environment variables passed to script.
msg Supplemental information message.
argument_warnings Warning messages for arguments that do not match the script schema.
env_warnings Warning messages for environment variables that do not match the script schema.
working_directory Directory to start execution script.

Executing the Discovered Nornir Module

After decorating the module, you are ready to execute it against the Cisco IOS device present in the Nornir inventory, ios_host.

Starting from the Execute tab of the module:

  1. Click the Hosts field to search a list of all hosts defined in the Nornir inventory. Select IOS1.

  2. Enter the 'show version' IOS command into the command field.

  3. Click the Play (►) button to execute the command against IOS1. The results of the command will be returned in JSON format.

    Figure 2: Executing a Command


ⓘ Note:

If you are attempting to run a command that contains a space, you must enclose the command in single quotation marks ('').

Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.