Use an HTTP/HTTPS proxy
StackState Self-hosted v5.0.x

Overview

The Agent can be configured to use a proxy for HTTP and HTTPS requests. Proxy settings can be configured in two ways:
Configured proxy settings will be used by the Agent in the following sequence:
  1. 1.
    Environment variables STS_PROXY_HTTPS / STS_PROXY_HTTP
  2. 2.
    Environment variables HTTPS_PROXY / HTTP_PROXY
  3. 3.
    Proxy settings in the Agent configuration file.
For example, if the environment variable STS_PROXY_HTTPS="" is set and the Agent configuration file contains 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 proxy for communication with StackState only.
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.
Linux
Docker
Windows
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. 1.
    Stop the service:
    1
    sudo systemctl stop stackstate-agent.service
    Copied!
  2. 2.
    Edit the service:
    1
    sudo systemctl edit stackstate-agent.service
    Copied!
  3. 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 are also set:
    1
    [Service]
    2
    Environment="HTTP_PROXY=http://example.com:1234"
    3
    Environment="HTTPS_PROXY=https://example.com:1234"
    Copied!
  4. 4.
    Restart the service:
    1
    sudo systemctl start stackstate-agent.service
    Copied!
Remove environment variables from the StackState Agent systemd service:
  1. 1.
    Stop the service:
    1
    sudo systemctl stop stackstate-agent.service
    Copied!
  2. 2.
    Delete the settings file:
    1
    sudo rm /etc/systemd/system/stackstate-agent.service.d/override.conf
    Copied!
  3. 3.
    Restart the service:
    1
    sudo systemctl daemon-reload
    2
    sudo systemctl start stackstate-agent.service
    Copied!
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:
1
docker run -d \
2
--name stackstate-agent \
3
--privileged \
4
--network="host" \
5
--pid="host" \
6
-v /var/run/docker.sock:/var/run/docker.sock:ro \
7
-v /proc/:/host/proc/:ro \
8
-v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
9
-e STS_API_KEY="<STACKSTATE_RECEIVER_API_KEY>>" \
10
-e STS_STS_URL="<STACKSTATE_RECEIVER_API_ADDRESS>" \
11
-e HOST_PROC="/host/proc" \
12
-e HTTP_PROXY="http://example.com:1234" \
13
-e HTTPS_PROXY="https://example.com:1234" \
14
docker.io/stackstate/stackstate-agent-2:latest
Copied!
Docker compose
  1. 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:
    1
    environment:
    2
    HTTP_PROXY="http://example.com:1234"
    3
    HTTPS_PROXY="https://example.com:1234"
    Copied!
  2. 2.
    Run the command:
    1
    docker-compose up -d
    Copied!
Docker Swarm
  1. 1.
    Add the following to the environment section of the docker-compose.yml file used to deploy the Agent:
    1
    environment:
    2
    HTTP_PROXY="http://example.com:1234"
    3
    HTTPS_PROXY="https://example.com:1234"\
    Copied!
  2. 2.
    Run the command:
    1
    docker stack deploy -c docker-compose.yml
    Copied!
To configure a proxy for an Agent running on Windows, add the required environment variables to the StackState Agent systemd service.
  1. 1.
    Stop the Agent.
    1
    # CMD
    2
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    3
    ​
    4
    # PowerShell
    5
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    Copied!
  2. 2.
    Add the environment variables
    1
    setx HTTP_PROXY http://example.com:1234
    2
    setx HTTPS_PROXY https://example.com:1234
    Copied!
  3. 3.
    Start the Agent.
    1
    # CMD
    2
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    3
    ​
    4
    # PowerShell
    5
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    Copied!

Proxy for communication with StackState only

A proxy can be configured to be used only for communication between the StackState Agent 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.
Linux
Docker
Windows
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. 1.
    Stop the service:
    1
    sudo systemctl stop stackstate-agent.service
    Copied!
  2. 2.
    Edit the service:
    1
    sudo systemctl edit stackstate-agent.service
    Copied!
  3. 3.
    Add the environment variables below to use a proxy for communication with StackState only:
    1
    [Service]
    2
    Environment="STS_PROXY_HTTP=http://example.com:1234"
    3
    Environment="STS_PROXY_HTTPS=https://example.com:1234"
    Copied!
  4. 4.
    Restart the service:
    1
    sudo systemctl start stackstate-agent.service
    Copied!
