lego

Lego is an ACME v2 (RFC 8555) client and library written in Go, designed for Let's Encrypt and other ACME Certificate Authorities. It provides automated certificate management including registration, obtaining (from scratch or existing CSR), renewal, and revocation.

Key features include:

• Support for RFC 8737 (ALPN), RFC 8738 (IP addresses), and RFC 9773 (ARI).
• Support for various ACME profiles and persistent DNS TXT record validation.
• Support for over 200 DNS providers.
• Robust implementation of HTTP-01, DNS-01, and TLS-ALPN-01 challenges.
• SAN (Subject Alternative Name) certificate support.
• CNAME support by default.
• Certificate bundling and OCSP helper functions.
• Ability to use custom challenge solvers.

Lego supports several ACME challenge types and certificate management features:

Challenge Types:

• DNS-01
• HTTP-01
• TLS-ALPN-01
• DNS-PERSIST-01

Certificate Management:

• Obtain, renew, and revoke certificates.
• Support for Wildcard and SAN (Subject Alternative Name) certificates.
• CNAME support is enabled by default.

To use EasyDNS as a DNS provider in lego, use the provider code easydns. You must provide credentials via environment variables. You can also configure API endpoints, timeouts, and propagation settings using specific environment variables.

To use file-based credentials instead of raw values, append _FILE to the environment variable names (e.g., EASYDNS_KEY_FILE).

EASYDNS_TOKEN=xxx \
EASYDNS_KEY=yyy \
lego run --dns easydns -d '*.example.com' -d example.com

Set the AZURE_AUTH_METHOD environment variable to specify your authentication strategy:

• env: Use Client Secret or Client Certificate (requires AZURE_CLIENT_ID, AZURE_TENANT_ID, and either AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH).
• wli: Use Azure Workload Identity (for AKS clusters using federated credentials).
• msi: Use Azure Managed Identity (for Azure VMs or Azure Arc).
• cli: Use Azure CLI credentials (requires az login).
• oidc: Use OpenID Connect.
• pipeline: Use Azure DevOps Pipelines.

If no method is specified, Lego uses Default Azure Credentials, which attempts to authenticate in this order:

1. Client Secret (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)
2. Client Certificate (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_CERTIFICATE_PATH)
3. Workload Identity
4. Azure CLI shared credentials (~/.azure folder)

To use Hetzner for DNS challenges in Lego, use the provider code hetzner. You must provide an API token via the HETZNER_API_TOKEN environment variable.

HETZNER_API_TOKEN="xxxxxxxxxxxxxxxxxxxxx" \
lego run --dns hetzner -d '*.example.com' -d example.com

lego searches for configuration files in the current working directory using the following filenames:

• .lego.yml
• .lego.yaml

You can validate your configuration file against the provided JSON Schema: lego.jsonschema.json.

To use Nodion for DNS-01 challenges in Lego, use the provider code nodion. You must provide an API token via the NODION_API_TOKEN environment variable.

NODION_API_TOKEN="xxxxxxxxxxxxxxxxxxxxx" \
lego run --dns nodion -d '*.example.com' -d example.com

In v5, most functions and methods now require a context.Context argument. When migrating, ensure you pass a context (e.g., context.TODO() or a context with a timeout) to these methods.

// Before
client.Certificate.Obtain(request)

// After
client.Certificate.Obtain(context.TODO(), request)

A pre-hook is executed before a certificate is created or renewed, but only if a change is actually required. You can configure it via the CLI or a .lego.yaml configuration file.

CLI usage: Use the --pre-hook flag.

Configuration file usage: Define the pre command under the hooks section in your .lego.yaml file.

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

# .lego.yaml
hooks:
  pre:
    command: './my-pre-hook.sh'

You can run Lego using the official Docker image. Use the following command to verify the installation by viewing the help text:

docker run goacme/lego -h