Splunk® Enterprise

Forwarding Data

Download manual as PDF

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 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:

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>"

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 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 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: These flags require that you set RECEIVING_INDEXER for them to have any effect.

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 LOGON_USERNAME and LOGON_PASSWORD flags. The installer ignores this flag if you install the forwarder as "Local System", which is the default if you do not specify these flags.

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

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.

Dbond
November 16, 2015

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.

Dbond
November 13, 2015

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.

Reswob4
December 12, 2014

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.

Bohrasaurabh
September 24, 2014

Sorry, the command line should be 'msiexec /i splunk.msi AGREETOLICENSE=YES /quiet'

Malmoore
September 23, 2014

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.

Malmoore
September 23, 2014

How do you upgrade the forwarder in quite mode. there does not seem to be a flag for upgrade.

Bohrasaurabh
September 23, 2014

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