Difference between revisions of "BIND9 DLZ DNS Back End"

(Added troubleshooting section: Updating the DNS Fails: NOTAUTH)
(suggest minimal-responses by default)
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
Samba provides support for the BIND DNS server as DNS back end on a Samba Active Directory (AD) domain controller (DC). The <code>BIND9_DLZ</code> back end is recommend for complex DNS setups, the Samba internal DNS server not supports.
+
Samba provides support for using the BIND DNS server as the DNS back end on a Samba Active Directory (AD) domain controller (DC). The <code>BIND9_DLZ</code> back end is recommended for complex DNS setups that the Samba internal DNS server does not support.
  
 
{{Imbox
 
{{Imbox
 
| type = note
 
| type = note
| text = This documentation supports only BIND versions that are actively maintained by ISC. For details about the ISC BIND lifecycle, see https://www.isc.org/downloads/software-support-policy/
+
| text = This documentation only supports BIND versions that are actively maintained by ISC. For details about the ISC BIND life cycle, see https://www.isc.org/downloads/software-support-policy/
 
}}
 
}}
  
The <code>BIND9_DLZ</code> module accesses the Samba Active Directory (AD) database directly. For this reason:
+
The <code>BIND9_DLZ</code> module is a BIND9 plugin that accesses the Samba Active Directory (AD) database directly for registered zones. For this reason:
 
* BIND must be installed on the same machine as the Samba AD domain controller (DC).
 
* BIND must be installed on the same machine as the Samba AD domain controller (DC).
 
* BIND must not run in a changed root environment.
 
* BIND must not run in a changed root environment.
 
* zones are stored and replicated within the directory.
 
* zones are stored and replicated within the directory.
  
 +
= Software Architecture =
  
 +
Bind9 operates a threading model with the 'worker threads' concept.  Each plugin has an associated mutex, so no two worker threads can call API functions provided by our plugin at once.  Database access by the plugin is guarded by a fcntl lock.
  
 +
= Recommended Architecture =
  
 +
For high traffic environments, it is not recommended to use BIND9_DLZ-backed samba as a primary DNS server.  Instead, use an external server that only forwards queries to BIND9_DLZ-backed samba DNS installations when the query is addressed to a zone managed by that node.
  
= Configuring the BIND9_DLZ module =
+
= Setting up BIND =
  
During the domain provisioning, join, or classic upgrade, the <code>/usr/local/samba/private/named.conf</code> file has been created. To enable the <code>BIND9_DLZ</code> module for your BIND version:
+
For details, see [[Setting_up_a_BIND_DNS_Server|Setting up a BIND DNS Server]].
 +
 
 +
 
 +
 
 +
 
 +
 
 +
= Configuring the BIND9_DLZ Module =
 +
 
 +
During the domain provisioning, join, or classic upgrade, the <code>/usr/local/samba/bind-dns/named.conf</code> file has been created.
 +
 
 +
{{Imbox
 +
| type = note
 +
| text = For Samba v4.7 and earlier, the <code>named.conf</code> filepath is slightly different: <code>/usr/local/samba/private/named.conf</code>. If you're using an older version of Samba, take care to use the correct filepath in the instructions that follow.
 +
}}
 +
 
 +
To enable the <code>BIND9_DLZ</code> module for your BIND version:
  
 
* Add the following <code>include</code> statement to your BIND <code>named.conf</code> file:
 
* Add the following <code>include</code> statement to your BIND <code>named.conf</code> file:
  
  include "/usr/local/samba/private/named.conf";
+
  include "/usr/local/samba/bind-dns/named.conf";
  
 
* Display the BIND version:
 
* Display the BIND version:
Line 30: Line 49:
 
  BIND 9.9.4
 
  BIND 9.9.4
  
* Edit the <code>/usr/local/samba/private/named.conf</code> file and uncomment the module for your BIND version. For example:
+
* Edit the <code>/usr/local/samba/bind-dns/named.conf</code> file and uncomment the module for your BIND version. For example:
  
 
  dlz "AD DNS Zone" {
 
  dlz "AD DNS Zone" {
Line 46: Line 65:
 
  };
 
  };
  
