Set up a security backend for Linux
StackState Self-hosted v5.1.x
Last updated
StackState Self-hosted v5.1.x
Last updated
This document explains the process of setting up a security backend on a Linux system. You can find more information in the .
StackState Agent V2 runs the secret_backend_command
executable as a sub-process. On Linux, the executable set as secret_backend_command
must:
Belong to the same user running the Agent (or root
inside a container).
Have no rights for group or other.
Have at least exec rights for the owner.
The executable respects a simple API that reads JSON structures from the standard input, and outputs JSON containing the decrypted secrets to the standard output. If the exit code is anything other than 0, then the integration configuration being decrypted is considered faulty and is dropped.
The executable receives a JSON payload from the standard input, containing the list of secrets to fetch:
version
: is a string containing the format version.
secrets
: is a list of strings; each string is a handle from a configuration file corresponding to a secret to fetch.
The executable is expected to output to the standard output a JSON payload containing the:
The expected payload is a JSON object, where each key is one of the handles requested in the input payload. The value for each handle is a JSON object with two fields:
value
: a string; the actual value used in the check configurations
error
: a string; the error message, if needed. If error is anything other than null, the integration configuration that uses this handle is considered erroneous and is dropped.
The following is a dummy implementation of the secret reader that's prefixing every secret with decrypted_
:
Above example updates the following configuration (from the check file):
into this in the Agent's memory:
The secret
command in the Agent CLI shows any errors related to your setup. For example, if the rights on the executable are incorrect. It also lists all handles found, and where they're located.
On Linux, the command outputs file mode, owner and group for the executable. Example:
To quickly see how the check’s configurations are resolved, you can use the configcheck
command:
Note: The Agent needs to be restarted to pick up changes on configuration files.
secret_backend_command
To test or debug outside of the Agent, you can mimic how the Agent runs it:
The stackstate-agent user is created when you install StackState Agent V2.