Re-enroll an Agent¶
Re-enrolling means pushing a new Alloy configuration, containing a fresh JWT, to an agent host and restarting the collector. This is required after:
- Rotating the signing secret - all existing tokens are invalidated simultaneously.
- Recovering an agent breach - a single agent is deregistered and re-registered with a new RID.
- Token expiry - an agent's 365-day token has expired and the agent has stopped reporting.
Step 1 - Get a fresh configuration¶
How you generate the new config file depends on whether the agent record still exists in the database.
Agent record exists (secret rotation, token expiry):¶
finchctl agent config \
--agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
--agent.config web-01-new.cfg \
finch.example.com
agent config always issues a new 365-day token. The agent registration
(hostname, log sources, labels) is unchanged.
Agent was deregistered (breach recovery, re-registration):¶
finchctl agent register \
--agent.hostname web-01 \
--agent.logs.journal \
--agent.logs.docker \
--agent.metrics \
--agent.config web-01-new.cfg \
finch.example.com
Use the same flags as the original registration to keep Grafana dashboards and alert rules intact. A new RID is generated automatically.
Alternatively, export the old configuration to a YAML file and pass it directly:
finchctl agent describe \
--agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
--output.json \
finch.example.com \
| yq --input-format json --output-format yaml > agent.yaml
finchctl agent register \
--agent.file agent.yaml \
--agent.config web-01-new.cfg \
finch.example.com
Any rid field in the file is ignored, a new resource ID is always generated.
Step 2 - Deploy to the host¶
Push the new config to the agent host. Alloy is restarted and reconnects with the fresh token, then flushes any data buffered in its WAL during the outage.
agent deploy is supported on Linux, FreeBSD, and macOS.
Windows agents¶
agent deploy is not supported on Windows. Push the configuration manually:
Download the new config file:
finchctl agent config \
--agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
--agent.config web-01-new.cfg \
finch.example.com
Copy web-01-new.cfg to the agent host as
C:\Program Files\Alloy\alloy.config and restart the Alloy service: