Showing results for 
Search instead for 
Did you mean: 
Historic F5 Account

Migrating to iSeries From Older Platforms: It’s About Time

Imagine this situation:  It’s a great day because the new F5 gear has come in and you can take advantage of the years of software and hardware advancements that have been included in the latest iSeries models. Decommissioning old gear is a great way to save space, power, and administrative costs. Applications can run faster, smoother, more reliably. The future is bright with the flexibility of TurboFlex for use case-oriented FPGA acceleration at line rate. There’s a great opportunity to clean up old configurations, getting rid of redundant virtual servers and profiles which were necessary on older gear due to performance limitations. Overall, change can be a really good time to update troubleshooting and shake down the whole incident resolution process.


There’s still a little bit of unease that comes with change. Moving applications to the new gear means migration. Migration can mean a large change window and the potential for regressions and having to back out the change. Memories of migrations past (and the accompanying all-nighters) cause shudders when scheduling a maintenance window. Copy and paste errors, incomplete certificate bundles, missing files, and incompatible interface numbering are all hallmarks of a long outage during a platform migration. 

What if there was a way to reduce the work and increase the accuracy of a migration? How much would you pay?

What about removing any doubts that migration could be done within a maintenance window? What about now?

Ladies and Gentlemen, allow me to introduce the platform-migrate flag, taking the load ucs command into new territory.  Best thing about it, if you’ve got TMOS 12.1.1 or later, it’s built right in! Amazing! (Not as amazing as winning the lottery, but go with it for the moment…)

What is ‘platform-migrate’? What does it do? Will it make a difference?

The full command we’re discussing is load ucs platform-migrate ’.

Here’s a quick overview of how easy it is to use the command once you’ve uploaded the source User Configuration Set (UCS) to the new platform. This screenshot is from a real-time video capture:


The configuration import took about 75 seconds (might have been faster without my slow typing). The UCS used was rather simple (only a few nodes, virtual servers, profiles), so it becomes a Your Mileage May Vary (YMMV) situation with larger configurations. However, the process is easily documented so administrators of all levels can easily follow the process and ensure it completes properly for each migration. This screenshot shows the migration of a configuration from a BIG-IP 8800 (D88) to a vCMP guest (Z101), demonstrating a leap-frog of two full generations of BIG-IP hardware in one quick keystroke.

The actual platform migration takes a very short time, but the upfront preparation, as with any activity related to upgrading or migrating, is the key to making this work smoothly.  There are several prerequisites to accomplish, but these are not any different than setting up a new device or vCMP guest

For those familiar with some of the other flags for the  load ucs  command,  platform-migrate  is a combination of the  no-license  and  no-platform-check  along with the capability to ignore the L2 configuration stanzas which may not import properly when moving from one platform to another. A not-so-secret secret: Some of the interface numbers are different between platforms, meaning the L2 configuration, at best, needs to be renumbered, though most commonly recreated.

Here’s a basic list of the things it does and does not do:

Included in platform-migrateNot included in platform-migrate

Functionality in ‘no-license’ and ‘no-platform-check’ (see: AskF5 K14096 and K16795)

Migration of unencrypted UCS files from 10.2.4+ and encrypted UCS files with user-set passphrases from 11.0+ to 12.1.1talk-26316

Ignorance of the L2 portion of the configuration, meaning differences in interface numbering don’t block configurations from loading

Automatic import and necessary conversion of configuration items such as:

  • Virtual Server information
  • Node information
  • Profile information
  • Any db variables that have been manually set
  • Certificate bundles
  • Monitors/EAV/Alerting configuration (alertd)
  • Remote Authentication Credentials (LDAP, etc.)

Migration of basic L2 configuration, as listed at K8240512, such as:

  • VLANs (both host and guest)
  • Management and Self-IP addresses
  • Config sync trust group information
  • Trunk group configuration

Migration of module configurations other than those for LTM and GTM

Migration of 10.2.4 configurations which are encrypted (because they are encrypted based on the appliance’s master key, not a user-specified passphrase)talk-26321

Reestablishing Device Trust relationships

vCMP Host configuration (there’s a different method for that, contained in K13132, though it restores everything, including guests which may or may not be wanted)

For platform-migrate to work well, there are a few prerequisites that must be accomplished on the destination system:

1) Prepare destination platform (provision vCMP if migrating to a vCMP guest)

