Skip to content

Nornir Service File Copy Task¤

task api name: file_copy

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, default 'False'
        ├── num-workers:    RetryRunner number of threads for tasks execution
        ├── num-connectors:    RetryRunner number of threads for device connections
        ├── connect-retry:    RetryRunner number of connection attempts
        ├── task-retry:    RetryRunner number of attempts to run task
        ├── reconnect-on-fail:    RetryRunner perform reconnect to host on task failure
        ├── connect-check:    RetryRunner test TCP connection before opening actual connection
        ├── connect-timeout:    RetryRunner timeout in seconds to wait for test TCP connection to establish
        ├── 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:    Display progress events, default 'True'
        ├── 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
        ├── FO:    Filter hosts using Filter Object
        ├── FB:    Filter hosts by name using Glob Patterns
        ├── 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
        │       ├── destination-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, default 'False'
        │       ├── 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, default 'False'
nf#

* - mandatory/required command argument

Python API Reference¤

Task to transfer files to and from hosts using SCP.

Parameters:

Name Type Description Default
job Job

NorFab Job object containing relevant metadata

required
source_file str

The path or URL of the source file to be copied in nf://path/to/file format

required
plugin str

The plugin to use for file transfer. Supported plugins:

  • netmiko - uses netmiko_file_transfer task plugin.
'netmiko'
to_dict bool

Whether to return the result as a dictionary. Defaults to True.

True
add_details bool

Whether to add detailed information to the result. Defaults to False.

False
dry_run bool

If True, performs a dry run without making any changes. Defaults to False.

False
**kwargs

Additional arguments to pass to the file transfer plugin.

{}

Returns:

Name Type Description
dict Result

The result of the file copy operation.

Raises:

Type Description
UnsupportedPluginError

If the specified plugin is not supported.

Source code in norfab\workers\nornir_worker.py
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
@Task(fastapi={"methods": ["POST"]})
def file_copy(
    self,
    job: Job,
    source_file: str,
    plugin: str = "netmiko",
    to_dict: bool = True,
    add_details: bool = False,
    dry_run: bool = False,
    **kwargs,
) -> Result:
    """
    Task to transfer files to and from hosts using SCP.

    Args:
        job: NorFab Job object containing relevant metadata
        source_file (str): The path or URL of the source file to be copied in
            ``nf://path/to/file`` format
        plugin (str, optional): The plugin to use for file transfer. Supported plugins:

            - netmiko - uses `netmiko_file_transfer` task plugin.

        to_dict (bool, optional): Whether to return the result as a dictionary. Defaults to True.
        add_details (bool, optional): Whether to add detailed information to the result. Defaults to False.
        dry_run (bool, optional): If True, performs a dry run without making any changes. Defaults to False.
        **kwargs: Additional arguments to pass to the file transfer plugin.

    Returns:
        dict: The result of the file copy operation.

    Raises:
        UnsupportedPluginError: If the specified plugin is not supported.
    """
    filters = {k: kwargs.pop(k) for k in list(kwargs.keys()) if k in FFun_functions}
    timeout = 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}'"
        )
        log.debug(msg)
        ret.messages.append(msg)
        ret.status = "no_match"
        return ret

    nr = self._add_processors(filtered_nornir, kwargs, job)  # 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.failed = result.failed  # failed is true if any of the hosts failed
    ret.result = ResultSerializer(result, to_dict=to_dict, add_details=add_details)

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

    return ret