LogoLogo
StackState.comDownloadSupportExplore playground
StackState v5.1
StackState v5.1
  • Welcome to the StackState docs!
  • StackState self-hosted v5.1 docs
  • Getting Started
  • 🚀Setup
    • Install StackState
      • Requirements
      • Kubernetes / OpenShift
        • Kubernetes install
        • OpenShift install
        • Required Permissions
        • Non-high availability setup
        • Override default configuration
        • Configure storage
        • Configure Ingress
        • Install from custom image registry
        • Migrate from Linux install
      • Linux
        • Before you install
        • Download
        • Install StackState
        • Install with production configuration
        • Install with development configuration
        • Install with POC configuration
        • Set up a reverse proxy
        • Set up TLS without reverse proxy
      • Initial run guide
      • Troubleshooting
    • Upgrade StackState
      • Steps to upgrade
      • Version specific upgrade instructions
      • StackPack versions
      • StackState release notes
    • StackState Agent
      • About StackState Agent V3
      • Docker
      • Kubernetes / OpenShift
      • Linux
      • Windows
      • Advanced Agent configuration
      • Use an HTTP/HTTPS proxy
      • Agent V1 (legacy)
      • Migrate Agent V1 to Agent V2
        • Linux
        • Docker
    • StackState CLI
      • CLI: sts
      • CLI: stac (deprecated)
      • Comparison between CLIs
    • Data management
      • Backup and Restore
        • Kubernetes backup
        • Linux backup
        • Configuration backup
      • Data retention
      • Clear stored data
  • 👤Use
    • Concepts
      • The 4T data model
      • Components
      • Relations
      • Health state
      • Layers, Domains and Environments
      • Perspectives
      • Anomaly detection
      • StackState architecture
    • StackState UI
      • Explore mode
      • Filters
      • Views
        • About views
        • Configure the view health
        • Create and edit views
        • Visualization settings
      • Perspectives
        • Topology Perspective
        • Events Perspective
        • Traces Perspective
        • Metrics Perspective
      • Timeline and time travel
      • Analytics
      • Keyboard shortcuts
    • Checks and monitors
      • Checks
      • Add a health check
      • Anomaly health checks
      • Monitors
      • Manage monitors
    • Problem analysis
      • About problems
      • Problem lifecycle
      • Investigate a problem
      • Problem notifications
    • Metrics
      • Telemetry streams
      • Golden signals
      • Top metrics
      • Add a telemetry stream
      • Browse telemetry
      • Set telemetry stream priority
    • Events
      • About events
      • Event notifications
      • Manage event handlers
    • Glossary
  • 🧩StackPacks
    • About StackPacks
    • Add-ons
      • Autonomous Anomaly Detector
      • Health Forecast
    • Integrations
      • About integrations
      • 💠StackState Agent V2
      • 💠AWS
        • AWS
        • AWS ECS
        • AWS X-ray
        • StackState/Agent IAM role: EC2
        • StackState/Agent IAM role: EKS
        • Policies for AWS
        • AWS (legacy)
        • Migrate AWS (legacy) to AWS
      • 💠Dynatrace
      • 💠Kubernetes
      • 💠OpenShift
      • 💠OpenTelemetry
        • About instrumentations
        • AWS NodeJS Instrumentation
        • Manual Instrumentation
          • Prerequisites
          • Tracer and span mappings
          • Relations between components
          • Span health state
          • Merging components
          • Code examples
      • 💠ServiceNow
      • 💠Slack
      • 💠Splunk
        • Splunk
        • Splunk Events
        • Splunk Health
        • Splunk Metrics
        • Splunk Topology
      • 💠VMWare vSphere
      • Apache Tomcat
      • Azure
      • Cloudera
      • Custom Synchronization
      • DotNet APM
      • Elasticsearch
      • Humio
      • Java APM
      • JMX
      • Logz.io
      • MySQL
      • Nagios
      • OpenMetrics
      • PostgreSQL
      • Prometheus
      • SAP
      • SCOM
      • SolarWinds
      • Static Health
      • Static Topology
      • Traefik
      • WMI
      • Zabbix
    • Develop your own StackPacks
  • 🔧Configure
    • Topology
      • Component actions
      • Identifiers
      • Topology naming guide
      • Topology sources
      • Create a topology manually
      • Configure topology synchronizations
      • Enable email event notifications
      • Send topology data over HTTP
      • Set the topology filtering limit
      • Use a proxy for event handlers
      • Use tags
      • Tune topology synchronization
      • Debug topology synchronization
    • Telemetry
      • Add telemetry during topology synchronization
      • Data sources
        • Elasticsearch
        • Prometheus mirror
      • Send events over HTTP
      • Send metrics data over HTTP
      • Set the default telemetry interval
      • Debug telemetry synchronization
    • Traces
      • Set up traces
      • Advanced configuration for traces
    • Health
      • Health synchronization
      • Send health data over HTTP
        • Send health data
        • Repeat Snapshots JSON
        • Repeat States JSON
        • Transactional Increments JSON
      • Debug health synchronization
    • Anomaly Detection
      • Export anomaly feedback
      • Scale the AAD up and down
      • The AAD status UI
    • Security
      • Authentication
        • Authentication options
        • File based
        • LDAP
        • Open ID Connect (OIDC)
        • KeyCloak
        • Service tokens
      • RBAC
        • Role-based Access Control
        • Permissions
        • Roles
        • Scopes
        • Subjects
      • Secrets management
      • Self-signed certificates
      • Set up a security backend for Linux
      • Set up a security backend for Windows
    • Logging
      • Kubernetes logs
      • Linux logs
      • Enable logging for functions
  • 📖Develop
    • Developer guides
      • Agent checks
        • About Agent checks
        • Agent check API
        • Agent check state
        • How to develop Agent checks
        • Connect an Agent check to StackState
      • Custom functions and scripts
        • StackState functions
        • Check functions
        • Component actions
        • Event handler functions
        • ID extractor functions
        • Mapping functions
        • Monitor functions
        • Propagation functions
        • Template functions
        • View health state configuration functions
      • Custom Synchronization StackPack
        • About the Custom Synchronization StackPack
        • How to customize elements created by the Custom Synchronization StackPack
        • How to configure a custom synchronization
      • Integrate external services
      • Mirroring Telemetry
      • Monitors
        • Create monitors
        • Monitor STJ file format
      • StackPack development
        • How to create a StackPack
        • Packaging
        • How to get a template file
        • How to make a multi-instance StackPack
        • Prepare a multi-instance provisioning script
        • Upload a StackPack file
        • Prepare a shared template
        • Customize a StackPack
        • Prepare instance template files
        • Prepare a StackPack provisioning script
        • Resources in a StackPack
        • StackState Common Layer
      • Synchronizations and templated files
    • Reference
      • StackState OpenAPI docs
      • StackState Template JSON (STJ)
        • Using STJ
        • Template functions
      • StackState Markup Language (STML)
        • Using STML
        • STML Tags
      • StackState Query Language (STQL)
      • StackState Scripting Language (STSL)
        • Scripting in StackState
        • Script result: Async
        • Script result: Streaming
        • Time in scripts
        • Script APIs
          • Async - script API
          • Component - script API
          • HTTP - script API
          • Prediction - script API
          • StackPack - script API
          • Telemetry - script API
          • Time - script API
          • Topology - script API
          • UI - script API
          • View - script API
    • Tutorials
      • Create a simple StackPack
      • Push data to StackState from an external system
      • Send events to StackState from an external system
      • Set up a mirror to pull telemetry data from an external system
