SSL Certificates

Issue and renew certificates automatically for use by Web Services, or export them to other software.

Capabilities

• ACME DNS-01 automatic issuance and renewal, reusing the DNS providers from Dynamic DNS, with no need to open ports 80 / 443;
• ACME HTTP-01: needs no DNS provider, but port 80 of each domain must be reachable from the internet; wildcards are not supported;
• Wildcard certificates and EAB (for example ZeroSSL);
• Upload an existing certificate, or read it from files;
• Map to a directory: after a certificate changes, the files are written to the specified directory and a script runs, so other services can reload;
• Auto deploy: after a certificate changes, copy it to several local directories, push it to other hosts over SSH and run a command, or restart the Docker containers that use it.

HTTP-01 validation

Choose HTTP-01 as the certificate's "Method". During issuance, the CA requests http://<domain>/.well-known/acme-challenge/<token>:

• If Web Services already listens on port 80, it answers directly without affecting existing sites;
• If port 80 is free, Gately listens on it temporarily during issuance and closes it right after;
• If your router forwards public port 80 to another local port, enter that port in "Temporary port".

Many residential ISPs (for example in mainland China) block inbound port 80; use DNS-01 in that case.

Certificate mapping

Once a certificate is enabled, Gately writes .crt, .key, .pem and _issuerCertificate.crt into the mapping directory and runs the change script.

Auto deploy

Under the certificate's "Auto deploy" you can add several deployment targets, which run automatically after the certificate is issued, renewed or updated:

• Copy to local directory: write the certificate to a directory on this machine, then run the "Run after copying" command locally. You can add several directories, each with a different command. If the certificate files in a directory are deleted or changed, the next check copies them again. When Gately runs in Docker, the directory and command are inside the container;
• Upload to SSH host: pick an existing SSH connection from Web Terminal to reuse its address, authentication and proxy. The certificate files (<remark>.crt, .key, .pem and _issuerCertificate.crt, the same as certificate mapping, so the remark is required) are written to the remote directory, then the "Run after upload" command runs on the remote host, for example systemctl reload nginx. The command can use $certName, $certDir, $certFile and $keyFile. Files are first written to temporary files with their permissions set and then renamed into place; the private key gets permission 0600;
• Restart local containers: after the certificate changes, the selected Docker containers are restarted in turn. Use this for containers that mount the mapping directory and need a restart to load the new certificate.

"Copy to local directory" and "Upload to SSH host" accept file names for the certificate (full chain) and the private key, such as fullchain.pem and privkey.pem. With both set, only those two files are written and the remark may be empty; left empty, the certificate mapping file names are used. $certFile and $keyFile in the command point to the files actually written.

Auto deploy never trusts an unknown host: connect to the selected SSH connection once in Web Terminal to record its host key before anything is pushed. Failed deployments are retried every hour and raise a "Certificate: deployment failed" event, which you can subscribe to in the Notification Center. "Deploy now" on the certificate card ignores the retry interval, deploys to all enabled targets right away and shows the result for each target.

When you edit a certificate, deployments whose target settings did not change are not run again; changing the remote directory, command or containers triggers one new deployment.

Security note

Private keys are stored in ssl.json in the configuration directory. Keep that file safe, and make sure the repository is private if you put it under version control.

Migrating from Lucky

Certificates that are already issued are imported as they are and are not requested again before they expire. ZeroSSL registers a new ACME account using the EAB credentials from Lucky. See the Migration Guide for details.