From 84cdcf970bd3556f2e0724a69c26040915ae939a Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Thu, 7 Jan 2016 13:13:47 +0100 Subject: [PATCH] Several improvements to the modes of operation Move TSIG related information to a separate TSIG page. Rename the modes of operation page to something a little more understandible. --- .../authoritative/backend-generic-sql.md | 7 + docs/markdown/authoritative/domainmetadata.md | 20 +- docs/markdown/authoritative/gss-tsig.md | 15 -- .../authoritative/modes-of-operation.md | 205 +++++++++--------- docs/markdown/authoritative/tsig.md | 112 ++++++++++ docs/mkdocs.yml | 8 +- 6 files changed, 233 insertions(+), 134 deletions(-) delete mode 100644 docs/markdown/authoritative/gss-tsig.md create mode 100644 docs/markdown/authoritative/tsig.md diff --git a/docs/markdown/authoritative/backend-generic-sql.md b/docs/markdown/authoritative/backend-generic-sql.md index b463f28e5..ff344c2f4 100644 --- a/docs/markdown/authoritative/backend-generic-sql.md +++ b/docs/markdown/authoritative/backend-generic-sql.md @@ -52,6 +52,13 @@ large installations may need to raise this value. Once a domain has been checked it will not be checked before its SOA refresh timer has expired. Domains whose status is unknown get checked every 60 seconds by default. +PowerDNS has support for multiple masters per zone, separate master IP addresses +by commas: + +``` +INSERT INTO domains (name, master, type) VALUES ('example.com', '198.51.100.6, 2001:0DB8:15:4AF::4', 'SLAVE'); +``` + ## Superslave operation To configure a supermaster with IP address 203.0.113.53 which lists this installation as 'autoslave.example.com', issue the following: diff --git a/docs/markdown/authoritative/domainmetadata.md b/docs/markdown/authoritative/domainmetadata.md index eb83dca4b..e1a0b61a5 100644 --- a/docs/markdown/authoritative/domainmetadata.md +++ b/docs/markdown/authoritative/domainmetadata.md @@ -16,10 +16,10 @@ tries to allow all potential slaves in. Example: ``` -sql> select id from domains where name='example.com'; +select id from domains where name='example.com'; 7 -sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','AUTO-NS'); -sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8::/48'); +insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','AUTO-NS'); +insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8::/48'); ``` ## AXFR-SOURCE @@ -32,16 +32,16 @@ See the documentation on [Dynamic DNS update](dnsupdate.md) When notifying this domain, also notify this nameserver (can occur multiple times). ## AXFR-MASTER-TSIG -Use this named TSIG key to retrieve this zone from its master (see -[Provisioning signed notification and AXFR requests](modes-of-operation.md#provisioning-signed-notification-and-axfr-requests)). +Use this named TSIG key to retrieve this zone from its master, see +[Provisioning signed notification and AXFR requests](tsig.md#provisioning-signed-notification-and-axfr-requests). ## GSS-ALLOW-AXFR-PRINCIPAL Allow this GSS principal to perform AXFR retrieval. Most commonly it is `host/something@REALM`, `DNS/something@REALM` or `user@REALM`. (See -[GSS-TSIG support](gss-tsig.md)). +[GSS-TSIG support](tsig.md#gss-tsig-support)). ## GSS-ACCEPTOR-PRINCIPAL -Use this principal for accepting GSS context. (See [GSS-TSIG support](gss-tsig.md)). +Use this principal for accepting GSS context. (See [GSS-TSIG support](tsig.md#gss-tsig-support)). ## LUA-AXFR-SCRIPT Script to be used to edit incoming AXFRs, see [Modifying a slave zone using a script](modes-of-operation.md#modifying-a-slave-zone-using-a-script). @@ -96,8 +96,8 @@ Available modes are: * NONE: Ignore [`default-soa-edit`](settings.md#default-soa-edit) and/or [`default-soa-edit-signed`](settings.md#default-soa-edit-signed) setings. ## TSIG-ALLOW-AXFR -Allow these named TSIG keys to AXFR this zone (see [Provisioning outbound AXFR access](modes-of-operation.md#provisioning-outbound-axfr-access)). +Allow these named TSIG keys to AXFR this zone, see [Provisioning outbound AXFR access](tsig.md#provisioning-outbound-axfr-access). ## TSIG-ALLOW-DNSUPDATE -This setting allows you to set the TSIG key required to do an DNS update. If -GSS-TSIG is enabled, you can put kerberos principals here as well. +This setting allows you to set the TSIG key required to do an [DNS update](dnsupdate.md). If +[GSS-TSIG](tsig.md#gss-tsig) is enabled, you can put kerberos principals here as well. diff --git a/docs/markdown/authoritative/gss-tsig.md b/docs/markdown/authoritative/gss-tsig.md deleted file mode 100644 index 727ad5565..000000000 --- a/docs/markdown/authoritative/gss-tsig.md +++ /dev/null @@ -1,15 +0,0 @@ -# GSS-TSIG support - -GSS-TSIG allows authentication and authorization of DNS updates or AXFR using Kerberos with TSIG signatures. NB! This feature is *experimental* and subject to change on future releases. - -## Prerequisites - -- Working Kerberos environment. Please refer to your Kerberos vendor documentation on how to setup it. -- Principal (such as DNS/@REALM) in either per-user keytab or system keytab. - -In particular, if something does not work, read logs and ensure that your kerberos environment is ok before filing an issue. Most common problems are time synchronization or changes done to the principal. - -## Setting up - -To allow AXFR / DNS update to work, you need to configure GSS-ACCEPTOR-PRINCIPAL in domain metadata. This will define the principal that is used to accept any GSS context requests. This *must* match to your keytab. Next -you need to define one or more GSS-ALLOW-AXFR-PRINCIPAL entries for AXFR, or TSIG-ALLOW-DNSUPDATE entries for DNS update. These must be set to the exact initiator principal names you intend to use. No wildcards accepted. diff --git a/docs/markdown/authoritative/modes-of-operation.md b/docs/markdown/authoritative/modes-of-operation.md index 9ba708b35..83b788c78 100644 --- a/docs/markdown/authoritative/modes-of-operation.md +++ b/docs/markdown/authoritative/modes-of-operation.md @@ -1,55 +1,101 @@ -PDNS offers full master and slave semantics for replicating domain information. Furthermore, PDNS can benefit from native database replication. +PDNS offers full master and slave semantics for replicating domain information. +Furthermore, PDNS can benefit from native database replication. # Native replication -Native replication is the default, unless other operation is specifically configured. Native replication basically means that PDNS will not send out DNS update notifications, nor will react to them. PDNS assumes that the backend is taking care of replication unaided. +Native replication is the default, unless other operation is specifically +configured. Native replication basically means that PDNS will not send out DNS +update notifications, nor will react to them. PDNS assumes that the backend is +taking care of replication unaided. -MySQL replication has proven to be very robust and well suited, even over transatlantic connections between badly peering ISPs. Other PDNS users employ Oracle replication which also works very well. +MySQL replication has proven to be very robust and well suited, even over +transatlantic connections between badly peering ISPs. Other PDNS users employ +Oracle replication which also works very well. -To use native replication, configure your backend storage to do the replication and do not configure PDNS to do so. +To use native replication, configure your backend storage to do the replication +and do not configure PDNS to do so. # Master operation -When operating as a master, PDNS sends out notifications of changes to slaves, which react to these notifications by querying PDNS to see if the zone changed, and transferring its contents if it has. Notifications are a way to promptly propagate zone changes to slaves, as described in [RFC 1996](http://tools.ietf.org/html/rfc1996). Since version 4.0.0, the NOTIFY messages have a TSIG record added (transaction signature) if zone has been configured to use TSIG and feature has been enabled. +When operating as a master, PDNS sends out notifications of changes to slaves, +which react to these notifications by querying PDNS to see if the zone changed, +and transferring its contents if it has. Notifications are a way to promptly +propagate zone changes to slaves, as described in [RFC 1996](http://tools.ietf.org/html/rfc1996). +Since version 4.0.0, the NOTIFY messages have a TSIG record added (transaction +signature) if zone has been configured to use TSIG and feature has been enabled. -**Warning**: Master support is OFF by default, turn it on by adding [`master`](settings.md#master) to the configuration. +**Warning**: Master support is OFF by default, turn it on by adding +[`master`](settings.md#master) to the configuration. -**Warning**: If you have DNSSEC-signed zones and non-PowerDNS slaves, please check your SOA-EDIT settings. +**Warning**: If you have DNSSEC-signed zones and non-PowerDNS slaves, please +check your [`SOA-EDIT`](domainmetadata.md#SOA-EDIT) settings. **Warning**: Notifications are only sent for domains with type MASTER in your backend. -Left open by RFC 1996 is who is to be notified - which is harder to figure out than it sounds. All slaves for this domain must receive a notification but the nameserver only knows the names of the slaves - not the IP addresses, which is where the problem lies. The nameserver itself might be authoritative for the name of its secondary, but not have the data available. +Left open by RFC 1996 is who is to be notified - which is harder to figure out +than it sounds. All slaves for this domain must receive a notification but the +nameserver only knows the names of the slaves - not the IP addresses, which is +where the problem lies. The nameserver itself might be authoritative for the name +of its secondary, but not have the data available. -To resolve this issue, PDNS tries multiple tactics to figure out the IP addresses of the slaves, and notifies everybody. In contrived configurations this may lead to duplicate notifications being sent out, which shouldn't hurt. +To resolve this issue, PowerDNS tries multiple tactics to figure out the IP +addresses of the slaves, and notifies everybody. In contrived configurations this +may lead to duplicate notifications being sent out, which shouldn't hurt. -Some backends may be able to detect zone changes, others may chose to let the operator indicate which zones have changed and which haven't. Consult the documentation for your backend to see how it processes changes in zones. +Some backends may be able to detect zone changes, others may chose to let the +operator indicate which zones have changed and which haven't. Consult the +documentation for your backend to see how it processes changes in zones. -To help deal with slaves that may have missed notifications, or have failed to respond to them, several override commands are available via the [`pdns_control`](../authoritative/internals.md#pdnscontrol) tool: +To help deal with slaves that may have missed notifications, or have failed to +respond to them, several override commands are available via the +[`pdns_control`](../authoritative/internals.md#pdnscontrol) tool: * `pdns_control notify ` This instructs PDNS to notify all IP addresses it considers to be slaves of this domain. * `pdns_control notify-host ` -This is truly an override and sends a notification to an arbitrary IP address. Can be used in [`also-notify`](settings.md#also-notify) situations or when PDNS has trouble figuring out who to notify - which may happen in contrived configurations. +This is truly an override and sends a notification to an arbitrary IP address. +Can be used in [`also-notify`](settings.md#also-notify) situations or when PowerDNS +has trouble figuring out who to notify - which may happen in contrived configurations. # Slave operation -On launch, PDNS requests from all backends a list of domains which have not been checked recently for changes. This should happen every '**refresh**' seconds, as specified in the SOA record. All domains that are unfresh are then checked for changes over at their master. If the [SOA](../types.md#soa) serial number there is higher, the domain is retrieved and inserted into the database. In any case, after the check the domain is declared 'fresh', and will only be checked again after '**refresh**' seconds have passed. +On launch, PDNS requests from all backends a list of domains which have not been +checked recently for changes. This should happen every '**refresh**' seconds, as +specified in the SOA record. All domains that are unfresh are then checked for +changes over at their master. If the [SOA](../types.md#soa) serial number there +is higher, the domain is retrieved and inserted into the database. In any case, +after the check the domain is declared 'fresh', and will only be checked again +after '**refresh**' seconds have passed. **Warning**: Slave support is OFF by default, turn it on by adding [`slave`](settings.md#slave) to the configuration. **Note**: When running PowerDNS via the provided systemd service file, [`ProtectSystem`](http://www.freedesktop.org/software/systemd/man/systemd.exec.html#ProtectSystem=) is set to `full`, this means PowerDNS is unable to write to e.g. `/etc` and `/home`, possibly being unable to write AXFR's zones. -PDNS also reacts to notifies by immediately checking if the zone has updated and if so, retransfering it. +PowerDNS also reacts to notifies by immediately checking if the zone has updated +and if so, retransfering it. -All backends which implement this feature must make sure that they can handle transactions so as to not leave the zone in a half updated state. MySQL configured with either BerkeleyDB or InnoDB meets this requirement, as do PostgreSQL and Oracle. The Bindbackend implements transaction semantics by renaming files if and only if they have been retrieved completely and parsed correctly. +All backends which implement this feature must make sure that they can handle +transactions so as to not leave the zone in a half updated state. MySQL configured +with either BerkeleyDB or InnoDB meets this requirement, as do PostgreSQL and +Oracle. The Bindbackend implements transaction semantics by renaming files if and +only if they have been retrieved completely and parsed correctly. -Slave operation can also be programmed using several [`pdns_control`](internals.md#pdnscontrol) commands. The `retrieve` command is especially useful as it triggers an immediate retrieval of the zone from the configured master. +Slave operation can also be programmed using several [`pdns_control`](internals.md#pdnscontrol) +commands. The `retrieve` command is especially useful as it triggers an immediate +retrieval of the zone from the configured master. -Since version 2.9.21, PowerDNS supports multiple masters. For the BIND backend, the native BIND configuration language suffices to specify multiple masters, for SQL based backends, list all master servers separated by commas in the 'master' field of the domains table. +PowerDNS supports multiple masters. For the BIND backend, the native BIND +configuration language suffices to specify multiple masters, for SQL based backends, +list all master servers separated by commas in the 'master' field of the domains table. Since version 4.0.0, PowerDNS requires that masters sign their notifications. During transition and interoperation with other nameservers, you can use options **allow-unsigned-notify** to permit unsigned notifications. For 4.0.0 this is turned off by default, but it might be turned on permanently in future releases. ## Supermaster: automatic provisioning of slaves -PDNS can recognize so called 'supermasters'. A supermaster is a host which is master for domains and for which we are to be a slave. When a master (re)loads a domain, it sends out a notification to its slaves. Normally, such a notification is only accepted if PDNS already knows that it is a slave for a domain. +PDNS can recognize so called 'supermasters'. A supermaster is a host which is +master for domains and for which we are to be a slave. When a master (re)loads a +domain, it sends out a notification to its slaves. Normally, such a notification +is only accepted if PowerDNS already knows that it is a slave for a domain. -However, a notification from a supermaster carries more persuasion. When PDNS determines that a notification comes from a supermaster and it is bonafide, PDNS can provision the domain automatically, and configure itself as a slave for that zone. +However, a notification from a supermaster carries more persuasion. When PowerDNS +determines that a notification comes from a supermaster and it is bonafide, it +can provision the domain automatically, and configure itself as a slave for that zone. Before a supermaster notification succeeds, the following conditions must be met: - The supermaster must carry a SOA record for the notified domain @@ -58,12 +104,24 @@ Before a supermaster notification succeeds, the following conditions must be met - If your master sends signed NOTIFY it will mark that TSIG key as the TSIG key used for retrieval as well - If you turn off **allow-unsigned-supermaster*, then your supermaster(s) are required to sign their notifications. -**Warning**: If you use another PowerDNS server as master and have DNSSEC enabled on that server please don't forget to rectify the domains after every change. If you don't do this there is no SOA record available and one requirement will fail. +**Warning**: If you use another PowerDNS server as master and have DNSSEC enabled +on that server please don't forget to rectify the domains after every change. If +you don't do this there is no SOA record available and one requirement will fail. -So, to benefit from this feature, a backend needs to know about the IP address of the supermaster, and how PDNS will be listed in the set of NS records remotely, and the 'account' name of your supermaster. There is no need to fill the account name out but it does help keep track of where a domain comes from. +So, to benefit from this feature, a backend needs to know about the IP address +of the supermaster, and how PowerDNS will be listed in the set of NS records +remotely, and the 'account' name of your supermaster. There is no need to fill +the account name out but it does help keep track of where a domain comes from. + +**Note**: Removal of zones provisioned using the supermaster must be done on the +slaves themselves. As there is no way to signal this removal from the master to +the slave. ## Modifying a slave zone using a script -As of version 3.0, the PowerDNS Authoritative Server can invoke a Lua script on an incoming AXFR zone transfer. The user-defined function `axfrfilter` within your script is invoked for each resource record read during the transfer, and the outcome of the function defines what PowerDNS does with the records. +The PowerDNS Authoritative Server can invoke a Lua script on an incoming AXFR +zone transfer. The user-defined function `axfrfilter` within your script is +invoked for each resource record read during the transfer, and the outcome of +the function defines what PowerDNS does with the records. What you can accomplish using a Lua script: - Ensure consistent values on SOA @@ -71,17 +129,28 @@ What you can accomplish using a Lua script: - Ensure consistent NS RRset - Timestamp the zone transfer with a TXT record -To enable a Lua script for a particular slave zone, determine the `domain_id` for the zone from the `domains` table, and add a row to the `domainmetadata` table for the domain. Supposing the domain we want has an `id` of 3, the following SQL statement will enable the Lua script `my.lua` for that domain: +To enable a Lua script for a particular slave zone, determine the `domain_id` +for the zone from the `domains` table, and add a row to the `domainmetadata` +table for the domain. Supposing the domain we want has an `id` of 3, the +following SQL statement will enable the Lua script `my.lua` for that domain: ``` - INSERT INTO domainmetadata (domain_id, kind, content) VALUES (3, "LUA-AXFR-SCRIPT", "/lua/my.lua"); +INSERT INTO domainmetadata (domain_id, kind, content) VALUES (3, "LUA-AXFR-SCRIPT", "/lua/my.lua"); ``` -The Lua script must both exist and be syntactically correct; if not, the zone transfer is not performed. +**Warning**: The Lua script must both exist and be syntactically correct; if not, +the zone transfer is not performed. -Your Lua functions have access to the query codes through a pre-defined Lua table called `pdns`. For example if you want to check for a CNAME record you can either compare `qtype` to the numeric constant 5 or the value `pdns.CNAME` -- they are equivalent. +Your Lua functions have access to the query codes through a pre-defined Lua table +called `pdns`. For example if you want to check for a CNAME record you can either +compare `qtype` to the numeric constant 5 or the value `pdns.CNAME` -- they are equivalent. -If your function decides to handle a resource record it must return a result code of 0 together with a Lua table containing one or more replacement records to be stored in the back-end database. If, on the other hand, your function decides not to modify a record, it must return pdns.PASS and an empty table indicating that PowerDNS should handle the incoming record as normal. If your function decides to drop a query and not respond whatsoever, it must return pdns.DROP and an empty table indicating that the recursor does not want to process the packet in Lua nor in the core recursor logic. +If your function decides to handle a resource record it must return a result code +of 0 together with a Lua table containing one or more replacement records to be +stored in the back-end database (if the table is empty, no record is added). +If, on the other hand, your function decides not to modify a record, it must +return pdns.PASS and an empty table indicating that PowerDNS should handle the +incoming record as normal. Consider the following simple example: @@ -120,81 +189,7 @@ Consider the following simple example: end ``` -Upon an incoming AXFR, PowerDNS calls our `axfrfilter` function for each record. All HINFO records are replaced by a TXT record with a TTL of 99 seconds and the specified string. TXT Records with names starting with `_tstamp.` get their value (rdata) set to the current time stamp. All other records are unhandled. - -# TSIG: shared secret authorization and authentication -**Note**: Available since PowerDNS Authoritative Server 3.0! - -TSIG, as defined in [RFC 2845](http://tools.ietf.org/html/rfc2845), is a method for signing DNS messages using shared secrets. Each TSIG shared secret has a name, and PowerDNS can be told to allow zone transfer of a domain if the request is signed with an authorized name. - -In PowerDNS, TSIG shared secrets are stored by the various backends. In case of the popular Generic backends, they can be found in the 'tsigkeys' table. The name can be chosen freely, but the algorithm name will typically be 'hmac-md5'. Other supported algorithms are 'hmac-sha1', 'hmac-shaX' where X is 224, 256, 384 or 512. The content is a Base64-encoded secret. - -**Note**: Most backends require DNSSEC support enabled to support TSIG. For the Generic SQL Backend make sure to use the DNSSEC enabled schema and to turn on the relevant '-dnssec' flag (for example, gmysql-dnssec)! - -## Provisioning outbound AXFR access -To actually provision a named secret permission to AXFR a zone, set a metadata item in the 'domainmetadata' table called 'TSIG-ALLOW-AXFR' with the key name in the content field. - -As an example: - -``` -sql> insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='); -sql> select id from domains where name='powerdnssec.org'; -5 -sql> insert into domainmetadata (domain_id, kind, content) values (5, 'TSIG-ALLOW-AXFR', 'test'); - -$ dig -t axfr powerdnssec.org @127.0.0.1 -y 'test:kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' -``` - -To ease interoperability, the equivalent configuration above in BIND would look like this: - -``` -key test. { - algorithm hmac-md5; - secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; -}; - -zone "powerdnssec.org" { - type master; - file "powerdnssec.org"; - allow-transfer { key test.; }; -}; -``` - -A packet authorized and authenticated by a TSIG signature will gain access to a zone even if the remote IP address is not otherwise allowed to AXFR a zone. - -## Provisioning signed notification and AXFR requests -To configure PowerDNS to send out TSIG signed AXFR requests for a zone to its master(s), set the AXFR-MASTER-TSIG metadata item for the relevant domain to the key that must be used. - -The actual TSIG key must also be provisioned, as outlined in the previous section. - -For the popular Generic SQL backends, configuring the use of TSIG for AXFR requests could be achieved as follows: - -``` -sql> insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='); -sql> select id from domains where name='powerdnssec.org'; -5 -sql> insert into domainmetadata (domain_id, kind, content) values (5, 'AXFR-MASTER-TSIG', 'test'); -``` - -This setup corresponds to the TSIG-ALLOW-AXFR access rule defined in the previous section. - -In the interest of interoperability, the configuration above is (not quite) similar to the following BIND statements: - -``` -key test. { - algorithm hmac-md5; - secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; -}; - -server 127.0.0.1 { - keys { test.; }; -}; - -zone "powerdnssec.org" { - type slave; - masters { 127.0.0.1; }; - file "powerdnssec.org"; -}; -``` - -Except that in this case, TSIG will be used for all communications with the master, not just those about AXFR requests. +Upon an incoming AXFR, PowerDNS calls our `axfrfilter` function for each record. +All HINFO records are replaced by a TXT record with a TTL of 99 seconds and the +specified string. TXT Records with names starting with `_tstamp.` get their value +(rdata) set to the current time stamp. All other records are unhandled. diff --git a/docs/markdown/authoritative/tsig.md b/docs/markdown/authoritative/tsig.md new file mode 100644 index 000000000..fd487707f --- /dev/null +++ b/docs/markdown/authoritative/tsig.md @@ -0,0 +1,112 @@ +# TSIG: shared secret authorization and authentication +TSIG, as defined in [RFC 2845](http://tools.ietf.org/html/rfc2845), is a method +for signing DNS messages using shared secrets. Each TSIG shared secret has a name, +and PowerDNS can be told to allow zone transfer of a domain if the request is +signed with an authorized name. + +In PowerDNS, TSIG shared secrets are stored by the various backends. In case of +the [`Generic SQL backends`](backend-generic-sql.md), they can be found in the +'tsigkeys' table. The name can be chosen freely, but the algorithm name will +typically be 'hmac-md5'. Other supported algorithms are 'hmac-sha1', 'hmac-shaX' +where X is 224, 256, 384 or 512. The content is a Base64-encoded secret. + +**Note**: Most backends require DNSSEC support enabled to support TSIG. For the +Generic SQL Backend make sure to use the DNSSEC enabled schema and to turn on +the relevant '-dnssec' flag (for example, gmysql-dnssec)! + +## Provisioning outbound AXFR access +To actually provision a named secret permission to AXFR a zone, set a metadata +item in the 'domainmetadata' table called `TSIG-ALLOW-AXFR` with the key name in +the content field. For example: + +``` +insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='); +select id from domains where name='powerdnssec.org'; +5 +insert into domainmetadata (domain_id, kind, content) values (5, 'TSIG-ALLOW-AXFR', 'test'); + +$ dig -t axfr powerdnssec.org @127.0.0.1 -y 'test:kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' +``` + +To ease interoperability, the equivalent configuration above in BIND would look like this: + +``` +key test. { + algorithm hmac-md5; + secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; +}; + +zone "powerdnssec.org" { + type master; + file "powerdnssec.org"; + allow-transfer { key test.; }; +}; +``` + +A packet authorized and authenticated by a TSIG signature will gain access to a +zone even if the remote IP address is not otherwise allowed to AXFR a zone. + +## Provisioning signed notification and AXFR requests +To configure PowerDNS to send out TSIG signed AXFR requests for a zone to its +master(s), set the `AXFR-MASTER-TSIG` metadata item for the relevant domain to +the key that must be used. + +The actual TSIG key must also be provisioned, as outlined in the previous section. + +For the Generic SQL backends, configuring the use of TSIG for AXFR requests could +be achieved as follows: + +``` +insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='); +select id from domains where name='powerdnssec.org'; +5 +insert into domainmetadata (domain_id, kind, content) values (5, 'AXFR-MASTER-TSIG', 'test'); +``` + +This setup corresponds to the `TSIG-ALLOW-AXFR` access rule defined in the previous section. + +In the interest of interoperability, the configuration above is (not quite) +similar to the following BIND statements: + +``` +key test. { + algorithm hmac-md5; + secret "kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="; +}; + +server 127.0.0.1 { + keys { test.; }; +}; + +zone "powerdnssec.org" { + type slave; + masters { 127.0.0.1; }; + file "powerdnssec.org"; +}; +``` + +Except that in this case, TSIG will be used for all communications with the master, +not just those about AXFR requests. + +# GSS-TSIG support +GSS-TSIG allows authentication and authorization of DNS updates or AXFR using +Kerberos with TSIG signatures. + +**Note**: this feature is experimental and subject to change on future releases. + +## Prerequisites + +- Working Kerberos environment. Please refer to your Kerberos vendor documentation on how to setup it. +- Principal (such as `DNS/@REALM`) in either per-user keytab or system keytab. + +In particular, if something does not work, read logs and ensure that your kerberos +environment is ok before filing an issue. Most common problems are time +synchronization or changes done to the principal. + +## Setting up +To allow AXFR / DNS update to work, you need to configure `GSS-ACCEPTOR-PRINCIPAL` +in [`domain metadata`](domainmetadata.md). This will define the principal that is +used to accept any GSS context requests. This *must* match to your keytab. Next +you need to define one or more `GSS-ALLOW-AXFR-PRINCIPAL` entries for AXFR, or +`TSIG-ALLOW-DNSUPDATE` entries for DNS update. These must be set to the exact +initiator principal names you intend to use. No wildcards accepted. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 27f4c02b1..82c5a0dd2 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -21,17 +21,17 @@ pages: - Installing PowerDNS: authoritative/installation.md - Running PowerDNS: authoritative/running.md - Upgrade Notes: authoritative/upgrading.md - - Modes of Operation: authoritative/modes-of-operation.md - - Domain metadata: authoritative/domainmetadata.md + - Native, Master and Slave Operation: authoritative/modes-of-operation.md + - Domain Metadata: authoritative/domainmetadata.md - Dynamic DNS Update: authoritative/dnsupdate.md - - GSS-TSIG: authoritative/gss-tsig.md + - Using TSIG for AXFR: authoritative/tsig.md - Various How To's: authoritative/howtos.md - Internals: authoritative/internals.md - Virtual Hosting: authoritative/virtual.md - Performance Tuning and Monitoring: authoritative/performance.md - Migrating to PowerDNS: authoritative/migration.md - Recursion with the Authoritative Server: authoritative/recursion.md - - Serve DNSSEC Signed Data: authoritative/dnssec.md + - Serving DNSSEC Signed Data: authoritative/dnssec.md - List of Settings: authoritative/settings.md - 'Manpage: zone2ldap.1': manpages/zone2ldap.1.md - 'Manpage: zone2sql.1': manpages/zone2sql.1.md -- 2.40.0