Options :: Let’s Encrypt client and ACME library written in Go.
Author: Lego Team
Description: This page describes various command line options.
Date: 2019-03-03T16:39:46+01:00

# Options

## Usage

    NAME:
       lego - Let's Encrypt client written in Go

    USAGE:
       lego [global options] command [command options]

    COMMANDS:
       run      Register an account, then create and install a certificate
       revoke   Revoke a certificate
       renew    Renew a certificate
       dnshelp  Shows additional help for the '--dns' global option
       list     Display certificates and accounts information.
       help, h  Shows a list of commands or help for one command

    GLOBAL OPTIONS:
       --domains value, -d value [ --domains value, -d value ]      Add a domain to the process. Can be specified multiple times.
       --server value, -s value                                     CA hostname (and optionally :port). The server certificate must be trusted in order to avoid further modifications to the client. (default: "https://acme-v02.api.letsencrypt.org/directory") [$LEGO_SERVER]
       --accept-tos, -a                                             By setting this flag to true you indicate that you accept the current Let's Encrypt terms of service. (default: false)
       --email value, -m value                                      Email used for registration and recovery contact. [$LEGO_EMAIL]
       --csr value, -c value                                        Certificate signing request filename, if an external CSR is to be used.
       --eab                                                        Use External Account Binding for account registration. Requires --kid and --hmac. (default: false) [$LEGO_EAB]
       --kid value                                                  Key identifier from External CA. Used for External Account Binding. [$LEGO_EAB_KID]
       --hmac value                                                 MAC key from External CA. Should be in Base64 URL Encoding without padding format. Used for External Account Binding. [$LEGO_EAB_HMAC]
       --key-type value, -k value                                   Key type to use for private keys. Supported: rsa2048, rsa3072, rsa4096, rsa8192, ec256, ec384. (default: "ec256")
       --filename value                                             (deprecated) Filename of the generated certificate.
       --path value                                                 Directory to use for storing the data. (default: "./.lego") [$LEGO_PATH]
       --http                                                       Use the HTTP-01 challenge to solve challenges. Can be mixed with other types of challenges. (default: false)
       --http.port value                                            Set the port and interface to use for HTTP-01 based challenges to listen on. Supported: interface:port or :port. (default: ":80")
       --http.delay value                                           Delay between the starts of the HTTP server (use for HTTP-01 based challenges) and the validation of the challenge. (default: 0s)
       --http.proxy-header value                                    Validate against this HTTP header when solving HTTP-01 based challenges behind a reverse proxy. (default: "Host")
       --http.webroot value                                         Set the webroot folder to use for HTTP-01 based challenges to write directly to the .well-known/acme-challenge file. This disables the built-in server and expects the given directory to be publicly served with access to .well-known/acme-challenge
       --http.memcached-host value [ --http.memcached-host value ]  Set the memcached host(s) to use for HTTP-01 based challenges. Challenges will be written to all specified hosts.
       --http.s3-bucket value                                       Set the S3 bucket name to use for HTTP-01 based challenges. Challenges will be written to the S3 bucket.
       --tls                                                        Use the TLS-ALPN-01 challenge to solve challenges. Can be mixed with other types of challenges. (default: false)
       --tls.port value                                             Set the port and interface to use for TLS-ALPN-01 based challenges to listen on. Supported: interface:port or :port. (default: ":443")
       --dns value                                                  Solve a DNS-01 challenge using the specified provider. Can be mixed with other types of challenges. Run 'lego dnshelp' for help on usage.
       --dns.disable-cp                                             (deprecated) use dns.propagation-disable-ans instead. (default: false)
       --dns.propagation-disable-ans                                By setting this flag to true, disables the need to await propagation of the TXT record to all authoritative name servers. (default: false)
       --dns.propagation-rns                                        By setting this flag to true, use all the recursive nameservers to check the propagation of the TXT record. (default: false)
       --dns.propagation-wait value                                 By setting this flag, disables all the propagation checks of the TXT record and uses a wait duration instead. (default: 0s)
       --dns.resolvers value [ --dns.resolvers value ]              Set the resolvers to use for performing (recursive) CNAME resolving and apex domain determination. For DNS-01 challenge verification, the authoritative DNS server is queried directly. Supported: host:port. The default is to use the system resolvers, or Google's DNS resolvers if the system's cannot be determined.
       --http-timeout value                                         Set the HTTP timeout value to a specific value in seconds. (default: 0)
       --tls-skip-verify                                            Skip the TLS verification of the ACME server. (default: false)
       --dns-timeout value                                          Set the DNS timeout value to a specific value in seconds. Used only when performing authoritative name server queries. (default: 10)
       --pem                                                        Generate an additional .pem (base64) file by concatenating the .key and .crt files together. (default: false)
       --pfx                                                        Generate an additional .pfx (PKCS#12) file by concatenating the .key and .crt and issuer .crt files together. (default: false) [$LEGO_PFX]
       --pfx.pass value                                             The password used to encrypt the .pfx (PCKS#12) file. (default: "changeit") [$LEGO_PFX_PASSWORD]
       --pfx.format value                                           The encoding format to use when encrypting the .pfx (PCKS#12) file. Supported: RC2, DES, SHA256. (default: "RC2") [$LEGO_PFX_FORMAT]
       --cert.timeout value                                         Set the certificate timeout value to a specific value in seconds. Only used when obtaining certificates. (default: 30)
       --overall-request-limit value                                ACME overall requests limit. (default: 18)
       --user-agent value                                           Add to the user-agent sent to the CA to identify an application embedding lego-cli
       --help, -h                                                   show help

    NAME:
       lego run - Register an account, then create and install a certificate

    USAGE:
       lego run [command options]

    OPTIONS:
       --no-bundle                               Do not create a certificate bundle by adding the issuers certificate to the new certificate. (default: false)
       --must-staple                             Include the OCSP must staple TLS extension in the CSR and generated certificate. Only works if the CSR is generated by lego. (default: false)
       --not-before value                        Set the notBefore field in the certificate (RFC3339 format)
       --not-after value                         Set the notAfter field in the certificate (RFC3339 format)
       --private-key value                       Path to private key (in PEM encoding) for the certificate. By default, the private key is generated.
       --preferred-chain value                   If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used.
       --profile value                           If the CA offers multiple certificate profiles (draft-aaron-acme-profiles), choose this one.
       --always-deactivate-authorizations value  Force the authorizations to be relinquished even if the certificate request was successful.
       --run-hook value                          Define a hook. The hook is executed when the certificates are effectively created.
       --run-hook-timeout value                  Define the timeout for the hook execution. (default: 2m0s)
       --help, -h                                show help

    NAME:
       lego renew - Renew a certificate

    USAGE:
       lego renew [command options]

    OPTIONS:
       --days value                              The number of days left on a certificate to renew it. (default: 30)
       --ari-disable                             Do not use the renewalInfo endpoint (draft-ietf-acme-ari) to check if a certificate should be renewed. (default: false)
       --ari-wait-to-renew-duration value        The maximum duration you're willing to sleep for a renewal time returned by the renewalInfo endpoint. (default: 0s)
       --reuse-key                               Used to indicate you want to reuse your current private key for the new certificate. (default: false)
       --no-bundle                               Do not create a certificate bundle by adding the issuers certificate to the new certificate. (default: false)
       --must-staple                             Include the OCSP must staple TLS extension in the CSR and generated certificate. Only works if the CSR is generated by lego. (default: false)
       --not-before value                        Set the notBefore field in the certificate (RFC3339 format)
       --not-after value                         Set the notAfter field in the certificate (RFC3339 format)
       --preferred-chain value                   If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used.
       --profile value                           If the CA offers multiple certificate profiles (draft-aaron-acme-profiles), choose this one.
       --always-deactivate-authorizations value  Force the authorizations to be relinquished even if the certificate request was successful.
       --renew-hook value                        Define a hook. The hook is executed only when the certificates are effectively renewed.
       --renew-hook-timeout value                Define the timeout for the hook execution. (default: 2m0s)
       --no-random-sleep                         Do not add a random sleep before the renewal. We do not recommend using this flag if you are doing your renewals in an automated way. (default: false)
       --force-cert-domains                      Check and ensure that the cert's domain list matches those passed in the domains argument. (default: false)
       --help, -h                                show help

    NAME:
       lego revoke - Revoke a certificate

    USAGE:
       lego revoke [command options]

    OPTIONS:
       --keep, -k      Keep the certificates after the revocation instead of archiving them. (default: false)
       --reason value  Identifies the reason for the certificate revocation. See https://www.rfc-editor.org/rfc/rfc5280.html#section-5.3.1. Valid values are: 0 (unspecified), 1 (keyCompromise), 2 (cACompromise), 3 (affiliationChanged), 4 (superseded), 5 (cessationOfOperation), 6 (certificateHold), 8 (removeFromCRL), 9 (privilegeWithdrawn), or 10 (aACompromise). (default: 0)
       --help, -h      show help

    NAME:
       lego list - Display certificates and accounts information.

    USAGE:
       lego list [command options]

    OPTIONS:
       --accounts, -a  Display accounts. (default: false)
       --names, -n     Display certificate common names only. (default: false)
       --help, -h      show help

    Credentials for DNS providers must be passed through environment variables.

    To display the documentation for a specific DNS provider, run:

      $ lego dnshelp -c code

    Supported DNS providers:
      acme-dns, active24, alidns, allinkl, arvancloud, auroradns, autodns, azure, azuredns, bindman, bluecat, bookmyname, brandit, bunny, checkdomain, civo, clouddns, cloudflare, cloudns, cloudru, cloudxns, conoha, constellix, corenetworks, cpanel, derak, desec, designate, digitalocean, directadmin, dnshomede, dnsimple, dnsmadeeasy, dnspod, dode, domeneshop, dreamhost, duckdns, dyn, dynu, easydns, edgedns, efficientip, epik, exec, exoscale, f5xc, freemyip, gandi, gandiv5, gcloud, gcore, glesys, godaddy, googledomains, hetzner, hostingde, hosttech, httpnet, httpreq, huaweicloud, hurricane, hyperone, ibmcloud, iij, iijdpf, infoblox, infomaniak, internetbs, inwx, ionos, ipv64, iwantmyname, joker, liara, lightsail, limacity, linode, liquidweb, loopia, luadns, mailinabox, manageengine, manual, metaname, metaregistrar, mijnhost, mittwald, myaddr, mydnsjp, mythicbeasts, namecheap, namedotcom, namesilo, nearlyfreespeech, netcup, netlify, nicmanager, nifcloud, njalla, nodion, ns1, oraclecloud, otc, ovh, pdns, plesk, porkbun, rackspace, rainyun, rcodezero, regfish, regru, rfc2136, rimuhosting, route53, safedns, sakuracloud, scaleway, selectel, selectelv2, selfhostde, servercow, shellrent, simply, sonic, spaceship, stackpath, technitium, tencentcloud, timewebcloud, transip, ultradns, variomedia, vegadns, vercel, versio, vinyldns, vkcloud, volcengine, vscale, vultr, webnames, websupport, wedos, westcn, yandex, yandex360, yandexcloud, zoneee, zonomi

    More information: https://go-acme.github.io/lego/dns

When using the standard `--path` option, all certificates and account configurations are saved to a folder `.lego` in the current working directory.

## Let’s Encrypt ACME server

lego defaults to communicating with the production Let’s Encrypt ACME server. If you’d like to test something without issuing real certificates, consider using the staging endpoint instead:

    lego --server=https://acme-staging-v02.api.letsencrypt.org/directory …

## Running without root privileges

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.port` or/and the `--tls.port` 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

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.port` and `--tls.port` 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 challenge1.

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.

## DNS Resolvers and Challenge Verification

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 domain2. 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 Google’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 (Let’s Encrypt).
- 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 Let’s Encrypt 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.

## Other options

### LEGO_CA_CERTIFICATES

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

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

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

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

Example:

    LEGO_DISABLE_CNAME_SUPPORT=false

### LEGO_DEBUG_CLIENT_VERBOSE_ERROR

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_ACME_HTTP_CLIENT

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

Example:

    LEGO_DEBUG_ACME_HTTP_CLIENT=true

1. 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`. ↩︎

2. 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`). ↩︎