K000112152: Update or upgrade BIG-IP HA systems using the

TMOS Shell | BIG-IP update and upgrade guide

https://my.f5.com/manage/s/article/K60339442
Published Date: Jan 13, 2021 UTC Updated Date: Feb 15, 2023 UTC

Chapter 8: Update or upgrade BIG-IP HA systems using the TMOS Shell

Table of contents | << Previous chapter | Next chapter >>

Contents

Chapter sections

Introduction
Upgrade vs. update
Prerequisites
Upload a software image to a BIG-IP system
Windows systems
Mac OS or Linux systems
Perform a software update or upgrade on a BIG-IP system
Reboot to a newly updated or upgraded software volume
Test the update or upgrade
Verify the configuration
Force the active BIG-IP to standby
Troubleshoot
Back out of your software update or upgrade
Common issues, possible causes, and resolutions

Tables

Table 8.1 Common issues, possible causes, and resolutions

Introduction

This chapter describes how to upgrade BIG-IP high availability (HA) systems using the TMOS Shell (tmsh).
If you prefer to use the Configuration utility, refer to Chapter 7: Update or upgrade BIG-IP HA systems using
the Configuration utility.

This procedure does not apply to BIG-IP Virtual Edition (VE) systems deployed using LTM_1SLOT
installation images, which are limited by disk space by design. While it is possible to expand disk space on
LTM_1SLOT BIG-IP systems and perform an upgrade, that procedure is out of scope for this article. For
more information, refer to K14946: Overview of BIG-IP VE image sizes.
Successfully upgrading the BIG-IP system requires some planning and preparation, such as checking the
current health of the BIG-IP system and backing up the configuration. Failure to perform these procedures
can lead to unexpected down time and extended maintenance windows.

Also, to decrease the duration of the maintenance window, you can upgrade the standby BIG-IP systems in
HA configurations during production. However, in critical environments, you may choose to perform the
entire upgrade during a maintenance window. For more information, refer to Chapter 4: Prepare to update or
upgrade the BIG-IP system.

Upgrade vs. update

This chapter may use the word upgrade to refer to either a software upgrade or update. For a definition that
explains the difference between the two terms, refer to Upgrading vs. updating in the Introduction.

Prerequisites

You must meet the following prerequisites to use this procedure:

You have access to the device serial terminal or virtual serial terminal console for VE systems.
You have administrative (root) permissions to the BIG-IP system.
You followed the steps in Chapter 4: Prepare to update or upgrade the BIG-IP system.
You installed a Secure Copy (SCP) protocol client utility on your local computer to upload files to the
BIG-IP system. Linux and Mac OS systems typically already have SCP utilities installed, but Windows
users must install third party utilities such as WinSCP.

Upload a software image to a BIG-IP system

SCP is the preferred method to transfer files to or from an F5 device. SCP securely transfers files between
hosts using the SSH protocol for authentication, encryption, and data transfer. For more information about
transferring files to or from an F5 system, refer to K175: Transferring files to or from an F5 system.

Windows systems

The WinSCP utility is third-party software that provides a graphical user interface to transfer files between
systems using SCP. For instructions on installing the software, refer to your software vendor documentation.

Impact of procedure: Performing the following procedure should not have a negative impact on your
system.

1. Open the WinSCP utility on your Windows computer.

2. In the Login window, select New Site.
3. For File Protocol, select SCP.
4. For Hostname, enter the management IP address of your BIG-IP system.
5. For User name, enter root.
6. For Password, enter the BIG-IP root user password.
7. Select Login.
8. If this is your first time connecting to this BIG-IP system, the system displays a message similar to the
following:

Continue connecting to an unknown server and add its host key to a cache?

Select Yes to continue.

 9. Locate and upload the BIG-IP upgrade image to the /shared/images directory of your BIG-IP system.

Mac OS or Linux systems

Mac OS or Linux system typically come with the SCP utility. If you need to install the SCP utility, refer to
your software vendor documentation.

Impact of procedure: Performing the following procedure should not have a negative impact on your
system.

1. Launch a command terminal to perform the following commands.

2. Use the SCP utility to upload the BIG-IP upgrade image to your BIG-IP system.

For example, to upload the BIGIP-16.0.0-0.0.12.iso image, you enter the following command:

scp BIGIP-16.0.0-0.0.12.iso [email protected]:/shared/images/

3. When prompted, enter your BIG-IP root user password.

Perform a software update or upgrade on the standby BIG-IP system

