Use cURL to manage HTTP Event Collector tokens, events, and services
You can use the cURL web data transfer application to manage tokens, events, and services for HTTP Event Collector (HEC) on your Splunk Enterprise instance using the Representational State Transfer (REST) API. Using the REST API lets you seamlessly manage HEC objects without having to use Splunk Web or the CLI.
cURL commands differ slightly based on your operating system. For information on how to use cURL commands in Windows, see this Splunk Community page.
By default, if your token doesn't specify a default index, the data will be under the main
index. You can specify a default index in your hec token configuration.
Manage HTTP Event Collector tokens with cURL
All HEC token operations are available REST using cURL. Splunk Enterprise stores the tokens at the following REST API endpoint, assuming your Splunk Enterprise server management address is as follows:
https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/
List the existing HTTP Event Collector tokens using cURL
You can list the existing tokens in your Splunk Enterprise HEC using cURL. For example, the following example cURL command lists the tokens that exist on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http
Create an HTTP Event Collector token using cURL
To create a token using cURL, use the name property. For example, the following example CLI command creates a token called mytoken on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http -d name=mytoken
Edit an HTTP Event Collector token using cURL
You can update any token property except its name or value using cURL. For example, the following example cURL command updates the description of the mytoken token on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken -d description=abc
You can update any of the following parameters:
Parameter | Description |
---|---|
disabled | Whether to disable the token. 1 indicates true; 0 indicates false. |
description | A description of the token. |
indexes | A list of indexes accepted by the token. |
index | The token's default index. Splunk Enterprise assigns this value to data that doesn't already have an index value set. |
source | The token's default source value. Splunk Enterprise assigns this value to data that doesn't already have a source value set. |
sourcetype | The token's default sourcetype value. Splunk Enterprise assigns this value to data that doesn't already have a sourcetype value set. |
outputgroup | The token's default outputgroup value. An output group is a group of indexers set up by the Splunk software administrator to index the data. Splunk Enterprise assigns this value to data that doesn't already have an outputgroup value set. |
port | The HTTP Event Collector server port. The default value is 8088, but you can change it using this parameter.
For more information on port values for Splunk Cloud Platform instances and free trials, see Send data to HTTP Event Collector on Splunk Cloud Platform. For more information on Splunk Enterprise port values, see Send data to HTTP Event Collector on Splunk Enterprise. |
enableSSL | Whether the HTTP Event Collector server protocol is HTTP or HTTPS. 1 indicates HTTPS; 0 indicates HTTP. |
dedicatedIoThreads | The number of dispatcher threads on the HTTP Event Collector server. The default value is 2. Do not alter this setting unless you are requested to do so by Splunk Support. The value of this parameter must never be more than the number of physical CPU cores on your Splunk Enterprise instance. |
useACK | Returns an acknowledgment when events are indexed. Set to 1 to enable. |
Enable or disable an HTTP Event Collector token using cURL
You can enable or disable a token using cURL. Changing the status of one token does not change the status of other tokens. To enable or disable a token, use the HTTP POST command, the token name, and the enable or disable endpoint. For example, the following command disables the token called mytoken on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken/disable
Similarly, the following example enables the token called mytoken on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken/enable
Enable or disable HTTP Event Collector using cURL
You can enable or disable HTTP Event Collector itself by making a bulk change to all tokens using cURL. Do not specify a token name when you use the enable or disable endpoint. To enable or disable HTTP Event Collector, use the HTTP POST command and the enable or disable endpoint. For example, the following example disables HTTP Event Collector on the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -X "POST" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/http/disable
Delete an HTTP Event Collector token using cURL
To delete a token using cURL, use the HTTP DELETE command and the token name. For example, the following example cURL command deletes the token called mytoken from the Splunk Enterprise instance at https://localhost:8089 using the user admin:
curl -X "DELETE" -u admin:changeme https://localhost:8089/servicesNS/admin/splunk_httpinput/data/inputs/http/mytoken
Manage HEC events and services with cURL
The following commands show how you can send events to and manage HEC services. This list isn't all-inclusive, but it can give you an idea of the things that you can accomplish with HEC.
Send an event to HEC
The following example demonstrates basic HEC usage. It includes the Splunk Enterprise instance address with port and endpoint, the authentication token, and event data and metadata formatted according to the HEC event data format specification.
curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"event": "Hello, world!", "sourcetype": "manual"}'
Send an event to HEC using basic authentication
This example demonstrates basic authentication, which is an alternative to the HTTP Authentication. To use basic authentication, submit a colon-separated username and password pair in the request as the -u
argument. using any string as the username and the token as the <password>: <user>:<password>
.
# Basic auth curl -u "x:CF179AE4-3C99-45F5-A7CC-3284AA91CF67" "http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector/event" \ -d '{"sourcetype": "mysourcetype", "event": "Hello, world!"}'
Send multiple events to HEC in one request
The following example demonstrates sending multiple events in one request. Though you can send multiple events in a single request, you cannot split one event across multiple requests.
curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"event": "Pony 1 has left the barn"}{"event": "Pony 2 has left the barn"}{"event": "Pony 3 has left the barn", "nested": {"key1": "value1"}}'
Send raw text to HEC
The following example demonstrates sending raw text to HEC. Note the use of the raw endpoint, plus the channel identifier and source type specification, both of which are done using URL query parameters.
curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector/raw?channel=00872DC6-AC83-4EDE-8AFE-8413C3825C4C&sourcetype=mydata" -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" -d '1, 2, 3... Hello, world!'
Send raw batched events to HEC
The following example demonstrates how to send raw batched events to HEC. In this case, the command sends splunkd access logs. It indicates that the indexer must assign these events the source type of splunkd_access
and specifies that they must be sent to the main
index.
# HEC Raw batching curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector/raw?channel=00872DC6-AC83-4EDE-8AFE-8413C3825C4C&sourcetype=splunkd_access&index=main" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '127.0.0.1 - admin [28/Sep/2016:09:05:26.875 -0700] "GET /servicesNS/admin/launcher/data/ui/views?count=-1 HTTP/1.0" 200 126721 - - - 6ms 127.0.0.1 - admin [28/Sep/2016:09:05:26.917 -0700] "GET /servicesNS/admin/launcher/data/ui/nav/default HTTP/1.0" 200 4367 - - - 6ms 127.0.0.1 - admin [28/Sep/2016:09:05:26.941 -0700] "GET /services/apps/local?search=disabled%3Dfalse&count=-1 HTTP/1.0" 200 31930 - - - 4ms 127.0.0.1 - admin [28/Sep/2016:09:05:26.954 -0700] "GET /services/apps/local?search=disabled%3Dfalse&count=-1 HTTP/1.0" 200 31930 - - - 3ms 127.0.0.1 - admin [28/Sep/2016:09:05:26.968 -0700] "GET /servicesNS/admin/launcher/data/ui/views?digest=1&count=-1 HTTP/1.0" 200 58672 - - - 5ms'
Send events to HEC with indexer acknowledgement active
The following example demonstrates how to send events to HEC with indexer acknowledgement active. The sole difference between this example and the basic example is the inclusion of a channel identifier. Indexer acknowledgement also works with raw data.
# Indexer ack curl "https://http-inputs-mycompany,splunkcloud.com:8088/services/collector?channel=00872DC6-AC83-4EDE-8AFE-8413C3825C4C" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"event": "Hello, world!", "sourcetype": "manual"}'
Check HEC indexer acknowledgement status
The following example demonstrates how to check the indexing status of a prior HEC request. It sends the request to the ack endpoint and includes the acks
key, which is set to the three acknowledgement identifiers (ackIDs) whose status is queried.
# Check ack status curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector/ack?channel=00872DC6-AC83-4EDE-8AFE-8413C3825C4C" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"acks": [1,3,4]}'
Extract JSON fields from events sent to HEC
The following example demonstrates how to instruct Splunk Enterprise to extract JSON fields from the events sent to HEC.
# Extracting JSON fields curl "https://http-inputs.mysplunkserver.splunkcloud.com:8088/services/collector" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"sourcetype": "_json", "event": {"a": "value1", "b": ["value1_1", "value1_2"]}}'
Extract explicit JSON fields from events sent to HEC
The following example is similar to the previous example, but it explicitly specifies the JSON fields.
# Explicit JSON fields curl "https://mysplunkserver.example.com:8088/services/collector/event" \ -H "Authorization: Splunk CF179AE4-3C99-45F5-A7CC-3284AA91CF67" \ -d '{"event": "Hello, world!", "sourcetype": "cool-fields", "fields": {"device": "macbook", "users": ["joe", "bob"]}}'
Set up and use HTTP Event Collector from the CLI | About HTTP Event Collector Indexer Acknowledgment |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.11, 8.1.13, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 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, 9.4.0, 8.1.10, 8.1.12, 8.1.14, 8.1.2
Feedback submitted, thanks!