Manual Chapter : Upgrading to BIG-IP Version 17.0.0

Applies To:

Show Versions Show Versions


  • 17.0.0


  • 17.0.0

BIG-IP Link Controller

  • 17.0.0

BIG-IP Analytics

  • 17.0.0


  • 17.0.0


  • 17.0.0


  • 17.0.0


  • 17.0.0


  • 17.0.0


  • 17.0.0
Manual Chapter

Upgrading to BIG-IP Version 17.0.0

Upgrading earlier configurations

When you upgrade from an earlier versions of the software, you might need to know about or take care of these configuration-specific issues.
ID Number
Fix Text
Loading UCS with platform-migrate option hangs and requires exiting from the command
The UCS loading process with platform-migrate stops responding and hangs after printing:
Platform migrate loaded successfully. Saving configuration. Load UCS with platform-migrate option: tmsh load sys ucs <ucs_name> platform-migrate
: If you are loading a UCS archive created on a system running a different software version that also has an Advanced WAF configuration, there are other other aspects to consider. See: The UCS loading process stops responding, causing the device to be in an INOPERATIVE state.
Loading UCS with the platform-migrate option executes smoothly without getting stuck.
Upgrade Microsoft Hyper-V driver
BIG-IP Virtual Edition (VE) on Azure has an issue where the BIG-IP system raises a kernel panic soon after a Network Management Agent update occurs on the host. When performance tests are run on VE in Microsoft Azure, the BIG-IP system loses all connectivity to the pools and becomes unresponsive.
-- Azure Host performs a Network Management Agent (NMAgent) update while TMM is running.
-- Running performance tests of VE in Azure.
The BIG-IP system might restart and the GUI becomes unresponsive during performance testing.
The Microsoft Hyper-V driver has been updated to v4.3.5.
IM installation fails with error: Spec file not found
IM installation fails with an error message: ERROR Error during switching: Spec file not found This can occur when deleting an IM file that is actively installing on one volume, and the BIG-IP system is booted from another volume. Upgrading/Downgrading to another IM does not work until you install a new BIG-IP image on the same disk.
During the init process, the system now installs FactoryDefaults if the active IM file is not found on disk.
Traffic Classification auto signature update fails from GUI
Beginning in BIG-IP software v14.1.0, Traffic Classification auto signature update fails when performed using the GUI. The system reports an error: Error: Exception caught in the script. Check logs (/var/log/hitless_upgrade.log) for details. Performing Traffic Classification auto signature update using the GUI. Fails to update the classification signature automatically.
You can use either of the following:
-- Perform Traffic Classification auto signature update operations from the CLI.
-- Use the GUI to manually update Traffic Classification signatures.
Fixed the hitless upgrade script to download the IM packages from the EDSM server for point releases.
Running cpcfg after first boot can result in daemons stuck in restart loop
After running cpcfg and booting into the volume, daemons such as named and gtmd are stuck restarting. Additionally the SELinux audit log contains denial messages about gtmd and named being unable to read unlabeled_t files. Running cpcfg on a volume that has already been booted into. Services do not come up.
In the bash shell, force SELinux to relabel at boot time. Then reboot: # touch /.autorelabel # reboot
None specified
Global/URL/Flow Parameters with flag is_sensitive true are not masked in Referer
Global/URL/Flow Parameters with flag is_sensitive true are not masked in referrer and their value may be exposed in logs. Global/URL/Flow Parameters with flag is_sensitive true are defined in the policy. In logs, the value of such parameter will be masked in QS, but will be exposed in the referrer. The parameter will not be masked in 'Referer' value header in logs, although it is masked in 'QS' string.
Can defined the parameters as global sensitive parameters.
After the fix, such parameters will be treated like global sensitive parameters and will be covered also in the Referer
A modified default profile that contains SSLv2, COMPAT, or RC2 cipher will cause the configuration to fail to load on upgrade
After upgrading, the configuration fails to load and throws an error about a profile that is located in profile_base.conf using SSLv2. However, upon inspection you will notice that there is no SSLv2 cipher in use.
The upgrade failure is seen when all the following conditions are met:
-- BIG-IP system with SSLv2 as the ciphers option in an SSL profile running software v12.x/v13.x.
-- Upgrading to a version that reports an error when using SSLv2, such as v14.x/v15.x.
(1) Modified root SSL profile (such as /Common/clientssl or /Common/serverssl) is present in bigip.conf.
(2) The modified root SSL profile contains an invalid keyword 'COMPAT', 'SSLv2', or 'RC2' in its ciphers
(3) The default profiles whose ciphers inherited from the root profile are not present in bigip.conf. The error for invalid ciphers is reported against these profiles.
Beginning in version 14.x, SSLv2 has been changed from being a warning condition, and now prevents the configuration from loading. In most cases the upgrade script properly removes this, so there is no issue. However, if this issue is encountered, the configuration fails to load after upgrading.
There are two possible workarounds:
-- The easiest way to work around this is to comment out the modified base profile from bigip.conf and then run the command: tmsh load sys config.
-- If you are post upgrade, you can use sed to remove the !SSLv2 entries. To do so, perform these steps on the standby device:
1. cp /config/bigip.conf /config/backup_bigip.conf
2. Run: sed -i "s/\(\!SSLv2:\|:\!SSLv2\)//g" /config/bigip.conf 3. tmsh load /sys config
None specified
Orphaned bigip_gtm.conf can cause config load failure after upgrading
Configuration fails to load after upgrade with a message:
01420006:3: Can't find specified cli schema data for x.x.x.x Where x.x.x.x indicates an older version of BIG-IP software than is currently running.
-- Orphaned bigip_gtm.conf from an older-version. This can occur if GTM/DNS is provisioned, then deprovisioned before upgrade, leaving behind a bigip_gtm.conf with the old schema.
-- Upgrading to a new version that does not contain the schema for the old version that the bigip_gtm.conf uses.
Configuration fails to load after upgrade.
Before upgrading: If the configuration in bigip_gtm.conf is not needed, then it can be renamed (or deleted) before upgrading:
mv /config/bigip_gtm.conf /config/bigip_gtm.conf.id837637
tmsh load sys config gtm-only
After upgrading (i.e., with the system in the Offline state) services must be restarted to pick up the change:
mv /config/bigip_gtm.conf /config/bigip_gtm.conf.id837637
tmsh restart sys service all
None specified
No swap memory available after upgrading to v14.1.0 and above
After an upgrade to v14.1.0 or higher, swap memory may not be mounted. TMM or other host processes may restart due to lack of memory.
-- System is upgraded to v14.1.0 or above.
-- System has RAID storage.
May lead to low or out-of-memory condition. The Linux oom killer may terminate processes, possibly affecting service. Typically management activities may be impacted, for example, a sluggish GUI (config utility) or tmsh sessions.
Mount the swap volume with correct ID representing the swap device.
Perform the following steps on the system after booting into the affected software version:
1. Get the correct ID (RAID device number (/dev/md<number>)):
blkid | grep swap
: If there is no RAID device number, perform the procedure detailed in the following section.
2. Check the device or UUID representing swap in /etc/fstab.
3. If swap is not represented with the correct ID, modify the /etc/fstab swap entry to point to the correct device.
4. Enable the swap:
swapon -a
5. Check swap volume size:
swapon -s
If the blkid command shows there is no UUID associated with the swap RAID device, use the following procedure:
1. Generate a random UUID:
2. Make sure swap is turned off:
swapoff -a
3. Recreate the swap partition with UUID generated in step 1:
mkswap -U <uuid_from_step_1> <raid_device_from_step_1>
4. Run blkid again to make sure that you now have a UUID associated with the raid device:
blkid | grep swap
5. edit fstab and find the line
<old_value> swap swap defaults 0 0
6. Replace the old value, whether it was an incorrect UUID or a device name, with the UUID generated in step 1, for example:
UUID=8b35b30b-1076-42bb-8d3f-02acd494f2c8 swap swap defaults 0 0
None specified
Automatic ISO digital signature checking not required when FIPS license active
Automatic ISO digital signature checking occurs but is not required when FIPS license active. The system logs an error message upon an attempt to install or update the BIG-IP system: failed (Signature file not found - /shared/images/BIGIP- When the FIPS license is active, digital signature checking of the ISO is automatically performed. This requires that both the ISO and the digital signature (.sig) file are uploaded to the system. Installation does not complete if the .sig file is not present or not valid. Installation failure.
To validate the ISO on the BIG-IP system, follow the procedure described in K24341140: Verifying BIG-IP software images using .sig and .pem files ::
The restriction of requiring automatic signature checking of the ISO is removed. The procedure described in K24341140: Verifying BIG-IP software images using .sig and .pem files :: to perform the checks on or off the BIG-IP system is still valid, but that checking is optional.
iControl REST token issue after upgrade
When upgrading to version 13.1.0.x or later, users who previously had permissions to make calls to iControl REST lose the ability to make those calls.
You will notice this issue when you use iControl REST and are upgrading to version 13.1.0.x or later.
You can also detect if the user is impacted by this issue with the following steps
1. Run below API to for impacted user account XYZ.
# curl -ik -u username:XYZ -XPOST https://localhost/mgmt/shared/authn/login --data-binary '{"username":"XYZ", "password":"XYZpass", "loginProviderName":"tmos"}' -H "Content-Type: application/json"
2. Find user XYZ's 'link' path under 'token' in previous output
There are two formats possible for 'link'
a. Path will have a UUID
For example "token"->"link"->"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/<UUID>"
b. Path will have a username (not UUID)
For example "token"->"link"->"https://localhost/mgmt/shared/authz/users/<username>"
3. Run below API to get list of user roles.
# restcurl -u "admin:<admin-user-pass>" /shared/authz/roles | tee /var/tmp/rest_shared_authz_roles.json
4. Check user XYZ's link path from step 2 in above output.
Check under the "userReferences" section for group "iControl_REST_API_User" . You will see the link path in one of the two formats listed in 2a/2b. If you do not see the user link path then you are impacted by this bug.
A previously privileged user can no longer query iControl REST. In addition, some remotely authenticated users may lose access to the Network Map and Analytics view after the upgrade.
You can repair the current users permissions with the following process:
1) Delete the state maintained by IControlRoleMigrationWorker and let it rerun by restarting restjavad process:
# restcurl -X DELETE "shared/storage?key=shared/authz/icontrol-role-migrator"
2) Restart services
# bigstart restart restjavad *or* tmsh restart /sys service restjavad
3) Now, when you create a new user, the permissions should start in a healthy state
4) If this still does not resolve the issue you could update shared/authz/roles/iControl_REST_API_User userReference list to add all affected users' accounts using PUT. Here you may need to use the UUID path as described under 'Conditions'
# restcurl shared/authz/roles/iControl_REST_API_User > role.json
# vim role.json
a. add { "link": "https://localhost/mgmt/shared/authz/users/[your-user-name]" } object to userReferences list
b. add { "link": "https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/<UUID>" } object to userReferences list
# curl -u admin:admin -X PUT -d@role.json http://localhost/mgmt/shared/authz/roles/iControl_REST_API_User
When upgrading to version 13.1.0.x or later, users who previously had permissions to make calls to iControl REST retain the ability to make those calls.
Image2disk does not work on F5OS BIG-IP tenant.
Image2disk fails to recognize the correct disk to install and installation fails. This occurs with BIG-IP tenants that are running in F5OS partitions. Installation fails.
None specified
Network virtual-addresses fail to retain the "icmp-echo enabled" property following an upgrade or reload of the configuration from file.
Network virtual-addresses default to "arp disabled" and "icmp-echo disabled". However, a BIG-IP Administrator can change these settings to "enabled", if required. Either following a software upgrade or a reload of the configuration from file, network virtual-addresses that had previously been set to "icmp-echo enabled" revert to the default of "icmp-echo disabled".
- One or more network virtual-addresses configured with "icmp-echo enabled".
- A software upgrade or reload of the configuration from file occurs (for example, taking and restoring a UCS archive, removing the mcpd binary database and reloading the config, etc.).
Traffic failures can occur as a result of the affected network virtual-addresses not being presented to the surrounding network as originally intended by the BIG-IP Administrator.
Manually configure the affected virtual-addresses to "icmp-echo enabled" again. This workaround is not permanent, and the issue will occur again in the future given the right conditions.
Network virtual-addresses no longer lose the "icmp-echo enabled" property.
Set auto-failback-enabled moved to false after upgrade
In a traffic group, auto-failback-enabled is changed from true to false after config save and upgrade. During the upgrade, the following log can be observed:
info: Warning: Invalid configuration - Traffic Group has high availability (HA) Group "test_HA_Group" assigned and auto-failback-enabled set to true. Resetting auto-failback-enabled to false.
-- auto-failback-enabled is set to true and high availability (HA) groups are configured and assigned to traffic-group
-- The device is upgraded. Auto-failback-enabled is set from true to false and auto failback is disabled.
After upgrade, set the auto-failback-enabled to true.
None specified

