Deploy a *nix universal forwarder manually
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:
- Install on Linux
- Install on Solaris
- Install on Mac OS
- Install on FreeBSD
- Install on AIX
- Install on HP-UX
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
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):
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
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>
<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>
<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
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:
The logs can be searched on the indexer for errors (
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