Topic This article applies to BIG-IP 10.x. For information about other versions, refer to the following articles:

K13132: Backing up and restoring BIG-IP configuration files (11.x - 13.x) K3499: Backing up and restoring BIG-IP configuration files (9.x) This article describes how to back up and restore your BIG-IP 10.x configuration data using a user configuration set (UCS) configuration archive. The UCS archive, by default, contains all files required to restore your current configuration to a new system, including configuration files, the product license, user accounts, and Secure Socket Layer (SSL) certificate/key pairs.

Note: For more information about UCS archive files, refer to K4423: Overview of UCS archives.

Backing up your BIG-IP system configuration

Prerequisites for backing up configuration data Backing up configuration data using the Configuration utility Backing up configuration data from the command line using the bigpipe utility Backing up configuration data from the command line using the tmsh utility Restoring your BIG-IP system configuration

Prerequisites for restoring configuration data Restoring configuration data using the Configuration utility Restoring configuration data from the command line using the bigpipe utility Restoring configuration data from the command line using the tmsh utility Restoring configuration data on a replacement RMA unit (BIG-IP 10.1.0 or later) Restoring UCS archives obtained from an earlier software version onto BIG-IP systems running later software versions Note: The F5 Enterprise Manager product facilitates the configuration management process for multiple systems. For more information, refer to the Enterprise Manager product documentation.

Prerequisites for backing up configuration data

UCS archive files

Review K4423: Overview of UCS archives to gain a better understanding of the UCS archive and the data it contains.

If your system configuration has been customized to reference files that are not included in the default BIG-IP installation, refer to K4422: Viewing and modifying the files that are configured for inclusion in a UCS archive.

Secure Storage

Make sure that you have access to a secure location for storage of your UCS archive files. A typical UCS archive contains user accounts, passwords, critical system files, and SSL private keys. However, you can explicitly exclude SSL private keys from a UCS archive during the backup process. It is important to store the backup UCS archives, which contain sensitive information, in a secure location. For instructions, refer to K175: Transferring files to or from an F5 system.

Backing up configuration data using the Configuration utility

Log in to the Configuration utility. Click System. Click Archives. From the Archives page, click Create. In the File Name field, type a name for the file. By default, the BIG-IP system saves the UCS archive file in the /var/local/ucs directory. If you do not include an extension, the system appends the .ucs extension to the file. Important: You must use a unique filename. If a file by the same name already exists, the archive file is not created, and the system displays the following warning:

The file already exists on the system

Note: F5 recommends that you include the BIG-IP hostname and current timestamp as part of the filename for ease of identification.

Note: If you specify a full path to the archive file, the file is saved to the specified location. If you do not include a path, the file is saved to the default archive directory, /var/local/ucs. Archives located in a directory other than the default do not appear in the list of available archives when you use the Configuration utility to create or restore a UCS archive.

Optional: If you want to encrypt the UCS archive file, select Enabled from the Encryption menu. Note: If you enable encryption, enter a passphrase to protect the encrypted UCS archive file. You must supply this passphrase to restore the encrypted UCS archive.

Optional: If you want to exclude SSL private keys from the UCS archive, select Exclude from the Private Keys menu. Note: In BIG-IP 10.1.0, the Exclude option does not exclude the private keys when backing up a UCS archive. F5 tracked this issue as ID 243415, and fixed it in BIG-IP 10.2.0.

Click Finished. A status screen displays.

Click OK. Copy the .ucs file to another system. Note: For specific instructions about copying files to and from the BIG-IP system, refer to K175: Transferring files to or from an F5 system.

Important: A typical UCS archive contains user accounts, passwords, critical system files, and SSL private keys. However, you can explicitly exclude SSL private keys from a UCS archive during the backup process. It is important to store the backup UCS archives in an environment that is as secure as where you store your private keys.

Backing up configuration data from the command line using the bigpipe utility

Log in to the command line. Save the configuration into a UCS archive by typing the following command: bigpipe config save

Replace with the filename of your choice.

Note: You can exclude SSL private keys from a UCS archive by adding the support option when running the bigpipe config save command. For example, bigpipe config support save . In BIG-IP 10.1.0, the support option does not exclude SSL private keys when backing up a UCS archive. F5 tracked this issue as ID 243415, and fixed it in BIG-IP 10.2.0.