Remove environment variables from the StackState Agent systemd service:
  1. 1.
    Stop the service:
    1
    sudo systemctl stop stackstate-agent.service
    Copied!
  2. 2.
    Delete the settings file:
    1
    sudo rm /etc/systemd/system/stackstate-agent.service.d/override.conf
    Copied!
  3. 3.
    Restart the service:
    1
    sudo systemctl daemon-reload
    2
    sudo systemctl start stackstate-agent.service
    Copied!
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:
1
docker run -d \
2
--name stackstate-agent \
3
--privileged \
4
--network="host" \
5
--pid="host" \
6
-v /var/run/docker.sock:/var/run/docker.sock:ro \
7
-v /proc/:/host/proc/:ro \
8
-v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
9
-e STS_API_KEY="<STACKSTATE_RECEIVER_API_KEY>" \
10
-e STS_STS_URL="<STACKSTATE_RECEIVER_API_ADDRESS>" \
11
-e HOST_PROC="/host/proc" \
12
-e STS_PROXY_HTTP="http://example.com:1234" \
13
-e STS_PROXY_HTTPS="https://example.com:1234" \
14
docker.io/stackstate/stackstate-agent-2:latest
Copied!
Docker compose
  1. 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:
    1
    environment:
    2
    STS_PROXY_HTTP="http://example.com:1234"
    3
    STS_PROXY_HTTPS="https://example.com:1234"
    Copied!
  2. 2.
    Run the command:
    1
    docker-compose up -d
    Copied!
Docker Swarm
  1. 1.
    Add the following to the environment section of the docker-compose.yml file used to deploy the Agent:
    1
    environment:
    2
    STS_PROXY_HTTP="http://example.com:1234"
    3
    STS_PROXY_HTTPS="https://example.com:1234"
    Copied!
  2. 2.
    Run the command:
    1
    docker stack deploy -c docker-compose.yml
    Copied!
To configure a proxy for an Agent running on Windows, add the required environment variables to the StackState Agent systemd service.
  1. 1.
    Stop the Agent.
    1
    # CMD
    2
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    3
    ​
    4
    # PowerShell
    5
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" stopservice
    Copied!
  2. 2.
    Add the environment variables
    1
    setx STS_PROXY_HTTP http://example.com:1234
    2
    setx STS_PROXY_HTTPS https://example.com:1234
    Copied!
  3. 3.
    Start the Agent.
    1
    # CMD
    2
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    3
    ​
    4
    # PowerShell
    5
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" start-service
    Copied!

Agent configuration

Note that proxy settings configured using an environment variable will override any proxy setting in the Agent configuration file.
A proxy set in the Agent configuration file will be used for communication with StackState only. Checks configured on the Agent will not use this proxy for communication with external systems. To use a proxy for Agent checks and communication with StackState, see how to use a proxy for all Agent communication.
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.
Linux
Docker
Windows
To update the configuration file for an Agent running on Linux:
  1. 1.
    Edit the Agent configuration file:
    1
    sudo vi /etc/stackstate-agent/stackstate.yaml
    Copied!
  2. 2.
    Uncomment the proxy settings:
    1
    proxy:
    2
    https: https://example.com:1234
    3
    http: http://example.com:1234
    Copied!
  3. 3.
    Restart the Agent.
    1
    sudo systemctl start stackstate-agent.service
    Copied!
To update the configuration file for an Agent running in a Docker container:
  1. 1.
    Set the proxy details in /etc/stackstate-agent/stackstate.yaml:
    1
    proxy:
    2
    https: https://example.com:1234
    3
    http: http://example.com:1234
    Copied!
  2. 2.
    Mount the config files as a volume into the container running the Agent as described in Docker Agent integration configuration.
To update the configuration file for an Agent running on Windows:
  1. 1.
    Edit the Agent configuration file:
    1
    C:\ProgramData\StackState\stackstate.yaml
    Copied!
  2. 2.
    Uncomment the proxy settings:
    1
    proxy:
    2
    https: https://example.com:1234
    3
    http: http://example.com:1234
    Copied!
  3. 3.
    Restart the Agent.
    1
    # CMD
    2
    "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" restart-service
    3
    ​
    4
    # PowerShell
    5
    & "C:\Program Files\StackState\StackState Agent\embedded\agent.exe" restart-service
    Copied!