Launch and management

Validating the configuration

Before running in production, always validate the configuration. A trial run with automatic exit is recommended:

stronghold agent -config=/etc/stronghold-agent/agent.hcl -exit-after-auth -log-level=debug

This command:

Checks the HCL configuration syntax.
Connects to the Stronghold server.
Performs full authentication.
Creates files and renders templates.
Exits automatically (no need for Ctrl+C).

Successful result:

[INFO]  agent: loaded config: path=/etc/stronghold-agent/agent.hcl
[INFO]  agent.auto_auth.approle: authentication successful
[INFO]  agent.sink.file: writing token to: /var/run/stronghold-agent/token
[INFO]  agent: exit after auth set, exiting

Running in development mode

For debugging, you can run Agent in the foreground:

# Basic run.
stronghold agent -config=/etc/stronghold-agent/agent.hcl

# With a more verbose log level.
stronghold agent -config=/etc/stronghold-agent/agent.hcl -log-level=debug

# Exit after the first successful authentication (for testing).
stronghold agent -config=/etc/stronghold-agent/agent.hcl -exit-after-auth

Running Agent as a systemd service

Create the systemd unit file /etc/systemd/system/stronghold-agent.service:

[Unit]
Description=Stronghold Agent
Documentation=https://docs.stronghold.example.com/agent
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/stronghold-agent/agent.hcl

[Service]
Type=notify
User=stronghold-agent
Group=stronghold-agent
ExecStart=/usr/local/bin/stronghold agent -config=/etc/stronghold-agent/agent.hcl
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
KillSignal=SIGTERM
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
# Add all directories Agent writes to: template.destination, the sink file, the unix socket and logs.
# Agent deletes the Secret ID file from /etc/stronghold-agent if remove_secret_id_file_after_reading is enabled.
# Extend the list for your configuration, for example, with /var/lib/myapp.
ReadWritePaths=/etc/stronghold-agent /var/run/stronghold-agent /var/log/stronghold-agent /etc/myapp
CapabilityBoundingSet=CAP_IPC_LOCK

[Install]
WantedBy=multi-user.target

The stronghold-agent user must own the /etc/stronghold-agent directory. Otherwise, Agent cannot delete the Secret ID file after reading it.

With NoNewPrivileges=true, the template command cannot use sudo. To allow Agent to reload a service, add a polkit rule as shown in the Application on a virtual machine with Stronghold Agent example.

Managing the service:

# Reload systemd.
sudo systemctl daemon-reload

# Start Agent.
sudo systemctl start stronghold-agent

# Enable autostart.
sudo systemctl enable stronghold-agent

# Check the status.
sudo systemctl status stronghold-agent

# View logs.
sudo journalctl -u stronghold-agent -f

# Reload the configuration (SIGHUP).
sudo systemctl reload stronghold-agent

# Stop.
sudo systemctl stop stronghold-agent

Launch and management