Alternatively, to create an encrypted UCS archive from the command line, use the following command syntax:

bigpipe config save

Replace with a password to protect the archive file. You must supply this passphrase to restore the encrypted UCS archive.

By default, the BIG-IP system saves the UCS archive file in the /var/local/ucs directory. If you do not include an extension, the system appends the .ucs extension to the file.

Important: If a file by the same name already exists, the system overwrites the existing file without warning.

Note: F5 recommends that you include the BIG-IP hostname and current timestamp as part of the filename for ease of identification.

Note: In both commands, you can specify a full path to the archive file, and the archive file will be saved to the specified location. If you do not include a path, the file is saved to the default archive directory, /var/local/ucs. Archives located in a directory other than the default do not appear in the list of available archives when you use the Configuration utility to restore a configuration.

Copy the .ucs file to another system. Note: For specific instructions about copying files to and from the BIG-IP system, refer to K175: Transferring files to or from an F5 system.

Important: A typical UCS archive contains user accounts, passwords, critical system files, and SSL private keys. However, you can explicitly exclude SSL private keys from a UCS archive during the backup process. It is important to store the backup UCS archives in an environment that is as secure as where you store your private keys.

Note: The backup process described in this section may be automated by using a cron job and secure shell (SSH) login without password protection to a remote system. For sample scripts and instructions, refer to the F5 DevCentral codeshare: BIG-IP Backup Scripts, LTM Backup Shell Script. A separate login is required to access this content.

Backing up configuration data from the command line using the tmsh utility

To back up the BIG-IP system configuration using the Traffic Management Shell (tmsh) utility, perform the procedure appropriate for your BIG-IP version:

BIG-IP 10.1.0 and later

Log in to the tmsh utility by typing the following command: tmsh

Create the UCS archive file by typing the following command: save /sys ucs <path/to/UCS>

In this command, note the following:

<path/to/UCS> refers to the full path of the UCS archive file (for example, /var/tmp/MyUCS.ucs) By default, the BIG-IP system saves the UCS archive file with a .ucs extension if you do not include the extension in the filename. You can also specify a full path to the archive file, and the archive file saves to the specified location. If you do not include a path, the file is saved to the default archive directory, /var/local/ucs. Archives located in a directory other than the default do not appear in the list of available archives when you use the list /sys ucs command in the tmsh utility. F5 recommends that you include the BIG-IP hostname and current timestamp as part of the filename for ease of identification.

To exclude SSL private keys from the UCS archive, type the following command:

save /sys ucs <path/to/UCS> no-private-key

In this command, note the following:

<path/to/UCS> refers to the full path to the UCS archive file (for example, /var/tmp/MyUCS.ucs). Note: In BIG-IP 10.1.0 the no-private-key option does not exclude SSL private keys when backing up a UCS archive. F5 tracked this issue as ID 243415, and fixed it in BIG-IP 10.2.0.

To encrypt the UCS archive with a passphrase, type the following command:

save /sys ucs <path/to/UCS> passphrase

In this command, note the following:

<path/to/UCS> refers to the full path to the UCS archive file (for example, /var/tmp/MyUCS.ucs). refers to the passphrase you want to use to encrypt the UCS archive. Copy the .ucs file to another system. Note: For specific instructions about copying files to and from the BIG-IP system, refer to K175: Transferring files to or from an F5 system.

Important: A typical UCS archive contains user accounts, passwords, critical system files, and SSL private keys. However, you can explicitly exclude SSL private keys from a UCS archive during the backup process. It is important to store the backup UCS archives in an environment that is as secure as where you store your private keys.

BIG-IP 10.0.x

From the BIG-IP command line, prefix all of the commands in the Backing up configuration data from the command line using the bigpipe utility procedure with the following string:

tmsh run

For example, the following command creates a UCS archive file named BIG-IP-6400B_20April2010:

tmsh run bigpipe config save BIG-IP-6400B_20April2010

From the tmshell prompt, prefix all of the commands in the Backing up configuration data from the command line using the bigpipe utility procedure with the following string:

run

For example, the following command creates a UCS archive file named BIG-IP-6400B_20April2010 from the tmshell prompt:

run bigpipe config save BIG-IP-6400B_20April2010

Prerequisites for restoring configuration data

BIG-IP software version