2) Configure (and publish, for vCMP) VLANs

3 Ensure that Self-IP addresses and VLANs have the same name on the source and destination platforms

  • If using vCMP,  create guest and assign VLANs to guest

4) Copy UCS from source BIG-IP to destination platform

5) Run migration command on new platform

6) Make source BIG-IP stop serving traffic

7) Test virtuals and other config on destination platform

If you are migrating from other platforms, such as from an older appliance to a iSeries appliance or from an older appliance to a BIG-IP Virtual Edition (VE), the initial configuration is similar to the migration to a vCMP guest, listed above. You need to set up Self-IP addresses, a Management address, and have VLANs that are similarly named for the migration to work properly.  

The platform-migrate option is best used with configurations that are relatively straightforward but would be time-consuming to replicate by hand.  This can be a time saver with configurations that have hundreds of nodes, monitors, profiles, and VIPs.  Sure, you could recreate them to some degree by using a script such as “create ltm pool members” on DevCentral, but that doesn’t really do much for specific config items for each node. 

Summary: platform-migrate  saves time, period.

A Word On Encrypted UCS Files…

Since UCS files contain quite a bit of important information about a BIG-IP, such as user credentials, SSL Certificates, etc., it’s important to store them in as secure a manner as possible. UCS files can be encrypted with a passphrase which allows them to be stored on an accessible server for quick restorations or reversions to prior configurations. Because they contain all the files needed to recreate a BIG-IP, they’re very convenient.

Just one small item that must be considered: UCS files from before 11.0 cannot be moved from one machine to another if they contain SSL certificates generated on a BIG-IP. Makes platform migration a bit more difficult without a portable archive.

Why? Between 10.x and 11.0, a change was made as to the source of the encryption passphrase used to create SSL certificates. Before 11.0, the passphrase was set by the machine itself, using the machine-generated master key of the device. This solution was convenient in that you didn’t need to write down or remember the passphrase to any SSL certificates from those devices, since the machine itself was the passphrase, so to speak. Unfortunately, with that convenience came an inability to use the UCS on any other device.  After 11.0, you could specify your own passphrase, thereby removing some of the portability issues that came with encrypting UCS files.

Where does that leave the platform-migrate process? 

If you plan to migrate a device from 10.2.4 to 12.1.1+, you must create an unencrypted UCS archive to do so. This action is well-documented in the overview of UCS files available on It also involves having the source platform up and running to do so. If you are working with 11.0+, you can specify a user-defined passphrase when you export and import the UCS as documented in the overview of the platform-migrate capability.  

Are There Other Options To Migrate From One Platform To Another? 

There most certainly are other options for migration.  BIG-IP’s reputation as a “Swiss Army Knife” extends into the possible methods of moving from one platform to another. Similar to a Swiss Army Knife, each one of these methods is great for solving a specific problem or concern but may not cover off every instance or use case that may occur during a migration.  Here are some of the other methods possible:

Using a Single Configuration File (SCF) with Tarball of Additional Files: K13408

The SCF was originally developed as an easy way to present an overview of a configuration in one place, enabling easier auditing and change tracking using tools like diff and the like. It is entirely ASCII text and includes unencrypted hash blocks for device certificates as well as sections which have encrypted tokens, such as the password hashes for the different users on the device. As such, it’s not ideal for insecure storage, such as on unauthenticated file shares or FTP, but is great to use for simple search-and-replace operations to move configurations or configuration stanzas. With some scripting, SCF templates could be used to create new configurations almost dynamically.

  • Can be used to migrate from one platform to another; has nothing that links it to a specific device aside from hostnames
  • Configuration is laid out in a plain-text file which can be printed for offline review
  • Templates can be created by copying and pasting or merging stanzas into new configurations via scripting or other command-line text manipulation
  • Platform-to-Platform migration requires hand editing of the SCF and other files in the accompanying archive which opens the process to errors
  • Does not handle differences in L2 configuration, such as a different management IP address but instead will try to overwrite the running config instead, possibly causing IP address collisions if on the same VLAN as the source device
  • Device trust for sync groups will have to be rebuilt as with other methods
  • Doesn’t include SSL keys, license information, external monitors
  • Any device trust keys are included in the SCF in an unencrypted manner
  • Cannot be secured with a passphrase for encrypted storage

