lego Documentation

File: README.md Copy Chapter

Lego

ACME client and library for Let's Encrypt and other ACME CAs written in Go.

lego is an independent, free, and open-source project, if you value it, consider supporting it! ❤️

Everybody thinks that the others will donate, but in the end, nobody does.

So if you think that lego is worth it, please consider donating.

Features Copy Chapter

• ACME v2 RFC 8555
  • Support RFC 8737: TLS Application‑Layer Protocol Negotiation (ALPN) Challenge Extension
  • Support RFC 8738: certificates for IP addresses
  • Support RFC 9773: Renewal Information (ARI) Extension
  • Support draft-ietf-acme-profiles-00: Profiles Extension
  • Support draft-ietf-acme-dns-persist-01: Challenge for Persistent DNS TXT Record Validation
• Comes with more than 200 DNS providers
• Register with CA
• Obtain certificates, both from scratch or with an existing CSR
• Renew certificates
• Revoke certificates
• Robust implementation of ACME challenges:
  • HTTP (http-01)
  • DNS (dns-01)
  • TLS (tls-alpn-01)
• SAN certificate support
• CNAME support by default
• Custom challenge solvers
• Certificate bundling
• OCSP helper function

Installation Copy Chapter

How to install.

Usage Copy Chapter

• as a CLI
• as a library

Documentation Copy Chapter

Documentation is hosted live at https://go-acme.github.io/lego/.

DNS providers Copy Chapter

Detailed documentation is available here.

If your DNS provider is not supported, please open an issue.

If your DNS provider is not supported, please open an issue.

File: docs/archetypes/default.md Copy Chapter

title: "{{ replace .Name "-" " " | title }}" date: {{ .Date }} draft: true Copy Chapter

File: docs/content/advanced/_index.md Copy Chapter

title: "Advanced usages" date: 2019-03-03T16:39:46+01:00 draft: false weight: 4 params: menuPre: ' ' Copy Chapter

{{% children type="card" description="true" %}}

File: docs/content/advanced/accounts.md Copy Chapter

title: "Account Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 2 Copy Chapter

This section describes account operations.

List Accounts Copy Chapter

You can list all the accounts registered in your local storage:

lego accounts list

Output:

Found the following accounts:
[email protected]
├── Email: 
├── Server: https://acme-v02.api.letsencrypt.org/directory
├── Key Type: EC256
└── Path: /path/to/.lego/accounts/acme-v02.api.letsencrypt.org/[email protected]/account.json

...

Register Copy Chapter

You can register a new account by using the following command:

{{< tabs >}}
{{% tab title="Simple Registration" %}}

lego accounts register --account-id='myaccount'

{{% /tab %}}
{{% tab title="With External Account Binding" %}}

lego accounts register --account-id='myaccount' \
    --server https://example.com/ca \
    --eab \
    --eab.kid xxx \
    --eab.hmac yyy

{{% /tab %}}
{{< /tabs >}}

To know the available options, run:

lego accounts register --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-register" %}}).

Key Rollover Copy Chapter

You can change the account private key (a key rollover) by using the following command:

lego accounts keyrollover --account-id='myaccount'

To know the available options, run:

lego accounts keyrollover --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-keyrollover" %}}).

Account Recovery Copy Chapter

You can recover/import an account, to do that, you need the private key of the account.

lego accounts recover --account-id='myaccount' --private-key /path/to/private-key.pem

The account will be imported and added to .lego/accounts/.

To know the available options, run:

lego accounts recover --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-recover" %}}).

File: docs/content/advanced/archives.md Copy Chapter

title: "Archive Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 7 Copy Chapter

This section describes operations on the archives.

List Copy Chapter

You can list all the backuped accounts and certificates with the following command:

lego archives list

To know the available options, run:

lego archives list --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-archives-list" %}}).

Restore Copy Chapter

You can restore a backup of an account or a certificate with the following command:

lego archives restore

The command will ask you for the backup file to restore.

