Install a *nix universal forwarder

This topic describes how to install the universal forwarder software on a *nix host, such as Linux, Solaris, or Mac OS X. It assumes that you plan 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

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, 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 full Splunk Enterprise.

Install the universal forwarder on Linux

About the least-privileged user

Running the universal forwarder as a root user is not a security best practice. However, a user running the forwarder as a basic non-root user cannot fully manage the forwarder or add-ons. To resolve this issue, the universal forwarder installer creates "least privileged" users with capabilities specific to running the universal forwarder.

If Splunk is unable to install a least privileged user, it will install as a non-root user. To learn more about how to add, enable, disable, and troubleshoot least privileged users, see Secure your *nix universal forwarder with a least privileged user.

For the universal forwarder to create a least privileged 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

Install on Linux

1. Login as ROOT to the machine that you want to install the Splunk Universal Forwarder.
2. Create the Splunk user and group.

   useradd -m splunk
   groupadd splunk

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 the Splunk Enterprise RPM in the default directory /opt/splunk: 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 you want to run the software.

   chown -R splunk:splunk $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 of 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 the least privileged (non-root) user 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.

If you plan 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, the universal forwarder cannot run because it needs this version of the library.

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

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

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

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 will be 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 finishes, a popup informs you that an initialization must be performed. Click OK.
10. A terminal window appears and you are prompted to specify a userid and password to use with the universal forwarder.

    The password must be at least 8 characters in length. The cursor will not advance as you type.
    Make note of the userid 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 any time.

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

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

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

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. For post-installation configuration and credential creation, see the Configure the universal forwarder chapter in this manual.

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. For post-installation configuration and credential creation, see the Configure the universal forwarder chapter in this manual.

Requirements 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.

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

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. 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. 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
   

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

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

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