Upgrade the universal forwarder for *nix systems

This topic describes the procedure for upgrading your universal forwarder from version 5.0.x, 6.0.x, 6.1.x, or 6.2.x to 6.3.

This topic describes two upgrade scenarios:

• Upgrade a single forwarder manually
• Perform a remote upgrade of a group of forwarders

For deployments of any size, you will most likely want to use this second scenario.

Before you upgrade

Be sure to read this section before performing an upgrade. Also, read "How to upgrade Splunk Enterprise" in the Installation Manual for up-to-date information and potential issues you might encounter when upgrading.

Confirm that an upgrade is necessary

Before doing an upgrade, consider whether you really need to. In most cases, there's no compelling reason to upgrade a forwarder. Forwarders are always compatible with later version indexers, so you do not need to upgrade them just because you've upgraded the indexers they're sending data to.

Back your files up

Before you perform the upgrade, back up your configuration files. For information on backing up configurations, read "Back up configuration information" in the Admin manual.

Splunk Enterprise does not provide a means of downgrading to a previous version; if you need to revert to an older forwarder release, just reinstall it.

How upgrading works

After performing the installation of the new version, configuration changes do not occur until you start the universal forwarder. 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

1. Execute the stop command:

     $SPLUNK_HOME/bin/splunk stop

Important: Make sure no other processes can start the forwarder automatically (such as Solaris SMF).

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

• If you use a .tar file, 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 a package manager, such as an RPM, type in rpm -U <splunk_package_name>.rpm from a shell prompt.
• If you use a .dmg file (on MacOS), double-click it and follow the instructions. Be sure to specify the same installation directory as your existing installation.
• If you use init scripts, be sure to include the following so the End-User License Agreement (EULA) gets accepted:

      ./splunk start --accept-license

3. Execute the start command:

     $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.

5. If you choose to view the expected changes, the script provides a list.

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

Note: You can complete Steps 3 to 5 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 upgrade a group of forwarders across your environment:

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

2. Create a script wrapper for the upgrade commands, as described in "Remotely deploy a nix universal forwarder with a static configuration" in the Forwarding Data manual. You will need to modify the sample script to meet the needs of an upgrade.

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.

5. Verify that the universal forwarders are functioning properly.