Welcome to the F5 BIG-IP Migration Assistant

Setup instructions

What is it?

The F5® BIG-IP® Migration Assistant is a tool freely distributed by F5 to facilitate migrating BIG-IP configurations between different platforms. Migration Assistant is a downloadable desktop application that coordinates the logistics required to migrate a BIG-IP configuration from one BIG-IP instance to another.

Why do I need it?

You can use Migration Assistant when you have an existing BIG-IP instance and you want to replace the current hardware with new hardware.

What does it do?

Migration Assistant does not perform the actual migration; the destination BIG-IP instance performs the actual migration. 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.

For more information, refer to K4423: Overview of UCS archives and K82540512: Overview of the UCS archive platform-migrate option.

You can configure multiple UCS files and destination BIG-IP instances, and you can run multiple migrations simultaneously.

Migration Assistant performs the following tasks:
  1. Pre-migration validation checks
  2. UCS generation (for source instance running 12.1.0 and later)
  3. Storing and managing UCS files
  4. Updating the master key on the source and destination device, if necessary
  5. Post-migration validation checks

How does it work?

F5 MA Diagram

Migration Assistant manages the logistics of a configuration migration. Migration Assistant either generates or accepts a UCS file from you, prompts you for a destination BIG-IP instance, and manages the migration. The destination BIG-IP instance has a tmsh command that performs the migration from a UCS to a running system. Migration Assistant uses this tmsh command to accomplish the migration.

Migration Assistant prompts you to enter a source BIG-IP (or upload a UCS file), the master key password, and destination BIG-IP instance. Once the tool obtains this information, it allows you to migrate the source BIG-IP configuration to the destination BIG-IP instance.


To use Migration Assistant, the instance you want to migrate from must be running 11.1.0 and later, and the instance you want to migrate to must be running 12.1.3 or 13.1.0 and later:

Source versions supported Target versions supported Notes
9.x, 10.x, 11.0.0 Not supported Not supported due to older versions lacking capabilities required for a migration
11.1.0 - 11.6.x 12.1.3 and 13.1.0 You must generate and supply the UCS file manually
12.1.0 and later 12.1.3 and 13.1.0 Migration Assistant generates UCS files
  • You cannot use this tool to migrate to or from a FIPS-enabled BIG-IP device.
  • You cannot use this tool to migrate from a BIG-IP device running in Appliance/Common Criteria mode.
  • If migrating into a vCMP guest, you must configure any needed VLANs in the host prior to attempting to migrate.

Where do I obtain it?

Download the appropriate installer file from the latest version of Migration Assistant, hosted on GitHub.

What can go wrong?

In some cases, Migration Assistant will not be able to successfully migrate a configuration from the source BIG-IP device to the destination BIG-IP device. 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 if needed.

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

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

For questions or further discussion please leave your comments below. Enjoy!