README
1
2ldapdns / ldapaxfr
3
4
5welcome to LDAPDNS.
6
7
8i wrote LDAPDNS simply because there is no other LDAP<->DNS gateway that
9I found useful, and infact, there are/were only two others that I am/was
10aware of:
11 1. Microsoft Active Directory
12 2. BIND+LDAP (patch)
13
14If you need to know why these are completely wrong, go elsewhere,
15because I'm not going to explain it in this README.
16
17Still here?
18
19LDAPDNS is a fast, rhobust, and powerful content DNS server.
20
21It does not do:
22 recursive resolving
23 proxying
24 caching
25
26or anything else but serve DNS content.
27
28The first version of LDAPDNS was written as a patch to DJBDNS - a very
29fine DNS server. However, OpenLDAP was unstable at the time, and had
30lots of bugs in the client-side code. It also blocked frequently, and
31even sometimes disappeared completely.
32
33LDAPDNS 2 is a rewrite that primarily addresses problems with OpenLDAP,
34and also succeeds the original: It is faster than other nameservers, and
35can scale above and beyond any other nameserver. <README.comparison>
36
37LDAPDNS does some things that other nameservers don't -- a kind of
38innovation if you will -- and AFAIK, is the only nameserver that
39supports generic records AND still compresses domain-names inside of
40them <README.generic-rr>
41
42Like DJBDNS, it supports "split-horizon" DNS, and also puts in some
43offensive programming tactics that make LDAPDNS safe to use.
44 a remote user cannot write to the LDAP server (permissions)
45 a remote user cannot trash the filesystem
46 a remote user cannot gain access to a "shell"
47some of the should-not's :)
48 a remote user should not be able to crash LDAPDNS
49
50that's a hard one. I'm not as good a programmer as DJB -- but his
51tactics have changed my code - and continue to. One day, I'll be able to
52make a guarantee :)
53
54Like BIND, you can make binary packages of LDAPDNS, and unlike the ISC,
55I will actually try and help you with it! Redistribution of LDAPDNS is a
56good thing...
57
58If you have any questions at all about LDAPDNS, feel free to contact me
59directly; all my relevent contact information is on my website.
60
README.admin
1administration tools readme
2
3this assumes ldapdns was setup into /service/ldapdns using ldapdns-conf
4first note:
5these tools ONLY work with the vanilla ldapdns system. they're not
6suited for Active Directory or BIND. there are existing tools for that.
7
8i also assume that you've installed perl, and at least Net::LDAP.
9
10configuration:
11
121. create a directory off of home called ~/.ldapdns/
13 * optional: more than one user can "share" a config by creating
14 /.ldapdns/ or (admintooldir)/.config/ but be warned; these
15 users will have access to your LDAP password.
16
17 * optional: this directory is also read from $ROOT;
18 you can use that too
19
20 this directory is called $ROOT for the remainder of this document
21
222. create two directories:
23 $ROOT/env
24 $ROOT/root
25 copy the files LDAP_BINDDN LDAP_HOST and LDAP_SUFFIX from
26 /service/ldapdns/env to $ROOT/env
27
28 copy the file "password" from /service/ldapdns/root into $ROOT/root
29
30 * optiona: make symlinks instead of directories;
31 ln -s /service/ldapdns/env $ROOT/env
32 ln -s /service/ldapdns/root $ROOT/root
33
343. if you don't use TLS/SSL (e.g. LDAPS) then comment out that code
35 at the top of config.pl and:
36 echo 1 > $ROOT/env/TRUSTED_NETWORK
37
384. if you're going to be using transfer_zone to transfer zones from
39 another nameserver into your directory, note that transfer_zone has
40 TWO MODES of operation:
41 1. a normal zone-transfer tool
42 2. a zone-migration tool
43 to invoke "type 2" set two envrionment variables prior to use:
44 IP the local IP of the nameserver
45 LOCAL_NS nameservers (names) handling PTR entries...
46 you may need to hack this a bit yourself... contact me if you have
47 any questions...
48
495. another possibility (thanks to <jordan@mjh.teddy-net.com>) is to use
50 secondary_zone; which basically eats BIND zone files and populates
51 the directory. this can be very useful for "trying out" data. some
52 warnings (from me):
53 1. make sure that if you're going to use $RELATIVE_NAMES
54 that you set it in the environment whenever you run
55 secondary_zone
56
57 (more to come)
58
59and that's it! the admin scripts should now work as you'd expect.
60Rather: as I would expect.
61
62just remember that set_sub_alias/mx ACTUALLY modifies the "source"
63instead of the "destination" (think of these as the direction of
64aliasing)
65
README.axfr
1the zone-transfer server (ldapaxfr) works similar to djbdns axfrdns
2except that it pulls "zones" out of the ldap server.
3
4the zone-transfer server REQUIRES that the AXFR environment variable be
5set to:
6 a single dot
7or
8 a root of the attempted zone
9
10before allowing a zone transfer to occur. AXFR can be disabled (by not
11setting the AXFR environment variable, or setting it to an empty string)
12and ldapaxfr will still answer regular queries via TCP.
13
14this change is primarily to support APNIC (asia and australia) domains
15that insist on TCP service but the administrator does not want wide-open
16zone transfers...
17
18sample/axfr contains a default configuration for this.
19
README.comparison
1
2a lot of people are curious as to how ldapdns stacks up to other DNS
3servers.
4
5 ldapdns djbdns bind msdns
6-----------------------------------------------------------------------
7threaded yes no[11] no probably
8scalable yes no no[6] no[8]
9live update yes[1] yes[3] yes[7] yes[9]
10bind zone file yes[2] no[4] yes yes[2]
11ldap support yes no no yes
12client diff. yes yes no yes
13recursive no yes[5] yes yes
14size (in lines) 6k 11k 233k ?[10]
15unixish? yes yes[12] yes no
16windows? no no yes yes
17
18[1] ldapdns supports live update by-way of it's LDAP server
19 security is enforced by the LDAP server
20[2] MS-DNS and ldapdns can both import BIND zone files.
21[3] djbdns does not keep queries in memory; all requests go to the disk
22[4] there are third party tools to support imports
23[5] djbdns uses a tool called dnscache to provide recursive-resolver
24 capabilities. i highly recommend it's use.
25[6] bind is about as un-scalable as you can get. it's bloated and
26 sluggish, it is NOT multithreaded, and must keep all records in
27 memory.
28[7] bind supports live updates through the NS-UPDATE protocol which
29 tries to attach modification requests into the DNS protocol stream.
30 there are no security considerations whatsoever when using NS-UPDATE
31[8] i discount MSDNS scalability simply because it isn't tunable, and
32 responsiveness does not seem to increase linearly as ram and cpus
33 increase.
34[9] MSDNS also supports NS-UPDATE, but it is less favored that
35 Microsoft's internal update that relies on Active Directory.
36[10] my guess? huge.
37[11] djbdns would never benefit from a threaded core. the response loop
38 is tighter than a single task-switch in many cases. preforking can
39 improve response times on multiprocessor machines- but nowhere else.
40[12] unixish on djbdns means many things. i suspect djbdns will be the
41 last djb software written for unixish systems. take this how you
42 like.
43[*] size in LOC (lines of code) is difficult to understand. said
44 plainly, the less code there is, the easier it is to determine where
45 problems are. LDAPDNS is huge (imho) as a nameserver (non-proxying,
46 non-caching), and yet I cannot imagine that even 10% of BIND is
47 "only" the content serving part.
48
49security comparisons are difficult to come by. MSDNS is highly
50integrated into Active Directory, so you could say that any and all
51Active Directory bugs are also bugs to MSDNS. Likewise, LDAPDNS is at
52the mercy of your LDAP directory. BIND is historically bad -- and the
53only other nameserver that truly controls its surroundings is DJBDNS. It
54shouldn't suprise you that DJBDNS has a better security record than
55BIND, but with proper premaintainence, it should be possible to set up
56BIND in a secure environment.
57
58interestingly enough, MS-DNS, the only really-commercial product that I listed
59is NOT the one with the security guarantee. presently only djbdns comes with a
60security guarantee.
61
62LDAPDNS should be adaquite: it does not cache, nor allow editing of the
63directory. It runs in a chrooted jail, with minimal permissions. it
64cannot be poisioned by any conventional means, and even if the LDAPDNS
65machine is comprimised, this does not mean that false DNS data can be
66generated (a short explaination on that: someone would have to replace
67the ldapdns server with a fake one with fake data. running a read-only
68filesystem is a good way to guarantee this doesn't happen -- ldapdns
69does not require write-access anywhere)
70
71Addendum:
72
73Many people check their LDAPDNS performance by timing something like
74this:
75
76$ time for D in `seq 1 1000`; do host -a domain.com ip.ldapdns; done >/dev/null
77
78And then wonder how could ldapdns _possibly_ be faster than BIND or
79DJBDNS!
80
81The simple answer is that for such a small load, it never will be. BIND
82and DJBDNS can take advantage of having their records stored in memory,
83and querying an external source will never be faster than that...
84
85... unless your domain structure is so large and your requests are so
86diverse that you cannot store your records in memory.
87
88However, _updating_ the data that LDAPDNS is _much_ faster than BIND or
89DJBDNS. Plus you get to take advantage of the replication in your LDAP
90server which is likely to be much more efficient than BIND or DJBDNS.
91
92Additional addendum:
93
94Run properly, it should be impossible for anything short of a DOS to
95stop LDAPDNS, and the threading core of LDAPDNS makes that rather
96difficult. I have tried to provide instructions as-to what properly
97really means, but the fact is that a would-be attacker has a much better
98chance against your directory than they do against my nameserver.
99LDAPDNS is an extremely simple piece of equipment -- it doesn't need to
100write anything, it doesn't store anything the user says. It's content
101only, chrooted, unprivelged process. The user doesn't have any control
102over any buffer (the response buffer code is almost identical to what
103djbdns uses) so LDAPDNS is about as low-risk as you can get.
104
105If you do not believe me, that's fine. Look at the code, and tell me
106what you do believe. I'll make every effort to fix every bug as quickly
107as possible -- I'll accept patches too. I'll never charge for updates
108(ISC), and I'll often add features just because they were requested. I
109strongly believe that LDAPDNS is the best kind of free software because
110the author is sticking out the proverbial neck here.
111
README.configure
1
2To configure LDAPDNS, you will need some kind of LDAP browser, or my
3administration scripts. See README.admin for details on those. This
4document describes the real deal :)
5
6ldapdns supports _THREE_ different schemas. If you're using Microsoft
7Active Directory, or BIND+LDAP, then this document will not help you.
8I'm afraid I haven't written much documentation on these things yet, but
9by poking around the FAQ, you may be able to get them working.
10
11ldapdns DOES SUPPORT AXFR: see INSTALL or README for details about it.
12
13ldapdns looks up DNS records in an LDAP directory. domains and zones are
14split onto a string of domainComponent (dc) objects, and use attributes
15to resource records on a dnsDomain object.
16
17ldapdns walks the tree up and down, first up to find SOA/NS records (it
18won't serve a request unless it has found an SOA/NS record somewhere in
19a domain's rootsor in the domain itself; e.g. www.nimh.org doesn't
20require an SOA/NS if nimh.org has one)
21
22the second pass is to find wildcards:
23 dc=www, dc=nimh, dc=org, [suffix]
24 dc=*, dc=nimh, dc=org, [suffix]
25 dc=*, dc=org, [suffix]
26
27note that ldapdns NEVER recursively resolves; it ONLY operates as a root
28server. this will likely never change.
29
30resource records (RR) are mapped to LDAP attributes:
31 SOA -- sOARecord
32 NS -- nSRecord
33 A -- aRecord
34 MX -- mXRecord
35 CNAME -- cNAMERecord
36 TXT -- description
37 PTR -- cNAMERecord or seeAlso
38 * -- photo
39
40all "domain names" in fields must be fully qualified: you may leave off
41the trailing dot. If you don't like this, search the FAQ for
42RELATIVE_NAMES
43
44aRecord
45 this can be in one of the following forms:
46 a.b.c.d
47 a.b.c.d%ID
48 A.B.C.D/CIDR=a.b.c.d
49 A.B.C.D/E.F.G.H=a.b.c.d
50 the last three forms are for implementing "split-horizon" DNS, and
51 can be useful if you want to serve a different address based on the
52 connecting client.
53
54 "split-horizon" has not yet been well documented. see the FAQ for
55 more details.
56
57sOARecord
58 this is 5 numbers seperated by whitespace.
59 serial refresh retry expire minimum
60
61 the defaults are:
62 nnn 3600 900 36000000 3600
63
64 where 'nnn' is the last-modified time of the DN.
65
66 this attribute has side-effects: If you start this with an asterisk,
67 this field will disable the entire zone.
68
69 note that under LDAPDNS you DO NOT NEED sOAReocrds! they can be
70 emulated- but note you WILL need nSRecords....
71
72nSRecord
73 this is a domain name.
74 it can also be a single @ which allows you to use the domains
75 specified in the environment variables $NS and $NSx (NS1, NS2, etc)
76
77 this specifies where a zone is.
78
79 if you create an nSRecord without ANY OTHER RECORDS, LDAPDNS will
80 treat this as a referral, and refer caching DNS proxies to the real
81 server. (clearing the AD bit)
82
83mXRecord
84 this is a preference, followed by whitespace, followed by a name.
85 this works exactly like "real MX records"
86
87 LDAPDNS will attempt to resolve these names if they are local,
88 placing the results in the ADDITIONAL section. This is useful for
89 caches.
90
91cNAMERecord
92 this is a domain name.
93
94 in the in-addr.arpa. tree, these return PTR records _unless_ the
95 target is outside of the directory OR retargets the in-addr.arpa.
96 tree, in which case it returns CNAME records.
97
98 otherwise, it returns CNAME records.
99
100 LDAPDNS will attempt to resolve these names if they are local,
101 placing the results in the ADDITIONAL section. This is useful for
102 caches.
103
104description
105 this is a free-form text string.
106 a hack splits this on the pipe(|) character. this is useful for
107 returning multiple TXT names.
108
109photo
110 this is a "catch all" record.
111
112 it is always in binary. the exact format lends itself to being
113 compressed in DNS packets:
114
115 0x00-0xFE literal octet
116 0xFF 0xFF literal 0xFF octet
117 0xFF DNS-compressed name (will be recompressed
118 to safe space) follows
119
120 this helps save space and reduce the need for TCP connections.
121
122 this allows LDAPDNS to support _all_ RR's as efficiently as any
123 other nameserver -- better still than some.
124
README.generic-rr
1
2the add_generic_record and set_generic_record tools use a format string
3to pack the data properly. since both take the same arguments, i'll
4refer to both as $GENERIC
5
6this document lists the format-specifications needed to make various
7kinds of generic records.
8
9-----
10
11to make a RP (responsible person):
12
13$GENERIC 37 'A' emailaddress
14
15
16to make a SRV (service locator):
17
18$GENERIC 33 'nnnA' priority weight port targetdns
19
20
21more to come!
22
README.how-can-i-help
1
2do you use ldapdns?
3do you like it? do you want to know how you can help?
4
51. what direction should ldapdns take? if you can code, start coding. if
6you can not, tell me. i can do things I know i want to do, and I can do
7things I don't know i want to do. the trick is to make me want it :)
8
9some coding projects i'm not interested in writing, but interested in
10seeing:
11 a) graphical front-ends (specifically for DNS)
12
132. document things! i don't like pulling double duty, and i only speak
14and write english. so translate my documentation into other forms, or
15write how-to's in other languages. write a book about life with
16ldapdns :)
17
18some good documentation projects:
19 a) a real quickstart guide :)
20 b) tuning options that work for your situation (esp. OpenLDAP
21 related)
22
233. distribution. mention ldapdns on your website, and pester your
24favored distribution to include it. tell your friends. make fun of BIND
25users.
26
README.quotes
1
2Simple Updates and true replication...This is the future.
3Inflexible text files and zone transfers just have to be
4history soon I hope (although rsync over ssh with tinydns
5is somewhat nicer than Bind already).
6 -Andreas Brenk
7
8
9
README.search
1Calculated dns using ldapdns
2
3TODO: this documentation stinks
4
5
6Q: I have a tree that looks like this: cn=personname, o=myorg
7 they have a dc attribute called "heaven" and i want this to
8 be for heaven.af.mil, how do I do this?
9
10A: follow these steps
11 1. set your LDAP_SUFFIX=o=myorg
12 2. create a $ROOT/search that contains the following line:
13af.mil dc
14
15add the following to your directory:
16
17dn: cn=Mrs. Brisby, dc=dns, o=myorg
18objectClass: person
19objectClass: dcObject
20objectClass: dnsDomain
21cn: Mrs. Brisby
22sn: Brisby
23dc: heaven
24aRecord: 192.168.1.3
25
26
27
README.using-debian
1so, you want to install via apt or dpkg?
2
3i cannot yet help you make an APT repository, but I _may_ be able to
4help you most of the way. if you follow these directions, you should
5have a functioning debian package. having that package, you should be
6able to find some APT-HOWTOs laying around the internet and create a
7repository for yourself.
8
9the order in which things happen is still not completely clear to me, so
10while I _think_ these instructions make a functioning debian package,
11I could be very mistaken.
12
13addendum: Toni Mueller pointed out that making debian packages isn't
14hard at all. the debian toolchain does most of the work for you. I just
15happen to have not used the debian toolchain.
16
17# cp ldapdns.tgz ldapdns-2.00-8.tar.gz
18# tar xzf ldapdns-2.00-8.tar.gz
19# cd ldapdns-2.00-8
20# ./debian/rules binary
21# cd ..
22
23you should now have a: ldapdns-2.00_8-1_i386.deb (or whatever platform
24you're running on).
25
26you cannot yet cross-compile ldapdns. if you want to do this, figure out
27how, edit the debian/* and send me your changes.
28
29you cannot yet configure ldapdns. see the remainder of the configuration
30guide, OR hack this stuff into the debian/* tree.
31
32I want to thank checkinstall/installwatch for teaching me more about
33debian packages than the official debian maintainers faq :)
34
README.using-rpm