This knowledge base has moved to the documentation site. Please visit the knowledge base here for the most up to date content. This site is no longer maintained.

Configuration File Migration Script


If you are upgrading a switch from Cumulus Linux 2.5.6 or later in the 2.y.z release train to Cumulus 3.y.z, you can use the Configuration File Migration Script with the --backup option to create a backup archive of configuration files from the previous release train, copy them off the box, then install them on the new version switch.

Warning: Configuration files in Cumulus Linux 2.5.6+ typically migrate to version 3.y.z without any problems; however, there are certain known issues:

  • Never migrate certain configuration files between versions or while replacing hardware. See Files to Never Migrate between Versions or Switches in the Cumulus Linux User Guide.
  • Do not migrate /etc/passwd and /etc/shadow to the new version directly. The examples and the Ansible script included with Configuration File Migration Script explicitly excludes these two files from the backup archive. You must change the default password for the cumulus user and add any locally created users to the new installation after the upgrade completes.
  • You must completely upgrade /etc/apt/sources.list with a new 3.x repository and repository structure. Remove repositories from Cumulus Linux 2.5.6+. If there are any custom repositories on the switch, you must migrate them into the new sources.list file or the sources.d/ directory.
  • Version 2.5.6+ configurations are not guaranteed to work in Cumulus Linux 3.y.z. Be sure to test the restoration and proper operation of the Cumulus Linux 2.5.6+ configuration in Cumulus Linux 3.y.z on a non-production switch or in a Cumulus VX image; every deployment is unique.

The following example excludes /etc/apt, /etc/passwd, and /etc/shadow from the backup archive.

  1. Back up the files from the previous release train (for example 2.5.6).
    # Make a temp dir
    loc=$(mktemp -d)
    # Create a backup archive to the temp dir
    sudo ./config_file_changes --backup --backup_dir $loc --exclude /etc/apt,/etc/passwd,/etc/shadow
    # Copy the archive and log file to an external server
    sudo scp -r $loc/* user@my_external_server:.
  2. Optional: Use the Ansible playbook included with the Configuration File Migration script to automate Cumulus Linux switch backup. The playbook creates a backup archive of the Cumulus Linux switch configuration files and retrieves them to a central server, automating backup for all deployed Cumulus Linux 2.5.6+ switches. This is a quick start to setting up automated configuration and control for your deployment.

  3. Install Cumulus Linux 3.x onto the switch using ONIE.

  4. Reinstall the files from the config file archive to the newly installed switch.

    # On the switch, copy the config file archive back from the server:
    scp user@my_external_server:PATH/SWITCHNAME-config-archive-DATE_TIME.tar.gz .
    # Untar the archive to the root of the box
    sudo tar -C / -xvf SWITCHNAME-config-archive-DATE_TIME.tar.gz


This support portal has moved

Cumulus Networks is now part of the NVIDIA Networking Business Unit! The NVIDIA Cumulus Global Support Services (GSS) team has merged its operations with the NVIDIA Mellanox support services team.

You can access NVIDIA Cumulus support content from the Mellanox support portal.

You open and update new cases on the Mellanox support portal. Any previous cases that have been closed have been migrated to the Mellanox support portal.

Cases that are still open on the Cumulus portal will continue to be managed on the Cumulus portal. Once these cases close, they will be moved to the Mellanox support portal.

Powered by Zendesk