Installare un certificato Let's Encrypt per i server qmail e dovecot

Changelog

• Jun 6, 2025
  - dehydrated now launches a hook.sh script which handles the post-installation tasks (assemble and copy the certificate into the qmail dir, restart the server and eventually alert the administrator in case of problems). It replaces the old scripts.
• 22 febbraio 2025
  Let's Encrypt ha annunciato che interromperà il servizio di avviso via mail per i certificati in scadenza. Aggiunto uno script che fa la stessa cosa internamente.
• 5 agosto 2023
  - L'installzione del certificato è ora basata su dehydrated. La vecchia documentazione basata su certbot si trova in fondo a questa pagina, ma non verrà più aggiornata.
• May 18, 2023
  - added the option --key-type rsa to the certbot command, to avoid that certbot will silently default to ECDSA the private key format, which results not understandable by my openssl-1.1. In this way the format of the private key will be RSA. More info here.

To enable HTTPS on your website, you need to get a certificate (a type of file) from a Certificate Authority (CA). Let’s Encrypt is a CA. In order to get a certificate for your website’s domain from Let’s Encrypt, you have to demonstrate control over the domain. With Let’s Encrypt, you do this using software that uses the ACME protocol which typically runs on your web host.

• Sito Let's Encrypt
• Pagina github dehydrated
• Pagina di AlienBob  (per utenti Slackware, ma con istruzioni generiche)

