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. (Private app management and Splunkbase app management require 8.2.2112 or higher.)
  • Have the sc_admin role.
  • Have a Mac or Linux operating system.
  • Install Homebrew. (See Homebrew installation instructions and Homebrew requirements for Mac and Linux).

Install or upgrade the ACS CLI

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

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 and the login credentials (username and password) of the current 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. You can specify a token value using the acs login --token parameter, which skips generating a new token and caches the specified token value.

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

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 either your splunk.com login credentials (e.g. acs apps install splunkbase) or the login credentials of the current Splunk Cloud Platform deployment (e.g. acs login and acs token create). In both cases, you can specify these login credentials using the --username and --password flags with the command.

If you do not specify the required login credentials with the command, you will be prompted to enter them.

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, and describe 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.
Manage private apps acs apps Install, list, describe, and uninstall private apps.
Manage Splunkbase apps acs apps Install, update, list, describe, and uninstall Splunkbase apps.

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 the current deployment. You can specify these using the --username and --password flags, or when prompted 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.

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.

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
Last modified on 01 June, 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 (latest FedRAMP release), 8.2.2202, 8.2.2203


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