Upgrade the *nix universal forwarder

You have several scenarios for upgrading a *nix universal forwarder:

• Upgrade a single forwarder manually.
• Perform a remote upgrade of a group of forwarders. (Use this option for deployments of any size)

As best practice when upgrading a *nix universal forwarder on Splunk Cloud Platform, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud Platform environment.

Prerequisites to upgrading a *nix universal forwarder

Read this section before performing an upgrade. Also, see How to upgrade Splunk Enterprise for up-to-date information and potential issues you might encounter when you upgrade Splunk Enterprise.

Confirm that an upgrade is necessary

Begin by checking the forwarder compatibility. To determine if you need to upgrade your forwarder version to remain in support or use specific features, see the appropriate topic for your deployment:

• Splunk Cloud Platform: Supported forwarder versions in the Splunk Cloud Platform Service Description
• Splunk Enterprise: Compatibility between forwarders and Splunk Enterprise indexers.

If your forwarders are on the same major release of Splunk software as the indexers, they are compatible. However, you might need an upgrade to a different minor release due to a technical issue in a specific feature. Before upgrading forwarders, review the Known Issues and Fixed Issues.

Back your files up

Before you perform the upgrade, back up your configuration files. See Back up configuration information in the Splunk Enterprise Admin Manual.

If you need to revert to an older forwarder release, uninstall the upgrade and reinstall the older release.

Make sure no other processes can start the forwarder automatically

Confirm that you do not have scripts in place to auto-start forwarders. If you do, disable such scripts for now. You can re-enable them later, after the upgrade.

How upgrading works

After you perform the installation of the new forwarder, you must restart it for any changes to take effect. You can run the migration preview utility at that time to see what will change before the files are updated. If you choose to view the changes before proceeding, the forwarder writes the proposed changes to $SPLUNK_HOME/var/log/splunk/migration.log.<timestamp>

Upgrade a single forwarder

There are several packages that you can use to upgrade a universal forwarder. Tar files and pre-built package such as an .rpm, .deb, or .dmg file are available depending on the operating system.

If you use a .tar file to upgrade a forwarder, expand it into the same directory with the same ownership as the existing universal forwarder instance. This overwrites and replaces matching files but does not remove unique files.

If you use an RPM file, use the RPM package manager (rpm -U <splunk_package_name>.rpm) from a shell prompt to perform the upgrade.

If you use a .dmg file (on MacOS), double-click it and follow the instructions. After the installation starts, specify the same installation directory as your existing installation.

On hosts that run AIX, do not use the AIX version of tar to unarchive a tar file during an upgrade. Use the GNU version of tar instead. This version comes with the AIX Toolbox for Linux Applications package that comes with a base AIX installation. If your AIX does not come with this package installed, you can download it from IBM. See IBM AIX Toolbox download information.

1. Stop the forwarder.

     $SPLUNK_HOME/bin/splunk stop

2. Install the universal forwarder package directly over the existing deployment.

As best practice when upgrading a *nix universal forwarder on Splunk Cloud Platform, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud Platform environment.

3. Start the forwarder again.

     $SPLUNK_HOME/bin/splunk start

The forwarder displays the following:

This appears to be an upgrade of Splunk.
--------------------------------------------------------------------------------
Splunk has detected an older version of Splunk installed on this machine. To
finish upgrading to the new version, Splunk's installer will automatically
update and alter your current configuration files. Deprecated configuration
files will be renamed with a .deprecated extension.
You can choose to preview the changes that will be made to your configuration
files before proceeding with the migration and upgrade:
If you want to migrate and upgrade without previewing the changes that will be
made to your existing configuration files, choose 'y'.
If you want to see what changes will be made before you proceed with the
upgrade, choose 'n'.
Perform migration and upgrade without previewing configuration changes? [y/n]

4. Choose whether you want to run the migration preview script to see what changes will be made to your existing configuration files, or proceed with the migration and upgrade right away. If you choose to view the expected changes, the script provides a list of those changes.

5. Once you have reviewed these changes and are ready to proceed with migration and upgrade, run $SPLUNK_HOME/bin/splunk start again.

You can complete the last three steps in one line.

• To accept the license and view the expected changes (answer 'n') before continuing the upgrade:

      $SPLUNK_HOME/bin/splunk start --accept-license --answer-no

• To accept the license and begin the upgrade without viewing the changes (answer 'y'):

      $SPLUNK_HOME/bin/splunk start --accept-license --answer-yes

Perform a remote upgrade

To perform a remote upgrade, first perform an upgrade on a test machine. Then, create a script to automate the upgrade on remote machines. You can use the sample script that is in the Install a nix universal forwarder remotely with a static configuration topic, but you might need to modify the script to meet the needs of an upgrade.

1. Upgrade the universal forwarder on a test machine, as described in Upgrade a single forwarder.

2. Create a script wrapper for the upgrade commands, as described in the "Create and execute the universal forwarder installation wrapper script" section of Install a nix universal forwarder remotely with a static configuration.

3. Run the script on representative target machines to verify that it works with all required shells.

4. Execute the script against the desired set of hosts.