
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.
- You run a version of Windows Server Core.
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 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.
You can also install the forwarder as a user who is not an administrator on the local machine. Use the SET_ADMIN_USER
installation flag to install the forwarder in "low privilege" mode.
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 runs 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 install the universal forwarder from the command line by invoking msiexec.exe
, the Microsoft 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
.
Note: Do not attempt to install the 32-bit version of the universal forwarder on a 64-bit platform. The installer warns you with an error if you try.
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.)
- Whether or not the forwarder runs in "low-privilege" mode - as a user who does not have local administrative access.
- 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.
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. |
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:
|
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: These flags require that you set |
n/a |
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.) |
SET_ADMIN_USER=1|0
|
Specifies whether or not the user you specify is an administrator. If you set this flag to 0, it allows the universal forwarder to run in "low-privilege" mode - as a user without administrator privileges on the local machine. This mode is available for customers that do not have the ability to run programs as an administrator on servers. Read "Run the universal forwarder in low-privilege mode" later in this topic for additional information and caveats.
Important: This flag requires that you set both the |
1 (Install the universal forwarder as a user with administrative privileges. The universal forwarder runs in normal mode and not "low-privilege" mode.) |
Install the universal forwarder in "low-privilege" mode
When you set the LOGON_USERNAME
and LOGON_PASSWORD
flags and specify SET_ADMIN_USER=0
, the forwarder installs and runs in "low-privilege" mode. This means that the user you specify does not need to have administrative privileges on the server that runs the forwarder.
There are some caveats to doing so:
- You do not have administrative access to any resources on either the server or the domain when you run the universal forwarder in low-privilege mode.
- You might need to add the domain user to additional domain groups in order to access remote resources. Additionally, you might need to add the user to local groups to access local resources that only privileged users would have access to.
- You cannot collect Windows Management Instrumentation (WMI) data as a non-admin user.
Install the universal forwarder silently
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 has UAC enabled (the default on some systems), you must run the installation as Administrator. To do this, when opening a commandd prompt, right click and select "Run As Administrator". Then use the command prompt to run the silent install command.
Enable verbose logging during installation
To provide verbose logging during a universal forwarder installation, use the /l
option provided by msiexec
Review the examples below for details.
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 in low-privilege mode and enable verbose installation logging to a log file
You might do this when you need to run the forwarder as a user who does not have administrative privileges on the local server.
msiexec.exe /i splunkuniversalforwarder_x64.msi /l*v install_splunkforwarder-6.1-201357-x64-release.msi.log LOGON_USERNAME=adtest1\lowpriv-testuser LOGON_PASSWORD=win1@splunk AGREETOLICENSE=Yes SET_ADMIN_USER=0 /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, run the Microsoft Installer to perform the uninstall:
msiexec /uninstall|x splunkuniversalforwarder-<...>-x86-release.msi
The installer has one supported flag that you can use during uninstallation:
Flag | What it's for | Default |
---|---|---|
REMOVE_FROM_GROUPS=1|0
|
This flag is only available when uninstalling the universal forwarder. Specifies whether or not to take away rights and administrative group membership from the user you installed the forwarder as.
If you set this flag to 1, the installer takes away group membership and elevated rights from the user you installed the forwarder as. If you set this flag to 0, the installer does not take away group membership and elevated rights from the user |
1 (Take away elevated rights and group membership on uninstall.) |
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.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15
Comments
Deployment via group policy does not work correctly, previous versions would error when you tried to remove and install a newer version, requiring deletion of registry entries to get it working. 6.3.1 now will just not install at all via group policy software deployment, on a newly installed server that has never had universal forwarder installed, deploying via software deployment will result in : "UniversalForwarder -- This version of UniversalForwarder has already been installed on this computer."
running "msiexec /i [splunk.msi] TRANSFORMS=[splunk.mst] /qb" will install splunk on the same server that GP deployment fails due to the msi saying its installed.
protip: Make sure you use the correct file name when running this command. The examples given above do not match name of the 6.2 file you download.<br /><br />splunkuniversalforwarder--x64-release.msi is the name given above.<br /><br />splunkforwarder--x64-release.msi is the name of the file you download.
Thanks that worked. Based on the recommendations form our windows team we had few other parameters after quite (like /passive /norestart) which were causing popus in quite mode.
Sorry, the command line should be 'msiexec /i splunk.msi AGREETOLICENSE=YES /quiet'
Hi Bohrasauabh,<br /><br />You can upgrade the forwarder in quiet mode by specifying the /quiet argument to msiexec and including the AGREETOLICENSE flag, as follows:<br /><br />msiexec /i AGREETOLICENSE=YES /quiet<br /><br />You must specify the AGREETOLICENSE flag because that installer prevents install otherwise.<br /><br />Thanks.
How do you upgrade the forwarder in quite mode. there does not seem to be a flag for upgrade.
The problem I have found is due to SameProdCodeExists being set to 1 when in admin install mode: So it will never install when trying to deploy. Setting this to 0 (as it doesnt actually check) fixes the install problem.