:The following table shows which BIND version is supported in which Samba version:
+
:The following table shows the supported BIND versions and from which version of Samba the support started:
  
 
:{| class="wikitable"
 
:{| class="wikitable"
!Supported BIND Version
+
!BIND Version
!Samba Version
+
!Supported in Samba Version
 
|-
 
|-
 
|BIND 9.11
 
|BIND 9.11
|Samba 4.6 and later
+
|Samba 4.5.2 and later
 
|-
 
|-
 
|BIND 9.10
 
|BIND 9.10
Line 65: Line 84:
 
|}
 
|}
  
 +
= Setting up BIND9 options and keytab for Kerberos =
  
 
+
Samba needs to have some options set to allow Kerberos clients to automatically update the Active Directory (AD) zone managed by the <code>BIND9_DLZ</code> back end and improve performance.
 
 
 
 
= Setting up Dynamic DNS Updates Using Kerberos =
 
 
 
Samba is able to automatically update the Active Directory (AD) zone managed by the <code>BIND9_DLZ</code> back end.
 
  
 
{{Imbox
 
{{Imbox
Line 78: Line 93:
 
}}
 
}}
  
To enable dynamic DNS updates using Kerberos:
+
To enable dynamic DNS updates using Kerberos and avoid returning NS records in all responses:
  
* Add the following <code>include</code> statement to the <code>options {}</code> section of your BIND <code>named.conf</code> file. For example:
+
* Add the following to the <code>options {}</code> section of your BIND <code>named.conf</code> file. For example:
  
 
  options {
 
  options {
 
       [...]
 
       [...]
 
       tkey-gssapi-keytab "/usr/local/samba/private/dns.keytab";
 
       tkey-gssapi-keytab "/usr/local/samba/private/dns.keytab";
       [...]
+
       minimal-responses yes;
 
  };
 
  };
  
Line 109: Line 124:
  
 
:The <code>nsupdate</code> command is used to update the DNS. If the utility is missing, see you distribution's documentation how to identify the package containing the command and how to install.
 
:The <code>nsupdate</code> command is used to update the DNS. If the utility is missing, see you distribution's documentation how to identify the package containing the command and how to install.
 
 
 
 
  
 
= AppArmor and SELinux Integration =
 
= AppArmor and SELinux Integration =
Line 138: Line 149:
 
= Testing Dynamic DNS Updates =
 
= Testing Dynamic DNS Updates =
  
To test the dynamic DNS updates, run as user <code>root</code> on your Samba domain controller (DC):
+
For details, see [[Testing_Dynamic_DNS_Updates|Testing Dynamic DNS Updates]].
  
# samba_dnsupdate --verbose --all-names
+
= The Lockup Problem =
  
This commands forces an update of all records specified in the <code>/usr/local/samba/private/dns_update_list</code> file.
+
When a BIND thread calls one of the BIND9_DLZ plugin API calls, execution can be blocked on database access calls if locks are out on the database at the time.  Unfortunately, during that time, BIND will not be able to serve any queries, even external (non-samba) queries.  Bind has a "-n" option that can increase the number of worker threads but testing has shown that increasing this number does not fix the problem, indicating that BIND's threading and queueing models are probably a bit broken.
 +
In small-scale environments this problem is unlikely to come up, but, in high-traffic environments, it may cause DNS outage.  The only solution right now is to use an external DNS server that only forwards queries to BIND9_DLZ-backed samba DNS installations when the query is addressed to a zone managed by that node.
  
The <code>samba_dnsupdate</code> utility updates the DNS. It automatically checks for missing DNS records specified in the <code>dns_update_list</code> file when the <code>samba</code> daemon starts and after every 10 minutes.
 
  
  
 +
= Troubleshooting =
 +
 +
== Reconfiguring the BIND9_DLZ Back End ==
 +
 +
Running the <code>BIND9_DLZ</code> back end setup automatically fixes several problems, such as recreating the Active Directory (AD) BIND DNS account (<code>dns-*</code>) and BIND Kerberos keytab file problems.
 +
 +
