Upgrade your Forwarders

If you are using either heavy or universal forwarders, maintaining version compatibility between your forwarders and Splunk Cloud Platform environment ensures there is no interruption to your service. In addition, when forwarders are version compatible with your Splunk Cloud Platform environment, you can immediately take advantage of new capabilities.

As a best practice, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud Platform environment.

To upgrade a heavy or universal forwarder for your Splunk Cloud Platform environment, see the appropriate section in this topic.

See also

For more information about	See
Supported forwarder versions, their compatible Splunk Cloud Platform versions, and respective end-of-support milestone dates	Supported forwarder versions in the Splunk Cloud Platform Service Description
The Splunk universal forwarder	Splunk Universal Forwarder Forwarder Manual
Upgrading a universal forwarder to a heavy forwarder	Upgrade the universal forwarder in the Splunk Universal Forwarder Forwarder Manual

Upgrade the *nix universal forwarder

To upgrade a *nix universal forwarder for a Splunk Cloud Platform deployment, see Upgrade the universal forwarder in the Splunk Universal Forwarder Forwarder Manual.

Upgrade the Windows universal forwarder

To upgrade a Windows universal forwarder for a Splunk Cloud Platform deployment, see Upgrade the universal forwarder in the Splunk Universal Forwarder Forwarder Manual.

Upgrade a heavy forwarder on *nix

This section describes how Splunk Cloud Platform administrators can upgrade a heavy forwarder on a *nix machine for their Splunk Cloud Platform deployment.

Before you upgrade

Before you upgrade, see About upgrading: READ THIS FIRST for information on changes in the new version that can impact you if you upgrade from an existing version.

Your Splunk Heavy Forwarder does not provide a means of downgrading to previous versions. If you need to revert to an older Splunk Forwarder, uninstall the upgraded version and reinstall the version you want.

Back your files up

Before you perform the upgrade, back up all of your files.

For information on backing up configurations, see Back up configuration information in the Splunk Enterprise Admin Manual.

How upgrading works

To upgrade a heavy forwarder installation, you must install the new version directly on top of the old version (into the same installation directory.) When the Splunk Heavy Forwarder starts after an upgrade, it detects that the files have changed and asks whether or not you want to preview the migration changes before it performs the upgrade.

If you choose to view the changes before proceeding, the upgrade script writes the proposed changes to the $SPLUNK_HOME/var/log/splunk/migration.log.<timestamp> file.

Splunk Heavy Forwarder does not change your configuration until after you restart it.

As a best practice, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud Platform environment.

Upgrade a Splunk Heavy Forwarder

1. Download the full version of Splunk Enterprise that you want to upgrade to from the splunk.com website.
2. Open a shell prompt on the machine that has the instance that you want to upgrade.
3. Change to the $SPLUNK_HOME/bin directory.
4. Run the $SPLUNK_HOME/bin/splunk stop command to stop the instance.
5. Confirm that no other processes can automatically start the Splunk Heavy Forwarder.
6. To upgrade and migrate, install the Splunk Heavy Forwarder package directly over your existing deployment.
   
   • If you use a .tar file, expand it into the same directory with the same ownership as your existing Splunk Heavy Forwarder instance. This overwrites and replaces matching files but does not remove unique files. tar xzf splunk-7.x.x-<version-info>.tgz -C $SPLUNK_HOME
   • If you use a package manager, such as RPM, type rpm -U splunk_package_name.rpm
   • If you use a .dmg file on Mac OS X, double-click it and follow the instructions. Specify the same installation directory as your existing installation.
7. Run the $SPLUNK_HOME/bin/splunk start command.
   The Splunk Heavy Forwarder displays the following output.

   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]
   

8. Choose whether or not you want to run the migration preview script to see proposed changes 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.
9. After you review these changes and are ready to proceed with migration and upgrade, run $SPLUNK_HOME/bin/splunk start again.

Upgrade and accept the license agreement simultaneously

After you place the new files in the Splunk Heavy Forwarder installation directory, you can accept the license and perform the upgrade in one command.

• To accept the license and view the expected changes (answer 'n') before continuing the upgrade, use the following command.

$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

Upgrade a heavy forwarder on Windows

You can upgrade with either the GUI installer or the msiexec utility on the command line as described in "Install on Windows via the command line".

Splunk does not provide a means of downgrading to previous versions.

After you upgrade Splunk Heavy Forwarder, if you need to downgrade, you must uninstall the upgraded version and then reinstall the previous version of Splunk Heavy Forwarder that you were using. Do not attempt to install over an upgraded installation with an installer from a previous version, as this can result in a corrupt instance and data loss.

As best practice, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud Platform environment.

Before you upgrade

Before you upgrade, see About upgrading: READ THIS FIRST for information on changes in the new version that can impact you if you upgrade from an existing version.

Splunk Heavy Forwarder does not provide a means of downgrading to previous versions. If you need to revert to an older Splunk Heavy Forwarder release, uninstall the upgraded version and reinstall the version you want.

The Windows domain user must match what you specified at installation

If you installed Splunk Heavy Forwarder with a domain user, you must specify the same domain user explicitly during an upgrade. If you do not, Splunk Heavy Forwarder installs the upgrade as the Local System user. If you do not do this, or you specify the wrong user accidentally during the upgrade, then see Correct the user selected during installation to switch to the correct user before you start Splunk Heavy Forwarder.

Changing heavy forwarder ports during an upgrade is not supported

Splunk Heavy Forwarder does not support changing the management or Splunk Web ports when you upgrade. If you need to change these ports, do so either before or after you upgrade.

Back your files up

Before you upgrade, back up all of your files, including Splunk Heavy Forwarder configurations, indexed data, and binaries.

• For information on backing up configurations, see Back up configuration information in the Admin Manual.

Keep copies of custom certificate authority certificates

When you upgrade on Windows, the installer overwrites any custom certificate authority (CA) certificates that you have created in %SPLUNK_HOME%\etc\auth. If you have custom CA files, back them up before you upgrade. After the upgrade, you can restore them into %SPLUNK_HOME%\etc\auth. After you have restored the certificates, restart Splunk Heavy Forwarder.

Upgrade a heavy forwarder using the GUI installer

1. Download the new MSI file from the Splunk download page.
2. Double-click the MSI file. The installer runs and attempts to detect the existing version of Splunk Heavy Forwarder installed on the machine. When it locates the older version, it displays a pane that asks you to accept the licensing agreement.
3. Accept the license agreement. The installer then installs the updated Splunk Heavy Forwarder. This method of upgrade retains all parameters from the existing installation. By default, the installer restarts Splunk Heavy Forwarder when the upgrade completes and places a log of the changes made to configuration files during the upgrade in %TEMP%.

Upgrade using the command line

1. Download the new MSI file from the Splunk download page.
2. Install the software, as described in Install on Windows via the command line.
   
   • If Splunk runs as a user other than the Local System user, specify the credentials for the user in your command-line instruction with the LOGON_USERNAME and LOGON_PASSWORD flags.
   • You can use the LAUNCHSPLUNK flag to specify whether Splunk Heavy Forwarder should start up automatically or not when the upgrade finishes, but you cannot change any other settings.
   • Do not change the network ports (SPLUNKD_PORT and WEB_PORT) at this time.
3. Depending on your specification, Splunk Heavy Forwarder might start automatically when you complete the installation.