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
- Download the full version of Splunk Enterprise that you want to upgrade to from the splunk.com website.
- Open a shell prompt on the machine that has the instance that you want to upgrade.
- Change to the
$SPLUNK_HOME/bin
directory. - Run the
$SPLUNK_HOME/bin/splunk stop
command to stop the instance. - Confirm that no other processes can automatically start the Splunk Heavy Forwarder.
- 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.
- If you use a
- 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]
- 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.
- 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
- Download the new MSI file from the Splunk download page.
- 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.
- 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
- Download the new MSI file from the Splunk download page.
- 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
andLOGON_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
andWEB_PORT
) at this time.
- 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
- Depending on your specification, Splunk Heavy Forwarder might start automatically when you complete the installation.
Forward data from files and directories to Splunk Cloud Platform | Configure IP allow lists using Splunk Web |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!