Splunk® Enterprise

Distributed Deployment Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Deploy a Windows universal forwarder via the commandline

This topic describes how to install, configure, and deploy the universal forwarder in a Windows environment using the commandline interface. If you prefer to use a GUI installer, see "Deploy a Windows universal forwarder via the installer GUI".

You can use the commandline interface to install manually on individual machines. You must use it if you want to install the universal forwarder across your system via a deployment tool. See "Remotely deploy a Windows universal forwarder with a static configuration" for detailed information on using the commandline interface with a deployment tool.

Important: If you do not want the universal forwarder to start immediately after installation, you must use the commandline interface and include the LAUNCHSPLUNK=0 flag. This is useful if you'll be cloning the system image. Using the right combination of commandline flags, as discussed below, you can specify that the universal forwarder start for the first time after the image is installed on each clone. This ensures that the original master itself does not forward data to an indexer -- behavior that might not be desired, depending on your particular environment.

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 (with optional migration and configuration).

2. Test and tune the deployment.

3. Perform any post-installation configuration.

4. Deploy the universal forwarder across your environment.

Before you install

Choose the user the universal forwarder should run as

When you install the universal forwarder, you can select a user it will run as. By default, the user is Local System. To specify a domain account, use the flags LOGON_USERNAME and LOGON_PASSWORD, described later in this topic.

If you install as the Local System user, the universal forwarder will have access to all or nearly all of the important information on your local machine. However, the Local System user has no privileges on other Windows machines by design.

You must give the universal forwarder a domain account if you intend to do any of the following:

  • Read Event Logs remotely
  • Collect performance counters remotely
  • Read network shares for log files
  • Enumerate the Active Directory schema, using Active Directory monitoring

The domain account you use must also be a member of the local Administrators group. This is particularly important for installation on versions of Windows prior to Windows Server 2008 - failure to give the universal forwarder account access to the local Administrators group can cause universal forwarder to fail to function properly.

If you're not sure which account to run the universal forwarder under, speak with your Windows domain administrator about the best way to proceed. If you are the domain administrator, then start off by using an account that has at most the permissions described here, and add rights as needed until you get the results you want.

Important: If you decide to change the user that the universal forwarder runs as after you have installed, you must ensure that the new user has the necessary resource access rights, and Full Control permissions to the entire %SPLUNK_HOME% directory.

Security and remote access considerations

In the interests of security, Splunk strongly recommends that you create and place the universal forwarder account into a domain group, and then place that group into local groups on workstations and member servers, when assigning rights for the universal forwarder account. This helps maintain security integrity and makes it a lot easier to control access in the event of a security breach or site-wide change.

The following is a list of the minimum local permissions required by the universal forwarder account. Depending on the sources of data you need to access, the universal forwarder account may need a significant amount of additional permissions.

Required basic permissions for the SplunkForwarder service:

  • Full control over Splunk's installation directory
  • Read access to any flat files you want to index

Required Local Security Policy user rights assignments for the splunkd service:

  • Permission to log on as a service
  • Permission to log on as a batch job
  • Permission to replace a process-level token
  • Permission to act as part of the operating system
  • Permission to bypass traverse checking

Using Group Policy to assign user rights domain-wide

If you want to assign the policy settings shown above to all member servers in your AD domain, you can define a Group Policy object (GPO) for these specific rights and deploy that GPO across the domain or forest using the Domain Security Policy MMC snap-in (use the Domain Controller Security Policy snap-in for domain controllers). The member servers in your domain will pick up the changes either during the next scheduled AD replication cycle (usually every 2-3 hours), or at the next boot time.

Remember that identical Local Security Policy user rights defined on a member server are overwritten by the rights inherited from a GPO, and you can't change this setting. If you wish to retain previously existing rights defined on your member servers, they'll also need to be assigned within the GPO.

Troubleshooting permissions issues

The rights described above are the rights that the SplunkForwarder service specifically invokes. Other rights may be required depending on your usage and what data you want to access. Additionally, many user rights assignments and other Group Policy restrictions can prevent the universal forwarder from working properly. If you have issues, consider using a tool such as Process Monitor to troubleshoot your environment. You can use the GPRESULT command line tool or the Group Policy Management Console (GPMC) to troubleshoot issues related to GPO application in your enterprise.

Install the universal forwarder

You can install the universal forwarder from the commandline by invoking msiexec.exe.

For 32-bit platforms, use splunkuniversalforwarder-<...>-x86-release.msi:

