How to change Certificate on a Custom Deployment Script

A custom script is appropriate when a product has no native aethercert target. The script is the deployment procedure: it must validate material, place it safely, update bindings, activate the service, verify the result, and be safe to run again.

Before you begin

Place a reviewed script on the target host. Define its input contract without passing private keys in command-line arguments. Use protected files or environment variables, restrict script modification to administrators, and record the exact rollback state.

Step-by-step certificate replacement

1. Fail early on missing input, invalid certificate dates/SANs, a key mismatch, or an incomplete chain.
2. Write to a protected temporary/versioned location and use an atomic rename where the target supports it. Preserve Windows key ACLs or Unix owner/mode/labels.
3. Back up the previous binding/object identifier, not only the certificate file.
4. Run the product's configuration validator and stop on any nonzero exit code.
5. Activate with the narrowest supported reload/restart and wait for health.
6. Verify both local configuration and the network certificate. Return a nonzero exit code when either fails.
7. Make every step idempotent: running the same script with the same material should converge, not create duplicate objects or progressively alter permissions.

Product-specific considerations

On Linux, avoid interpolating untrusted values into a shell string. On Windows, avoid embedding PFX passwords in PowerShell source or process arguments. Bound execution time, capture useful non-secret diagnostics, and serialize changes when two renewals could target the same service.

Verify the new certificate

The script should compare the deployed fingerprint to the input certificate and query the real endpoint with SNI/protocol-specific TLS. A zero exit code should mean the replacement is active, not merely copied.

Rollback

Provide a reviewed rollback mode or separate script that restores files, objects, bindings, permissions, and the service state. Test it before the first production run.

Common problems

• Secrets appear in arguments, stdout, or logs.
• A copy succeeds but activation or network verification is omitted.
• Repeated runs create duplicate certificate objects.
• The script catches an error and still returns success.
• Rollback restores files but not the binding.

Automating certificate replacement with aethercert

The aethercert custom-script targets run an administrator-provided script that already exists in the agent's protected scripts directory and pass configured values as AC_VAR_<NAME> environment variables. aethercert does not upload script content. The script receives your variables and nothing else: aethercert writes no certificate, chain or key for a custom-script target, and passes no paths to the script. If the hook needs the material, give the certificate a second deploy target that writes the files.

See Deploy targets for the fields this preset takes, the permission gate a script has to pass, and what reaches its environment.