lcfg-x509 with letsencrypt

LCFG configuration

lcfg-x509 has had support for obtaining certificates from letsencrypt since version 0.1.2.

The x509 component can be installed on any machine via the inclusion of:


lcfg-x509 includes dehydrated - a shell based letsencrypt client used by the componentĚ

Next, add the following to your profile:

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

Now 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 one of the apacheconf-x509-letsencrypt.h headers:

...before inclusion of the header.

Using the dns-01 challenge type (probably Informatics only)

There is support for Informatics hosts to use the dns-01 challenge type when acquiring certificates - this allows certificate acquisition without running a web server and without the need to open firewall holes. This can be done by using the dice-level header in the following way:

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

It could be used for non-Informatics hosts providing the following are in place:

  • a scriptable interface for DNS updates
  • fast propagation of DNS updates
  • a hook script to drive DNS updates (one is provided with the component for Informatics)

The implementation of this within Informatics is described here.

Cosign-protected sites using letsencrypt

Lets Encrypt certificates are not trusted by the Informatics cosign service, so certificates for this should be obtained in the usual way, using lcfg-x509/sixkts. This means it is likely a cosign-protected web site will require two certificates - one for the front end (letsencrypt) and a separate one for the backend cosign communication (sixkts).


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.6.5/

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).

Useful links

Sample configuration

Below is some sample LCFG configuration to obtain a letsencrypt certificate. Uncomment the bits you require.

Any configuration required for other components (e.g. apacheconf) is beyond the scope of this document.

/* Location for certificates ... */
#define _X509_PATH_CERT /etc/pki/tls/certs
#include <dice/options/x509-client.h>

/* Use the following for initial testing, remove to obtain a proper certificate ... */

/* Using the dns-01 challenge is recommended where possible - currently DICE-only ... */
/* (if you don't use this, you will need to make /.well-known/acme-challenge/ directory accessible (see above) */

#include <dice/options/apacheconf-x509-letsencrypt.h>
/* or <lcfg/options/apacheconf-x509-letsencrypt.h> for non-DICE */

/* Uncomment one of the following... */
/* Note: in these examples, the files will be created with the name "name.{crt,key,chain}" in _X509_PATH_CERT (see above)
   MAKE SURE this won't overwrite files already in use - if this might be the case change the tag name, for example:
   The first argument to _X509_SERVICE and _X509_SERVICE_SERVER is an LCFG tag */
/* Obtain a certificate for name.<%profile.domain%> */
/* _X509_SERVICE(name) */
/* Or, if you want to specify either the LCFG tag name, or the certificate name yourself... */
/* _X509_SERVICE_SERVER(name,myname.fully.qualified.domain) */

/* If your certificate requires any Subject Alternative Names... */
/* !x509.lealtnames_name mADD(altname.fully.qualified.domain)

!x509.catype_name mSET(letsencrypt)

/* if you need to set ownership of the certificate files... */ 
/* _X509_SERVICE_OWNERSHIP(name,apache,apache) */

/* If you need to restart a component when a new certificate is required... */
/* !x509.component_name mADD(apacheconf) */

-- TobyBlake - 04 Feb 2020

Topic revision: r16 - 15 Jun 2020 - 15:35:20 - 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