Obtain or renew certificates

This guide explains various ways to get and renew a certificate.

These examples assume you have lego installed. You can get a pre-built binary from the releases page.

Quickstart

​

Execute the following command:

lego run -d 'example.com' --http

Create a .lego.yml file with the following content:

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

And execute:

lego

Wildcard Certificates

​

Execute the following command:

CLOUDFLARE_EMAIL="you@example.com" \
CLOUDFLARE_API_KEY="yourprivatecloudflareapikey" \
lego run --dns cloudflare -d 'example.org' -d '*.example.org'

Create a .lego.yml file with the following content:

challenges:
  cf:
    dns:
      provider: cloudflare

certificates:
  foo:
    domains:
      - example.com
      - '*.example.com'

And execute:

CLOUDFLARE_EMAIL="you@example.com" \
CLOUDFLARE_API_KEY="yourprivatecloudflareapikey" \
lego

Certificates

You will find your certificates in the .lego folder of the current working directory:

$ ls -1 ./.lego/certificates
example.com.crt
example.com.issuer.crt
example.com.json
example.com.key
[maybe more files for different domains...]

where

  • example.com.crt is the server certificate (including the CA certificate),
  • example.com.key is the private key needed for the server certificate,
  • example.com.issuer.crt is the CA certificate, and
  • example.com.json contains some JSON encoded meta information.

For each domain, you will have a set of these four files. For wildcard certificates (*.example.com), the filenames will look like _.example.com.crt.

The .crt and .key files are PEM-encoded x509 certificates and private keys. If you’re looking for a cert.pem and privkey.pem, you can just use example.com.crt and example.com.key.

Using a custom certificate signing request (CSR)

The first step in the process of obtaining certificates involves creating a signing request. This CSR bundles various information, including the domain name(s) and a public key. By default, lego will hide this step from you, but if you already have a CSR, you can easily reuse it:

​

Execute the following command:

lego run --http --csr="/path/to/csr.pem"

Create a .lego.yml file with the following content:

certificates:
  foo:
    csr: /path/to/csr.pem
    challenge: http-01
    domains:
      - example.com

And execute:

lego

lego will infer the domains to be validated based on the contents of the CSR, so make sure the CSR’s Common Name and SubjectAltNames are set correctly.

Challenge Types

May 13, 2026

Subsections of Obtain or renew certificates

DNS-01 Challenge

This guide explains how to get and renew a certificate with the DNS-01 challenge.

lego comes with support for many providers, and you need to pick the one where your domain’s DNS settings are set up. Typically, this is the registrar where you bought the domain, but in some cases this can be another third-party provider.

Using a DNS provider

For this example, let’s assume you have set up Cloudflare for your domain.

​

Execute the following command:

CLOUDFLARE_EMAIL='you@example.com' \
CLOUDFLARE_API_KEY='yourprivatecloudflareapikey' \
lego run --dns cloudflare --domains 'example.org' --domains '*.example.org'

Create a .lego.yml file with the following content:

challenges:
  cf:
    dns:
      provider: cloudflare

certificates:
  foo:
    domains:
      - example.com
      - '*.example.com'

And execute:

CLOUDFLARE_EMAIL='you@example.com' \
CLOUDFLARE_API_KEY='yourprivatecloudflareapikey' \
lego

Configuration and Credentials

More information here

Tips

For a zone that has multiple SOAs

This can often be found where your DNS provider has a zone entry for an internal network (i.e., a corporate network, or home LAN) as well as the public internet. In this case, point lego at an external authoritative server for the zone using the additional parameter --dns.resolvers.

​

Execute the following command:

CLOUDFLARE_EMAIL='you@example.com' \
CLOUDFLARE_API_KEY='yourprivatecloudflareapikey' \
lego run --dns cloudflare --dns.resolvers 9.9.9.9:53 -d 'example.org' -d '*.example.org'

Create a .lego.yml file with the following content:

challenges:
  cf:
    dns:
      provider: cloudflare
      resolvers:
        - 9.9.9.9:53
certificates:
  foo:
    domains:
      - example.org
      - '*.example.org'

And execute:

CLOUDFLARE_EMAIL='you@example.com' \
CLOUDFLARE_API_KEY='yourprivatecloudflareapikey' \
lego

More information about resolvers.

Apr 26, 2026

HTTP-01 Challenge

This guide explains how to get and renew a certificate with the HTTP-01 challenge.

Note

The examples require that the lego binary has permission to bind to ports 80.
If your environment does not allow you to bind to these ports, please read Running without root privileges and Port Usage.

Using the built-in web server

​

Execute the following command:

lego run -d 'example.com' --http

Create a .lego.yml file with the following content:

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

And execute:

lego

Using an existing, running web server

If you have an existing server running on port 80, the --http option also requires the --http.webroot option. This just writes the http-01 challenge token to the given directory in the folder .well-known/acme-challenge and does not start a server.

The given directory should be publicly served as / on the domain(s) for the validation to complete.

If the given directory is not publicly served, you will have to support rewriting the request to the directory;

You could also implement a rewrite to rewrite .well-known/acme-challenge to the given directory .well-known/acme-challenge.

You should be able to run an existing webserver on port 80 and have lego write the token file with the HTTP-01 challenge key authorization to <webroot dir>/.well-known/acme-challenge/ by running something like:

​

Execute the following command:

lego run --http --http.webroot /path/to/webroot --domains example.com

Create a .lego.yml file with the following content:

challenges:
  mychallenge:
    http:
      webroot: /tmp/webroot

certificates:
  foo:
    challenge: mychallenge
    domains:
      - example.com

And execute:

lego
Apr 25, 2026

TLS-ALPN-01 Challenge

This guide explains how to get and renew a certificate with the TLS-ALPN-01 challenge.

Note

The examples require that the lego binary has permission to bind to ports 443.
If your environment does not allow you to bind to these ports, please read Running without root privileges and Port Usage.

​

Execute the following command:

lego run -d 'example.com' --tls

Create a .lego.yml file with the following content:

certificates:
  foo:
    challenge: tls-alpn-01
    domains:
      - example.com

And execute:

lego
Apr 25, 2026

DNS-PERSIST-01 Challenge

This guide explains how to get and renew a certificate with the DNS-PERSIST-01 challenge.

Note
  • The RFC is still a draft.
  • This is currently not available in most CA production.
Important

This challenge could be less secure than DNS-01 due to its requirements.

This is especially true if your DNS provider does not offer any way to limit the access controls to the specific persistent record required by the DNS-PERSIST-01 challenge.

The security of this challenge relies primarily on protecting your account’s private key.

​

Execute the following command:

lego run -d 'example.com' --dns-persist

Create a .lego.yml file with the following content:

certificates:
  foo:
    challenge: dns-persist-01
    domains:
      - example.com

And execute:

lego