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] diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 178c26c97f..0f6758ec69 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. @@ -6377,13 +6397,13 @@ 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: :: keys { ksk key-directory lifetime unlimited algorithm rsasha256 2048; - zsk lifetime P30D algorithm 8; + zsk lifetime 30d algorithm 8; csk lifetime P6MT12H3M15S algorithm ecdsa256; }; @@ -6402,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