Qué hace este módulo #
Un certificado TLS es lo que convierte http:// en https://: cifra la conexión entre tus visitantes y el servidor, y hace que el navegador muestre el candado en vez de un aviso de «sitio no seguro».
El módulo tls se encarga de todo el ciclo de vida de ese certificado apoyándose en certbot: lo solicita a Let's Encrypt (una autoridad gratuita y reconocida), demuestra que el dominio es tuyo mediante el reto ACME, instala el certificado donde tu servidor web lo espera y lo renueva automáticamente antes de que caduque — sin que tengas que acordarte.
Tu dominio (p. ej. app.ejemplo.com) debe apuntar por DNS a la IP de este servidor, y el puerto 80 debe estar accesible para el reto HTTP-01. Si no, la emisión fallará en el paso de validación.
Tareas comunes #
Elige lo que quieres hacer. Cada receta trae el comando ya escrito — solo cambia el dominio y tu correo por los tuyos, y pulsa Copiar.
1
Emitir mi primer certificado
Consigue el candado HTTPS para tu dominio en un minuto.
Conéctate por SSH a tu servidor con el usuario ubuntu.
Lanza el comando cambiando el dominio y el correo por los tuyos (el correo solo se usa para avisarte si algo caduca):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Espera unos segundos. Verás el progreso del reto y, al final, la fecha de caducidad.
https:// con candado. La renovación automática queda activada — no tienes que hacer nada más.2
Ver cuáles hay y cuándo caducan
Comprueba de un vistazo el estado de tus certificados.
Un resumen rápido del estado general y del timer de renovación:
$ sudo imaxe tls status¿Quieres el detalle dominio a dominio, con días restantes y ruta del fullchain? Usa list:
$ sudo imaxe tls list3
Forzar una renovación
Normalmente es automática, pero puedes adelantarla si lo necesitas.
Renueva todos los certificados próximos a caducar (esto es justo lo que hace el timer):
$ sudo imaxe tls renew¿Quieres ensayarlo primero sin tocar disco, o renovar aunque aún queden días? Añade --dry-run o --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Revocar un certificado
Invalida un certificado en la autoridad (p. ej. si la clave se filtró).
Revoca el certificado de un dominio en Let's Encrypt, indicando el motivo si lo conoces:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Borrar un certificado del disco
Deja de gestionar un dominio que ya no usas.
Elimina el certificado y sus claves del disco. Ojo: esto no lo revoca en la autoridad — para eso usa revoke antes.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list y su renovación automática se detiene.El error más habitual es que el DNS aún no ha propagado o el puerto 80 está cerrado. Espera unos minutos y reintenta. Si persiste, prueba primero en modo de pruebas con --staging (ver la referencia) para no gastar el cupo de intentos.
Sinopsis #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Los subcomandos que tocan certificados requieren privilegios de root (usa sudo) porque escriben en /etc/imaxe/ y recargan servicios del sistema. Añade --json a list o status para obtener salida legible por máquina, apta para scripting.
Subcomandos #
| Subcomando | Qué hace | Flags relevantes |
|---|---|---|
| issue | Emite un certificado para uno o más dominios, resolviendo el reto ACME. | --email, --webroot, --standalone, --staging |
| renew | Renueva los certificados próximos a caducar y recarga el servidor web. Apto para timer. | --dry-run, --force |
| list | Lista los certificados gestionados con días a caducar y ruta del fullchain. | --json |
| status | Resumen: nº de certificados, próximos a caducar y estado del timer de renovación. | --json |
| revoke | Revoca un certificado por dominio en la autoridad (ACME). | --reason |
| delete | Borra el certificado y sus claves del disco. No revoca en ACME. | — |
Argumentos y flags #
| Flag | Tipo | Por defecto | Descripción |
|---|---|---|---|
| <dominio> req. | string… | — | Uno o más dominios para el certificado. En issue el primero es el principal (CN); el resto, SAN. En revoke/delete, el dominio a operar. |
| string | tls.yml | Correo de contacto de la cuenta ACME. Obligatorio en el primer issue; luego se reutiliza el de tls.yml. | |
| --webroot | path | /var/www/html | Directorio raíz para el reto HTTP-01. El método por defecto. |
| --standalone | bool | false | Usa el servidor embebido de certbot en lugar de un webroot. Requiere el puerto 80 libre. |
| --staging | bool | false | Usa el entorno de pruebas de Let's Encrypt (no cuenta para el límite de tasa). El certificado no será de confianza. |
| --dry-run | bool | false | En renew, simula la renovación sin tocar disco. |
| --force | bool | false | En renew, renueva aunque no esté próximo a caducar. |
| --reason | enum | unspecified | En revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | En list/status, emite el resultado como JSON en stdout. |
Ficheros y rutas #
| Ruta | Contenido |
|---|---|
| /etc/imaxe/tls.yml | Configuración del módulo: correo por defecto, método (webroot/standalone), webroot, staging, auto-renovación y hook de recarga. |
| /etc/letsencrypt/live/<dominio>/ | Certificado (fullchain.pem) y clave privada (privkey.pem) gestionados por certbot. |
| /var/log/imaxe/tls.log | Registro estructurado de cada emisión, renovación y revocación. |
| imaxe-tls.timer | Temporizador systemd que dispara renew periódicamente. |
Ejemplo 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 salida y logs #
Cada ejecución devuelve un código que puedes comprobar con echo $? — útil para encadenar en scripts:
Sigue el log en vivo mientras depuras:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logEjemplos avanzados #
Varios dominios en un mismo certificado
El primer dominio es el principal; los siguientes se añaden como SAN, todos en un único certificado:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Prueba segura antes de producción
Valida toda la cadena contra el entorno de pruebas para no gastar el cupo real. Con --standalone no necesitas un servidor web configurado:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Resolución de problemas #
| Síntoma | Causa probable | Solución |
|---|---|---|
| Sale CHALLENGE (código 3) | El dominio no resuelve a este host o el puerto 80 está cerrado. | Verifica el registro A/AAAA y abre el 80 en el security group; reintenta. |
| Sale RATELIMIT (código 4) | Demasiadas emisiones del mismo dominio en una semana. | Usa --staging para probar; espera a que se libere la ventana. |
| HTTPS carga pero con aviso | Emitido en --staging: el certificado no es de confianza. | Reemite sin --staging para obtener uno válido. |
| Sale RELOAD (código 5) | El reload_hook apunta a un servicio inexistente. | Ajusta reload_hook en tls.yml y vuelve a lanzar renew. |
¿Te atascaste con el módulo TLS?
Escríbenos con la salida de «imaxe <módulo> status --json» y te respondemos rápido.