External ACME Clients

An external ACME client can request and renew certificates when the integrated certificate request does not match your network or DNS setup. The client writes the certificate and private key to files, and the server uses these files as a custom certificate.

Common clients include acme.sh and Certbot. Choose a client that supports your DNS provider and the required ACME challenge.

The following workflow applies to most clients:

1. Select a public DNS name and the certificate authority.
2. Configure the DNS provider module or a delegated challenge zone.
3. Request the certificate with DNS-01.
4. Install the certificate, full chain and private key into dedicated files.
5. Configure the server to use these files as a custom certificate.
6. Enable the client's scheduled renewal.
7. Verify that renewed files are written atomically and that the changed files are loaded by the server.

Use the client documentation for installation, credentials and service scheduling. This documentation does not contain provider-specific API credentials.

The following example is provider-neutral. Replace the DNS module, domain and file paths with values for your environment:

# Issue a certificate through a DNS provider module
acme.sh --issue --dns dns_provider_module -d app.example.com --server letsencrypt
 
# Install the renewed files into the paths used by the server
acme.sh --install-cert -d app.example.com \
  --key-file /path/to/server.key \
  --fullchain-file /path/to/server-fullchain.pem

The provider module name and required environment variables are different for every DNS provider. Use the acme.sh DNS API list and the provider documentation to select them.

For an experimental DNS-PERSIST-01 staging workflow, use only an ACME client version and staging directory that explicitly document this challenge. Do not replace –server letsencrypt with a guessed staging option.

Select the custom certificate source in the Web Server configuration and provide the certificate and key files installed by the ACME client.

The certificate file must contain the required intermediate certificates. The private key must be readable by the server process and must not be protected with a password if the server cannot request one during startup.

Store certificate files outside a public web directory. Restrict file permissions so that only the ACME client and the server process can read the private key.

The external ACME client owns the renewal schedule. Test the renewal command before the first expiry window and monitor its log or service status.

When a certificate file changes, the Automatic update of custom SSL Certificates task can load the changed certificate without a full server restart. Keep the certificate and key paths stable so the file-change trigger continues to work.

• A manual DNS challenge does not provide unattended renewal.
• A DNS API token is a dependency that must be renewed or revoked separately.
• A certificate can be issued successfully while the internal DNS name still points to the wrong address.
• Staging certificates are intentionally not trusted.
• The ACME client and its scheduled job must be maintained outside the server configuration.