Distributed Deployment Manual

 


Deploy a *nix universal forwarder manually

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Deploy a *nix universal forwarder manually

This topic describes how to manually configure and deploy the universal forwarder in a *nix environment, such as Linux or Solaris. It assumes that you're installing directly onto the *nix machine, rather than using 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

If you are interested in a different deployment scenario, look for another topic in this section that better fits your needs.

Before following the procedures in this topic, read "Deployment overview".

Steps to deployment

Once you have downloaded the universal forwarder and have planned your deployment, as described in "Deployment overview", perform these steps:

1. Install the universal forwarder.

2. Configure (and optionally migrate) the universal forwarder.

3. Test and tune the deployment.

4. Perform any additional post-installation configuration.

Install the universal forwarder

You can install the universal forwarder on a *nix machine using a package or a tar file. To install the universal forwarder on any of the supported *nix environments, see the set of *nix install topics in the Installation manual:

You install the universal forwarder the same way that you install a full Splunk instance, as documented in these topics in the Installation manual. There are only two differences:

  • The package name.
  • The default installation directory.

The package name

When installing a package, substitute the name of the universal forwarder package for the full Splunk package name used in the commands in the Installation manual.

For example, if installing the universal forwarder onto Red Hat Linux, use this command:

rpm -i splunkforwarder_<package_name>.rpm

instead of this command for a full Splunk instance:

rpm -i splunk_<package_name>.rpm

The only difference is the prefix to the package name: "splunkforwarder", instead of "splunk".

The default install directory

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

Important: Do not install the universal forwarder over an existing installation of full Splunk. This is particuarly vital if you will be migrating from a light forwarder as described in "Migrate a nix light forwarder".

Configure the universal forwarder

The universal forwarder can run as any user on the local system. If you run the universal forwarder as a non-root user, make sure that it has the appropriate permissions to read the inputs that you specify. Refer to the instructions for running Splunk as a non-root user for more information.

As part of configuration, you can migrate checkpoint settings from an existing forwarder to the universal forwarder. See "Deployment overview".

Use the Splunk CLI to start and configure your universal forwarders.

Start the universal forwarder

Important: If you want to migrate from an existing forwarder, you must perform a specific set of actions before you start the universal forwarder for the first time. See "Migrate a nix forwarder" for details.

To start the universal forwarder, run the following command from $SPLUNK_HOME/bin directory (where $SPLUNK_HOME is the directory into which you installed the universal forwarder):

splunk start

Accept the license agreement automatically

The first time you start the universal forwarder after a new installation, you must accept the license agreement. To start the universal forwarder and accept the license in one step:

splunk start --accept-license

Note: There are two dashes before the accept-license option.

Configuration steps

After you start the universal forwarder and accept the license agreement, follow these steps to configure it:

1. Configure universal forwarder to auto-start:

splunk enable boot-start

2. Configure universal forwarder to act as a deployment client (optional). To do this, just specify the deployment server:

      splunk set deploy-poll <host>:<port>

where:

  • <host> is the deployment server's hostname or IP address and <port> is the port it's listening on.

This step also automatically enables the deployment client functionality.

3. Configure the universal forwarder to forward to a specific receiving indexer, also known as the "receiver" (optional):

splunk add forward-server <host>:<port> -auth <username>:<password>

where:

  • <host> is the receiving indexer's hostname or IP address and <port> is the port it's listening on. By convention, the receiver listens for forwarders on port 9997, but it can be set to listen on any port, so you'll need to check with the receiver's administrator to obtain the port number. For information on setting up a receiver, see "Enable a receiver".
  • <username>:<password> is the username and password for logging into the forwarder. By default, these are "admin:changeme" (To set a different password than the default , issue the following command "splunk edit user admin -password <new password> -role admin -auth admin:changeme").

During this step, you can also configure a certificate for secure intra-Splunk communications, using a set of optional ssl flags to specify a certificate, root CA, and password. For example:

splunk add forward-server <host>:<port> -ssl-cert-path /path/ssl.crt -ssl-root-ca-path /path/ca.crt -ssl-password <password>