Upgrading from earlier versions

Upgrading from version 14.x or later

When you upgrade from version 14.x or later, you use the Software Management screens in the Configuration utility to complete these steps. To open the Software Management screens, in the navigation pane of the Configuration utility, expand
, and click
Software Management
. For information about using the Software Management screens, see the online help.

Upgrading from versions earlier than 14.x

You cannot roll forward a configuration directly to this version from BIG-IP version 13.x or earlier. You must be running version 14.x (or later) software. For details about upgrading from earlier versions, see the release notes for the associated release.

Automatic firmware upgrades

If this version includes new firmware for your specific hardware platform, after you install and activate this version, the system might reboot additional times to perform all necessary firmware upgrades.

Issues when upgrading from earlier Advanced WAF versions

If you upgrade from an earlier version of Advanced WAF, note the following issues.

Exporting Logs

In version 13.0.0 the ability to export request logs in binary (.csv) and PDF file formats was removed. Log files are exported in HTML format only. The resultant HTML log file can be converted to a PDF by:
  • Printing the HTML page to PDF from the browser window.
  • Scripting the HTML to PDF conversion using CLI can be found in wkHTMLtopdf.

Advanced WAF cookie security

As a result of changes made to the signing of Advanced WAF cookies, performing a clean upgrade may result in cookie violations and blocked traffic. To prevent these, F5 recommends that you perform the following actions before upgrading:
  • Disable the modified domain cookie violation, and re-enable it only after at least 24 hours have passed.
  • If you do not have a wildcard cookie, before the upgrade add an Advanced WAF allowed cookie to the security policy, with the name
  • Have all clients restart their browsers.
