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_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
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
- 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
- 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
For 32-bit platforms, use
msiexec.exe /i splunkuniversalforwarder-<...>-x86-release.msi [<flag>]... [/quiet]
For 64-bit platforms, use
msiexec.exe /i splunkuniversalforwarder-<...>-x64-release.msi [<flag>]... [/quiet]
The value of
<...> varies according to the particular release; for example,
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|
|| Use this flag to agree to the EULA. This flag must be set to
|| 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
|| Use these flags to provide domain\username and password information for the user to run the
|| 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
|| 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
||Use this flag to specify whether the universal forwarder should be configured to launch automatically when the installation finishes.||1 (yes)|
|| Use this flag to specify whether the universal forwarder should start automatically when the system reboots.
Note: By setting
||Use this flag to specify a file or directory to monitor.||n/a|
|| Use these flags to enable these Windows event logs, respectively:
Note: You can specify multiple flags.
|| Use this flag to enable perfmon inputs.
cpu memory network diskspace
||Use this flag to enable Active Directory monitoring for a remote deployment.||0 (not enabled)|
|| 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
|| Determines whether migration from an existing forwarder will occur during installation. If
||0 (no migration)|
|| Tells Splunk to delete any instance-specific data in preparation for creating a clone of a machine. This invokes the
||0 (do not prepare the instance for cloning.)|
To run the installation silently, add
/quiet to the end of your installation command string. You must also set the
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.
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 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
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:
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, use the Add or Remove Programs option in the Control Panel. In 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.
Deploy a Windows universal forwarder via the installer GUI
Remotely deploy a Windows universal forwarder with a static configuration
This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7