Delegated DNS-01 in the Agent¶

See Agent workflow usage for the complete ACME challenge lifecycle, job timeline, and DNS troubleshooting.

The Windows and Linux Agents use CertIntel Delegated DNS-01 for native ACME workflows. The service publishes and removes the challenge value, verifies authoritative DNS propagation, and then lets the configured certificate authority validate it. There is no separate DNS hook or scheduled ACME client to configure.

DNS-01 is the only validation method for ACME certificates. A CertIntel Private CA certificate needs no validation at all.

HTTP-01 was removed in Agent 1.5.0¶

Agent 1.4.0 could also validate names with HTTP-01, from a web root or with a standalone listener on port 80. HTTP-01 was removed in Agent 1.5.0, from the Agent, the dashboard and the documentation; every ACME certificate is now validated with Delegated DNS-01.

• Settings written by Agent 1.4.x keep loading. The rest of the configuration, and every other certificate, work as before.
• A certificate that still has an HTTP-01 challenge stops renewing. It is not issued or renewed, and its status shows HTTP-01 is no longer supported (removed in Agent 1.5.0); delegate DNS-01 for these names and remove the challenge setting. The Agent's activity log records certificate-challenge-unsupported once each time the service starts. A certificate that was already issued is still installed, including in its deployment window, until it expires.
• Switch to DNS-01. Create a delegation for each name (see below), then use Switch to DNS-01: in the terminal interface, edit the certificate; in the Windows desktop app, open the workflow. Or remove challenge from the certificate in the configuration. Adding or changing a challenge setting is refused; removing it is allowed.
• Dashboard assignments. The dashboard refuses a challenge other than DNS-01 (HTTP-01 is no longer supported; use DNS-01 delegation.), and every ACME assignment needs a delegation for its names. The platform update that removes HTTP-01 cancels pending and awaiting-approval HTTP-01 assignments (reason HTTP-01 removed); older cards show HTTP-01 (removed). An Agent 1.5.0 refuses a proposal carrying another challenge with HTTP-01 is no longer supported; this agent validates names with DNS-01 only.
• Linux host setup. The next terminal-interface host setup rewrites 50-certintel-tui-paths.conf without the HTTP-01 challenge folders and without the port-80 capability (CAP_NET_BIND_SERVICE). Until then, the drop-in written by Agent 1.4.x stays in place.

If you opened inbound port 80 only for HTTP-01, you can close it again once every certificate on the machine has switched.

Add a delegation to a workflow¶

1. In CertIntel, open Delegated DNS-01 and create a delegation for the base domain to validate. Copy the record ID (username) and one-time secret.
2. On Windows, open Workflows → + New certificate workflow and continue to the DNS validation step. Enter the delegation ID and secret for each base domain. On Linux, use the terminal interface (Settings → Delegations → add), which prompts for the secret without echo, or add the delegation to the configuration and set its protected key with sudo certintel secret set dns DELEGATION-ID.
3. In the Windows wizard, select Verify credentials. The Agent authenticates the credential and retrieves the exact CNAME destination that belongs to it.
4. Publish the displayed CNAME at your authoritative DNS provider, then continue after the Agent verifies it. On Linux, use the exact destination from the CertIntel delegation and validate the configuration before applying it.

For example:

_acme-challenge.shop.example.com.  CNAME  <assigned-name>.dns01.certin.tel.

Use the exact name and destination shown by CertIntel; the assigned name is a 32-character label and CertIntel's DNS answers only for labels of that exact shape. Some DNS providers want a trailing dot; Cloudflare records must be DNS only, not proxied. See Delegated DNS-01 in the dashboard for record creation, rotation and revocation.

The secret is sent only to the local service, stored in its protected secret store, and never displayed again. A custom API base is available under the advanced options for private or non-default CertIntel deployments; it must be the deployment's HTTPS API base including /api/v1.

Test or replace a credential¶

Open Edit workflow… → DNS delegations to test the current mapping or use Add / replace delegation to supply a different ID and secret. The agent verifies that the credential belongs to the displayed CNAME destination; after you create the record, choose Connect delegation to save it. A custom (non-hosted) API base also needs the CNAME destination entered under Advanced. On Linux, the terminal interface's Settings screen offers t (test), s (replace secret) and d (delete) on each delegation.

For advanced provisioning, after a delegation mapping already exists in the agent configuration, an elevated prompt can replace only its protected secret:

certintel secret set dns DELEGATION-ID

The command prompts without echo. Use --stdin for automation. The Agent publishes and removes DNS challenges automatically as part of certificate issuance and renewal.

A delegation that still has a challenge value waiting to be cleaned up cannot be removed (DNS delegation still has a pending challenge record to clean up). Let the agent finish or retry the cleanup first; while a cleanup keeps failing, the agent also refuses to start new issuance for that delegation.

What happens during issuance¶

Before publishing a challenge, the service:

• authenticates the scoped delegation credential;
• confirms the public _acme-challenge CNAME points to the assigned target; and
• merges its value without evicting another active value.

The agent then checks the TXT response directly at authoritative nameservers. It uses fresh wire queries rather than the operating-system DNS cache. Public resolvers help discover the authority; if public or authoritative DNS is unreachable, the agent can fall back to the machine's configured DNS servers. Those local servers may still return cached data.

Checks run every ten seconds, for at most 30 attempts and five minutes. A TXT API write alone is not treated as success: the expected value must be visible in DNS before the CA is asked to validate it. On failure, the saved order, key and CSR remain available for a safe retry. Challenge values owned by the agent are removed when the authorization is terminal, including recovery after a restart.

Current ownership limit¶

Use a delegation from one issuing agent host at a time. The service safely serializes workflows on one host, but the Delegated DNS-01 API does not yet offer a conditional update that lets multiple machines coordinate the same two-value set without a race.

Troubleshooting¶