--- /dev/null
+.TH tinydns-data 8
+
+.SH NAME
+tinydns-data \- data tool for tinydns
+
+.SH DESCRIPTION
+This is a reference page.
+For tutorial information, see the instructions for
+.br
+.B running a DNS server
+(http://cr.yp.to/djbdns/run-server.html).
+
+.B tinydns-data
+reads local DNS information
+from a file named
+.I data
+in the current directory.
+It creates
+.I data.cdb
+in a binary format designed for
+fast access by
+.BR tinydns (8).
+It may also create some other files
+with names beginning with
+.IR data .
+
+.B tinydns-data
+updates
+.I data.cdb
+atomically,
+so you can use it safely while
+.BR tinydns (8)
+is running.
+If anything goes wrong with the creation of
+.IR data.cdb ,
+.B tinydns-data
+stops and leaves the old
+.I data.cdb
+in place.
+
+.SH Data format
+The DNS information in
+.I data
+is a series of lines.
+There are several types of lines, as shown below.
+
+Each line starts with a special character
+and continues with a series of colon-separated fields.
+In some cases the fields may be omitted;
+however, all colons must be included except at the end of the line.
+Spaces and tabs at the end of a line are ignored.
+Blank lines are ignored.
+
+Each line contains a
+.I ttl
+(``time to live'')
+specifying the number of seconds that the line's DNS records may be cached.
+Beware that cache times below 300 seconds
+will be treated as 300 by some clients,
+and NS cache times below 2 seconds can cause lookup failures.
+You may omit
+.IR ttl ;
+.B tinydns-data
+will use default cache times,
+carefully selected to work well in normal situations.
+
+You may include a timestamp on each line.
+If
+.I ttl
+is nonzero (or omitted),
+the timestamp is a starting time
+for the information in the line;
+the line will be ignored before that time.
+If
+.I ttl
+is zero,
+the timestamp is an ending time (``time to die'')
+for the information in the line;
+.BR tinydns (8)
+dynamically adjusts
+.I ttl
+so that the line's DNS records are not cached for more than a few seconds
+past the ending time.
+A timestamp is an
+external TAI64 timestamp,
+printed as 16 lowercase hexadecimal characters.
+For example, the lines
+
++www.heaven.af.mil:1.2.3.4:0:4000000038af1379
++www.heaven.af.mil:1.2.3.7::4000000038af1379
+
+specify that
+.I www.heaven.af.mil
+will have address
+.I 1.2.3.4
+until time
+.I 4000000038af1379
+(2000-02-19 22:04:31 UTC)
+and will then switch to IP address
+.IR 1.2.3.7 .
+
+For versions 1.04 and above:
+You may include a client location on each line.
+The line is ignored for clients outside that location.
+Client locations are specified by
+.B %
+lines:
+
+%\fIlo\fR:\fIipprefix\fR
+
+means that IP addresses starting with
+.I ipprefix
+are in location
+.IR lo .
+.I lo
+is a sequence of one or two ASCII letters.
+A client is in only one location;
+longer prefixes override shorter prefixes.
+For example,
+
+ %in:192.168
+ %ex
+ +jupiter.heaven.af.mil:192.168.1.2:::in
+ +jupiter.heaven.af.mil:1.2.3.4:::ex
+
+specifies that
+.I jupiter.heaven.af.mil
+has address
+.I 192.168.1.2
+for clients in the
+.I 192.168.*
+network
+and address
+.I 1.2.3.4
+for everyone else.
+
+.SH Common data lines
+
+.RI \. fqdn\fR:\fIip\fR:\fIx\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Name server for our domain
+.IR fqdn .
+
+.B tinydns-data
+creates
+.IP
+an NS (``name server'') record
+showing
+.IR x .ns.\fIfqdn\fR
+as a name server for
+.IR fqdn ;
+.P
+.IP
+an A (``address'') record showing
+.I ip
+as the IP address
+of
+.IR x\fR.ns.\fIfqdn ;
+and
+.P
+.IP
+an SOA (``start of authority'') record for
+.I fqdn
+listing
+.IR x\fR.ns.\fIfqdn
+as the primary name server
+and hostmaster@\fIfqdn\fR
+as the contact address.
+.P
+
+You may have several name servers for one domain,
+with a different
+.I x
+for each server.
+
+.BR tinydns (8)
+will return only one SOA record per domain.
+
+If
+.I x
+contains a dot
+then
+.B tinydns-data
+will use
+.I x
+as the server name
+rather than
+.IR x\fR.ns.\fIfqdn .
+This feature is provided only for compatibility reasons;
+names not ending with
+.I fqdn
+will force clients to contact parent servers
+much more often than they otherwise would,
+and will reduce the overall reliability of DNS.
+You should omit
+.I ip
+if
+.I x
+has IP addresses assigned elsewhere in
+.IR data ;
+in this case,
+.B tinydns-data
+will omit the A record.
+.P
+Examples:
+
+ .panic.mil:1.8.7.55:a
+
+creates an NS record showing
+.I a.ns.panic.mil
+as a name server for
+.IR panic.mil ,
+an A record showing
+.I 1.8.7.55
+as the IP address of
+.IR a.ns.panic.mil ,
+and an SOA record for
+.IR panic.mil .
+
+ .panic.mil:1.8.7.56:dns2.panic.mil
+
+creates an NS record showing
+.I dns2.panic.mil
+as a name server for
+.IR panic.mil ,
+an A record showing
+.I 1.8.7.56
+as the IP address of
+.IR dns2.panic.mil ,
+and an SOA record for
+.IR panic.mil .
+
+ .panic.mil::a.ns.heaven.af.mil
+
+creates an NS record showing
+.I a.ns.heaven.af.mil
+as a name server for
+.IR panic.mil ,
+and an SOA record for
+.IR panic.mil .
+
+.RI & fqdn\fR:\fIip\fR:\fIx\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Name server for domain
+.IR fqdn .
+
+.B tinydns-data
+creates
+.IP
+an NS record
+showing
+.IR x\fR.ns.\fIfqdn
+as a name server for
+.IR fqdn
+and
+.P
+.IP
+an A record showing
+.I ip
+as the IP address
+of
+.IR x\fR.ns.\fIfqdn .
+.P
+
+If
+.I x
+contains a dot
+then it is treated specially; see above.
+
+You may have several name servers for one domain,
+with a different
+.I x
+for each server.
+
+Normally
+.I &
+is used
+for domains delegated by this server to child servers,
+while
+.I .
+is used for domains delegated to this server.
+.P
+Examples:
+
+ &serious.panic.mil:1.8.248.6:a
+
+creates an NS record showing
+.I a.ns.serious.panic.mil
+as a name server for
+.IR serious.panic.mil ,
+and an A record showing
+.I 1.8.248.6
+as the IP address of
+.IR a.ns.serious.panic.mil .
+
+ &serious.panic.mil:1.8.248.7:ns7.panic.mil
+
+creates an NS record showing
+.I ns7.panic.mil
+as a name server for
+.IR serious.panic.mil ,
+and an A record showing
+.I 1.8.248.7
+as the IP address of
+.IR ns7.panic.mil .
+
+.RI = fqdn\fR:\fIip\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Host
+.I fqdn
+with IP address
+.IR ip .
+
+.B tinydns-data
+creates
+.IP
+an A record showing
+.I ip
+as
+the IP address of
+.IR fqdn
+and
+.P
+.IP
+a PTR (``pointer'') record showing
+.I fqdn
+as
+the name of
+.IR d.c.b.a .in-addr.arpa
+if
+.I ip
+is
+.IR a.b.c.d .
+.P
+
+Remember to specify name servers for some suffix of
+.IR fqdn ;
+otherwise
+.BR tinydns (8)
+will not respond
+to queries about
+.IR fqdn .
+The same comment applies to other records described below.
+Similarly, remember to specify name servers for some suffix of
+.IR d.c.b.a .in-addr.arpa,
+if that domain has been delegated to you.
+.P
+Example:
+
+ =button.panic.mil:1.8.7.108
+
+creates an A record showing
+.I 1.8.7.108
+as the IP address of
+.IR button.panic.mil ,
+and a PTR record showing
+.I button.panic.mil
+as the name of
+.IR 108.7.8.1.in-addr.arpa .
+
+.RI + fqdn\fR:\fIip\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Alias
+.I fqdn
+with IP address
+.IR ip .
+This is just like
+.RI = fqdn\fR:\fIip\fR:\fIttl\fR
+except that
+.B tinydns-data
+does not create the PTR record.
+
+For versions 1.04 and above:
+.BR tinydns (8)
+returns addresses
+(from
+.I +
+or
+.I =
+or
+.I @
+or
+.I .
+or
+.I &
+lines)
+in a random order in the answer section.
+If there are more than 8 records,
+it returns a random set of 8.
+.P
+Example:
+
+ +button.panic.mil:1.8.7.109
+
+creates an A record showing
+.I 1.8.7.109
+as another IP address for
+.IR button.panic.mil .
+
+.RI @ fqdn\fR:\fIip\fR:\fIx\fR:\fIdist\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Mail exchanger for
+.IR fqdn .
+
+.B tinydns-data
+creates
+.IP
+an MX (``mail exchanger'') record
+showing
+.IR x\fR.mx.\fIfqdn
+as a mail exchanger for
+.I fqdn
+at distance
+.I dist
+and
+.P
+.IP
+an A record showing
+.I ip
+as the IP address
+of
+.IR x\fR.mx.\fIfqdn .
+.P
+You may omit
+.IR dist ;
+the default distance is 0.
+
+If
+.I x
+contains a dot
+then it is treated specially; see above.
+
+You may create several MX records for
+.IR fqdn ,
+with a different
+.I x
+for each server.
+Make sure to arrange for the SMTP server on each IP address
+to accept mail for
+.IR fqdn .
+.P
+Example:
+
+ @panic.mil:1.8.7.88:mail.panic.mil
+
+creates an MX record showing
+.I mail.panic.mil
+as a mail exchanger for
+.I panic.mil
+at distance 0, and an A record showing
+.I 1.8.7.88
+as the IP address of
+.IR mail.panic.mil .
+
+.RI # comment
+
+Comment line. The line is ignored.
+
+.SH Uncommon data lines
+
+.RI - fqdn\fR:\fIs\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+For versions 1.04 and above:
+This type of line is used by
+programs that automatically edit
+.B +
+lines in
+.I data
+to temporarily exclude addresses of overloaded or dead machines.
+The line is ignored.
+
+.RI ' fqdn\fR:\fIs\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+TXT (``text'') record for
+.IR fqdn .
+.B tinydns-data
+creates a TXT record for
+.I fqdn
+containing the string
+.IR s .
+You may use octal
+.RI \ nnn
+codes
+to include arbitrary bytes inside
+.IR s ;
+for example,
+.RI \ 072
+is a colon.
+
+.RI ^ fqdn\fR:\fIp\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+PTR record for
+.IR fqdn .
+.B tinydns-data
+creates a PTR record for
+.I fqdn
+pointing to the domain name
+.IR p .
+
+.RI C fqdn\fR:\fIp\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+CNAME (``canonical name'') record for
+.IR fqdn .
+.B tinydns-data
+creates a CNAME record for
+.I fqdn
+pointing to the domain name
+.IR p .
+
+Don't use
+.RI C fqdn
+if there are any other records for
+.I fqdn
+Don't use
+.RI C fqdn
+for common aliases;
+use
+.RI + fqdn
+instead.
+Remember the wise words of Inigo Montoya:
+``You keep using CNAME records.
+I do not think they mean what you think they mean.''
+
+.RI Z fqdn\fR:\fImname\fR:\fIrname\fR:\fIser\fR:\fIref\fR:\fIret\fR:\fIexp\fR:\fImin\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+SOA record for
+.I fqdn
+showing
+.I mname
+as the primary name server,
+.I rname
+(with the first
+.I .
+converted to
+.IR @ )
+as the contact address,
+.I ser
+as the serial number,
+.I ref
+as the refresh time,
+.I ret
+as the retry time,
+.I exp
+as the expire time, and
+.I min
+as the minimum time.
+.IR ser ,
+.IR ref ,
+.IR ret ,
+.IR exp ,
+and
+.I min
+may be omitted;
+they default to, respectively,
+the modification time of the
+.I data
+file,
+16384 seconds,
+2048 seconds,
+1048576 seconds, and
+2560 seconds.
+
+.RI : fqdn\fR:\fIn\fR:\fIrdata\fR:\fIttl\fR:\fItimestamp\fR:\fIlo\fR
+
+Generic record for
+.IR fqdn .
+.B tinydns-data
+creates a record of type
+.I n
+for
+.I fqdn
+showing
+.IR rdata .
+.I n
+must be an integer between 1 and 65535;
+it must not be 2 (NS), 5 (CNAME), 6 (SOA), 12 (PTR), 15 (MX), or 252 (AXFR).
+The proper format of
+.I rdata
+depends on
+.IR n .
+You may use octal
+.RI \ nnn
+codes
+to include arbitrary bytes inside
+.IR rdata .
+
+.SH Wildcards
+
+.I tinydns
+supports wildcards of the form
+.IR *.fqdn .
+Information for
+.I *.fqdn
+is provided for every name ending with
+.IR .fqdn ,
+.I except
+names that have their own records
+and names that are covered by more specific wildcards.
+
+For example, the lines
+
+ +pink.floyd.u.heaven.af.mil:1.2.3.4
+ +*.u.heaven.af.mil:1.2.3.200
+
+have the same effect as
+
+ +pink.floyd.u.heaven.af.mil:1.2.3.4
+ +joe.u.heaven.af.mil:1.2.3.200
+ +bill.u.heaven.af.mil:1.2.3.200
+ +floyd.u.heaven.af.mil:1.2.3.200
+ +ishtar.u.heaven.af.mil:1.2.3.200
+ +joe.bob.u.heaven.af.mil:1.2.3.200
+ +sally.floyd.u.heaven.af.mil:1.2.3.200
+ +post.pink.floyd.u.heaven.af.mil:1.2.3.200
+
+and so on.
+
+As another example, the lines
+
+ +pink.floyd.u.heaven.af.mil:1.2.3.4
+ @*.u.heaven.af.mil::mail.heaven.af.mil
+
+have the same effect as
+
+ +pink.floyd.u.heaven.af.mil:1.2.3.4
+ @joe.u.heaven.af.mil::mail.heaven.af.mil
+ @bill.u.heaven.af.mil::mail.heaven.af.mil
+ @floyd.u.heaven.af.mil::mail.heaven.af.mil
+ @ishtar.u.heaven.af.mil::mail.heaven.af.mil
+ @joe.bob.u.heaven.af.mil::mail.heaven.af.mil
+ @sally.floyd.u.heaven.af.mil::mail.heaven.af.mil
+ @post.pink.floyd.u.heaven.af.mil::mail.heaven.af.mil
+
+and so on.
+Notice that the wildcard does not apply to
+.IR pink.floyd.u.heaven.af.mil ,
+because that name has its own records.
+
+.SH A typical data file:
+
+ =lion.heaven.af.mil:1.2.3.4
+ @heaven.af.mil:1.2.3.4
+ @3.2.1.in-addr.arpa:1.2.3.4
+
+ =tiger.heaven.af.mil:1.2.3.5
+ \.heaven.af.mil:1.2.3.5:a
+ \.3.2.1.in-addr.arpa:1.2.3.5:a
+
+ =bear.heaven.af.mil:1.2.3.6
+ \.heaven.af.mil:1.2.3.6:b
+ \.3.2.1.in-addr.arpa:1.2.3.6:b
+
+ =cheetah.heaven.af.mil:1.2.3.248
+ =panther.heaven.af.mil:1.2.3.249
+
+Here is the same information in BIND zone-file format
+with the two zones merged:
+
+ heaven.af.mil. 2560 IN SOA a.ns.heaven.af.mil. hostmaster.heaven.af.mil. ...
+ heaven.af.mil. 259200 IN NS a.ns.heaven.af.mil.
+ heaven.af.mil. 259200 IN NS b.ns.heaven.af.mil.
+ heaven.af.mil. 86400 IN MX mx.heaven.af.mil.
+
+ 3.2.1.in-addr.arpa. 2560 IN SOA a.ns.3.2.1.in-addr.arpa. hostmaster.3.2.1.in-addr.arpa. ...
+ 3.2.1.in-addr.arpa. 259200 IN NS a.ns.3.2.1.in-addr.arpa.
+ 3.2.1.in-addr.arpa. 259200 IN NS b.ns.3.2.1.in-addr.arpa.
+ 3.2.1.in-addr.arpa. 86400 IN MX mx.3.2.1.in-addr.arpa.
+
+ 4.3.2.1.in-addr.arpa. 86400 IN PTR lion.heaven.af.mil.
+ lion.heaven.af.mil. 86400 IN A 1.2.3.4
+ mx.heaven.af.mil. 86400 IN A 1.2.3.4
+ mx.3.2.1.in-addr.arpa. 86400 IN A 1.2.3.4
+
+ 5.3.2.1.in-addr.arpa. 86400 IN PTR tiger.heaven.af.mil.
+ tiger.heaven.af.mil. 86400 IN A 1.2.3.5
+ a.ns.heaven.af.mil. 259200 IN A 1.2.3.5
+ a.ns.3.2.1.in-addr.arpa. 259200 IN A 1.2.3.5
+
+ 6.3.2.1.in-addr.arpa. 86400 IN PTR bear.heaven.af.mil.
+ bear.heaven.af.mil. 86400 IN A 1.2.3.6
+ b.ns.heaven.af.mil. 259200 IN A 1.2.3.6
+ b.ns.3.2.1.in-addr.arpa. 259200 IN A 1.2.3.6
+
+ 248.3.2.1.in-addr.arpa. 86400 IN PTR cheetah.heaven.af.mil.
+ cheetah.heaven.af.mil. 86400 IN A 1.2.3.248
+
+ 249.3.2.1.in-addr.arpa. 86400 IN PTR panther.heaven.af.mil.
+ panther.heaven.af.mil. 86400 IN A 1.2.3.249
+
+.SH Design notes
+The
+.I data
+format is very easy for programs to edit,
+and reasonably easy for humans to edit,
+unlike the traditional zone-file format.
+
+.B tinydns-data
+could support a name wherever an IP address is required;
+it would look up the name in DNS and use the resulting address.
+This would reliably track changes in offsite IP addresses
+if the database were rebuilt periodically.
+
+.SH SEE ALSO
+tinydns(8)
+
+http://cr.yp.to/djbdns.html
HCoop / hcoop / zz_old / debian / djbdns.git / blobdiff