From 07c70ea2bd2b4ba5051a74cd18cc4030628360c8 Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Tue, 22 Aug 2023 11:45:41 +0200 Subject: [PATCH 1/4] Fix keys reference link in ARM There's a statement that says: "Here is an example (for illustration purposes only) of some possible entries in a [keys] list:", and that links to the wrong "keys" statement (it links to the TSIG keys section). Remove the reference, as we are already in the right section. --- doc/arm/reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 2e131908e9..7f73cc4434 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6162,7 +6162,7 @@ The following options can be specified in a :any:`dnssec-policy` statement: DNSKEY RRset always includes a key-signing key for that algorithm. Here is an example (for illustration purposes only) of some possible - entries in a :any:`keys` list: + entries in a ``keys`` list: :: From cc122d22b46af7117b034d0732a3074e349e8e98 Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Tue, 22 Aug 2023 11:48:37 +0200 Subject: [PATCH 2/4] Add a glossary definition for duration We don't yet explain the syntax of TTL-style suffixes or ISO 8601 duration formats. --- doc/arm/reference.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 7f73cc4434..7db5efd642 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -314,6 +314,26 @@ file documentation: ``domain_name`` A quoted string which is used as a DNS name; for example: ``my.test.domain``. + ``duration`` + A duration in BIND 9 can be written in three ways: as single number + representing seconds, as a string of numbers with TTL-style + time-unit suffixes, or in ISO 6801 duration format. + + Allowed TTL time-unit suffixes are: "W" (week), "D" (day), "H" (hour), + "M" (minute), and "S" (second). Examples: "1W" (1 week), "3d12h" + (3 days, 12 hours). + + ISO 8601 duration format consists of the letter "P", followed by an + optional series of numbers with unit suffixes "Y" (year), "M" (month), + "W" (week), and "D" (day); this may optionally be followed by the + letter "T", and another series of numbers with unit suffixes + "H" (hour), "M" (minute), and "S" (second). Examples: "P3M10D" + (3 months, 10 days), "P2WT12H" (2 weeks, 12 hours), "pt15m" + (15 minutes). For more information on ISO 8601 duration format, + see :rfc:`3339`, appendix A. + + Both TTL-style and ISO 8601 duration formats are case-insensitive. + ``fixedpoint`` A non-negative real number that can be specified to the nearest one-hundredth. Up to five digits can be specified before a decimal point, and up to two digits after, so the maximum value is 99999.99. Acceptable values might be further limited by the contexts in which they are used. From b5a757c4525aa29a9bdb6037dbe40dd079394d8c Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Tue, 22 Aug 2023 11:49:22 +0200 Subject: [PATCH 3/4] Explain lifetime format Add the text "TTL-style unit suffixes or ISO 8601 duration formats", just like we do at other places that are duration option types. Also, in the dnssec-policy "keys" example, use a TTL-style unit too. --- doc/arm/reference.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 7db5efd642..065f05ccce 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6188,7 +6188,7 @@ The following options can be specified in a :any:`dnssec-policy` statement: keys { ksk key-directory lifetime unlimited algorithm rsasha256 2048; - zsk lifetime P30D algorithm 8; + zsk lifetime 30d algorithm 8; csk lifetime P6MT12H3M15S algorithm ecdsa256; }; @@ -6207,7 +6207,11 @@ The following options can be specified in a :any:`dnssec-policy` statement: keys in hardware security modules or separate directories. The ``lifetime`` parameter specifies how long a key may be used - before rolling over. In the example above, the first key has an + before rolling over. For convenience, TTL-style time-unit suffixes + can be used to specify the key lifetime. It also accepts ISO 8601 + duration formats. + + In the example above, the first key has an unlimited lifetime, the second key may be used for 30 days, and the third key has a rather peculiar lifetime of 6 months, 12 hours, 3 minutes, and 15 seconds. A lifetime of 0 seconds is the same as From fd3d58d512fd79de3d51037bf1685df42fa05d8e Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Tue, 22 Aug 2023 11:51:25 +0200 Subject: [PATCH 4/4] Add CHANGES entry for #4266 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 6635e2417b..778c0b3056 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,5 @@ +6235. [doc] Clarify BIND 9 time formats. [GL #4266] + 6234. [bug] Restore stale-refresh-time value after flushing the cache. [GL #4278]