The upgrade process does not affect the existing boot location; therefore, you can boot back in to the original
volume if any issues occur during the upgrade process. Consequently, if you want to limit the duration of the
maintenance window, you can perform the actual installation during normal operation, and then schedule a
separate maintenance window to reboot the BIG-IP system into the newly upgraded software volume. The
configuration from the active boot location automatically copies to the new boot location during the upgrade
process. You cannot install to the current active boot location.

Also, ensure that you already booted your system into the software volume that contains the configuration
you are planning to upgrade. If you did not already boot the system into that volume, restart your system to
that software volume before you begin the following procedure. By default, during the upgrade process, the
BIG-IP system imports the current running configuration from the active volume into the target volume. To
prevent the system from importing the configuration during the upgrade process, refer to K13438:
Controlling configuration import when performing software installations.

In BIG-IP HA configurations, first you perform the upgrade on the standby system, then you fail over and
test applications, before you perform the upgrade on peer BIG-IP systems.

Impact of procedure: During the upgrade process on the standby BIG-IP system, the active BIG-IP has no
backup. In critical environments, F5 recommends performing the entire upgrade during a maintenance
window.

1. Log in to the command line of the standby BIG-IP system using the Advanced Shell (bash).
2. Enter the following command to view information about the software images that are available for
installation on the BIG-IP system:

tmsh list sys software image

The output appears similar to the following example:

sys software image BIGIP-14.1.0-0.0.116.iso {

build 0.0.116
build-date "Wed Nov 14 18 41 56 PST 2018"
 checksum acb4537e37557ada7f60267d5f946387
file-size "2238 MB"
last-modified "Tue Sep 8 08:36:50 2020"
product BIG-IP
verified yes
version 14.1.0
}
sys software image BIGIP-16.0.0-0.0.12.iso {
build 0.0.12
build-date "Tue Jun 23 18 31 26 PDT 2020"
checksum 7d0fe1341f74567946d0e196456b9fa0
file-size "2322 MB"
last-modified "Tue Sep 8 08:37:58 2020"
product BIG-IP
verified yes
version 16.0.0
}

3. Enter the following command to view information about the current BIG-IP installed images.

Make a note of the Volume name, such as HD1.1, so that you can use it when you install the upgrade
image.

tmsh show sys software status

The output appears similar to the following example:

---------------------------------------------------
Sys::Software Status
Volume Product Version Build Active Status
---------------------------------------------------
HD1.1 BIG-IP 14.1.0 0.0.116 yes complete

4. Use the following command syntax to create a new volume and install an available image to the new
volume:

tmsh install sys software image <BIG-IP image ISO name> volume <volume name> create-volume

Note: If you are installing over an existing volume that is not currently active, omit the create-volume
option. You cannot install over the current active volume. Additionally, when selecting the new
volume name, you can use any combination of lowercase alphanumeric characters (a-z, 0-9) and the
hyphen (-). The volume set name can be from 1 to 32 characters in length but cannot be only one 0
(zero) character (for example HD1.0 or MD1.0). For example, volume names can be project related,
such as HD1.Development, or they can be simply numeric, such as HD1.2.

For example, to create a volume named HD1.2 and install the BIGIP-16.0.0-0.0.12.iso image to that
volume, you enter the following command:

tmsh install sys software image BIGIP-16.0.0-0.0.12.iso volume HD1.2 create-volume

5. Enter the following command to view the installation status:

tmsh show sys software status

 The output appears similar to the following example, with the percent (pct) installed status
incrementing until installation is complete:

----------------------------------------------------------------
Sys::Software Status
Volume Product Version Build Active Status
----------------------------------------------------------------
HD1.1 BIG-IP 14.1.0 0.0.116 yes complete
HD1.2 BIG-IP 16.0.0 0.0.12 no installing 10.000 pct

You can also use the watch utility to monitor the installation status, for example you enter the
following command syntax:

watch -n 30 "tmsh show sys software status"

This causes the screen to refresh every 30 seconds and provide the current installation status. Select
Ctrl+c to exit the watch utility.

Reboot to the newly updated or upgraded software volume

Impact of procedure: This procedure requires that you restart the system. During this time, the system is not
available to process traffic, nor can it serve as a backup to your active BIG-IP system. In critical
environments, F5 recommends that you perform this procedure during a maintenance window. Additionally,
the first time that you restart and boot to the new volume, the process can take up to 30 or more minutes,
depending on the size of the configuration.

1. Log in to the command line of the standby BIG-IP system using bash.
2. Enter the following command to view the current active BIG-IP boot location:

tmsh show sys software status

The output appears similar to the following example:

---------------------------------------------------
Sys::Software Status
Volume Product Version Build Active Status
---------------------------------------------------
HD1.1 BIG-IP 14.1.0 0.0.116 yes complete
HD1.2 BIG-IP 16.0.0 0.0.12 no complete

