Configuration file

This describes the configuration file format.

lego looks for configuration files in the following paths from the current working directory:

.lego.yml
.lego.yaml

The configuration file can be validated with the JSON Schema: lego.jsonschema.json

Global configuration

# Path to the directory to use for storing the data.
#
# Default: ./lego
storage: /tmp/lego/

# The network stack to use.
# It can be:
# - ipv6only
# - ipv4only
#
# Default: both
networkStack: ipv6only

# The user agent to use when connecting to the ACME server.
#
# Default: information related to lego.
userAgent: foo

Certificates

# When a certificate definition is removed from the configuration file, the corresponding certificate files are archived.
# The archives are deleted after 30 days.
certificates:
  
  # The ID/Name of the certificate.
  myCert:
    # The challenge type.
    # It can be:
    # 1. `http-01` (This is a special name to use the default HTTP challenge provider)
    # 2. `tls-alpn-01` (This is a special name to use the default TLS-ALPN-01 challenge provider)
    # 3. a reference to the ID of a challenge provider defined in the configuration section `challenges`.
    #
    # Required.
    challenge: one
    
    # The account ID/Name.
    # If there is no account defined in the configuration file, the default account is used.
    # If there is only one account defined in the configuration file, the account ID can be omitted.
    #
    # Required.
    account: foo
    
    # The key type used to generate the certificate.
    # If not set, use the account key type, or EC256 if no account key type is defined.
    #
    # Required.
    keyType: RSA2048
    
    # The domains to request a certificate for.
    #
    # Mutually exclusive with `csr`.
    domains:
      - example.com
      - '*.example.com'
    
    # The path to a Certificate Signing Request (CSR) file.
    #
    # Mutually exclusive with `domains`.
    csr: /tmp/foo.csr

    # The preferred chain to use.
    #
    # Optional.
    preferredChain: "ISRG Root X1"
    
    # The ACME server profile
    #
    # Optional.
    profile: "tls"
    
    # Enable the use of the Common Name (CN) in the certificate.
    # CN is deprecated and should not be used.
    #
    # Optional.
    # Default: false
    enableCommonName: true
    
    # The notBefore field in the certificate.
    #
    # Optional.
    notBefore: ""

    # The notAfter field in the certificate.
    #
    # Optional.
    notAfter: ""
    
    # Do not create a certificate bundle by adding the issuers certificate to the new certificate.
    #
    # Default: false
    noBundle: true

    # Include the OCSP must staple TLS extension in the CSR and generated certificate.
    # Only works if the CSR is generated by lego.
    #
    # Default: true
    mustStaple: false
    
    # Force the authorizations to be relinquished even if the certificate request was successful.
    #
    # Default: false
    alwaysDeactivateAuthorizations: true
    
    # Options for the certificate renewal.
    #
    # Optional.
    renew:
      # Reuse the private key if it exists.
      #
      # Optional.
      # Default: false
      reuseKey: true
      
      
      # The number of days left on a certificate to renew it.
      # 
      # By default, compute dynamically, based on the lifetime of the certificate(s), when to renew:
      # use 1/3rd of the lifetime left, or 1/2 of the lifetime for short-lived certificates.
      days: 1
  
      # Do not add a random sleep before the renewal.
      #
      # We do not recommend using this option if you are doing your renewals in an automated way.
      #
      # Default: false
      disableRandomSleep: true
      
      # ARI configuration.
      #
      # Optional.
      ari:
        # Disable the ARI mechanism.
        #
        # Default: false
        disable: true
        
        # The maximum duration you're willing to sleep for a renewal time returned by the renewalInfo endpoint.
        # 
        # Default: 0s
        waitToRenewDuration: 1m
    
    # Generate an additional .pfx (PKCS#12) file by concatenating the .key and .crt and issuer .crt files together.
    # 
    # Optional.
    pfx:
      # The password used to encrypt the .pfx (PCKS#12) file.
      #
      # Required.
      password: xxx
      
      # The encoding format to use when encrypting the .pfx (PCKS#12) file.
      #
      # Supported:
      # - DES
      # - RC2
      # - SHA256
      # - PBMAC1
      #
      # Optional.
      # Default: RC2
      format: PBMAC1

Challenges

