Prerequisites

Agent (cea) — Debian/Ubuntu: libio-socket-ssl-perl libjson-perl · Alpine: perl-io-socket-ssl perl-json

ctrl-exec (ced) — Debian/Ubuntu: libwww-perl libio-socket-ssl-perl libjson-perl · Alpine: perl-libwww perl-io-socket-ssl perl-json

All roles require openssl and perl. The installer checks all dependencies before making any changes.

Install

sudo ./install.sh --agent        # on each remote host
sudo ./install.sh --ctrl-exec    # on the control host
sudo ./install.sh --api          # on the control host (optional API server)

Run as root. Detects Debian/Ubuntu or Alpine automatically. Add yourself to the ctrl-exec group for CLI access without sudo:

sudo usermod -aG ctrl-exec $USER

First-Time Setup

On the ctrl-exec host — initialise the CA (once only) and generate the ctrl-exec certificate:

sudo ctrl-exec setup-ca
sudo ctrl-exec setup-ctrl-exec

Back up /etc/ctrl-exec/ca.key to encrypted offline storage immediately. This is the root of trust for the entire deployment.

On each agent host — edit /etc/ctrl-exec-agent/agent.conf and /etc/ctrl-exec-agent/scripts.conf, then start the agent:

sudo systemctl enable ctrl-exec-agent
sudo systemctl start ctrl-exec-agent

Pairing

On the ctrl-exec host:

sudo ctrl-exec pairing-mode

On the agent host:

sudo ctrl-exec-agent request-pairing --dispatcher <ctrl-exec-hostname>

A prompt appears in the pairing mode terminal showing the agent's hostname, source IP, and a 6-digit verification code. Verify the code matches what the agent displayed, then type a to approve. The agent stores its signed certificate and exits.

Confirm the agent is registered and reachable:

ctrl-exec list-agents
ctrl-exec ping <agent-hostname>

Docker

Agent containers pair on first start and serve on subsequent starts, with all state on named volumes. Set CTRL_EXEC_HOST in the agent container environment to point at the ctrl-exec service.

agent:
  environment:
    CTRL_EXEC_HOST: ctrl-exec
  volumes:
    - agent-data:/etc/ctrl-exec-agent

Reference Documentation

Full installation guide — configuration, auth hooks, adding scripts, troubleshooting, uninstall: INSTALL