Containers and manual setups
Running the agent without registering an operating-system service - in a container, or under your own process supervisor.
When you do not want aethercert to register an operating-system service - inside a container, or under your own process supervisor - download the agent binary directly rather than the installer, and split enrollment from running.
# Enroll only: writes config, registers no service.
aethercert-agent enroll --api https://api.aethercert.com --token <token>
# Run in the foreground.
aethercert-agent runrun behaves the same way whether it was started by hand, by systemd, or by the Windows
Service Control Manager. It shuts down cleanly on SIGTERM and on Ctrl+C, which is what
makes it well-behaved as a container's main process.
Where the config goes
enroll writes config.json to the platform default -
/etc/aethercert-agent/agent/config.json on Linux - unless you pass --config with an
absolute path. In a container, point it at a mounted volume so the enrollment survives a
restart:
aethercert-agent enroll \
--api https://api.aethercert.com --token <token> \
--config /var/lib/aethercert/agent/config.json
aethercert-agent run --config /var/lib/aethercert/agent/config.jsonThe file holds this host's bearer secret and is written 0600 inside a 0700 directory.
Mount it accordingly, and do not bake it into an image - every container started from
that image would be the same agent.
Foreground mode gets no automatic updates
The agent never updates itself; a separate Update Service does, and it is not installed
by aethercert-agent enroll. A host running aethercert-agent run stays on whatever
build you put there. In a container that usually fits: rebuild the image on a new
version. See Updates.
What a containerised agent can and cannot do
The agent does the work on whatever machine it runs on, so a container's isolation is the constraint.
| Deploy target | In a container |
|---|---|
| Third-party APIs - NetScaler, F5, Kemp, FortiGate, PAN-OS, FMC, Sophos, WatchGuard, vCenter, Nutanix, Proxmox, Kubernetes | Works. These are plain HTTPS calls to a remote management endpoint. |
| Docker | Works, with the Docker socket mounted into the container. |
| Linux file targets - NGINX, Apache, HAProxy, Custom | Works only for paths inside the container, or a volume shared with whatever serves them. A reload command runs inside the container, not on the host. |
| Custom script (Linux) | Works, if the script is inside the container's scripts directory, owned by root and not group- or world-writable. |
| Every Windows target | Not applicable. |
A container is therefore a good home for an agent whose job is talking to appliances, and a poor one for an agent meant to install a certificate onto its own host.
Challenges from a container
DNS-01 needs nothing but outbound HTTPS, so it is the natural choice here.
HTTP-01 and TLS-ALPN-01 without a webroot make the agent bind port 80 or 443 for the duration of the challenge. In a container that means publishing the port and having the CA reach it - see Network requirements. If the published port differs from the local one, set the agent's standalone challenge ports under Manage > Agents > Edit.
Your own process supervisor
The same two commands work under runit, s6, an rc script or a hand-written systemd unit. Two things the aethercert-installed unit does that yours should too:
- Restart on failure. The agent exits non-zero on an unrecoverable startup error.
AmbientCapabilities=CAP_NET_BIND_SERVICE, if any certificate on this host uses HTTP-01 or TLS-ALPN-01 without a webroot, so the process can bind a low port without running as root.
If you would rather have the standard unit, run aethercert-installer install instead -
it writes one and registers the Update Service alongside.