> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-gateway/4/nornir-integration/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Nornir integration > Configure and use the Nornir Python automation framework with Itential Gateway for network device inventory management and module execution. **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 Gateway contains a **Nornir Module Execution Engine** that supports the discovery, decoration, and execution of Nornir modules. Gateway also provides support for managing Nornir device inventory files and plugins. 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 Gateway UI for more information. ## Prerequisites Before proceeding, ensure that the following prerequisites are met: * Familiarity with Nornir is recommended. For more information, refer to the [Nornir documentation](https://nornir.readthedocs.io/en/latest/index.html). * Nornir should be installed and configured on the Gateway 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 Gateway. To do this, Gateway interacts with two Nornir components: * The Nornir inventory (via its configuration file) * Nornir modules Nornir is installed and configured on the relevant Gateway server. The following files are present: * Nornir Configuration * Nornir Hosts * Nornir Groups * Nornir Netmiko Module Some values in the following code blocks, such as `username` and `password`, have been abstracted for security reasons. These values are denoted by brackets (curly braces). ### Nornir configuration file (`config.yml`) ```yaml --- inventory: plugin: SimpleInventory options: host_file: "/usr/share/nornir/hosts.yml" group_file: "/usr/share/nornir/groups.yml" defaults_file: "/usr/share/nornir/defaults.yml" runner: plugin: threaded options: num_workers: 100 ``` ### Nornir hosts file (`hosts.yml`) ```yaml --- ios_host: hostname: 172.20.100.203 platform: 'ios' username: USERNAME_PLACEHOLDER password: PASSWORD_PLACEHOLDER groups: - ios_group ``` ### Nornir groups file (`groups.yml`) ```yaml --- ios_group: platform: 'ios' ``` ### Nornir Netmiko module (`send_command.py`) ```python #!/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 = nr.run(netmiko_send_command, command_string=command) print_result(results) ``` ## Configure Gateway to use Nornir To use Nornir with Gateway, several properties must first be configured in the Gateway `properties.yml` file. Some values in the following table may vary depending on your environment. These values are denoted by brackets (curly braces). | Property | Required Value | Description | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | nornir\_enabled | true | Enables Nornir functionality in Gateway. | | nornir\_config\_file | /usr/share/nornir/config.yml | The path to the Nornir configuration file. Gateway automatically discovers the inventory files defined here at startup. | | nornir\_module\_path | /usr/share/nornir/modules | The path to the Nornir module directory. Gateway automatically discovers modules in this directory at startup. If multiple module directories exist, a list of paths can be provided. | The Gateway service must be restarted for changes to the **properties.yml** file to take effect. ### Edit the Gateway configuration file In the [previous example](#example-nornir-components), you confirmed that the required Nornir components are present on the Gateway server. Now, you can configure Gateway to use these components: #### Open the Gateway properties.yml file Open the Gateway **properties.yml** file in a text editor. For example, if using VIM, issue the following command. ```bash vim /opt/automation-gateway/conf/properties.yml ``` #### Locate the Nornir section Locate the Nornir section of the configuration file. This is denoted by the `# Nornir #` header. #### Configure the Nornir properties 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. #### Save your changes Save your changes to the `properties.yml` file and exit the text editor. #### Restart the Gateway service Restart the Gateway service with the following command. ```bash systemctl restart automation-gateway ``` #### Verify the Gateway service Verify that the Gateway service has restarted successfully by issuing this command. ```bash systemctl status automation-gateway ``` #### Example Nornir configuration in the Gateway properties file (`properties.yml`) ```yaml ########## # 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 Gateway. nornir_module_path: # Default location for custom content per the setup script - '/usr/share/nornir/modules' ``` ## Module decoration After Gateway has been configured to use Nornir, it will automatically discover any modules present in the designated directory. Discovered modules can be decorated in Gateway. The decoration of Nornir modules within Gateway is similar to that of Ansible playbooks. However, instead of decorating the variables within a playbook, you 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 Gateway. The same features and functionality provided by Gateway for decorating proprietary scripts are available for decorating Nornir modules. See the [Script execution engine](./script-execution-engine) section of the Gateway guide for complete instructions on module decoration. ### Decorate the discovered Nornir module Now that you have [integrated Nornir with Gateway](#edit-the-iag-configuration-file), you can use Gateway to decorate Nornir modules. In this example, you will decorate the `send_command.py` module detailed [earlier](#example-nornir-components). This module allows you to send commands to inventory devices for execution. Starting from the Gateway dashboard: #### Open Nornir Select **Nornir** from the side navigation menu to open Nornir. #### Open the Modules menu Select **Modules** from the side navigation menu. An accordion menu that lists all discovered Nornir modules expands. #### Select the module Select **send\_command.py** from the accordion menu to open the module for decoration. ![](/_fern-img/9b4ad3e1f35744c32b6eb03b1c1f56d245b807f0616c111bcc9f5438bdd5684a.webp) #### Open the parameter editor On the Parameters tab, click the **Edit (pencil)** icon. A text editor opens that displays a JSON representation of the available module parameters. ```json { "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": [ "argument_list" ] } ``` #### Edit the module parameters Edit the JSON as follows. The module will now have a single parameter, **"command"**. ```json { "schema": { "properties": { "command": { "type": "string", "description": "command to run remotely" } }, "script_argument_order": [ "command" ], "title": "send_command.py", "type": "object" } } ``` #### Save your changes Click **Save** to retain your changes. ## Execution Nornir modules are executed by issuing a `POST /nornir//execute` call to Gateway. Executing a module can be done using the Gateway UI or by a separate application. Modules are executed on the node on which the Gateway 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 Gateway 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 Gateway inventory. Similarly, the `groups` parameter is an array of Nornir group names that are present in the Gateway inventory. 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. ### Results 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. | ### Execute the discovered Nornir module After [decorating the `send_command.py` module](#decorate-the-discovered-nornir-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 `send_command.py` module: #### Select the host Click the **Hosts** field to search a list of all hosts defined in the Nornir inventory. Select **IOS1**. #### Enter the command Enter the **'show version'** IOS command into the **command** field. #### Execute the command Click the **Play** button to execute the command against IOS1. The results of the command will be returned in JSON format. ![](/_fern-img/f98719cd3563d7942281095a2ae87bb8a975ff87e69c2e3d424f1b34642a209a.webp) If you are attempting to run a command that contains a space, you must enclose the command in single quotation marks (''). > Configure and use the Nornir Python automation framework with Itential Gateway for network device inventory management and module execution.