Control forwarder access

You can configure Splunk Enterprise to allow communication from authorized forwarders through the use of tokens. A token is a unique key that is generated and enabled on the indexer, and configured on the forwarder. A forwarder attempting to send data to an indexer without the correct token value will be rejected. Forwarder access control is independent of Secure Sockets Layer (SSL,) and can be used in environments that do not have SSL enabled between Splunk platform instances.

Prerequisites to configuring forwarder access control

The token creation process requires command line access to the management port of the Splunk platform indexers and an administrative level Splunk Enterprise account to create and enable tokens. To access the REST API, use the curl command. There's no integrated support for curl on the Windows Operating System (OS.) You can use a Linux system to configure and manage tokens, or find a supported Windows OS tool.

Forwarder access controls are not available for Splunk Cloud.

Once a token is generated, it must be enabled on the Splunk platform indexers and configured in the outputs.conf on the forwarders that connect to the indexer. For forwarder configuration management options, see Best practices for deploying configuration updates across universal forwarders in the Updating Splunk Enterprise Instances manual.

Token management

The token is created on the receiver. The receiver can be a heavy forwarder, or an indexer.

Generate a token

Before you can configure token-based authentication, you must generate a token to use:

1. From a command or shell prompt, use the REST API to connect to a Splunk Enterprise indexer to create the token:

   curl -v -k -u <user>:<password> https://<host>:<management_port>/services/data/inputs/tcp/splunktcptoken -d "name=<token_name>"
   

In this command:

• user and password are the administrative credentials you'll use to log into the Splunk platform indexer.
• host is the host name or IP address of the indexer.
• management_port is the TCP management port on the indexer (default: 8089.)
• token_name is the friendly name that you want to assign the token.
2. The REST command response is returned to the command line and includes the token value. Copy the token value into a password management vault or other repository for later use in configuring the forwarders.
3. The token must be enabled on the indexer before it can be used for forwarder authentication.

For example, to create a token named "my_token" on the host idx1.mycompany.com using the Splunk admin user and password:

curl -v -k -u admin:changeme https://idx1.mycompany.com:8089/services/data/inputs/tcp/splunktcptoken -d "name=my_token"

The REST response includes the token value:

<s:key name = "token">808F7BD7-1444-4910-B8F5-87B83D694E18</s:key>

Enable a token

A token can be enabled using the REST API, or by modifying the inputs.conf of the receiving indexer.

To use the REST API to enable a token, from a command or shell prompt, run:

curl -v -k  -X "POST" -u <user>:<password> https://<host>:<management_port>/services/data/inputs/tcp/splunktcptoken/<token_name>/enable

Optionally, use the inputs.conf to enable a token:

1. Edit inputs.conf on the indexer and add the stanza:

   [splunktcptoken://<token_name>]
   disabled = 0
   token = <token_value>
   

2. Restart Splunk Enterprise services.

Disable a token

To disable a token using the REST API, use the following command:

curl -v -k  -X "POST" -u <username>:<password> https://<host>:<management_port>/services/data/inputs/tcp/splunktcptoken/<token_name>/disable

Delete a token

To remove a token using the REST API, use the following command:

curl -v -k -X "DELETE" -u <username>:<password> https://<host>:<management_port>/services/data/inputs/tcp/splunktcptoken/<token_name>

List tokens

To receive a list of configured tokens using the REST API, use the following command:

curl -v -k -u <user>:<password> https://<host>:<management_port>/services/data/inputs/tcp/splunktcptoken

Configure the forwarder with a token

Add the token value to the forwarder's outputs.conf under the [tcpout] stanza to configure authentication with an indexer.

1. Edit the outputs.conf for the forwarder and add the token value under the [tcpout] stanza:

   [tcpout]
   server=idx1.mycompany.com:9997
   token = <token_value>
   ...
   

2. Restart the forwarder services.

Confirm that the forwarder and indexer can communicate using the tokens

When you configure a forwarder with a token, the communication process with the indexer becomes:

• The forwarder connects to the indexer.
• The indexer requests authentication.
• The forwarder provides the token to the indexer.
• The indexer compares the token it received with the token it has.
• If the tokens match, the indexer accepts the TCP connection and sets up the data stream. If the tokens do not match, the indexer rejects the connection and logs an entry in the splunkd.log.

A forwarder without the correct token value for an indexer cannot forward data to that indexer.

Common error messages

A forwarder that does not have the correct token generates this event in splunkd.log:

ERROR TcpInputProc - Exception: Token sent by forwarder does not match configured tokens src=127.0.0.1:58798! for data received from src=127.0.0.1:58798

A forwarder that does not submit a token to an indexer with a token enabled generates this event in splunkd.log:

ERROR TcpInputProc - Invalid S2S token=Token not sent by forwarder for data received from src=127.0.0.1:58796