ACME For Domains

How to Enable Let's Encrypt and Install an SSL for a Domain

DirectAdmin can automatically issue and renew TLS certificates using the ACME protocol for user domains and subdomains. Popular certificate providers like Let's Encrypt and ZeroSSL can be used to get TLS certificates for free.

The ACME support is controlled by the letsencrypt configuration option in the directadmin.conf file. It is enabled by default.

When this feature is enabled, users will be able to configure ACME settings in their panel in User Level -> SSL Certificates -> ACME settings.

When ACME is enabled for a domain, the certificates will be issued and renewed automatically once every 24 hours. It is also possible to trigger on-demand certificate provisioning.

LEGO: Remote DNS Providers with Let's Encrypt

LEGO is a LetsEncrypt client and ACME library written in Go, hence the name LEGO. This useful library facilitates the use of 3rd-party, remote DNS providers with Let's Encrypt by utilizing those providers' APIs to complete domain validation checks via DNS, thus permitting the issuance of LE SSLs for domains using remote DNS.

Wildcard certificates for LetsEncrypt require DNS confirmation. If you're running at some remote DNS provider that is not currently supported by the Multi-Server Setup, then this tool lets you use wildcard certs with those DNS providers.

This document will use Cloudflare as the example remote DNS provider.

INSTALL

Ensure that wildcard domain SSL certificate support via Let's Encrypt is enabled via dns_ttl=1 in the directadmin.conf.

GUI USAGE

This feature is only available in the Evolution Skin as of September 2024. You may access it via the User Level » SSL Certificates » Manage ACME DNS Providers Sample URI for the Enhanced GUI: CMD_SSL?action=dnsprovider&domain=domain.com&type=domain