The BIG-IP system must be running the same version of BIG-IP software from which the UCS archive was created.

To upgrade, refer to the release notes for the version to which you want to upgrade.

To downgrade versions, you must perform a clean installation of version 10.x software, as detailed in K10819: Performing a clean installation of BIG-IP version 10.x or Enterprise Manager 2.x.

After new system software has been installed, reboot the system, connect to the serial port, and then type the config command to configure the system with a management IP address.

Licensing

The BIG-IP license is associated with a specific hardware serial number. The UCS archive contains the license of the file from which the configuration was saved. To successfully install a UCS configuration file on a BIG-IP system, you must perform one of the following actions:

Restore the UCS configuration to the same system from which it was saved. Have the license associated with the serial number of a new system. To do so, contact F5 Technical Support. Note: F5 Technical Support will associate a license file with a new serial number only on an as-needed basis, in the event of a Return Materials Authorization (RMA).

Relicense the BIG-IP system after restoring the UCS archive. Save the license file prior to restoring the configuration from another system, then copy the license file back. Install the UCS using the tmsh utility rma option (version 10.1 or later). Important: If you use a different license than the one contained in a restored UCS archive, the replacement license must include authorization for the same options and add-on modules, such as BIG-IP WebAccelerator or BIG-IP ASM. If you attempt to restore a UCS configuration that references an unlicensed module, the BIG-IP system does not restore the UCS archive.

Note: For information about UCS installation and licensing, refer to K10245: BIG-IP UCS installation and licensing behavior and K7752: Licensing the BIG-IP system.

Important: If you are restoring the backup on a different device than the system on which the backup was created, such as an RMA system, you should follow the procedure documented in the Restoring configuration data on a replacement RMA unit section.

UCS files

If necessary, copy the UCS archive file you want to restore to the BIG-IP file system.

Note: For specific instructions about copying files to and from the BIG-IP system, refer to K175: Transferring files to or from an F5 system.

Note: Restoring a UCS archive only overwrites files that have a copy of those files stored in the UCS archive. The system does not delete or overwrite existing files that are not archived within the UCS archive. For example, if you create a UCS archive, and then you create a new file called /config/test.txt, the system restores the previous UCS archive, and the /config/test.txt file remains on the BIG-IP system.

Verify hostname

The UCS restore operation restores the full configuration only if the hostname of the target system matches the hostname on which the UCS archive was created. If the hostname does not match, only the shared configuration is restored.

You can set the hostname of the BIG-IP system on the System > Platform screen of the Configuration utility, or by using the bigpipe system hostname command at the BIG-IP command line.

Base configuration

When restoring only the shared portion of a UCS archive, the base configuration of the target system must include all Virtual Local Area Networks (VLANs) and other objects referenced by name in the shared configuration. If you are restoring the archive on a newly-installed system, use the Configuration utility's Setup Wizard to configure the base configuration to match the configuration you are restoring.

SSL private keys with passphrases

When restoring on a new system, a UCS archive that includes SSL private keys with encrypted passphrases cannot be decrypted by the new system. This format is an intentional security measure.

When replacing one system of a failover pair, instead of restoring the configuration by installing the UCS archive, F5 recommends that you configure basic networking on the replacement unit and synchronize the configuration from its peer. Because the master key is shared between units of a redundant pair, the configuration synchronization process synchronizes the original master key to the newly-installed device.

If you cannot synchronize the original master key to the new system from its peer, but you know the original unencrypted passphrases, you can install the UCS file to restore the configuration, modify the affected SSL profiles to replace the encrypted passphrases with unencrypted versions, and save the resulting configuration.

GTM consideration

For a BIG-IP GTM RMA unit that is licensed and provisioned with the GTM module and the DNSSEC feature, refer to K13542: Restoring configuration data to a BIG-IP GTM RMA unit.

For BIG-IP GTM 10.1.0 through 10.2.4, the BIG-IP GTM system updates the timestamp of the restored wideip.conf file during the UCS archive restoration process. As a result, the restored BIG-IP GTM configuration will overwrite the configuration on the remaining systems in the same synchronization group. For information about preventing this behavior, refer to K12679: The gtmparse utility now updates the timestamp of the wideip.conf file before reloading the configuration from disk or UCS archive.

ASM consideration

