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

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 and accept the license agreement. 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 to enable the configuration changes that you made.

Install the universal forwarder on Linux

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

Install from a tar file

1. Expand the tar file into an appropriate directory using the tar command. The default installation location is splunk in the current working directory.

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

2. To install into /opt/splunkforwarder, run:

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

Install from a RedHat Package Manager (RPM) package

1. Confirm that the rpm package you want to install from is available locally on the target host and that the user that runs the forwarder can read it.
2. Use the rpm program to install RPM files. To install the Splunk RPM in the default directory /opt/splunkforwarder:

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

Install from a Debian package management (DEB) file

1. Use the dpkg tool to install the Splunk DEB package. dpkg only lets you install the DEB package into the default location, /opt/splunkforwarder.

   dpkg -i splunk_package_name.deb
   

Install the universal forwarder on Solaris

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

Install from a tar file

1. Expand the tar file into an appropriate directory using the tar command. The default install directory is splunk in the current working directory.

   tar xvzf splunk_package_name.tar.Z
   

To install into /opt/splunkforwarder, run:

tar xvzf splunk_package_name.tar.Z -C /opt

Install from a Solaris PKG file

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

1. Run the installer.

   pkgadd -d ./splunk_product_name.pkg
   

   The installer displays a list of available packages.

2. Select the packages you want to process (the default is "all").
3. Specify a base installation directory.
4. To install into the default directory, /opt/splunkforwarder, leave this blank. Otherwise, enter the directory that you want to install the 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. Double-click on the DMG file. A Finder window that contains splunkforwarder.pkg opens.
2. In the Finder window, double-click on splunkforwarder.pkg. The installer opens and displays the Introduction, which lists version and copyright information.
3. Click Continue.
4. Choose a location to install the universal forwarder.
   • To install in the default directory, click on the harddrive icon.
   • To select a different location, click Choose Folder...
5. Click Continue. The pre-installation summary displays.
6. (Optional) To make changes, click Change Install Location to choose a new folder, or Back to go back a step. Otherwise, click Install. The installation starts. It might take a few minutes to complete.
7. Click Finish. The installer places a shortcut on the Desktop.

Install the universal forwarder from a Terminal window

To install the universal forwarder on Mac OS X from the command line, you must use the root user, or elevate privileges using the sudo command. If you use sudo, your account must be an Admin-level account.

1. Open a Terminal window.
2. Mount the DMG:

   sudo hdid splunk_package_name.dmg
   

   The Finder mounts the disk image onto the desktop. The image is available under /Volumes/SplunkForwarder <version> (note the space).

3. Run the installer:

   cd /Volumes/SplunkForwarder\ <version>
   sudo installer -pkg .payload/splunk.pkg -target <target>
   

   Note: There is a space in the disk image name. Use a backslash to escape the space or wrap the disk image name in quotes.

   -target specifies a target volume, such as another disk, where the forwarder will be installed in /Applications/splunk.

To install into a directory other than /Applications/splunk on any volume, use the graphical installer as described above.

Install from a tar file

1. Open a Terminal window.
2. Expand the tar file into an appropriate directory using the tar command:

   tar xvzf splunkforwarder.tgz
   

The default install directory is splunk in the current working directory. To install into /Applications/splunk, use the following command:

tar xvzf splunkforwarder.tgz -C /Applications

Install the universal forwarder on FreeBSD

The universal forwarder is available for FreeBSD as a tar file.

Prerequisites for installing the universal forwarder on FreeBSD

For FreeBSD 8, only, the universal forwarder requires compatibility packages. To install the compatibility package:

1. Install the port: portsnap fetch update cd /usr/ports/misc/compat7x/ && make install clean
2. Add the package: pkg_add -r compat7x-amd64

Basic FreeBSD installation

FreeBSD best practices maintain a small root filesystem. You might want to create a symbolic link to another filesystem and install Splunk there, rather than attempting to install in /opt.

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

1. Confirm that the /opt/splunkforwarder directories exist.
2. If the directories do not exist, create them or link to another file system from there.
3. Install the universal forwarder on FreeBSD using the intel installer:

   pkg_add splunkforwarder-intel.tgz
   

To install the forwarder in a different directory:

pkg_add -v -p /usr/splunk splunkforwarder-intel.tgz

Install from a tar file

Expand the universal forwarder tar file into an appropriate directory using the tar command. The default install directory is splunkforwarder in the current working directory.

tar xvzf splunkforwarder.tgz

To install into /opt/splunkforwarder, execute:

tar xvzf splunkforwarder.tgz -C /opt

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

Considerations for installing the universal forwarder

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

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

Sun SPARC systems that run Solaris require a minimum patch level to install a universal forwarder

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.

Default installation location

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

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