> For the complete documentation index, see [llms.txt](https://docs.glesys.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.glesys.com/platform/control-panel/api/real-world-use-cases/lets-encrypt-dns-01-challenge-using-glesys-api-and-dehydrated.md). # Let's Encrypt DNS-01 challenge using Glesys API and Dehydrated *** Let’s Encrypt has released a type of challenge to verify that you are truly the owner of the domain for which you have created a certificate. This challenge does not require you to use a web server for verification; instead, it is entirely based on having access to create DNS records for the domain. This guide shows how you can use the GleSYS API for this purpose. ## Setting up Dehydrated and issuing a certificate You will need to install cURL and XMLStarlet if you don’t already have these packages installed. {% tabs %} {% tab title="Debian / Ubuntu" %} For Debian and Ubuntu, use the following command to install the packages: {% code title="Command" %} ``` sudo apt-get install curl xmlstarlet ``` {% endcode %} {% endtab %} {% tab title="CentOS / AlmaLinux" %} For CentOS and AlmaLinux, use the following command (requires EPEL): {% code title="Command" %} ``` sudo yum install curl xmlstarlet ``` {% endcode %} For more information about EPEL, see the [EPEL Wiki](https://fedoraproject.org/wiki/EPEL). {% endtab %} {% endtabs %} {% hint style="warning" %} All commands you are going to run from this point must be executed as root. To avoid having to type `sudo` for every command, switch to a root login shell using `sudo -i`. All commands executed after this command will then be executed as root, until you run `exit`. {% endhint %} Next, enter the working directory `/etc/ssl/private`. {% code title="Command" %} ``` cd /etc/ssl/private/ ``` {% endcode %} If, for some reason, the directory does not exist, you create it using the following command. {% code title="Command" %} ``` mkdir /etc/ssl/private && chmod 700 /etc/ssl/private ``` {% endcode %} The next step is to create environment variables (envvars) that contain the API references. Log in to Glesys Cloud and click on your profile in the upper‑right corner. Choose **Control API access**, then click the green **Create** button. In the *Create API Key* window that opens, select the project for which the key should be created and give it a name. In this case, the description is set to *letsencrypt*.
In the image below, you can see that an API key with no permissions has been created with the ID `0JSmAiYu3l0ZGCNAOa15jWOP7OXKFIidk47RVElQ`. This key is unique to this example; the key that was generated for you will differ. To specify which IP address or domain is allowed to use the API key, click **Actions** and then select **Access**.
When you click **Add**, the changes take effect immediately. Press **Close** when you’re done.
Next, we’ll grant the API key permission to edit domains. Click **Actions** and select **Permissions**.
In the *Permissions for API-key* window that opens, select **Allowed** for the **Domain** row. Finish by clicking **Save**.
Now it’s time to start using the API key you created, and you do that by running the commands: {% code title="Multiple commands" %} ``` echo "export USER=CL12345" > /etc/ssl/private/.glesys-credentials echo "export KEY=ABCDE12345" >> /etc/ssl/private/.glesys-credentials ``` {% endcode %} * Replace `CL12345` with the identifier of the project for which you created the key. * Replace `ABCDE12345` with the key you generated. In our example, it is `0JSmAiYu3l0ZGCNAOa15jWOP7OXKFIidk47RVElQ`. Download Dehydrated together with the example configuration and our hook script from GitHub: {% code title="Multiple commands" %} ``` wget https://raw.githubusercontent.com/lukas2511/dehydrated/master/dehydrated wget https://raw.githubusercontent.com/glesys/api-docs/master/BASH/LetsencryptGlesysHook/glesys-dns-01-hook.sh wget https://raw.githubusercontent.com/glesys/api-docs/master/BASH/LetsencryptGlesysHook/config ``` {% endcode %} Edit the `config` file and enter the values as shown below (but make sure to use you're own email address). Be sure to remove the comment symbols (the `#` characters) at the beginning of each line. Also, delete the line `CONFIG_D=/etc/dehydrated/conf.d` from the file since this isn't used in this case. A complete and fully working `config` file is shown below. {% code title="/etc/ssl/private/config" %} ``` BASEDIR=/etc/ssl/private WELLKNOWN="${BASEDIR}/acme-challenges" DOMAINS_TXT="${BASEDIR}/domains.txt" CHALLENGETYPE="dns-01" HOOK="${BASEDIR}/glesys-dns-01-hook.sh" CONTACT_EMAIL=user@example.com CHAIN="yes" CA="https://acme-v02.api.letsencrypt.org/directory" ``` {% endcode %} Dehydrated uses domains.txt by default to manage the domains for which it should create or update certificates. The syntax of the file looks like this: {% code title="domains.txt syntax example" %} ``` example.net www.example.net example.se dev.example.se ``` {% endcode %} This will create two certificates. One certificate for `example.net` with the *alternative name* `www.example.net` and another certificate for `example.se` with the *alternative name* `dev.example.se`. In our example, we want to add the domain `example.com`. With the following command, we write to `domains.txt`: {% code title="Command" %} ``` echo "example.com www.example.com" > domains.txt ``` {% endcode %} You also need to set permissions on the files you created so that they can only be accessed by the root user. You do this with the following command: {% code title="Multiple commands" %} ``` chmod 700 glesys-dns-01-hook.sh dehydrated chmod 600 domains.txt config .glesys-credentials ``` {% endcode %} If this is the first time you use Dehydrated with Let's Encrypt on this server, you first need to accept Let's Encrypt's terms of service. You do this using the following command: {% code title="Command" %} ``` ./dehydrated --accept-terms --register ``` {% endcode %} This will output something similar to this: {% code title="Output" %} ``` # INFO: Using main config file /etc/ssl/private/config + Generating account key... + Registering account key with ACME server... + Fetching account URL... + Done! ``` {% endcode %} Finally, we run Dehydrated with the `-c` flag to generate the certificates for our domain: {% code title="Command" %} ``` ./dehydrated -c ``` {% endcode %} The output will look similar to this: {% code title="Output" %} ``` # INFO: Using main config file /etc/ssl/private/config + Creating chain cache directory /etc/ssl/private/chains Processing example.com with alternative names: www.example.com + Signing domains... + Creating new directory /etc/ssl/private/certs/example.com ... + Generating private key... + Generating signing request... + Requesting challenge for example.com... + Requesting challenge for www.example.com... + Responding to challenge for example.com... + Challenge is valid! + Responding to challenge for www.example.com... + Challenge is valid! + Requesting certificate... + Checking certificate... + Done! + Creating fullchain.pem... + Done! ``` {% endcode %} It’s all done now, and you can find the certificates in the directory `/etc/ssl/private/certs/`. ## Apache usage example To use the certificates with your Apache 2 web server, add the following to its configuration: {% code title="Apache2 config example" %} ``` SSLEngine on SSLCertificateFile /etc/ssl/private/certs/example.com/cert.pem SSLCertificateKeyFile /etc/ssl/private/certs/example.com/privkey.pem SSLCertificateChainFile /etc/ssl/private/certs/example.com/chain.pem ``` {% endcode %} ## Automatically renew the certificate A free SSL certificate from Let’s Encrypt is only valid for 90 days. To auto‑renew the certificate at 00:00 (midnight) every Saturday, you can use the following cron job (edit the crontab using `crontab -e`): {% code title="crontab" %} ``` 00 00 * * 06 /etc/ssl/private/dehydrated -c &>/dev/null ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.glesys.com/platform/control-panel/api/real-world-use-cases/lets-encrypt-dns-01-challenge-using-glesys-api-and-dehydrated.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.