Dehydrated is a client for signing certificates with an ACME-server (e.g. Let's Encrypt) implemented as a relatively simple (zsh-compatible) bash-script. This client supports both ACME v1 and the new ACME v2 including support for wildcard certificates!

Trattandosi di un programma shell, dehydrated ha il vantaggio di non richiedere dipendenze, a differenza deI programma ufficiale certbot, che richiede una lunghissima serie di librerie python. Mantenere tutto questo volume di programmi si è rivelato faticoso nel tempo, ed è questo il motivo per cui mi sono deciso a passare a dehydrated.

Note per l'aggiornamento

Nel caso si debba rimpiazzare una installazione funzionante dei certificati basati su certbot, non è necessario prendere alcuna precauzione poichè questi non saranno sovrascritti dai nuovi generati da dehydrated. Pertanto è possibile eseguire i nostri test riguardanti la configurazione di dehydrated nello stesso server di produzione. Naturalmente sarà bene utilizzare un dominio di prova mentre si smanetta con Apache.

Installazione di dehydrated

E' probabile che la distribuzione in uso metta a disposizione un pacchetto dehydrated. In tal caso installarlo da lì, altrimenti scaricare e installare il programma dal sito github.

Qui di seguito un breve esempio di una installazione manuale in /usr/local (modificare secondo i propri bisogni):

VERSION=0.7.2
PREFIX=/usr/local

wget https://github.com/dehydrated-io/dehydrated/releases/download/v${VERSION}/dehydrated-${VERSION}.tar.gz
tar xzf dehydrated-${VERSION}.tar.gz
cd dehydrated-${VERSION}
chown -R root:root .
cp dehydrated $PREFIX/bin/
mkdir -p $PREFIX/man/man1 $PREFIX/share/doc/dehydrated-${VERSION}/docs/examples
cp docs/man/dehydrated.1 $PREFIX/man/man1/
mkdir -p /etc/dehydrated
cp docs/examples/config /etc/dehydrated/config.new # .new just to avoid overwrite of the existing config. Rename to config
cp CHANGELOG* LICENSE* README* $PREFIX/share/doc/dehydrated-${VERSION}
cp docs/*.md $PREFIX/share/doc/dehydrated-${VERSION}/docs
cp docs/examples/{domains.txt,hook.sh} $PREFIX/share/doc/dehydrated-${VERSION}/docs/examples

Configurazione

• Esempio di file di configurazione

Portarsi nella cartella /etc/dehydrated, dove abbiamo i file di configurazione e dove verranno installati i certificati. Queste le mie modifiche al file config:

CA="letsencrypt-test"
CHALLENGETYPE="http-01"
WELLKNOWN="/var/www/htdocs/dehydrated"
HOOK="${BASEDIR}/scripts/hook.sh"
HOOK_CHAIN="yes"
KEY_ALGO=rsa
CONTACT_EMAIL=postmaster@mydomain.tld

• CA contiene l'URL al server Let’s Encrypt, oppure un parametro (in questo caso letsencrypt-test) che dice al programma quale URL usare. In fase di test lasciare "letsencrypt-test" di modo che il server non venga intasato e noi bannati di conseguenza se si supera il limite di tentativi non validi. Una volta che tutto sarà a posto useremo CA="letsencrypt". Maggiori informazioni qui.
• CHALLENGETYPE="http-01" Come sappiamo, è necessario dimostrare di avere il controllo dei domini di cui si vuole ottenere un certificato. Per fare ciò verrà testato l'accesso a un file di verifica posto nel nostro web server, in una cartella dove Apache deve avere accesso per ciascuno dei domini da certificare.
  Esistono anche altri CHALLENGETYPE, dns-01 ad esempio è adatto a certificare domini con wildcard come *.sagredo.eu, ma è necessario disporre di programmi per manipolare in automatico il server DNS. Questa parte non viene pertanto trattata qui.
• WELLKNOWN="/var/www/htdocs/dehydrated" è la cartella locale dove dehydrated installerà i ‘challenge-tokens’, che poi sarà recuperato via http al fine di validare il dominio.
• HOOK="${BASEDIR}/scripts/hook.sh" è lo script che viene lanciato durante le operazioni di creazione del certificato. E' usato per assemblare/copiare il certificato nella cartella di qmail, per riavviare i server e per inviare notifiche via mail all'amministratore in casi di problemi.
• HOOK_CHAIN="yes" Ripulisce gli argomenti delle funzioni clean_challenge|deploy_challenge tutti insieme in una singola chiamata per certificato.
• KEY_ALGO=rsa specifica l'algoritmo da usare per la chiave pubblica.

Per usare dehydrated è necessario registrare un account:

# dehydrated --register --accept-terms 
# INFO: Using main config file /etc/dehydrated/config 
+ Generating account key... 
+ Registering account key with ACME server... 
+ Fetching account URL... 
+ Done!

Le informazioni riguardanti l'account vengono salvate nella cartella /etc/dehydrated/accounts.

Configurazione dei domini

• Maggiori informazioni

Creare un file domains.txt nel quale disporre i domini da certificare separati da uno spazio bianco. Si possono inserire domini su righe separate. Quelli che stanno sulla stessa riga faranno capo a uno stesso certificato, il cui nome sarà quello del primo dominio della riga. Ad esempio

mx.mydomain.tld
mydomain.tld www.mydomain.tld webmail.mydomain.tld otherdomain.tld www.otherdomain.tld webmail.otherdomain.tld

creerà due certificati mx.mydomain.tld e mydomain.tld.

In aggiunta verranno letti tutti gli eventuali file con estensione txt posti nella cartella /etc/dehydrated/domains.d.

Configurazione di Apache

In un caso tipico dovremo certificare molti domini, alcuni dei quali dedicati al server di posta, altri a dei semplici spazi web (per esempio la webmail o il pannello di controllo qmailadmin) ognuno con il proprio VirtualHost e la propria cartella radice DocumentRoot. Faremo in modo di salvare i ‘challenge-tokens’ in una medesima cartella accessibile a tutti questi domini, diciamo /var/www/htdocs/dehydrated, che è quella indicata dal parametro WELLKNOWN nel file di configurazione.

Creiamo innanzitutto la suddetta cartella:

mkdir -p /var/www/htdocs/dehydrated

Il codice da aggiungere è ripetitivo ed è conveniente automatizzare il tutto salvandolo in un file redirect.conf da importare in ciascun VirtualHost. Salviamolo nella cartella di configurazione di Apache, ovvero /etc/httpd:

LOGDIR=/var/www/error

cat > /etc/httpd/redirect.conf << __EOF__
<IfModule mod_rewrite.c> 
  RewriteEngine On 
  RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge 
  RewriteRule ^(.*) https://%{SERVER_NAME}\$1 [R,L] 
</IfModule> 

Alias /.well-known/acme-challenge /var/www/htdocs/dehydrated
<Directory /var/www/htdocs/dehydrated>
  Options None 
  AllowOverride None 
  Require all granted 
</Directory>

# Define or change \${LOGDIR} to where your server saves the logs
CustomLog "\${LOGDIR}/dehydrated_access.log" combined
ErrorLog  "\${LOGDIR}/dehydrated.f2b.log"
__EOF__

Così facendo le richieste per i file del tipo /.well-known/acme-challenge/* saranno servite nella cartella /var/www/htdocs/dehydrated, mentre il resto del traffico verrà reindirizzato (in questo esempio) all'indirizzo https con lo stesso dominio (SERVER_NAME). Come si può vedere, ciò presuppone che il modulo mod_rewrite di Apache sia stato abilitato.

Sempre per questioni di ordine e di economia di codice, converrà definire, nel file generale di configurazione /etc/httpd.conf o dove si preferisce, alcune variabili, ad esempio il percorso del file da includere e, visto che ci siamo, il file che useremo in seguito per importare i certificati SSL e la cartella che andrà a ospitare i certificati:

Define REDIRECT /etc/httpd/redirect.conf
Define SSL      /etc/httpd/ssl.conf
Define CERTDIR  /etc/dehydrated/certs

Ecco uno schema del virtual host relativo al dominio che porta al nostro server di posta:

<VirtualHost *:80> 
  ServerName mx.mydomain.tld
  Include \${REDIRECT}
</VirtualHost>

Creazione del certificato

Non ci resta che creare il certificato:

# dehydrated -c 
# INFO: Using main config file /etc/dehydrated/config 
Processing mx.mydomain.tld 
+ Creating new directory /etc/dehydrated/certs/mx.mydomain.tld ... 
+ Signing domains... 
+ Generating private key... 
+ Generating signing request... 
+ Requesting new certificate order from CA... 
+ Received 1 authorizations URLs from the CA 
+ Handling authorization for mx.mydomain.tld 
+ 1 pending challenge(s) 
+ Deploying challenge tokens... 
+ Responding to challenge for mx.mydomain.tld authorization... 
+ Challenge is valid! 
+ Cleaning challenge tokens... 
+ Requesting certificate... 
+ Order is processing... 
+ Checking certificate... 
+ Done! 
+ Creating fullchain.pem... 
+ Done!

Dovremo ottenere un risultato simile per ogni certificato richiesto (uno per ogni riga in domains.txt). I certificati vengono salvati nella cartella certs, di cui abbiamo registrato l'indirizzo nel parametro CERTDIR. Usare il man o anche dehydrated -h per vedere come cancellare o revocare i certifcati.

Una volta che la procedura di creazione dei certificati è andata a buon fine possiamo impostare dehydrated affinchè si colleghi all'indirizzo di produzione (CA="letsencrypt" nel file config).

A questo punto i certificati non sono ancora visti nè dal web-server, nè da qmail e nè da dovecot.

Installazione del certificato su Apache

Per quanto riguarda Apache, creiamo un file con le impostazioni SSL da importare in ogni VirtualHost:

cat > /etc/httpd/ssl.conf << __EOF__
SSLEngine on 
SSLCertificateFile \${CERTDIR}/\${CERTNAME}/fullchain.pem 
SSLCertificateKeyFile \${CERTDIR}/\${CERTNAME}/privkey.pem 
SSLCertificateChainFile \${CERTDIR}/\${CERTNAME}/fullchain.pem
__EOF__

CERTNAME è il nome del certificato, da passare prima di includere il file, come da esempio qui sotto. CERTDIR l'abbiamo già definito più sopra.

Questo è un esempio di VirtualHost configurato per ospitare delle pagine web in https, ad esempio per la webmail:

<VirtualHost *:80> 
  ServerName webmail.mydomain.tld
  ServerAlias webmail.otherdomain.tld
  Include ${REDIRECT} 
</VirtualHost> 

<VirtualHost *:443> 
  # The name of the certificate is the first domain of the line in /etc/dehydrated/domains.txt
  Define CERTNAME mydomain.tld
  # SSL cannot work until the certificate is in place. Comment it out initially
  Include ${SSL} 

  ServerName webmail.mydomain.tld
  ServerAlias webmail.otherdomain.tld

  ErrorLog  ${LOGDIR}/roundcube_error.log 
  CustomLog ${LOGDIR}/roundcube_access.log combined 

  DocumentRoot ${HTDOCS}/roundcube

  <Directory ${HTDOCS}/roundcube> 
    Require all granted 
  </Directory> 
</VirtualHost>

Installazione del certificato su qmail e dovecot

• hook.sh script

dehydrated è in grado di lanciare un programma a nostra scelta durante la creazione del certificato (HOOK="${BASEDIR}/scripts/hook.sh" nel file di configurazione). Come già detto, è usato per assemblare/copiare il certificato per qmail, riavviare i server e per invisare notifiche via mail all'amministratore in caso di problemi.

Lo script hook.sh è rilasciato dallo stesso progetto dehydrated e per questo potrebbe subire delle variazioni in futuro, pertanto le nostre funzioni per qmail sono contenute in hook.inc e poi importate in hook.sh in modo da semplificare gli aggiornamenti futuri del file principale.

Scaricarlo nella cartella "scripts":

mkdir -p /etc/dehydrated/scripts
cd /etc/dehydrated/scripts
wget https://notes.sagredo.eu/files/qmail/dehydrated/hook.sh
wget https://notes.sagredo.eu/files/qmail/dehydrated/hook.inc
wget https://notes.sagredo.eu/files/qmail/dehydrated/hook.conf
wget https://notes.sagredo.eu/files/qmail/dehydrated/hook.tpl
chmod +x hook.sh

E' necessario inserire la propria email ed eventualmente la posizione dei file di avvio dei servers in hook.conf. CERTNAME è la variabile che contiene il nome del certificato per qmail (in caso ci siano più certificati da creare):

# qmail cert name
CERTNAME=mx.domain.tld
CERTDIR=/etc/dehydrated/certs/${CERTNAME}
QMAILDIR=/var/qmail
QMAILCTL=${QMAILDIR}/bin/qmailctl
DOVECOTCTL=/usr/local/bin/dovecotctl
APACHECTL=/usr/sbin/apachectl
# email address where alerts are sent on failures
OWNER_EMAIL=owner@domain.tld
# sender address
FROM_EMAIL=postmaster@domain.tld
# The message template which will be used to draft the email alert
MSG_TEMPLATE="$(dirname $0)/hook.tpl"

hook.tpl è il file template per gli avvisi via mail. Si può personalizzare anche quello, magari traducendolo nella propia lingua.

Come sappiamo, il certificato di qmail (file control/servercert.pem) è il risultato della concatenazione della chiave privata e della fullchain. Per quanto riguarda qmail non dobbiamo fare altro.

Riguardo a Dovecot, invece, è necessario impostare correttamente l'indirizzo dei certificati nel file local.conf:

ssl_server_cert_file = /etc/dehydrated/certs/mx.mydomain.tld/fullchain.pem
ssl_server_cert_file = /etc/dehydrated/certs/mx.mydomain.tld/privkey.pem

Letsencrypt raccomanda di rinnovare automaticamente i certificati quando sono a circa un terzo dal loro fine vita, che al momento è 90 giorni. Questo significa che è necessario rinnovarli a 30 giorni dalla scadenza Settiamo dunque il cronjob affinchè lanci dehydrated una volta al mese:

cat > /etc/cron.d/dehydrated << __EOF__
40 2 6 * * root /usr/bin/dehydrated -c >> /var/log/cron 2>&1
__EOF_

E' ora possibile rimuovere la vecchia linea update_tmprsadh dal crontab, se la si era creata.

---

Installazione di certbot

La documentazione su certbot non è più aggiornata in quanto soppiantata da quella basata su dehydrated. Viene lasciata intatta in caso possa ancora essere di aiuto a qualcuno.

Qui di seguito viene spiegato come installare e configurare un certificato SSL valido di Let's Encrypt per i server qmail e dovecot. L'installazione è ad opera del client certbot.

Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communication over the Web relies on HTTPS, which requires the use of a digital certificate that lets browsers verify the identity of web servers (e.g., is that really google.com?). Web servers obtain their certificates from trusted third parties called certificate authorities (CAs). Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server.

Maggiori informazioni qui:

• https://certbot.eff.org/docs/
• https://letsencrypt.org/ 

Innanzitutto è necessaria una versione di python v.3, e poi vi sono una marea di prerequisiti, perciò è consigliabile lasciar fare l'installazione al package manager della propria distribuzione. Per gli utenti Slackware c'è uno sclackbuild pronto su SBO qui e se non si ha voglia di risolvere manualmente tutte le dipendenze si può sempre usare sbotools.

Installazione del certificato

Naturalmente il certificato viene rilasciato dopo che si è data prova delle affettiva proprietà del dominio associato al certificato. Pertanto certbot dovrà installare una "ACME challenge" (ovvero un file con un nome riconoscibile) in una directory a nostra scelta dove far girare un webserver temporaneo e recuperare l'ACME via http. Se tutto va a buon fine il certificato verrà installato in /etc/letsencrypt.

Creiamo quindi la cartella dove "webroot" la ACME challenge dovrà essere salvata:

mkdir -p /path/to/webroot

Creare un virtual host apposito su apache. yourdomain.tld è il dominio al quale faremo la connessione smtp e imap/pop3:

<VirtualHost *:80>
 ServerName yourdomain.tld

DocumentRoot /path/to/webroot
 <Directory /path/to/webroot>
   Require all granted
 </Directory>
</VirtualHost>

Prepariamo uno script per installare i certificati via certbot in /usr/local/bin/my_certbot.sh: 

cat > /usr/local/bin/my_certbot.sh << __EOF__
#!/bin/sh
#

CERTBOT=/usr/bin/certbot
DOMAIN=mydomain.tld

\$CERTBOT certonly \\
 --webroot \\
 --webroot-path /path/to/webroot \\
 --preferred-challenges http-01 \\
 --key-type rsa \\
 -d \${DOMAIN} \\
 --email myemail@\${DOMAIN} \\
 --renew-by-default \\
 --agree-tos \\
 --text

# qmail cert
if [ ! -d "/var/qmail/control/certs_backup" ]; then
 mkdir -p /var/qmail/control/certs_backup
fi
cp -p /var/qmail/control/*.pem /var/qmail/control/certs_backup/
cat /etc/letsencrypt/live/\${DOMAIN}/privkey.pem /etc/letsencrypt/live/\${DOMAIN}/fullchain.pem > /var/qmail/control/servercert.pem
chown vpopmail:vchkpw /var/qmail/control/*.pem 
chmod o-r /var/qmail/control/*.pem
/usr/local/bin/qmailctl restart

# dovecot cert (you have to set the path inside 10-ssl.conf accordingly)
/usr/local/bin/dovecotctl restart
__EOF__

chmod +x /usr/local/bin/my_certbot.sh

mydomain.tld sarà usato come nome del certificato stesso. Per conoscere meglio cosa può fare certbot si può digitare:

certbot --help all

Ricordiamoci infine di settare la x flag:

chmod +x /usr/local/bin/my_certbot.sh

Possiamo quindi eseguire lo script e se non vi saranno errori avremo ottenuto il nostro certificato.

Infine settiamo un cronjob per rinnovare il certificato una volta al mese (la validità è di 3 mesi):

15 2 20 * * /usr/local/bin/my_certbot.sh >> /var/log/cron

Ricordare di disabilitare la linea di update_tmprsadh nel crontab.

Configurazione di qmail e dovecot

Per quanto riguarda qmail la private key e la fullchain devono essere unite in un unico file /var/qmail/control/servercert.pem. Questo viene fatto dallo script di cui sopra e non deve essere fatto altro.

Riguardo a dovecot invece, è sufficiente modificare il file di configurazione /usr/local/dovecot/etc/dovecot/conf.d/10-ssl.conf come segue:

#ssl_cert = </etc/ssl/certs/dovecot.pem
#ssl_key = </etc/ssl/private/dovecot.pem
ssl_cert = </etc/letsencrypt/live/yourdomain.tld/fullchain.pem
ssl_key = </etc/letsencrypt/live/yourdomain.tld/privkey.pem

Ora riavviare qmail e dovecot per abilitare il nuovo certificato.

Aggiungi un commento

Nome

e-mail (opzionale, non verrà pubblicata)

Il tuo sito web

Oggetto

Commento

Inviami una notifica via email ad ogni nuovo commento su questa pagina.

Tutti i commenti Solo le risposte a questa discussione (thread)

Invio