2014-04-30: Most of the Q&A in this FAQ is dated around 2004. Most of the content is still quite valid. With the exception(s) regarding *BSD, and possibly Openldap. As things have changed, and version(s) are newer. This is especially true where *BSD is concerned, as they were all pure conjecture, anyway. :) note: this really is a FAQ. people asked me these questions at one point or another. i have found that most people could find the answer easily enough if they simply knew what question to ask. however, for convenience's sake (and my gigantic maildir) you may also find answers that i have given. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ preinstallation: Q: these version numbers are confusing! what do they mean? A: they shouldn't be anymore. To ease package maintainers jobs' I've switched to a more conventional scheme. I had to change my build-scripts to handle these changes, but that wasn't such a big deal. 2.01 means simply that we're using LDAPDNS2, serial number 1. if you're new to ldapdns, we've actually had 37 releases between 2.00 and 2.01. Q: what does ldapdns require? A: two pieces of software: pthreads library, and the openldap library. build/install these first before using ldapdns. you'll probably want a decent ldap browser like GQ (search freshmeat for it). to run the admin scripts, you'll need perl, the Net::LDAP module, and probably Net::LDAPS and Crypt::SSLeay. beyond software? a good understanding of dns ldap schemas is nice, but not completely required. a decent understanding of ldap is also good, but (apparently) not completely required. Q: what platforms will ldapdns run on? A: ldapdns will run on any system with a semi-decent C library, and even less-than-decent POSIX threads (pthreads) support. finally, (and mostly obvious), ldapdns requires LDAP client library, and an LDAP server. version 2 has a very small test-base. let me know what platforms it works on and i'll add them here. Q: how do I build it? A: read INSTALL. it contains all the build instructions you will need. Q: i'm getting a bunch of undefined references! what gives! A: you probably don't have openldap installed. install it (rpm is fine) A2:make sure you're using openldap 2. openldap 1 doesn't have server-side schema support, and it's API is somewhat deficient. Q: it just won't compile! i have openldap installed. A: let me see the error. i may know what's going on and just not have written it down into this faq... Q: what's this merge/ directory for? A: you unpacked ldapdns 2 into your ldapdns 1 source folder. dumbass. delete the old tree and/or unpack elsewhere. Q: i'm getting a lot of undefined symbols for `_pthread_.*' A: make sure you set -I/-L properly in your Makefile A2:OpenBSD will find pthreads in -lc_r NOT -lpthread A3:Actually. You can solve this for lots of programs in the future with: ln -s /usr/lib/libc_r.a /usr/lib/libpthread.a A4:The configure script should detect this for you. Please send the mailing list details about your system so that future versions of ldapdns will know about you. Q: i'm getting warnings when i compile, what does that mean? A: it means there's a bug. there shouldn't be _ANY_ warnings. if there are, i'm not doing my job right... Q: is ldapdns secure? A: signs point to yes. A2:ldapdns has a very good security history. the biggest failure has been a potential crash due to misconfiguration. i'm fairly sure there simply aren't any places where a remote user can trigger a buffer overflow, or a stack smash. ldapdns doesn't run very long as root, and doesn't answer any queries while it is root, so remote users can't gain root. ldapdns chroots itself so even if a problem is discovered, remote users can't manipulate any files. the biggest risk to using ldapdns is ldap. you've got an ldap server and a machine that can query it, or at least parts of it. don't give ldapdns any more access than it absolutely needs to query your directory, and you'll probably be fine. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ postinstallation: Q: how do i use it? A: similarly to tinydns. quickstart (using daemontools): ldapdns-conf named nobody /var/ldapdns 172.16.0.2 192.168.0.15 \ 'cn=root,o=myorg' 'dc=dns,o=myorg' [ assumes this will be a nameserver listening to 172.16.0.2 and talking to an ldap server on 192.168.0.15 ] then put your password into /var/ldapdns/root/password and finally: ln -s /var/ldapdns /service/ldapdns and svscan should notice the new directory and start it. check the log to see if anything went wrong (it probably won't) A2:take a look at INSTALL Q: can i use kerberos with ldapdns? A: yes! you probably want to know how. after initially configuring it (see previous question), do the following: rm -f $ROOT/env/LDAP_BINDDN rm -f $ROOT/env/ROOT rm -f $ROOT/root/password then create: echo 'xxx' > $ROOT/env/LDAP_SASL replacing xxx with whatever your kerberos identity is. ldapdns will try LDAP_AUTH_KRBV42 first (authentication against DSA), then LDAP_AUTH_KRB41 (authentication directly against the ldap server) Q: none of the admin scripts seem to work! A: you'll need perl to run them. you'll also need Net::LDAP , and probably also Net::LDAPS + Crypt::SSLeay Q: i think ldapdns has a memory leak! it keeps growing! A: the openldap client libraries seem to "cache" attributes, and on a heavy nameserver it may seem to grow for a while. make sure softlimit is correct, and that you have a backup nameserver. one day, i may write a more low-memory ldap client lib to fix this... [ or i may find a bug in my code... or YOU might. it's possible; especially since i refuse to look at code before 2am... ] if it's a real bug. let me know, and i'll try to track it down. if you can code, more power! let's squash it together! Q: how do i make ldapdns resolve domains not in the directory? A: you don't. and you shouldn't either. DNS is "supposed" to be a unified space; however, if you're using a proper dns cache (like djb's dnscache), you CAN load the "root" nameservers into ldapdns. use: $ROOT/transfer_zone dns.vrx.net . then tell dnscache to use ldapdns as the only "root" server (in the @ file). [note: you will have to set up the admin tools first; see README.admin] there aren't a lot of good reasons to do this. if you come up with one, let me know... Q: how do I get "generic" records to work? A: use the "photo" objectClass, and write your data directly into it. note that you'll (probably) need to write a program to do this. A2:use the administrative tools: $ROOT/add_generic_record and $ROOT/set_generic_record -- they both take a format string. see README.generic-rr for details. Q: how do I create LOC records? A: you have to use "generic" records for now... if there's enough demand, i'll add a parser for it. even if there isn't enough demand, YOU can add it. just send patches. Q: how do I delagate PTR records? A: short answer: you can't. A2:long answer, if you point cNAMERecord inside the in-addr.arpa space from inside the in-addr.arpa space you'll get a real CNAME. note that this only works ONCE (RFC2317) so it probably won't do everything you want. some clients will (erroniously) work better if you use an nSRecord in there. A3:you can create users and allow ldap users to modify that part of your directory. A4:seeAlso is encoded as a DN (as that's what the schema for seeAlso requires) this attribute emits real PTR. A5:use regular ldap referrals. ldapdns understand them, and works fine with them. this is best because you can get other people to use ldapdns too :) Q: how do I listen for NOTIFY requests? A: set $HELPER_NOTIFY to your notify-helper program :) A2:I haven't written one yet... you could theoretically use transfer_zone, although you might want to make sure the zone exists, and that your source (the machine sending the notify request) is allowed. The remote address is put in the environment variable $REMOTE_ADDR. i don't think using transfer_zone would be safe. Q: i like to set the hostmaster address depending on the zone as I do a lot of delagation. how can I do this with ldapdns? A: i would prefer that you setup seperate instances of ldapdns, but that's not always possible. use the "mail" attribute in your directory on an object that also has an nSRecord. It's simply an email address; the last one listed will be used as the hostmaster address. A2:when I said it was an email address, i mean you put: hostmaster@nimh.org. not that stupid bind thing of hostmaster.nimh.org. Q: sometimes ldapdns crashes after serving queries, what's going on? A: this appears to be a bug in the openldap libraries. it seems to be getting better; all data comming into ldapdns is checked, so whatever openldap is doing, it's doing it on it's own. normal ldapdns operation should keep it running (by restarting it). I don't know how other openldap clients work around this. Q: sometimes ldapdns hangs after serving queries, what's going on? A: again, i need to attribute this to openldap; all loops in ldapdns are finite, so ldapdns should never hang. it might hang due to bugs in the C library, or blocking errors, but at this point i'm betting my chips on openldap. the only calls that openldap should block on are: ldap_result using timeval, so max block time should be ~500usec ldap_simple_bind_s nameserver hasn't started yet normally, unless openldap hung up on ldapdns - in which case a connection isn't possible yet. the log will contain: ``handler XX was hung up on, restarting'' if this happens. A2:there is a legitimate bug in many operating systems. if the operating system is not reentrant, you will have better luck using 1:1 mode (HANDLERS=1) if you are using an SMP system, your operating system isn't using it any. trade it in on a nice 486 :) openbsd and freebsd _both_ have problems using the fast threading system. solaris does not, and oddly enough, LINUX does not- despite all the hype about linux having such poor support for threads, etc... Q: what does the following error mean? ldapdns: getattr.c:99: ldap_next_attribute: Assertion `entry != ((void *)0)' failed. Q: what does the following error mean? ldapdns: error.c:221: ldap_parse_result: Assertion `r != ((void *)0)' failed. A: it means there's a bug in openlap (imagine that)! try upgrading to a newer version ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ tweaking/tuning: Q: i have lots of A records and I want to load balance with them. A: well, DNS is the poorest place to put that, IMHO, but if you define multiple aRecords, and: echo random > env/SCHEDULE_ARECORD you'll be set. Q: ldapdns appears to parse the ldap data each time the query occurs. is there a way to speed this up? A: i've been using ldapdns for quite a while, and i haven't noticed any speed problems. adding caching to this would probably slow things down some, (because we have to expire the cache), and definately add so much complexity that bugs would crop up. A2:enable the feature ACCELERATE_CACHE but do so at your own risk: OpenLDAP presently has bugs in this code. this enables the OpenLDAP client-side cache into ldapdns thus increasing speed. this can help GREATLY if your ldap server is blocking. (buying faster hardware is probably better) this value is measured in seconds, the default (60*5) is five minutes. under NO CIRCUMSTANCES should you set this above DEFAULT_RETRY (900, or 15 minutes). you will force ldapdns to violate the DNS protocol by doing this... echo 900 > $ROOT/env/ACCELERATE_CACHE Q: how can i provide access control for ldapdns? A: you don't. use a dnscache in a method described by the previous answer. Q: how do I provide a distributed directory to make sure things stay running? A: here's the way I did it: LDAPM (192.168.1.20) - master openldap server LDAP1 (192.168.1.25) - slave openldap server LDAP2 (192.168.1.26) - slave openldap server DNS1 (192.168.1.40) - ldapdns DNS2 (192.168.1.41) - ldapdns then after ldapdns installation is complete, you go into /service/ldapdns/env and delete the file: LDAP_HOST and create a new file called LDAP_HOSTS which has: 192.168.1.25,192.168.1.26,192.168.1.20 in it. this will cause ldapdns to try each one. since ldapdns will die if an ldap query fails, daemontools will restart ldapdns to try another host. try to set a different order on each machine (if possible) as it will speed recovery somewhat. Q: BIND has an option that XXX... how do I do this in ldapdns? A: chances are, you don't. however, in conjunction with other tools (including tools distributed with djbdns), it SHOULD be possible to do everything BIND does except crash [eratically]. Q: i'm used to using relative names and origins. how can I do this with ldapdns? A: well, ordinarily you can't. fortunately another programmer saw this to be necessary for him () and added support for it. if you type: echo 1 > $ROOT/env/RELATIVE_NAMES the feature is now enabled. restart ldapdns. please remember that if you're going to use some admin scripts the rely on this, make sure to keep the environment variable RELATIVE_NAMES actually IN the environment. I do not recommend that you use this feature, as it makes your directory confusing. It may be useful if you are handling the directory by hand. Q: are there any general purpose speed improvements you can recommend? A: use dnscache as a front-line resolver. this is not appropriate for all users of ldapdns, but should be suitable for a small number of zones. A2:put slapd in replication mode on the same machine as ldapdns. this will speed requests. A3:balance your requests by setting up multiple ldapdns's. use pickdns to help load balance further. A4:enable the feature ACCELERATE_CACHE this builds the OpenLDAP client-side cache into ldapdns thus increasing speed. this can help GREATLY if your ldap server is blocking. (OpenLDAP blocks horribly) this is measured in seconds, the default (60*5) is five minutes. this is a recommended value for most cases. under NO CIRCUMSTANCES should you set this above DEFAULT_RETRY (900, or 15 minutes). you will force ldapdns to violate the DNS spec by doing this... echo 900 > $ROOT/env/CACHE just so you know. thie OpenLDAP client-side cache is broken at the time of this writing. don't use it. Q: what's an optimal value for $HANDLERS ? A: the default :) A2:you want the value to be just a little bit greater than your AVERAGE DNS REQUESTS PER UNIQUE LDAP CYCLE. this means that if you can yank 100 ldap records per second, and are receiving around 500 dns requests per second, you'll want: 500/100 or 5 handlers. 8 should be fine. however, if your ldap server is heavily loaded, you may only be able to fit 50 records per second. 500/50 or 10 handlers. 12 should be fine. A3:i've found the above formula to also be a crock of shit when dealing with OpenLDAP. Whatever number you get, multiply by ten, because OpenLDAP likes to block at strange moments. A4:this number is SHARED, so if you say 128, then you really only have 128, not 1024 (with 8 threads). A5:HANDLERS=1 is good for broken threading libraries with non-reentrant kernels. it does NOT seem to be necessary with LINUX or SOLARIS. if you set HANDLERS=1, then ldapdns uses your THREADS count to set up 1:1: mode. Q: what's an optimal value for $THREADS ? A: usually, DOUBLE the number of cpu's is good. A2:this is extremely dependent on the schedular that your operating system uses. A3:you can tune this: $LDAP_THREADS and $DNS_THREADS are seperate entities. A4:if using $HANDLERS=1 then set this number high. 100-200 seem good. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ migration: Q: how do i convert from using BIND/DJBDNS/Win2K/etc? A: at the moment? perform a zone transfer. see README.admin for details of how to use the admin scripts. note see below for behavior-modifying options to ldapdns. Q: How do I use ldapdns as a drop-in replacement for BIND+LDAP? A: very carefully. There are several BIND+LDAP patches; one set follows RFC1279 which should work if: echo 1 > $ROOT/env/RFC1279 Q: How do I use ldapdns with Active Directory? A: very carefully. First you must enable MSDNS mode. this is presently done by simply setting the LDAP suffix to: CN=MicrosoftDNS,CN=System,DC=windowsdomain,DC=... [e.g. mydomain.local is: CN=MicrosoftDNS,CN=System,DC=mydomain,DC=local] ldapdns will now attempt to search for dnsRecords that are encoded in the manner that Active Directory uses. [note that ldapdns will NOT SEARCH PROPERLY unless you're setting your ldap_suffix properly. you CAN force it to use AD encoded entries if you've mirrored your trees elsewhere by: echo msdns > $ROOT/env/DNSRECORD but please avoid doing this as Microsoft DNS records search slowly.] ldapdns does not understand all RR's that MSDNS does. It should be sufficient for gatewaying certain Win2K services (like IIS) to the outside world, yet still provide the ease/management that Active Directory can provide. All my understanding of Active Directory was obtained through reverse-engineering of the directory by examining the LDAP tree directly. I can guarantee I am not supporting all features. I can not guarantee that I am supporting _any_ of the features. Send patches for additional queries that you find I'm performing incorrectly. big warning here: until I can handle SRV requests properly, you cannot use ldapdns as a stand-in for Microsoft DNS. this is because Microsoft REQUIRES the use of SRV records to locate the directory, locate the keyservers, and to locate that big hole you have in your head. however, if you are MIGRATING from a MS-DNS platform, this option MAY be of some use to you. on the other hand, if you are migrating, zone transfers may be a better option... you have been warned. Q: i use bind. i provide name-services for my customers so that they can have a NS1.EXAMPLE.COM and a NS2.EXAMPLE.COM of their own in the whois records. how do i do this with ldapdns? A: set up multiple ldapdns instances- each on a seperate IP. A2:set up multiple ldapdns servers. just like bind :) Q: how do I setup ldapdns to be a secondary for a BIND-based machine? A: this is one of the most common ldapdns questions. i highly recommend that you don't do this (nor the other way around). running two dns databases is a bad idea, but transfer_zone and ldapaxfr can help you do this... A2:the admin tool secondary_zone was built for this purpose. run it as: secondary_zone ns zone ... periodically to keep the directory up to date with your bind files. - Q: i used djbdns, and i really like the ability to send information based on what address the client is comming from. how do i do this in ldapdns? A: you couldn't until very recently: first you need to create a: $ROOT/root/switch the format is simple: nym=subnet nym=subnet then, in your directory, set up multiple aRecords that end with %nym; to perform djb's example you'll have: in=192.168.0.0/16 ex=0/0 and then records: dc=juniper, dc=heaven, dc=af, dc=mil aRecord=192.168.1.2%in aRecord=1.2.3.4%ex this feature is experimental. i have no use for it, but other people seem to like it. so if you used this feature, you too might like it. A2:You can also create aRecords like this: 192.168.0.0/16=192.168.1.2 0/0=1.2.3.4 but note that this method depends on the order in which things come back from the LDAP directory. Unless you have control of this, you'll probably want to use the former method. ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ bugs and problems: Q: i keep getting ber_dump: related things in my log. A: you enabled ACCELERATE_CACHE thinking it would be a good idea to use overly complicated and experimental code on a production nameserver, didn't you? :) don't do that. ACCELERATE_CACHE is presently BROKEN in OpenLDAP (2.0.11) this could change at any time. post the bug to the OpenLDAP mailing lists; it isn't my fault. Q: there's a long delay before "starting ldapdns" is displayed. how do i fix this? A: don't use names in defining your LDAP servers. ldapdns chroots into it's directory so it cannot access your resolver files or your static host map. A2:freebsd appears to have some weird resolver problems: mkdir $ROOT/root/etc cp /etc/hosts /etc/resolv.conf $ROOT/root/etc/. echo hosts > $ROOT/root/etc/host.conf yet another braindead thing freebsd does... (should not probe 127.0.0.1 if no resolver is found) (thanks to mg@bindone.de for helping me work this out) A3:ldapdns 2 should solve this issue (by bringing up ldap connections in a different order). Q: it built fine on solaris, but it doesn't run! A2:solaris requires some device nodes. you need to: mkdir $ROOT/root/dev cp -p /devices/pseudo/clone@0:ip $ROOT/root/dev/ip cp -p /devices/pseudo/clone@0:tcp $ROOT/root/dev/tcp Q: what does this mean? ldapdns fatal: handler 91 has waited too long A: it means there's a bug in openlap (imagine that)! try upgrading to a newer version A2:you can try and increase the number of threads/handlers so that it won't affect DNS operation. A3:try disabling the client side cache if you have it enabled. I've noticed some potentially infinite loops there... ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ other questions: Q: how much of ldapdns is dependant on djbdns? A: none. not any more. djbdns is very quick so long as the blocking-factor is the udp network. however with ldapdns, the blocking factor is LDAP. Q: ldap2dns allows djbdns to use ldap. why do we need another gateway? A: because ldap2dns (despite the propaganda) is not an ldap to dns gateway. it's a perl script that downloads records out of an ldap directory and into a normal tinydns data file. i wanted something that could speak directly. Q: why don't you support the ldap2dns schema format? A: because it's extremely slow, and doesn't appear to be well thought out. it's fairly easy to reconstruct valid entries from the LDAP tree that ldap2dns uses, but it is not easy to contort a valid DNS query into one of these messages. storing the record type as part of the DN is a bad idea. Q: bind can already read from an ldap directory? why not use that? A: honestly. do you really think i would be caught dead running ISC software? A2:bind is slow, by-design bug prone, and it's methods in the directory are quite silly. A3:some BIND people find this humerous. I will digress: BIND has got to be the worst nameserver implementation ever. It is certainly the first, and most certainly the most rhobust (all around), and for that I am fortunate, for I have learned from many of the mistakes BIND has (is, does) made. A4:BIND leaks memory even worse than the OpenLDAP client libs. A5:Okay, this one is for real: BIND's LDAP support is still very buggy, and crashed on me several times when first trying it out. Perhaps it's better now. Probably not. The BIND core isn't well suited for anything except pulling records from memory. This is because BIND uses the same blocks for caching DNS records as it uses for storing the real authoritative records. This is probably the reason DNS poisoning worked so well. Anyway, BIND isn't multithreaded, so no matter which hacks you're using, BIND will either block when a query is received, or it will suck up memory like mad. Your choice. Q: windows 2000 with active directory and three-dee-action stores DNS records in active directory (ldap server), why not just use that? A: because nameservers should never be rebooted! A2:win2k requires lots of licensing. ldapdns is free (cost-wise). A3:win2k requires lots of licensing. ldapdns is free (freedom-wise). A4:win2k has many security-related problems. try a good *nix and ldapdns. Q: will active directory/BIND+LDAP support improve over time? A: possibly. only you can answer that question by using it. tell me what you need, write patches, run probes, and etc. I don't use Microsoft anything, nor do I use BIND, so I can't help you a whole lot. the only reason I was able to do ANY active directory code is that a client used MSDNS and I decided to take some snaps of parts of the directory for perusal. Q: what do i do if my question isn't answered here? A: ask me! see http://www.nimh.org/ for directions on reaching my contact page.