O que faz este módulo #
Um certificado TLS é o que transforma http:// em https://: cifra a ligação entre os teus visitantes e o servidor, e faz o navegador mostrar o cadeado em vez de um aviso de «não seguro».
O módulo tls trata de todo o ciclo de vida desse certificado usando o certbot: solicita-o à Let's Encrypt (uma autoridade gratuita e bem reconhecida), prova que o domínio é teu através do desafio ACME, instala o certificado onde o teu servidor web o espera e renova-o automaticamente antes de expirar — sem teres de te lembrar.
O teu domínio (ex. app.ejemplo.com) tem de apontar via DNS para o IP deste servidor, e a porta 80 tem de estar acessível para o desafio HTTP-01. Caso contrário, a emissão falhará no passo da validação.
Tarefas comuns #
Escolhe o que queres fazer. Cada receita traz o comando já escrito — basta trocar pelo teu próprio domínio e email, e clicar em Copiar.
1
Emitir o meu primeiro certificado
Consegue o cadeado HTTPS para o teu domínio num minuto.
Liga-te por SSH ao teu servidor com o utilizador ubuntu.
Executa o comando, trocando pelo teu próprio domínio e email (o email só é usado para te avisar se algo estiver prestes a expirar):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Espera uns segundos. Verás o progresso do desafio e, no final, a data de expiração.
https:// com o cadeado. A renovação automática está ativada — não tens de fazer mais nada.2
Ver quais existem e quando expiram
Verifica o estado dos teus certificados num relance.
Um resumo rápido do estado geral e do timer de renovação:
$ sudo imaxe tls statusQueres o detalhe domínio a domínio, com os dias restantes e o caminho do fullchain? Usa list:
$ sudo imaxe tls list3
Forçar uma renovação
Normalmente é automática, mas podes antecipá-la se precisares.
Renova todos os certificados perto de expirar (é exatamente o que o timer faz):
$ sudo imaxe tls renewQueres ensaiá-la primeiro sem tocar no disco, ou renovar mesmo que ainda faltem dias? Adiciona --dry-run ou --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Revogar um certificado
Invalida um certificado na autoridade (ex. se a chave foi comprometida).
Revoga o certificado de um domínio na Let's Encrypt, indicando o motivo se o souberes:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Apagar um certificado do disco
Deixa de gerir um domínio que já não usas.
Remove o certificado e as suas chaves do disco. Nota: isto não o revoga na autoridade — para isso, usa revoke primeiro.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list e a sua renovação automática para.O problema mais comum é o DNS ainda não ter propagado ou a porta 80 estar fechada. Espera uns minutos e tenta de novo. Se persistir, experimenta primeiro o modo de teste com --staging (vê a referência) para não gastares a tua quota de tentativas.
Sinopse #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Os subcomandos que tocam em certificados requerem privilégios de root (usa sudo) porque escrevem em /etc/imaxe/ e recarregam serviços do sistema. Adiciona --json a list ou status para saída legível por máquina, apta para scripting.
Subcomandos #
| Subcomando | O que faz | Flags relevantes |
|---|---|---|
| issue | Emite um certificado para um ou mais domínios, resolvendo o desafio ACME. | --email, --webroot, --standalone, --staging |
| renew | Renova os certificados perto de expirar e recarrega o servidor web. Adequado para um timer. | --dry-run, --force |
| list | Lista os certificados geridos com os dias até expirar e o caminho do fullchain. | --json |
| status | Resumo: número de certificados, os que estão perto de expirar e o estado do timer de renovação. | --json |
| revoke | Revoga um certificado por domínio na autoridade (ACME). | --reason |
| delete | Apaga o certificado e as suas chaves do disco. Não revoga no ACME. | — |
Argumentos e flags #
| Flag | Tipo | Por omissão | Descrição |
|---|---|---|---|
| <dominio> obr. | string… | — | Um ou mais domínios para o certificado. Em issue, o primeiro é o principal (CN); os restantes são SANs. Em revoke/delete, o domínio sobre o qual operar. |
| string | tls.yml | Email de contacto para a conta ACME. Obrigatório no primeiro issue; depois reutiliza-se o de tls.yml. | |
| --webroot | path | /var/www/html | Diretório raiz para o desafio HTTP-01. O método por omissão. |
| --standalone | bool | false | Usa o servidor incorporado do certbot em vez de um webroot. Requer que a porta 80 esteja livre. |
| --staging | bool | false | Usa o ambiente de teste da Let's Encrypt (não conta para o rate limit). O certificado não será de confiança. |
| --dry-run | bool | false | Em renew, simula a renovação sem tocar no disco. |
| --force | bool | false | Em renew, renova mesmo que não esteja perto de expirar. |
| --reason | enum | unspecified | Em revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | Em list/status, emite o resultado como JSON em stdout. |
Ficheiros e caminhos #
| Caminho | Conteúdo |
|---|---|
| /etc/imaxe/tls.yml | Configuração do módulo: email por omissão, método (webroot/standalone), webroot, staging, renovação automática e reload hook. |
| /etc/letsencrypt/live/<dominio>/ | Certificado (fullchain.pem) e chave privada (privkey.pem) geridos pelo certbot. |
| /var/log/imaxe/tls.log | Log estruturado de cada emissão, renovação e revogação. |
| imaxe-tls.timer | Timer do systemd que dispara o renew periodicamente. |
Exemplo de tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxCódigos de saída e logs #
Cada execução devolve um código que podes verificar com echo $? — útil para encadear em scripts:
Segue o log em direto enquanto depuras:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logExemplos avançados #
Vários domínios num único certificado
O primeiro domínio é o principal; os seguintes são adicionados como SANs, todos num único certificado:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Um teste seguro antes de produção
Valida toda a cadeia contra o ambiente de teste para não gastares a tua quota real. Com --standalone não precisas de um servidor web configurado:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Resolução de problemas #
| Sintoma | Causa provável | Solução |
|---|---|---|
| Sai CHALLENGE (código 3) | O domínio não resolve para este servidor ou a porta 80 está fechada. | Verifica o registo A/AAAA e abre a porta 80 no security group; tenta de novo. |
| Sai RATELIMIT (código 4) | Demasiadas emissões do mesmo domínio numa semana. | Usa --staging para testar; espera que a janela se liberte. |
| O HTTPS carrega mas com um aviso | Emitido com --staging: o certificado não é de confiança. | Reemite sem --staging para obter um válido. |
| Sai RELOAD (código 5) | O reload_hook aponta para um serviço inexistente. | Ajusta o reload_hook em tls.yml e executa renew de novo. |
Ficou bloqueado com o módulo TLS?
Escreva-nos com a saída de «imaxe <module> status --json» e respondemos rapidamente.