Splunk Cloud Platform

Admin Config Service Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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_admin role has all 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:

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.

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

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.com 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.

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:

  1. Add a deployment (acs config add-stack <stack-name>)
  2. Set the current deployment (acs config use-stack <stack-name>)
  3. Log in/create authentication token (acs login)
  4. 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. For example:

$ acs config add-stack my-company-name --stack-type victoria

Stack added: my-company-name , Type: victoria 
Please run "acs config use-stack" to use this stack for further CLI 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

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.

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, run the acs setup command, specifying the stack-name and --token-user value. For example:

acs setup <stack name> --token-user test_acs_user

For deployments on Classic Experience, you must also explicitly specify --stack-type classic. For example:

acs setup <stack name> --token-user test_acs_user --stack-type classic

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.

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.
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.
Manage indexes acs indexes Create, delete, describe, list, and update indexes. Supports DDAA and DDSS parameters for index creation and updating in ACS CLI version 2.4.0 and higher. Supports bulk-create and bulk-delete in ACS CLI version 2.5.0 and higher. See Create indexes in bulk.
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 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.

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": "eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnIjoiSFM1MTIiLCJ2ZXIiOiJ2MiIsInR0eXAiOiJzdGF0aWMifQ.eyJpc3MiOiJ0ZXN0X2Fjc……9kFQ",
    "status": "enabled",
    "expiresOn": "2022-04-03T19:55:16Z",
    "notBefore": "2022-03-04T19:55:16Z"
}

Example 2. Get authentication token information:

$ acs token describe 0c00464d6e55dc779dd862cf9c541d99b9a8380022fb20d4a1e822bfd17965ca
{
    "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 11d61711dd4f069a772bf6e4ca4d5debf3e8ac71fbc9dab7cdbce1f887bab8f1
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-062a2051d8d7dc48b.acs-noah-eng.splunkcloud.com",
            "defaultIndex": "default",
            "defaultSource": "",
            "defaultSourcetype": "",
            "disabled": false,
            "name": "testcli",
            "useAck": false
        },
        "token": "9231927a-2e52-4893-a799-5f766b634b91"
    }
}

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-062a2051d8d7dc48b.acs-noah-eng.splunkcloud.com",
            "defaultIndex": "main",
            "defaultSource": "",
            "defaultSourcetype": "",
            "disabled": false,
            "name": "testcli",
            "useAck": false
        },
        "token": "9231927a-2e52-4893-a799-5f766b634b91"
    }
}

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-062a2051d8d7dc48b.acs-noah-eng.splunkcloud.com",
                "defaultIndex": "main",
                "defaultSource": "acs-noah-eng.splunkcloud.com",
                "defaultSourcetype": "",
                "disabled": false,
                "name": "runscope_2022-01-02-12-37",
                "useAck": false
            },
            "token": "d6a3d5de-a617-4e1f-b70b-abfe2e8c0557"
        },
        {
            "spec": {
                "allowedIndexes": [
                    "main"
                ],
                "defaultHost": "sh-i-062a2051d8d7dc48b.acs-noah-eng.splunkcloud.com",
                "defaultIndex": "main",
                "defaultSource": "acs-noah-eng.splunkcloud.com",
                "defaultSourcetype": "",
                "disabled": false,
                "name": "runscope_2022-01-13-17-40",
                "useAck": false
            },
            "token": "b2ace4e6-5e4c-41ea-93c7-b4a3facc3e72"
        }
    ]
}

Manage indexes

For help, run acs indexes --help.

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 index create --help or acs index update --help.

For detailed information on DDAA and DDSS parameters for index creation and update, see Create a new index with DDAA or DDSS.

ACS supports index management on Splunk Cloud Platform deployments on Victoria Experience only.

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"
}

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"
}

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.

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.4"
}

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.1 --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.1"
}

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 apps and indexes. You can use bulk commands to minimize repetitive administration tasks when managing large numbers of apps and indexes. 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.

The ACS CLI provides the following commands for bulk operations:

  • acs indexes bulk-delete

  • acs indexes bulk-create
  • acs apps bulk-install private

  • acs apps bulk-fetch-license

  • acs apps bulk-install splunkbase

  • acs apps bulk-uninstall

When you run ACS CLI bulk commands, you must specify either an input JSON file that contains a list of apps and indexes, 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 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.

For more information on the DDAA and DDSS parameters for index creation and update, see Create a new index with DDAA or DDSS.

Delete indexes in bulk

For help, run acs indexes bulk-delete --help.

To create 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.

Vet and install private apps in bulk

For help, run acs apps bulk-install private --help.

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. 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. If you do not set these environment variables, the ACS CLI prompts you to enter them.

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, as specified in the Splunk legal disclaimer for app installation, which is provided in the ACS OpenAPI 3.0 specification. Please refer to the API documentation for limitations and more detail.

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 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.

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
Last modified on 12 November, 2022
PREVIOUS
Admin Config Service (ACS) API endpoint reference
  NEXT
Troubleshoot ACS error messages

This documentation applies to the following versions of Splunk Cloud Platform: 8.2.2109, 8.2.2111, 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209 (latest FedRAMP release)


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters