Configuration (dc-acme.toml)

Every production enroll starts with dc-acme request enroll from the shell. You can pass all settings as CLI flags (Production CLI Examples), or store shared defaults in dc-acme.toml and load them with --use-default-config—the file fills in what you omit on the command line; it does not replace the enroll command or create a separate workflow.

Acronyms used on this page

CLI-only vs. config file

Why use dc-acme.toml?

• Reuse across instances — Copy the same file (or a templated variant) to multiple Linux or Windows hosts so every server uses identical EAB, challenge, and installer settings.
• Shorter enroll commands — After the file is populated, production enrolls can be as small as --use-default-config --directory-url … --cn example.com --auto-ari-renew=true.
• Secrets off the command line — EAB credentials and handler args live in a file with restricted permissions instead of shell history and process listings.
• Renewal defaults in one place — Set [service] values once per host; see Renewal settings below.
• Team and automation friendly — Check the file into your config management (Ansible, cloud-init, etc.) or hand the same template to operators rolling out new certificates.

Why stay CLI-only?

• Transparency — Every flag is visible in the command you ran; useful for first production proof and support tickets.
• No file dependency — Nothing to copy or permission-lock beyond the client install itself.
• Sandbox and one-shot enrolls — Sandbox walkthroughs intentionally avoid TOML so DCV mechanics stay obvious.

Loading the config file

dc-acme.toml is opt-in. Production CLI Examples use explicit flags only—the file is not read unless you pass --use-default-config (default path) or --config /path/to/dc-acme.toml. Without either flag, the client uses smart defaults (for example, HTTP-01 with the standalone handler) and ignores dc-acme.toml, even if the file exists and is fully configured.

Default locations:

• Linux: /var/digicert/acme-client/config/dc-acme.toml
• Windows: C:\Program Files\DigiCert\AcmeClient\config\dc-acme.toml

Configuration precedence

When multiple sources define the same setting, the DigiCert ACME Client applies them in this order—highest priority first:

1. Command-line flags — wins for any key you pass on this request
2. Environment variables — for example, ACME_CONFIG_FILE for a custom config path
3. dc-acme.toml — values from the config file when you load it with --use-default-config or --config on the enroll command; without one of those flags, the file is not read and settings from this tier do not apply
4. Smart defaults — built-in fallbacks (HTTP-01 / standalone if challenge is unspecified)

Example: Your TOML configures DNS-01 with Route 53 and an NGINX installer for example.com. For a one-off cert for staging.example.com, you can run:

sudo dc-acme request enroll \
  --use-default-config \
  --directory-url "https://one.digicert.com/mpki/api/v1/acme/v2/directory" \
  --auto-ari-renew=false \
  --cn "staging.example.com" \
  --installer-handler-args "identifier=staging.example.com"

Everything not overridden—EAB, email, challenge type, Route 53 handler args—comes from dc-acme.toml.

Configure dc-acme.toml

Open dc-acme.toml in a text editor with elevated privileges. At minimum, set basic ACME settings and the challenge and installer sections that match your stack and DCV method—the same values you would pass as CLI flags in a production CLI example.

Linux / NGINX example (DNS-01, Route 53)

# Basic ACME settings
directory_url = "https://one.digicert.com/mpki/api/v1/acme/v2/directory"
email = "admin@example.com"
eab_key = "YOUR_EAB_KEY"
eab_hmac = "YOUR_EAB_HMAC"

# Domain control validation — DNS-01 (Route 53 example)
[challenge]
type = "dns-01"
handler_name = "default"
handler_args = "DNS_PROVIDER_NAME=route53,AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY,AWS_REGION=us-east-1"

# Post-issuance install
[installer]
handler_name = "nginx"
handler_args = "identifier=example.com"

# Renewal behavior — enable ARI for production (see Renewal settings)
[service]
auto_ari_renew = true   # recommended — CA-directed reissue timing
auto_renew = true       # keep enabled; not used when ARI registers on the certificate
auto_renew_days = 30    # legacy fixed-window; ignored when auto_ari_renew = true

For DNS-01 you must set both type = "dns-01" and handler_name = "default". For other DNS providers, see DigiCert’s DNS-01 handler reference.

Windows / IIS example

The same structure applies on Windows—adjust [installer] for IIS:

[installer]
handler_name = "iis"
handler_args = "hostname=example.com"

Complete the one-time IIS bootstrap before the first install. Other sections (directory_url, EAB, [challenge], [service]) match the Linux example.

Run a production request with config

With dc-acme.toml in place, enroll using --use-default-config. Pass --directory-url and --cn on every production enroll; other settings come from the file. When [service] auto_ari_renew = true, each certificate registers an ARI job—confirm non-zero acmeAriId in request list after completion:

# Production DNS-01 request using dc-acme.toml
sudo dc-acme request enroll \
  --use-default-config \
  --directory-url "https://one.digicert.com/mpki/api/v1/acme/v2/directory" \
  --cn "example.com"

PowerShell (elevated):

# Production DNS-01 request using dc-acme.toml
dc-acme request enroll `
  --use-default-config `
  --directory-url "https://one.digicert.com/mpki/api/v1/acme/v2/directory" `
  --cn "example.com"

Confirm COMPLETED in dc-acme request list, a non-zero acmeAriId when ARI is enabled in TOML, and the order in CertCommand under Certificates > Orders.

Renewal settings

Renewal timing is set in [service] in dc-acme.toml and/or with flags on request enroll. For challenge, installer, EAB, and most other keys, CLI flags override TOML when you pass both—the same precedence as Configuration precedence above.

Renewal flags behave differently depending on how you enroll. With --use-default-config, [service] auto_ari_renew in TOML controls whether an ARI job is registered. CLI --auto-ari-renew and --auto-renew on the enroll command do not override TOML in that mode. To disable ARI on a one-shot enroll while using the config file, set auto_ari_renew = false in TOML (restart the service if needed) or enroll without --use-default-config and pass flags on the CLI (as in Sandbox walkthroughs).

Do not use dc-acme --defaults or --help to infer ARI behavior—they report Auto ARI Renew: false even when CLI-only enrolls register an ARI job without the flag.

New installations ship with renewals disabled (auto_renew = false, auto_ari_renew = false). The [service] block in the example above enables ARI for production.

Pass --auto-ari-renew on enroll commands

Verify the client is running

After editing dc-acme.toml, confirm the DigiCert ACME Client service is running—the service applies renewal settings and processes enroll requests in the background.

On Linux:

sudo systemctl status DigicertAcmeClient

On Windows (PowerShell):

Get-Service -Name DigicertAcmeClient

List tracked requests:

sudo dc-acme request list

View smart defaults

dc-acme --defaults lists the client’s built-in smart defaults (for example, HTTP-01 with the standalone handler when challenge settings are omitted). Auto ARI Renew: false in that output does not reflect CLI-only enroll behavior—omitting --auto-ari-renew still registers an ARI job. There is no CLI command that prints your current dc-acme.toml or the values applied on a config-based enroll.

dc-acme --defaults

To verify renewal settings on a host, read the [service] section in dc-acme.toml and check acmeAriId in dc-acme request list after enroll.

Next step

Understanding Automated Renewals »

Related topics

• Production CLI Examples — All-CLI production recipes (alternative to config-based enroll)
• NGINX with DNS-01 — Reference production walkthrough
• Renewal Timing and Configuration — Enable ARI and legacy fixed-window settings
• Install the DigiCert ACME Client — Config file location
• Frequently Asked Questions — CLI vs dc-acme.toml

← Back to Certificate Automation (ACME)