From 2db51ad6043015c02bc7a768f109652d14e90d97 Mon Sep 17 00:00:00 2001 From: Jacky Date: Thu, 12 Nov 2026 20:09:25 +0800 Subject: [PATCH 1/2] fix: only check the recursive resolvers when the certificate asks for it NGINX UI 2.x waited for the authoritative nameservers only, because local resolvers such as systemd-resolved at 127.0.0.53 often do not return a fresh TXT record in time (0xJacky/nginx-ui#1711, #1719). The plugin also checked the recursive resolvers unless the certificate turned that off, so DNS-01 issuance that worked on 2.x stalled after the upgrade. dns01.check now skips the recursive resolvers unless disable_recursive_ns_propagation is explicitly false. The challenge form starts with "Check public resolvers" off, reads a missing option as off, and lists the switch in the summary only when it differs from that default. Refs 0xJacky/nginx-ui#2115 Co-Authored-By: Claude Opus 5.5 --- README.md | 14 +++--- provider/check_options_test.go | 81 +++++++++++++++++++++++++++++++++ provider/provider.go | 39 ++++++++++++++-- webapp/src/DnsChallengeSlot.vue | 17 +++++-- 4 files changed, 135 insertions(+), 16 deletions(-) create mode 100644 provider/check_options_test.go diff --git a/README.md b/README.md index 9a03f45..4385f65 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,10 @@ waits for the record to propagate and cleans it up afterwards. * Credential validation without issuing a certificate: the plugin builds the provider from the values you entered and reports the first field that is missing. -* Propagation check against the zone's authoritative nameservers and against - your recursive resolvers, with CNAME delegation support. -* Per-certificate switches to disable CNAME following, the authoritative check - or the recursive check when a network does not allow them. +* Propagation check against the zone's authoritative nameservers, with CNAME + delegation support, and on request against your recursive resolvers. +* Per-certificate switches to disable CNAME following or the authoritative + check, and to turn on the recursive check. * Propagation timings reported per provider, so NGINX UI waits as long as the vendor actually needs instead of using one global timeout. * Runs on demand: the host starts the process when a certificate needs it and @@ -58,7 +58,7 @@ Per-certificate options travel with the request rather than the settings: | --- | --- | | `disable_cname` | Do not follow the challenge record's CNAME. Also exported as `LEGO_DISABLE_CNAME_SUPPORT` for the duration of the call. | | `disable_authoritative_ns_propagation` | Skip the authoritative nameserver check. | -| `disable_recursive_ns_propagation` | Skip the recursive nameserver check. | +| `disable_recursive_ns_propagation` | Set it to `false` to also wait for the recursive nameservers. When it is missing or `true` the check stays on the authoritative nameservers, as NGINX UI did before the providers moved into this plugin: local resolvers such as systemd-resolved often do not return a fresh TXT record in time. | ## Credential fields @@ -113,8 +113,8 @@ plugin. [@nginxui/plugin-sdk](https://github.com/nginxui/plugin-sdk-web), that replaces the host's built-in DNS-01 challenge form (`certificate.challenge.form:dns01`) with one that also exposes the plugin's -own per-certificate options: disabling CNAME following, and skipping the -authoritative or the recursive nameserver propagation check. +own per-certificate options: disabling CNAME following, skipping the +authoritative nameserver check and turning on the recursive one. ```bash cd webapp diff --git a/provider/check_options_test.go b/provider/check_options_test.go new file mode 100644 index 0000000..3ddcd0c --- /dev/null +++ b/provider/check_options_test.go @@ -0,0 +1,81 @@ +package provider + +import ( + "strings" + "testing" + + "github.com/nginxui/plugin-sdk-go/protocol" +) + +// The recursive check is opt-in: a certificate that never set the option only +// waits for the authoritative nameservers, as NGINX UI 2.x did. +func TestCheckOptionsRecursiveCheckIsOptIn(t *testing.T) { + cases := []struct { + name string + options map[string]any + skipRecursive bool + }{ + {name: "no options", options: nil, skipRecursive: true}, + {name: "option missing", options: map[string]any{protocol.DNS01OptionDisableCNAME: true}, skipRecursive: true}, + {name: "disabled", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: true}, skipRecursive: true}, + {name: "turned on", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: false}, skipRecursive: false}, + {name: "turned on as string", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: "false"}, skipRecursive: false}, + {name: "turned on as number", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: float64(0)}, skipRecursive: false}, + {name: "unreadable value", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: "maybe"}, skipRecursive: true}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := checkOptions(protocol.DNS01CheckParams{FQDN: "_acme-challenge.example.com.", Value: "v", Options: tc.options}, Settings{}) + if got.DisableRecursiveNSPropagation != tc.skipRecursive { + t.Fatalf("DisableRecursiveNSPropagation = %v, want %v", got.DisableRecursiveNSPropagation, tc.skipRecursive) + } + }) + } +} + +// The other switches and the settings pass through unchanged. +func TestCheckOptionsKeepsTheOtherSwitches(t *testing.T) { + params := protocol.DNS01CheckParams{ + FQDN: "_acme-challenge.example.com.", + Value: "v", + Options: map[string]any{ + protocol.DNS01OptionDisableCNAME: true, + protocol.DNS01OptionDisableAuthoritativeNSPropagation: true, + }, + } + got := checkOptions(params, Settings{RecursiveNameservers: []string{"9.9.9.9:53"}}) + + if !got.DisableCNAME || !got.DisableAuthoritativeNSPropagation { + t.Fatalf("switches = %+v, want CNAME and authoritative checks off", got) + } + if got.FQDN != params.FQDN || got.Value != params.Value { + t.Fatalf("record = %q %q, want %q %q", got.FQDN, got.Value, params.FQDN, params.Value) + } + if len(got.RecursiveNameservers) != 1 || got.RecursiveNameservers[0] != "9.9.9.9:53" { + t.Fatalf("RecursiveNameservers = %v, want the plugin setting", got.RecursiveNameservers) + } +} + +// Through the handler: with the option missing, a recursive resolver that +// never answers must not be what holds the check up. +func TestCheckSkipsRecursiveResolversByDefault(t *testing.T) { + h := New() + // Nothing listens here, every query fails at once. + h.SetSettings(Settings{RecursiveNameservers: []string{"127.0.0.1:1"}}) + + result, err := h.Check(t.Context(), protocol.DNS01CheckParams{ + FQDN: "_acme-challenge.example.com.", + Value: "value", + Options: map[string]any{protocol.DNS01OptionDisableCNAME: true}, + }) + if err != nil { + t.Fatalf("Check: %v", err) + } + if result.Ready { + t.Fatal("Check reported ready without any nameserver answering") + } + if strings.HasPrefix(result.Detail, "recursive nameservers:") { + t.Fatalf("Detail = %q, the recursive check ran although the certificate never asked for it", result.Detail) + } +} diff --git a/provider/provider.go b/provider/provider.go index 377198b..6af7663 100644 --- a/provider/provider.go +++ b/provider/provider.go @@ -295,18 +295,26 @@ func (h *Handler) Validate(_ context.Context, providerCode string, config map[st // Check runs the DNS propagation check for one challenge record. func (h *Handler) Check(ctx context.Context, params protocol.DNS01CheckParams) (protocol.DNS01CheckResult, error) { - settings := h.settingsFor(ctx) + return check.Propagated(ctx, checkOptions(params, h.settingsFor(ctx))) +} - opts := check.Options{ +// checkOptions maps a check request onto the checker options. +// +// The recursive check only runs when the certificate asked for it by setting +// disable_recursive_ns_propagation to false. Before the providers moved into +// this plugin, NGINX UI only waited for the authoritative nameservers, because +// local resolvers such as systemd-resolved at 127.0.0.53 often do not return a +// fresh TXT record in time (0xJacky/nginx-ui#1711, #1719). Certificates that +// never set the option keep that behaviour. +func checkOptions(params protocol.DNS01CheckParams, settings Settings) check.Options { + return check.Options{ FQDN: params.FQDN, Value: params.Value, RecursiveNameservers: settings.RecursiveNameservers, DisableCNAME: boolOption(params.Options, protocol.DNS01OptionDisableCNAME), DisableAuthoritativeNSPropagation: boolOption(params.Options, protocol.DNS01OptionDisableAuthoritativeNSPropagation), - DisableRecursiveNSPropagation: boolOption(params.Options, protocol.DNS01OptionDisableRecursiveNSPropagation), + DisableRecursiveNSPropagation: !optionSetToFalse(params.Options, protocol.DNS01OptionDisableRecursiveNSPropagation), } - - return check.Propagated(ctx, opts) } // applyCNAMEOption exports LEGO_DISABLE_CNAME_SUPPORT for the duration of the @@ -341,6 +349,27 @@ func boolOption(options map[string]any, key string) bool { } } +// optionSetToFalse reports whether a per-certificate option is present and +// false, as opposed to missing. +func optionSetToFalse(options map[string]any, key string) bool { + v, ok := options[key] + if !ok { + return false + } + + switch value := v.(type) { + case bool: + return !value + case string: + parsed, err := strconv.ParseBool(strings.TrimSpace(value)) + return err == nil && !parsed + case float64: + return value == 0 + default: + return false + } +} + // missingCredentialsPrefix is the message lego's env helper produces when a // required variable is empty. const missingCredentialsPrefix = "some credentials information are missing:" diff --git a/webapp/src/DnsChallengeSlot.vue b/webapp/src/DnsChallengeSlot.vue index 289ad82..800d3ee 100644 --- a/webapp/src/DnsChallengeSlot.vue +++ b/webapp/src/DnsChallengeSlot.vue @@ -56,6 +56,8 @@ interface CheckItem { title: string description: string offSummary: string + /** The state a certificate that never set the option gets. */ + defaultOn: boolean } const props = defineProps<{ @@ -88,7 +90,7 @@ const isAdvancedOpen = ref(false) const checks = reactive>({ followCname: true, checkAuthoritative: true, - checkRecursive: true, + checkRecursive: false, }) const checkItems = computed(() => [ @@ -97,24 +99,29 @@ const checkItems = computed(() => [ title: $t('Follow CNAME'), description: $t('Keep on when the validation record of a domain is delegated to another domain.'), offSummary: $t('CNAME following off'), + defaultOn: true, }, { key: 'checkAuthoritative', title: $t('Check authoritative servers'), description: $t('When off, waits a fixed 60 seconds before asking for validation.'), offSummary: $t('Authoritative server check off'), + defaultOn: true, }, { key: 'checkRecursive', title: $t('Check public resolvers'), description: $t('Confirms the record is visible through the recursive DNS servers set in the plugin settings.'), offSummary: $t('Public resolver check off'), + defaultOn: false, }, ]) const changedSummary = computed(() => checkItems.value - .filter(item => !checks[item.key]) - .map(item => item.offSummary)) + .filter(item => checks[item.key] !== item.defaultOn) + .map(item => checks[item.key] + ? item.title + : item.offSummary)) const openCredentialEditor = shared.ui?.openDnsCredentialEditor @@ -267,7 +274,9 @@ function initSwitches() { const config = props.context.options.challenge_config ?? {} checks.followCname = !config.disable_cname checks.checkAuthoritative = !config.disable_authoritative_ns_propagation - checks.checkRecursive = !config.disable_recursive_ns_propagation + // Off unless the certificate turned it on, matching what the plugin does + // when the option is missing. + checks.checkRecursive = config.disable_recursive_ns_propagation === false } // Mirrors the switches and the selected credential into challenge_config, the From 02da2b95ac46a26ba3b0156699a6b436ba1c55de Mon Sep 17 00:00:00 2001 From: Jacky Date: Thu, 12 Nov 2026 20:18:03 +0800 Subject: [PATCH 2/2] fix: turn the recursive check on with its own option and keep the fixed wait Review of the previous commit found two problems: - The 1.0.0 challenge form wrote disable_recursive_ns_propagation: false for every certificate it saved, so reading an explicit false as opt-in kept the recursive check on for exactly those certificates. The check is now turned on by check_recursive_ns_propagation, and the older option can only keep it off. - With the authoritative check off and the recursive check now off by default, check.Propagated reported the record ready at once. dns01.check now answers unsupported when both checks are off, so NGINX UI waits its fixed 60 seconds first, as the challenge form says. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 +- provider/check_options_test.go | 65 +++++++++++++++++++++++++++++---- provider/provider.go | 50 +++++++++++-------------- webapp/src/DnsChallengeSlot.vue | 9 +++-- 4 files changed, 86 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 4385f65..be7e783 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,8 @@ Per-certificate options travel with the request rather than the settings: | Option | Effect | | --- | --- | | `disable_cname` | Do not follow the challenge record's CNAME. Also exported as `LEGO_DISABLE_CNAME_SUPPORT` for the duration of the call. | -| `disable_authoritative_ns_propagation` | Skip the authoritative nameserver check. | -| `disable_recursive_ns_propagation` | Set it to `false` to also wait for the recursive nameservers. When it is missing or `true` the check stays on the authoritative nameservers, as NGINX UI did before the providers moved into this plugin: local resolvers such as systemd-resolved often do not return a fresh TXT record in time. | +| `disable_authoritative_ns_propagation` | Skip the authoritative nameserver check. When the recursive check is off too, `dns01.check` reports itself unsupported and NGINX UI waits a fixed 60 seconds instead. | +| `check_recursive_ns_propagation` | Also wait for the recursive nameservers. Off by default: the check stays on the authoritative nameservers, as NGINX UI did before the providers moved into this plugin, because local resolvers such as systemd-resolved often do not return a fresh TXT record in time. The older `disable_recursive_ns_propagation` option is no longer read. | ## Credential fields diff --git a/provider/check_options_test.go b/provider/check_options_test.go index 3ddcd0c..0cd2105 100644 --- a/provider/check_options_test.go +++ b/provider/check_options_test.go @@ -1,14 +1,17 @@ package provider import ( + "errors" "strings" "testing" "github.com/nginxui/plugin-sdk-go/protocol" ) -// The recursive check is opt-in: a certificate that never set the option only -// waits for the authoritative nameservers, as NGINX UI 2.x did. +// The recursive check is opt-in: a certificate that never turned it on only +// waits for the authoritative nameservers, as NGINX UI 2.x did. The false value +// of the older disable option, written by the 1.0.0 form for every +// certificate, does not turn it on. func TestCheckOptionsRecursiveCheckIsOptIn(t *testing.T) { cases := []struct { name string @@ -17,11 +20,19 @@ func TestCheckOptionsRecursiveCheckIsOptIn(t *testing.T) { }{ {name: "no options", options: nil, skipRecursive: true}, {name: "option missing", options: map[string]any{protocol.DNS01OptionDisableCNAME: true}, skipRecursive: true}, - {name: "disabled", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: true}, skipRecursive: true}, - {name: "turned on", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: false}, skipRecursive: false}, - {name: "turned on as string", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: "false"}, skipRecursive: false}, - {name: "turned on as number", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: float64(0)}, skipRecursive: false}, - {name: "unreadable value", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: "maybe"}, skipRecursive: true}, + {name: "legacy disable false", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: false}, skipRecursive: true}, + {name: "legacy disable true", options: map[string]any{protocol.DNS01OptionDisableRecursiveNSPropagation: true}, skipRecursive: true}, + {name: "turned off", options: map[string]any{optionCheckRecursiveNSPropagation: false}, skipRecursive: true}, + {name: "turned on", options: map[string]any{optionCheckRecursiveNSPropagation: true}, skipRecursive: false}, + {name: "turned on as string", options: map[string]any{optionCheckRecursiveNSPropagation: "true"}, skipRecursive: false}, + { + name: "turned on with a legacy false", + options: map[string]any{ + optionCheckRecursiveNSPropagation: true, + protocol.DNS01OptionDisableRecursiveNSPropagation: false, + }, + skipRecursive: false, + }, } for _, tc := range cases { @@ -79,3 +90,43 @@ func TestCheckSkipsRecursiveResolversByDefault(t *testing.T) { t.Fatalf("Detail = %q, the recursive check ran although the certificate never asked for it", result.Detail) } } + +// With both nameserver checks off the plugin must not report the record as +// ready on the spot: it hands the wait back to the host, which waits a fixed +// time before asking for validation. +func TestCheckWithBothChecksOffDefersToTheHost(t *testing.T) { + h := New() + _, err := h.Check(t.Context(), protocol.DNS01CheckParams{ + FQDN: "_acme-challenge.example.com.", + Value: "value", + Options: map[string]any{protocol.DNS01OptionDisableAuthoritativeNSPropagation: true}, + }) + + var rpcErr *protocol.Error + if !errors.As(err, &rpcErr) || rpcErr.Code != protocol.CodeUnsupported { + t.Fatalf("Check = %v, want an unsupported error so the host waits instead", err) + } +} + +// With the authoritative check off and the recursive one on, the recursive +// resolvers are still queried. +func TestCheckWithOnlyTheRecursiveCheckQueriesIt(t *testing.T) { + h := New() + h.SetSettings(Settings{RecursiveNameservers: []string{"127.0.0.1:1"}}) + + result, err := h.Check(t.Context(), protocol.DNS01CheckParams{ + FQDN: "_acme-challenge.example.com.", + Value: "value", + Options: map[string]any{ + protocol.DNS01OptionDisableCNAME: true, + protocol.DNS01OptionDisableAuthoritativeNSPropagation: true, + optionCheckRecursiveNSPropagation: true, + }, + }) + if err != nil { + t.Fatalf("Check: %v", err) + } + if result.Ready || !strings.HasPrefix(result.Detail, "recursive nameservers:") { + t.Fatalf("result = %+v, want not ready on the recursive check", result) + } +} diff --git a/provider/provider.go b/provider/provider.go index 6af7663..f7e4a58 100644 --- a/provider/provider.go +++ b/provider/provider.go @@ -293,19 +293,32 @@ func (h *Handler) Validate(_ context.Context, providerCode string, config map[st return nil } +// optionCheckRecursiveNSPropagation turns the recursive resolver check on for +// a certificate. It replaces disable_recursive_ns_propagation, whose false +// value the challenge form of 1.0.0 wrote for every certificate it saved. +const optionCheckRecursiveNSPropagation = "check_recursive_ns_propagation" + // Check runs the DNS propagation check for one challenge record. +// +// With both nameserver checks off nothing is left to query. The plugin then +// reports dns01.check as unsupported, and NGINX UI waits a fixed time before +// asking for validation, as the challenge form describes. func (h *Handler) Check(ctx context.Context, params protocol.DNS01CheckParams) (protocol.DNS01CheckResult, error) { - return check.Propagated(ctx, checkOptions(params, h.settingsFor(ctx))) + opts := checkOptions(params, h.settingsFor(ctx)) + if opts.DisableAuthoritativeNSPropagation && opts.DisableRecursiveNSPropagation { + return protocol.DNS01CheckResult{}, sdk.Unsupported(protocol.MethodDNS01Check) + } + return check.Propagated(ctx, opts) } // checkOptions maps a check request onto the checker options. // -// The recursive check only runs when the certificate asked for it by setting -// disable_recursive_ns_propagation to false. Before the providers moved into -// this plugin, NGINX UI only waited for the authoritative nameservers, because -// local resolvers such as systemd-resolved at 127.0.0.53 often do not return a -// fresh TXT record in time (0xJacky/nginx-ui#1711, #1719). Certificates that -// never set the option keep that behaviour. +// The recursive check only runs when the certificate turned it on with +// check_recursive_ns_propagation. Before the providers moved into this plugin, +// NGINX UI only waited for the authoritative nameservers, because local +// resolvers such as systemd-resolved at 127.0.0.53 often do not return a fresh +// TXT record in time (0xJacky/nginx-ui#1711, #1719). The older +// disable_recursive_ns_propagation option can only keep the check off. func checkOptions(params protocol.DNS01CheckParams, settings Settings) check.Options { return check.Options{ FQDN: params.FQDN, @@ -313,7 +326,7 @@ func checkOptions(params protocol.DNS01CheckParams, settings Settings) check.Opt RecursiveNameservers: settings.RecursiveNameservers, DisableCNAME: boolOption(params.Options, protocol.DNS01OptionDisableCNAME), DisableAuthoritativeNSPropagation: boolOption(params.Options, protocol.DNS01OptionDisableAuthoritativeNSPropagation), - DisableRecursiveNSPropagation: !optionSetToFalse(params.Options, protocol.DNS01OptionDisableRecursiveNSPropagation), + DisableRecursiveNSPropagation: !boolOption(params.Options, optionCheckRecursiveNSPropagation), } } @@ -349,27 +362,6 @@ func boolOption(options map[string]any, key string) bool { } } -// optionSetToFalse reports whether a per-certificate option is present and -// false, as opposed to missing. -func optionSetToFalse(options map[string]any, key string) bool { - v, ok := options[key] - if !ok { - return false - } - - switch value := v.(type) { - case bool: - return !value - case string: - parsed, err := strconv.ParseBool(strings.TrimSpace(value)) - return err == nil && !parsed - case float64: - return value == 0 - default: - return false - } -} - // missingCredentialsPrefix is the message lego's env helper produces when a // required variable is empty. const missingCredentialsPrefix = "some credentials information are missing:" diff --git a/webapp/src/DnsChallengeSlot.vue b/webapp/src/DnsChallengeSlot.vue index 800d3ee..ea0ddaa 100644 --- a/webapp/src/DnsChallengeSlot.vue +++ b/webapp/src/DnsChallengeSlot.vue @@ -274,9 +274,10 @@ function initSwitches() { const config = props.context.options.challenge_config ?? {} checks.followCname = !config.disable_cname checks.checkAuthoritative = !config.disable_authoritative_ns_propagation - // Off unless the certificate turned it on, matching what the plugin does - // when the option is missing. - checks.checkRecursive = config.disable_recursive_ns_propagation === false + // Off unless the certificate turned it on. The disable_recursive_ns_propagation + // value earlier versions wrote is not read: it was false for every + // certificate they saved. + checks.checkRecursive = config.check_recursive_ns_propagation === true } // Mirrors the switches and the selected credential into challenge_config, the @@ -295,7 +296,7 @@ watch( credential_id: credentialId ? String(credentialId) : '', disable_cname: !checks.followCname, disable_authoritative_ns_propagation: !checks.checkAuthoritative, - disable_recursive_ns_propagation: !checks.checkRecursive, + check_recursive_ns_propagation: checks.checkRecursive, } }, )