To know the available options, run:

lego archives restore --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-archives-restore" %}}).

File: docs/content/advanced/certificates.md Copy Chapter

title: "Certificate Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 1 Copy Chapter

This section describes certificate operations.

List Certificates Copy Chapter

You can list all certificates managed by lego with:

lego certificates list

Output:

Found the following certificates:
_.example.com
├── Status: this certificate is expired.
├── Domains: *.example.com, example.com
├── Expiration Date: 2026-04-08 21:02:27 +0000 UTC
├── Issuer: CN=(STAGING) Puzzling Parsnip E7,O=(STAGING) Let's Encrypt,C=US
└── Certificate Path: /path/to/.lego/certificates/_.example.com.crt

...

Revoke Certificates Copy Chapter

You can revoke existing certificates.

{{< tabs groupid="usage-examples" >}}
{{% tab title="Classic Way" %}}

Execute the following command:

lego certificates revoke --cert.name 'example.com'

{{% /tab %}}
{{% tab title="With a Configuration File" %}}

If you have the following .lego.yml configuration file:

certificates:
  foo:
    challenge: http-01
    domains:
      - example.com

And execute:

lego certificates revoke --cert.name foo

When using a configuration file, you can revoke all certificates at once:

lego certificates revoke

{{% /tab %}}
{{< /tabs >}}

To know the available options, run:

lego certificates revoke --help

Or read the [documentation]({{% ref "references/ref-flags/#lego-certificates-revoke" %}}).

File: docs/content/advanced/file-configuration.md Copy Chapter

title: "File Configuration" date: 2019-03-03T16:39:46+01:00 draft: false weight: 5 Copy Chapter

The configuration file is a way to simplify the management of multiple certificates.

Commands Copy Chapter

The configuration file is used by the following commands:

• lego
• lego certificates revoke
• lego certificates list
• lego accounts list
• lego archives list
• lego archives restore

File Location and Format Copy Chapter

The configuration file is a YAML file named .lego.yml (or .lego.yaml) placed in the current working directory.
lego will automatically find and use it when present.

You can also pass a custom path with the --config flag.

Configuration File Structure Copy Chapter

The configuration file is organized in a way that makes it easy to understand and modify.

The four main sections (servers, accounts, challenges, and certificates) are named maps:
each entry has a key (a name you choose) and a value (its configuration).

Certificates reference accounts and challenges by their name, and accounts reference servers by their name.

More information about the configuration file structure can be found in the [configuration file reference]({{% ref "references/ref-file" %}}).

Smart Defaults Copy Chapter

The configuration file applies a number of defaults to reduce verbosity:

This means the minimal configuration to obtain a certificate is just a certificate entry (and a challenge for DNS-01):

{{< tabs >}}
{{% tab title="HTTP-01" %}}