It can be used for both the Manually requested LetsEncrypt / ZeroSSL, as well as the Use the best match certificate (aka: Auto SSL and Use the server's certificate).

It's no longer nessecary to have this setup at the same time as the request of the certificate. Simply the existence of the created dnsprovider.conf file will be used anytime the letsencrypt.sh script is called.

You can then pick a new DNS provider, say "CloudFlare", and enter your user/key + extra bits, as specified by that provider.

We'll be adding fixes/improvements as we go, so ensure you have the updated script if you encounter any issues!

OBTAINING THE CLOUDFLARE_DNS_API_TOKEN FROM CLOUDFLARE

CloudFlare does not recommend using the Global API Key (CLOUDFLARE_API_KEY), and now recommends using the CLOUDFLARE_DNS_API_TOKEN, as it can be restricted by zones and IP addresses. There is no need to specify the CLOUDFLARE_EMAIL when using the CLOUDFLARE_DNS_API_TOKEN.

To create the CLOUDFLARE_DNS_API_TOKEN token:

• login to your CloudFlare account
• click your "Profile" at the top-right, click "Profile" in the drop-down.
• Select the API Tokens option on the left.
• Click "Create Token", and pick Use Template for the Edit zone DNS option.
• Set:
  • Permission: Zone : DNS : Edit
  • Zone Resources: Include : Specific Zone : select the domain to allow DirectAdmin to edit.
  • Client IP Address Filtering: If you wish to restrict the token to an IP, enter your server IP address, which may differ from your Domain's IP. The generated token is to be used along with the CLOUDFLARE_DNS_API_TOKEN token, when setting up the DnsProvider in DirectAdmin.

You plan to create a Reseller or Global level dnsprovider setup for User Domains to inherit, you can use a different Zone Resources value of All Zones, or anything applicable to what this token should be editing.

INHERIT DNS PROVIDER

An Admin/Creator can set up 2 possible inherit files:

• Global: /usr/local/directadmin/data/admin/dnsprovider.conf
• Creator: /usr/local/directadmin/data/users/resellerbob/dnsprovider.conf

Should either of these exist, where creator=resellerbob is in the given User's user.conf, they'll be included in the list of dnsproviders["data"] output as:

dnsproviders["data"]["inherit-creator"]
dnsproviders["data"]["inherit-global"]

where each would still have the correct "Name", but the type is prefixed, e.g., dnsproviders["data"]["inherit-creator"]["name"] = "Inherit Creator : Cloudflare"

"Inherit Creator : " or "Inherit Global" would be prefixed beside the name from the used provider, Cloudflare in this example, for that inherited dnsprovider.conf type.

The inherit-creator or inherit-global arrays will have an empty credentials array, and zero credentials are allowed to be passed if the master (including inherited configs) have zero creds.

If the "dnsprovider" is empty (nothing picked yet), check for:
dnsproviders["settings"]["default"]
to know which selection should be used by default. It should be either local, inherit-creator, or inherit-global.

The Global/Creator dnsprovider.conf files may contain one of the following:

default=inherit-creator
default=inherit-global
default=local

which is what specifies the default value for a User to have pre-selected.

USER / DOMAIN DATA FILES AND CONTENT

When a selection is made by a User (or via a creator's default choice), the domain's DNS settings will be stored in: /usr/local/directadmin/data/users/USERNAME/domains/DOMAIN.COM.dnsprovider

Sample data:

dnsprovider=cloudflare
CLOUDFLARE_DNS_API_TOKEN=sdgsd7681afn

OR:

dnsprovider=inherit-creator

OR:

dnsprovider=inherit-global

The data from any of the 3 possible file locations is loaded into the ENV and passed onto the letsencrypt.sh script. Eg: If the domain.com.dnsprovider contains an inherit type, the letsencrypt.sh will go find the respective dnsprovider.conf.

Automatically redirect domain/pointer to SSL

Since a lot of domains use .htaccess for SSL redirection this feature is disabled by default to prevent loops. However, DirectAdmin SSL redirection comes directly from webserver so it will be faster than using .htaccess. Each user may individually enable redirection under:

User Level -> Domain Setup -> domain.com -> Force Redirect

Available redirection options:

• www
• non-www
• none

Pointers will also use this setting. You may find more information about this feature here.

Create new User with ssl on, but with ssl off for the new domain

In some cases, you might want to create a new User and allow that User the ability to use SSL and SSL certificates, but don't want it turned on by default for the domain, to keep the VirtualHost count down.

This can be done with the user_create_post_confirmed.sh script.

So create /usr/local/directadmin/scripts/custom/user_create_post_confirmed.sh with code:

#!/bin/sh
CONF=/usr/local/directadmin/data/users/$username/domains/$domain.conf
if [ -s $CONF ]; then
   perl -pi -e 's/ssl=ON/ssl=OFF/' $CONF
   echo "action=rewrite&value=httpd&user=$username" >> /usr/local/directadmin/data/task.queue
fi
exit 0;

and make it executable:

chmod 755 /usr/local/directadmin/scripts/custom/user_create_post_confirmed.sh

This will shut off SSL for the new domain after the User is created, and rewrite their httpd.conf file up to 1 minute later via task.queue (in case you're wondering why the 443 VH might still be added immediately after User creation).

Enforcing ssl=ON for all Users, Resellers and their packages

For the modern age, websites should be using SSL for their websites. This guide provides a means to enforce enabling it for all Users/Resellers, their domains, and the packages used to create them.

First, we'll setup the enforcement for actions in the GUI.

Saving a package

Create the directory and script:

/usr/local/directadmin/scripts/custom/package_write_pre/enforce_ssl.sh

with code:

#!/bin/sh
if [ "${ssl}" = "OFF" ]; then
   echo "SSL must be enabled";
   exit 1;
fi
exit 0;

Account creation/modification

Create both:

/usr/local/directadmin/scripts/custom/user_create_pre/enforce_ssl.sh

and

/usr/local/directadmin/scripts/custom/user_modify_pre/enforce_ssl.sh

with the same code as above.
Chmod all scripts to 755:

chmod 755 /usr/local/directadmin/scripts/custom/*/enforce_ssl.sh

Change all Users, domains, and packages to use ssl=ON:

cd /usr/local/directadmin/data
perl -pi -e 's/^ssl=OFF/ssl=ON/' users/*/user.conf
perl -pi -e 's/^ssl=OFF/ssl=ON/' users/*/domains/*.conf
perl -pi -e 's/^ssl=OFF/ssl=ON/' users/*/reseller.conf
perl -pi -e 's/^ssl=OFF/ssl=ON/' admin/packages/*.pkg
perl -pi -e 's/^ssl=OFF/ssl=ON/' users/*/packages/*.pkg

Follow up with a rewrite of the webserver configs to use the values:

cd /usr/local/directadmin/custombuild
./build rewrite_confs

Let's Encrypt weekly domain rate limit

LetsEncrypt has a rate limit of 50 requests per week, per main domain. Read more here

DirectAdmin has this directadmin.conf option:

letsencrypt_max_requests_per_week=200

The 50 LE limit is only requests that make it that far. The letsencrypt.sh script has some prechecks which could fail before the LE limit, so the 200 limit is used to err on the side of caution to reach the actual LE 50 limits.

In effect, the letsencrypt_max_requests_per_week=200 value is mainly for a last-resort limit on "far too many requests", vs trying to predict the true LE 50 limit.

DISABLE

You can fully disable the DA limit enforcement by setting:

/usr/local/directadmin/directadmin set letsencrypt_max_requests_per_week 0
service directadmin restart