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.) Choose the package type that suits your needs and you are comfortable with.

In general, 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

Considerations for installing the universal forwarder

When you perform an installation of the universal forwarder, note the following caveats:

Default installation location

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

Installation of the universal forwarder as a non-root user

The instructions for installing a universal forwarder for a non-root user are the same as installation of Splunk Enterprise as a non-root user. The only difference will be the default destination folder. See Run Splunk Enterprise as a different or non-root user in the Installation Manual.

Installation 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 Splunk Enterprise

Do not install the universal forwarder over an existing installation of full Splunk Enterprise. This is particularly vital if you plan to migrate from a light forwarder as described in "Migrate a nix light forwarder".

Install the universal forwarder on Linux

The universal forwarder is available for Linux as a tar file, an RPM package, and a DEB package.

Install from a tar file

Use the tar command to install the forwarder.

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

tar xvzf splunkforwarder-<…>-Linux-x86_64.tgz -C /opt

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

tar xvzf splunkforwarder-<…>-Linux-x86_64.tgz

For post-installation configuration and credential creation, see After you install: Start and configure the universal forwarder.

Install from a RedHat Package Manager (RPM) package

Use the rpm command to install the forwarder.

• To install the forwarder RPM package into the default directory /opt/splunkforwarder:

rpm -i splunkforwarder-<…>-linux-2.6-x86_64.rpm

For post-installation configuration and credential creation, see After you install: Start and configure the universal forwarder.

Install from a Debian package management (DEB) file

Use the dpkg command to install the forwarder DEB package.

• To install the forwarder DEB package in the default directory /opt/splunkforwarder:

dpkg -i splunk_package_name.deb

The DEB package only supports installation into: /opt/splunkforwarder

For post-installation configuration and credential creation, see After you install: Start and configure the universal forwarder.

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.

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 After you install: Start and configure the universal forwarder.

Install from a Solaris PKG file

The PKG installation includes a request file that asks you a few questions before installation starts.

1. Uncompress the PKG file.

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

2. Run the installer.

   pkgadd -d ./splunkforwarder-<version-os-arch>.pkg 

3. The installer displays a list of available packages. Select the default (all packages) or select only the packages you want.
4. Specify an installation directory. Enter a path and directory to install the forwarder into, or leave it blank to install to the default directory /opt/splunkforwarder.

For post-installation configuration and credential creation, see After you install: Start and configure the universal forwarder.

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.

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 After you install: Start and configure the universal forwarder.

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.

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 After you install: Start and configure the universal forwarder.

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.

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
   

Enable automatic starting of the universal forwarder 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.

After you install: Start and configure the universal forwarder

After you complete the installation of the universal forwarder, you must configure it before it can do anything.

You can configure the forwarder from the command line or by using configuration files. If you want to configure from the command line, the forwarder must be running.

1. Start the universal forwarder, accept the license agreement, and provide credentials. See Start the universal forwarder.
2. Configure the universal forwarder, either from the command line or with a configuration file. See Configure the universal forwarder or Configure forwarding with outputs.conf.
3. Restart the forwarder service to enable the configuration changes you made.