<!-- |Goal| Configure the functional software for SSL certificate management.| |----|-----------| |Rationale| Enable creation and maintenance of (wild card) SSL certificates.| |Nuance| Although Dehydrated is used in this guide, Certbot is another, more commonly applied tool that could be considered too (but it does not support wild card certification out of the box as easily as Dehydrated).| ## Procedure --> <ol> <li> <p>Create a directory to be used as Dehydrated's default:</p> <pre><code class="language-shell">mkdir /etc/dehydrated</code></pre> </li> <li> <p>Download THE DEFAULT lexicon implementation hook file USED FOR DNS API communication:</p> <pre><code class="language-shell">curl https://raw.githubusercontent.com/AnalogJ/lexicon/master/examples/dehydrated.default.sh -o /etc/dehydrated/lexicon_hooks.reference.sh</code></pre> </li> <li> <p>Copy the default hook file and take ownership of the copy to enable specific DNS registrar (e.g. Transip) API configuration - replacing <code><specific-dns-registar></code> with the name of your specific DNS registar:</p> <pre><code class="language-shell">cp /etc/dehydrated/lexicon_hooks.reference.sh /etc/dehydrated/lexicon_hooks.<specific-DNS-registar>.sh chmod u+x /etc/dehydrated/lexicon_hooks.<specific-DNS-registar>.sh</code></pre> </li> <li> <p>Obtain the specific API credentials required by your specific DNS registrar.</p> <blockquote> <blockquote> <blockquote> <p>The method of obtaining the rsa key differs per DNS registrar!</p> </blockquote> </blockquote> <p>E.g. for TransIP:</p> <ol> <li>Visit <a href="https://www.transip.nl/cp/account/api/">API key</a>,</li> <li>Generate the key, a. Label the key, b. Check <code>☑ Whitelisted IP</code>, c. Provide your IP address.</li> <li>Store it as <code>/tmp/transip-api.key</code></li> <li>Convert the file to the dehydrated required RSA format: <pre><code class="language-shell">openssl rsa -in /tmp/transip-api.key -out /etc/dehydrated/transip-rsa.key</code></pre></li> </ol> </blockquote> </li> <li> <p>Edit <code>/etc/dehydrated/lexicon_hooks.<specific-DNS-registar>.sh</code> to configure your specific DNS registrar's API settings - replacing <code><specific-dns-registar></code> with the name of your specific DNS registar:</p> <blockquote> <blockquote> <blockquote> <p>DNS API settings differ per DNS registrar. Refer to <em>your</em> DNS registrar's documentation for <em>their specific</em> API settings!</p> </blockquote> </blockquote> <p>E.g. for TransIP:</p> <p>Configure login-credentials and timeout to comply with Transip requirements - replacing <code><username></code> with your TransIP username:</p> <pre><code class="language-diff">set -e set -u set -o pipefail - export PROVIDER=${PROVIDER:-"cloudflare"} + export PROVIDER="transip" + export LEXICON_TRANSIP_USERNAME="<username>" + export LEXICON_TRANSIP_API_KEY="/etc/dehydrated/transip-rsa.key" lexicon $PROVIDER create ${DOMAIN} TXT --name="_acme-challenge.${DOMAIN}." --content="${TOKEN_VALUE}" - sleep 30 + sleep 300</code></pre> </blockquote> </li> <li> <p>Create a new default config in <code>/etc/dehydrated/config</code> using the staging API for testing - replacing <code><specific-dns-registar></code> with the name of your specific DNS registar:</p> <pre><code class="language-diff">+ # Defining the API endpoint + CA="https://acme-staging-v02.api.letsencrypt.org/directory" + + # Use the new (recommended) DNS-01 challenge implementation (has wildcard supported). + CHALLENGETYPE="dns-01" + + # Tell dehydrated to use the lexicon implementation for automatically managing DNS records + HOOK="/etc/dehydrated/lexicon_hooks.<specific-DNS-registar>.sh"</code></pre> </li> <li> <p>Create a list of domains you want request SSL certificates in <code>/etc/dehydrated/domains.txt</code> - replacing <code>example.org</code> with your domains (add a newline per domain:</p> <pre><code class="language-diff">+ example.org *.example.org</code></pre> </li> <li> <p>Register to the staging API of Letsencrypt:</p> <pre><code class="language-shell">/usr/local/bin/dehydrated --register --accept-terms</code></pre> </li> <li> <p>Run the dehydrated script to see if the dehydrated is set up correctly:</p> <pre><code class="language-shell">PATH=$PATH:/usr/local/bin dehydrated --cron</code></pre> <blockquote> <blockquote> <blockquote> <p>This command will take some time due to the time out on DNS changes! <br />Correct operation will return <code>+ Done!</code></p> </blockquote> </blockquote> </blockquote> </li> <li> <p>Edit <code>/etc/dehydrated/config</code> to use the production API:</p> <pre><code class="language-diff"># Defining the API endpoint - CA="https://acme-staging-v02.api.letsencrypt.org/directory" + CA="https://acme-v02.api.letsencrypt.org/directory"</code></pre> </li> <li> <p>Register to the production API of Letsencrypt:</p> <pre><code class="language-shell">/usr/local/bin/dehydrated --register --accept-terms</code></pre> </li> <li> <p>Rerun the dehydrated script to get the wildcard certificates from the production API of Letsencrypt:</p> <pre><code class="language-shell">PATH=$PATH:/usr/local/bin dehydrated --cron --force</code></pre> <blockquote> <blockquote> <blockquote> <p>This command will take some time due to the time out on DNS changes!</p> </blockquote> </blockquote> </blockquote> </li> <li> <p>Append crontab for automatic renewal of the certificates by issuing <code>crontab -e</code>:</p> <pre><code class="language-diff"> # For more information see the manual pages of crontab(5) and cron(8) # + PATH=$PATH:/bin:/usr/local/bin:/usr/bin # m h dom mon dow command + @daily bash /usr/local/bin/dehydrated --cron > /var/log/dehydrated.log 2>&1 + @reboot bash /usr/local/bin/dehydrated --cron > /var/log/dehydrated.log 2>&1</code></pre> </li> </ol>