Powered by GitBook
LogoLogo

Legal notices

  • Privacy
  • Cookies
  • Responsible disclosure
  • SOC 2/SOC 3
On this page
  • Overview
  • Install the stac CLI
  • Linux install
  • Windows install
  • Docker install (macOS, Linux, Windows)
  • Configure the stac CLI
  • Configuration wizard (Linux and Windows install)
  • Manual configuration (Docker)
  • Add multiple configurations
  • Authentication
  • API key - Receiver API
  • API token - Base API and Admin API
  • Custom tool authentication
  • Upgrade
  • Uninstall
  • Use the stac CLI
  • License
  1. Setup
  2. StackState CLI

CLI: stac (deprecated)

StackState Self-hosted v5.1.x

PreviousCLI: stsNextComparison between CLIs

Last updated 2 years ago

Overview

The new sts CLI replaces the stac CLI. It's advised to install the new sts CLI and upgrade any installed instance of the old sts CLI to stac. For details see:

The StackState stac CLI provides easy access to the functionality provided by the StackState APIs. It can be used to configure StackState, work with data, automate using StackState data and help with developing StackPacks. You can configure the CLI to work with multiple instances of StackState.

Install the stac CLI

A standalone executable is available to run the stac CLI on and . You can also run the stac CLI on Linux, Windows or macOS.

