Nornir Service File Copy Task

The Nornir Service File Copy Task is a component of NorFab's Nornir service, designed to facilitate the transfer of files to and from network devices. This task provides network engineers with a reliable and efficient method for managing device configurations, firmware updates, and other critical files. By leveraging the capabilities of the Nornir service, users can automate file transfers.

Nornir File Copy Sample Usage

NORFAB Nornir File Copy Shell Reference

NorFab shell supports these command options for Nornir file-copy task:

nf#man tree nornir.file-copy
root
└── nornir:    Nornir service
    └── file-copy:    Copy files to/from devices
        ├── timeout:    Job timeout
        ├── workers:    Filter worker to target, default 'all'
        ├── add_details:    Add task details to results
        ├── run_num_workers:    RetryRunner number of threads for tasks execution
        ├── run_num_connectors:    RetryRunner number of threads for device connections
        ├── run_connect_retry:    RetryRunner number of connection attempts
        ├── run_task_retry:    RetryRunner number of attempts to run task
        ├── run_reconnect_on_fail:    RetryRunner perform reconnect to host on task failure
        ├── run_connect_check:    RetryRunner test TCP connection before opening actual connection
        ├── run_connect_timeout:    RetryRunner timeout in seconds to wait for test TCP connection to establish
        ├── run_creds_retry:    RetryRunner list of connection credentials and parameters to retry
        ├── tf:    File group name to save task results to on worker file system
        ├── tf_skip_failed:    Save results to file for failed tasks
        ├── diff:    File group name to run the diff for
        ├── diff_last:    File version number to diff, default is 1 (last)
        ├── progress:    Emit execution progress
        ├── table:    Table format (brief, terse, extend) or parameters or True
        ├── headers:    Table headers
        ├── headers_exclude:    Table headers to exclude
        ├── sortby:    Table header column to sort by
        ├── reverse:    Table reverse the sort by order
        ├── FO:    Filter hosts using Filter Object
        ├── FH:    Filter hosts by hostname
        ├── FC:    Filter hosts containment of pattern in name
        ├── FR:    Filter hosts by name using Regular Expressions
        ├── FG:    Filter hosts by group
        ├── FP:    Filter hosts by hostname using IP Prefix
        ├── FL:    Filter hosts by names list
        ├── FM:    Filter hosts by platform
        ├── FX:    Filter hosts excluding them by name
        ├── FN:    Negate the match
        ├── hosts:    Filter hosts to target
        ├── *source_file:    Source file to copy
        ├── plugin:    Connection plugin parameters
        │   └── netmiko:    Use Netmiko plugin to copy files
        │       ├── dest-file:    Destination file to copy
        │       ├── file-system:    Destination file system
        │       ├── direction:    Direction of file copy, default 'put'
        │       ├── inline-transfer:    Use inline transfer, supported by Cisco IOS
        │       ├── overwrite-file:    Overwrite destination file if it exists, default 'False'
        │       ├── socket-timeout:    Socket timeout in seconds, default '10.0'
        │       └── verify-file:    Verify destination file hash after copy, default 'True'
        └── dry-run:    Do not copy files, just show what would be done
nf#

* - mandatory/required command argument

Python API Reference

Task to transfer files to and from hosts using SCP

Parameters:

Name	Type	Description	Default
source_file	str	path to file to copy, support nf://path/to/file URL to copy from broker	required
plugin	str	plugin name to use - netmiko	'netmiko'
to_dict	bool	default is True - produces dictionary results, if False produces list	True
add_details	bool	if True will add task execution details to the results	False
dry_run	bool	if True will not copy files just return what would be copied	False
kwargs		additional arguments to pass to the plugin function	{}

Returns:

Type	Description
dict	dictionary with the results of the file copy task

Source code in norfab\workers\nornir_worker.py

def file_copy(
    self,
    source_file: str,
    plugin: str = "netmiko",
    to_dict: bool = True,
    add_details: bool = False,
    dry_run: bool = False,
    **kwargs,
) -> dict:
    """
    Task to transfer files to and from hosts using SCP

    :param source_file: path to file to copy, support ``nf://path/to/file`` URL to copy from broker
    :param plugin: plugin name to use - ``netmiko``
    :param to_dict: default is True - produces dictionary results, if False produces list
    :param add_details: if True will add task execution details to the results
    :param dry_run: if True will not copy files just return what would be copied
    :param kwargs: additional arguments to pass to the plugin function
    :return: dictionary with the results of the file copy task
    """
    filters = {k: kwargs.pop(k) for k in list(kwargs.keys()) if k in FFun_functions}
    timeout = self.current_job["timeout"] * 0.9
    ret = Result(task=f"{self.name}:file_copy", result={} if to_dict else [])

    # download file from broker
    if self.is_url(source_file):
        source_file_local = self.fetch_file(
            source_file, raise_on_fail=True, read=False
        )

    # decide on what send commands task plugin to use
    if plugin == "netmiko":
        task_plugin = netmiko_file_transfer
        kwargs["source_file"] = source_file_local
        kwargs.setdefault("socket_timeout", timeout / 5)
        kwargs.setdefault("dest_file", os.path.split(source_file_local)[-1])
    else:
        raise UnsupportedPluginError(f"Plugin '{plugin}' not supported")

    self.nr.data.reset_failed_hosts()  # reset failed hosts
    filtered_nornir = FFun(self.nr, **filters)  # filter hosts

    # check if no hosts matched
    if not filtered_nornir.inventory.hosts:
        msg = (
            f"{self.name} - nothing to do, no hosts matched by filters '{filters}'"
        )
        ret.messages.append(msg)
        log.debug(msg)
        return ret

    nr = self._add_processors(filtered_nornir, kwargs)  # add processors

    # run task
    log.debug(
        f"{self.name} - running file copy with arguments '{kwargs}', is dry run - '{dry_run}'"
    )
    if dry_run is True:
        result = nr.run(task=nr_test, name="file_copy_dry_run", **kwargs)
    else:
        with self.connections_lock:
            result = nr.run(task=task_plugin, **kwargs)

    ret.result = ResultSerializer(result, to_dict=to_dict, add_details=add_details)

    self.watchdog.connections_update(nr, plugin)
    self.watchdog.connections_clean()

    return ret