If you are restoring a UCS file that is licensed and provisioned with the BIG-IP ASM module, you may need to provision the system for BIG-IP ASM before loading the UCS file. For information, refer to K13945: The BIG-IP ASM MySQL database is not installed completely if the BIG-IP ASM is not provisioned when the UCS is loaded.

Other considerations

If you are restoring a UCS file on a BIG-IP unit that is part of a redundant pair, refer to K8086: Replacing a BIG-IP system in a redundant pair without interrupting service.

Restoring configuration data using the Configuration utility

If you are restoring a UCS archive on a BIG-IP 1500, 3400, 4100, 6400, 6800, or 8400 hardware platform, other than the system from which the backup was created, such as when replacing an RMA system, you must perform the procedure in the Restoring configuration data from the command line using the bigpipe utility section to restore the configuration.

To restore a configuration in a UCS archive using the Configuration utility, review the additional prerequisites described in the Prerequisites for restoring configuration data section before performing the following procedure:

Log in to the Configuration utility. Click System. Click Archives. If you are restoring a backup containing SSL private key passphrases after reinstalling the operating system, replacing a failed system with a new system, or otherwise moving an existing configuration to a new system, the encrypted passphrases for SSL private keys used in the configuration cannot be decrypted, and an error message displays that appears similar to the following example:

BIGpipe client SSL profile creation error: 01070937:3: Master Key decrypt failure - decrypt failure

If you receive this error message when installing the UCS archive, refer to K9420: Installing a UCS file containing an encrypted passphrase before proceeding.

From the Archive List, click the name of the UCS archive that you want to restore. Note: If the UCS archive is encrypted, type the passphrase for the archive file in the Restore Passphrase field.

Click Restore. A status screen displays.

Examine the screen for errors. Important: If you are restoring the backup on a different device from the system where the backup was created, such as an RMA system, the configuration load may fail with a license error. As a result, a BigDB.dat load error message that appears similar to the following example displays:

mcpd[2395]: 01070608:0: License is not operational(expired or digital signature does not match contents). Loading the new /config/BigDB.dat failed. 01080023:3: Error return while getting reply from mcpd: 0x1070370, 01070370:3: Failover (redundant mode) is not licensed. After updating your license, run loaddb -local /config/BigDB.dat.cs

The previous error message is expected, and is corrected by re-licensing the system later in the procedure.

Click OK. Click System. Click Configuration. Click Reboot. If you restored the UCS archive on the same device where the archive was created, it will load the restored configuration after the system reboots. If you restored the UCS archive on a different device and received the first error noted in step 5, you must reactivate the BIG-IP system license.

Note: For more information about licensing, refer to K7752: Licensing the BIG-IP system.

After re-licensing the system, reboot the system again to ensure that the BigDB.dat is fully built and loaded. To reboot the system, browse to System > Configuration, and click Reboot.

Restoring configuration data from the command line using the bigpipe utility

To restore a configuration in a UCS archive using the bigpipe utility, review the prerequisites in the Prerequisites for restoring configuration data section before performing the following procedure:

Log in to the BIG-IP command line. Back up the existing license file to the /var/tmp/ directory by typing the following command: cp /config/bigip.license /var/tmp

Restore the configuration from the UCS archive by typing the following command, replacing

Note: If the UCS archive is not located in the default directory, include the path to the file.

Note: If the UCS archive file specified was encrypted, you are prompted to enter the passphrase for the archive file.

Important: If you are restoring the backup on a different device from the system where the backup was created, such as an RMA system, the configuration load may fail with a license error. As a result, a BigDB.dat load error message that appears similar to the following example displays:

mcpd[2395]: 01070608:0: License is not operational(expired or digital signature does not match contents). Loading the new /config/BigDB.dat failed. 01080023:3: Error return while getting reply from mcpd: 0x1070370, 01070370:3: Failover (redundant mode) is not licensed. After updating your license, run loaddb -local /config/BigDB.dat.cs

The previous error message is expected, and is corrected by re-licensing the system later in the procedure.

Important: If you are restoring a backup containing SSL private key passphrases after reinstalling the operating system, replacing a failed system with a new system, or otherwise moving an existing configuration to a new system, the encrypted passphrases for SSL private keys used in the configuration cannot be decrypted, and an error message similar to the following example displays:

BIGpipe client SSL profile creation error: 01070937:3: Master Key decrypt failure - decrypt failure

