rbldnsd NAME
SYNOPSIS
DESCRIPTION
OPTIONS
DATASET TYPES AND FORMATS
SIGNALS
NOTES
BUGS
VERSION
AUTHOR
LICENCE
NAME
rbldnsd − DNS daemon suitable for running DNS−based blocklists |
SYNOPSIS
rbldnsd |
DESCRIPTION
rbldnsd rbldnsd rbldnsd For rbldnsd Several zones may be specified in command line, so that There are several dataset formats available, each is suitable and optimized (in terms of memory, speed and ease of use) for a specific task. Available dataset types may be grouped into the following categories: |
lists of IP addresses. When a query is done to a zone with such data, query is interpreted as an IP address in a reverse form (similar to in−addr.arpa zone). If the address is found in dataset data, lists of domain names. Similar to list of IP addresses, but with generic domain names instead of IPs (wildcards allowed). This type of data may be used to form a blocklist of e.g. sender domain names. generic list of various types of records, as an auxilary data to form a complete nameserver. This format is similar to bind−style datafiles, but very simplified. One may specify A, TXT, NS and MX records here. combined set, different datasets from the list above combined in the single (set of) source files, for easy maintenance. acl, or Access Control List. This is a pseudo dataset, that works by overweriting query results based on the requestor (peer) IP address. |
OPTIONS
The following options may be specified: |
−u |
rbldnsd |
−r |
rbldnsd |
−w |
rbldnsd |
−b |
This option is |
−4 | Use IPv4 listening socket/transport, do not attempt to use IPv6 (ignored if | ||
−6 | Use IPv6 listening socket/transport, do not attempt to use IPv4 (this option will be reported as error if IPv6 support was not compiled in). |
−t |
Set default reply time−to−live (TTL) value to be |
−c |
Set interval between checking for zone file changes to be |
−e | Allow non−network addresses to be used in CIDR ranges. Normally, | ||
−q | Quick and quiet start. Normally, |
−p |
Write rbldnsd’s pid to the specified |
−l |
Specifies a file to which log all requests made. This file is created after entering a chroot jail and becoming a user. Logfiles may be quite large, esp. on busy sites (rbldnsd |
−s |
Specifies a file where timestamp zone:qtot:qok:qnxd:bin:bout zone:... where 1234 bl1.ex:10:5:4:311:432 bl2.ex:24:13:7:248:375 *:98:35:12:820:987 Note the total values may be larger than the sum of per-zone values, due to queries made against unlisted zones, or bad/broken packets. Rbldnsd By default, |
−n | Do not become a daemon. Normally, | ||
−f | Request | ||
−d | Dump all zones to stdout in BIND format and exit. This may be suitable to convert easily editable rbldnsd-style data into BIND zone. | ||
−v | Do not show exact version information in response to version.bind CH TXT queries (by default | ||
−C | Disable automatic on−the−fly uncompression of data files if this feature is compiled in (see below). | ||
−A | |||
−a | Controls "laziness" of |
−x |
Load the given |
−X |
Pass the given argument, |
DATASET TYPES AND FORMATS
Dataset files are text files which are interpreted depending on type specified in command line. Empty lines and lines starting with hash character (#) or semicolon (;) are ignored, except for a special case outlined below in section titled "Special Entries". A (comma−separated) list of files in dataset specification (in When compiled with zlib support, rbldnsd |
Special Entries |
If a line starts with a dollar sign ($), hash character and a dollar sign (#$), semicolon and dollar sign (;#) or colon and a dollar sign (:$), it is interpreted in a special way, regardless of dataset type (this is one exception where a line starting with hash character is not ignored − to be able to use zone files for both |
$SOA |
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, |
If If All time fields (ttl, refresh, retry, expire, minttl) may be specified in time units. See |
$NS |
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 |
$TTL |
Specifies TTL (time-to-live) value for all records in current dataset. See also |
$TIMESTAMP |
(experimental) Specifies the data timestamp |
Note that |
$MAXRANGE4 |
Specifies maximum size of IPv4 range allowed for IPv4−based datasets. If an entry covers more IP addresses than $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 |
$= |
Set the base template for all individual TXT records. See section "Resulting A values and TXT templates" below for more information. |
ip4set Dataset |
A set of IP addresses or CIDR address ranges, together with A and TXT resulting values. IP addresses are specified one per line, by an IP address prefix (initial octets), complete IP address, CIDR range, or IP prefix range (two IP prefixes or complete addresses delimited by a dash, inclusive). Examples, to specify 127.0.0.0/24: 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 to specify 127.16.0.0−127.31.255.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 Note that in prefix range, last boundary is completed with all−ones (255), not all−zeros line with first boundary and a prefix alone. In prefix ranges, if last boundary is only one octet (127.16−31), it is treated as "suffix", as value of last 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 In this case all characters up to the end of line are ignored, and default A and TXT values will be used for this IP range. Every IP address that fits within any of specified ranges is "listed", and 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, |
ip4trie Dataset |
Set of IP4 CIDR ranges with corresponding (A, TXT) values. Similar to ip4set, but uses different internal representation (implemented as a patricia trie), accepts CIDR ranges only (not a.b.c.d−e.f.g.h), allows to specify only one value per CIDR range, and returns only one, most close matching, entry on queries. Exclusions are supported too. This dataset is not memory-efficient to store many single IP addresses, but it is ok to use it to store many possible wide CIDR ranges. |
ip4tset Dataset |
"trivial" ip4set: a set of single IP addresses (one per line), with the same A+TXT template. This dataset type is more efficient than ip4set (in both memory usage and access times), but have obvious limitation. It is intended for DNSBLs like DSBL.org, ORDB.org and similar, where each entry uses the same default A+TXT template. This dataset uses only half a memory for the same list of IP addresses compared to |
dnset Dataset |
Set of (possible wildcarded) domain names with associated A and TXT values. Similar to 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 |
This dataset type may be used instead of |
generic Dataset |
Generic type, simplified bind−style format. Every record should be on one line (line continuations are not supported), and should be specified completely (i.e. all domain names in values should be fully−qualified, entry name may not be omitted). No wildcards are accepted. Only A, TXT, and MX records are recognized. TTL value may be specified before record type. Examples: |
# 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 |
This is a special dataset that stores no data by itself but acts like a container for several other datasets of any type except of combined type itself. The data file contains an optional common section, where various specials are recognized like $NS, $SOA, $TTL (see above), and a series of sections, each of which defines one (nested) dataset and several subzones of the base zone, for which this dataset should be consulted. New (nested) dataset starts with a line $DATASET type[:name] subzone subzone... and all subsequent lines up to the end of current file or to next $DATASET line are interpreted as a part of dataset of type 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 |
Resulting A values and TXT templates |
In all zone file types except generic, A values and TXT templates are specified as following: :127.0.0.2:Blacklisted: http://example.com/bl?$ If a line starts with a colon, it specifies default A and TXT for all subsequent entries in this dataset. Similar format is used to specify values for individual records, with the A value (enclosed by colons) being optional: 127.0.0.2 :127.0.0.2:Blacklisted: http://example.com/bl?$ or, without specific A value: 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), :2:Blacklisted: http://example.com/bl?$ There is no default TXT value, so 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). 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/$ will result in the following text to be generated: 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" ($= $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 $ |
produces the following TXT records: 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 |
This is not a real dataset, while the syntax and usage is the same as with other datasets. Instead of defining which records exists in a given zone and which does not, |
:ignore |
ignore all queries from this IP address altogether. |
:refuse |
refuse all queries from the IP in question. |
: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 | |
: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 |
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... In this case the ACL defined in For this dataset type, only a few $-style specials are recognized. In particular, $SOA and $NS keywords are not allowed. When |
SIGNALS
Rbldnsd |
SIGHUP | recheck zone files and reload any outdated ones. This is done automatically if enabled, see |
SIGTERM, |
Terminate process. |
SIGUSR1 |
Log current statistic counters into syslog. |
SIGUSR2 |
The same as SIGUSR1, but reset all counters and start new sample period. |
NOTES
Some unsorted usage notes follows. |
Generating and transferring data files |
When creating a data file for Right: scp remote:data target.tmp && mv target.tmp target Wrong: scp remote:data target Right: ./generate.pl > target.tmp && mv target.tmp target Wrong: ./generate.pl > target From this point of view, 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 |
All |
Aggregating datasets |
Several zones may be served by 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 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 Similar effect may be achieved by using combined |
All authoritative nameservers should be set up similarily |
When you have several nameservers for your zone, set them all in a similar way. Namely, if one is set up using dialups.bl.ex.com. IN NS a.ns.ex.com. while second will always use base zone, and NS records will look like bl.ex.com. IN NS a.ns.ex.com. All authoritative nameservers for a zone must have consistent metadata records. The only way to achieve this is to use similar configuration (combined or not) on all nameservers. Have this in mind when using other software for a nameserver. |
Generic dataset usage |
generic Since 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 for several (sub)zones, each of which are represented as a zone too (either in command line or as |
BUGS
Most of the bugs outlined in this section aren’t really bugs, but present due to non-standartized and thus unknown expected behaviour of a nameserver that serves a DNSBL zone. rbldnsd There is no TCP mode. If a resource record does not fit in UDP packet (512 bytes), it will be silently ignored. For most usages, this isn’t a problem, because there should be only a few RRs in an answer, and because one record is usually sufficient to decide whenever a given entry is "listed" or not. rbldnsd rbldnsd rbldnsd |
VERSION
This manpage corresponds to |
AUTHOR
The |
LICENCE
GPL. |