Note: If you do not specify a receiving indexer, be sure to configure universal forwarder to act as a deployment client, as described in step 2, so that it can later be configured for a receiving indexer.

4. To configure the universal forwarder's inputs, use the CLI add command or edit inputs.conf. See "About the CLI" and subsequent topics for details on using the CLI.

For a complete list of CLI commands supported in the universal forwarder, see "Supported CLI commands".

Test the deployment

Test your configured universal forwarder on a single machine, to make sure it functions correctly, before deploying the universal forwarder across your environment. Confirm that the universal forwarder is getting the desired inputs and sending the right outputs to the indexer. You can use the deployment monitor to validate the universal forwarder.

If you migrated from an existing forwarder, make sure that the universal forwarder is forwarding data from where the old forwarder left off. If it isn't, you probably need to modify or add data inputs, so that they conform to those on the old forwarder. Examine the two inputs.conf files to ensure that the new universal forwarder has all the inputs that you want to maintain.

If you migrated from an existing forwarder, you can delete that old instance once your universal forwarder has been thoroughly tested and you're comfortable with the results.

See "Troubleshoot your deployment" for troubleshooting tips.

Perform additional configuration

In addition to using the CLI, you can update the universal forwarder's configuration by editing its configuration files, such as inputs.conf and outputs.conf, directly. See "Deployment overview" for information.

For information on distributing configuration changes across multiple universal forwarders, see "About deployment server".

Deploy the universal forwarder across your environment

If you need just a few universal forwarders, you might find it simpler just to repeat the installation process manually, as documented in this topic. If you need to install a larger number of universal forwarders, however, it will probably be easier to deploy them remotely (using scripting or a deployment tool) or else as part of a system image or virtual machine.

Troubleshoot your deployment

The universal forwarder forwards some internal logs to the receiving indexer. These are:

$SPLUNK_HOME/var/log/splunk/splunkd.log
$SPLUNK_HOME/var/log/splunk/license_audit.log

The logs can be searched on the indexer for errors (index=_internal host=<ua-machine>).

If the universal forwarder is malfunctioning such that it cannot forward the logs, use a text editor or grep to examine them on the universal forwarder machine itself.

This documentation applies to the following versions of Splunk: 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 , 5.0 , 5.0.1 , 5.0.2 , 5.0.3 , 5.0.4 , 5.0.5 , 5.0.6 , 5.0.7 , 5.0.8 , 5.0.9 , 5.0.10 , 5.0.11 View the Article History for its revisions.


Comments

Ganga kn: the instructions for adding an input via the CLI are not in this document, review the help for the CLI command "add". instructions for using the CLI are here: http://docs.splunk.com/Documentation/Splunk/latest/Admin/AbouttheCLI and here:
http://docs.splunk.com/Documentation/Splunk/latest/Admin/GethelpwiththeCLI

there is further information here:
http://docs.splunk.com/Documentation/Splunk/latest/Data/Configureyourinputs#Use_the_CLI

Rachel, Splunker
September 23, 2012

Under Configuration steps, step 4 is not clear. we are not getting how to add inputs to inputs.conf

Ganga kn
July 26, 2012

Doc was wrong; it's been corrected now. Thanks for catching that.

Sgoodman
July 25, 2011

Hi,

I had the same problem as Sminkio and found that it was the the FORWARDER's credentials needed, not the receiver's.

In the doc it clearly says the receiver's, is this wrong?

Kyleharrison
July 25, 2011

even with -auth set correctly i always get "Login Failed".

The remote port is open and there's no firewall.

Sminkio
July 4, 2011

Please update this document to mention the fact that you must supply a username and password in order to run

splunk add forward-server

which by default are admin/changeme

Dland
June 28, 2011

You may want to note that the command "splunk set deploy-poll " requires a default password which is: user=admin password=changeme...

Tomo
May 26, 2011

This document should say that it is going to create a user and group. We centrally manage that.

Mgh4
May 2, 2011

You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!