In the previous output, HD1.1 is the current active boot location.

3. Optionally, use the following syntax to copy the configuration from the current active configuration to
the new boot location, prior to restarting and booting into the new volume.

Note: When you install a new image, the system automatically installs the configuration from the
current active volume to the new boot location. If you did not make any changes to the configuration
after you installed the new upgrade image, skip this step.

cpcfg --source=<volume name to copy the configuration from> <newly installed software volume>

For example, to copy the configuration from the active volume HD1.1 to the newly installed volume
HD1.2, you enter the following command:
 cpcfg --source=HD1.1 HD1.2

The output appears similar to the following example:

info: Getting configuration from HD1.1

info: Copying configuration to HD1.2
info: Applying configuration to HD1.2

4. Use the following command syntax to restart the system and boot to the upgraded software volume.

Important: After you enter this command, the system immediately begins restarting. The system drops
all existing connections and does not pass traffic until the restart completes and the BIG-IP
configuration loads.

tmsh reboot volume <volume name>

For example, to boot to the volume named HD1.2, you enter the following command:

tmsh reboot volume HD1.2

The output appears similar to the following example:

The system will be rebooted momentarily

Test the update or upgrade

Verify the configuration

Impact of procedure: Performing this procedure should not have a negative impact on your system.

1. Log in to the command line of the standby BIG-IP system using tmsh.
2. Spot-check configuration objects to visually confirm that the expected configuration exists and is in the
expected state. Use commands similar to those in the following table to review the common
configuration elements.

Note: tmsh interactive mode provides tab completion for command options. When at the tmsh prompt,
select the Tab key to see possible command options. For most objects, you can use the list command to
see configured object parameters and the show command to see statistical information for the object.
Also, if there are multiple objects of a certain type, such as virtual servers, you can usually specify one
of those objects by entering the object name in the command. Leaving off the object name shows all
objects of that type.

Command Description
Show configuration information for one or all configured virtual
list /ltm virtual <virtual_name>
servers
show /ltm virtual
Show statistical traffic information for one or all virtual servers
<virtual_name>
list /ltm pool <pool_name> Show configuration information for one or all configured pools
show /ltm pool <pool_name> Show statistical traffic information for one or all pools
list /net vlan <vlan_name> Show configuration information for one or all configured VLANs
 show /net vlan <vlan_name> Show statistical traffic information for one or all VLANs
3. Create a QKView diagnostic file by typing the following command:

run /util qkview

Note: By default, the qkview utility creates the file /var/tmp/<hostname of the BIG-IP>.qkview.

4. Use your SCP client utility to download the QKView file from your BIG-IP system to your desktop
computer, then upload the file to iHealth and review.

For more information, refer to the Upload your QKView diagnostic file to iHealth and review
section of Chapter 4: Prepare to update or upgrade the BIG-IP system.

Force the active BIG-IP to standby

If the BIG-IP device has more than one traffic group, all traffic groups fail over to the next available device.
On systems with more than one traffic group and more than two BIG-IP systems, you can select the next
active BIG-IP system for each traffic group. For more information, refer to K15455872: Forcing an active
BIG-IP system into standby mode using tmsh.

Impact of procedure: This procedure interrupts traffic during failover. F5 recommends that you perform this
procedure during a maintenance window. If you encounter any problems with the newly upgraded system
after failover, you must repeat this procedure on the newly upgraded system to fail back to the previously
active system.

1. Log in to the command line of the active BIG-IP system using bash.
2. Enter the following command to view the current active BIG-IP system:

Note: You cannot directly promote the standby system to active; you can only force the active system
to standby, while logged into the active system.

tmsh show cm failover-status

The output appears similar to the following example:

-------------------------------------------
CM::Failover Status
-------------------------------------------
Color green
Status ACTIVE
Summary 1/1 active
Details
active for /Common/traffic-group-1

---------------------------------------------------------------------------------------------------
CM::Failover Connections
Local Failover Address Remote Device Packets Transitions Received Last Packet Status
---------------------------------------------------------------------------------------------------
192.0.2.2:1026 BIGIP2.example.com 11335814 15 2020-Dec-29 13:08:54 Ok
10.0.0.2:1026 BIGIP2.example.com 11331074 15 2020-Dec-29 13:08:54 Ok

Confirm that the standby system that you upgraded is listed in the Remote Device section, and that the
Status is listed as Ok. If this is not the case, go back to the standby BIG-IP system and troubleshoot.
 3. Enter the following command to force the active BIG-IP system into standby mode, moving the