After upgrading, users must synchronize their Cookie Protection settings in the following cases:
  • Systems that share traffic but are NOT in the same device group
  • Systems from different versions that share traffic, even if they are in the same device group

Cookie signature validation

After upgrading, the system performs the following:
  • Turns on staging for all Allowed cookies
  • Applies signature checks on existing Allowed cookies
  • Adds a * wildcard Allowed cookie even if the user did not have on previously Upgrading to version 11.3.0 or later

Running Advanced WAF on a vCMP system

If you are running Advanced WAF on a vCMP system: For best performance, F5 recommends configuring remote logging to store Advanced WAF logs remotely on
servers rather than locally.

About changing the resource provisioning level of the Advanced WAF

After upgrading or installing a new version, before you can use the Advanced WAF, you must set the Advanced WAF resource provisioning level to Nominal if it is not already set to Nominal. You can do this from the command line, or using the Configuration utility.
Wait 5 minutes after you set the resource provisioning level before making any configuration changes to the Advanced WAF. The system overrides all configuration changes that were made before this process is completed. When the process is not complete, the system informs you by displaying, in the Configuration utility, the following message:
ASM is not ready
. The system informs you when the process is completed by indicating in the log (
) the following message:
ASM started successfully

Prevent traffic from bypassing the Advanced WAF