To fix the problem:
 +
 +
* Run the auto-reconfiguration:
 +
 +
# samba_upgradedns --dns-backend=BIND9_DLZ
 +
Reading domain information
 +
DNS accounts already exist
 +
No zone file /usr/local/samba/private/dns/SAMDOM.EXAMPLE.COM.zone
 +
DNS records will be automatically created
 +
DNS partitions already exist
 +
dns-DC1 account already exists
 +
See /usr/local/samba/private/named.conf for an example configuration include file for BIND
 +
and /usr/local/samba/private/named.txt for further documentation required for secure DNS updates
 +
Finished upgrading DNS
  
 +
* Restart the BIND service.
  
  
= Troubleshooting =
 
  
 
== Debugging the BIND9_DLZ Module ==
 
== Debugging the BIND9_DLZ Module ==
Line 156: Line 187:
 
To set a log level for the <code>BIND9_DLZ</code> module:
 
To set a log level for the <code>BIND9_DLZ</code> module:
  
* Append the <code>-d</code> parameter and log level to the module in the <code>/usr/local/samba/private/named.conf</code> file. For example:
+
* Append the <code>-d</code> parameter and log level to the module in the <code>/usr/local/samba/bind-dns/named.conf</code> file. For example:
  
 
  database "dlopen .../bin/modules/bind9/dlz_bind9_9.so -d 3";
 
  database "dlopen .../bin/modules/bind9/dlz_bind9_9.so -d 3";
Line 164: Line 195:
 
* Start BIND manually to display the debug out put and to capture the log output in the <code>/tmp/named.log</code> file:
 
* Start BIND manually to display the debug out put and to capture the log output in the <code>/tmp/named.log</code> file:
  
   # named -u named -f -g 2>&1 | tee /etc/named.log
+
   # named -u named -f -g 2>&1 | tee /tmp/named.log
  
 
: See the <code>named (8)</code> man page for details about the used parameters.
 
: See the <code>named (8)</code> man page for details about the used parameters.
 
 
  
 
== New DNS Entries Are Not Resolvable ==
 
== New DNS Entries Are Not Resolvable ==
Line 188: Line 217:
 
The same files must have the same inode number in the first column of the output in the both directories. If they differ, the hard link got lost and Samba and BIND use separate database files and thus DNS updates in the directory are not resolveable through the BIND DNS server.
 
The same files must have the same inode number in the first column of the output in the both directories. If they differ, the hard link got lost and Samba and BIND use separate database files and thus DNS updates in the directory are not resolveable through the BIND DNS server.
  
