What this module does #
A TLS certificate is what turns http:// into https://: it encrypts the connection between your visitors and the server, and makes the browser show the padlock instead of a "not secure" warning.
The tls module handles the entire lifecycle of that certificate using certbot: it requests it from Let's Encrypt (a free, well-recognized authority), proves the domain is yours through the ACME challenge, installs the certificate where your web server expects it, and renews it automatically before it expires — without you having to remember.
Your domain (e.g. app.ejemplo.com) must point via DNS to this server's IP, and port 80 must be reachable for the HTTP-01 challenge. Otherwise, issuance will fail at the validation step.
Common tasks #
Pick what you want to do. Each recipe comes with the command already written — just swap in your own domain and email, and hit Copy.
1
Issue my first certificate
Get the HTTPS padlock for your domain in a minute.
Connect to your server over SSH as the ubuntu user.
Run the command, swapping in your own domain and email (the email is only used to warn you if something is about to expire):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Wait a few seconds. You'll see the challenge progress and, at the end, the expiry date.
https:// with the padlock. Automatic renewal is enabled — you don't have to do anything else.2
See which ones exist and when they expire
Check the state of your certificates at a glance.
A quick summary of the overall status and the renewal timer:
$ sudo imaxe tls statusWant the detail domain by domain, with days remaining and the fullchain path? Use list:
$ sudo imaxe tls list3
Force a renewal
It's usually automatic, but you can bring it forward if you need to.
Renew all certificates close to expiring (this is exactly what the timer does):
$ sudo imaxe tls renewWant to rehearse it first without touching disk, or renew even if days remain? Add --dry-run or --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Revoke a certificate
Invalidate a certificate at the authority (e.g. if the key leaked).
Revoke a domain's certificate at Let's Encrypt, giving the reason if you know it:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Delete a certificate from disk
Stop managing a domain you no longer use.
Remove the certificate and its keys from disk. Note: this does not revoke it at the authority — for that, use revoke first.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list and its automatic renewal stops.The most common issue is that DNS hasn't propagated yet or port 80 is closed. Wait a few minutes and retry. If it persists, try the test mode first with --staging (see the reference) so you don't burn through your attempt quota.
Synopsis #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Subcommands that touch certificates require root privileges (use sudo) because they write to /etc/imaxe/ and reload system services. Add --json to list or status for machine-readable output suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| issue | Issues a certificate for one or more domains, resolving the ACME challenge. | --email, --webroot, --standalone, --staging |
| renew | Renews certificates close to expiring and reloads the web server. Suitable for a timer. | --dry-run, --force |
| list | Lists the managed certificates with days to expiry and the fullchain path. | --json |
| status | Summary: number of certificates, those close to expiring, and the renewal timer status. | --json |
| revoke | Revokes a certificate by domain at the authority (ACME). | --reason |
| delete | Deletes the certificate and its keys from disk. Does not revoke at ACME. | — |
Arguments and flags #
| Flag | Type | Default | Description |
|---|---|---|---|
| <dominio> req. | string… | — | One or more domains for the certificate. In issue, the first is the primary (CN); the rest are SANs. In revoke/delete, the domain to operate on. |
| string | tls.yml | Contact email for the ACME account. Required on the first issue; afterwards the one in tls.yml is reused. | |
| --webroot | path | /var/www/html | Root directory for the HTTP-01 challenge. The default method. |
| --standalone | bool | false | Uses certbot's built-in server instead of a webroot. Requires port 80 to be free. |
| --staging | bool | false | Uses the Let's Encrypt test environment (doesn't count toward the rate limit). The certificate won't be trusted. |
| --dry-run | bool | false | In renew, simulates the renewal without touching disk. |
| --force | bool | false | In renew, renews even if it's not close to expiring. |
| --reason | enum | unspecified | In revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | In list/status, emits the result as JSON on stdout. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/tls.yml | Module configuration: default email, method (webroot/standalone), webroot, staging, auto-renewal and reload hook. |
| /etc/letsencrypt/live/<dominio>/ | Certificate (fullchain.pem) and private key (privkey.pem) managed by certbot. |
| /var/log/imaxe/tls.log | Structured log of every issuance, renewal and revocation. |
| imaxe-tls.timer | systemd timer that triggers renew periodically. |
Example tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxExit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
Follow the log live while debugging:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logAdvanced examples #
Several domains in a single certificate
The first domain is the primary; the following ones are added as SANs, all in a single certificate:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]A safe test before production
Validate the whole chain against the test environment so you don't burn through your real quota. With --standalone you don't need a configured web server:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Troubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| Returns CHALLENGE (code 3) | The domain doesn't resolve to this host or port 80 is closed. | Verify the A/AAAA record and open port 80 in the security group; retry. |
| Returns RATELIMIT (code 4) | Too many issuances of the same domain in one week. | Use --staging to test; wait for the window to free up. |
| HTTPS loads but with a warning | Issued with --staging: the certificate isn't trusted. | Reissue without --staging to get a valid one. |
| Returns RELOAD (code 5) | The reload_hook points to a nonexistent service. | Adjust reload_hook in tls.yml and run renew again. |
Stuck with the TLS module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.