From caf5eeb1410b80e08f4f8117dade5ba630cf1f65 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. (cherry picked from commit 07c70ea2bd2b4ba5051a74cd18cc4030628360c8) --- 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 178c26c97f..800a2cfed7 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6377,7 +6377,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 a3f94bf0025ed33d0a59e464081a11b6e30560f1 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. (cherry picked from commit cc122d22b46af7117b034d0732a3074e349e8e98) --- doc/arm/reference.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 800a2cfed7..2836eea255 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 44cd3788ac3ba86ade9a3dc0ac9dd5708f9ad709 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. (cherry picked from commit b5a757c4525aa29a9bdb6037dbe40dd079394d8c) --- 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 2836eea255..0f6758ec69 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6403,7 +6403,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; }; @@ -6422,7 +6422,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 41085510a6ebd584d7e5c6ad9186b8446cbefdd1 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 (cherry picked from commit fd3d58d512fd79de3d51037bf1685df42fa05d8e) --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 89a13719f6..b6f4860471 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,8 @@ 6237. [bug] Address memory leaks due to not clearing OpenSSL error stack. [GL #4159] +6235. [doc] Clarify BIND 9 time formats. [GL #4266] + 6234. [bug] Restore stale-refresh-time value after flushing the cache. [GL #4278]