lcfg-x509 with letsencrypt

LCFG configuration

To configure lcfg-x509 with letsencrypt support...

prior to the inclusion of either

and run om updaterpms run

This will install:

  • lcfg-x509 with letsencrypt support
  • dehydrated - the letsencrypt client used by the component

Next, add the following to your profile:

#include <lcfg/options/apacheconf-x509-letsencrypt.h>

and set:

!x509.catype_TAG   mSET(letsencrypt)
... for any configured x509 certificate for which you would like to obtain a letsencrypt certificate.

The apacheconf-x509-letsencrypt.h header configures the well-known directory and makes it available via apache (from all virtual hosts) - this is required for certificate acquisition from letsencrypt. The directory is created by lcfg-x509 as part of the configure method, but only when one or more certificates have a catype of 'letsencrypt'.

A bit more detail on the well-known exchange: when requesting a certificate for site '', must be visible to the outside world - the dehydrated client writes to this directory, which proves to letsencrypt that it has ownership over this domain. If you have a local firewall configured, make sure that suitable holes exist.

Using the staging environment

If you are bringing up a new service, it might be wise to use the lets encrypt staging environment so as not to fall foul of strict rate limiting. This can be done using the lcfg-x509 component, either by setting the following resource:

!x509.le_ca mSET(

... or, if using <lcfg/options/apacheconf-x509-letsencrypt.h>:

...before inclusion of the header.


The letsencrypt support in lcfg-x509 has been largely tested using dehydrated defaults.

man lcfg-x509 has some documentation

dehydrated itself has documentation in the directory /usr/share/doc/dehydrated-0.4.0/

dehydrated logs to /var/lcfg/log/x509

If you see messages of the type "ERROR: WELLKNOWN directory doesn't exist...", make sure that:

  1. x509.le_wellknown is set to an appropriate directory
  2. run om x509 configure.

The /well-known/acme-challenge/ directory must be accessible over HTTP from the outside world in order to obtain letsencrypt certificates. This can fail for a number of different reasons:

  1. Local firewall blocking access
  2. Any kind of redirection affecting the serving of this directory, e.g. cosign

If you are affected by (2) above, many of our apache servers include default HTTP → HTTPS redirection (implemented with the Redirect directive) which can easily be modified to exclude all requests beginning with /.well-known with a change along these lines:

 -apacheconf.vhostline_TAG_0    Redirect / https://<%apacheconf.vhostname_TAG%>/
 +apacheconf.vhostline_TAG_0    RedirectMatch ^/(?!\.well-known)(.*)$ https://<%apacheconf.vhostname_TAG%>/$1$2

Most of the letsencrypt configuration will apply to all letsencrypt certificates on a given host, so you cannot set different configuration options for different certificates, (e.g. they will use the same keysize, configuration directories, etc.) Options such as certificate names are obviously unique, and different certificates are maintained separately within the dehydrated directory. If you require a more fine-grained configuration, please submit a bug report (or, even better, a bug report with a patch).

-- TobyBlake - 18 Jul 2018

Topic revision: r7 - 28 Aug 2019 - 13:38:33 - TobyBlake
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies