Agent configuration
The agent's config.json: what is in it, the two settings that are only configurable there, and what belongs in the dashboard instead.
Almost everything about an agent's behaviour is configured in the dashboard, not on the host: check-in cadence, preferred challenge type, standalone challenge ports, network stack, update channel and log retention all arrive in the heartbeat response. See Agents.
What lives on the host is config.json.
Where it is
| Platform | Path |
|---|---|
| Linux | /etc/aethercert-agent/agent/config.json |
| Windows | C:\ProgramData\aethercert\agent\config.json |
| CA connector | C:\ProgramData\aethercert\ca-connector\config.json |
--config <absolute path> on install or enroll puts it somewhere else. The path has
to be absolute; a relative one is rejected.
The file is written 0600 inside a 0700 directory, because it holds this host's bearer
secret. Do not commit it, copy it between hosts, or bake it into an image.
What is in it
{
"api_base": "https://api.aethercert.com",
"agent_id": "<agent-id>",
"secret": "<the host's bearer secret>",
"check_in_interval_seconds": 300
}| Key | Meaning |
|---|---|
api_base | The control plane this host talks to. Written at enrollment. |
agent_id | This host's identity. Written at enrollment. |
secret | This host's credential. Written at enrollment. Never log it, never copy it. |
check_in_interval_seconds | A fallback only - see below. |
check_in_interval_seconds is not the real cadence
It is the value --check-in-interval wrote at install time. The cadence the agent
actually uses is whatever the control plane returns on every heartbeat, derived from the
agent's own setting and its plan. The agent also checks in immediately on its first
cycle rather than waiting this out.
Change the cadence under Manage > Agents, not here.
The two settings that only exist here
Both tune the external certificate inventory
- the periodic scan that reports certificates already installed on this host. Neither has a dashboard equivalent; both are hand-edited.
{
"certificate_scan_paths": ["/opt/myapp/tls", "/srv/certs/server.pem"],
"disable_certificate_scan": false
}| Key | Effect |
|---|---|
certificate_scan_paths | Extra directories or individual files to include, on top of the platform defaults. For a host that keeps its certificates somewhere the defaults do not cover. |
disable_certificate_scan | true turns the inventory off for this host entirely. The scan reads public certificate material only and never opens a private key, but an operator who does not want their installed certificates catalogued can opt out. |
Restart the agent service after editing the file.
The scripts directory
A custom-script deploy target runs a script from a fixed directory beside the config. It is not configurable and never remotely settable.
| Platform | Path |
|---|---|
| Linux | /etc/aethercert-agent/agent/scripts/ |
| Windows | C:\ProgramData\aethercert\agent\scripts\ |
A script has to be a regular file in that directory, owned by root, not group- or
world-writable, and named .sh on Linux or .ps1 on Windows. The dashboard selects it by
bare filename - a path, a traversal or a symlink out of the directory is rejected.
The control-plane hostname
An agent enrolled before the control plane split across dedicated hostnames carries a
www.-style api_base. The agent rewrites that to the api. form once, silently, and
persists the change the first time it actually makes a call - so an already-deployed fleet
moves on its own without being re-enrolled.
Changing api_base by hand to point at a different control plane does not work: the
credentials belong to the control plane that issued them. Enroll again instead.
Repair and uninstall
Repairing a broken installation, replacing a quarantined binary, and removing the agent or the CA connector from a host.
Updates and release channels
How a host gets a new build: the Update Service, the three-step verification, release channels, staged rollout, pinning a version and rolling one back.