To auto-repair the hard linking:
+
To auto-repair the hard linking, see [[#Reconfiguring_the_BIND9_DLZ_Back_End|Reconfiguring the BIND9_DLZ Back End]].
 
 
* Rerun the back end configuration:
 
 
 
# samba_upgradedns --dns-backend=BIND9_DLZ
 
 
 
* Restart the BIND service.
 
 
 
  
  
 
== Updating the DNS Fails: NOTAUTH ==
 
== Updating the DNS Fails: NOTAUTH ==
  
If BIND is not able to use the local <code>/usr/local/samba/private/dns.keytab</code> file on the Active Directory (AD) DNS server, dynamic DNS updates fail. For example:
+
If BIND uses incorrect Kerberos settings on the Samba Active Directory (AD) domain controller (DC), dynamic DNS updates fail. For example:
  
 
  # samba_dnsupdate --verbose
 
  # samba_dnsupdate --verbose
Line 218: Line 240:
 
* Verify that BIND configuration is set up correctly. For further details, see [[#Setting_up_Dynamic_DNS_Updates_Using_Kerberos|Setting up Dynamic DNS Updates Using Kerberos]].
 
* Verify that BIND configuration is set up correctly. For further details, see [[#Setting_up_Dynamic_DNS_Updates_Using_Kerberos|Setting up Dynamic DNS Updates Using Kerberos]].
  
* Recreate BIND back end settings:
+
* Recreate the BIND back end settings. For details, see [[#Reconfiguring_the_BIND9_DLZ_Back_End|Reconfiguring the BIND9_DLZ Back End]].
 +
 
 +
 
 +
 
 +
== Updating the DNS Fails: dns_tkey_negotiategss: TKEY is unacceptable ==
 +
 
 +
For details, see [[Dns_tkey_negotiategss:_TKEY_is_unacceptable|dns_tkey_negotiategss: TKEY is unacceptable]].
 +
 
 +
 
 +
 
 +
== Reloading the Bind9 DNS Server ==
 +
 
 +
If you <code>reload</code> Bind9, you are likely to see lines similar to these in the logs:
 +
named[29534]: samba_dlz: Ignoring duplicate zone
 +
 
 +
You cannot <code>reload</code> Bind9 on a Samba AD DC, you must use <code>restart</code>.
 +
You should check if logrotate is using <code>reload</code> and change it if it is>
 +
 
 +
 
 +
== Starting Bind9 DNS Server fails with "unhandled record type 65281" (Windows AD + Samba AD)==
 +
 
 +
If when starting Bind9 DNS Server you see something like:
 +
 
 +
samba_dlz: starting configure
 +
samba_dlz b9_format: unhandled record type 65281
 +
zone example.local/NONE: could not find NS and/or SOA records
 +
zone example.local/NONE: has 0 SOA records
 +
zone example.local/NONE: has no NS records
 +
samba_dlz: Failed to configure zone 'example.local'
 +
 
 +
 
 +
This is likely caused because you have a Windows Server Active Directory that has WINS entries and you are joining it.
 +
To fix it, you have to disable WINS resolving in DNS of Windows Server DC direct search zones, restart Samba AD service, reload DNS config <code>samba_upgradedns --dns-backend=BIND9_DLZ</code>, and then, restart Bind9 service.
  
# samba_upgradedns --dns-backend=BIND9_DLZ
 
Reading domain information
 
DNS accounts already exist
 
No zone file /usr/local/samba/private/dns/SAMDOM.EXAMPLE.COM.zone
 
DNS records will be automatically created
 
DNS partitions already exist
 
dns-DC1 account already exists
 
See /usr/local/samba/private/named.conf for an example configuration include file for BIND
 
and /usr/local/samba/private/named.txt for further documentation required for secure DNS updates
 
Finished upgrading DNS
 
  
* Restart the BIND service.
+
----
 +
[[Category:Active Directory]]
 +
[[Category:DNS]]

Revision as of 17:08, 19 June 2019

Introduction

Samba provides support for using the BIND DNS server as the DNS back end on a Samba Active Directory (AD) domain controller (DC). The BIND9_DLZ back end is recommended for complex DNS setups that the Samba internal DNS server does not support.

The BIND9_DLZ module is a BIND9 plugin that accesses the Samba Active Directory (AD) database directly for registered zones. For this reason:

  • BIND must be installed on the same machine as the Samba AD domain controller (DC).
  • BIND must not run in a changed root environment.
  • zones are stored and replicated within the directory.

Software Architecture

Bind9 operates a threading model with the 'worker threads' concept. Each plugin has an associated mutex, so no two worker threads can call API functions provided by our plugin at once. Database access by the plugin is guarded by a fcntl lock.

Recommended Architecture

For high traffic environments, it is not recommended to use BIND9_DLZ-backed samba as a primary DNS server. Instead, use an external server that only forwards queries to BIND9_DLZ-backed samba DNS installations when the query is addressed to a zone managed by that node.

Setting up BIND

For details, see Setting up a BIND DNS Server.



Configuring the BIND9_DLZ Module

During the domain provisioning, join, or classic upgrade, the /usr/local/samba/bind-dns/named.conf file has been created.

To enable the BIND9_DLZ module for your BIND version:

  • Add the following include statement to your BIND named.conf file:
include "/usr/local/samba/bind-dns/named.conf";
  • Display the BIND version:
# named -v
BIND 9.9.4
  • Edit the /usr/local/samba/bind-dns/named.conf file and uncomment the module for your BIND version. For example:
dlz "AD DNS Zone" {
    # For BIND 9.8
    # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9.so";

    # For BIND 9.9
    database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_9.so";

    # For BIND 9.10
    # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_10.so";
    
    # For BIND 9.11
    # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_11.so";
};
The following table shows the supported BIND versions and from which version of Samba the support started:
BIND Version Supported in Samba Version
BIND 9.11 Samba 4.5.2 and later
BIND 9.10 Samba 4.2 and later
BIND 9.9 Samba 4.0 and later
BIND 9.8 Samba 4.0 and later

Setting up BIND9 options and keytab for Kerberos

Samba needs to have some options set to allow Kerberos clients to automatically update the Active Directory (AD) zone managed by the BIND9_DLZ back end and improve performance.

To enable dynamic DNS updates using Kerberos and avoid returning NS records in all responses:

  • Add the following to the options {} section of your BIND named.conf file. For example:
options {
     [...]
     tkey-gssapi-keytab "/usr/local/samba/private/dns.keytab";
     minimal-responses yes;
};
  • If you provisioned or joined an AD forest or run the classic upgrade using a Samba version prior to 4.4.0, the BIND Kerberos key tab file was generated using wrong permissions. To fix, enable read access for the BIND user:
# chmod 640 /usr/local/samba/private/dns.keytab
# chown root:named /usr/local/samba/private/dns.keytab
  • Verify that your /etc/krb5.conf Kerberos client configuration file is readable by your BIND user. For example:
# ls -l /etc/krb5.conf
-rw-r--r--. 1 root named 99  2. Sep 2014  /etc/krb5.conf
  • Verify that the nsupdate utility exists on your domain controller (DC):
# which nsupdate
/usr/bin/nsupdate
The nsupdate command is used to update the DNS. If the utility is missing, see you distribution's documentation how to identify the package containing the command and how to install.

AppArmor and SELinux Integration

For details, see BIND9_DLZ AppArmor and SELinux Integration.



Starting the BIND Service

  • Before you start the service, verify the BIND configuration:
# named-checkconf
If no output is shown, the BIND configuration is valid.
  • Start the BIND service.



Testing Dynamic DNS Updates

For details, see Testing Dynamic DNS Updates.

The Lockup Problem

When a BIND thread calls one of the BIND9_DLZ plugin API calls, execution can be blocked on database access calls if locks are out on the database at the time. Unfortunately, during that time, BIND will not be able to serve any queries, even external (non-samba) queries. Bind has a "-n" option that can increase the number of worker threads but testing has shown that increasing this number does not fix the problem, indicating that BIND's threading and queueing models are probably a bit broken. In small-scale environments this problem is unlikely to come up, but, in high-traffic environments, it may cause DNS outage. The only solution right now is to use an external DNS server that only forwards queries to BIND9_DLZ-backed samba DNS installations when the query is addressed to a zone managed by that node.


Troubleshooting

Reconfiguring the BIND9_DLZ Back End

Running the BIND9_DLZ back end setup automatically fixes several problems, such as recreating the Active Directory (AD) BIND DNS account (dns-*) and BIND Kerberos keytab file problems.

To fix the problem:

  • Run the auto-reconfiguration:
# samba_upgradedns --dns-backend=BIND9_DLZ
Reading domain information
DNS accounts already exist
No zone file /usr/local/samba/private/dns/SAMDOM.EXAMPLE.COM.zone
DNS records will be automatically created
DNS partitions already exist
dns-DC1 account already exists
See /usr/local/samba/private/named.conf for an example configuration include file for BIND
and /usr/local/samba/private/named.txt for further documentation required for secure DNS updates
Finished upgrading DNS
  • Restart the BIND service.


Debugging the BIND9_DLZ Module

To set a log level for the BIND9_DLZ module:

  • Append the -d parameter and log level to the module in the /usr/local/samba/bind-dns/named.conf file. For example:
database "dlopen .../bin/modules/bind9/dlz_bind9_9.so -d 3";
  • Stop the BIND service.
  • Start BIND manually to display the debug out put and to capture the log output in the /tmp/named.log file:
 # named -u named -f -g 2>&1 | tee /tmp/named.log
See the named (8) man page for details about the used parameters.

New DNS Entries Are Not Resolvable

If you create new DNS records in the directory and are not able to resolve them using the nslookup, host or other DNS lookup tools, the database hard links can got lost. This happens, for example, if you move the databases across mount points.

To verify that the domain and forest partition as well as the metadata.tdb database are hard linked in both directories, run

# ls -lai /usr/local/samba/private/sam.ldb.d/
17344368 -rw-rw---- 2 root named  4251648 11. Nov 18:27 DC%3DDOMAINDNSZONES,DC%3DSAMBA,DC%3DEXAMPLE,DC%3DCOM.ldb
17344370 -rw-rw---- 2 root named  4251648 11. Nov 18:27 DC%3DFORESTDNSZONES,DC%3DSAMBA,DC%3DEXAMPLE,DC%3DCOM.ldb
17344372 -rw-rw---- 2 root named   421888 11. Nov 17:53 metadata.tdb

# ls -lai /usr/local/samba/private/dns/sam.ldb.d/
17344368 -rw-rw---- 2 root named 4251648 11. Nov 18:27 DC%3DDOMAINDNSZONES,DC%3DSAMBA,DC%3DEXAMPLE,DC%3DCOM.ldb
17344370 -rw-rw---- 2 root named 4251648 11. Nov 18:27 DC%3DFORESTDNSZONES,DC%3DSAMBA,DC%3DEXAMPLE,DC%3DCOM.ldb
17344372 -rw-rw---- 2 root named  421888 11. Nov 17:53 metadata.tdb

The same files must have the same inode number in the first column of the output in the both directories. If they differ, the hard link got lost and Samba and BIND use separate database files and thus DNS updates in the directory are not resolveable through the BIND DNS server.

To auto-repair the hard linking, see Reconfiguring the BIND9_DLZ Back End.


Updating the DNS Fails: NOTAUTH

If BIND uses incorrect Kerberos settings on the Samba Active Directory (AD) domain controller (DC), dynamic DNS updates fail. For example:

# samba_dnsupdate --verbose
...
update(nsupdate): SRV _gc._tcp.Default-First-Site-Name._sites.samdom.example.com DC1.samdom.example.com 3268
Calling nsupdate for SRV _gc._tcp.Default-First-Site-Name._sites.samdom.example.com DC1.samdom.example.com 3268 (add)
Outgoing update query:
;; ->>HEADER<<- opcode: UPDATE, status: NOERROR, id:      0
;; flags:; ZONE: 0, PREREQ: 0, UPDATE: 0, ADDITIONAL: 0
;; UPDATE SECTION:
_gc._tcp.Default-First-Site-Name._sites.samdom.example.com. 900	IN SRV 0 100 3268 DC1.samdom.example.com.

update failed: NOTAUTH

To solve the problem:


Updating the DNS Fails: dns_tkey_negotiategss: TKEY is unacceptable

For details, see dns_tkey_negotiategss: TKEY is unacceptable.


Reloading the Bind9 DNS Server

If you reload Bind9, you are likely to see lines similar to these in the logs:

named[29534]: samba_dlz: Ignoring duplicate zone

You cannot reload Bind9 on a Samba AD DC, you must use restart. You should check if logrotate is using reload and change it if it is>


Starting Bind9 DNS Server fails with "unhandled record type 65281" (Windows AD + Samba AD)

If when starting Bind9 DNS Server you see something like:

samba_dlz: starting configure
samba_dlz b9_format: unhandled record type 65281
zone example.local/NONE: could not find NS and/or SOA records
zone example.local/NONE: has 0 SOA records
zone example.local/NONE: has no NS records
samba_dlz: Failed to configure zone 'example.local'


This is likely caused because you have a Windows Server Active Directory that has WINS entries and you are joining it. To fix it, you have to disable WINS resolving in DNS of Windows Server DC direct search zones, restart Samba AD service, reload DNS config samba_upgradedns --dns-backend=BIND9_DLZ, and then, restart Bind9 service.