You can install and run the stac CLI on the same machine as the .

Linux install

The steps below describe how to install the stac CLI on Linux using the standalone executable file. If you prefer, you can run the stac CLI .

Requirements:

  • Access to the StackState APIs.

Installation:

  1. Download the Linux executable sts-cli-VERSION-linux64 from where the VERSION is the same as the StackState version you are running. For example, download sts-cli-5.0.0-linux64 if you are running StackState v5.0.0.

  2. Rename the downloaded file to be stac and make it executable:

    mv sts-cli-VERSION-linux64 stac
    chmod +x stac
  3. (optional) Add the file to your PATH to use stac CLI commands from .

  4. To configure the StackState CLI, do one of the following:

    • (recommended).

    • .

Windows install

Requirements:

  • Access to the StackState APIs.

Installation:

  1. Rename the downloaded file to be stac.exe.

  2. To configure the StackState CLI, do one of the following:

Docker install (macOS, Linux, Windows)

The StackState CLI can be run inside a Docker container on Linux, Windows or macOS. The ZIP archive provided contains scripts that run the CLI without needing to worry about Docker invocations.

Requirements:

  • Access to the StackState APIs.

  • Internet connection for first time run.

Installation:

  1. The ZIP archive contains the following files:

    .
    +-- bin
    |   +-- sts     # Script to run the stac CLI in Docker for bash
    |   +-- sts.ps1 # Script to run the stac CLI in Docker for Powershell
    +-- conf.d
    |   +-- conf.yaml.example # Example stac CLI configuration
    |   +-- VERSION           # The stac CLI version to retrieve from Docker hub
    +-- templates
    |   +-- topology   # Topology templates in a format specific to the stac CLI
    +-- release_notes.md  # Changelog of the stac CLI
    +-- usage.md          # How to configure and use this package
  2. Rename the bash and Powershell scripts in the bin directory to use the new stac name:

    • Script to run the CLI in Docker for bash: Rename from sts to stac.

    • Script to run the CLI in Docker for Powershell: Rename from sts.ps1 to stac.ps1.

Configure the stac CLI

After a new installation, the stac CLI must be configured with the API connection details for your StackState instance. If you upgraded from a previous version of the CLI, it isn't necessary to configure the CLI again, the existing CLI configuration will be used.

The standalone executable StackState CLI on Linux or Windows includes a wizard to guide you through configuration. If you installed the Docker version of the stac CLI on macOS, Linux or Windows, the configuration file must be manually created.

Configuration wizard (Linux and Windows install)

If the stac CLI was installed on Linux or Windows using a standalone executable file, the first time you run any stac command, a configuration wizard will request the required configuration items. The wizard will then create a configuration file with the entered details and store it under the user's home directory. If a valid configuration file already exists, the stac CLI will use this and the configuration wizard won't run.

The configuration wizard isn't available when the stac CLI is run inside a Docker container on macOS, Linux or Windows.

Example configuration wizard:

$ stac graph list-types
No config was found. Would you like to configure the CLI using this wizard? (Y/n): Y

