UCS Migration Workflow for F5OS BIG-IP Platforms

Overview

You can migrate UCS configuration files from iSeries and VIPRION BIG-IP systems to F5OS BIG-IP platforms using the platform-migrate option of the tmsh load sys ucs command. Beginning in version 21.1.0, the validate (dry run) capability enhances this workflow by checking UCS compatibility before migration and generating a report of unsupported or modified configuration elements.

Before You Begin

Before you load a UCS file on the target system, complete the following steps:

1. Deploy a BIG-IP Tenant
   Ensure that a BIG-IP tenant is deployed on the F5OS system. Licensing is inherited from the host system; no separate licensing is required for the BIG-IP tenant.

2. Set Interface and Network Settings
   Configure the required interface and network settings on both the F5OS platform and within the BIG-IP tenant. Refer to Initial Setup Within the Chassis Partition.

3. Move the UCS File
   Copy the UCS file created from the source BIG-IP system to the /var/local/ucs directory on the target system.

Migration Workflow

To migrate a UCS file to an F5OS BIG-IP system, follow these steps in sequence:

1. Validate the UCS file (dry run).
2. Review the validation report.
3. Load the UCS file using platform-migrate.
4. Verify system status.
5. Perform post-migration setup and

Validating UCS Compatibility (Dry Run)

Use the validate option with platform-migrate to check configuration compatibility before loading the UCS file.

Procedure

1. Log in to the TMOS Shell (tmsh):

   Copy

   
   tmsh

2. Run the validate command:

 load sys ucs <filename> platform-migrate validate

Result

• The system analyses the UCS file for platform compatibility.

• Unsupported configurations are identified and excluded.

• A validation log is generated at:

/var/log/platform_migrate_validate.log

• Warnings for removed or unsupported configurations are displayed.

Reviewing the Validation Report

After validation, review the generated log file to understand configuration changes.

Procedure:

1. Open the Validation Log File: Use JSON formatting for easier readability, such as jq:

   Copy

   
   cat /var/log/platform_migrate_validate.log | jq

Example Output:

{
  "ignored_properties": [
    {
      "property_removed": [
        {
          "text": "mode stp",
          "property": "mode"
        }
      ],
      "key": "net stp-globals"
    },
    {
      "property_removed": [
        {
          "text": "failsafe-action failover-restart-tm",
          "property": "failsafe-action"
        },
        {
          "text": "mgmt-dhcp dhcpv6",
          "property": "mgmt-dhcp"
        }
      ],
      "key": "sys global-settings"
    },
    {
      "property_removed": [
        {
          "text": "    trunks {\n        trunk1 {\n            minimum-threshold 1\n            weight 20\n        }\n    }\n",
          "property": "trunks"
        }
      ],
      "key": "sys ha-group test_ha"
    },
    {
      "property_removed": [
        {
          "text": "    network-failover disabled\n",
          "property": "network-failover"
        }
      ],
      "key": "cm device-group /Common/dg-serial-failover"
    }
  ],
  "ucs_name": "example-migration.ucs",
  "ignored_objects": [
    {
      "block_lines": [
        "net trunk trunk1 {",
        "    interfaces {",
        "        3.2",
        "        3.3",
        "    }",
        "    lacp enabled",
        "}"
      ],
      "key": "net trunk trunk1"
    }
  ],
  "date": "Mar 18 03:29:53",
  "result": "success"
}

2. Review the following sections in the output:

• ignored_properties - Properties removed from configuration objects
• ignored_objects - Entire configuration blocks removed
• ucs_name, date, result - Metadata about the validation process

Result

The report provides a detailed summary of:

• Unsupported features (for example, STP, LACP, trunk references)
• Removed HA group dependencies
• Modified global or network settings

Loading the UCS Configuration

After reviewing the validation results, load the UCS file onto the target system.

Procedure:

1. Log in to tmsh:

tmsh

2. Set the master key using the same password used on the source device:

modify sys crypto master-key prompt-for-password

3. Save the configuration:

save sys config

4. Load the UCS file using platform-migrate:

load sys ucs <filename> platform-migrate

Result

• Unsupported platform-dependent objects are ignored.
• A success message confirms migration completion.

Verifying System Status

Check the system’s operational state after loading the UCS file.

Procedure:

1. Run the MCP Status Check

tmsh show sys mcp-state

2. Review the output.

Result

If successful:

• Running Phase: running
• Last Configuration Load Status: full-config-load-succeeded

If unsuccessful:

• Running Phase: platform
• Load Status: May display different failure messages depending on the issue
  (for example, high-config-load-failed or base-config-load-failed)

Post-migration setup and validation

If the system is not fully operational after migration, update the configuration.

Procedure:

1. Review Migration Output

Review the output of the tmsh load sys ucs platform-migrate command to understand how the configuration was interpreted during migration. The output may include informational messages about configuration adjustments, such as deprecated or unsupported objects being removed or modified.

For example:

Replacing global-settings mgmt-dhcp value with: sys global-settings {
    mgmt-dhcp enabled
}

 Reloading License and configuration - this may take a few minutes...
Warnings were generated:
    Compliance '/Common/gtp_unknown_tunnel_id' is deprecated and removed from '/Common/protocol_inspection'.
    Compliance '/Common/smtp_command_length_overflow' is deprecated and removed from '/Common/protocol_inspection'.

Platform migrate loaded successfully. Saving configuration.
/var/local/ucs/config.ucs is loaded.

2. Update Configuration for Platform Migration Fixups:
   Modify and address the reported issues in the configuration files. Common actions include:

• Reassign VLANs to appropriate interfaces.
• Reconfigure trunk or LAG settings.
• Update HA group configurations.
• Reconfigure management IP or failover settings.

After updating the configuration using tmsh commands, the changes are applied to the running configuration. Once all updates are complete, save the running configuration to persist the changes:

tmsh save sys config

Troubleshooting

If errors occur during the UCS platform-migrate process, use the following steps to identify and resolve the issue.

Identify the Issue Review the output of the tmsh load sys config platform-migrate command.

The output may provide details such as:

• Configuration file name (for example, /config/bigip_base.conf)
• Line number where the error occurred
• Failure reason (for example, syntax error or unexpected argument)

Example:

Syntax Error:(/config/bigip_base.conf at line: 438) "}" unexpected argument

You will also see a load error:

Configuration loading error: base-config-load-failed
ERROR: UCS installation failed.

For additional details, review the log file:

/var/log/ltm

Resolve the Issue

Open the identified configuration file and navigate to the specified line number.

Modify the configuration based on the reported error. For example:

• Correct syntax errors (missing or extra brackets)
• Remove unsupported or deprecated properties
• Fix invalid arguments

Save the changes.

Verify the Configuration

After updating the configuration, verify that the issue is resolved:

tmsh load sys config platform-migrate verify

The command validates the configuration.

Result

• If successful, no errors are displayed.
• Warnings may appear for deprecated features.

Apply the Configuration

After successful verification, apply the updated configuration:

tmsh load sys config platform-migrate

Result

The configuration loads without errors.

Update Configuration for Platform Migration

Post-migration setup and validation

Summary

The platform-migrate workflow with validate (dry run) provides a structured approach to migrating UCS files. By validating configurations before migration and reviewing detailed reports, you can identify unsupported elements, resolve issues, and ensure a successful transition to F5OS BIG-IP systems.