Minimal example for a certificate (Let's Encrypt).

# .lego.yml
certificates:
  my-cert:
    challenge: http-01
    domains:
      - example.com

{{% /tab %}}
{{% tab title="TLS-ALPN-01" %}}

Minimal example for a certificate (Let's Encrypt).

# .lego.yml
certificates:
  my-cert:
    challenge: tls-alpn-01
    domains:
      - example.com

{{% /tab %}}
{{% tab title="DNS-01" %}}

Minimal example for a wildcard certificate (Let's Encrypt and DNS-01 via Cloudflare).

# .lego.yml
challenges:
  my-dns:
    dns:
      provider: cloudflare

certificates:
  my-cert:
    domains:
      - example.com
      - '*.example.com'

{{% /tab %}}
{{% tab title="DNS-PERSIST-01" %}}

Please read the dedicated [documentation]({{% ref "obtain/dnspersist01" %}}).

{{% /tab %}}
{{< /tabs >}}

Archive Behavior Copy Chapter

The configuration file drives lifecycle management:

• When a certificate entry is removed, its files are archived.
• When an account entry is removed, its files are archived.
• When a server entry is removed, the server and its related accounts are archived.

More information about commands related to archives can be found in the [archives section]({{% ref "advanced/archives" %}}).

File: docs/content/advanced/hooks.md Copy Chapter

title: 'Hooks' date: 2019-03-03T16:39:46+01:00 draft: false weight: 3 Copy Chapter

This section describes how to use hooks.

There are three hooks available:

Don't hesitate to share your hook scripts with the community.

Pre-Hook Copy Chapter

This hook is executed, before the creation or the renewal, in cases where a certificate will be effectively created/renewed.

{{< tabs groupid="usage-examples" >}}
{{% tab title="Classic Way" %}}

Execute the following command:

lego run -d 'example.com' --pre-hook='./my-pre-hook.sh'

{{% /tab %}}
{{% tab title="With a Configuration File" %}}

Define the following section in your .lego.yaml file:

hooks:
  pre:
    command: './my-pre-hook.sh'

{{% /tab %}}
{{< /tabs >}}

Deploy-Hook Copy Chapter

This hook is executed after the successful creation or the renewal of a certificate.

{{< tabs groupid="usage-examples" >}}
{{% tab title="Classic Way" %}}

Execute the following command:

lego run -d 'example.com' --deploy-hook='./my-deploy-hook.sh'

{{% /tab %}}
{{% tab title="With a Configuration File" %}}

Define the following section in your .lego.yaml file:

hooks:
  deploy:
    command: './my-deploy-hook.sh'

{{% /tab %}}
{{< /tabs >}}

Post-Hook Copy Chapter

This hook is executed, after the creation or the renewal, in cases where a certificate is created/renewed, regardless of whether any errors occurred.

{{< tabs groupid="usage-examples" >}}
{{% tab title="Classic Way" %}}

Execute the following command:

lego run -d 'example.com' --post-hook='./my-post-hook.sh'

{{% /tab %}}
{{% tab title="With a Configuration File" %}}

Define the following section in your .lego.yaml file:

hooks:
  post:
    command: './my-post-hook.sh'

{{% /tab %}}
{{< /tabs >}}

Environment Variables Copy Chapter

Some details are passed through environment variables to help you with your hooks:

Use Case Copy Chapter

A typical use case is distributing the certificate for other services and reload them if necessary.
Since many programs understand PEM-formatted TLS certificates, it is relatively simple to use certificates for more than a web server.

This example script installs the new certificate for a mail server and reloads it.
Beware: this is just a starting point, error checking is omitted for brevity.

#!/bin/bash

# copy certificates to a directory controlled by Postfix
postfix_cert_dir="/etc/postfix/certificates"

# our Postfix server only handles mail for @example.com domain
if [ "$LEGO_HOOK_CERT_NAME" = "example.com" ]; then
  install -u postfix -g postfix -m 0644 "$LEGO_HOOK_CERT_PATH" "$postfix_cert_dir"
  install -u postfix -g postfix -m 0640 "$LEGO_HOOK_CERT_KEY_PATH"  "$postfix_cert_dir"

  systemctl reload postfix@-service
fi

Don't hesitate to share your hook scripts with the community.

Notes Copy Chapter

The hooks must be a system-executable: binary or script with a proper shebang (e.g. #!/bin/bash and chmod +x my-hook.sh).

There is neither subshell nor shell interpretation.
Arguments are allowed, but there is no shell-escaping support (spaces inside arguments or paths are not supported).

The hooks run in the same environment as lego, augmented with LEGO_HOOK_* variables.

Both stdout and stderr used by the hooks are merged into a single pipe.
The output is read line by line and printed to lego's own stdout.

If the hook exits with a non-zero code (or times out), lego will surface it as a failure.

File: docs/content/advanced/options.md Copy Chapter

title: "Options"
date: 2019-03-03T16:39:46+01:00
draft: false
weight: 6
aliases:

• usage/cli/options

This section describes advanced options that can be used to configure lego.

LEGO_CA_CERTIFICATES Copy Chapter

The environment variable LEGO_CA_CERTIFICATES allows to specify the path to PEM-encoded CA certificates
that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list.

Multiple file paths can be added by using : (unix) or ; (Windows) as a separator.

Example:

# On Unix system
LEGO_CA_CERTIFICATES=/foo/cert1.pem:/foo/cert2.pem

LEGO_CA_SYSTEM_CERT_POOL Copy Chapter

The environment variable LEGO_CA_SYSTEM_CERT_POOL can be used to define if the certificates pool must use a copy of the system cert pool.

Example:

LEGO_CA_SYSTEM_CERT_POOL=true

LEGO_CA_SERVER_NAME Copy Chapter

The environment variable LEGO_CA_SERVER_NAME allows to specify the CA server name used to authenticate an ACME server
with an HTTPS certificate not issued by a CA in the system-wide trusted root list.

Example:

LEGO_CA_SERVER_NAME=foo

LEGO_DISABLE_CNAME_SUPPORT Copy Chapter

By default, lego follows CNAME, the environment variable LEGO_DISABLE_CNAME_SUPPORT allows to disable this support.

Example:

LEGO_DISABLE_CNAME_SUPPORT=true

There is a Let's Encrypt blog post about the behavior of CNAMEs.

LEGO_DEBUG_CLIENT_VERBOSE_ERROR Copy Chapter

The environment variable LEGO_DEBUG_CLIENT_VERBOSE_ERROR allows to enrich error messages from some of the DNS clients.

Example:

LEGO_DEBUG_CLIENT_VERBOSE_ERROR=true

LEGO_DEBUG_DNS_API_HTTP_CLIENT Copy Chapter

⚠️ WARNING: This will expose credentials in the log output! ⚠️

Do not run this in production environments, or if you can't be sure that logs aren't accessed by third parties or tools (like log collectors).

You have been warned. Here be dragons.

The environment variable LEGO_DEBUG_DNS_API_HTTP_CLIENT allows debugging the DNS API interaction.
It will dump the full request and response to the log output.

Some DNS providers don't support this option.

Example:

LEGO_DEBUG_DNS_API_HTTP_CLIENT=true

LEGO_DEBUG_ACME_HTTP_CLIENT Copy Chapter

The environment variable LEGO_DEBUG_ACME_HTTP_CLIENT allows debug the calls to the ACME server.

Example:

LEGO_DEBUG_ACME_HTTP_CLIENT=true

File: docs/content/advanced/tips.md Copy Chapter

title: "Tips" date: 2019-03-03T16:39:46+01:00 draft: false weight: 8 Copy Chapter

This section contains some tips and tricks for using lego.

Automatic Renewal Copy Chapter

It is tempting to create a cron job (or systemd timer) to automatically renew all you certificates.

When doing so, please note that some cron defaults will cause a measurable load on the ACME provider's infrastructure.
Notably @daily jobs run at midnight.

To both counteract load spikes (caused by all lego users) and reduce subsequent renewal failures, we were asked to implement a small random delay for non-interactive renewals.[^loadspikes]
Since v4.8.0, lego will pause for up to 8 minutes to help spread the load.

You can help further, by adjusting your crontab entry, like so:

# avoid:
#@daily      /usr/bin/lego ...
#@midnight   /usr/bin/lego ...
#0 0 * * *   /usr/bin/lego ...

# instead, use a randomly chosen time:
35 3 * * *  /usr/bin/lego ...

If you use systemd timers, consider doing something similar, and/or introduce a RandomizedDelaySec:

[Unit]
Description=Renew certificates

[Timer]
Persistent=true
# avoid:
#OnCalendar=*-*-* 00:00:00
#OnCalendar=daily

# instead, use a randomly chosen time:
OnCalendar=*-*-* 3:35
# add extra delay, here up to 1 hour:
RandomizedDelaySec=1h

[Install]
WantedBy=timers.target

[^loadspikes]: See GitHub issue #1656 for an excellent problem description.

Running without root privileges Copy Chapter

The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges.
To run the CLI without sudo, you have four options:

• Use setcap 'cap_net_bind_service=+ep' /path/to/lego (Linux only)
• Pass the --http.address or/and the --tls.address option and specify a custom port to bind to. In this case you have to forward port 80/443 to these custom ports (see Port Usage).
• Pass the --http.webroot option and specify the path to your webroot folder. In this case the challenge will be written in a file in .well-known/acme-challenge/ inside your webroot.
• Pass the --dns option and specify a DNS provider.

Port Usage Copy Chapter

By default, lego assumes it is able to bind to ports 80 and 443 to solve challenges.
If this is not possible in your environment, you can use the --http.address and --tls.address options to instruct
lego to listen on that interface:port for any incoming challenges.

If you are using either of these options, make sure you setup a proxy to redirect traffic to the chosen ports.

HTTP Port: All plaintext HTTP requests to port 80 which begin with a request path of /.well-known/acme-challenge/ for the HTTP challenge[^header].

TLS Port: All TLS handshakes on port 443 for the TLS-ALPN challenge.

This traffic redirection is only needed as long as lego solves challenges. As soon as you have received your certificates you can deactivate the forwarding.

[^header]: You must ensure that incoming validation requests contains the correct value for the HTTP Host header. If you operate lego behind a non-transparent reverse proxy (such as Apache or NGINX), you might need to alter the header field using --http.proxy-header X-Forwarded-Host.

DNS Resolvers and Challenge Verification Copy Chapter

When using a DNS challenge provider (via --dns <name>), Lego tries to ensure the ACME challenge token is properly setup before instructing the ACME provider to perform the validation.

This involves a few DNS queries to different servers:

1. Determining the DNS zone and resolving CNAMEs.

   The DNS zone for a given domain is determined by the SOA record, which contains the authoritative name server for the domain and all its subdomains.
   For simple domains like example.com, this is usually example.com itself.
   For other domains (like fra.eu.cdn.example.com), this can get complicated, as cdn.example.com may be delegated to the CDN provider, which means for cdn.example.com must exist a different SOA record.

   To find the correct zone, Lego requests the SOA record for each DNS label (starting on the leaf domain, i.e. the left-most DNS label).
   If there is no SOA record, Lego requests the SOA record of the parent label, then for its parent, etc., until it reaches the apex domain[^apex].
   Should any DNS label on the way be a CNAME, it is resolved as per usual.

   In the default configuration, Lego uses the system name servers for this, and falls back to Cloudflare's DNS servers, should they be absent.

2. Verifying the challenge token.

   The _acme-challenge.<yourdomain> TXT record must be correctly installed.
   Lego verifies this by directly querying the authoritative name server for this record (as detected in the previous step).

Strictly speaking, this verification step is not necessary, but helps to protect your ACME account.
Remember that some ACME providers impose a rate limit on certain actions (at the time of writing, Let's Encrypt allows 300 new certificate orders per account per 3 hours).

There are also situations where this verification step doesn't work as expected:

• A "split DNS" setup gives different answers to clients on the internal network (Lego) vs. on the public internet (ACME server).
• With "hidden master" setups, Lego may be able to directly talk to the primary DNS server, while the _acme-challenge record might not have fully propagated to the (public) secondary servers, yet.

The effect is the same: Lego determined the challenge token to be installed correctly, while the ACME server has a different view and rejects the certificate order.

In these cases, you can instruct Lego to use a different DNS resolver, using the --dns.resolvers flag.
You should prefer one on the public internet, otherwise you might be susceptible to the same problem.

[^apex]: The apex domain is the domain you have registered with your domain registrar. For gTLDs (.com, .fyi) this is the 2nd level domain, but for ccTLDs, this can either be the 2nd level (.de) or 3rd level domain (.co.uk).