msiexec.exe /i splunkuniversalforwarder-<...>-x86-release.msi [<flag>]... [/quiet]

For 64-bit platforms, use splunkuniversalforwarder-<...>-x64-release.msi:

msiexec.exe /i splunkuniversalforwarder-<...>-x64-release.msi [<flag>]... [/quiet]

The value of <...> varies according to the particular release; for example, splunkuniversalforwarder-4.2-86454-x64-release.msi.

Important: Running the 32-bit version of the universal forwarder on a 64-bit platform is not recommended. If you can run 64-bit universal forwarder on 64-bit hardware, we strongly recommend it. The performance is greatly improved over the 32-bit version.

Commandline flags allow you to configure your forwarder at installation time. Using commandline flags, you can specify a number of settings, including:

  • The user the universal forwarder runs as. (Be sure the user you specify has the appropriate permissions to access the content you want to forward.)
  • The receiving Splunk instance that the universal forwarder will send data to.
  • A Splunk deployment server for updating the configuration.
  • The Windows event logs to index.
  • Whether the universal forwarder should start automatically when the installation is completed.
  • Whether to migrate checkpoint data from an existing light forwarder.

The following sections list the flags available and provide a few examples of various configurations.

List of supported flags

Important: The installer for the full version of Splunk is a separate executable, with its own installation flags. Review the installation flags for the full Splunk installer at "Install on Windows" in the Installation Manual.

Flag What it's for Default
AGREETOLICENSE=Yes|No Use this flag to agree to the EULA. This flag must be set to Yes for a silent installation. No
INSTALLDIR="<directory_path>" Specifies the installation directory.

Important: Do not install the universal forwarder over an existing installation of full Splunk. This is particularly vital if you are migrating from a light forwarder as described in "Migrate a Windows light forwarder". The default install directory for full Splunk is C:\Program Files\Splunk, so, if you stick with the defaults, you're safe.

c:\Program Files\SplunkUniversalForwarder
LOGON_USERNAME="<domain\username>"

LOGON_PASSWORD="<pass>"

Use these flags to provide domain\username and password information for the user to run the SplunkForwarder service. You must specify the domain with the username in the format: domain\username. If you don't include these flags, the universal forwarder will run as Local System user. See "Choose the user the universal forwarder should run as". n/a
RECEIVING_INDEXER="<host:port>" Use this flag to specify the receiving indexer to which the universal forwarder will forward data. Enter the name (hostname or IP address) and receiving port of the Splunk receiver. For information on setting up a receiver, see "Enable a receiver".

Note: This flag is optional, but if you don't specify it and also don't specify DEPLOYMENT_SERVER, the universal forwarder will be unable to function, as it will not have any way of determining which indexer to forward to.

n/a
DEPLOYMENT_SERVER="<host:port>" Use this flag to specify a deployment server for pushing configuration updates to the universal forwarder. Enter the deployment server's name (hostname or IP address) and port.

Note: This flag is optional, but if you don't specify it and also don't specify RECEIVING_INDEXER, the universal forwarder will be unable to function, as it will not have any way of determining which indexer to forward to.

n/a
LAUNCHSPLUNK=1|0 Use this flag to specify whether the universal forwarder should be configured to launch automatically when the installation finishes. 1 (yes)
SERVICESTARTTYPE=auto|manual Use this flag to specify whether the universal forwarder should start automatically when the system reboots.

Note: By setting LAUNCHSPLUNK to 0 and SERVICESTARTTYPE to auto, you will cause the universal forwarder to not start forwarding until the next system boot. This is useful when cloning a system image.

auto
MONITOR_PATH="<directory_path>" Use this flag to specify a file or directory to monitor. n/a


WINEVENTLOG_APP_ENABLE=1|0

WINEVENTLOG_SEC_ENABLE=1|0

WINEVENTLOG_SYS_ENABLE=1|0

WINEVENTLOG_FWD_ENABLE=1|0

WINEVENTLOG_SET_ENABLE=1|0

Use these flags to enable these Windows event logs, respectively:

application

security

system

forwarders

setup

Note: You can specify multiple flags.

0 (no)
PERFMON=<input_type>,<input_type>,... Use this flag to enable perfmon inputs. <input_type> can be any of these:
cpu
memory
network
diskspace
n/a
ENABLEADMON=1|0 Use this flag to enable Active Directory monitoring for a remote deployment. 0 (not enabled)


CERTFILE=<c:\path\to\certfile.pem>

