[[Vorlage(getestet, )]]

[[Vorlage(Fortgeschritten)]]

{{{#!vorlage Wissen
[:sudo: Root-Rechte]
[:Terminal: Ein Terminal öffnen]
[:Dnsmasq: DNS Records richtig setzen]
[:Apache_2.4: Aliase definieren]
[:Git: Quellcode von git herunterladen]
[:Cron: Einen Cronjob anlegen]
}}}

{{{#!vorlage Warnung
  Die Verwendung dieses Howto geschieht auf eigene Gefahr. Bei Problemen mit der Anleitung melde dies bitte in der dazugehörigen Diskussion im Forum.
}}}

[[Inhaltsverzeichnis()]]
= Vorwort =
In diesem Artikel wird beschrieben, wie man mithilfe des Scripts [github:srvrco/getssl: getSSL] von Let's Encrypt allgemein gültige Zertifikate erzeugen lassen kann. Dies ist eine Alternative zu [:certbot:] und bietet dem Nutzer mehr Kontrolle und Flexibilität. Dazu gibt es zwei verschiedene Verfahren die Zertifikate von Let's Encrypt validieren zu lassen. Das erste Verfahren basiert auf DNS-Einträgen, das zweite auf Validierung per Verifizierungscodes, die über einen Webserver veröffentlicht werden. In diesem Artikel wird letzteres beschrieben. Hierzu ist es notwendig, dass ein Webserver über das Internet erreichbar ist. Die Installation des Webservers wird vorausgesetzt. Zur Validierung der Zertifikate wird Apache2 als Webserver eingesetzt. Beispielhaft sollen Zertifikate für die Domain `example.com` erstellt werden mit den Subdomains `mail.example.com`, `shop.example.com` und `www.example.com`. Dies sind ausschließlich beispielhafte Domainnamen und sollten durch die eigenen Domains, Subdomains oder DynDNS-Adressen ersetzt werden.

= Installation =
Alle Befehle werden als Benutzer `root` ausgeführt. Dazu ist es notwendig sich im Terminal als Benutzer `root` anzumelden.

{{{#!vorlage Befehl
sudo -i
}}}

== Anlegen eines Aliases unter Apache2 ==
Als nächstes wird ein Alias definiert unter Apache2. Der Alias bewirkt, dass jeder Aufruf unabhängig von der Domain und Subdomain, soweit diese auf dem Server gehostet sind, in ein und das selbe Verzeichnis verweisen. Dazu wird eine neue Alias-Datei angelegt unter `/etc/apache2/conf-available`.

{{{#!vorlage Befehl
echo "Alias /.well-known /var/www/letsencrypt/.well-known" > /etc/apache2/conf-available/letsencrypt.conf
}}}

Der Alias soll in das Verzeichnis `/var/www/letsencrypt` verweisen. Nun wird das Verzeichnis letsenctypt angelegt mit zwei Unterverzeichnissen, die später zur Verifizierung der Domains, Subdomains oder DynDNS-Adressen zuständig sein sollen. In dem Verzeichnis acme-challenge werden sobald Domains, Subdomains oder DynDNS-Adressen verifiziert werden, Verifizierungscodes automatisch abgelegt, sodass Let's Encrypt diese abrufen kann. Dazu ist es notwendig, dass ein Zugriff aus dem Internet möglich ist. Die Verifizierungscodes werden nach Abschluss der Verifizierung entfernt.

{{{#!vorlage Befehl
mkdir -p /var/www/letsencrypt/.well-known/acme-challenge/
}}}

Man Aktiviert das Alias unter Apache2 und starten den Dienst neu.

{{{#!vorlage Befehl
a2enconf letsencrypt
systemctl reload apache2.service
}}}

Zum Testen kann man im Browser nun die Domain `example.com/.well-known` oder die Subdomains mit `mail.example.com/.well-known`, `shop.example.com/.well-known` oder `www.example.com/.well-known` aufrufen. Alle Adressen sollten im Browser das Verzeichnis acme-challenge anzeigen.

