From fd9a5746807a214ecd638e1cf86d3dce8924af35 Mon Sep 17 00:00:00 2001 From: BradKollmyer Date: Fri, 11 Sep 2026 04:42:42 -0700 Subject: firewall: T9076: document remote-group update interval (#2148) * firewall: T9076: document remote-group update interval Document the new 'set firewall group remote-group interval' command: per-group update interval from 60 seconds to 4 weeks, given as plain seconds or with s/m/h/d/w suffixes (e.g. 4h), falling back to the global resolver-interval when unset. Co-Authored-By: Claude Fable 5 * firewall: T9076: note URL quoting and log redaction for remote-group Warn that remote-group URLs with query strings must be quoted (unquoted '&' silently truncates the value; literal '?' may need Ctrl-V, see T9077) and that vyos-domain-resolver logs redact the query string on download failures (T8829). Co-Authored-By: Claude Fable 5 * firewall: T9076: note that remote-group interval suffixes may be combined Address review feedback: document that s/m/h/d/w units can be stacked (e.g. 1h30m), matching human_to_seconds and the CLI regex. --------- Co-authored-by: Claude Fable 5 --- docs/configuration/firewall/groups.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/configuration/firewall/groups.md b/docs/configuration/firewall/groups.md index 817f610e..d364d2d7 100644 --- a/docs/configuration/firewall/groups.md +++ b/docs/configuration/firewall/groups.md @@ -43,9 +43,10 @@ Provide an IPv4 or IPv6 address group description. A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically -according to the frequency you define in the firewall **resolver-interval** -and loads matching entries into the group for use in rules. The list is cached -in persistent storage, so rules continue to function if updates fail. +according to the frequency you define in the group **interval** (or, if not +set, the firewall **resolver-interval**) and loads matching entries into the +group for use in rules. The list is cached in persistent storage, so rules +continue to function if updates fail. ```{cfgcmd} set firewall group remote-group \ url \ @@ -53,6 +54,33 @@ Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs to fetch. ``` +::::{note} +Quote URLs that contain a query string, otherwise an unquoted `&` silently +truncates the value. On releases where the `?` key always triggers +completion help, enter the literal `?` by pressing `Ctrl-V` followed by +`?`: + +``` none +set firewall group remote-group AbuseIPDB url 'https://api.abuseipdb.com/api/v2/blacklist?key=YOUR_KEY&plaintext' +``` +:::: + +::::{note} +When a download fails, `vyos-domain-resolver` logs a redacted URL with the +query string removed, keeping API keys out of the system log. A logged URL +without its query parameters does not mean the configured value is wrong — +verify it with `show firewall group remote-group url` instead. +:::: + +```{cfgcmd} set firewall group remote-group \ interval \ + +Set the update interval for this remote group, from 60 seconds to 4 weeks. +The interval can be given in seconds (e.g. `300`) or with the time unit +suffixes `s`, `m`, `h`, `d` or `w` (e.g. `4h`). Multiple suffixes may be +combined (e.g. `1h30m`). If not set, the group follows the global +`firewall global-options resolver-interval`. +``` + ```{cfgcmd} set firewall group remote-group \ description \ Set a description for a remote group. -- cgit v1.2.3