Special Entries

$SOA ttl origindn persondn serial refresh retry expire minttl

Specifies SOA (Start Of Authority) record for all zones using this dataset. Only first SOA record is interpreted. This is the only way to specify SOA - by default, rbldnsd will not add any SOA record into answers, and will REFUSE to answer to certain queries (notably, SOA query to zone's base domain name). It is recommended, but not mandatory to specify SOA record for every zone. If no SOA is given, negative replies will not be cacheable by caching nameservers. Only one, first $SOA line is recognized in every dataset (all subsequent $SOA lines encountered in the same dataset are silently ignored). When constructing a zone, SOA will be taken from first dataset where $SOA line is found, in an order as specified in command line, subsequent $SOA lines, if any, are ignored. This way, one may overwrite $SOA found in 3rd party data by prepending small local file to the dataset in question, listing it before any other files.

If serial value specified is zero, timestamp of most recent modified file will be substituted as serial.

If ttl field is zero, default ttl (-t option or last $TTL value, see below) will be used.

All time fields (ttl, refresh, retry, expire, minttl) may be specified in time units. See -t option for details.

$NS ttl nameserverdn nameserverdn...

Specifies NS (Name Server) records for all zones using this dataset. Only first $NS line in a dataset is recognized, all subsequent lines are silently ignored. When constructing a zone from several datasets, rbldnsd uses nameservers from $NS line in only first dataset where $NS line is given, in command-line order, just like for $SOA record. Only first 32 namservers are recognized. Individual nameserver(s) may be prefixed with a minus sign (-), which means this single nameserver will be ignored by rbldnsd. This is useful to temporary comment out one nameserver entry without removing it from the list. If ttl is zero, default ttl will be used. The list of NS records, just like $SOA value, are taken from the first data file in a dataset where the $NS line is found, subsequent $NS lines, if any, are ignored.

$TTL time-to-live

Specifies TTL (time-to-live) value for all records in current dataset. See also -t option. $TTL special overrides -t value on a per-dataset basis.

$TIMESTAMP dstamp [expires]

(experimental) Specifies the data timestamp dstamp when the data has been generated, and optionally when it will expire. The timestamps are in form yyyy:mm:dd[:hh[:mi[:ss]]], where yyyy is the year like 2005, mm is the month number (01..12), dd is the month day number (01..31), hh is hour (00..23), mi and ss are minutes and secounds (00.59); hours, minutes and secounds are optional and defaults to 0; the delimiters (either colon or dash may be used) are optional too, but are allowed for readability. Also, single zero (0) or dash (-) may be used as dstamp and/or expires, indicating the value is not given. expires may also be specified as +rel, where rel is a time specification (probably with suffix like s, m, h, d) as an offset to dstamp. rbldnsd compares dstamp with current timestamp and refuses to load the file if dstamp specifies time in the future. And if expires is specified, rbldnsd will refuse to service requests for that data if current time is greather than the value specified in expires field.

Note that rbldnsd will check the data expiry time every time it checks for data file updates (when receiving SIGHUP signal or every -c interval). If automatic data reload timer (-c option) is disabled, zones will not be exipired automatically.

$MAXRANGE4 range-size

Specifies maximum size of IPv4 range allowed for IPv4-based datasets. If an entry covers more IP addresses than range-size, it will be ignored (and a warning will be logged). range-size may be specified as a number of hosts, like 256, or as network prefix lenght, like /24 (the two are the same):

  $MAXRANGE4 /24
  $MAXRANGE4 256
    

This constraint is active for a dataset it is specified in, and can be owerwritten (by subsequent $MAXRANGE statement) by a smaller value, but can not be increased.

$n text

(n is a single digit). Specifies a substitution variable for use as $n placeholders (the $n entries are ignored in generic daaset). See section "Resulting A values and TXT templates" below for description and usage examples.

$= text

Set the base template for all individual TXT records. See section "Resulting A values and TXT templates" below for more information.

ip4set Dataset

  127.0.0.0/24
  127.0.0
  127/24
  127-127.0.0
  127.0.0.0-127.0.0.255
  127.0.0.1-255

  127.16.0.0-127.31.255.255
  127.16.0-127.31.255
  127.16-127.31
  127.16-31
  127.16.0.0/12
  127.16.0/12
  127.16/12

After an IP address range, A and TXT values for a given entry may be specified. If none given, default values in current scope (see below) applies. If a value starts with a colon, it is interpreted as a pair of A record and TXT template, delimited by colon (:127.0.0.2:This entry is listed). If a value does not start with a colon, it is interpreted as TXT template only, with A record defaulting to the default A value in current scope.

IP address range may be followed by a comment char (either hash character (#) or semicolon (;)), e.g.:

  127/8 ; loopback network

Every IP address that fits within any of specified ranges is "listed", and rbldnsd will respond to reverse queries against it within specified zone with positive results. In contrast, if an entry starts with an exclamation sign (!), this is an exclusion entry, i.e. corresponding address range is excluded from being listed (and any value for this record is ignored). This may be used to specify large range except some individual addresses, in a compact form.

If a line starts with a colon (:), this line specifies the default A value and TXT template to return (see below) for all subsequent entries up to end of current file. If no default entry specified, and no value specified for a given record, rbldnsd will return 127.0.0.2 for matching A queries and no record for matching TXT queries. If TXT record template is specified and contains occurences of of dollar sign ($), every such occurence is replaced with an IP address in question, so singe TXT template may be used to e.g. refer to a webpage for an additional information for a specific IP address.

ip4trie Dataset

This dataset is not particularly memory-efficient for storing many single IP addresses — it uses about 50% more memory than the ip4set dataset in that case. The ip4trie dataset is better adapted, however, for listing CIDR ranges (whose lengths are not a multiple of 8 bits.)

ip4tset Dataset

ip6trie Dataset

Example zone data:

  # Default A and TXT template valuse
  :127.0.1.2: Listed, see http://example.com/lookup?$
  # A listing, note that trailing :0s can be omitted
  2001:21ab:c000/36
  # /64 range with non-default A and TXT values
  2001:21ab:def7:4242 :127.0.1.3: This one smells funny
  # compressed notation
  2605:6001:42::/52
  ::1                   # localhost
  !2605:6001:42::bead   # exclusion

ip6tset Dataset

This dataset wants the /64s listed as four ip6 words, for example:

  2001:20fe:23:41ed
  abac:adab:ad00:42f

  !abac:adab:ad00:42f:face:0f:a:beef
  !abac:adab:ad00:42f::2

dnset Dataset

Wildcards are interpreted as follows:

example.com

only example.com domain is listed, not subdomains thereof. Not a wildcard entry.

*.example.com

all subdomains of example.com are listed, but not example.com itself.

.example.com

all subdomains of example.com and example.com itself are listed. This is a shortcut: to list a domain name itself and all it's subdomains, one may either specify two lines (example.com and *.example.com), or one line (.example.com).

This dataset type may be used instead of ip4set, provided all CIDR ranges are expanded and reversed (but in this case, TXT template will be expanded differently).

generic Dataset

 # bl.ex.com
 # specify some values for current zone
 $NS 0 ns1.ex.com ns2.ex.com
 # record with TTL
 www 3000 A 127.0.0.1
 about TXT "ex.com combined blocklist"
    

combined Dataset

  $DATASET type[:name] subzone subzone...

This dataset type aims to simplify subzone maintenance, in order to be able to include several subzones in one file for easy data transfer, atomic operations and to be able to modify list of subzones on remote secondary nameservers.

Example of a complete dataset that contains subzone `proxies' with a list of open proxies, subzone `relays' with a list of open relays, subzone `multihop' with output IPs of multihop open relays, and the base zone itself includes proxies and relays but not multihops:

  # common section
  $NS 1w ns1.ex.com ns2.ex.com
  $SOA 1w ns1.ex.com admin.ex.com 0 2h 2h 1w 1h
  # list of open proxies,
  # in `proxies' subzone and in base zone
  $DATASET ip4set:proxy proxies @
  :2:Open proxy, see http://bl.ex.com/proxy/$
  127.0.0.2
  127.0.0.10
  # list of open relays,
  # in `relays' subzone and in base zone
  $DATASET ip4set:relay relays @
  :3:Open relay, see http://bl.ex.com/relay/$
  127.0.0.2
  127.0.2.10
  # list of optputs of multistage relays,
  # in `multihop' subzone only
  $DATASET ip4set:multihop-relay multihop
  :4:Multihop open relay, see http://bl.ex.com/relay/$
  127.0.0.2
  127.0.9.12
  # for the base zone and all subzones,
  # include several additional records
  $DATASET generic:common proxies relays multihop @
  @ A 127.0.0.8
  www A 127.0.0.8
  @ MX 10 mx.ex.com
  # the above results in having the following records
  # (provided that the base zone specified is bl.ex.com):
  #  proxies.bl.ex.com A 127.0.0.8
  #  www.proxies.bl.ex.com 127.0.0.8
  #  relays.bl.ex.com A 127.0.0.8
  #  www.relays.bl.ex.com 127.0.0.8
  #  multihop.bl.ex.com A 127.0.0.8
  #  www.multihop.bl.ex.com 127.0.0.8
  #  bl.ex.com A 127.0.0.8
  #  www.bl.ex.com 127.0.0.8

Note that $NS and $SOA values applies to the base zone only, regardless of the placement in the file. Unlike the $TTL values and $n substitutions, which may be both global and local for a given (sub-)dataset.

Resulting A values and TXT templates

  :127.0.0.2:Blacklisted: http://example.com/bl?$

  127.0.0.2 :127.0.0.2:Blacklisted: http://example.com/bl?$

  127.0.0.2 Blacklisted: http://example.com/bl?$

Two parts of a line, delimited by second colon, specifies A and TXT record values. Both are optional. By default (either if no default line specified, or no IP address within that line), rbldnsd will return 127.0.0.2 as A record. 127.0.0 prefix for A value may be omitted, so the above example may be simplified to:

  :2:Blacklisted: http://example.com/bl?$

When A value is specified for a given entry, but TXT template is omitted, there may be two cases interpreted differently, namely, whenever there's a second semicolon (:) after the A value. If there's no second semicolon, default TXT value for this scope will be used. In contrast, when second semicolon is present, no TXT template will be generated at all. All possible cases are outlined in the following example:

  # default A value and TXT template
  :127.0.0.2:IP address $ is listed
  # 127.0.0.4 will use default A and TXT
  127.0.0.4
  # 127.0.0.5 will use specific A and default TXT
  127.0.0.5 :5
  # 127.0.0.6 will use specific a and no TXT
  127.0.0.6 :6:
  # 127.0.0.7 will use default A and specific TXT
  127.0.0.7 IP address $ running an open relay

In a TXT template, references to substitution variables are replaced with values of that variables. In particular, single dollar sign ($) is replaced by a listed entry (an IP address in question for IP-based datasets and the domain name for domain-based datasets). $n-style constructs, where n is a single digit, are replaced by a substitution variable $n defined for this dataset in current scope (see section "Special Entries" above). To specify a dollar sign as-is, use $$.

For example, the following lines:

  $1 See http://www.example.com/bl
  $2 for details
  127.0.0.2  $1/spammer/$ $2
  127.0.0.3  $1/relay/$ $2
  127.0.0.4  This spammer wants some $$$$.  $1/$

  See http://www.example.com/bl/spammer/127.0.0.2 for details
  See http://www.example.com/bl/relay/127.0.0.3 for details
  This spammer wants some $$.  See http://www.example.com/bl/127.0.0.4

If the "base template" ($= variable) is defined, this template is used for expansion, instead of the one specified for an entry being queried. Inside the base template, $= construct is substituted with the text given for individual entries. In order to stop usage of base template $= for a single record, start it with = (which will be omitted from the resulting TXT value). For example,

  $0 See http://www.example.com/bl?$= ($) for details
  127.0.0.2	r123
  127.0.0.3
  127.0.0.4	=See other blocklists for details about $

  See http://www.example.com/bl?r123 (127.0.0.2) for details
  See http://www.example.com/bl?127.0.0.3 (127.0.0.3) for details
  See other blocklists for details about 127.0.0.4

acl Dataset

:ignore

ignore all queries from this IP address altogether. rbldnsd acts like there was no query received at all. This is the default action.

:refuse

refuse all queries from the IP in question. rbldnsd will always return REFUSED DNS response code.

:empty

pretend there's no data in all other datasets for the given zone. This means that all the clients in question will always receive reply from rbldnsd telling that the requested IP address or domain name is not listed in a given DNSBL. rbldnsd still replies to metadata queries (SOA and NS records, and to all queries satisfied by generic dataset if specified for the given zone) as usual.

:pass

process the request as usual. This may be used to add a "whitelisting" entry for a network/host bloked by another (larger) ACL entry.

a_txt_template

usual A+TXT template as used by other datasets. This means that rbldnsd will reply to any valid DNSBL query with "it is listed" answer, so that the client in question will see every IP address or domain name is listed in a given DNSBL. TXT record used in the reply is taken from the acl dataset instead of real datasets. Again, just like with empty case, rbldnsd will continue replying to metadata queries (including generic datasets if any) as usual.

Only one ACL dataset can be specified for a given zone, and each zone must have at least one non-acl dataset. It is also possible to specify one global ACL dataset, by specifying empty zone name (which is not allowed for other dataset types), like

  rbldnsd ... :acl:filename...

For this dataset type, only a few $-style specials are recognized. In particular, $SOA and $NS keywords are not allowed. When rbldnsd performs $ substitution in the TXT template returned from ACL dataset, it will use client IP address to substitute for a single $ character, instead of the IP address or domain name found in the original query.

Generating and transferring data files

Right:

  scp remote:data target.tmp && mv target.tmp target

  scp remote:data target

  ./generate.pl > target.tmp && mv target.tmp target

  ./generate.pl > target

From this point of view, rsync(1) command seems to be safe, as it always creates temporary file and renames it to the destination only when all is ok (but note the --partial option, which is good for downloading something but may be wrong to transfer data files -- usually you don't want partial files to be loaded). In contrast, scp(1) command is not safe, as it performs direct copying. You may still use scp(1) in a safe manner, as shown in the example above.

Also try to eliminate a case when two (or more) processes performs data copying/generation at the same time to the same destination. When your data is generated by a cron job, use file locking (create separate lock file (which should never be removed) and flock/fcntl it in exclusive mode without waiting, exiting if lock fails) before attempting to do other file manipulation.

Absolute vs relative domain names

Aggregating datasets

 rbldnsd options... \
   dialups.bl.ex.com:ip4set:dialups \
   spam.bl.ex.com:ip4set:spammers \
   bl.ex.com:ip4set:dialups,spammers

or:

 rbldnsd options... \
   dialups.bl.ex.com:ip4set:dialups \
   spam.bl.ex.com:ip4set:spammers \
   bl.ex.com:ip4set:dialups \
   bl.ex.com:ip4set:spammers

(note you should specify combined bl.ex.com zone after all its subzones in a command line, or else subzones will not be consulted at all).

In the first form, there will be 3 independent data sets, and every record will be stored 2 times in memory, but only one search in internal data structures will be needed to resolve queries for aggregate bl.ex.com. In second form, there will be only 2 data sets, every record will be stored only once (both datasets will be reused), but 2 searches will be performed by rbldnsd to answer queries against aggregate zone (but difference in speed is almost unnoticeable). Note that when aggregating several data files into one dataset, an exclusion entry in one file becomes exclusion entry in the whole dataset (which may be a problem when aggregating dialups, where exclusions are common, with open relays/proxies, where exclusions are rare if at all used).

Similar effect may be achieved by using combined dataset type, sometimes more easily. combined dataset results in every nested dataset to be used independantly, like in second form above.

combined dataset requires rbldnsd to be the authoritative nameserver for the whole base zone. Most important, one may specify SOA and NS records for the base zone only. So, some DNSBLs which does not use a common subzone for the data, cannot use this dataset. An example being DSBL.org DNSBL, where each of list.dsbl.org, multihop.dsbl.org and unconfirmed.dsbl.org zones are separate, independant zones with different set of nameservers. But for DSBL.org, where each dataset is really independant and used only once (there's no (sub)zone that is as a combinations of other zones), combined dataset isn't necessary. In contrast, SORBS.net zones, where several subzones used and main zone is a combination of several subzones, combined dataset is a way to go.

All authoritative nameservers should be set up similarily

  dialups.bl.ex.com. IN NS a.ns.ex.com.

  bl.ex.com. IN NS a.ns.ex.com.

Generic dataset usage

Since rbldnsd only searches one, most closely matching (sub)zone for every request, one cannot specify a single e.g. generic dataset in form

  proxies      TXT list of open proxies
  www.proxies  A 127.0.0.8
  relays       TXT list of open relays
  www.relays   A 127.0.0.9