ROOTCACERTFILE=<c:\path\to\rootcacertfile.pem>

CERTPASSWORD=<password>

Use these flags to supply SSL certificates:

Path to the cert file that contains the public/private key pair.

Path to the file that contains the Root CA cert for verifying CERTFILE is legitimate (optional).

Password for private key of CERTFILE (optional).

Note: You must also set RECEIVING_INDEXER for these flags to have any effect.

n/a
MIGRATESPLUNK=1|0 Determines whether migration from an existing forwarder will occur during installation. If MIGRATESPLUNK=1, the installer stops the existing forwarder and copies its checkpoint files to the new universal forwarder. You are responsible for uninstalling the old forwarder. See "Deployment overview" and "Migrate a Windows light forwarder" for details. 0 (no migration)
CLONEPREP=1|0 Tells Splunk to delete any instance-specific data in preparation for creating a clone of a machine. This invokes the splunk clone-prep command from the CLI. 0 (do not prepare the instance for cloning.)

Silent installation

To run the installation silently, add /quiet to the end of your installation command string. You must also set the AGREETOLICENSE=Yes flag.

If your system is running UAC (which is sometimes on by default), you must run the installation as Administrator. To do this, when opening a cmd prompt, right click and select "Run As Administrator". Then use the cmd window to run the silent install command.

Examples

The following are some examples of using different flags.

Install the universal forwarder to run as the Local System user and request configuration from deploymentserver1

You might do this for new deployments of the forwarder.

msiexec.exe /i splunkuniversalforwarder_x86.msi DEPLOYMENT_SERVER="deploymentserver1:8089" AGREETOLICENSE=Yes /quiet

Install the universal forwarder to run as a domain user, but do not launch it immediately

You might do this when preparing a sample host for cloning.

msiexec.exe /i splunkuniversalforwarder_x86.msi LOGON_USERNAME="AD\splunk" LOGON_PASSWORD="splunk123" DEPLOYMENT_SERVER="deploymentserver1:8089" LAUNCHSPLUNK=0 AGREETOLICENSE=Yes /quiet

Install the universal forwarder, enable indexing of the Windows security and system event logs, and run the installer in silent mode

You might do this to collect just the Security and System event logs through a "fire-and-forget" installation.

msiexec.exe /i splunkuniversalforwarder_x86.msi RECEIVING_INDEXER="indexer1:9997" WINEVENTLOG_SEC_ENABLE=1 WINEVENTLOG_SYS_ENABLE=1 AGREETOLICENSE=Yes /quiet

Install the universal forwarder, migrate from an existing forwarder, and run the installer in silent mode

You might do this if you want to migrate now and redefine your inputs later, perhaps after a validation step.

msiexec.exe /i splunkuniversalforwarder_x86.msi RECEIVING_INDEXER="indexer1:9997" MIGRATESPLUNK=1 AGREETOLICENSE=Yes /quiet

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

Important: Migration does not automatically copy any configuration files; you must set those up yourself. The usual way to do this is to copy the files, including inputs.conf, from the old forwarder to the universal forwarder. Compare the inputs.conf files on the universal forwarder and the old forwarder to ensure that the 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.

Perform additional configuration

You can update your universal forwarder's configuration, post-installation, by directly editing its configuration files, such as inputs.conf and outputs.conf. You can also update the configuration using the CLI. See "Deployment overview" for information.

Note: When you use the CLI, you might need to authenticate into the Splunk forwarder to complete commands. The default credentials for a universal forwarder are:

Username: admin
Password: changeme

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 commandline installation process manually, as documented in this topic. If you need to install a larger number of universal forwarders, it will probably be easier to deploy them remotely with a deployment tool or else as part of a system image or virtual machine.

Uninstall the universal forwarder

To uninstall the universal forwarder, perform the following steps:

1. Stop the service from the command line with the following command:

NET STOP SplunkForwarder

Note: You can also use the Services MMC snap-in (Start > Administrative Tools > Services) to stop the SplunkForwarder service.

2. Next, use the Add or Remove Programs control panel to uninstall the forwarder. On Windows 7 and Windows Server 2008, that option is available under Programs and Features.

Note: Under some circumstances, the Microsoft installer might present a reboot prompt during the uninstall process. You can safely ignore this request without rebooting.

PREVIOUS
Deploy a Windows universal forwarder via the installer GUI
  NEXT
Remotely deploy a Windows universal forwarder with a static configuration

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters