zerossl
Request a ZeroSSL certificate for a domain, validate it with a Cloudflare DNS record, and install it
- Command:
/go/zerossl - Category: SSL
- Required option: A domain and a ZeroSSL API key
- Output: Progress messages; no final success message
- Last updated: 2026-11-21
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/zerossl gets a free 90-day SSL certificate from ZeroSSL and installs it for a hosted domain. It does the whole job in one command:
- creates a new private key and certificate request for the domain
- asks ZeroSSL for a certificate and receives a DNS validation record
- adds that record to the domain's DNS in Cloudflare
- asks ZeroSSL to validate it, and waits about a minute
- downloads and installs the certificate, then rebuilds the web configuration
You need a ZeroSSL account and its API key (available in the ZeroSSL dashboard). The domain must be in your Cloudflare account and known to GoAdmio (see dns), because validation is done with a DNS record. The folder /etc/ssl/<domain>, where GoAdmio keeps a domain's paid SSL files, must already exist (see openssl).
The command runs sudo internally, so run it as root or as a user with sudo rights. It needs curl, unzip, openssl, and sqlite3.
[!WARNING] The API key is saved in plain text. The command log,
/var/log/go/zerossl.log, records every argument you pass, including the API key, and the key is visible to other users in the process list while the command runs. Remove the line from the log if the log may be shared, and replace the key in ZeroSSL if it may have been exposed.
[!WARNING] The existing private key is replaced right away. The command overwrites
/etc/ssl/<domain>/privkey.pemwith a new key before it asks ZeroSSL for anything. If the run fails, the new key won't match the certificate that was installed before, and the web server may refuse to start with it. Back up the folder first.
Quick start
# Get and install a ZeroSSL certificate for a domain
/go/zerossl example.com <your-zerossl-api-key>
Syntax
/go/zerossl <domain> <api-key>
Every run is recorded in /var/log/go/zerossl.log, with the time and the arguments you passed.
Options
| Argument | Required | Notes |
|---|---|---|
domain |
Yes | The domain to secure. The folder /etc/ssl/<domain> must exist. |
api-key |
Yes | Your ZeroSSL API access key. |
Output
The command prints a few progress lines, then stops without a final success message.
Domain: example.com
ID: <certificate-id>
Validate certificate at ZeroSSL...
The command takes about a minute or more, because it waits 30 seconds after adding the DNS record and another 30 seconds after asking ZeroSSL to validate it.
| Message | Meaning |
|---|---|
Directory /etc/ssl/<domain> |
That folder doesn't exist. Exit status 1. |
Missing Access Key |
No API key was given. |
Invalid Access Key |
ZeroSSL rejected the API key. |
Certificate Limit Reached |
Your ZeroSSL account has reached its certificate limit. |
Duplicate Certificates Found |
ZeroSSL already has a certificate request for this domain. |
Can not get SSL Domain ID |
ZeroSSL's reply had no certificate ID, so the request failed for another reason. |
Certificate Not Issued |
ZeroSSL hadn't finished validating when the command tried to download. |
Invalid API Function |
ZeroSSL didn't recognize the download request. |
The ZIP file is invalid or corrupted. |
The downloaded file isn't a valid certificate package. |
Every message above ends the command with exit status 1.
Log
Each run appends one line to /var/log/go/zerossl.log, including the API key:
[Nov 21 12:00:00]# zerossl example.com <your-zerossl-api-key>
Examples
# Get and install a certificate
/go/zerossl example.com <your-zerossl-api-key>
# Back up the domain's SSL folder first
cp -a /etc/ssl/example.com /etc/ssl/example.com.backup
# Check the new certificate's expiry date
openssl x509 -enddate -noout -in /etc/ssl/example.com/cert.pem
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Directory /etc/ssl/<domain> |
The domain's SSL folder doesn't exist, or the domain was misspelled. | Check the name. The folder is normally created with the account (see openssl). |
Invalid Access Key or Missing Access Key |
The key is wrong or missing. | Copy the key from your ZeroSSL dashboard and run the command again. |
Certificate Limit Reached |
The ZeroSSL account has used up the certificates it is allowed. | Delete or cancel certificates you no longer need in the ZeroSSL dashboard, or use another account. |
Duplicate Certificates Found |
An earlier request for this domain is still open at ZeroSSL, for example after a failed run. | Delete or cancel that certificate in the ZeroSSL dashboard, then run the command again. |
Certificate Not Issued |
Validation takes longer than the command waits (about 60 seconds), or the DNS record didn't reach ZeroSSL. | Check that the validation CNAME record exists in Cloudflare. The command can't resume, so delete the pending certificate in ZeroSSL and run it again. |
The CNAME record isn't in Cloudflare |
The domain isn't in the Cloudflare account, GoAdmio has no zone ID saved for it, or the API token can't edit DNS. | Add the domain with dns and check the Cloudflare settings in GoAdmio. The command doesn't report this error. |
unzip asks whether to replace files |
certificate.crt and ca_bundle.crt from an earlier run are in the folder. |
Answer A (all) to replace them. |
| The command ends with no message and the certificate isn't new | The downloaded package didn't contain certificate.crt and ca_bundle.crt, so nothing was installed. |
Check /etc/ssl/<domain>, then run the command again. |
| The web server fails after a failed run | privkey.pem was replaced and no longer matches cert.pem. |
Restore the folder from your backup. |
Details
What it does
| Step | Action |
|---|---|
| 1 | Checks that /etc/ssl/<domain> exists, then works inside it. |
| 2 | Creates a new 2048-bit RSA private key (privkey.pem) and a certificate request (<domain>.csr). The certificate request's other fields hold placeholder values. Only the domain name is used by ZeroSSL. |
| 3 | Asks ZeroSSL for a 90-day certificate for the domain. The certificate covers the domain you give, and not www.<domain>. |
| 4 | Takes the validation CNAME host and value from ZeroSSL's reply and creates that record in the domain's Cloudflare DNS (not proxied, TTL 3600). The record is left in DNS afterward. |
| 5 | Waits 30 seconds, asks ZeroSSL to validate with CNAME_CSR_HASH, then waits another 30 seconds. |
| 6 | Downloads certificate.zip and unpacks it in the folder. |
| 7 | Copies certificate.crt to cert.pem and ca_bundle.crt to bundle.pem, replacing the old files. |
| 8 | Runs conf to rebuild the web configuration for all accounts, skipping the SSL and mail SSL steps. |
The result is the same set of files GoAdmio uses for a paid certificate: cert.pem, bundle.pem, and privkey.pem in /etc/ssl/<domain>.
The command doesn't schedule renewal. ZeroSSL's certificates last 90 days, so run the command again before then.
flowchart TD
A["zerossl domain api-key"] --> B{"/etc/ssl/domain exists?"}
B -- "No" --> X["Print the folder, exit 1"]
B -- "Yes" --> C["Create a new private key and certificate request"]
C --> D["Ask ZeroSSL for a certificate"]
D -- "Error" --> E["Print the error, exit 1"]
D -- "ID received" --> F["Add the validation CNAME in Cloudflare"]
F --> G["Wait 30 s, ask ZeroSSL to validate, wait 30 s"]
G --> H["Download the certificate package"]
H -- "Not issued or invalid" --> E
H -- "Valid" --> I["Install cert.pem and bundle.pem"]
I --> J["Run conf for all accounts"]
See also
| Command | Description |
|---|---|
openssl |
Generate, install, or delete a paid SSL certificate |
ssl |
Install an SSL certificate for a domain in GoAdmio |
installssl |
Install Let's Encrypt SSL on GoAdmio |
checkssl |
Audit SSL certificates for all hosted domains, renew those close to expiry, and send expiry alerts |
conf |
Rebuild Apache/Nginx virtual hosts, PHP-FPM pools, and SSL for all accounts, or the web configuration of one domain |
dns |
Add one or all hosted domains to Cloudflare and set up their DNS zone, proxy and cache mode, nameservers, and SSL |