From 32e937d97aa4c555ae4b2d7638b58ea014fcd5c0 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 7 Oct 2026 17:46:46 -0700 Subject: [PATCH 1/2] Document the step-ca --resolver flag and dns-01 retries Add a section to ACME Basics about the --resolver flag. The flag applies to all DNS queries that step-ca makes. A systemd drop-in file can replace ExecStart, and the RA install script creates one at step-ca.service.d/local.conf. Add a section about DNS propagation. step-ca does not retry a dns-01 validation in the background, so the ACME client must wait for propagation before it requests validation. On the RA page, tell users to edit the drop-in file to change step-ca flags. Refs EFF-883 Co-Authored-By: Claude Opus 5.5 --- .../acme-for-certificate-manager.mdx | 2 +- step-ca/acme-basics.mdx | 47 +++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/registration-authorities/acme-for-certificate-manager.mdx b/registration-authorities/acme-for-certificate-manager.mdx index f66da0e8..bdc568f6 100644 --- a/registration-authorities/acme-for-certificate-manager.mdx +++ b/registration-authorities/acme-for-certificate-manager.mdx @@ -48,7 +48,7 @@ The script will: - Help you choose a JWK provisioner on your CA to link your RA to - Create RA configuration files in `/etc/step-ca` - Create a `step` user and group -- Add a systemd service called `step-ca.service` +- Add a systemd service called `step-ca.service`, with a drop-in file at `/etc/systemd/system/step-ca.service.d/local.conf` that sets the `step-ca` command line. To change `step-ca` flags, edit the drop-in file. - Enable and start `step-ca.service` - Export a `STEPPATH` variable in `/root/.bash_profile` diff --git a/step-ca/acme-basics.mdx b/step-ca/acme-basics.mdx index 12ab56fb..385ffdd2 100644 --- a/step-ca/acme-basics.mdx +++ b/step-ca/acme-basics.mdx @@ -159,6 +159,53 @@ Finalizing Order .. done! ✔ Private Key: example.key ``` +### Use a specific DNS resolver for `dns-01` validation + +By default, `step-ca` uses the system DNS resolver to look up `dns-01` challenge records. +In a split-horizon DNS environment, the internal resolver may not see the `TXT` records that your ACME client creates at a public DNS provider. +To send DNS queries to a different resolver, start `step-ca` with the `--resolver` flag: + +```shell +step-ca --resolver 1.1.1.1 $(step path)/config/ca.json +``` + +The flag applies to all DNS queries that `step-ca` makes, including `http-01` and `tls-alpn-01` validation and outbound connections to an upstream CA or to webhook servers. + +If systemd runs `step-ca`, add the flag to the `ExecStart=` line that systemd actually uses. +A drop-in file in `/etc/systemd/system/step-ca.service.d/` replaces the `ExecStart=` line of the main unit file. +For example, the [RA install script](../registration-authorities/acme-for-certificate-manager.mdx#option-1-use-our-linux-ra-install-script) creates the drop-in file `/etc/systemd/system/step-ca.service.d/local.conf`. +To see the command line that systemd uses, run: + +```shell +systemctl cat step-ca +``` + +To change the command line, edit the drop-in file and restart the service: + +```shell +sudo systemctl edit step-ca +sudo systemctl restart step-ca +``` + +### DNS propagation and challenge retries + +`step-ca` validates a challenge one time each time the ACME client requests it. +It does not try the validation again in the background. +If the `TXT` record is not yet visible to the resolver, the challenge stays in the `pending` state and shows an error. +The client can then request validation again. + +Some ACME clients, such as `certbot`, request validation only one time, and then wait for the challenge to change state. +If the DNS record is not visible at that time, the request fails when the client times out. +To prevent this, configure the client to wait for DNS propagation before it requests validation. +For example, the `certbot` DNS plugins have a `--dns--propagation-seconds` flag: + +```shell +certbot certonly --dns-cloudflare --dns-cloudflare-propagation-seconds 60 ... +``` + +DNS provider API rate limits can make propagation slower. +If you get certificates for many hosts at the same time, get them one after the other, or add a delay between requests. + ## Next steps From 1002e6a8078085d30b6cf133e9d7928cd31b0d28 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 7 Oct 2026 17:51:50 -0700 Subject: [PATCH 2/2] Move the --resolver section to Production Considerations Move the DNS resolver section from ACME Basics to Production Considerations, and add it to the table of contents. Remove the systemd drop-in and DNS propagation sections. Refs EFF-883 Co-Authored-By: Claude Opus 5.5 --- step-ca/acme-basics.mdx | 48 ------------------- ...ertificate-authority-server-production.mdx | 15 +++++- 2 files changed, 14 insertions(+), 49 deletions(-) diff --git a/step-ca/acme-basics.mdx b/step-ca/acme-basics.mdx index 385ffdd2..e086ee9f 100644 --- a/step-ca/acme-basics.mdx +++ b/step-ca/acme-basics.mdx @@ -159,54 +159,6 @@ Finalizing Order .. done! ✔ Private Key: example.key ``` -### Use a specific DNS resolver for `dns-01` validation - -By default, `step-ca` uses the system DNS resolver to look up `dns-01` challenge records. -In a split-horizon DNS environment, the internal resolver may not see the `TXT` records that your ACME client creates at a public DNS provider. -To send DNS queries to a different resolver, start `step-ca` with the `--resolver` flag: - -```shell -step-ca --resolver 1.1.1.1 $(step path)/config/ca.json -``` - -The flag applies to all DNS queries that `step-ca` makes, including `http-01` and `tls-alpn-01` validation and outbound connections to an upstream CA or to webhook servers. - -If systemd runs `step-ca`, add the flag to the `ExecStart=` line that systemd actually uses. -A drop-in file in `/etc/systemd/system/step-ca.service.d/` replaces the `ExecStart=` line of the main unit file. -For example, the [RA install script](../registration-authorities/acme-for-certificate-manager.mdx#option-1-use-our-linux-ra-install-script) creates the drop-in file `/etc/systemd/system/step-ca.service.d/local.conf`. -To see the command line that systemd uses, run: - -```shell -systemctl cat step-ca -``` - -To change the command line, edit the drop-in file and restart the service: - -```shell -sudo systemctl edit step-ca -sudo systemctl restart step-ca -``` - -### DNS propagation and challenge retries - -`step-ca` validates a challenge one time each time the ACME client requests it. -It does not try the validation again in the background. -If the `TXT` record is not yet visible to the resolver, the challenge stays in the `pending` state and shows an error. -The client can then request validation again. - -Some ACME clients, such as `certbot`, request validation only one time, and then wait for the challenge to change state. -If the DNS record is not visible at that time, the request fails when the client times out. -To prevent this, configure the client to wait for DNS propagation before it requests validation. -For example, the `certbot` DNS plugins have a `--dns--propagation-seconds` flag: - -```shell -certbot certonly --dns-cloudflare --dns-cloudflare-propagation-seconds 60 ... -``` - -DNS provider API rate limits can make propagation slower. -If you get certificates for many hosts at the same time, get them one after the other, or add a delay between requests. - - ## Next steps - Start tailoring `step-ca` to your infrastructure. See [Provisioners](./provisioners.mdx), [Production Considerations](./certificate-authority-server-production.mdx), and our [Configuration Guide](./configuration.mdx). diff --git a/step-ca/certificate-authority-server-production.mdx b/step-ca/certificate-authority-server-production.mdx index e1a3d157..155fb456 100644 --- a/step-ca/certificate-authority-server-production.mdx +++ b/step-ca/certificate-authority-server-production.mdx @@ -27,6 +27,7 @@ safely and securely in a production environment. - [High Availability](#high-availability) - [Proxying `step-ca` traffic](#proxying-step-ca-traffic) - [Exposing `step-ca` to the internet](#exposing-step-ca-to-the-internet) + - [Using an alternative DNS resolver](#using-an-alternative-dns-resolver) - [Certificate Lifecycle Management](#certificate-lifecycle-management) - [Automate Certificate Renewal](#automate-x509-certificate-lifecycle-management) - [Certificate Revocation](#certificate-revocation) @@ -649,7 +650,6 @@ When connecting an ACME provisioner to the internet, you will need to take preca echo https://ca.example.com/acme/$PROVISIONER_NAME/directory } ``` - ### Alternative: Use federation @@ -659,6 +659,19 @@ there's no need to expose your CA to the internet. Use [multiple autonomous federated CAs](../tutorials/pki-trust-model-federation.mdx) instead. +## Using an alternative DNS resolver + +By default, `step-ca` uses the system DNS resolver to look up `dns-01` challenge records. +In a split-horizon DNS environment, the internal resolver may not see the `TXT` records that your ACME client creates at a public DNS provider. +To send DNS queries to a different resolver, start `step-ca` with the `--resolver` flag: + +```shell +step-ca --resolver 1.1.1.1 $(step path)/config/ca.json +``` + +The flag applies to all DNS queries that `step-ca` makes, including `http-01` and `tls-alpn-01` validation and outbound connections to an upstream CA or to webhook servers. + + ## Certificate lifecycle management ### Automate X.509 certificate lifecycle management