Administer Splunk Cloud Platform using the ACS CLI
The Admin Config Service (ACS) provides a command line interface (CLI) that lets you perform many Splunk Cloud Platform configuration and management tasks in a self-service manner. You can use the CLI to run corresponding ACS API operations from the command line, without having to know specific API endpoint details.
For a complete list of supported ACS features, see ACS compatibility matrix.
For detailed information on ACS API endpoints, see ACS API endpoint reference.
Requirements
To use the ACS CLI:
- You must have Splunk Cloud Platform version 8.2.2109 or higher. (Managing private apps and Splunkbase apps requires version 8.2.2112 or higher. Configuring limits.conf requires version 8.2.2203 or higher.)
- Your assigned role must contain the capabilities required to access the ACS API endpoint. The
sc_adminrole has most required capabilities by default. For a list of required capabilities, see Manage ACS API access with capabilities. - You must have a Mac, Linux, or Windows operating system.
- For Mac or Linux, install Homebrew. (See Homebrew installation instructions and Homebrew requirements for Mac and Linux).
Install or upgrade the ACS CLI
The ACS CLI supports installation on Mac, Linux, and Windows operating systems.
Install or upgrade on Mac or Linux
You must have the Homebrew package manager installed on your machine to run the following installation commands.
To install the ACS CLI on Mac or Linux:
$ brew tap splunk/tap $ brew install acs
This installs the latest acs binary for your operating system from https://github.com/splunk/acs-cli/releases into the /usr/local/Cellar/acs directory on your local machine.
To upgrade from an older acs version to the latest version, run the following:
$ brew install acs
or
$ brew upgrade acs
Install or upgrade on Windows
The ACS CLI version 2.4.0 and higher supports installation on Windows.
To install the ACS CLI on Windows:
- Download the ACS CLI installer.exe file from https://github.com/splunk/acs-cli/releases/latest.
- Run the installer on your local Windows machine.
or
As of ACS CLI version 2.5.0, you can install the binary on Windows using the Windows Package Manager (winget).
You must have Windows Package Manager installed on your machine to run the following command. See Install winget.
Run the following command at the Command Prompt or Powershell:
winget install acs-cli
This installs the latest version of the ACS CLI on your local Window machine.
Set environment variables
The --username, --password, and --token flags are deprecated as of ACS CLI version 2.6.0.
You can now set the following environment variables to specify login credentials and pre-existing token values:
| Environment variable | Description |
|---|---|
| SPLUNK_USERNAME | The login username of your splunk.com account. |
| SPLUNK_PASSWORD | The login password of your splunk.com account. |
| STACK_USERNAME | The login username of your Splunk Cloud Platform deployment. |
| STACK_PASSWORD | The login password of your Splunk Cloud Platform deployment. |
| STACK_TOKEN | A pre-existing JWT token value. |
| ACS_SERVER | ACS server URL override. Use instead of the --server flag to override the default ACS server URL: https://admin.splunk.com. Requires ACS CLI version 2.13.0 or higher. For FedRAMP deployments, set ACS_SERVER to the FedRAMP IL2 URL: https://admin.splunkcloudgc.com. |
For example:
export SPLUNK_USERNAME=my_splunk_username SPLUNK_PASSWORD=my_splunk_password STACK_USERNAME=admin STACK_PASSWORD=my_deployment_password STACK_TOKEN=existing_token_value ACS_SERVER=https://admin.splunkcloudgc.com
If you do not set environment variables, you can still use the deprecated flags to specify login credentials and existing token values. If you do not set environment variables or use flags, the CLI will continue to prompt you for username and password values.
Set login credentials
Some ACS CLI commands require you to specify login credentials for your splunk.com account (acs login, acs token create, and acs setup), while other commands require you to specify login credentials for your Splunk Cloud Platform deployment (acs apps install and acs apps update). Instead of specifying these credentials using the deprecated --username and --password flags, you can now set the corresponding environment variables to specify these credentials securely.
To specify login credentials for your splunk.com account, set SPLUNK_USERNAME and SPLUNK_PASSWORD to the appropriate values. To specify login credentials for your Splunk Cloud Platform deployment, set STACK_USERNAME and STACK_PASSWORD to the appropriate values.
Set existing token value for SAML accounts
For SAML users who must provide an existing token value when running the acs login command, instead of using the deprecated --token flag, you can now set the corresponding environment variable to specify the existing token value securely.
To specify an existing token value, set STACK_TOKEN to the appropriate value.
Setting a token value is optional for non-SAML users. If you set a token value, your stack login credentials are not used to generate a new token.
For more information, see the Log in/create authentication token section under Configure the ACS CLI.
Set FedRAMP server URL (FedRAMP only)
You can optionally set the ACS_SERVER environment variable to the FedRAMP IL2 URL, to make it the default ACS server and simplify ACS CLI operations:
export ACS_SERVER=https://admin.splunkcloudgc.com
If you do not set ACS_SERVER to the FedRAMP IL2 URL, you can still run ACS CLI operations on FedRAMP using the --server override flag.
Configure the ACS CLI
Before you can use the ACS CLI, you must specify the Splunk Platform Platform deployment on which you want to run ACS CLI operations. To do so, you must first add the deployment to the ACS CLI configuration, then set that deployment as the current deployment. You can add multiple deployments to your ACS CLI configuration, and switch between them to run ACS CLI operations on different deployments.
You must also log in to the deployment, which creates a token to authenticate ACS CLI operations.
Here is a summary of the initial ACS CLI configuration workflow and corresponding commands for each step:
- Add a deployment (
acs config add-stack <stack-name>) - Set the current deployment (
acs config use-stack <stack-name>) - Log in/create authentication token (
acs login) - Run ACS CLI operations (
acs <command>)
Each Splunk Cloud Platform deployment is identified by the stack-name, which is the prefix of the deployment's URL. For example, if your deployment's URL is "https://my-company-name.splunkcloud.com" the stack-name is "my-company-name".
Add a deployment
To add a new deployment to the ACS CLI configuration:
Run the acs config add-stack command, specifying the <stack-name> and the --stack-type (the Splunk Cloud Platform Experience type, victoria or classic). If you do not specify --stack-type, it is set to "victoria" by default.
$ acs config add-stack my-company-name Stack added: my-company-name , Type: victoria Please run "acs config use-stack" to use this stack for further CLI operations.
As of ACS CLI version 2.11.0, the --stack-type flag is deprecated, but continues to function for backward compatibility. The ACS CLI now populates the stack type (Victoria or Classic) automatically when you run the acs login or acs setup command.
As of ACS CLI version 2.9.0, you can specify a target search head (or search head cluster) for a deployment using the optional --target-sh flag followed by the search head prefix. This adds the search head to the configuration file for the specified stack. For example:
$ acs config add-stack my-company-name --target-sh sh-i-06b6d1ge9st944 Stack added: my-company-name , Type: victoria, Search Head added: sh-i-06b6d1ge9st9445 Please run "acs config use-stack" to use this stack for further CLI operations.
For more information on targeting search heads, see Target a specific search head for ACS operations.
Set the current deployment
To set the current deployment on which to run ACS CLI operations:
Run the acs config use-stack command. This sets the current-stack value in the CLI configuration. You can use this command to switch between multiple previously added deployments. For example:
$ acs config use-stack my-company-name current-stack is now set to my-company-name Please run "acs login" command to create and cache token to authenticate against ACS for further commands on this stack.
To confirm that your deployment is currently set for use with CLI operations, run the acs config current-stack command. For example:
$ acs config current-stack Stack: my-company-name Type: victoria
As of ACS CLI version 2.9.0, you can specify a target search head (or search head cluster) for the current deployment using the optional --target-sh flag followed by the search head prefix. This sets the current-search-head value for the CLI configuration. All future commands will target this search head, until you run the use-stack command again, specifying a different stack or search head. For example:
$ acs config use-stack my-company-name --target-sh sh-i-06b6d1ge9st9445 Stack added: my-company-name, Type: victoria, Search Head added: sh-i-06b6d1ge9st9445 current-stack is now set to my-company-name with current-search-head set to sh-i-06b6d1ge9st9445 All future operations will be targeted on the search head specified. To stop targeting a search head, please rerun the "acs config use-stack" without the --target-sh flag
For more information on targeting search heads, see Target a specific search head for ACS operations.
Log in/create authentication token
For each deployment that you add to the CLI, you must run the acs login command once to generate and cache an authentication token for the deployment. The CLI uses the cached token for subsequent operations.
To log in and create a new authentication token for a user:
Run the acs login command, specifying the token user. If prompted, enter the login credentials (username and password) for the Splunk Cloud Platform deployment. This creates and caches a new JWT token to authenticate all further ACS CLI operations. For example:
$ acs login --token-user test_acs_user
Enter Username: test_acs_user
Enter Password:
{
"user": "test_acs_user",
"audience": "test_acs_user",
"id": "0c00464d6e55dc77….8380022fb20d4a1e822bfd17965ca",
"token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...",
"status": "enabled",
"expiresOn": "2022-04-03T19:52:04Z",
"notBefore": "2022-03-04T19:52:04Z"
You must rerun the acs login command when the cached token expires. A symptom of token expiry is CLI operations returning unauthorized error codes.
The ACS CLI does not support log in using deployment credentials for SAML users. If you are a SAML user, you must provide the value of an existing token, which you can create in the Splunk Web UI. To specify the token value, you can use the STACK_TOKEN environment variable or the acs login --token parameter, which skips generating a new token and caches the existing token value.
If targeting a specific search head (ACS CLI version 2.9.0 and higher), the acs login command creates a token unique to that specific search head. If you do not want to target the search head, you must run acs login again (after running acs config use-stack without the --target-sh flag.)
FedRamp deployments do not support the ACS CLI login and setup commands or the the ACS tokens endpoint.
Optional: Configure ACS CLI with single acs setup command
ACS CLI 2.6.0 and higher provides an optional acs setup command, which combines the functionality of the acs add-stack, acs use-stack and acs login into a single command. You can use the acs setup command to configure the ACS CLI for your deployment in a single step, instead of running each of the three commands separately.
The available flags for the acs setup include all flags available for the three commands it combines. For a list of available flags, run acs setup --help.
To configure the ACS CLI for deployments on Victoria Experience and Classic Experience, run the acs setup command, specifying the stack-name and --token-user value. For example:
acs setup <stack name> --token-user test_acs_user
View ACS CLI configuration
The ACS CLI configuration is stored in ~/.acs/acs_config.json. The file contains the current-stack and token, token-id, and type values for all added stacks. For example:
$ cat ~/.acs/acs_config.json
{
"current-stack": "mystack",
"stacks": {
"calm-cheetah-hau": {
"token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...",
"type": "victoria"
},
"mystack": {
"token": "",
"token-id": "",
"type": "victoria"
}
}
}
View ACS CLI logs
ACS CLI logs are stored in the following locations:
- Mac: $HOME/Library/Logs/acs/acs.log
- Linux: $HOME/.acs/logs/acs.log
To view ACS CLI log details, run a cat command against the appropriate log file. For example:
$ cat acs.log INFO: 2022/04/05 17:44:45 Adding stack to ACS config: ruchikatestc INFO: 2022/04/05 17:44:57 Switching to use stack: ruchikatestc INFO: 2022/04/05 17:44:57 Current-stack is now set to: ruchikatestc INFO: 2022/04/05 17:45:44 Creating token on stack ruchikatestc INFO: 2022/04/05 17:45:56 Token creation status code: 200 INFO: 2022/04/05 17:45:56 Create token Request id: 3706f1aa-3cc3-9e5a-9882-4d4f975d6107
GET help with the ACS CLI
The ACS CLI provides a built-in help reference. To get started, you can access the CLI help reference using the help command, as follows:
$ acs -h or --help
Useful help commands
The following table lists some useful ACS CLI help commands:
| Help command | Description |
|---|---|
| acs or acs --help | ACS API overview. Available commands and flags. |
| acs config --help | Help for acs config commands: add-stack, use-stack, current stack. |
| acs login --help | Help for acs login command. Login to create and cache token to authenticate against ACS. |
| acs setup --help | Help for acs setup command, including usage and flags. |
| acs [command] --help | Help for a command, including usage, subcommands, and flags. |
| acs apps --help | Help for private app and Splunkbase app management commands. |
| acs indexes --help | Help for index management commands. |
| acs hec-token --help | Help for HEC token management commands. |
| acs token --help | Help for JWT authentication token management commands. |
| acs ip-allowlist --help | Help for IP allow list configuration commands. |
| acs outbound-port --help | Help for outbound port configuration commands. |
| acs limits --help | Help for limits.conf configuration commands. |
| acs users --help | Help for users management commands |
| acs roles --help | Help for roles management commands. |
| acs capabilities --help | Help for capabilities listing commands. |
Other helpful commands:
| Command | Description |
|---|---|
| acs config current-stack | Get the <stack-name> and <type> of the current deployment. |
| acs status current-stack | Get status info for the current deployment. |
| acs version | View the ACS CLI version. |
| acs license | View Splunk General Terms. |
Run ACS CLI operations
This section introduces the CLI commands you can use to run ACS feature operations on your deployment.
ACS CLI command syntax
The general syntax for an ACS CLI command is, as follows
acs <command> <subcommand> <object> [ [--<parameter>] <value>]...
Specify login credentials (username and password)
Some ACS CLI commands require you to specify the login credentials of your splunk.com account or the login credentials of your Splunk Cloud Platform deployment. To specify these login credentials securely, set the corresponding environment variables to the appropriate value. For more information, see Set environment variables.
ACS CLI commands
The following table lists ACS features and the corresponding CLI commands you can use to perform the ACS feature operations.
| ACS feature | Command | Description | |
|---|---|---|---|
| Configure IP allow lists | acs ip-allowlist |
Create, describe, and delete IP allow lists that grant access to Splunk Cloud Platform features from specified subnets on your network. | |
| Configure outbound ports | acs outbound-port |
Create, delete, describe, and list outbound ports for your deployment. | |
| Export apps | acs apps export |
Export app data, including app configurations, knowledge objects, and metadata from app/default, app/local, and users/app directories. Supports bulk export of data from multiple apps. Requires ACS CLI version 2.16.0 or higher and Splunk Cloud Platform version 9.2.2403 or higher on Victoria Experience. See Export apps in bulk. | |
| Manage app permissions | acs permissions apps |
List, describe, and update read or write permissions for apps. Supports bulk-update in ACS CLI version 2.12.0 and higher. See Manage app permissions in Splunk Cloud Platform. | |
| Manage authentication tokens | acs token |
Create, delete, describe, and list JWT authentication tokens. | |
| Manage HEC tokens | acs hec-token |
Create, delete, describe, list, and update HTTP Event Collector (HEC) tokens. Supports bulk-create, bulk-update, and bulk-delete in ACS CLI version 2.8.0 and higher. See Create HEC tokens in bulk. | |
| Manage indexes | acs indexes |
Create, delete, describe, list, and update indexes.
| |
| Manage limits.conf configurations | acs limits |
Set, reset, and list select limits.conf settings. For information on supported limits.conf settings, see Manage limits.conf configurations using the ACS API. For help with ACS CLI limits commands, see acs limits --help.
| |
| Manage maintenance windows | maintenance-windows |
View maintenance window schedules (list, describe, and audit) using the schedules subcommand. Manage maintenance window change freezes (describe and update) using the preferences subcommand. Requires ACS CLI version 2.7.0. See Manage maintenance windows for Splunk Cloud Platform.
| |
| Manage private apps | acs apps |
Install, list, describe, and uninstall private apps. Supports bulk-install and bulk-uninstall in ACS CLI version 2.5.0 and higher. See Vet and install private apps in bulk. | |
| Manage Splunkbase apps | acs apps |
Install, update, list, describe, and uninstall Splunkbase apps. Supports bulk-install, bulk-fetch-license, and bulk-uninstall in ACS CLI version 2.5.0 and higher. See Install Splunkbase apps in bulk. | |
| Manage restarts | acs restart |
Restart the 1st search head or search head cluster of a stack. Triggers a rolling restart for a search head cluster. Deployments on Classic Experience require Splunk Cloud Platform version 9.1.2308 or higher. See Manage restarts. | |
| Manage roles | acs roles |
Create, update, list, describe, and delete Splunk Cloud Platform roles. Requires ACS CLI version 2.10.0 and higher. See Manage users, roles, and capabilities. | |
| Manage users | acs users |
Create, update, list, describe, and delete Splunk Cloud Platform users. Requires ACS CLI version 2.10.0 and higher. See Manage users, roles, and capabilities. | |
| Retry failed operations | acs deployment |
View status and retry failed operations. Requires ACS CLI version 2.12.0 and higher. See Retry failed operations. | |
| Set up Unified Identify for Splunk Observability Cloud | observability |
Pair your Splunk Cloud Platform and Splunk Observability Cloud deployments using the pair subcommand. Check pairing status using the pairing-status-by-id subcommand. Requires ACS CLI version 2.14.0. See How to set up Unified Identify in the Splunk Observability Cloud documentation.
| |
| View capabilities | acs capabilities |
List all Splunk Cloud Platform capabilities. Requires ACS CLI version 2.10.0 and higher. See Manage users, roles, and capabilities. |
For more information on ACS CLI bulk commands for apps and indexes, see Run ACS CLI bulk operations.
Examples:
Configure IP allow lists
For help, run acs ip-allowlist --help.
For more information, including ACS API endpoint details, see Configure IP allow lists in Splunk Cloud Platform.
Example 1. Add new subnets to the "search-api" feature allow list:
$ acs ip-allowlist create search-api --subnets 1.1.1.1/32,2.2.2.2/32
IP allow list subnets creation request submitted successfully for feature: search-api
Note that it can take several minutes for the subnet update to be applied to your Splunk Cloud Platform stack.
To verify the status of your stack after subnet update request, please run the "acs status current-stack" command.
$ acs status current-stack
{
"status": {
"infrastructure": {
"status": "Ready"
}
}
}
Example 2. List the existing subnets for the "search-api" feature:
$ acs ip-allowlist describe search-api
{
"subnets": [
"12.26.0.2/32",
"54.203.114.197/32",
"52.32.57.234/32",
"54.203.207.205/32",
"47.16.104.185/32",
"1.1.1.1/32",
"2.2.2.2/32"
]
}
Example 3. Delete subnets from the "search-api" feature allow list:
$ acs ip-allowlist delete search-api --subnets 1.1.1.1/32 IP allow list subnets deleted successfully. To verify the status of your stack after subnet delete request, please run the "acs status current-stack" command.
Configure outbound ports
For help, run acs outbound-port --help.
For more information, including ACS API endpoint details, see Configure outbound port.
Example 1. Create an outbound port configuration:
$ acs outbound-port create 8089 --subnets 1.1.1.1/32,2.2.2.2/32
Request successfully accepted to add connection from outbound port 8089
To check the status of your stack after the outbound port request, please run the "acs status current-stack" command.
{
"outboundPorts": [
{
"port": 8089,
"subnets": [
"1.1.1.1/32",
"2.2.2.2/32"
]
}
]
}
Example 2. View an individual outbound port with subnets:
$ acs outbound-port describe 8089
{
"destinationRanges": [
"1.1.1.1/32",
"2.2.2.2/32"
],
"name": "8089",
"port": 8089
}
Example 3. Delete an outbound port configuration:
$ acs outbound-port delete 8089 --subnets 1.1.1.1/32 Request successfully accepted to delete connection from outbound port 8089 To check the status of your stack after the outbound port request, please run the "acs status current-stack" command.
Manage authentication tokens
For help, run acs token --help.
For more information, including ACS API endpoint details, see Manage authentication tokens.
When you create a JWT authentication token, you must specify the login credentials (username and password) of your Splunk Cloud Platform deployment. To specify these credentials securely, set the STACK_USERNAME and STACK_PASSWORD environment variables to the appropriate values. If you do not set these environment variables, you will be prompted for username and password at the command line.
Example 1. Create a JWT authentication token:
$ acs token create --token-user test_acs_user
Enter Username: test_acs_user
Enter Password:
{
"user": "test_acs_user",
"audience": "test_acs_user",
"id": "11d61711dd4f069a772bf6e4ca4d5debf3e8ac71fbc9dab7cdbce1f887bab8f1",
"token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0Iiwi...",
"status": "enabled",
"expiresOn": "2022-04-03T19:55:16Z",
"notBefore": "2022-03-04T19:55:16Z"
}
As of ACS CLI version 2.11.0, instead of providing login credentials (username and password), you can specify the --use-stack-token flag for authorization. This flag lets you use the cached token created at login/setup as authorization for creating a new token.
Example 2. Get authentication token information:
$ acs token describe <token-id>
{
"id": "0c00464d6e55dc779dd862cf9c541d99b9a8380022fb20d4a1e822bfd17965ca",
"user": "test_acs_user",
"audience": "test_acs_user",
"status": "enabled",
"expiresOn": "2022-04-03T19:52:04Z",
"notBefore": "2022-03-04T19:52:04Z",
"lastUsed": "2022-03-04T19:53:27Z",
"lastUsedIP": "50.19.33.107"
}
Example 3. Delete an authentication token:
$ acs token delete <token-id> Token deleted successfully
Manage HTTP Event Collector (HEC) tokens
For help, run acs hec-token --help.
For more information, including ACS API endpoint details, see Manage HEC tokens in Splunk Cloud Platform.
Example 1. Create a new HEC token:
% acs hec-token create --name testcli
{
"http-event-collector": {
"spec": {
"allowedIndexes": null,
"defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
"defaultIndex": "default",
"defaultSource": "",
"defaultSourcetype": "",
"disabled": false,
"name": "testcli",
"useAck": false
},
"token": "9231927a-2e52-4893-a799-5f76..."
}
}
Example 2. Update an existing HEC token:
% acs hec-token update testcli --default-index main Hec token update request successfully submitted
Example 3. Describe an individual HEC token:
$ acs hec-token describe testcli
{
"http-event-collector": {
"spec": {
"allowedIndexes": null,
"defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
"defaultIndex": "main",
"defaultSource": "",
"defaultSourcetype": "",
"disabled": false,
"name": "testcli",
"useAck": false
},
"token": "9231927a-2e52-4893-a799-5f76..."
}
}
Example 4. Delete an HEC token:
$ acs hec-token delete testcli Hec token deletion request successfully submitted
Example 5. List existing HEC tokens in your deployment:
% acs hec-token list
{
"http-event-collectors": [
{
"spec": {
"allowedIndexes": [
"main"
],
"defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
"defaultIndex": "main",
"defaultSource": "<stack-id>.splunkcloud.com",
"defaultSourcetype": "",
"disabled": false,
"name": "runscope_2022-01-02-12-37",
"useAck": false
},
"token": "d6a3d5de-a617-4e1f-b70b-abfe..."
},
{
"spec": {
"allowedIndexes": [
"main"
],
"defaultHost": "sh-i-<search-head-id-suffix>.<stack-id>.splunkcloud.com",
"defaultIndex": "main",
"defaultSource": "<stack-id>.splunkcloud.com",
"defaultSourcetype": "",
"disabled": false,
"name": "runscope_2022-01-13-17-40",
"useAck": false
},
"token": "b2ace4e6-5e4c-41ea-93c7-b4a3..."
}
]
}
Manage indexes
For help, run acs indexes --help.
ACS supports index management on Splunk Cloud Platform deployments on both Victoria Experience and Classic Experience.
For more information, including ACS API endpoint details, see Manage indexes in Splunk Cloud Platform.
Supports --self-storage-bucket-path and --splunk-archival-retention-days flags for DDAA and DDSS index creation and update. For more information, run acs indexes create --help or acs indexes update --help.
For detailed information on DDAA and DDSS parameters for index creation and update, see Create a new index with DDAA or DDSS.
Use acs indexes self-storage-locations to view and manage self storage locations for DDSS. For more information, run acs indexes self-storage-locations --help.
Example 1. Create a new index:
$ acs indexes create --name testcli
{
"name": "testcli",
"datatype": "event",
"searchableDays": 90,
"maxDataSizeMB": 0,
"totalEventCount": "0",
"totalRawSizeMB": "0"
}
Example 2. Update configuration for an index:
$ acs indexes update testcli --searchable-days 200
{
"name": "testcli",
"datatype": "event",
"searchableDays": 200,
"maxDataSizeMB": 0,
"totalEventCount": "0",
"totalRawSizeMB": "0"
}
You cannot update an index to disable DDAA or DDSS, nor can you update an index to change from DDSS to DDAA, or vice versa. To disable DDAA/DDSS or change the dynamic data storage type for an index, you must use the Splunk web UI.
Example 3. View configuration information for a specific index:
$ acs indexes describe testcli
{
"name": "testcli",
"datatype": "event",
"searchableDays": 200,
"maxDataSizeMB": 0,
"totalEventCount": "0",
"totalRawSizeMB": "0"
}
Example 4. List existing indexes:
$ acs indexes list
[
{
"name": "history",
"datatype": "event",
"searchableDays": 7,
"maxDataSizeMB": 0,
"totalEventCount": "0",
"totalRawSizeMB": "0"
},
{
"name": "lastchanceindex",
"datatype": "event",
"searchableDays": 1095,
"maxDataSizeMB": 0,
"totalEventCount": "0",
"totalRawSizeMB": "0"
},
{
"name": "main",
"datatype": "event",
"searchableDays": 1095,
"maxDataSizeMB": 0,
"totalEventCount": "12358",
"totalRawSizeMB": "8.90"
}
]
Example 5. Delete an index:
$ acs indexes delete testcli
{
"status": "testcli index deletion request successfully submitted"
}
Manage private apps
For help, run acs apps --help, acs apps install private --help.
ACS CLI supports private app management on Splunk Cloud Platform version 8.2.2112 and higher. For earlier versions, you can manage private apps using ACS API endpoints. see Manage private apps in Splunk Cloud Platform.
When you install a private app using acs apps install private, the command automatically runs the following installation steps:
- Splunk login to get new splunkbase token
- Submits the app to AppInspect for inspections
- Gets the app-inspection status
- Installs the app using the ACS endpoint.
You can optionally skip app inspection steps by specifying the --pre-vetted flag.
Example 1. Install a private app:
$ acs apps install private --acs-legal-ack Y --app-package /Users/username/Downloads/o3.tgz
Authenticating with the Splunk API service using your splunk.com credentials.
Enter Username: username@splunk.com
Enter Password:
Successfully authenticated user and assigned a token
Inspecting your private app before installing...
Submitted app for inspection (requestId='78c95205-e411-4c9c-93ad-fe3fb151579a')
Waiting for inspection to finish...
processing..
success
Vetting completed, summary:
{
"error": 0,
"failure": 0,
"skipped": 0,
"manual_check": 0,
"not_applicable": 65,
"warning": 3,
"success": 147
}
Vetting successful
Installing the app...
{
"appID": "opsgenie3",
"label": "Opsgenie3-NEW",
"name": "opsgenie3",
"status": "installed",
"version": "1.2.2"
}
For troubleshooting information on AppInspect validation errors, see Troubleshoot ACS error messages.
Example 2. Describe a private app:
$ acs apps describe opsgenie3
{
"appID": "opsgenie3",
"label": "Opsgenie3-NEW",
"name": "opsgenie3",
"status": "installed",
"version": "1.2.2"
}
Example 3. Uninstall a private app:
% acs apps uninstall opsgenie3 App uninstalled successfully
Example 4. List all apps (private and splunkbase):
% acs apps list
{
"apps": [
{
"appID": "000-self-service",
"label": "000-self-service",
"name": "000-self-service",
"status": "installed",
"version": ""
},
{
"appID": "075-cloudworks",
"label": "075-cloudworks",
"name": "075-cloudworks",
"status": "installed",
"version": ""
} ,
{..}
]
Manage Splunkbase apps
For help, run acs apps --help, acs apps install splunkbase --help.
ACS CLI supports Splunkbase app management on Splunk Cloud Platform version 8.2.2112 and higher, on Victoria Experience only.
When you install a Splunkbase app using the acs apps install splunkbase command, you must provide your splunk.com login credentials (username and password), not the login credentials of the current deployment. To provide these credentials securely, set the SPLUNK_USERNAME and SPLUNK_PASSWORD environment variables. If you do not set these environment variables you will be prompted for them at the command line.
After the install operation completes, make sure to run the acs status current-stack command to see if a restart is required. Some app and index state changes can require a Splunk restart. For more information, see Manage restarts for Splunk Cloud Platform.
For more information, including ACS API endpoint details, see Manage Splunkbase apps in Splunk Cloud Platform.
Example 1. Install a Splunkbase app:
$ acs apps install splunkbase --splunkbase-id 3662 --acs-licensing-ack https://supportforums.cisco.com/sites/default/files/attachments/document/cisco_estreamer_end_user_license_agreement.pdf
Authenticating with the Splunk API service using your splunk.com credentials.
Enter Username: username@splunk.com
Enter Password:
Installing the app...
{
"appID": "TA-eStreamer",
"label": "Cisco Secure eStreamer Client (f.k.a Firepower eNcore) Add-On for Splunk",
"name": "TA-eStreamer",
"splunkbaseID": "3662",
"status": "installed",
"version": "5.0.1"
}
Please run 'acs status current-stack' to check if the stack needs a restart
Example 2. List all Splunkbase apps:
$ acs apps list --splunkbase
{
"apps": [
{
"appID": "python_upgrade_readiness_app",
"label": "Upgrade Readiness App",
"name": "python_upgrade_readiness_app",
"splunkbaseID": "5483",
"status": "installed",
"version": "3.1.0"
},
{
"appID": "TA-eStreamer",
"label": "Cisco eStreamer eNcore for Splunk",
"name": "TA-eStreamer",
"splunkbaseID": "3662",
"status": "installed",
"version": "5.0.1"
}
]
}
Example 3. Update a Splunkbase app:
$ % acs apps update TA-eStreamer --version 5.0.4 --acs-licensing-ack https://supportforums.cisco.com/sites/default/files/attachments/document/cisco_estreamer_end_user_license_agreement.pdf
Authenticating with the Splunk API service using your splunk.com credentials.
Enter Username: username@splunk.com
Enter Password:
Updating the app...
{
"appID": "TA-eStreamer",
"label": "Cisco Secure eStreamer Client (f.k.a Firepower eNcore) Add-On for Splunk",
"name": "TA-eStreamer",
"splunkbaseID": "3662",
"status": "installed",
"version": "5.0.4"
}
Example 4. Describe a Splunkbase app:
$ acs apps describe TA-eStreamer
{
"appID": "TA-eStreamer",
"label": "Cisco eStreamer eNcore for Splunk",
"name": "TA-eStreamer",
"splunkbaseID": "3662",
"status": "installed",
"version": "5.0.1"
}
Example 5. Uninstall a Splunkbase app:
$ acs apps uninstall TA-eStreamer App uninstalled successfully
Run ACS CLI bulk operations
The ACS CLI supports self-service bulk operations for HEC tokens, indexes, and apps. You can use bulk commands to minimize repetitive administration tasks when managing large numbers of these items. You can also integrate ACS bulk operations into your automated CI/CD pipelines.
To run bulk operations you must have ACS CLI version 2.5.0 or higher.
Deployments on Classic Experience support ACS CLI bulk operations for HEC tokens and indexes only.
The ACS CLI provides the following commands for bulk operations:
| Bulk operation | Command |
|---|---|
| Export apps | acs apps export (Requires ACS CLI version 2.16.0 or higher) |
| Manage app permissions | acs permissions apps bulk-update (Requires ACS CLI version 2.12.0 or higher) |
| Manage HEC tokens | acs hec-token bulk-create acs hec-token bulk-update |
| Manage indexes | acs indexes bulk-create acs indexes bulk-update (Requires ACS CLI version 2.8.0 or higher.) |
| Manage private apps | acs apps bulk-install private |
| Manage Splunkbase apps | acs apps bulk-fetch-license
acs apps bulk-install splunkbase |
When you run ACS CLI bulk commands, you must specify either an input JSON file that contains a list of HEC tokens, indexes, and apps, or, in the case of private apps, the directory where the private app packages are located. Examples of properly formatted JSON files are provided for each bulk operation in the following sections.
When you run a bulk command, the ACS CLI attempts the request for each listed item. When the command completes, the output shows a summary of the results, including the number of request failures and successes. Each bulk operation also generates a full report that contains detailed results of the operation.
By default the ACS CLI stores the detailed results of all bulk operations in ~/.acs/reports/<stack-name>, with the exception of the bulk-fetch-license command, whose results are stored in ~/.acs/reports. You can optionally specify the file where you want to store the results of any bulk operation using the --report-file flag.
After a bulk operation completes, make sure to run the acs status current-stack command to see if a restart is required. Some app and index state changes can require a Splunk restart. When checking status in a search head cluster environment, it can take a few seconds for the restartRequired field to populate accurately.
You can also run the acs status current-stack command before you run a bulk operation to make sure that your deployment is in a proper state and does not require a restart as a result of previous operations.
Create HEC tokens in bulk
For help, run acs hec-token bulk-create --help.
To create HEC tokens in bulk:
Run the acs hec-token bulk-create command, specifying an input JSON file that contains the list of HEC tokens to create. For example:
acs hec-token bulk-create --file path/to/input/create_hec-token.json
Example input JSON file for create HEC tokens in bulk
{
"hec-tokens": [
{
"name": "mock-token-1"
},
{
"name": "mock-token-2",
"defaultIndex": "main"
},
{
"name": "mock-token-3",
"allowedIndexes": [
"main"
]
},
{
"name": "mock-token-4",
"allowedIndexes": [
"main"
],
"defaultIndex": "main",
"defaultSource": "/var/log/messages"
},
{
"name": "mock-token-5",
"allowedIndexes": [
"main",
"summary"
],
"defaultIndex": "summary",
"defaultSource": "/var/log/messages"
}
]
Update HEC tokens in bulk
For help, run acs hec-token bulk-update --help.
To update HEC tokens in bulk:
Run the acs hec-token bulk-update command, specifying an input JSON file that contains the list of HEC tokens to update. For example:
acs hec-token bulk-update --file path/to/input/update_hec-token.json
Example input JSON file for update HEC tokens in bulk
{
"hec-tokens": [
{
"name": "mock-token-1",
"defaultIndex": "main"
},
{
"name": "mock-token-2",
"defaultIndex": "summary"
},
{
"name": "mock-token-3",
"allowedIndexes": [
"main",
"summary"
]
},
{
"name": "mock-token-4",
"allowedIndexes": [
"main",
"summary"
],
"defaultIndex": "summary",
"defaultSource": "/var/log/messages"
},
{
"name": "mock-token-5",
"allowedIndexes": [
"main",
"summary"
],
"defaultIndex": "summary",
"defaultSource": "/var/log/messages"
},
{
"name": "mock-token-6",
"allowedIndexes": [
"main",
"summary"
],
"defaultIndex": "summary",
"defaultSource": "/var/log/messages"
}
Delete HEC tokens in bulk
For help, run acs hec-token bulk-delete --help.
To delete indexes in bulk:
Run the acs hec-token bulk-delete command, specifying the input JSON file that contains the list of HEC tokens to delete. For example:
acs hec-token bulk-delete --file path/to/input/delete_hec-token.json
Example input JSON file for delete HEC tokens in bulk
{
"hec-tokens": [
"mock-token-1",
"mock-token-2",
"mock-token-3",
"mock-token-4",
"mock-token-5",
"mock-token-6"
]
}
Create indexes in bulk
For help, run acs indexes bulk-create --help.
To create indexes in bulk:
Run the acs indexes bulk-create command, specifying an input JSON file that contains the list of indexes to create. For example:
acs indexes bulk-create --file path/to/input/create_indexes.json
Example input JSON file for create indexes in bulk
{
"indexes": [
{
"name": "bulk-index-0",
"datatype": "event",
"maxDataSizeMB": 512
},
{
"name": "bulk-index-1",
"datatype": "event",
"maxDataSizeMB": 512,
"searchableDays": 90,
"splunkArchivalRetentionDays": 1000
},
{
"name": "bulk-index-2",
"datatype": "event",
"maxDataSizeMB": 512,
"searchableDays": 90,
"splunkArchivalRetentionDays": 1000
},
{
"name": "bulk-index-3",
"datatype": "event",
"maxDataSizeMB": 512,
"searchableDays": 90,
"selfStorageBucketPath": "s3://selfStorageBucket/selfStorageBucketFolder"
},
{
"name": "bulk-index-4",
"datatype": "event",
"maxDataSizeMB": 512,
"searchableDays": 90,
"selfStorageBucketPath": "s3://selfStorageBucket/selfStorageBucketFolder"
}
]
}
After the acs indexes bulk-create command completes, you can run acs indexes list to confirm index creation.
In some cases, when performing bulk index operations on Classic Experience, the operation completes successfully for the first index (status code 202), but the operation fails for subsequent indexes. This failure occurs when a configuration bundle validation/reload remains in progress. See Bundle validation remains in progress and does not complete. If you experience this failure, you can retry the bulk index operation, perform the index operation using non-bulk CLI commands, or contact Splunk Support.
For more information on the DDAA and DDSS parameters for index creation and update, see Create a new index with DDAA or DDSS.
Update indexes in bulk
For help, run acs indexes bulk-update --help.
To update indexes in bulk:
Run the acs indexes bulk-update command, specifying an input JSON file that contains the list of indexes to create. For example:
acs indexes bulk-update --file path/to/input/update_indexes.json
Example input JSON file for update indexes in bulk
{
"indexes": [
{
"name": "bulk-index-0",
"maxDataSizeMB": 512
},
{
"name": "bulk-index-1",
"maxDataSizeMB": 512
"searchableDays": 90,
"splunkArchivalRetentionDays": 1000
},
{
"name": "bulk-index-2",
"maxDataSizeMB": 512
"searchableDays": 90,
"splunkArchivalRetentionDays": 1000
},
{
"name": "bulk-index-3",
"maxDataSizeMB": 512
"searchableDays": 90,
"selfStorageBucketPath": "s3://selfStorageBucket/selfStorageBucketFolder"
},
{
"name": "bulk-index-4",
"maxDataSizeMB": 512
"searchableDays": 90,
"selfStorageBucketPath": "s3://selfStorageBucket/selfStorageBucketFolder"
}
]
}
After the acs indexes bulk-update command completes, you can run acs indexes list to confirm index update.
In some cases, when performing bulk index operations on Classic Experience, the operation completes successfully for the first index (status code 202), but the operation fails for subsequent indexes. This failure occurs when a configuration bundle validation/reload remains in progress. See Bundle validation remains in progress and does not complete. If you experience this failure, you can retry the bulk index operation, perform the index operation using non-bulk CLI commands, or contact Splunk Support.
Delete indexes in bulk
For help, run acs indexes bulk-delete --help.
To delete indexes in bulk:
Run the acs indexes bulk-delete command, specifying the input JSON file that contains the list of indexes to delete. For example:
acs indexes bulk-delete --file path/to/input/delete_indexes.json
Example input JSON file for delete indexes in bulk
{
"indexes": [
"mock-index-1",
"mock-index-2",
"mock-index-3",
"mock-index-4",
"mock-index-5"
]
}
After the acs indexes bulk-delete command completes, you can run acs indexes list to confirm index deletion.
In some cases, when performing bulk index operations on Classic Experience, the operation completes successfully for the first index (status code 202), but the operation fails for subsequent indexes. This failure occurs when a configuration bundle validation/reload remains in progress. See Bundle validation remains in progress and does not complete. If you experience this failure, you can retry the bulk index operation, perform the index operation using non-bulk CLI commands, or contact Splunk Support.
Vet and install private apps in bulk
For help, run acs apps bulk-install private --help.
When you install private app in bulk using acs apps bulk-install private, the command automatically runs the following installation steps for each app package in the specified source directory:
- Submits the app to AppInspect for inspections
- Gets the app inspection status
- Installs the app using the ACS endpoint
To vet and install private apps in bulk:
Run the acs apps bulk-install private command, specifying a source directory that contains the app packages you want to inspect and install. When you install a private app, you must also specify --acs-legal-ack=Y to acknowledge your acceptance of any risks involved in the installation of unsupported apps on your system. See Set up the ACS API. For example:
acs apps bulk-install private --package-src-dir path/to/packages \ --acs-legal-ack=Y
You must provide your splunk.com login credentials before app installation can proceed. To specify these credentials securely, set the SPLUNK_USERNAME and SPLUNK_PASSWORD environment variables in advance. If you do not set these environment variables, the ACS CLI prompts you to enter them.
The acs apps bulk-install private command output shows the status of app vetting and app installation, including a summary of the app validation report. You can identify each app in the output by its unique identifier value. For example:
Processing app: empty_app.tgz
Inspecting your private app...
Submitted app for inspection (requestId='2b24db68-783f-4818-8786-c6f888120097')
Waiting for inspection to finish...
processing...success
Vetting completed, summary:
{
"error": 0,
"failure": 2,
"skipped": 157,
"manual_check": 0,
"not_applicable": 4,
"warning": 0,
"success": 8
}
{
"identifier": "inspect-empty_app.tgz",
"requestID": "2b24db68-783f-4818-8786-c6f888120097",
"statusCode": 200,
"message": "vetting failed (failures=2, errors=0, manual check=0)",
"response": "{\"request_id\":\"2b24db68-783f-4818-8786-c6f888120097\",\"status_code\":200,\"status\":\"SUCCESS\",\"info\":{\"error\":0,\"failure\":2,\"skipped\":157,\"manual_check\":0,\"not_applicable\":4,\"warning\":0,\"success\":8},\"links\":[{\"rel\":\"self\",\"href\":\"/v1/app/validate/status/2b24db68-783f-4818-8786-c6f888120097\"},{\"rel\":\"report\",\"href\":\"/v1/app/report/2b24db68-783f-4818-8786-c6f888120097\"}]}",
"content-type": ""
}
Installing the app...
{
"identifier": "install-empty_app.tgz",
"requestID": "aed48907-416c-9d23-ade0-96b8c9841a89",
"statusCode": 400,
"message": "Extract app information from the package failed. Please refer https://docs.splunk.com/Documentation/SplunkCloud/latest/Config/ACSerrormessages for general troubleshooting tips.",
"response": "{\"code\":\"400-bad-request\",\"message\":\"Extract app information from the package failed. Please refer https://docs.splunk.com/Documentation/SplunkCloud/latest/Config/ACSerrormessages for general troubleshooting tips.\"}\n",
"content-type": "application/json; charset=UTF-8"
}
To get detailed information about the cause of app vetting failures, review the full app validation report generated by AppInspect. You can retrieve the report using either the AppInspect API or the Splunk Web UI. For instructions on how to retrieve the report using the AppInspect API, see Validate your private app. For instructions on how to retrieve your report in the Splunk Web UI, see View app validation report (Victoria Experience).
You can also vet apps in bulk without installing them, and install pre-vetted apps in bulk:
To inspect apps only in bulk:
acs apps bulk-install private --package-src-dir path/to/packages --app-inspect-only
To install pre-vetted apps only in bulk:
acs apps bulk-install private --package-src-dir path/to/packages --install-only \ --acs-legal-ack=Y
After the acs apps bulk-install private command completes, you can run acs apps list to confirm app installation.
After you install private apps in bulk, make sure to clean up your app package source directory. Running the bulk-install private command unnecessarily for apps that are already installed can return a 409 error and negatively impact performance.
Install Splunkbase apps in bulk
For help, run acs apps bulk-install splunkbase --help.
To install Splunkbase apps in bulk:
Run the acs apps bulk-install splunkbase command, specifying an input JSON file that contains the list of apps to install, including the Splunkbase id for each app, along with its version and third-party URL to acknowledge your acceptance of any risks. If you do not specify the version, ACS installs the latest version from Splunkbase. If you do not specify the URL, the ACS CLI will fetch it for you and prompt you for acknowledgement. For example:
acs apps bulk-install splunkbase --file /apps/test/bulk_splunkbase_apps.json
Example input JSON file for install Splunkbase apps in bulk
{ "apps": [
{
"id": 742,
"version": "",
"license": ""
},
{
"id": 3662,
"version": "5.1.0",
"license": "https://license-url.com"
}
]
}
You must specify your splunk.com login credentials before app installation can proceed. To specify these credentials securely, set the SPLUNK_USERNAME and SPLUNK_PASSWORD environment variable to the appropriate values. If you do not set the environment variables, the ACS CLI prompts you to enter them.
Fetch licenses for Splunkbase apps in bulk
To simplify the process of adding multiple Splunkbase licenses and for non-interactive use cases, the ACS CLI provides the acs apps bulk-fetch-license command, which fetches licenses for Splunkbase apps in bulk. You can use the output of this command to generate the input file for the bulk install command.
You must specify an input JSON file that contains a list of the apps, including Splunkbase id and version, whose licenses you want to fetch. If the app version is not specified, ACS uses the latest version. For example:
{
"apps": [
{
"id": 1620
},
{
"id": 1274,
"version": "6.0.3"
},
{
"id": 742,
"version": "8.5.0"
}
]
}
You must also specify an output file to store the list of apps along with their licenses using the --output-file flag. You can use this output file as an input for Splunkbase app installation in bulk. For example:
acs apps bulk-fetch-license --file path/to/input/apps.json \ --output-file path/to/acs/generated/apps.json
acs apps bulk-install splunkbase --file path/to/acs/generated/apps.json \
By default, results of the acs apps bulk-fetch-license command are stored in ~/.acs/reports You can optionally specify a file where you want to store the results using the -- report-file flag.
After the acs apps bulk-install splunkbase command completes, you can run acs apps list to confirm app installation.
Uninstall apps in bulk
For help, acs apps bulk-uninstall --help.
To uninstall private apps or Splunkbase apps in bulk:
Run the acs apps bulk-uninstall command. You must specify an input JSON file that contains the list of apps to uninstall. For example:
acs apps bulk-uninstall --file /path/to/input/file.json
Example input JSON file for apps bulk-uninstall
{
"apps": [
"opsgenie3",
"TA-eStreamer",
"netflow"
]
}
After the acs apps bulk-uninstall command completes, you can run acs apps list to confirm app deletion.
Export apps in bulk
For help, run acs apps export --help
To export apps in bulk:
Run the acs apps export command, specifying an input JSON file that contains the list of apps to export. You can export up to 20 apps. For example:
acs apps export --file=apps_to_export.json
The command outputs app data as a tar file in the format <app_id>.tgz.
You can optionally specify the --default, --local, --users, or --confs-only flags to limit data export to the specified directories or configuration files only. You can also use the --export-dir option to specify a custom output directory, and use the --log-file option to export a custom log file with your app data. For example:
acs apps export --file=apps_to_export.json --default=true --local=true --users=false --confs-only=false --export-dir=path/to/output/dir/ --log-file="app_export_log.txt"
Example input JSON file for apps export
{"Apps":["app_id1", "app_id2"]}
For more information on ACS app export, see Export apps in Splunk Cloud Platform.
ACS CLI enhancements for automation use cases
ACS CLI version 2.6.0 and higher provides enhancements that support non-interactive use cases, such as automated CI/CD pipelines and scripts. These enhancements include exit codes for execution errors, as well as new structured and verbose output formatting options.
Exit codes
The ACS CLI now exits with a non-zero code whenever an error occurs during execution. Additionally, unexpected HTTP status codes returned in requests made by the client on behalf of the user are treated as errors, and will cause the CLI to exit with a code of 2. Automation can use this information to check if the error was bad HTTP status code.
| Exit code | Description |
|---|---|
| 0 | Operation successful. This is the POSIX standard meaning of exit code 0, and shells will automatically distinguish exit code 0 from all the others. |
| 1 | General error. The application was unable to complete the action for some reason. |
| 2 | Unexpected HTTP request response. The client made a request to a server on behalf of the user, and did not get the desired response back. |
In addition to the exit code, the client will print human-readable information about any failure to the system's standard error (stderr) stream.
Output formatting options
The ACS CLI provides the following output formatting options:
-f, --format string Controls the output format of the CLI.
The "pretty" format is optimized for interactive use.
The "structured" format is more parsable for automation. (default "pretty")
-v, --verbose Configures the client to print detailed messages
The "pretty" format prints roughly the same as the current CLI, and is the default format unless otherwise specified.
The "structured" format prints all messages in JSON format with the following schema:
{
"type": "<message type, currently have 'http', 'message', 'json'>",
<message type specific fields...>
},
<other messages...>
]
All informational messages are printed to the system's standard output stream (stdout), while errors are printed to the system's standard error stream (stderr). This applies both to the "pretty" and "structured" formats. Therefore, the contents of stdout will always be parsable in the "structured" output format mode, regardless of whether errors occurred. This means that script users can pipe stdout to their own parser scripts in most scenarios. In "structured" formatting mode, if the stdout and stderr streams are combined, then the output may not be parsable, so it is best not to combine them when inputting them into their parser scripts.
When you specify the --verbose flag, the CLI generates messages that contain additional information. This can be useful for debugging and other troubleshooting situations.
Message type schemas
Schema for http messages:
{
"type": "http",
"response": "raw HTTP response body, usually JSON-encoded, but content-type declares the format",
"statusCode": <http response code, an integer>,
"message": "custom string message, may be blank",
"content-type": "value of the Content-Type HTTP response header, used to help parse the body",
"requestID": "request ID, which can be used to trace the request"
}
Schema for json messages:
{
"message": "custom string message, may be blank",
"json": "JSON-encoded content",
"type": "json"
}
Schema for basic messages:
{
"message": "message contents",
"type": "message"
}
Schema for stack-info messages (used in the acs config subcommand):
{
"stack": {
"name": "stack name",
"type": "victoria" or "classic"
},
"type": "stack-info"
}
Schema for bulk-item-result messages (used in bulk operations):
{
"identifier": "bulk result identifier",
"message": "message contents",
"requestID": "0ff9bc6d-a284-9da7-ae98-243db68ddfcd",
"response": "bulk result response body, usually JSON",
"statusCode": <http response code>,
"type": "bulk-item-result",
"content-type": ""value of the Content-Type HTTP response header, used to help parse the body"
}
Additionally, all regular messages involved in bulk operations will have the same schema, with the addition of the "identifier" field, as in:
{
"identifier": "bulk request identifier"
<regular fields for the message type...>
}
Examples of Structured Output Parsing
This section lists a few basic examples of parsing the JSON encoded output of a subcommand when in structured output mode. It assumes that jq is installed on the machine. Users are free to parse the output however way they wish, including with jq as shown below, or by calling the ACS command-line interface from a Python script, etc.
Add a Stack and return its name
acs --format structured config add-stack test-stack | jq .[0].stack.name "test-stack"
List Token users, identifiers, and expiry date
acs --format structured token list | jq .[0].response --raw-output | jq '.[] | "\(.user) \(.id) \(.expiresOn)"' --raw-output admin 2297ea6fa887da503e315b81d43f30fc6d0d2469af89ac4f3445f1b6573c31eb 2022-09-14T19:08:29Z admin da7454d31fe9dc4236b95efdf0a500d2960018fedbd8ce9b9547030cf4dcd5ec 2022-09-14T19:08:33Z admin fa74cce347e250e32001df28075a5cc277d0666212e95f3b75c3fbdeef55d94a 2022-09-14T19:08:36Z admin fd56bc270326f88cf37e3367a0275b46110c305aa1fcc9d2267478f40d42491b 2022-09-14T19:02:50Z
List the name, number of events, and data types for all indexes
acs --format structured indexes list | jq .[0].response --raw-output | jq '.[] | "\(.name) \(.totalEventCount) \(.datatype)"' --raw-output history 0 event lastchanceindex 0 event main 0 event splunklogger 0 event summary 0 event
| Admin Config Service (ACS) API endpoint reference | Troubleshoot ACS error messages |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Download manual
Feedback submitted, thanks!