F5 Logo MyF5
Search
  1. MyF5 Home
  2. F5 Secure Vault: Administration
  3. Working with UCS archives
Manual Chapter : Working with UCS archives

Applies To:

Show Versions Show Versions

BIG-IP LTM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 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, 13.1.5, 13.1.4, 13.1.3, 13.1.1, 13.1.0

BIG-IP DNS

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 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, 13.1.5, 13.1.4, 13.1.3, 13.1.1, 13.1.0
Manual Chapter

Working with UCS archives

Best practices for UCS restore operations

A user configuration set (UCS) is an archive file that contains a backup of your BIG-IP configuration data. Before you configure a new or replacement BIG-IP system by restoring a UCS archive, F5 recommends you do the following:
Store passwords and passphrases securely
After you encrypt configuration object passwords or passphrases on any BIG-IP system, another system can only decrypt them (during a
tmsh load config
 operation) by using the same master key that you used to encrypt them. F5 recommends that you retain a record of each configuration object password or passphrase in a secure location on a system other than the BIG-IP system that uses the password or passphrase. Doing so makes it possible for you to restore a UCS configuration archive when the original master key is not available.
Store UCS archives securely
Make sure that you regularly back up the BIG-IP system configuration and maintain the backup UCS archives in a secure manner. The preferred way to store UCS archives securely (encrypts the entire UCS file):
tmsh save sys ucs <ucs name> passphrase <passphrase>
. For more information about creating and restoring UCS archives, see the Knowledge Base article K13132: Backing up and restoring BIG-IP configuration files with a UCS archive, at
http://support.f5.com
.
Learn about licensing with respect to UCS archives
Before installing a UCS archive on a new BIG-IP system, for example a Return Materials Authorization (RMA) device, see the Licensing section of the Knowledge Base article K13132: Backing up and restoring BIG-IP configuration files, at
http://support.f5.com
.
Learn about non-matching hardware platforms
Before moving a UCS archive from one hardware platform type to another, for example from a Virtual Clustered Multiprocessing (vCMP) guest to a hardware device, see the Knowedge Base article K82540512: Overview of the UCS archive platform-migrate option, at
http://support.f5.com
.

About decryption errors

When you attempt to restore a UCS archive or load a BIG-IP configuration that contains configuration object passwords or passphrases encrypted with a different master key, the operation fails and the system displays an error message that appears similar to one of the following examples:

0107102b:3: Master Key decrypt failure - decrypt failure - final
01071769:3: Decryption of the field (pvalue) for object (/Common/http_monitor_example 1 PASSWORD=) failed.
01071769:3: Decryption of the field (passphrase) for object (/Common/client_ssl_example example_encrypt) failed.
You might also encounter additional error messages such as the following:

01071027:5: Master key OpenSSL error: 1533808276:error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt:evp_enc.c:587:
01071769:3: Decryption of the field (privatekey) for object (9717) failed.
01070596:3: An unexpected failure has occurred,  - sys/validation/MasterKey.cpp, line 4306, exiting..

Preventing BIG-IP configuration load issues

Whenever you acquire a new or replacement BIG-IP system, a common way to configure the system is to restore a UCS archive that you created earlier on another BIG-IP system.
If the archive that you restore on the new system contains encrypted passwords or passphrases for securing BIG-IP configuration objects, the new system must decrypt those passwords or passphrases before it can load the restored BIG-IP configuration successfully (using the
tmsh load sys config
 command).
To do this decryption, the new system attempts to use the same master key that was initially used to encrypt the passwords and passphrases. If the master key that you use on the new system to decrypt passwords and passphrases on BIG-IP objects is not the same master key that was used for the encryption, the system generates load errors, and the load operation fails.
Fortunately, there are measures that you can take to prevent load failures caused by master key issues. The preventative measure you choose depends on whether or not you have the master key that was initially used to encrypt the passwords or passphrases for the BIG-IP configuration objects.

Solution 1: Reset the master key on a new system

The task below requires you to know the unencrypted password or passphrase for the master key. Before continuing, make sure you have read the section titled Preventing UCS restore issues
 in this document.
Use this task if you intend to use a user configuration set (UCS) archive from an existing BIG-IP system to configure a new (or replacement) system, and you no longer have the master key from the existing system to decrypt any passwords or passphrases in the archive.
In this case, if you at least know the unencrypted password or passphrase associated with the master key that's on the existing system, you can ensure that the new BIG-IP system loads the BIG-IP configuration successfully: Before you restore the UCS archive on the new system, simply reset the master key on the new system, using the same unencrypted password or passphrase from the master key on the existing system. The following task describes this process.
You can perform this task on any BIG-IP system, including a vCMP host or a vCMP guest.
  1. On the new system, open a console window using a program such as PuTTY.
  2. Log in to the system.
  3. At the system prompt, type
    tmsh
    .
  4. Begin resetting the master key on the new system by typing this command:
    modify sys crypto master-key prompt-for-password
    The command displays this prompt:
    enter new password:
  5. Type the unencrypted password or passphrase that's associated with the master key on the existing system.
    The system displays the prompt again:
    enter new password:
  6. Type the password or passphrase again.
  7. Securely copy the UCS archive from the existing system to the
    /var/local/ucs
     directory on the new BIG-IP system. For information about transferring files, see the Knowledge Base article K175: Transferring files to or from an F5 system, on
    http://support.f5.com
    .
  8. Restore the UCS archive on the new system by using this command syntax:
    load sys ucs
    ucs_archive_name
  9. Save the BIG-IP configuration on the new system by typing this command:
    save sys config
  10. At the BIG-IP system prompt on the new system, load the BIG-IP configuration by typing this command:
    load sys config
