Install a *nix universal forwarder

The following tasks describe how to install the universal forwarder software on a *nix host, such as Linux, Solaris, or Mac OS X. These tasks describe how to install directly onto the host, rather than use a deployment tool. This type of deployment best suits these needs:

• Small deployments.
• Proof-of-concept test deployments.
• System image or virtual machine for eventual cloning.

The universal forwarder installation packages are available for download from splunk.com.

On *nix operating systems, the installation comes as a tar file or an installation package (.rpm, .deb, .pkg, etc.)

A tar file contains only the files needed to install and run the universal forwarder and can be installed wherever you have permissions. Installation packages contain logic that checks for software dependencies and install in a predetermined place, depending on your operating system.

To install the universal forwarder on a *nix host, follow the directions later in this topic for your specific OS.

• Install on Linux
• Install on Solaris
• Install on Mac OS X
• Install on FreeBSD
• Install on AIX

Version 9.1.0 deprecates version 3 of the Splunk-to-Splunk protocol. You should upgrade all of your instances if possible, but if you do want to use the old version of the Splunk-to-Splunk protocol, see [http://docs.splunk.com/Documentation/Forwarder/9.3.2/Forwarder/Troubleshoottheuniversalforwarder Troubleshoot the universal forwarder] to learn how to enable that behaviour. With this deprecation introduced in 9.1.0, the latest forwarders will not be able to talk to the indexers running Splunk 7.0 or earlier.

Default installation location

The universal forwarder installs by default in the /opt/splunkforwarder directory. The default installation directory for Splunk Enterprise is /opt/splunk.

About installing with tar files

When you install the universal forwarder using a tar file:

• Some non-GNU versions of tar might not have the -C argument available. In this case, to install in a specific directory, you can either cd to the directory where you want to install the forwarder or place the tar file in that directory before you run the tar command.

• The universal forwarder does not create the splunk user on the machine. If you want the forwarder to run as a specific user, you must create the user manually before you install.

• Confirm that the disk partition has enough space to hold the uncompressed volume of the data you plan to index.

Do not install the universal forwarder over an existing installation of Splunk Enterprise.

Install the universal forwarder on Linux

About the splunkfwd user

Running the universal forwarder as ROOT or SUDO is not a security best practice, as it provides a lot of high-risk permissions that are not necessary to run the universal forwarder. To better secure your configuration, when you install the forwarder on Linux, the universal forwarder installer creates a non-root user called splunkfwd. splunkfwd is a new "least privileged" user that provides only the capabilities necessary to run the universal forwarder.

To learn more about how to add, enable, disable, and troubleshoot splunkfwd users, see Manage a Linux least privileged user.

For the universal forwarder to create a splunkfwd user at installation, your system must meet the following criteria:

• One or more universal forwarders; least privileged mode does not run on other systems or applications.
• systemd version 219 or greater.
• Linux x86_64, ARM, ARM64

Least privileged (splunkfwd) user security and performance implications

Least privilege mode is enabled to read any file permission on Linux version 9.0.0 and later.

A non-root or non-admin user that could not access some files before upgrade to least privilege user, may be able to access those files after upgrade in the following situations:

• You upgrade the universal forwarder from old versions to a least privilege version.
• Before upgrade, your universal forwarder is running as non-root or non-local admin.
• Prior to upgrade, you have inputs to monitor a directory with many files, or inputs with scripts to read many files, where users have no permission to access those files

In addition to security issues, this can lead to potential performance issues. Since the universal forwarder is able to read far more files than before, more resources such as CPU, memory, and disk input/output are consumed.

To avoid this, you can disable the "read any file" capability manually. To do this, edit the unit file to remove the CAP_DAC_READ_SEARCH capability.

Install on Linux

As of Splunk 9.1, the universal forwarder installs a new least privileged user called splunkfwd. This means that the user name for Splunk Enterprise, "Splunk", and your universal forwarder user name, "splunkfwd", will be different. We recommend that you implement the splunkfwd user, however, if your system requires that your Splunk Enterprise and universal forwarder names be identical, see Manage a Linux least-privileged user in this manual.

1. Login as ROOT to the machine on which you want to install the universal forwarder.
2. Create the Splunk user and group.

   useradd -m splunkfwd
   groupadd splunkfwd

3. Install the Splunk software, as described in the installation instructions for your platform in Installation instructions. Create the $SPLUNK_HOME directory wherever desired.

   export SPLUNK_HOME="/opt/splunkforwarder"
   mkdir $SPLUNK_HOME

4. Make sure the splunkforwarder package is present in $SPLUNK_HOME:

   For a tar package:	tar xvzf splunkforwarder_package_name.tgz
   For an rpm package:	If necessary, change permissions on the file: chmod 644 splunkforwarder_package_name.rpm Install in the default directory opt/splunkforwarder: rpm -i splunkforwarder_package_name.rpm
   For a .deb package:	dpkg -i splunkforwarder_package_name.deb

5. Run the chown command to change the ownership of the splunk directory and everything under it to the user that will run the software.

   chown -R splunkfwd:splunkfwd $SPLUNK_HOME

   If you change users, you must run this command again

   .

   If the chown binary on your system does not support changing group ownership for files, you can use the chgrp command instead. See the Man pages on your system for additional information on changing group ownership.

6. Switch to ROOT or SUDO and run

   sudo $SPLUNK_HOME/bin/splunk start

   Or

   sudo $SPLUNK_HOME/bin/splunk start --accept-license

For post-installation configuration and credential creation, see the Configure the universal forwarder chapter in this manual.

Install the universal forwarder on Solaris

The universal forwarder is available for Solaris as a tar file or a PKG file.

To install a universal forwarder on a Sun SPARC system that runs Solaris, confirm that you have patch level SUNW_1.22.7 or later of the C library (libc.so.1). If you do not have this library, the universal forwarder cannot run.

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Install from a tar file

Use the tar command to install the forwarder.

• To install into the folder /opt/splunkforwarder:

1. Uncompress the tar file.

   uncompress splunkforwarder-<version-os-arch>.tar.Z

2. Extract the tar file.

    tar xvf splunkforwarder-<version-os-arch>.tar -C /opt

• To install into the current working directory under the splunkforwarder folder:

1. Uncompress the tar file.

   uncompress splunkforwarder-<version-os-arch>.tar.Z

2. Extract the tar file.

    tar xvf splunkforwarder-<version-os-arch>.tar

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Install the universal forwarder on Mac OS X

The universal forwarder is available for Mac OS X as a tar file or a DMG package.

Install the universal forwarder from the Finder

1. Navigate to the folder or directory where the installer is located.
2. Double-click the DMG file.
   A Finder window that contains the splunkforwarder.pkg opens.
3. Double-click the Install Splunk Universal Forwarder icon to start the installer.
4. The Introduction panel lists version and copyright information. Click Continue.
5. The License panel lists shows the software license agreement. Click Continue.
6. You are asked to agree to the terms of the software license agreement. Click Agree.
7. In the Installation Type panel, click Install. This installs the universal forwarder in the default directory /Applications/SplunkForwarder.
8. You are prompted to type the password that you use to login to your computer.
9. When the installation completes, a popup informs you that an initialization must be performed. Click OK.
10. A terminal window appears and you are prompted to specify a username and password to use with the universal forwarder.

    The password must be at least eight characters in length. The cursor will not advance as you type.
    Make note of your username and password. You will use these credentials to authenticate when using CLI commands on the forwarder.

11. A popup appears asking what you would like to do. Click Start Splunk.
12. Close the Install Splunk Forwarder window.

    The installer places a shortcut on the desktop so that you can start or stop the universal forwarder from your desktop at any time.

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Install from a tar file

Use the tar command to install the forwarder.

• To install the forwarder into the folder /Applications/splunkforwarder, run:

 tar xvzf splunkforwarder.tgz -C /Applications

• To install the forwarder into the current working directory under the splunkforwarder folder, run:

tar xvzf splunkforwarder.tgz

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Install the universal forwarder on FreeBSD

The universal forwarder is available for FreeBSD as a .txz file package.

Prerequisites

FreeBSD best practices maintain a small root filesystem. Verify that the root filesystem has sufficient free space for the universal forwarder installation.

The package installs the forwarder in the default directory, /opt/splunkforwarder. If /opt does not exist, you might receive an error message.

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Basic FreeBSD installation

1. Download the FreeBSD package file from splunk.com (login required.)
2. Install the universal forwarder on FreeBSD using the pkg command:

   pkg install splunkforwarder-<version>-freebsd-<version>-amd64.txz
   

3. Start the universal forwarder service and create a local user and password. See Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

After installing the forwarder on FreeBSD

These instructions ensure that the forwarder functions properly on FreeBSD. If your host has less than 2 GB of memory, reduce the kern.maxdsiz and kern.dfldsiz values accordingly.

1. Add the following to /boot/loader.conf

   kern.maxdsiz="2147483648" # 2GB
   kern.dfldsiz="2147483648" # 2GB
   machdep.hlt_cpus=0 
   

2. Add the following to /etc/sysctl.conf:

   vm.max_proc_mmap=2147483647
   

3. Restart the FreeBSD host for the changes to effect.

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Install the universal forwarder on AIX

The universal forwarder is available for AIX as a tar file. The default installation directory is /opt/splunkforwarder.

Do not use the AIX version of tar to unarchive the file. Use the GNU version instead. The GNU 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. Confirm that the user that the universal forwarder runs as has permission to read the /dev/random and /dev/urandom devices.
2. Expand the tar file into an appropriate directory:

   tar xvzf splunkforwarder-<...>.tgz
   

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.

Enable the universal forwarder to automatically start at boot time

The AIX version of the universal forwarder does not register itself to auto-start on reboot. You can register it by running the following command from the $SPLUNK_HOME/bin directory at a prompt:

./splunk enable boot-start

This command invokes the following system commands to register the forwarder in the System Resource Controller (SRC):

mkssys -G splunk -s splunkd -p <path to splunkd> -u <splunk user> -a _internal_exec_splunkd -S -n 2 -f 9

When you enable automatic boot start, the SRC handles the run state of the forwarder. This means that you must use a different command to start and stop the forwarder manually:

• /usr/bin/startsrc -s splunkd to start the forwarder.
• /usr/bin/stopsrc -s splunkd to stop the forwarder.

If you attempt to start and stop the forwarder using the ./splunk [start|stop] method from the $SPLUNK_HOME directory, the SRC catches the attempt and the forwarder displays the following message:

Splunk boot-start is enabled. Please use /usr/bin/[startsrc|stopsrc] -s splunkd to [start|stop] Splunk.

To prevent this message from occurring and restore the ability to start and stop the forwarder from the $SPLUNK_HOME directory, disable boot start:

./splunk disable boot-start

• For more information on the mkssys command line arguments, see Mkssys command on the IBM pSeries and AIX Information Center website.
• For more information on the SRC, see System resource controller on the IBM Knowledge Center website.

Next steps

Once you have installed the forwarder, see Configure the universal forwarder chapter in this manual to configure your forwarder and create credentials.