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
  • Proxy for all Agent communication
  • Proxy for communication with StackState only
  • Environment variables
  • Agent configuration
  1. Setup
  2. StackState Agent

Use an HTTP/HTTPS proxy

StackState Self-hosted v5.1.x

PreviousAdvanced Agent configurationNextAgent V1 (legacy)

Last updated 1 year ago

Overview

The Agent can be configured to use a proxy for HTTP and HTTPS requests. Proxy settings can be configured in two ways:

  • . This includes Agent checks and communication with StackState. Configured with:

    • Environment variables HTTPS_PROXY / HTTP_PROXY

  • . Can be configured in 2 places:

    • Environment variables STS_PROXY_HTTPS / STS_PROXY_HTTP

    • Agent configuration file

Configured proxy settings will be used by the Agent in the following sequence:

  1. Environment variables STS_PROXY_HTTPS / STS_PROXY_HTTP

  2. Environment variables HTTPS_PROXY / HTTP_PROXY

  3. Proxy settings in the Agent configuration file.

For example, if the environment variable STS_PROXY_HTTPS="" is set and the Agent configuration file includes the proxy setting https: https://example.com:1234, the Agent will use the proxy "" for HTTPS requests to StackState.

Proxy for all Agent communication

Note that these settings will be overridden by the environment variables: STS_PROXY_HTTPS / STS_PROXY_HTTP. See .

To use a proxy for all Agent communication including checks and communication with StackState, set the following environment variables:

  • HTTP_PROXY - proxy to use for all HTTP communication.

  • HTTPS_PROXY - proxy to use for all HTTPS communication.

To configure a proxy for an Agent running on Linux, add the required environment variables to the StackState Agent systemd service.

Add environment variables to the StackState Agent systemd service:

  1. Stop the service:

    sudo systemctl stop stackstate-agent.service  
  2. Edit the service:

    sudo systemctl edit stackstate-agent.service
  3. Add the environment variables below to use a proxy for Agent checks and communication with StackState - note that this setting will be overridden by the environment variables STS_PROXY_HTTPS / STS_PROXY_HTTP if they're also set:

    [Service]
    Environment="HTTP_PROXY=http://example.com:1234"
    Environment="HTTPS_PROXY=https://example.com:1234"
  4. Restart the service:

    sudo systemctl start stackstate-agent.service

Remove environment variables from the StackState Agent systemd service:

  1. Stop the service:

    sudo systemctl stop stackstate-agent.service
  2. Delete the settings file:

    sudo rm /etc/systemd/system/stackstate-agent.service.d/override.conf 
  3. Restart the service:

    sudo systemctl daemon-reload
    sudo systemctl start stackstate-agent.service

To configure a proxy for an Agent running in a Docker container, use one of the commands below to pass the required environment variables when starting StackState Agent.

Single container

Run the command:

docker run -d \
 --name stackstate-agent \
 --privileged \
 --network="host" \
 --pid="host" \
 -v /var/run/docker.sock:/var/run/docker.sock:ro \
 -v /proc/:/host/proc/:ro \
 -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
 -e STS_API_KEY="<STACKSTATE_RECEIVER_API_KEY>>" \
 -e STS_STS_URL="<STACKSTATE_RECEIVER_API_ADDRESS>" \
 -e HOST_PROC="/host/proc" \
 -e HTTP_PROXY="http://example.com:1234" \
 -e HTTPS_PROXY="https://example.com:1234" \
 quay.io/stackstate/stackstate-agent:latest

Docker compose

  1. Add the following to the environment section of the compose file on each node where the Agent will run and should use a proxy:

    environment:
      HTTP_PROXY="http://example.com:1234"
      HTTPS_PROXY="https://example.com:1234"
  2. Run the command:

    docker-compose up -d

Docker Swarm

  1. Add the following to the environment section of the docker-compose.yml file used to deploy the Agent:

    environment:
      HTTP_PROXY="http://example.com:1234"
      HTTPS_PROXY="https://example.com:1234"\
  2. Run the command:

    docker stack deploy -c docker-compose.yml

To configure a proxy for an Agent running on Windows, add the required environment variables to the StackState Agent systemd service.

  1. Stop the Agent.

    # CMD
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    
    # PowerShell
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
  2. Add the environment variables

    setx HTTP_PROXY http://example.com:1234
    setx HTTPS_PROXY https://example.com:1234
  3. Start the Agent.

    # CMD
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    
    # PowerShell
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service

Proxy for communication with StackState only

A proxy can be configured to be used only for communication between StackState Agent V3 and StackState. This can be set up either by using environment variables or by updating the Agent configuration file.

Environment variables

Note that these settings will override all other proxy settings either in environment variables or the Agent configuration file.

