diff options
Diffstat (limited to 'src/knot/modules/whoami/whoami.rst')
-rw-r--r-- | src/knot/modules/whoami/whoami.rst | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/src/knot/modules/whoami/whoami.rst b/src/knot/modules/whoami/whoami.rst new file mode 100644 index 0000000..25d0174 --- /dev/null +++ b/src/knot/modules/whoami/whoami.rst @@ -0,0 +1,97 @@ +.. _mod-whoami: + +``whoami`` — Whoami response +============================ + +The module synthesizes an A or AAAA record containing the query source IP address, +at the apex of the zone being served. It makes sure to allow Knot DNS to generate +cacheable negative responses, and to allow fallback to extra records defined in the +underlying zone file. The TTL of the synthesized record is copied from +the TTL of the SOA record in the zone file. + +Because a DNS query for type A or AAAA has nothing to do with whether +the query occurs over IPv4 or IPv6, this module requires a special +zone configuration to support both address families. For A queries, the +underlying zone must have a set of nameservers that only have IPv4 +addresses, and for AAAA queries, the underlying zone must have a set of +nameservers that only have IPv6 addresses. + +Example +------- + +To enable this module, you need to add something like the following to +the Knot DNS configuration file:: + + zone: + - domain: whoami.domain.example + file: "/path/to/whoami.domain.example" + module: mod-whoami + + zone: + - domain: whoami6.domain.example + file: "/path/to/whoami6.domain.example" + module: mod-whoami + +The whoami.domain.example zone file example: + + .. code-block:: none + + $TTL 1 + + @ SOA ( + whoami.domain.example. ; MNAME + hostmaster.domain.example. ; RNAME + 2016051300 ; SERIAL + 86400 ; REFRESH + 86400 ; RETRY + 86400 ; EXPIRE + 1 ; MINIMUM + ) + + $TTL 86400 + + @ NS ns1.whoami.domain.example. + @ NS ns2.whoami.domain.example. + @ NS ns3.whoami.domain.example. + @ NS ns4.whoami.domain.example. + + ns1 A 198.51.100.53 + ns2 A 192.0.2.53 + ns3 A 203.0.113.53 + ns4 A 198.19.123.53 + +The whoami6.domain.example zone file example: + + .. code-block:: none + + $TTL 1 + + @ SOA ( + whoami6.domain.example. ; MNAME + hostmaster.domain.example. ; RNAME + 2016051300 ; SERIAL + 86400 ; REFRESH + 86400 ; RETRY + 86400 ; EXPIRE + 1 ; MINIMUM + ) + + $TTL 86400 + + @ NS ns1.whoami6.domain.example. + @ NS ns2.whoami6.domain.example. + @ NS ns3.whoami6.domain.example. + @ NS ns4.whoami6.domain.example. + + ns1 AAAA 2001:db8:100::53 + ns2 AAAA 2001:db8:200::53 + ns3 AAAA 2001:db8:300::53 + ns4 AAAA 2001:db8:400::53 + +The parent domain would then delegate whoami.domain.example to +ns[1-4].whoami.domain.example and whoami6.domain.example to +ns[1-4].whoami6.domain.example, and include the corresponding A-only or +AAAA-only glue records. + +.. NOTE:: + This module is not configurable. |