Configuring the ACME client

Extract the files

Extract the contents of the zip file to a directory of your choice. You will find the following files inside the package:

  • spacme (or spacme.exe): The main command-line interface tool.

  • config.yaml: The starter configuration file where you define your certificates.

  • .env: A convenient place to set environment variables.

  • examples/: Contains example configurations for advanced use cases (e.g., multi-account setups).

  • README.html: An offline, easy-to-read version of the readme documentation.

  • EULA.txt: The End User License Agreement.

Configure the ACME client

Get DNS credentials

  1. Navigate to Lego.

  2. Under DNS Providers, select your DNS provider (for example, IONOS)

  3. Follow the on-screen instructions and links (if any) to the DNS provider’s documentation.

    Retrieve the following. You will need them to edit the config file.

    • the provider’s code

    • provider-specific environment variable names and values

Each DNS provider is different. They may have different numbers of variables and specific methods for retrieving the information.
lego-ionos-screenshot

Edit the config file

  1. From the package, copy the config file to your text editor.

  2. Edit config.yaml to configure certificate, ACME, and DNS details, referring to the following table.

    Parameter Definition

    common_name

    Your domain name.

    san_domains

    Optional. The list of SAN domains (common_name included automatically)

    acme_server

    ACME server URL, provided by the certificate authority. For example, "https://acme.sectigo.com".

    acme_eab_id

    Your ACME EAB ID, provided by the certificate authority.

    acme_eab_key

    Your ACME EAB key, provided by the certificate authority.

    acme_eab_hmac

    Your ACME HMAC key, provided by the certificate authority.

    contact_email

    The email that should receive expiry/revocation notifications.

    provider

    Copied from the Code field on the DNS Provider page on Lego (in this example, "ionos").

    Provider-specific variables. For example, IONOS_API_KEY

    Copied from the Environment Variable Name table on the DNS Provider page on Lego (in this example, follow the link to retrieve API key "014a58734f70…​").
    Example config.yaml
    certificates:
  - common name: "example1.com"
    san_domains: [ "*.example1.com", "api.example1.com"]
    acme_server: "https://acme.sectigo.com/dv"
    acme_eab_kid: "rqEI7222N6YAHH_T65ioZA"
    acme_eab_hmac: "U9xwni3WOIAuuwjc91ZAEhPydSoZjTrQvOMZVvgqqQ8HM3gPYe3iCKhwsC1zLiTZ9pb5vTAfnP4IHCVRX0y6XA"
    contact_email: "[email protected]"
    dns:
      provider: "ionos"
      IONOS_API_KEY: "014a58734f704b3fa254d3fb843ce371.nMiGBa0VK8EjbjImCvsQF9xPYKzlaHTKco9ix5j0InoBv8RxJpdlY_A3hEnk67ZiBrcVblNzeMdkLFTNiqjULg"
    You can also provide credentials by exporting them as environment variables or by putting them in the .env file.

Validate the config file

Before processing, you can validate your configuration for syntax errors.

  • Linux/mac:

    ./spacme validate

  • Windows:

    spacme.exe validate

Separate secrets from config (optional)

You might want to remove secrets from config.yaml to track it in version control. The config file supports environment variable substitution.

For example, if you have the following environment variables:

ACME_EAB_HMAC=abc123

DEPARTMENT=infosec

Then you can use the ${VAR} syntax in config.yaml:

acme_eab_hmac: "${ACME_EAB_HMAC}" # will be abc123

contact_email: "${DEPARTMENT}@company.com" # will be [email protected]

Config file reference

This table lists all supported configuration fields. For more details on how to use them, see the examples/ directory.

Field Level Default Description

contact_email

Global

-

Default email address for ACME notifications.

key_type

Global

RSA2048

Default key type. Supported: RSA2048, RSA3072, RSA4096, RSA8192, EC256, EC384.

renew_before_days

Global

3

Default number of days before expiration to renew.

renew_on_ocsp_fail

Global

false

Default behavior for renewal if OCSP check fails.

acme_accounts

Global

-

Dictionary of reusable ACME account profiles.

acme_accounts.<name>.server

ACME

-

ACME server directory URL.

acme_accounts.<name>.eab_kid

ACME

-

External Account Binding (EAB) Key ID.

acme_accounts.<name>.eab_hmac

ACME

-

External Account Binding (EAB) HMAC.

acme_accounts.<name>.skip_tls_check

ACME

false

Skip TLS verification for the ACME server.

dns_providers

Global

-

Dictionary of reusable DNS provider configurations.

dns_providers.<alias>

Global

-

DNS provider alias to be referenced by certificates.

dns_providers.<alias>.some_key

Global

-

DNS provider specific settings.

certificates

Global

-

List of certificate configurations to manage.

certificates[].name

Cert

common_name

Unique name for the certificate storage.

certificates[].common_name

Cert

-

Required. Primary domain name.

certificates[].san_domains

Cert

-

List of additional domain names (SANs).

certificates[].key_type

Cert

Global

Overrides global key_type.

certificates[].acme_account

Cert

"default"

Reference to acme_accounts.

certificates[].acme_server

Cert

-

Ad-hoc ACME server URL (if acme_account is not used).

certificates[].acme_eab_kid

Cert

-

Ad-hoc EAB Key ID.

certificates[].acme_eab_hmac

Cert

-

Ad-hoc EAB HMAC.

certificates[].acme_skip_tls_check

Cert

false

Ad-hoc skip ACME server TLS verification.

certificates[].dns_provider

Cert

-

Reference to dns_providers alias or a LEGO provider name.

certificates[].dns

Cert

-

Ad-hoc DNS provider config (must include provider key).

certificates[].acme_contact_email

Cert

Global

Overrides global contact_email.

certificates[].renew_before_days

Cert

Global

Overrides global renew_before_days.

certificates[].renew_on_ocsp_fail

Cert

Global

Overrides global renew_on_ocsp_fail.