Splunk Cloud

Splunk Cloud User Manual

Download manual as PDF

Download topic as PDF

Upgrade your Forwarders

If you are using either heavy or universal forwarders, maintaining version compatibility between your forwarders and Splunk Cloud environment ensures there is no interruption to your service. In addition, when forwarders are version compatible with your Splunk Cloud 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 environment.

The following are the supported forwarder versions for Splunk Cloud:

Forwarder Version Supported Splunk Cloud Versions
7.2.x 7.0.3+, 7.1.x, 7.2.x
7.1.x 7.0.3+, 7.1.x, 7.2.x
7.0.3+ 7.0.3+, 7.1.x, 7.2.x
6.6.x or Less (TLS only) 6.6.3, 7.0.2
6.6.x or Less (non-TLS) None

To upgrade your universal forwarder, use the following instructions:

To upgrade your heavy forwarder, use the following instructions:

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, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud 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.

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 a best practice, run the most recent forwarder version, even if the forwarder is a higher version number than your Splunk Cloud 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 Create and execute the script.

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.

Upgrade the Windows universal forwarder

When you upgrade a universal forwarder, the installer updates the software without changing its configuration. You must make any necessary configuration changes after you complete the upgrade. A deployment server can assist in the configuration update process.

There are several forwarder upgrade scenarios:

  • You can upgrade a single forwarder with the GUI installer
  • You can upgrade a single forwarder with the command line installer
  • You can perform a remote upgrade of a group of forwarders (good for deployments of any size)

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

Prerequisites to upgrading a universal forwarder

Confirm that you understand or have all of the following prior to upgrading a forwarder.

Confirm that an upgrade is necessary

Before you upgrade, consider whether you really need to. In most cases, you do not have to upgrade a forwarder. Forwarders are always compatible with later versions of indexers, so you do not need to upgrade them just because you have upgraded the indexers that they send data to.

A case where you might need to upgrade a forwarder is if a later version of the forwarder includes a feature that is not available in the installed forwarder version.

You must perform any platform architecture changes manually

You cannot upgrade a 32-bit version of the universal forwarder with a 64-bit universal forwarder installer. To upgrade from 32-bit to 64-bit, follow these instructions:

  1. Back up your configurations, including any apps or add-ons (in %SPLUNK_HOME%\etc\apps). Also back up the checkpoint files located in %SPLUNK_HOME%\var\lib\modinputs.
  2. Uninstall the existing 32-bit forwarder, as described in Uninstall the universal forwarder.
  3. Install the 64-bit forwarder, as described in Install a Windows Universal Forwarder from an installer.
  4. Restore apps, configurations and checkpoints by copying them to the appropriate directories:
%SPLUNK_HOME%\etc\system\local for configuration files.
%SPLUNK_HOME%\etc\apps for apps and add-ons.
%SPLUNK_HOME%\var\lib\modinputs for checkpoint files.

Back your files up

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

There is no means of downgrading to a previous version. If you need to revert to an older forwarder release, uninstall the current version and reinstall the older release.

Upgrade a single forwarder using the GUI installer

You can upgrade a single forwarder with the GUI installer. The installer stops the forwarder as part of the upgrade process.

  1. Download the new MSI file from the universal forwarder download page.
  2. Double-click the MSI file. The installer displays the "Accept license agreement" panel.
  3. Accept the license agreement and click "Install." The installer upgrades the forwarder, retains the existing configuration, and starts automatically when you complete the installation.

The installer puts a log of upgrade changes in the %TEMP% directory (This is usually the C:\TEMP directory but can be different based on your Windows machine configuration.) It also reports any errors in the Application Event Log.

Upgrade a single forwarder using the command line

You can upgrade a single forwarder by running the command line installer. To upgrade a group of forwarders, load the command line installer into a deployment tool such as Group Policy or System Center Configuration Manager, as described in Perform a remote upgrade.

You cannot make configuration changes during an upgrade. The installer ignores any command line flags that you specify except for the AGREETOLICENSE flag.

  1. Download the new MSI file from the Splunk universal forwarder download page.
  2. Run msiexec.exe to Install the universal forwarder from the command line.
    • For 32-bit platforms, use splunkuniversalforwarder-<...>-x86-release.msi.
          msiexec.exe /i splunkuniversalforwarder-<...>-x86-release.msi [AGREETOLICENSE=Yes /quiet]
    
    • For 64-bit platforms, use splunkuniversalforwarder-<...>-x64-release.msi.
          msiexec.exe /i splunkuniversalforwarder-<...>-x64-release.msi [AGREETOLICENSE=Yes /quiet]
    

    The value of <...> varies according to the particular release, for example, splunkuniversalforwarder-6.3.0-aa7d4b1ccb80-x64-release.msi.

  3. Wait for the upgrade to complete. The forwarder starts automatically when you complete the installation.

The installer puts a log of upgrade changes in the %TEMP% directory. It also reports any errors in the Application Event Log.

Perform a remote upgrade of one or more forwarders

You can use a deployment tool such as Group Policy or System Center Configuration Manager to distribute the forwarder software among a group of forwarders in your environment. You might want to test the upgrade locally on one machine before performing a remote upgrade across all your forwarders.

See Upgrade using the command line, for details on the command line syntax to use in the deployment tool.

The Splunk Enterprise deployment server cannot distribute the universal forwarder, only its apps and configurations. Do not attempt to use deployment server to distribute universal forwarders.

  1. Download the new MSI file from the Splunk universal forwarder download page.
  2. Load the MSI into your deployment tool. In the tool, specify the command line as follows.
       msiexec.exe /i splunkuniversalforwarder-<...>.msi AGREETOLICENSE=Yes /quiet
    
  3. Start the deployment with your deployment tool.
  4. Use the deployment monitor to verify that the universal forwarders function properly.

Upgrade a Heavy Forwarder on *nix

Before you upgrade

Before you upgrade, see About upgrading to 7.2: 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 environment..

Upgrade a Splunk Heavy Forwarder

  1. Open a shell prompt on the machine that has the instance that you want to upgrade.
  2. Change to the $SPLUNK_HOME/bin directory.
  3. Run the $SPLUNK_HOME/bin/splunk stop command to stop the instance.
  4. Confirm that no other processes can automatically start the Splunk Heavy Forwarder.
  5. 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/parent/directory
    • 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.
  6. 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]
    
  7. 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.
  8. 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 environment..

Before you upgrade

Before you upgrade, see About upgrading to 7.2: 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 Splunk 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.

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 Splunk 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.
PREVIOUS
Manage a rolling restart in Splunk Cloud
 

This documentation applies to the following versions of Splunk Cloud: 6.6.3, 7.0.0, 7.0.2, 7.0.3, 7.0.5, 7.0.8, 7.0.11, 7.1.3, 7.1.6, 7.2.3, 7.2.4, 7.2.6, 7.2.7


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters