Cosa fa questo modulo #
Un certificato TLS è ciò che trasforma http:// in https://: cifra la connessione tra i tuoi visitatori e il server, e fa sì che il browser mostri il lucchetto invece di un avviso di «sito non sicuro».
Il modulo tls si occupa di tutto il ciclo di vita di quel certificato appoggiandosi a certbot: lo richiede a Let's Encrypt (un'autorità gratuita e riconosciuta), dimostra che il dominio è tuo mediante la sfida ACME, installa il certificato dove il tuo server web se lo aspetta e lo rinnova automaticamente prima che scada — senza che tu debba ricordartene.
Il tuo dominio (ad es. app.ejemplo.com) deve puntare via DNS all'IP di questo server, e la porta 80 deve essere raggiungibile per la sfida HTTP-01. In caso contrario, l'emissione fallirà nella fase di validazione.
Attività comuni #
Scegli cosa vuoi fare. Ogni ricetta porta il comando già scritto — cambia solo il dominio e la tua email con i tuoi, e premi Copia.
1
Emettere il mio primo certificato
Ottieni il lucchetto HTTPS per il tuo dominio in un minuto.
Connettiti via SSH al tuo server con l'utente ubuntu.
Lancia il comando cambiando il dominio e l'email con i tuoi (l'email serve solo ad avvisarti se qualcosa scade):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Aspetta qualche secondo. Vedrai l'avanzamento della sfida e, alla fine, la data di scadenza.
https:// con il lucchetto. Il rinnovo automatico rimane attivato — non devi fare altro.2
Vedere quali ci sono e quando scadono
Verifica a colpo d'occhio lo stato dei tuoi certificati.
Un riepilogo rapido dello stato generale e del timer di rinnovo:
$ sudo imaxe tls statusVuoi il dettaglio dominio per dominio, con i giorni rimanenti e il percorso del fullchain? Usa list:
$ sudo imaxe tls list3
Forzare un rinnovo
Di norma è automatico, ma puoi anticiparlo se ti serve.
Rinnova tutti i certificati prossimi alla scadenza (è esattamente ciò che fa il timer):
$ sudo imaxe tls renewVuoi provarlo prima senza toccare il disco, o rinnovare anche se mancano ancora dei giorni? Aggiungi --dry-run o --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Revocare un certificato
Invalida un certificato presso l'autorità (ad es. se la chiave è trapelata).
Revoca il certificato di un dominio su Let's Encrypt, indicando il motivo se lo conosci:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Eliminare un certificato dal disco
Smetti di gestire un dominio che non usi più.
Elimina il certificato e le sue chiavi dal disco. Attenzione: questo non lo revoca presso l'autorità — per quello usa prima revoke.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list e il suo rinnovo automatico si ferma.L'errore più comune è che il DNS non si sia ancora propagato o che la porta 80 sia chiusa. Aspetta qualche minuto e riprova. Se persiste, prova prima in modalità di test con --staging (vedi il riferimento) per non consumare il limite di tentativi.
Sinossi #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]I sottocomandi che toccano i certificati richiedono privilegi di root (usa sudo) perché scrivono in /etc/imaxe/ e ricaricano servizi di sistema. Aggiungi --json a list o status per ottenere un output leggibile dalla macchina, adatto allo scripting.
Sottocomandi #
| Sottocomando | Cosa fa | Flag rilevanti |
|---|---|---|
| issue | Emette un certificato per uno o più domini, risolvendo la sfida ACME. | --email, --webroot, --standalone, --staging |
| renew | Rinnova i certificati prossimi alla scadenza e ricarica il server web. Adatto al timer. | --dry-run, --force |
| list | Elenca i certificati gestiti con i giorni alla scadenza e il percorso del fullchain. | --json |
| status | Riepilogo: n° di certificati, prossimi alla scadenza e stato del timer di rinnovo. | --json |
| revoke | Revoca un certificato per dominio presso l'autorità (ACME). | --reason |
| delete | Elimina il certificato e le sue chiavi dal disco. Non revoca su ACME. | — |
Argomenti e flag #
| Flag | Tipo | Predefinito | Descrizione |
|---|---|---|---|
| <dominio> obbl. | string… | — | Uno o più domini per il certificato. In issue il primo è il principale (CN); gli altri, SAN. In revoke/delete, il dominio su cui operare. |
| string | tls.yml | Email di contatto dell'account ACME. Obbligatoria al primo issue; in seguito si riutilizza quella di tls.yml. | |
| --webroot | path | /var/www/html | Directory radice per la sfida HTTP-01. Il metodo predefinito. |
| --standalone | bool | false | Usa il server incorporato di certbot al posto di un webroot. Richiede la porta 80 libera. |
| --staging | bool | false | Usa l'ambiente di test di Let's Encrypt (non conta per il limite di frequenza). Il certificato non sarà affidabile. |
| --dry-run | bool | false | In renew, simula il rinnovo senza toccare il disco. |
| --force | bool | false | In renew, rinnova anche se non è prossimo alla scadenza. |
| --reason | enum | unspecified | In revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | In list/status, emette il risultato come JSON su stdout. |
File e percorsi #
| Percorso | Contenuto |
|---|---|
| /etc/imaxe/tls.yml | Configurazione del modulo: email predefinita, metodo (webroot/standalone), webroot, staging, rinnovo automatico e hook di ricarica. |
| /etc/letsencrypt/live/<dominio>/ | Certificato (fullchain.pem) e chiave privata (privkey.pem) gestiti da certbot. |
| /var/log/imaxe/tls.log | Registro strutturato di ogni emissione, rinnovo e revoca. |
| imaxe-tls.timer | Timer systemd che avvia renew periodicamente. |
Esempio di tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxCodici di uscita e log #
Ogni esecuzione restituisce un codice che puoi verificare con echo $? — utile per concatenare negli script:
Segui il log in tempo reale mentre analizzi:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logEsempi avanzati #
Più domini in un unico certificato
Il primo dominio è il principale; i successivi si aggiungono come SAN, tutti in un unico certificato:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Prova sicura prima della produzione
Convalida l'intera catena contro l'ambiente di test per non consumare il quota reale. Con --standalone non ti serve un server web configurato:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Risoluzione dei problemi #
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Esce CHALLENGE (codice 3) | Il dominio non risolve a questo host o la porta 80 è chiusa. | Verifica il record A/AAAA e apri la 80 nel security group; riprova. |
| Esce RATELIMIT (codice 4) | Troppe emissioni dello stesso dominio in una settimana. | Usa --staging per fare prove; aspetta che si liberi la finestra. |
| HTTPS si carica ma con avviso | Emesso in --staging: il certificato non è affidabile. | Riemetti senza --staging per ottenerne uno valido. |
| Esce RELOAD (codice 5) | Il reload_hook punta a un servizio inesistente. | Regola reload_hook in tls.yml e rilancia renew. |
Bloccato con il modulo TLS?
Scrivici allegando l'output di «imaxe <module> status --json» e ti rispondiamo in fretta.