As is mentioned in the platform-migrate overview document, SCF files may be useful for simple configurations or where additional modules beyond LTM and DNS(ne é GTM) need to be migrated to the new platform. 

Loading a UCS From the Source Platform Directly on the New Platform: K13132

As mentioned above, the UCS was originally meant to be a great way to archive configurations and ensure that everything needed to restore a device is present in one place. Loading a UCS by itself onto a BIG-IP device without the platform-migrate flag does have the issue of interface numbering incompatibility when moving from one platform to another. 

  • Ensures all important files are collected in a single archive so they are not missing at startup after being loaded
  • File list can be modified to add customized files into the UCS archive that are not part of the standard manifest
  • Can move configuration from all modules including the supporting data stores and policies
  • Encrypted UCS files either need to have a user-defined passphrase or no passphrase for successful migration (changes between 10.x and 11.0, as noted above)
  • Requires hand editing of configuration files
  • Using the “no-license” flag (formerly known as the RMA option) requires console access because the appliance or guest must be restored to factory defaults before the new UCS can be applied (K16795)

 Using Config Sync with an Existing Device to Copy Configuration Items

There is a feature within the device service clustering and Device Group capabilities known as ConfigSync. When you’ve created a cluster of BIG-IPs, VEs, or vCMP guests to share the workload of an application, this is a great way to create high-availability across platforms of different speeds and capabilities. In the background, configuration changes to the clustered applications are replicated automatically, ensuring that all devices supporting that application are in lock-step and there won’t be any discrepancy between them as far as performance and capabilities are concerned. 0151T000003d6z5QAA.jpg

Synchronizing configuration objects you say? Wouldn’t that be a great way to replicate a configuration from one platform to another? Configurations are copied in the background and ensured that they are kept up to date from trusted sources – that sounds almost ideal!

Well, no. It really isn’t ideal.

ConfigSync has its limitations, and for good reason.  If all of the items in a UCS or SCF were synchronized to another device, the Management IP and its related settings, the hostname, and other information that is best used when its unique, would be overwritten, causing address collisions and general mayhem. 

Device trust between the hosts needs to be established for synchronization to work. This may be a manageable situation if you’re setting up 2 discrete devices with different hostnames, etc. where there could be a period where both platforms could run simultaneously without issue. If you’re decommissioning an old device and want to keep the hostname and IP addresses on a new device, you’l have a more difficult time, since the trust certificates are X.509 certificates with the hostname in them.

Aside from that mess, the list of things that, by design, don’t synchronize between devices is essentially the list of items you’d have to recreate on a new vCMP guest or other platform regardless of the method you used to migrate. Add on top of that the remaining need to import SSL certificates and other config files by hand which would be in the UCS or SCF and ConfigSync isn’t really the answer.

I’m not going to have a Pro and Con section here, because it’s not the right tool for platform migration. I did want to mention it in the interest of completeness and of avoiding a large mistake which could eat up a maintenance window quite quickly. There’s a link in the Resources section which has all the items that don’t get synchronized, if you’re interested.

Manually Entering Configuration 

  • It’s a great use of a weekend to bond with your co-workers, especially one that’s sunny and warm
  • The satisfaction of knowing you and your team typed in each and every node of the several thousand nodes and profiles that make up each of your data centers…
  • You find yourself not wanting it to end!

Seriously?  You wouldn’t be looking at any automation or other ways to make things faster if this was they way you wanted things to run. I’m not judging you, but someone else may be…

The Best Way To Migrate Configurations From Platform To Platform Is…?

The one that ticks as many boxes as it can. There is no single right way to do it, similar to programming in Perl (cue the Programming Language Flame Wars, episode 27 ). The most important part of any migration is preparation. Make some dry runs if possible and time the dry runs of the migrations for more accurate change window estimation. Regardless of how configuration and consolidation happens, the fact is that the new iSeries provides many advancements that make getting off of older devices is more appealing than ever. That, and they’re fast.   Really, really fast.


Replacing or migrating a BIG-IP or BIG-IQ hosted on a CSP (discusses considerations for moving a VE ...

Overview of vCMP configuration considerations

Device Trust Certificate overview

Overview of Single Configuration Files

Overview of User Configuration Sets

Creating LTM Pool Members in tmsh

Overview of platform-migrate




Version history
Last update:
‎08-Mar-2017 10:14
Updated by: