Rotate mTLS Certificates¶

The mTLS client certificate issued during service deploy or service register is valid for 90 days. After expiry, finchctl commands are rejected by the server. Rotating the certificate proactively - before it expires - keeps access uninterrupted.

This tutorial covers the normal proactive rotation scenario. If your finchctl machine is suspected to be compromised, rotate immediately following the same steps.

When to rotate¶

There is no built-in expiry warning. Set a calendar or CI reminder to rotate every 60–80 days to stay well within the 90-day validity window.

If you want to check the exact expiry of your current certificate, decode it from the local config:

cat ~/.config/finch.json \
  | jq -r '.stacks[] | select(.name == "finch.example.com") | .cert' \
  | base64 -d \
  | openssl x509 -noout -enddate

The output shows notAfter=<date> - the moment the current cert stops being accepted.

Step 1 - Rotate the certificate¶

Run service rotate-certificate with SSH access to the server host:

finchctl service rotate-certificate root@10.19.80.100

That is the only command needed.

What happens¶

1. A new ECDSA P-256 CA certificate and key are generated locally (on your finchctl machine).
2. A new client certificate and key are signed by the new CA, also locally.
3. The new CA certificate is uploaded to the server at via SSH, replacing the old CA certificate in-place. No service restart is required.
4. The new client certificate and key are stored in ~/.config/finch.json, overwriting the previous values.
5. The CA key is discarded locally immediately after signing (written to a temp file and deleted).

Step 2 - Verify connectivity¶

After rotation, confirm that the new certificate is accepted:

finchctl service info finch.example.com

A successful response confirms the new mTLS handshake works.

Agents are unaffected¶

mTLS certificates govern the finchctl → Finch control channel only. Agent authentication uses separate 365-day JWT. Rotating the mTLS certificate has no impact on enrolled agents, they continue reporting without interruption and require no action.

Summary¶