StackState URL: https://company.stackstate.com/
Your API token (see https://company.stackstate.com/#/cli ):
Admin API URL (default: https://company.stackstate.com/admin):
Receiver API URL (default: https://company.stackstate.com/receiver):
Receiver API key (default: API_KEY):
Hostname used for receiver ingestion via the CLI (default: mycli):

Thank you! Config file saved to: /Users/myuser/.stackstate/cli/conf.yaml

Manual configuration (Docker)

  1. Copy the file conf.d/conf.example.yaml from the ZIP archive and put it in one of the following directories:

    • Docker:

      • conf.d/ - relative to the directory where the stac CLI is run.

    • Linux or Windows:

      • conf.d/ - relative to the directory where the stac CLI is run.

      • ~/.stackstate/cli/ - relative to the user's home directory.

      • %APPDATA%/StackState/cli/ - relative to the user's home directory.

  2. Rename the file to be conf.yaml.

  3. Edit the file and add:

    • URLs to the StackState APIs.

    • Client details.

## The CLI uses an instance of StackState for all its commands.
## Unless the `--instance` argument is passed the CLI will pick the `default` instance as configured below.
## Other instances follow the exact same configuration pattern as the instance below.
instances:
  default:
    base_api:
      url: "https://stackstate.mycompany.com"
      # Get the api token from the user interface, see https://stackstate.mycompany.com/#/cli
      apitoken_auth:
        token: '???'
      ## HTTP basic authentication.
      #basic_auth:
        #username: '???'
        #password: '???'
    receiver_api:
      url: "https://stackstate.mycompany.com/receiver"
      ## HTTP basic authentication.
      #basic_auth:
        #username: '???'
        #password: '???'
    admin_api:
      url: "https://stackstate.mycompany.com/admin"
      # Get the api token from the user interface, see https://stackstate.mycompany.com/#/cli
      apitoken_auth:
        token: '???'
      ## HTTP basic authentication.
      #basic_auth:
        #username: '???'
        #password: '???'

    ## The CLI uses a client configuration to identify who is sending to the StackState instance. The client
    ## is used to send topology and telemetry to the receiver API.
    ##
    ## Unless the `--client` argument is passed the CLI will pick the `default` instance as configured below.
    ## Other clients follow the exact same configuration pattern as the default client. You may simply copy-paste its config and modify whatever is needed.
    clients:
      default:
        api_key: "<STACKSTATE_RECEIVER_API_KEY>"
        ## The name of the host that's passed to StackState when sending. Leave these values unchanged
        ## if you have no idea what to fill here.
        hostname: "hostname"
        internal_hostname: "internal_hostname"

Add multiple configurations

The conf.yaml configuration file for the stac CLI can hold multiple configurations. Other StackState instances can be added on the same level as the default configuration. For example:

instances:
  default:
    base_api:
      ...
    admin_api:
      ...
    receiver_api:
      ...
    clients:
      ...
  Preproduction:
    base_api:
      ...
    clients:
      ...

To use the stac CLI with a non-default instance, specify the instance name in the stac command:

stac --instance <instance_name> ...

Authentication

The stac CLI uses three StackState APIs: the Base API, the Admin API and the Receiver API. These APIs are secured differently and need to have separate authentication details provided in the stac CLI configuration file.

API key - Receiver API

StackState receives topology, telemetry and trace data via the Receiver API. If you want to push information to StackState using the stac CLI, you will need a Receiver API key. This is the same API key used by the StackState Agent and is available from your administrator.

API token - Base API and Admin API

Base API and Admin API authentication using username/password will be deprecated.

The stac CLI will issue a warning when username/password authentication is used for the Base API and the Admin API. It's recommended to switch to token based authentication as described below.

The stac CLI authenticates against the Base API and the Admin API using a unique API token auto-generated for your StackState user account. The same API token should be entered in the stac CLI configuration file for both the Base API and the Admin API.

  • The Base API is used for most operations. All users have access to this API, although the available operations will be restricted in accordance with the permissions assigned to each role.

  • The Admin API is used for some operations that affect the global configuration of StackState, such as the configuration of StackGraph's retention. Only users with the permission access-admin-api will have access to the Admin API and the associated operations.

You can find your API token in the StackState UI, go to Main menu > CLI.

Custom tool authentication

curl -H "Authorization: ApiToken <token>" <stackstate-api-endpoint>

Upgrade

Follow the steps below to upgrade an installed version of the CLI. Note that it isn't necessary to configure the CLI again after the upgraded version is installed, the existing CLI configuration will be used.

  1. Delete the existing CLI files:

    • Windows and Linux:

      • Version 4.6 and older: The file was downloaded as sts-cli-VERSION-linux64 and renamed to sts.

      • Version 5.0 and above: The file was downloaded as sts-cli-VERSION-linux64 and renamed to stac.

    • Docker:

      • The zip archive was downloaded as sts-cli-VERSION.zip and extracted. All files extracted from the zip archive should be removed.

  2. Follow the instructions to download and install the upgraded CLI:

  3. It isn't necessary to configure the CLI again, the existing CLI configuration will be used.

Uninstall

To uninstall an installed version of the stac CLI:

  1. Delete the old CLI files:

    • Linux or Windows:

      1. Version 4.6 and older: The file was downloaded as sts-cli-VERSION-linux64 and renamed to sts.

      2. Version 5.0 and above: The file was downloaded as sts-cli-VERSION-linux64 and renamed to stac.

    • Docker:

      • The zip archive was downloaded as sts-cli-VERSION.zip and extracted. All files extracted from the zip archive should be removed.

  2. Delete any stac CLI configuration files:

    • Linux or Windows:

      • conf.d/conf.yaml - relative to the directory where the CLI is run.

      • ~/.stackstate/cli/conf.yaml - relative to the user's home directory.

      • %APPDATA%/StackState/cli/conf.yaml - relative to the user's home directory.

    • Docker:

      • conf.d/conf.yaml - relative to the directory where the CLI would run. Should have been removed together with the old CLI files in step 1.

  3. If you added the CLI file or directory to your path (an optional installation step), remove it.

Use the stac CLI

For details on how to work with the StackState CLI, refer to the help provided in the CLI.

stac --help

License

The stac CLI can be used to check your license validity and update a license key when needed, for example, in case of expiration.

# check license key validity
stac subscription show
# Update license key
stac subscription update new-license-key

Note that it isn't necessary to do this using the CLI. StackState will also offer this option in the UI when a license is about to expire or has expired.

The steps below describe how to install the StackState CLI on Windows using the standalone executable file. If you prefer, you can run the stac CLI .

Download the executable sts-cli-VERSION-windows.exe from where the VERSION is the same as the StackState version you are running. For example, download sts-cli-5.0.0-windows.exe if you are running StackState v5.0.0.

(optional) Add the file to your PATH to use stac CLI commands from .

(recommended).

.

.

Download the ZIP file sts-cli-VERSION.zip from where the VERSION is the same as the StackState version you are running. For example, download sts-cli-5.0.0.zip if you are running StackState v5.0.0.

(optional) Add the bin directory to your PATH to use stac CLI commands from .

To configure the StackState CLI, .

Linux or Windows install (standalone executable): .

macOS (Docker): .

To configure the stac CLI, you will need your .

Follow the steps below to manually create or edit the stac CLI configuration file. A Docker install of the stac CLI must be manually configured. For a Linux or Windows install using a standalone executable file, you can also use the (preferred).

Download the ZIP file sts-cli-VERSION.zip from . If you ran the Docker install, you can skip this step and use the ZIP archive you already downloaded.

Any required authentication details for the APIs. The base_api API has support for . You can copy your private API Token from the CLI page in the StackState UI.

➡️

If you are using a custom tool instead of the CLI, you can authenticate with the same used by the CLI. For example, this can be done by including the following header in a curl request:

🚀
https://download.stackstate.com
anywhere on the command line
Docker installed (docker.com)
https://download.stackstate.com
anywhere on the command line
https://download.stackstate.com
Learn more about StackState permissions
inside a Docker container
Launch the configuration wizard
Manually add configuration
manually add configuration
Configuration wizard
Create the configuration file manually
authentication credentials
configuration wizard
API tokens
API token
Linux install
Windows install
Docker install (macOS, Linux, Windows)
Comparison between the CLIs
new sts CLI
https://download.stackstate.com
anywhere on the command line
Linux
Windows
inside a Docker container
inside a Docker container
Launch the configuration wizard
Manually add configuration
Which version of the sts CLI am I running?
Install the new sts CLI and upgrade the old sts CLI to stac