For important information needed to prevent traffic from bypassing the Advanced WAF, please see the AskF5 Knowledge Center articles K8018: Overview of the BIG-IP HTTP class traffic flow and K12268: Successive HTTP requests that do not match HTTP class may bypass the BIG-IP ASM.

About working with device groups

This section is relevant only if you are working with device groups.
When Advanced WAF is provisioned, the
device-group is automatically created (even if there are no device-groups on the unit) in any of the following scenarios:
  • First provisioning of Advanced WAF installed.
  • Adding a device to a trust-domain that has another device which already has the
  • Upgrading to when Advanced WAF is already provisioned.
  • Upgrading when the device is joined in a trust-domain that has another device which already has the
This device group is used to synchronize client-side scripts and cryptographic keys across all of the devices in the trust-domain.
Note the following:
  • The synchronization is performed across the entire trust-domain, regardless of the configured device groups.
  • The
    device group must not be removed; it is essential for consistency of client-side scripts and keys across the devices.
  • This device group is created upon provisioning, even if the BIG-IP system is working as a standalone.
  • All of the devices in the trust-domain are automatically added to this device group.
  • This device group is manually synchronized. Therefore, when working with device groups (multiple devices in a trust-domain), customers must choose which device will hold the master scripts and keys. The rest of the devices receive these scripts and keys from the chosen device.
  • This device group is also created on units that do not have Advanced WAF provisioned, but are in a trust-domain with other units which do have Advanced WAF provisioned.