If you receive this error message when installing the UCS archive, refer to K9420: Installing a UCS file containing an encrypted passphrase before proceeding.

If you are running BIG-IP on a 1500, 3400, 4100, 6400, 6800, or 8400 hardware platform, type the following command to verify that the new or replaced SSH keys from the UCS file are synchronized between the BIG-IP system and the Switch Card Control Processor (SCCP): keyswap.sh sccp

Note: For more information about synchronizing SSH keys, refer to K3759: Synchronizing SSH keys between the BIG-IP host system and the SCCP.

Reboot the system by typing the following command: reboot

If you restored the UCS archive on the same device where the archive was created, it loads the restored configuration after the system reboots. If you restored the UCS archive on a different device and received the first error noted in step 3, you must reactivate the BIG-IP system license.

Note: For more information about licensing, refer to K7752: Licensing the BIG-IP system.

Alternatively, you can replace the /config/bigip.license file with the original bigip.license file you backed up from the target system. After re-licensing the system or replacing the license file, reboot the system again to ensure the BigDB.dat is fully built and loaded. To reboot the system, type the following command:

reboot

Note: If the system you have restored contains the FIPS 140 HSM, you must configure the FIPS 140 HSM Security World after completing this procedure. For additional information about recovering FIPS information after a system recovery, refer to the Platform Guide: 6900 and the Platform Guide: 8900.

Restoring configuration data from the command line using the tmsh utility

Important: If you are restoring a UCS archive on a BIG-IP 1500, 3400, 4100, 6400, 6800, or 8400 hardware platform other than the system from which the backup was created, such as when replacing an RMA system, you must perform the procedure in the Restoring configuration data from the command line using the bigpipe utility section to restore the configuration.

Note: For more information about the Traffic Management Shell (tmsh), refer to the Traffic Management Shell (tmsh) Reference Guide.

Note: For information about how to locate F5 product guides, refer to K12453464: Finding product documentation on AskF5.

To restore the BIG-IP system configuration using the tmsh utility, perform the procedure appropriate for your BIG-IP version:

BIG-IP 10.1.0 and later

Log in to the tmsh utility by typing the following command: tmsh

Restore the UCS archive file by entering the following command: load /sys ucs <path/to/UCS>

In this command, note the following:

<path/to/UCS> refers to the full path of the UCS archive file you want to restore. Note: If you do not specify the path, the BIG-IP system acts as though the UCS archive file is located in the default /var/local/ucs directory.

Note: If the UCS archive file specified was encrypted, you are prompted to enter the passphrase for the archive file.

Important: If you are restoring the backup on a different device from the system where the backup was created, such as an RMA system, and you did not restore using the tmsh utility rma option, the configuration load may fail with a license error. As a result, a BigDB.dat load error message that appears similar to the following example displays:

mcpd[2395]: 01070608:0: License is not operational(expired or digital signature does not match contents). Loading the new /config/BigDB.dat failed. 01080023:3: Error return while getting reply from mcpd: 0x1070370, 01070370:3: Failover (redundant mode) is not licensed. After updating your license, run loaddb -local /config/BigDB.dat.cs

The previous error message is expected, and is corrected by re-licensing the system later in the procedure.

Important: If you are restoring a backup containing SSL private key passphrases after reinstalling the operating system, replacing a failed system with a new system, or otherwise moving an existing configuration to a new system, the encrypted passphrases for SSL private keys used in the configuration cannot be decrypted, and an error message that appears similar to the following displays:

BIGpipe client SSL profile creation error: 01070937:3: Master Key decrypt failure - decrypt failure

If you receive this error message when installing the UCS archive, refer to K9420: Installing a UCS file containing an encrypted passphrase before proceeding.

If you are running the BIG-IP system on a 6400, 6800, 8400, or 8800 hardware platform, type the following command to switch to the bash shell: run /util bash

Then type the following command to verify that the new or replaced SSH keys from the UCS file are synchronized between the BIG-IP system and the SCCP:

keyswap.sh sccp

Note: For more information about synchronizing SSH keys, refer to K3759: Synchronizing SSH keys between the BIG-IP host system and the SCCP.

Then type the following command to switch back to the tmsh utility:

exit

Reboot the system by typing the following command: reboot

