Manual Chapter : Migration of Configurations Between Different Platforms

Applies To:

Show Versions Show Versions


  • 17.1.0, 17.0.0, 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
Manual Chapter

Migration of Configurations Between Different Platforms

About Migrating BIG-IP configurations between different platforms

What is the BIG-IP Migration Assistant?

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.

Supported source and target versions

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.

Migration Assistant considerations

  • 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.

Task list

Install the Migration Assistant
Add a source device
Create a UCS archive
Migrate a configuration
Confirm the migration on the target device

Install the Migration Assistant

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
    , locate the version and platform you want to use to install the Migration Assistant:
    • For Mac OS X, open the
      file and drag the F5 BIG-IP Migration Assistant icon into the Applications folder.
    • For Linux, open the
    • For Windows, open the
      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.

Adding a source device

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.
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

Create a UCS archive

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.
      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
    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.
      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

Migrate a configuration

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.
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.
    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.

Confirm the migration on the target device

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.
    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).
    For a list of configuration elements, refer to K82540512:
    Overview of the UCS archive platform-migrate option
  3. Perform traffic testing on the target device to verify that it is working properly.

Troubleshoot migration issues with the Migration Assistant

Invalid UCS

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.

Unsuccessful migration

Generally when this occurs, the destination BIG-IP device is unable to execute the
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