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:
- 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>"
user
andpassword
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.- 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.
- The token must be enabled on the indexer before it can be used for forwarder authentication.
In this command:
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:
- Edit
inputs.conf
on 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>
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.
- 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> ...
- 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
Manage a Linux least-privileged user | Troubleshoot the universal forwarder |
This documentation applies to the following versions of Splunk® Universal Forwarder: 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.1.7, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.2.4, 9.3.0, 9.3.1, 9.3.2
Feedback submitted, thanks!