upgraded system to the active role:

tmsh run sys failover standby

4. Repeat step 2 to confirm that the system is now in standby mode.

5. Test client traffic to the upgraded BIG-IP system to confirm that the system is processing traffic as
expected.
6. After confirming the health of the upgraded system, repeat the upgrade steps on the peer BIG-IP
system.
7. After completing all upgrades and testing, create a new set of UCS archive files to retain backups of
the new BIG-IP version configuration.

For more information, refer to the Create a backup of the BIG-IP configuration section of Chapter
4: Prepare to update or upgrade the BIG-IP system.

Troubleshoot

Back out of your software update or upgrade

If a BIG-IP system fails to upgrade and you cannot perform further troubleshooting due to time constraints,
complete the following steps before reverting to the previous BIG-IP version.

Note: If you do not perform troubleshooting before reverting changes, it may be difficult to determine a root
cause for failure. If possible, contact F5 Support while the issue is occurring so you can perform relevant data
gathering, such as creating a new QKView file.

Gather troubleshooting information

1. To determine what may be causing the configuration load error, run the tmsh load /sys config
command from the BIG-IP command line to observe any error messages.
2. Use the qkview utility to create a QKView file.

For more information about the qkview utility, refer to K12878: Generating diagnostic data using the
qkview utility.

Boot to a previous software version

1. Log in to the command line of the BIG-IP system using bash.

2. Enter the following command to view the current active BIG-IP boot location:

tmsh show sys software status

The output appears similar to the following example:

---------------------------------------------------
Sys::Software Status
Volume Product Version Build Active Status
---------------------------------------------------
HD1.1 BIG-IP 14.1.0 0.0.116 no complete
HD1.2 BIG-IP 16.0.0 0.0.12 yes complete

3.
 3. Use the following command syntax to restart the system and boot to the previous software volume:

tmsh reboot volume <volume name>

For example, to boot to the pre-upgrade volume named HD1.1, you enter the following command:

tmsh reboot volume HD1.1

Common issues, possible causes, and resolutions

Table 8.1 Common issues, possible causes, and resolutions

Common issue Possible causes Resolution
The configuration fails to load and you
observer one or both of the following messages
in the Configuration utility:
Errors in
The configuration has not yet loaded. If BIG-IP K02091043: Error Message: The
this message persists, it may indicate a configuration. configuration has not yet loaded. If
configuration problem. Issues with this message persists, it may indicate a
This BIG-IP system has encountered a license configuration problem.
configuration problem that may prevent enforcement.
the Configuration utility from
functioning properly.

BIG-IP update and upgrade guide

Chapter 1: Guide contents

Chapter 2: Introduction
Chapter 3: Choose a BIG-IP update or upgrade version
Chapter 4: Prepare to update or upgrade any BIG-IP system
Chapter 5: Update or upgrade a standalone BIG-IP VE system using the Configuration utility
Chapter 6: Update or upgrade a standalone BIG-IP VE system using the TMOS Shell
Chapter 7: Update or upgrade BIG-IP HA systems using the Configuration utility
Chapter 9: Update or upgrade BIG-IP systems using BIG-IQ
Chapter 10: Update or upgrade BIG-IP VIPRION systems (non-vCMP)
Chapter 11: Update or upgrade BIG-IP VIPRION systems (vCMP)
Chapter 12: Update or upgrade BIG-IP appliance systems (vCMP)
Chapter 13: Update or upgrade BIG-IP VE instances in an AWS autoscaling group (F5 AWS
CloudFormation Templates 1.0)
Chapter 14: Upgrade or update BIG-IP VE instances in an AWS autoscaling group (F5 AWS
CloudFormation 2.0)
Chapter 15: Update or upgrade a BIG-IP VE instance on AWS using the f5-aws-migrate.py script
Chapter 16: Update or upgrade a BIG-IP Azure VM using the Azure portal to deploy an ARM template
Chapter 17: Update or upgrade a BIG-IP Azure VM using Terraform to deploy an ARM template
Chapter 18: Update or upgrade a BIG-IP Azure VM using Ansible to deploy an ARM template
Chapter 19: Upgrade or update BIG-IP VE instances in an Azure VMSS (F5 Azure ARM Templates
2.0)
Chapter 20: Update or upgrade a BIG-IP GCP VM using Terraform
Chapter 21: Using F5 Modules for Ansible to update or upgrade BIG-IP system software
Chapter 22: Update or upgrade the BIG-IP Edge Client
Chapter 23: Update or upgrade the F5 SSL Orchestrator
Related Content

About operations guides

Optimizing the support experience