To use a proxy for communication with StackState only, set the following environment variables:

  • STS_PROXY_HTTPS - proxy to use for HTTP communication with StackState.

  • STS_PROXY_HTTP - proxy to use for HTTPS communication with StackState.

To configure a proxy for an Agent running on Linux, add the required environment variables to the StackState Agent systemd service.

Add environment variables to the StackState Agent systemd service:

  1. Stop the service:

    sudo systemctl stop stackstate-agent.service  
  2. Edit the service:

    sudo systemctl edit stackstate-agent.service
  3. Add the environment variables below to use a proxy for communication with StackState only:

    [Service]
    Environment="STS_PROXY_HTTP=http://example.com:1234"
    Environment="STS_PROXY_HTTPS=https://example.com:1234"
  4. Restart the service:

    sudo systemctl start stackstate-agent.service

Remove environment variables from the StackState Agent systemd service:

  1. Stop the service:

    sudo systemctl stop stackstate-agent.service
  2. Delete the settings file:

    sudo rm /etc/systemd/system/stackstate-agent.service.d/override.conf 
  3. Restart the service:

    sudo systemctl daemon-reload
    sudo systemctl start stackstate-agent.service

To configure a proxy for an Agent running in a Docker container, use one of the commands below to pass the required environment variables when starting StackState Agent.

Single container

Run the command:

docker run -d \
 --name stackstate-agent \
 --privileged \
 --network="host" \
 --pid="host" \
 -v /var/run/docker.sock:/var/run/docker.sock:ro \
 -v /proc/:/host/proc/:ro \
 -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
 -e STS_API_KEY="<STACKSTATE_RECEIVER_API_KEY>" \
 -e STS_STS_URL="<STACKSTATE_RECEIVER_API_ADDRESS>" \
 -e HOST_PROC="/host/proc" \
 -e STS_PROXY_HTTP="http://example.com:1234" \
 -e STS_PROXY_HTTPS="https://example.com:1234" \
 quay.io/stackstate/stackstate-agent:latest

Docker compose

  1. Add the following to the environment section of the compose file on each node where the Agent will run and should use a proxy:

    environment:
      STS_PROXY_HTTP="http://example.com:1234"
      STS_PROXY_HTTPS="https://example.com:1234"
  2. Run the command:

    docker-compose up -d

Docker Swarm

  1. Add the following to the environment section of the docker-compose.yml file used to deploy the Agent:

    environment:
      STS_PROXY_HTTP="http://example.com:1234"
      STS_PROXY_HTTPS="https://example.com:1234"
  2. Run the command:

    docker stack deploy -c docker-compose.yml

To configure a proxy for an Agent running on Windows, add the required environment variables to the StackState Agent systemd service.

  1. Stop the Agent.

    # CMD
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    
    # PowerShell
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
  2. Add the environment variables

    setx STS_PROXY_HTTP http://example.com:1234
    setx STS_PROXY_HTTPS https://example.com:1234
  3. Start the Agent.

    # CMD
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    
    # PowerShell
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service

Agent configuration

Note that proxy settings configured using an environment variable will override any proxy setting in the Agent configuration file.

To use a proxy for communication with StackState add the following items to the Agent configuration file:

  • proxy.http - proxy to use for HTTP communication with StackState.

  • proxy.https - proxy to use for HTTPS communication with StackState.

To update the configuration file for an Agent running on Linux:

  1. Edit the Agent configuration file:

    sudo vi /etc/stackstate-agent/stackstate.yaml
  2. Uncomment the proxy settings:

    proxy:
      https: https://example.com:1234
      http: http://example.com:1234
  3. Restart the Agent.

    sudo systemctl start stackstate-agent.service

To update the configuration file for an Agent running in a Docker container:

  1. Set the proxy details in /etc/stackstate-agent/stackstate.yaml:

    proxy:
      https: https://example.com:1234
      http: http://example.com:1234

To update the configuration file for an Agent running on Windows:

  1. Edit the Agent configuration file:

    C:\ProgramData\StackState\stackstate.yaml
  2. Uncomment the proxy settings:

    proxy:
      https: https://example.com:1234
      http: http://example.com:1234
  3. Restart the Agent.

    # CMD
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" restart-service
    
    # PowerShell
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" restart-service

You can also .

You can also .

A proxy set in the Agent configuration file will be used for communication with StackState only. Checks configured on the Agent won't use this proxy for communication with external systems. To use a proxy for Agent checks and communication with StackState, see how to use a .

Mount the config files as a volume into the container running the Agent as described in .

🚀
Proxy for all Agent communication
Proxy for communication with StackState only
proxy for communication with StackState only
use a proxy only for communication with StackState
use a proxy for all Agent communication
proxy for all Agent communication
Docker Agent integration configuration