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.
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.2.1/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 eithercd
to the directory where you want to install the forwarder or place the tar file in that directory before you run thetar
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.
- Login as ROOT to the machine on which you want to install the universal forwarder.
- Create the Splunk user and group.
useradd -m splunkfwd groupadd splunkfwd
- 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
- 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
- If necessary, change permissions on the file:
- 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 thechgrp
command instead. See the Man pages on your system for additional information on changing group ownership. - 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
:
- Uncompress the tar file.
uncompress splunkforwarder-<version-os-arch>.tar.Z
- Extract the tar file.
tar xvf splunkforwarder-<version-os-arch>.tar -C /opt
- To install into the current working directory under the
splunkforwarder
folder:
- Uncompress the tar file.
uncompress splunkforwarder-<version-os-arch>.tar.Z
- 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
- Navigate to the folder or directory where the installer is located.
- Double-click the DMG file.
A Finder window that contains thesplunkforwarder.pkg
opens. - Double-click the
Install Splunk Universal Forwarder
icon to start the installer. - The Introduction panel lists version and copyright information. Click Continue.
- The License panel lists shows the software license agreement. Click Continue.
- You are asked to agree to the terms of the software license agreement. Click Agree.
- In the Installation Type panel, click Install. This installs the universal forwarder in the default directory
/Applications/SplunkForwarder
. - You are prompted to type the password that you use to login to your computer.
- When the installation completes, a popup informs you that an initialization must be performed. Click OK.
- 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. - A popup appears asking what you would like to do. Click Start Splunk.
- 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
- Download the FreeBSD package file from splunk.com (login required.)
- Install the universal forwarder on FreeBSD using the
pkg
command:pkg install splunkforwarder-<version>-freebsd-<version>-amd64.txz
- 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.
- Add the following to
/boot/loader.conf
kern.maxdsiz="2147483648" # 2GB kern.dfldsiz="2147483648" # 2GB machdep.hlt_cpus=0
- Add the following to
/etc/sysctl.conf
:vm.max_proc_mmap=2147483647
- 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.
- Confirm that the user that the universal forwarder runs as has permission to read the
/dev/random
and/dev/urandom
devices. - 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.
Install a Windows universal forwarder | Upgrade the universal forwarder |
This documentation applies to the following versions of Splunk® Universal Forwarder: 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1
Feedback submitted, thanks!