If you restored the UCS archive on the same device where the archive was created, it will load the restored configuration after the system reboots. If you restored the UCS archive on a different device and received the first error noted in step 2, you must reactivate the BIG-IP system license.

Note: For more information about licensing, refer to K7752: Licensing the BIG-IP system.

Alternatively, you can replace the /config/bigip.license file with the original bigip.license file you backed up from the target system. After you re-license the system or replace the license file, reboot the system again to ensure that the BigDB.dat is fully built and loaded. To reboot the system, type the following command:

reboot

Note: If the system you have restored contains the FIPS 140 HSM, you must configure the FIPS 140 HSM Security World after completing this procedure. For additional information about recovering FIPS information after a system recovery, refer to the Platform Guide: 6900 and the Platform Guide: 8900.

BIG-IP 10.0.x

From the BIG-IP command line, prefix all of the commands in the previous procedure with the following string:

tmsh run

For example, the following command restores the UCS archive file named BIG-IP-6400B_20April2010:

tmsh run bigpipe config install BIG-IP-6400B_20April2010

From the tmsh prompt, prefix all of the commands in the previous procedure with the following string:

run

For example, the following command restores the UCS archive file named BIG-IP-6400B_20April2010 from the tmshell prompt:

run bigpipe config install BIG-IP-6400B_20April2010

Restoring configuration data on a replacement RMA unit (BIG-IP 10.1.0 or later)

Impact of procedure: The BIG-IP system replaces any existing configuration with the UCS archive file configuration. However, the license file is not overwritten with the license file from the UCS archive.

Activate the license on the unit according to the steps detailed in K7752: Licensing the BIG-IP system. Log in to the tmsh utility by typing the following command: tmsh

Restore the UCS archive file by using the following command syntax, replacing <path/to/UCS> with the full path of the UCS archive file you want to restore: load /sys ucs <path/to/UCS> rma

Note: If you do not specify the path, the BIG-IP system acts as though the UCS archive file is located in the default /var/local/ucs directory.

Note: If the UCS archive file specified was encrypted, you are prompted to enter the passphrase for the archive file.

If you are running BIG-IP on a 6400, 6800, 8400, or 8800 hardware platform, type the following command to switch to the bash shell: run /util bash

To verify that the new or replaced SSH keys from the UCS file are synchronized between the BIG-IP system and the SCCP, type the following command: keyswap.sh sccp

Note: For more information about synchronizing SSH keys, refer to K3759: Synchronizing SSH keys between the BIG-IP host system and the SCCP.

Type the following command to switch back to the tmsh utility: exit

Reboot the system by typing the following command: reboot

If the system you have restored contains the FIPS 140 HSM, you must configure the FIPS 140 HSM Security World after completing steps 1 through 5. For additional information about recovering FIPS information after a system recovery, refer to the Configuring and Maintaining a FIPS Security Domain chapter in the Platform Guide: 6900 and the Platform Guide: 8900. Restoring UCS archives obtained from an earlier software version onto BIG-IP systems running later software versions

Impact of procedure: The BIG-IP system replaces any existing configuration with the UCS archive file configuration.

F5 recommends that the BIG-IP system runs the same version of the BIG-IP software from which it was backed up. However, in some cases it is possible to restore a UCS archive that was obtained from an earlier software version on a target BIG-IP system that is running a later software version. For example, if you saved a UCS archive on a system running BIG-IP 9.4.8, it is possible to restore the archive file on a BIG-IP system running version 10.x. To restore a UCS archive on a BIG-IP system running a later software version, perform the following procedure:

Verify that a supported upgrade path exists between the software version from which the UCS archive was obtained and the software version running on the target system. For example, there is a supported upgrade path between BIG-IP 9.4.x and 10.x. As a result, you can successfully restore a BIG-IP 9.4.x UCS archive file on a BIG-IP system running version 10.x. However, there is no supported upgrade path between BIG-IP 9.2.x and 10.x. As a result, you cannot restore a BIG-IP 9.2.x UCS archive file on a BIG-IP system running version 10.x.

For information about supported upgrade paths, refer to the release notes for your specific software versions.

Manually copy the UCS archive file to the /var/local/ucs/ directory on the target system. Review Prerequisites for restoring configuration data. Restore the UCS archive file using the bigpipe utility by using the following command syntax, replacing

Reboot the system.