After you perform this task, the BIG-IP system configuration is successfully loaded on the new system, and the new system has the same master key as the existing system.

Solution 2: Copy a master key to a new system

Before you perform this task, make sure you read the section titled
Preventing UCS restore issues
 in this document.
Use this task if you intend to use a user configuration set (UCS) archive from an existing BIG-IP system to configure a new (or replacement) system, and you have the existing system's master key.
In this case, you can manually copy the master key from the existing system to the new system and then, on the new system, restore the UCS archive. This will ensure that you can load the BIG-IP configuration successfully.
This task is based on the assumption that the existing system and the new system are members of the same Device Service Clustering (DSC) device group.
You can perform this task on any BIG-IP system, including a vCMP guest.
  1. On both the existing system and the new system, open a console window, using a program such as PuTTY.
  2. Log in to the existing BIG-IP system, and at the system prompt, obtain the master key by typing this command:
    f5mku -K
    . The command output appears similar to this example:
    oruIVCHfmVBnwGaSR/+MAA==
  3. Copy the output.
    The output is the master key that you will install on the new BIG-IP system.
  4. Log in to the new system, and at the system prompt, install the master key that you copied from the existing system by typing this command:
    f5mku -r
    key_value
    Use the
    -r
     option with extreme caution. Using this option when the file
    /config/bigip.conf
     contains encrypted passwords or passphrases will cause a BIG-IP load operation to fail.
    Here's a sample command sequence:
    f5mku -r oruIVCHfmVBnwGaSR/+MAA==
  5. Verify that the master key is the same on both the existing system and the new system by typing this command from the command lines of both systems:
    f5mku -K
  6. Restore the UCS archive on the new system using this command syntax:
    tmsh load sys ucs
    file_name
    .ucs no-license
    Because the original device license was created using device-specific information and specific license registration key(s), any attempt to restore the UCS archive without specifying the
    no-license
     flag places the device in the unlicensed state, causing the restore operation to fail.
  7. On the new system, save the BIG-IP configuration by typing this command:
    tmsh save sys config
  8. On the new system, load the BIG-IP configuration by typing this command:
    tmsh load sys config
  9. At the existing system's system prompt, set the existing system as the sync leader using this command syntax:
    tmsh modify cm device-group
    device_group
     devices modify {
    existing_BIG-IP
     { set-sync-leader } }
    Note that in this command sequence,
    device_group
     is the name of the device group that both the existing system and the new system are members of.
  10. At the existing system's system prompt, sync the configuration to the new system using this command syntax:
    tmsh run cm config-sync to-group
    device_group
    Note that the process of initializing the BIG-IP configuration on the new system can take up to a full minute to complete.
  11. Confirm that the two systems are in sync by typing this command:
    tmsh show cm sync-status

Solution 3: Edit the BIG-IP configuration file

Use this task if you intend to use a user configuration set (UCS) archive from an existing BIG-IP system to configure a new system, but you do not have the master key from the existing system or its unencrypted password to prevent errors when loading the BIG-IP new configuration.
In this case, you can restore the UCS archive on the new system and edit the BIG-IP configuration file
/config/bigip.conf
 (or
/config/bigip_gtm.conf
) on the new system directly, to specify the configuration object passwords or passphrases in clear text. Examples of configuration objects that can have passwords on them are local traffic profiles, pools, and health monitors. After editing and saving the file, you can load the BIG-IP configuration into memory successfully.
You can perform this task on any BIG-IP system, including a vCMP guest.
  1. Securely copy the UCS archive from the existing system to the new system.
  2. On the new system, restore the UCS archive.
  3. On the new system, open the
    /config/bigip.conf
     file with a text editor. Or open the
    /config/bigip_gtm.conf
     file with a text editor, if the new system you are configuring is a BIG-IP LTM/BIG-IP DNS combination device (BIG-IP v11.5.0 and later).
  4. For each password-protected configuration object, replace each encrypted password or passphrase with the unencrypted password or passphrase.
  5. Load the new configuration into memory by typing this command:
    tmsh load sys config
  6. Save the running configuration in the
    /config/bigip.conf
     file by typing this command:
    tmsh save sys config
    . Or if the new system you are configuring is a BIG-IP LTM/BIG-IP DNS combination device (BIG-IP v11.5.0 and later), load the new configuration into memory by typing this command:
    tmsh load sys config
    .
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information