# The challenge configurations.
challenges:
  # The ID/Name of the challenge.
  #
  # Required.
  one:
    # The HTTP-01 challenge configuration.
    #
    # Optional.
    http:
      # The address to listen on.
      #
      # Default: ":80"
      address: ":80"
      
      # Delay between the starts of the HTTP server (use for HTTP-01 based challenges) and the validation of the challenge.
      #
      # Default: 0s
      delay: 6s
      
      # Validate against this HTTP header when solving HTTP-01 based challenges behind a reverse proxy.
      #
      # Optional.
      proxyHeader: Host

      # 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".
      #
      # Optional.
      webroot: /tmp/webroot

      # The memcached host(s) to use for HTTP-01 based challenges. Challenges will be written to all specified hosts.
      #
      # Optional.
      memcachedHosts:
        - memcached:11211
      
      # Tthe S3 bucket name to use for HTTP-01 based challenges. Challenges will be written to the S3 bucket.
      s3Bucket: 's3-bucket'

  # The ID/Name of the challenge.
  #
  # Required.
  two:
    # The TLS-ALPN-01 challenge configuration.
    #
    # Optional.
    tls:
      # The address to listen on.
      #
      # Default: ":443"
      address: ":443"

      # Delay between the start of the TLS listener (use for TLSALPN-01 based challenges) and the validation of the challenge.
      #
      # Default: 0s
      delay: 6s

  # The ID/Name of the challenge.
  #
  # Required.
  three:
    # The DNS-01 challenge configuration.
    #
    # Optional.
    dns:
      # The DNS provider.
      #
      # Required.
      provider: cloudflare
      
      # The path to the dotenv file containing the credentials.
      #
      # Optional.
      envFile: /tmp/secrets/.env
      
      # The configuration related to propagation check.
      #
      # Optional.
      propagation:
        # By setting this option to true,
        # disables the need to await propagation of the TXT record to all authoritative name servers.
        #
        # Default: false
        disableAuthoritativeNameservers: true

        # By setting this option to true,
        # disables the need to await propagation of the TXT record to all recursive name servers (aka resolvers).
        #
        # Default: false
        disableRecursiveNameservers: true

        # Disables all the propagation checks of the TXT record and uses a wait duration instead.
        #
        # This option is strongly discouraged.
        #
        # Default: 0
        wait: 5s

      # Set the DNS timeout value to a specific value in seconds. Used only when performing authoritative name server queries.
      #
      # Default: 10
      dnsTimeout: 30

      # 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 syntax: host:port.
      #
      # Optional.
      # The default is to use the system resolvers, or Google's DNS resolvers if the system ones cannot be determined.
      resolvers:
        - 1.1.1.1:53

  # The ID/Name of the challenge.
  #
  # Required.
  four:
    # The DNS-PERSIST-01 challenge configuration.
    #
    # Optional.
    dnsPersist:
      # Override the issuer-domain-name to use for DNS-PERSIST-01 when multiple are offered.
      # Must be offered by the challenge.
      #
      # Optional.
      issuerDomainName: example.com

      # Set the optional `persistUntil` for DNS-PERSIST-01 records as an RFC3339 timestamp.
      #
      # Optional.
      persistUntil: 2020-01-01T00:00:00Z

      # The configuration related to propagation check.
      #
      # Optional.
      propagation:
        # By setting this option to true,
        # disables the need to await propagation of the TXT record to all authoritative name servers.
        #
        # Default: false
        disableAuthoritativeNameservers: true

        # By setting this option to true,
        # disables the need to await propagation of the TXT record to all recursive name servers (aka resolvers).
        #
        # Default: false
        disableRecursiveNameservers: true

        # Disables all the propagation checks of the TXT record and uses a wait duration instead.
        #
        # This option is strongly discouraged.
        #
        # Default: 0
        wait: 5s

Accounts

Defining an account is optional: lego will create one for you by default on the Let’s Encrypt ACME server.

If you want to use a different ACME server, or if you want to customize the account, you can define it in the configuration file.

# When an account definition is removed from the configuration file, the corresponding account files are archived.
# The archives are deleted after 30 days.
accounts:
  # The ID/Name of the account.
  #
  # Required.
  myAccount:
    # The ACME server.
    #
    # It can be:
    # 1. a URL
    # 2. a short code (see the shortcode section)
    # 3. a reference to the ID of a server defined in the servers configuration section
    #
    # Default: https://acme-v02.api.letsencrypt.org/directory
    server: https://example.com/dir
    
    # The account email.
    #
    # Optional.
    email: foo@example.com
    
    # The key type used to generate the account private key.
    #
    # Default: EC256
    keyType: RSA2048
    
    # The acceptance of the terms of service.
    #
    # Default: false
    acceptsTermsOfService: true
    
    # The External Account Binding (EAB) configuration.
    #
    # Optional.
    eab:
      # The External Account Binding (EAB) KID.
      #
      # Required.
      kid: foo
      # The External Account Binding (EAB) HMAC key.
      #
      # Required.
      hmacKey: foo

Servers

servers:
  # The ID/Name of the server.
  #
  # Required.
  myServer:
    # The ACME server URL.
    #
    # Required.
    url: https://example.com/dir

    # ACME overall requests limit.
    #
    # Default: 18
    overallRequestLimit: 7

    # Skip the TLS verification of the ACME server.
    #
    # Default: false
    tlsSkipVerify: true

    # The HTTP timeout value to a specific value in seconds.
    #
    # Default: 30
    httpTimeout: 60

    # The certificate timeout value to a specific value in seconds.
    # Only used when getting certificates.
    #
    # Default: 30
    certTimeout: 60

Logging

# Logging configuration.
#
# Optional.
log:
  # The logging level.
  #
  # Default: info
  level: debug
  
  # The logging format.
  #
  # Supported:
  # - text
  # - json
  # - colored
  #
  # Default: colored
  format: json

Hooks

# Hooks configuration.
#
# Optional.
hooks:
  # The pre-hook.
  #
  # Optional.
  pre:
    # The command to execute.
    #
    # Required.
    command: "./my-pre-hook.sh"
    
    # The timeout of the command.
    #
    # optional.
    timeout: 3s
  
  # The deploy-hook.
  #
  # Optional.
  deploy:
    # The command to execute.
    #
    # Required.
    command: "./my-deploy-hook.sh"

    # The timeout of the command.
    #
    # optional.
    timeout: 3s
  
  # The post-hook.
  #
  # Optional.
  post:
    # The command to execute.
    #
    # Required.
    command: "./my-post-hook.sh"

    # The timeout of the command.
    #
    # optional.
    timeout: 3s