HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In

Switch Firmware Distribution Script

Python workflow for switch-to-switch image distribution

This workflow updates the firmware across a mass amount of switches using the switch-to-switch download feature that is enabled through the firmware-site-distribution API. The source code for this script can be found here.

How it Works

This script uses the firmware-site-distribution configuration on a switch to act as a remote server. This enables switch to switch firmware upgrades using REST APIs.

This script works by taking in an input CSV with information for a host switch and client switches to be upgraded. Any switch can only support upgrading two clients at a time using this API. However, this script utilizes threading to run this process concurrently across multiple switches to upgrade several switches at a time. Each switch upgrade is performed and handled by an individual thread. As the client switches complete the upgrade process they are then enabled as host switches via REST API and added to a pool of available hosts. This cascading effect will exponentially increase the speed of the upgrade process the more switches that are provided as input. Once all switches have been upgraded, the remote endpoints are turned off and sessions are logged out.


  • Faster than than traditional means of mass upgrade, such as using a remote TFTP server sequentially to switches
  • Efficiently uses switches that have completed upgrading to be enabled as hosts
  • Saves multitudes of network WAN bandwidth
  • Ideal for Day 0 network infrastructure setups or site upgrades


Switches must be of the same platform and on the same network to use this script.


  1. Upgrade the host switch manually with the image to be used for re-imaging
  2. Create an input CSV with the all the switch information detailed below
  3. Copy the code from instructions here
  4. Install the requirements
  5. Once complete, the script is ready to be ran

CSV Format

Required information for each switch includes external IP, internal IP, username, password. The host switch information must be on the first line of the CSV. If the switches do not have an external IP (via NAT translator for example) fill in the internal IP for both cells.

Example CSV,,host_user,host_pass,,client_user,client_pass,,client_user,client_pass


The first line of the input CSV must be the host switch.

CLI Arguments

A variety of CLI Arguments required and optional are available for additional functionality.
usage: fimware-site-dist.py [-h] [-vrf VRF] [-r] [-cred] [-d D] [-s S] input threads

Positional Arguments

  1. Input - Required
    1. This argument takes a relative filepath to a CSV file containing input information
  2. Threads - Required
    1. Designate the number of threads for python to utilize for the multithreading portion of the script.
    2. No more upgrades can execute at once greater than the number of threads. More threads means more concurrent switch upgrades can execute at a time.
    3. The more threads you include the faster the script will complete. Threads can also be used to limit and control the number of upgrades happening concurrently if this use case is applicable to your particular network.

Optional Arguments

  1. -vrf {vrf name}
    1. This will set the VRF to be used for the upgrade process.
    2. Common inputs are 'mgmt' or 'default'.
    3. Defaults to 'default'.
  2. -r
    1. If this option is set all switches will be rebooted after re-imaging is complete.
    2. This feature is not currently compatible with switches configured in a stack.
  3. -cred
    1. If this option is set the user will be prompted to enter username and password credentials to be used for ALL switches.
  4. -d {destination}
    1. This argument designates the firmware image location to be upgraded.
    2. Valid options are 'primary' and 'secondary'
    3. Defaults to 'secondary.
  5. -s {source}
    1. This argument designates the source firmware image location to download from.
    2. Valid options are 'primary' and 'secondary'.
    3. Defaults to 'primary'.

Executing the workflow

To run the workflow simply run the following command:

python firmware-site-distribution.py {inputpath.csv} {threads}

Please reference the above section on CLI Arguments for full usage of executing with commands on the CLI. Most common usage will specify image source and destination for upgrade. This would look as follows:

python firmware-site-distribution.py {inputpath.csv} {threads} -d primary -s primary


The most common errors for the script are generally input related. Here are a few things to check first when troubleshooting:

  1. If the switches are logging in but failing to re-image check the input file. The input file must include two fields for switch IP address even if there is only one. In this case please use the same IP for both fields. Refer to the CSV Format section.
  2. If the switches are logging in but failing to re-image, check the that the correct VRF argument is being passed in the CLI. Refer to the -vrf section of Optional Arguments.
  3. If the switches are failing to login, make sure that the switches are reachable from the environment you are attempting to execute the script from.

What’s Next

Check out the full code for this documentation!