BIND9 DLZ DNS Back End
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.
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 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.
If you are using the internal DNS server and wish to use Bind9 instead, see Changing the DNS Back End of a Samba AD DC. |
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.
For Samba v4.7 and earlier, the named.conf filepath is slightly different: /usr/local/samba/private/named.conf . If you're using an older version of Samba, take care to use the correct filepath in the instructions that follow. |
To enable the BIND9_DLZ
module for your BIND version:
- Add the following
include
statement to your BINDnamed.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.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9.so"; # For BIND 9.9.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_9.so"; # For BIND 9.10.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_10.so"; # For BIND 9.11.x database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_11.so"; # For BIND 9.12.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_12.so"; # For BIND 9.14.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_14.so"; # For BIND 9.16.x # database "dlopen /usr/local/samba/lib/bind9/dlz_bind9_16.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.16 Samba 4.12.10 , 4.13.2 and later BIND 9.14 Samba 4.12.10 , 4.13.2 and later BIND 9.12 Samba 4.12.10 , 4.13.2 and later 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.
Dynamic DNS updates require minimum BIND version 9.8. |
To enable dynamic DNS updates using Kerberos and avoid returning NS records in all responses:
- Add the following to the
options {}
section of your BINDnamed.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
- If you upgrade from a version earlier than 4.8.0, you should check the permissions on the
/usr/local/samba/bind-dns
directory, these should be:
# chmod 770 /usr/local/samba/bind-dns # chown root:named /usr/local/samba/bind-dns
If you have joined a DC using a version of Samba >= 4.8.0 , there is a bug with the dns.keytab
file. The code to create the keytab in the correct location does not exist, see https://bugzilla.samba.org/show_bug.cgi?id=14535 . The fix (at the moment) is to change to the internal dns server and then upgrade to Bind9 again, see Changing the DNS Back End of a Samba AD DC.
If you are installing installing Samba using packages, validate that the BIND user is able to read the dns.keytab
file. Some package installations set to restrictive permissions on higher folders.
- 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.
The binddns dir was changed at Samba 4.8.0 from /usr/local/samba/private/dns to /usr/local/samba/bind-dns/dns . |
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:
- Verify that BIND configuration is set up correctly. For further details, see Setting up Dynamic DNS Updates Using Kerberos.
- Recreate the BIND back end settings. For details, see 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.
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.
If using systemd this can be disabled or changed to restart.
You can do this in a systemd override file or the bind9.service file.
If 'systemctl edit' is used, an override file is automatically created:
/etc/systemd/system/bind9.service.d/override.conf
run:
systemctl edit bind9.service
add:
[Service] # Disable reloading completely. ExecReload= # Or set it to restart #ExecReload=/usr/sbin/rndc restart
Ensure that Samba always starts after Bind9:
systemctl edit samba-ad-dc.service
This creates: /etc/systemd/system/samba-ad-dc.service.d/override.conf
Add:
[Unit] After=network.target network-online.target bind9.service
Depending on the OS used, you might need to change bind9.service to named.service.
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.
I cannot find the Bind9 dns directory
You have searched for the dns folder /usr/local/samba/bind-dns
but cannot find it. This directory was introduced at Samba version 4.8.0, but is only created if one of these three things has occurred:
- You provisioned Samba with the '--dns-backend=BIND9_DLZ' option.
- You joined a DC with the '--dns-backend=BIND9_DLZ' option.
- You upgraded to Bind9 with 'samba_upgradedns' and the '--dns-backend=BIND9_DLZ' option.
Bind9 does not start and throws a "Read-only file system" error
If you see an error like:
samba_dlz: Failed to connect to /var/lib/samba/bind-dns/dns/sam.ldb: Unable to open tdb '/var/lib/samba/bind-dns/dns/sam.ldb': Read-only file system: Operations error samba_dlz: FAILED dlz_create call result=25 #refs=0 dlz_dlopen of 'AD DNS Zone' failed
Check if the Bind9 systemd's service file defines the "ReadWritePaths" option, you might need to add the path to the samba's LDB file where the zone is stored. To do so you can execute:
# systemctl edit named.service
- Note, you might need to change named.service to bind9.service.
And add the path to the list of current paths:
[Service] ... ReadWritePaths=/var/lib/named /run/named /var/lib/samba/bind-dns ...