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.
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.
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:
- 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:
passwordare the administrative credentials you'll use to log into the Splunk platform indexer.
hostis the host name or IP address of the indexer.
management_portis the TCP management port on the indexer (default: 8089.)
token_nameis the friendly name that you want to assign the token.
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:
inputs.confon the indexer and add the stanza:
[splunktcptoken://<token_name>] disabled = 0 token = <token_value>
- 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>
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.
- Edit the outputs.conf for the forwarder and add the
tokenvalue under the
[tcpout] server=idx1.mycompany.com:9997 token = <token_value> ...
- 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
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
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
ERROR TcpInputProc - Invalid S2S token=Token not sent by forwarder for data received from src=127.0.0.1:58796
Configure forwarding to Splunk Enterprise indexer clusters
Protect against loss of in-flight data
This documentation applies to the following versions of Splunk® Universal Forwarder: 126.96.36.199, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 9.0.0