Renewal Timing and Configuration

This page covers where and how to configure renewal timing—ARI (recommended) in [service], legacy fixed-window settings, CLI enroll flags, and production vs. sandbox defaults.

For how renewals behave over time (service loop, ARI replacement orders, eligibility rules), see Understanding Automated Renewals.

Acronyms used on this page

Where settings live

Renewal behavior is configured in:

• dc-acme.toml [service] section (loaded with --use-default-config or --config)
• CLI flags on request enroll — for most settings, CLI overrides TOML per key. Exception: with --use-default-config, auto_ari_renew in TOML controls ARI job registration; CLI --auto-ari-renew and --auto-renew do not override TOML for renewal mode (see Configuration — Renewal settings).

Settings reference

With --use-default-config, TOML [service] controls renewal mode for each certificate. CLI flags override TOML for other keys (EAB, challenge, --cn, etc.) but not for --auto-ari-renew / --auto-renew.

Default settings

New installations ship with renewals disabled:

[service]
auto_renew = false
auto_ari_renew = false
auto_renew_days = 30

This conservative default prevents unexpected reissues on fresh installs. You must explicitly enable renewal automation and pass the appropriate enroll flags.

Recommended configurations

Production automation (ARI — recommended)

Match Production CLI Examples and Configuration:

[service]
auto_ari_renew = true   # required for production — CA-directed reissue timing
auto_renew = true       # keep enabled; ignored for certs with an ARI job
auto_renew_days = 30    # legacy — not used when auto_ari_renew = true

Enroll with --use-default-config. TOML auto_ari_renew = true registers an ARI job for each certificate (non-zero acmeAriId in request list). You do not need to tune a day count—DigiCert directs timing via ARI.

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

CLI-only production enrolls (no --use-default-config) should still pass --auto-ari-renew=true explicitly.

Sandbox or one-shot enrolls (no automatic reissues)

CLI-only (sandbox walkthroughs — no --use-default-config):

sudo dc-acme request enroll \
  --directory-url "https://one.digicert.com/mpki/api/v1/acme/v2/directory" \
  --auto-ari-renew=false \
  --cn "test.example.com" \
  ...

Config-based enroll: set TOML auto_ari_renew = false before enroll (restart the service if needed). Passing --auto-ari-renew=false on the CLI does not override TOML true when --use-default-config is used.

Legacy fixed window only (not recommended)

Use only for existing hosts that cannot enable ARI, or for special testing. GeoCerts does not recommend this for new production automation.

[service]
auto_renew = true
auto_ari_renew = false
auto_renew_days = 30    # legacy “renew N days before expiry” model

Enroll with --use-default-config. Confirm acmeAriId: 0 in request list after completion.

Legacy: what auto_renew_days means

auto_renew_days is part of the legacy fixed-window model—the older “renew ~N days before expiry” approach that predates ARI. It applies only when auto_ari_renew = false at enroll time (acmeAriId: 0 in request list).

auto_renew_days does not schedule renewal at an exact date and time. It defines the earliest point at which the client may attempt fixed-window renewal—a rolling window evaluated by the running service.

Example: a certificate expiring March 31 with auto_renew_days = 30 becomes eligible around March 1. The exact attempt time depends on when the service next evaluates conditions.

For production, enable ARI instead (auto_ari_renew = true). ARI adapts as certificate lifetimes and CA policy change; a static day count does not.

Renewal flags on enroll

Operational factors that delay renewal

Even with correct configuration, renewal attempts may be delayed or fail because of:

• Too early — outside DigiCert’s renewal eligibility window (or ARI returns Should renew now: false)
• DNS or HTTP validation failures — DCV must succeed on every reissue
• Expired OV organization or domain validation — see Understanding Automated Renewals
• Host permission issues — challenge handler or installer cannot write files or reload the web server
• Account funding or billing — prepaid coverage or balance must support reissue

If a renewal attempt fails, the existing certificate remains valid until expiration. The client may retry; check service logs for details.

For renewals that create new billable orders instead of reissuing, see Auto-detection Rules and Unexpected new orders in Troubleshooting.

Verify configuration

1. Review the [service] section in dc-acme.toml — this is the source of truth for renewal settings when you use --use-default-config
2. Confirm DigicertAcmeClient is running
3. Run sudo dc-acme request list — COMPLETED status; check acmeAriId (non-zero = ARI, 0 = legacy fixed window)

sudo systemctl status DigicertAcmeClient
sudo dc-acme request list

The client does not show a “next renewal date” in CLI output. Use CertCommand for expiration dates. See Understanding Automated Renewals.

Key takeaways

• Production: auto_ari_renew = true in TOML + --use-default-config on enroll
• Confirm ARI with non-zero acmeAriId in request list
• auto_renew_days is legacy — only when ARI is off; not recommended for new deployments
• Defaults are off; enable auto_ari_renew explicitly for production automation
• Sandbox CLI-only: --auto-ari-renew=false. Sandbox config-based: TOML auto_ari_renew = false
• With --use-default-config, TOML controls ARI registration—not CLI --auto-ari-renew
• No CLI renewal countdown—monitor expiration in CertCommand

Next step

Advanced Automation »

Related topics

• Understanding Automated Renewals
• Configuration (dc-acme.toml)
• Frequently Asked Questions

← Back to Renewals