Download File to Device
netcli.file_download has each target download one file from a file repository by itself, over HTTP or HTTPS: a software image onto a network device. The file does not pass through the worker.
For a Linux or Unix server, use shell.file_download (Download File to Host) instead: it needs no transport setting on the device and verifies the file's checksum on the host.
Using It
Pick the file with File; the step takes exactly one. Browse the file repositories and pick it, or type a template that gives a file reference: a run-form field of the "Repository file" type ({{ inputs.firmware }}), or another download step's {{ steps.NODE_ID.output.file }}. A reference names the file by its repository's name and its path there ({"repository": "Internal object storage", "path": "firmware/iosxe/cat9k.bin"}). The repository is looked up in the run's organization first, then in the shared organization. Two files with the same path in one repository are refused as ambiguous: remove or move one. A file the field names directly cannot be deleted from the repository while the flow uses it.
File by id (legacy), under the advanced settings, is how flows saved before File name the file: by its stored id. Such flows keep working. Set one of the two, not both. Naming a file by repository and path needs a Hegemony version that supports it; an older one fails the step and says to upgrade or use a file id.
Destination is where the file goes on the target: a device filesystem with its colon (flash:, the default, or bootflash:), or a directory on a server (/var/tmp). Destination Filename names it there; left empty, the file keeps the name it has in the repository. It is a file name only, with no slash: a directory belongs in Destination (flash:images/, /var/tmp). Neither field may contain a line break or another control character, or a question mark, because both are typed into the target's command line (where a question mark asks for help). Targets are chosen with the role-based target picker.
For each target, the step asks the platform for a download link, connects to the target and has it fetch the link:
- With the netmiko transport (network devices), it runs
copy <link> <destination><filename>and answers the questions the device asks before it starts (the destination file name, a confirmation to overwrite). This is the Cisco IOS and IOS XE form of the command. A platform that copies files with another command (Junos usesfile copy) is not supported: such a device fails. It fails at once when the device answers that it does not know the command, otherwise when Transfer timeout ends. - With the asyncssh transport (servers), it runs
curlon the server, which must have it installed. - The scrapli transport cannot do this; the step fails such a device and says to use the netmiko transport.
The link looks like <platform address>/dl/<token>/<filename>. It has no query string and is not a redirect, because the HTTP clients of network devices often handle neither. The token in it opens that one file and nothing else. Each target gets a link of its own, issued right before its download and ended right after it; an unused link expires after ten minutes (after an hour when targets download in parallel, because a target may wait its turn after its link was issued). The platform records each issued link in the audit log, with the run, the step and the file.
Targets must be able to reach the platform at the address an administrator set as HEGEMONY_API_EXTERNAL_URL. They do not need to reach the object store. With an https:// address the target must trust the platform's certificate; a device that cannot needs an http:// address on a trusted management network.
Transfer timeout (one hour by default, at most 24 hours) limits one target's download. The step's own timeout (two hours unless set) still covers the whole step, so it must leave time for every target. Max Parallel Devices controls the fan-out: 1 (the default) handles targets one after another, higher values up to that many at once (capped at 32).
The step transfers the file and reports what the target said. It does not check free space first and does not verify the file afterwards: follow it with a netcli.execute step for that (on Cisco IOS XE, verify /md5 flash:<filename> <md5>, with the checksum from this step's output).
SSH Compatibility
Allow legacy SSH algorithms defaults to off. Enable allow_legacy_ssh only for older devices which require weak algorithms or small host keys; it applies to the device and jump host for this step. Host-key verification still applies, and a failed secure connection never retries weakly. Prefer upgrading the device; use legacy mode only on a trusted network.
Output
Later steps can read:
steps.NODE_ID.output.filenameandsteps.NODE_ID.output.file_id: the stored file.steps.NODE_ID.output.dest_fsandsteps.NODE_ID.output.dest_filename: where it went.steps.NODE_ID.output.size_bytes,steps.NODE_ID.output.sha256andsteps.NODE_ID.output.md5: the stored file's size and checksums, for a verification step.md5is null for a file stored without one, so check it before a step uses it.steps.NODE_ID.output.transferred_count: how many targets completed the download.steps.NODE_ID.output.repository,steps.NODE_ID.output.pathandsteps.NODE_ID.output.folder: the file repository's name, the file's path in it (folder and file name) and its folder (empty for the repository root).steps.NODE_ID.output.repository_idis the repository's id.steps.NODE_ID.output.content_type,steps.NODE_ID.output.sha512andsteps.NODE_ID.output.metadata: the stored file's content type, SHA-512 (null for a file stored without one) and the metadata stored with it.steps.NODE_ID.output.file: a file reference to the same file ({"repository": ..., "path": ...}). Another download step takes it as its File:{{ steps.NODE_ID.output.file }}. The next step looks the repository and path up again, so it gets whatever file is at that path then. To get exactly the file this step downloaded, pass{{ steps.NODE_ID.output.file_id }}as its File by id (legacy) instead.fileis null when the platform did not report where the file is (an older platform given a file id); pass the id then too.
The repository keys need a Hegemony version that reports them; an older one leaves them null when the step names the file by id.
Each target contributes a "File download" evidence artifact with what it printed during the transfer, the file's details and the time taken; the download link is replaced by a placeholder there. It also names the file's repository, path and checksums. A target that fails contributes an "Error" artifact instead. Metrics record device_count, transferred_count and size_bytes.
When It Fails
The step fails immediately when no target devices are configured, when no file or more than one is selected, when both File and File by id (legacy) are set, when File is not a file reference, when Destination or Destination Filename contains a line break, another control character or a question mark, when Destination Filename has a directory part, and on a platform that cannot issue download links. Per target, it fails when the device has no management host, when the file is not one the run's organization may read or its path is ambiguous, when the platform cannot open files by repository and path, when the stored file's name contains a control character, a question mark or a directory part and no Destination Filename is set, when the platform has no HEGEMONY_API_EXTERNAL_URL, when the connection fails, when the target's transport cannot do the transfer, and when the target does not report a completed download (it could not reach the platform, the destination is full or does not exist, the transfer timed out). One failing target does not stop the others, but all must succeed for the step to succeed.