
Deploy a Windows universal forwarder via the command line
This topic describes how to install, configure, and deploy the universal forwarder in a Windows environment using the command line interface. If you prefer to use a GUI installer, see "Deploy a Windows universal forwarder via the installer GUI".
When to install from the command line?
You can manually install the universal forwarder on individual machines from a command prompt or PowerShell window. Here are some scenarios where installing from the command line is useful:
- You want to install the forwarder, but don't want it to start right away.
- You want to automate installation of the forwarder with a script.
- You want to install the forwarder on a system that you will clone later.
- You want to use a deployment tool such as Group Policy or System Center Configuration Manager.
Read the following topics for additional information on installing universal forwarders:
- "Deployment overview" for basics on universal forwarders.
- "Remotely deploy a Windows universal forwarder with a static configuration" for detailed information on using the command line interface with a deployment tool.
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 Windows user the universal forwarder should run as
When you install the universal forwarder, you can select the user it should 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 the forwarder as the Local System user, the forwarder can collect any kind of data that is available on the local machine. It cannot, however, collect data from other machines. This is by design.
You must give the universal forwarder a user 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
Read "Choose the Windows user Splunk should run as" in the Installation Manual for concepts and procedures on the user requirements that must be in place before you collect remote Windows data.
Important: You must choose - and configure - the user that Splunk will run as before attempting to install a universal forwarder for remote Windows data collection. Failure to do so can result in a failed installation.
Configure your Windows environment prior to installation
To configure your Windows environment for the proper installation of the forwarder, follow these steps:
1. Create and configure security groups with the user you want the universal forwarder to run as.
2. Optionally, configure the universal forwarder account as a managed service account.
3. Create and configure Group Policy or Local Security Policy objects for user rights assignments.
4. Assign appropriate security settings.
5. If using Active Directory, deploy the Group Policy object(s) with the updated settings to the appropriate objects.
Note: These steps are high-level procedures only. For step-by-step instructions, read "Prepare your Windows network for a Splunk Enterprise installation as a network or domain user" in the Installation Manual.
Install the universal forwarder
You can install the universal forwarder from the command line by invoking msiexec.exe
, Microsoft's installer program.
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.
Command line flags allow you to configure your forwarder at installation time. Using command line 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 Enterprise instance that the universal forwarder will send data to.
- A 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 Enterprise is a separate executable, with its own installation flags. See "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 Enterprise. 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 Enterprise is |
c:\Program Files\SplunkUniversalForwarder
|
LOGON_USERNAME="<domain\username>"
|
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 installs as the Local System user. See "Choose the Windows user Splunk 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 receiver. This flag accepts only a single receiver. To specify multiple receivers (to implement load balancing), you must instead configure this setting through the CLI or outputs.conf .
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 |
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 |
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 |
auto |
MONITOR_PATH="<directory_path>"
|
Use this flag to specify a file or directory to monitor. | n/a |
|
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) |
|
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 |
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
|
Deletes 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 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 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" in the Updating Splunk Enterprise Instances manual.
Deploy the universal forwarder across your environment
If you need just a few universal forwarders, you might find it simpler just to repeat the command line 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, 8, Server 2008, and Server 2012, 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: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15
Feedback submitted, thanks!