== Herunterladen von getSSL via git ==
Nun wird das Script [https://github.com/srvrco/getssl getSSL] von [https://github.com/ github] heruntergeladen und in das Verzeichnis `~/workspace` des Benutzers root gespeichert. Anschließend ist das Verzeichnis unter `~/workspace/getssl` verfügbar.

{{{#!vorlage Befehl
mkdir ~/workspace
git clone https://github.com/srvrco/getssl ~/workspace/getssl
}}}

Nun wird ein symbolischer Link erzeugt, der das Script nach `/usr/local/bin` linkt, damit getssl über die Konsole direkt aufrufbar ist.

{{{#!vorlage Befehl
ln -s ~/workspace/getssl/getssl /usr/local/bin/getssl
}}}

= getSSL Einrichten =
== getSSL und seine Parameter ==
Nun kann man mittels `getssl <Parameter>` Parameter übergeben. Hier ist eine Tabelle aller Parameter mit Bedeutung.

||<-5 rowclass="titel"> Parameter für getSSL ||
||<rowclass="kopf"<cellstyle="width: 2%">Parameter ||<: cellstyle="width: 10%"> Bedeutung ||
||<> -a, --all ||<> Überprüft alle Zertifikate auf Erneuerung ||
||<> -d, --debug ||<> Gibt Informationen zum Debuggen aus ||
||<> -c, --create ||<> Erstellt Konfigurationsdateien für die zu Zertifizierende Domain ||
||<> -f, --force ||<> Zwingt auf Erneuerung der Zertifikate, obwohl diese noch nicht abgelaufen sind ||
||<> -h, --help ||<> Zeigt diese Hilfe an ||
||<> -q, --quiet ||<> Stiller Modus, zeigt nur einen Output bei Fehlern, Bestätigung bei Erneuerung von Zertifikaten oder wenn getSSL aktualisiert wurde an ||
||<> -Q, --mute ||<> Das gleiche wie -q bzw. --quite, nur dass auch Benachrichtigungen über die erfolgreiche Erneuerung von SSL Zertifikaten verhindert wird ||
||<> -r, --revoke cert key ||<> Entzieht dem Zertifikat die Gültigkeit. Benötigt das Zertifikat als auch den Private Key ||
||<> -u, --upgrade ||<> Aktualisiert und überprüft die getSSL Dateien auf eine neuere Version ||
||<> -U, --nocheck ||<> Aktualisiert und überprüft nicht die getSSL Dateien auf eine neuere Version ||
||<> -w, --working_dir ||<> Legt das Arbeitsverzeichnis fest ||

== Konfigurationsverzeichnis erzeugen ==
Als nächstes legt man für die Domain `example.com` eine neues Konfigurationsverzeichnis an. Dies wird ohne den Parameter `-w` Standardmäßig in das Heimatverzeichnis des aktuellen Benutzers erzeugt unter `~/.getssl/<domain>`. Dieses Verzeichnis wird auch `Arbeitsverzeichnis` oder `working dir` genannt.

{{{#!vorlage Befehl
getssl -c example.com
}}}

== Konfiguration anpassen ==
Die Datei `~/.getssl/example.com/getssl.cfg` wird bearbeitet

{{{#!vorlage Befehl
nano ~/.getssl/example.com/getssl.cfg
}}}

Zu beginn der Konfigurationsdatei für die Domain example.com findet man Einstellungen für einen Server. Hier gibt es zwei Varianten. Einmal den staging Server, der Zertifikate ausstellt zum testen der Einstellungen. Die hierdurch erzeugten Zertifikate sind fake Zertifikate oder auch nicht vertrauenswürdige Zertifikate. Man kommentiert die Einstellung des Servers entsprechend ein oder aus nach unseren Bedürfnissen. Es ist jedoch Sinnvoll erst alles durch zu testen, weswegen auch der staging Server ein kommentiert ist.

{{{
# The staging server is best for testing
CA="https://acme-staging.api.letsencrypt.org"
# This server issues full certificates, however has rate limits
# CA="https://acme-v02.api.letsencrypt.org"
}}}

In dem nächsten Block wird definiert, welche E-Mail Adresse in den Zertifikaten hinterlegt wird. Welche Bit-Stärke der Primary-Key besitzen soll, wo er gespeichert wird und welches Verfahren angewendet wird. Dieser Private Key wird auch bei getSSL `Account-Key` genannt. Der Pfad zum Account-Key kann angepasst werden.
{{{
# Set an email address associated with your account - generally set at account level rather than domain.
ACCOUNT_EMAIL="webmaster@example.com"
ACCOUNT_KEY_LENGTH=4096
ACCOUNT_KEY="/etc/ssl/private/ca/ca.key"
PRIVATE_KEY_ALG="rsa"
}}}

Im nächsten Absatz wird definiert, welche Subdomains zu dem Zertifikat hinzugefügt werden sollen. Jede aufgelistete Subdomain muss später unter der Webadresse `http://<subdomain>.<domain>.<tld>/.well-known` verifiziert werden können.
{{{
# Additional domains - this could be multiple domains / subdomains in a comma separated list
# Note: this is Additional domains - so should not include the primary domain.
SANS=mail.example.com,shop.example.com,www.example.com
}}}

Nun kommt der wichtigste Block. Die Einstellung, wie Let's Encrypt die Domains für die Zertifikate erzeugt werden sollen überprüfen kann.
Dazu erzeugt das Skript Verifizierungscodes. Diese sind öffentlich abrufbar. Die Gegenstelle, also die Server von Let's Encrypt überprüfen somit, ob die Domain für die Zertifikate erzeugt werden sollen auch existiert und identisch sind mit denen, die auf den eigenen Servern von Let's Encrypt für die Domain vorgehalten sind. Diese Codes können auch auf andere Server ausgelagert werden sofern die Domain auf einen anderen Server zeigt per DNS Record.

Der erste ACL Eintrag gilt für die Domain. In dem Beispiel für `example.com`. Der zweite Eintrag in ACL würde für die Subdomain `mail.example.com` gelten, der dritte Eintrag in ACL für die Subdomain `shop.example.com`. So kann für jede Domain ein individueller Pfad angegeben werden wo die Verifizierungscode gespeichert werden sollen damit eine Verifizierung möglich ist. Sollen die Codes auf einen externen Server gespeichert werden, kann man das auch per SSH oder FTP einrichten.

Da der Server in diesem Beispiel alle Domains hostet wäre es ja unschön für jede Subdomain den gleichen Pfad (`/var/www/letsencrypt/.well-known/acme-challenge`) anzugeben. Dazu bietet uns das Skript die Möglichkeit ein Pfad für alle Domains, Subdomains und DynDNS-Adressen anzugeben. Hier bietet sich die Option `USE_SINGLE_ACL` an.

{{{
# Acme Challenge Location. The first line for the domain, the following ones for each additional domain.
# If these start with ssh: then the next variable is assumed to be the hostname and the rest the location.
# An ssh key will be needed to provide you with access to the remote server.
# If these start with ftp: then the next variables are ftpuserid:ftppassword:servername:ACL_location
# These should be of the form "/path/to/your/website/folder/.well-known/acme-challenge"
# where "/path/to/your/website/folder/" is the path, on your web server, to the web root for your domain.
# ACL=('/var/www/example.com/web/.well-known/acme-challenge'
#     'ssh:server5:/var/www/example.com/web/.well-known/acme-challenge'
#     'ftp:ftpuserid:ftppassword:example.com:/web/.well-known/acme-challenge')

ACL=('/var/www/letsencrypt/.well-known/acme-challenge')

#Enable use of a single ACL for all checks
USE_SINGLE_ACL="true"
}}}

Sobald Let's Encrypt die Domains verifizieren konnte, kann man optional angeben wo die Zertifikate gespeichert werden sollen. Hier werden die Zertifikate nur kopiert, da sie in Wirklichkeit im Arbeitsverzeichnis erstellt werden. In dem Arbeitsverzeichnis befindet sich auch das Archiv. Dort werden alle alten Zertifikate abgelegt. Das Arbeitsverzeichnis ist unter `~/.getssl/example.com` für die Domain `example.com` zu finden sofern das Verzeichnis mit dem Parameter `-w` nicht angepasst wurde.

{{{
# Location for all your certs, these can either be on the server (so full path name) or using ssh as for the ACL
DOMAIN_CERT_LOCATION="/etc/ssl/public/example.com/domain.crt"
DOMAIN_KEY_LOCATION="/etc/ssl/private/example.com/domain.key"
CA_CERT_LOCATION="/etc/ssl/public/example.com/chain.crt"
#DOMAIN_CHAIN_LOCATION="" # this is the domain cert and CA cert
#DOMAIN_KEY_CERT_LOCATION="" # this is the domain_key and domain cert
#DOMAIN_PEM_LOCATION="" # this is the domain_key. domain cert and CA cert
}}}

Nun kommt der letzte Absatz. Indem eingestellt werden kann, wie viel Tage vor Ablauf der Zertifikate die Gültigkeit erneuert wird. Hierzu dient die Option `RENEW_ALLOW`. Die auf 30 Tage vor Ablauf der Gültigkeit eingestellt ist. Werden neue Zertifikate generiert bzw. die Gültigkeit erneuert, kann man über `RELOAD_CMD` Dienste neu starten, damit diese die neuen Zertifikate aufnehmen. Im Beispiel wird der Webserver Apache2 neu gestartet.

{{{
# The command needed to reload apache / nginx or whatever you use
RELOAD_CMD="systemctl restart apache2.service"
# The time period within which you want to allow renewal of a certificate
#  this prevents hitting some of the rate limits.
RENEW_ALLOW="30"
}}}

== Beispiel Konfiguration für die Domain example.com ==
Nun noch einmal die ganze Konfiguration für die Domain example.com.

{{{
# Uncomment and modify any variables you need
# see https://github.com/srvrco/getssl/wiki/Config-variables for details
#
# The staging server is best for testing
CA="https://acme-staging.api.letsencrypt.org"
# This server issues full certificates, however has rate limits
# CA="https://acme-v01.api.letsencrypt.org"

#AGREEMENT="https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf"

# Set an email address associated with your account - generally set at account level rather than domain.
ACCOUNT_EMAIL="webmaster@example.com"
ACCOUNT_KEY_LENGTH=4096
ACCOUNT_KEY="/etc/ssl/private/ca/ca.key"
PRIVATE_KEY_ALG="rsa"

# Additional domains - this could be multiple domains / subdomains in a comma separated list
# Note: this is Additional domains - so should not include the primary domain.
SANS=mail.example.com,shop.example.com,www.example.com

# Acme Challenge Location. The first line for the domain, the following ones for each additional domain.
# If these start with ssh: then the next variable is assumed to be the hostname and the rest the location.
# An ssh key will be needed to provide you with access to the remote server.
# If these start with ftp: then the next variables are ftpuserid:ftppassword:servername:ACL_location
# These should be of the form "/path/to/your/website/folder/.well-known/acme-challenge"
# where "/path/to/your/website/folder/" is the path, on your web server, to the web root for your domain.
# ACL=('/var/www/example.com/web/.well-known/acme-challenge'
#      'ssh:server5:/var/www/example.com/web/.well-known/acme-challenge'
#      'ftp:ftpuserid:ftppassword:example.com:/web/.well-known/acme-challenge')

ACL=('/var/www/letsencrypt/.well-known/acme-challenge')

#Enable use of a single ACL for all checks
USE_SINGLE_ACL="true"

# Location for all your certs, these can either be on the server (so full path name) or using ssh as for the ACL
DOMAIN_CERT_LOCATION="/etc/ssl/public/example.com/domain.crt"
DOMAIN_KEY_LOCATION="/etc/ssl/private/example.com/domain.key"
CA_CERT_LOCATION="/etc/ssl/public/example.com/chain.crt"
#DOMAIN_CHAIN_LOCATION="" # this is the domain cert and CA cert
#DOMAIN_KEY_CERT_LOCATION="" # this is the domain_key and domain cert
#DOMAIN_PEM_LOCATION="" # this is the domain_key. domain cert and CA cert

# The command needed to reload apache / nginx or whatever you use
RELOAD_CMD="service apache2 reload"
# The time period within which you want to allow renewal of a certificate
#  this prevents hitting some of the rate limits.
RENEW_ALLOW="30"
}}}

== Zertifikate erzeugen ==
Nachdem nun die Konfiguration für eine Domain abgeschlossen wurde kann man sich von getSSL die Zertifikate erzeugen lassen. Dazu verwendet man folgenden Befehl.

{{{#!vorlage Befehl
getssl -f example.com
}}}

Ähnliche Meldungen sollten im Terminal zu sehen sein. Der Output wurde generiert für eine Domain, deren Zertifikate noch gültig waren, allerdings einer Erneuerung erzwungen wurde.

{{{
Registering account
Verify each domain
Verifying example.com
example.com is already validated
Verifying mail.example.com
mail.example.comis already validated
Verifying shop.example.com
shop.example.com is already validated
Verifying www.example.com
www.example.com is already validated
Verification completed, obtaining certificate.
Certificate saved in /root/.getssl/example.com/example.com.crt
The intermediate CA cert is in /root/.getssl/example.com/chain.crt
copying domain certificate to /etc/ssl/public/example.com/domain.crt
copying private key to /etc/ssl/private/example.com/domain.key
copying CA certificate to /etc/ssl/public/example.com/chain.crt
reloading SSL services
example.com - certificate installed OK on server
certificate obtained for example.com
}}}

= Automatische Aktualisierung =
Das Script kann automatisch ausgeführt werden über `systemd`, per `timer` unit.

Um mit systemd ein Programm nach Zeitplan auszuführen, werden zwei Datei benötigt. Einmal eine `.service` Datei, die ein anderes Programm startet und eine `.timer` Datei, in der der Zeitplan enthalten ist, wann die `.service` Datei gestartet werden soll.

Beide Dateien sind unter `/etc/systemd/system` anzulegen.

`/etc/systemd/system/lets-encrypt.service`

{{{
[Unit]
Description=Generate Let's Encrypt certificates
Requires=apache2.service network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/getssl --all --debug
}}}

`/etc/systemd/system/lets-encrypt.timer`

{{{
[Unit]
Description=Daily update for let's encrypt certificate

[Timer]
OnCalendar=*-*-* 00:00:00

[Install]
WantedBy=multi-user.target
}}}

Nachdem die Dateien angelegt wurden, muss systemd alle Unit-Files neu einlesen. Dies wird mit mit folgendem Befehl erreicht.
{{{#!vorlage Befehl
systemd daemon-reload
}}}

Anschließen kann der `systemd-timer` aktiviert werden.
{{{#!vorlage Befehl
systemctl enable --now lets-encrypt.timer
}}}

Eine Übersicht über alle systemd-timer, deren letzte, zukünftige Ausführung wird wie folgt ausgegeben.
{{{#!vorlage Befehl
systemctl list-timers
}}}

= Links =

== extern ==
* [https://letsencrypt.org/de/docs/client-options/ ACME Client Implementierungen] {de}



#tag: Howto