6.11 Agent Locking
Keep working deployment settings protected while renewals continue.
Locking an agent prevents CertKit from adding, changing, or removing its deployment configurations. Certificate renewals and deployments continue using the settings already on the host. To change those settings, someone with administrator access must unlock the agent on that host.
Why lock an agent?
Use locking once a production agent is configured and deploying certificates successfully. It helps prevent an accidental edit from changing a working setup and makes host access a requirement for future deployment changes.
It also protects the commands your agent runs. Deployment scripts can reload services or push certificates to other devices, using the agent’s permissions. Locking prevents someone with access to your CertKit account, or to a compromised CertKit application, from replacing those scripts through a configuration update.
Keep the agent unlocked during initial setup. Once you have verified the certificate destinations, scripts, and any maintenance windows, lock it. You can unlock it again when a planned change is needed.
What changes when an agent is locked?
The lock applies to all deployment configurations on that agent.
| Action | While locked |
|---|---|
| Renew and deploy certificates for existing configurations | Continues, using the existing settings and deploy windows. |
| Run existing post-deployment scripts | Continues when certificates are deployed. |
| Add, edit, or remove deployment configurations through CertKit | Blocked. |
| Change certificate destinations, scripts, or deploy windows through CertKit | Blocked. |
| Receive agent software updates and monitor hosts | Continues. |
The lock protects deployment configurations. Other settings, including Keystore settings, private CA trust settings, and values supplied to deployment scripts, can still update.
The agent enforces the lock using a file beside its configuration file. The lock stays in place across service restarts until someone removes it on the host.
Lock an agent
- Confirm the agent has received your latest configuration and deployed successfully.
- In CertKit, open Agents, select the agent, and use the lock action on its detail page.
- Wait for the agent to check in and confirm that CertKit shows it as locked.
You can also lock it from the host using the commands below with lock in place of unlock.
Unlock an agent
You cannot unlock an agent from the CertKit dashboard. Connect to the machine running the agent, for example through Remote Desktop or SSH, and run the appropriate command below.
Windows
Open PowerShell as Administrator on the agent host and run:
& "C:\Program Files\CertKit\bin\certkit-agent.exe" unlock
Linux
Run on the agent host with sudo:
sudo /usr/local/bin/certkit-agent unlock
These commands use the default installation paths. If your agent uses a different location, adjust the executable path and pass the running agent’s configuration file with --config.
Remove the lock file instead
The unlock command removes a file named config.json.lock. You can also delete that file directly with administrator or root permissions. The default locations are:
- Windows:
C:\ProgramData\CertKit\certkit-agent\config.json.lock - Linux:
/etc/certkit-agent/config.json.lock
For a custom configuration path, the lock file is that full path with .lock appended. Delete only the lock file; keep config.json in place.
After unlocking
No service restart is required. Wait for the running agent to check in, then refresh its page in CertKit and confirm the locked status has cleared. It can now accept deployment configuration changes again.
Make your changes, confirm the agent has received them and deployed successfully, then lock it again. If CertKit still shows the agent as locked, check that the agent is online and that you used the configuration path for that running agent. See Agent Troubleshooting for log locations.