Container Agent | Keyfactor Docs

The Signum Container Agent is a container-based version of the Linux Agent. The Container Agent starts and runs the Agent service and provides a base image that can be added to as needed for configuring various additional signing applications.

For access to the Container Agent, contact Keyfactor support.

For instructions and examples, see https://github.com/Keyfactor/signum-container-agent.

Operational Information

The Container Agent runs as a dedicated non-root user 10001. Any files mounted into the container must be readable and accessible by this user.

During startup, the container bootstrap script (/usr/local/keyfactor/bin/start.sh) reads configuration values from environment variables and configures the appropriate credentials and permissions for the dedicated runtime user 10001.

Do not run the Container Agent as root or as any user other than 10001. Doing so will prevent the agent from accessing its configuration correctly.

Agent Version

When pulling the image from the registry, ensure the tag value matches your server version.

Available tag values:

latest (4.70.1)
4.60.3
4.40.1

For the supported Container Agent for your server version, see Supported Versions.

Run the Signum Container Agent Base Image

Use the following command to run the agent, providing values for the environment variables:

docker run --name signum-agent \
  -e "SIGNUM_HOSTNAME=A URL" \
  -e "SIGNUM_USERNAME=myuser@somedomain" \
  -e "SIGNUM_PASSWORD=$mycreds" \
  -e "SIGNUM_LOGLEVEL=HIGH" \
  -e "SIGNUM_LOGTYPE=FILE" \
  repo.keyfactor.com/images/signum-agent:4.80.1

docker exec -it signum-agent /bin/bash

Use the following command to list certificates:

signum-util lc

Subject CN     : Signum-RSA-3072
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 170570A1D56FBB5A4CC780B69ACAEF94010D5DAA
Subject CN     : Signum-RSA-4096
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2029-04-23
    Valid From     : 2024-04-24
    Thumbprint     : 3AB5BFB91DFBB46CF765D5BEE51429618C4857DD
Subject CN     : Signum-RSA-2048
    Issuer CN      : DemoRoot-G2
    Valid Until    : 2030-02-05
    Valid From     : 2025-02-06
    Thumbprint     : F78AE7871FEF1D0CF3EFFB58E9CC85F261438D2B

Environment Variable Reference

Variable	Required	Description
`SIGNUM_HOSTNAME`	Yes	URL of the Signum server (such as `https://signum.example.com`)
`SIGNUM_USERNAME`	Yes*	Username for authenticating to the Signum server.
`SIGNUM_PASSWORD`	Yes*	Password for authenticating to the Signum server, if using certificate authentication it's the password of the .p12 file.
`SIGNUM_LOGLEVEL`	No	Controls log verbosity. Valid values: `LOW`, `MEDIUM`, `HIGH`. `HIGH` produces the most output and should be only used for troubleshooting.
`SIGNUM_LOGTYPE`	No	Controls log destination. Valid values: `FILE` (writes to a log file inside the container), `STDOUT` (writes to stdout).
`SIGNUM_AGENTID`	No	Allows the pre-define the agentID that will be reported to the server. The default value is `AAAAA-BBBBB-CCCCC-DDDDD`. The provided AgentID must have the same format.
`SIGNUM_HTTPS_PROXY`	No	The proxy to be used for connecting to the Signum instance. Set up an HTTP proxy to be used by Signum. This configuration overrides the system configuration (usually /etc/systemd/system.conf). If not specified, blank or unable to connect to the Signum instance through it, the agent will fall back to the system configuration, usually /etc/systemd/system.conf.
`SIGNUM_CERTIFICATE_PATH`	No*	The absolute certificate path inside the Container Agent used to connect to the Signum instance, must be a .p12 file.
`SIGNUM_WAF_PORT`	No*	Provide the WAF port configured in the Administration Console. Required only when using certificate-based login behind a WAF.

*_{If using certificate or user-password authentication, you need to provide SIGNUM_CERTIFICATE_PATH and SIGNUM_PASSWORD.}

Authenticate with User and Password

To authenticate with username and password, you need the Signum Server URL which can be found in the Signum Links at Keyfactor Customer Portal. Provide the URL in the SIGNUM_HOSTNAME value.

docker run --name signum-agent -d \
  -e "SIGNUM_HOSTNAME=A URL" \
  -e "SIGNUM_USERNAME=myuser@somedomain" \
  -e "SIGNUM_PASSWORD=$mycreds" \
  -e "SIGNUM_LOGLEVEL=HIGH" \
  -e "SIGNUM_LOGTYPE=FILE" \
  repo.keyfactor.com/images/signum-agent:4.80.1

Authenticate with Certificate

To authenticate with a certificate, you need the Signum Server URL which can be found in the Signum Links at Keyfactor Customer Portal. Provide the URL in the SIGNUM_HOSTNAME value. You also need a .p12 file of the certificate used for login, located in a folder accessible with permissions from the terminal, such as /tmp.

docker run --name signum-agent -d \
  -v $PWD/loginCertificate.p12:/mnt/loginCertificate.p12 \
  -e "SIGNUM_HOSTNAME=A URL" \
  -e "SIGNUM_CERTIFICATE_PATH=/mnt/loginCertificate.p12" \
  -e "SIGNUM_PASSWORD=$myCertificatePassword" \
  -e "SIGNUM_LOGLEVEL=HIGH" \
  -e "SIGNUM_LOGTYPE=FILE" \
  -e "SIGNUM_WAF_PORT=$myWafPort" \
  repo.keyfactor.com/images/signum-agent:4.80.1

For more information about logging in with certificates, see Use Certificate-based Authentication.