Manual Chapter : Migration of Configurations Between Different Platforms

Applies To:

  • BIG-IP LTM

    21.0.0, 17.5.1, 17.5.0, 17.1.3, 17.1.2, 17.1.1, 17.1.0, 17.0.0, 16.1.6, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 15.1.10, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0, 15.0.1, 15.0.0, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0, 14.0.1, 14.0.0

back-action BIG-IP System: Migrating Devices and Configurations Between Different Platforms

Updated Date: 04/28/2026

Migration of Configurations Between Different Platforms

The BIG-IP Migration Assistant is a desktop application to facilitate migrating BIG-IP configurations between different platforms. You can use the Migration Assistant when you have an existing BIG-IP instance and want to replace the current hardware with new hardware.

The Migration Assistant does not perform the actual migration; instead, migration is done by a destination BIG-IP instance. Configuration migrations depend on a user configuration set (UCS) file. UCS files contain all the data needed to back up and restore a BIG-IP instance, and are also used during platform migrations.

To use the Migration Assistant, the instance you want to migrate from (the source version) must be running BIG-IP version 11.1.0 or later, and the instance you want to migrate to (the target version) must be running BIG-IP version 12.1.3 or 13.1.0 and later.

  • Cannot migrate to or from a FIPS-enabled BIG-IP device.
  • Cannot migrate from a BIG-IP device running in the Appliance/Common Criteria mode.

Complete these tasks to migrate a source BIG-IP system configuration to a destination BIG-IP instance.

Install the Migration Assistant

Add a source device

Create a UCS archive

Migrate a configuration

Confirm the migration on the target device

You can install the Migration Assistant to facilitate migrating BIG-IP system configurations between different platforms.

  1. At the Releases tab for f5-big-ip-migration-assistant on github.com/f5devcentral, locate the version and platform you want to use to install the Migration Assistant:

    • For Mac OS X, open the .dmg file and drag the F5 BIG-IP Migration Assistant icon into the Applications folder.

    • For Linux, open the .deb file.

    • For Windows, open the .exe file.

      The F5 End-User License Agreement opens.

  2. Read the F5 End-User License Agreement, and then click I Accept.

    The BIG-IP Migration Assistant opens.

Before adding a BIG-IP source device, ensure that you install the BIG-IP Migration Assistant and gather the management IP address of the source device that you want to use.

You can add a source device to enable remote user configuration set (UCS) archive generation and platform migration.

Note: The source device must be BIG-IP version 12.1.0 or later.

  1. Open the BIG-IP Migration Assistant.

  2. On the left, click BIG-IP Devices, and then click the Add Device button at upper right.

  3. In the Device Address field, type the management IP address (host name or IP address) of the BIG-IP source device for which you want to store a reference.

  4. In the Admin User field, type a user name for connecting to the device.

  5. In the Admin Password field, type a password for connecting to the device.

  6. If the BIG-IP device is using a self-signed certificate, clear the Verify server identity check box.

  7. Click Save Device.

Before creating a user configuration set (UCS) archive, ensure that you added a source device and know the master key passphrase of the source device.

You can generate a UCS archive on a remote device, or select a UCS file as a source for platform migration.

  1. In the Migration Assistant, on the left, click UCS Archives, and then click the New Archive button at upper right.

  2. Based on your target device version, specify whether you are generating or selecting a UCS:

    1. For a BIG-IP version 12.1.0 or later target device, click Generate UCS, and go to step 3.

    2. For a BIG-IP version 11.1.0 – 11.6.x or 12.0.0 target device, click Select UCS, and skip to step 4.

  3. To generate and import a UCS file for a BIG-IP target device version 12.1.0 or later:

    1. From the BIG-IP Device list, select the source device the UCS file will be generated from.

    2. In the Archive Name field, type a file name for the UCS archive.

    3. For the Master Key list, either provide or reset the passphrase: To enter a master key passphrase, select Master key passphrase and type the passphrase in the field, or to reset the master key, select Reset master key and type a new master key passphrase.

    4. Click Generate Archive.

  4. To select a previously generated UCS archive file for a BIG-IP target device version 11.1.0 – 11.6.x, or 12.0.0:

    1. For the UCS Archive setting, click Choose File, and then select a UCS archive file.

      Note: You must use a previously generated archive file because Migration Assistant cannot generate UCS files for any BIG-IP system earlier than version 12.1.0. For more information about UCS files, refer to K4423: Overview of UCS archives on support.f5.com.

    2. In the Admin User field, type the administrative user name for the device that the UCS was generated from.

    3. In the Admin Password field, type the administrative password for the device that the UCS was generated from.

      Note: The user name and password are needed to maintain the connection to the new device when migrating the UCS.

    4. In the Master Key field, type the passphrase for the UCS.

    5. Click Select Archive.

Before you migrate a configuration, ensure that you have created a user configuration set (UCS) Archive. You also need to gather the name and management IP address of the target device that you want to use.

You can perform a migration to copy the BIG-IP system configuration from one BIG-IP platform to another.

Important: If you are migrating to a vCMP guest, you must have VLANs already configured in the host to support incoming configuration.

  1. Power down the source BIG-IP device.

  2. Boot the target device.

  3. Change the management IP address on the target device so it has the same address as the source device.

  4. On the Migration Assistant, on the left click Platform Migration, and then click the New Migration button at upper right.

  5. From the Source Archive list, select the UCS archive migration source previously created.

  6. From the Target Device list, select the target device you want to migrate to.

    Note: You can only migrate UCS files to devices running BIG-IP version 12.1.3 and later, or version 13.1.0 and later.

  7. Click Begin Migration.

    After a successful migration, the progress indicator migration row will no longer display.

After the migration is complete, you can take additional steps to confirm the migration on the target device.

  1. Log in to the BIG-IP target device to verify all configuration changes are complete.

    Note: Depending on your network configuration, you may need to force the old device offline.

  2. If necessary, reconfigure VLANs and interface mappings, or configuration element(s).

    Note: For a list of configuration elements, refer to K82540512: Overview of the UCS archive platform-migrate option on support.f5.com.

  3. Perform traffic testing on the target device to verify that it is working properly.

When uploading a user configuration set (UCS) file into the Migration Assistant, you see an Invalid UCS error message.

This error occurs under the following conditions:

  • The UCS file is encrypted at generation time.
  • The UCS file is damaged during download from the source BIG-IP device.

For either condition, go back to your source BIG-IP device and generate a new, unencrypted UCS file. Make sure to include the private keys if you want your target BIG-IP device to be fully functional.

Generally when this occurs, the destination BIG-IP device is unable to execute the tmsh command successfully. The ucs load command creates a backup of the original configuration prior to running the migration, which can be used to restore the BIG-IP device configuration if needed.

The Migration Assistant will show the output of the ucs load command on the BIG-IP device, which might help you to correct issues before you attempt to migrate again.

For more information about limitations of the platform-migrate option, which also affects the Migration Assistant, refer to K82540512: Overview of the UCS archive platform-migrate option on support.f5.com.