1rbldnsd(8) System Manager's Manual rbldnsd(8)
2
6 rbldnsd - DNS daemon suitable for running DNS-based blocklists
7
9 rbldnsd options zone:dataset...
10
13 rbldnsd is a small DNS-protocol daemon which is designed to handle
14 queries to DNS-based IP-listing or NAME-listing services. Such ser‐
15 vices are a simple way to share/publish a list of IP addresses or
16 (domain) names which are "listed" for for some reason, for example in
17 order to be able to refuse a service to a client which is "listed" in
18 some blocklist.
19 rbldnsd is not a general-purpose nameserver. It will answer to A and
22 TXT (and SOA and NS if such RRs are specified) queries, and has limited
23 ability to answer to some other types of queries.
24 rbldnsd tries to handle data from two different perspectives: given a
27 set (or several) of "listed entries" (e.g. IP address ranges or domain
28 names), it builds and serves a DNS zone. Note the two are not the
29 same: list of spammer's IPs is NOT a DNS zone, but may be represented
30 and used as such, provided that some additional information necessary
31 to build complete DNS zone (e.g. NS and SOA records, maybe A records
32 necessary for http to work) is available. In this context, rbldnsd is
33 very different from other general-purpose nameservers such as BIND or
34 NSD: rbldnsd operates with datasets (sets of entries - IP addresses or
35 domain names, logically grouped together), while other general-purpose
36 nameservers operates with zones. The way how rbldnsd operates may be
37 somewhat confusing to BIND experts.
38 For rbldnsd, a building block is a dataset: e.g., set of inse‐
41 cure/abuseable hosts (IP addresses), set of network ranges that belongs
42 to various spam operations (IP ranges), domain names that belong to
43 spammers (RHSBL) and so on. Usually, different kind of information is
44 placed into separate file, for easy maintenance. From a number of such
45 datasets, rbldnsd constructs a number of DNS zones as specified on com‐
46 mand line. A single dataset may be used for several zones, and a sin‐
47 gle zone may be constructed from several datasets.
48 rbldnsd will answer queries to DNS zones specified on the command line
51 as a set of zone specifications. Each zone specification consists of
52 zone basename, dataset type and a comma-separated list of files that
53 forms a given dataset: zone:type:file,file,...
54 Several zones may be specified in command line, so that rbldnsd will
57 answer queries to any of them. Also, a single zone may be specified
58 several times with different datasets, so it is possible to form a zone
59 from a combination of several different dataset. The same dataset may
60 be reused for several zones too (and in this case, it will be read into
61 memory only once).
62 There are several dataset formats available, each is suitable and opti‐
65 mized (in terms of memory, speed and ease of use) for a specific task.
66 Available dataset types may be grouped into the following categories:
67 lists of IP addresses. When a query is done to a zone with such
69 data, query is interpreted as an IP address in a reverse form
70 (similar to in-addr.arpa zone). If the address is found in
71 dataset data, rbldnsd will return A and TXT records specified in
72 data for that IP. This is a classical IP-based blocklist.
73 lists of domain names. Similar to list of IP addresses, but
75 with generic domain names instead of IPs (wildcards allowed).
76 This type of data may be used to form a blocklist of e.g.
77 sender domain names.
78 generic list of various types of records, as an auxilary data to
80 form a complete nameserver. This format is similar to
81 bind-style datafiles, but very simplified. One may specify A,
82 TXT, NS and MX records here.
83 combined set, different datasets from the list above combined in
85 the single (set of) source files, for easy maintenance.
86 acl, or Access Control List. This is a pseudo dataset, that
88 works by overweriting query results based on the requestor
89 (peer) IP address.
90
93 The following options may be specified:
94 -u user[:group]
97 rbldnsd will change its userid to the specified user, which
98 defaults to rbldns, and group, which by default is the primary
99 group of a user. rbldnsd will refuse to run as the root user,
100 since this is insecure.
101 -r rootdir
104 rbldnsd will chroot to rootdir if specified. Data files should
105 be available inside rootdir.
106 -w workdir
109 rbldnsd will change its working directory to workdir (after
110 chrooting to rootdir if -r option is also specified). May be
111 used to shorten filename paths.
112 -b address/port
115 This option is required. rbldnsd will bind to specified address
116 and port (port defaults to port 53, domain). Either numeric IP
117 address or a hostname may be specified, and either port number
118 or service name is accepted. It is possible to specify several
119 addresses to listen on this way, by repeating -b option. Addi‐
120 tionally, if there are several addresses listed for a hostname,
121 rbldnsd will listen on all of them. Note that rbldnsd will work
122 slightly faster if only one listening address is specified.
123 Note the delimiter between host and port is a slash (/), not a
124 colon, to be able to correctly handle IPv6 addresses.
125 -4 Use IPv4 listening socket/transport, do not attempt to use IPv6
128 (ignored if rbldnsd was built without IPv6 support).
129 -6 Use IPv6 listening socket/transport, do not attempt to use IPv4
132 (this option will be reported as error if IPv6 support was not
133 compiled in).
134 -t defttl:minttl:maxttl
137 Set default reply time-to-live (TTL) value to be defttl, and set
138 constraints for TTL to minttl and maxttl. Default applies when
139 there's no TTL defined in a given scope (in data file), and con‐
140 straints are applied when such value provided in data. Any of
141 the values may be omitted, including trailing colon (:) charac‐
142 ters, e.g. "-t 30" set default TTL to be 30 secound, and
143 "-t ::120" or "-t ::2m" sets maximum allowed TTL to 2 minutes.
144 All 3 values are in time units, with optional suffix: s (sec‐
145 ounds, default), m (minutes), h (hours), d (days) or w (weeks).
146 Zero minttl or maxttl means no corresponding constraint will be
147 enforced. Default defttl is 35m.
148 -c check
151 Set interval between checking for zone file changes to be check,
152 default is 1m (one minute). rbldnsd will check zone file's last
153 modification time every so often, and if it detects a change,
154 zone will be automatically reloaded. Setting this value to 0
155 disables automatic zone change detection. This procedure may
156 also be triggered by sending a SIGHUP signal to rbldnsd (see
157 SIGNALS section below).
158 -e Allow non-network addresses to be used in CIDR ranges. Nor‐
161 mally, rbldnsd rejects addresses such as 127.2.3.4/24, where
162 prefix is not within the network mask derived from bit number
163 (in this case, correct form is 127.2.3.0/24, note the trailing
164 zero in prefix). This is done in order to catch possible typos
165 in zones (rbldnsd will warn about a problem and will ignore such
166 entry). This option disables checking whether the CIDR prefix
167 fits within the network mask.
168 -q Quick and quiet start. Normally, rbldnsd does socket initial‐
171 ization and zone load in foreground, writing progress and
172 statistic to standard output, and aborts in case of any errors.
173 With this flag, nothing will be printed and first zone load will
174 be done in background (unless -n option is also given), and zone
175 load errors will be non-fatal.
176 -p pidfile
179 Write rbldnsd's pid to the specified pidfile, so it will be eas‐
180 ily findable. This file gets written before entering a chroot
181 jail (if specified) and before changing userid, so it's ok to
182 specify e.g. /var/run/rbldnsd.pid here.
183 -l logfile
186 Specifies a file to which log all requests made. This file is
187 created after entering a chroot jail and becoming a user. Log‐
188 files may be quite large, esp. on busy sites (rbldnsd will log
189 every recognized request if this option is specified). This
190 option is mainly intended for debugging purposes. Upon receip‐
191 tion of SIGHUP signal, rbldnsd reopens its logfile. If logfile
192 prefixed with a plus sign (+), logging will not be buffered
193 (i.e. each line will be flushed to disk); by default, logging is
194 buffered to reduce system load. Specify a single hyphen (-) as
195 a filename to log to standard output (filedescriptor 1), either
196 buffered by default, or line-buffered if specified as `+-'
197 (standard output will not be "reopened" upon receiving SIGHUP
198 signal, but will be flushed in case logging is buffered).
199 -s statsfile
202 Specifies a file where rbldnsd will write a line with short
203 statistic summary of queries made per zone, every check (-c)
204 interval. Format of each line is:
205 timestamp zone:qtot:qok:qnxd:bin:bout zone:...
206 where timestamp is unix time (secounds since epoch), zone is the
207 name of the base zone, qtot is the total number of queries
208 received, qok - number of positive replies, qnxd - number of
209 NXDOMAIN replies, bin is the total number of bytes read from
210 network (excluding IP/UDP overhead and dropped packets), bout is
211 the total number of bytes written to network. Ther are as many
212 such tuples as there are zones, and one extra, total typle at
213 the end, with zone being "*", like:
214 1234 bl1.ex:10:5:4:311:432 bl2.ex:24:13:7:248:375 *:98:35:12:820:987
215 Note the total values may be larger than the sum of per-zone
216 values, due to queries made against unlisted zones, or bad/bro‐
217 ken packets.
218 Rbldnsd will write bare timestamp to statsfile when it is start‐
220 ing up, shutting down or when statistic counters are being reset
221 after receiving SIGUSR2 signal (see below), to indicate the
222 points where the counters are starting back from zero.
223 By default, rbldnsd writes absolute counter values into stats‐
225 file (number of packets (bytes) since startup or last reset).
226 statsfile may be prefixed with plus sign (+), in which case
227 rbldnsd will write delta values, that is, number of packets or
228 bytes since last write, or number of packets (bytes) per unit of
229 time ("incremental" mode, hence the "+" sign).
230 -n Do not become a daemon. Normally, rbldnsd will fork and go to
233 the background after successful initialization. This option
234 disables this behaviour.
235 -f Request rbldnsd to continue processing requests during data
238 reloads. Rbldnsd forks a child process to handle requests while
239 parent reloads the data. This ensures smooth operations, but
240 requires more memory, since two copies of data is keept in mem‐
241 ory during reload process.
242 -d Dump all zones to stdout in BIND format and exit. This may be
245 suitable to convert easily editable rbldnsd-style data into BIND
246 zone. rbldnsd dumps all zones as one stream, so one may want to
247 specify only one zone with -d. Zone file will have appropriate
248 $ORIGIN tags. Note that data generated may be really huge (as
249 BIND format isn't appropriate for this sort of things), and some
250 entries may not be really the same in BIND as in rbldnsd (e.g.,
251 IP netblocks of large size will be represented as wildcard
252 entries - 10.0.0.0/8 will become *.10; excluded entries will be
253 represented by a CNAME to `excluded' name, so such name should
254 not be present in a data set). In this mode, rbldnsd ignores -r
255 (root directory) option.
256 -v Do not show exact version information in response to ver‐
259 sion.bind CH TXT queries (by default rbldnsd responds to such
260 queries since version 0.98). With single -v, rbldnsd will only
261 return "rbldnsd" to the caller, without the version number.
262 Second -v disables providing any information in response to such
263 requests, i.e. rbldnsd will return REFUSE code.
264 -C Disable automatic on-the-fly uncompression of data files if this
267 feature is compiled in (see below).
268 -A
271 -a Controls "laziness" of rbldnsd when constructing replies. With
273 -a specified, rbldnsd does not add AUTH section (containing NS
274 records) to replies unless explicitly asked for NS records. It
275 is equivalent to BIND9 "minimal-answers" configuration setting.
276 While with -A specified, rbldnsd will always fill in AUTH sec‐
277 tion, increasing size of replies dramatically but allowing
278 (caching) resolver clients to react faster to changes in name‐
279 server lists. Currently (as of 0.998 version), non-lazy (as
280 with -A) mode is the default, but it will change in future
281 release.
282 -x extension
285 Load the given extension file (a dynamically-linked library,
286 usually with ".so" suffix). This allows to gather custom sta‐
287 tistics or perform other custom tasks. See separate document
288 for details about building and using extensions. This feature
289 is not available on all platforms, and can be disabled at com‐
290 pile time.
291 -X extarg
294 Pass the given argument, extarg, to the extension loaded with
295 -x.
296
299 Dataset files are text files which are interpreted depending on type
300 specified in command line. Empty lines and lines starting with hash
301 character (#) or semicolon (;) are ignored, except for a special case
302 outlined below in section titled "Special Entries".
303 A (comma-separated) list of files in dataset specification (in
306 type:file,file,...) is interpreted as if all files where logically com‐
307 bined into one single file.
308 When compiled with zlib support, rbldnsd is able to read gzip-com‐
311 pressed data files. So, every file in dataset specification can be
312 compressed with gzip(1), and rbldnsd will read such a file decompress‐
313 ing it on-the-fly. This feature may be turned off by specifying -C
314 option.
315 rbldnsd is designed to service a DNSBL, where each entry have single A
318 record and optional TXT record assotiated with it. rbldnsd allows to
319 specify A value and TXT template either for each entry individually, or
320 to use default A value and TXT template pair for a group of entries.
321 See section "Resulting A values and TXT templates" below for a way to
322 specify them.
323 Special Entries
326 If a line starts with a dollar sign ($), hash character and a dollar
327 sign (#$), semicolon and dollar sign (;#) or colon and a dollar sign
328 (:$), it is interpreted in a special way, regardless of dataset type
329 (this is one exception where a line starting with hash character is not
330 ignored - to be able to use zone files for both rbldnsd and for DJB's
331 rbldns). The following keywords, following a dollar sign, are recog‐
332 nized:
333 $SOA ttl origindn persondn serial refresh retry expire minttl
336 Specifies SOA (Start Of Authority) record for all zones using
337 this dataset. Only first SOA record is interpreted. This is
338 the only way to specify SOA - by default, rbldnsd will not add
339 any SOA record into answers, and will REFUSE to answer to cer‐
340 tain queries (notably, SOA query to zone's base domain name).
341 It is recommended, but not mandatory to specify SOA record for
342 every zone. If no SOA is given, negative replies will not be
343 cacheable by caching nameservers. Only one, first $SOA line is
344 recognized in every dataset (all subsequent $SOA lines encoun‐
345 tered in the same dataset are silently ignored). When con‐
346 structing a zone, SOA will be taken from first dataset where
347 $SOA line is found, in an order as specified in command line,
348 subsequent $SOA lines, if any, are ignored. This way, one may
349 overwrite $SOA found in 3rd party data by prepending small local
350 file to the dataset in question, listing it before any other
351 files.
352 If serial value specified is zero, timestamp of most recent mod‐
354 ified file will be substituted as serial.
355 If ttl field is zero, default ttl (-t option or last $TTL value,
357 see below) will be used.
358 All time fields (ttl, refresh, retry, expire, minttl) may be
360 specified in time units. See -t option for details.
361 $NS ttl nameserverdn nameserverdn...
364 Specifies NS (Name Server) records for all zones using this
365 dataset. Only first $NS line in a dataset is recognized, all
366 subsequent lines are silently ignored. When constructing a zone
367 from several datasets, rbldnsd uses nameservers from $NS line in
368 only first dataset where $NS line is given, in command-line
369 order, just like for $SOA record. Only first 32 namservers are
370 recognized. Individual nameserver(s) may be prefixed with a
371 minus sign (-), which means this single nameserver will be
372 ignored by rbldnsd. This is useful to temporary comment out one
373 nameserver entry without removing it from the list. If ttl is
374 zero, default ttl will be used. The list of NS records, just
375 like $SOA value, are taken from the first data file in a dataset
376 where the $NS line is found, subsequent $NS lines, if any, are
377 ignored.
378 $TTL time-to-live
381 Specifies TTL (time-to-live) value for all records in current
382 dataset. See also -t option. $TTL special overrides -t value
383 on a per-dataset basis.
384 $TIMESTAMP dstamp [expires]
387 (experimental) Specifies the data timestamp dstamp when the data
388 has been generated, and optionally when it will expire. The
389 timestamps are in form yyyy:mm:dd[:hh[:mi[:ss]]], where yyyy is
390 the year like 2005, mm is the month number (01..12), dd is the
391 month day number (01..31), hh is hour (00..23), mi and ss are
392 minutes and secounds (00.59); hours, minutes and secounds are
393 optional and defaults to 0; the delimiters (either colon or dash
394 may be used) are optional too, but are allowed for readability.
395 Also, single zero (0) or dash (-) may be used as dstamp and/or
396 expires, indicating the value is not given. expires may also be
397 specified as +rel, where rel is a time specification (probably
398 with suffix like s, m, h, d) as an offset to dstamp. rbldnsd
399 compares dstamp with current timestamp and refuses to load the
400 file if dstamp specifies time in the future. And if expires is
401 specified, rbldnsd will refuse to service requests for that data
402 if current time is greather than the value specified in expires
403 field.
404 Note that rbldnsd will check the data expiry time every time it
406 checks for data file updates (when receiving SIGHUP signal or
407 every -c interval). If automatic data reload timer (-c option)
408 is disabled, zones will not be exipired automatically.
409 $MAXRANGE4 range-size
412 Specifies maximum size of IPv4 range allowed for IPv4-based
413 datasets. If an entry covers more IP addresses than range-size,
414 it will be ignored (and a warning will be logged). range-size
415 may be specified as a number of hosts, like 256, or as network
416 prefix lenght, like /24 (the two are the same):
417 $MAXRANGE4 /24
418 $MAXRANGE4 256
419 This constraint is active for a dataset it is specified in, and
420 can be owerwritten (by subsequent $MAXRANGE statement) by a
421 smaller value, but can not be increased.
422 $n text
425 (n is a single digit). Specifies a substitution variable for
426 use as $n placeholders (the $n entries are ignored in generic
427 daaset). See section "Resulting A values and TXT templates"
428 below for description and usage examples.
429 $= text
432 Set the base template for all individual TXT records. See sec‐
433 tion "Resulting A values and TXT templates" below for more
434 information.
435 ip4set Dataset
438 A set of IP addresses or CIDR address ranges, together with A and TXT
439 resulting values. IP addresses are specified one per line, by an IP
440 address prefix (initial octets), complete IP address, CIDR range, or IP
441 prefix range (two IP prefixes or complete addresses delimited by a
442 dash, inclusive). Examples, to specify 127.0.0.0/24:
443 127.0.0.0/24
444 127.0.0
445 127/24
446 127-127.0.0
447 127.0.0.0-127.0.0.255
448 127.0.0.1-255
449 to specify 127.16.0.0-127.31.255.255:
450 127.16.0.0-127.31.255.255
451 127.16.0-127.31.255
452 127.16-127.31
453 127.16-31
454 127.16.0.0/12
455 127.16.0/12
456 127.16/12
457 Note that in prefix range, last boundary is completed with all-ones
458 (255), not all-zeros line with first boundary and a prefix alone. In
459 prefix ranges, if last boundary is only one octet (127.16-31), it is
460 treated as "suffix", as value of last specified octet of the first
461 boundary prefix (127.16.0-31 is treated as 127.16.0.0-127.16.31.255,
462 i.e. 127.16.0.0/19).
463 After an IP address range, A and TXT values for a given entry may be
465 specified. If none given, default values in current scope (see below)
466 applies. If a value starts with a colon, it is interpreted as a pair
467 of A record and TXT template, delimited by colon (:127.0.0.2:This entry
468 is listed). If a value does not start with a colon, it is interpreted
469 as TXT template only, with A record defaulting to the default A value
470 in current scope.
471 IP address range may be followed by a comment char (either hash charac‐
473 ter (#) or semicolon (;)), e.g.:
474 127/8 ; loopback network
475 In this case all characters up to the end of line are ignored, and
476 default A and TXT values will be used for this IP range.
477 Every IP address that fits within any of specified ranges is "listed",
479 and rbldnsd will respond to reverse queries against it within specified
480 zone with positive results. In contrast, if an entry starts with an
481 exclamation sign (!), this is an exclusion entry, i.e. corresponding
482 address range is excluded from being listed (and any value for this
483 record is ignored). This may be used to specify large range except
484 some individual addresses, in a compact form.
485 If a line starts with a colon (:), this line specifies the default A
487 value and TXT template to return (see below) for all subsequent entries
488 up to end of current file. If no default entry specified, and no value
489 specified for a given record, rbldnsd will return 127.0.0.2 for match‐
490 ing A queries and no record for matching TXT queries. If TXT record
491 template is specified and contains occurences of of dollar sign ($),
492 every such occurence is replaced with an IP address in question, so
493 singe TXT template may be used to e.g. refer to a webpage for an addi‐
494 tional information for a specific IP address.
495 ip4trie Dataset
498 Set of IP4 CIDR ranges with corresponding (A, TXT) values. This
499 dataset is similar to ip4set, but uses a different internal representa‐
500 tion. It accepts CIDR ranges only (not a.b.c.d-e.f.g.h), and allows
501 for the specification of A/TXT values on a per CIDR range basis. (If
502 multiple CIDR ranges match a query, the value for longest matching pre‐
503 fix is returned.) Exclusions are supported too.
504 This dataset is not particularly memory-efficient for storing many sin‐
506 gle IP addresses — it uses about 50% more memory than the ip4set
507 dataset in that case. The ip4trie dataset is better adapted, however,
508 for listing CIDR ranges (whose lengths are not a multiple of 8 bits.)
509 ip4tset Dataset
512 "trivial" ip4set: a set of single IP addresses (one per line), with the
513 same A+TXT template. This dataset type is more efficient than ip4set
514 (in both memory usage and access times), but have obvious limitation.
515 It is intended for DNSBLs like DSBL.org, ORDB.org and similar, where
516 each entry uses the same default A+TXT template. This dataset uses
517 only half a memory for the same list of IP addresses compared to
518 ip4set.
519 ip6trie Dataset
522 Set of IP6 CIDR ranges. This is the IP6 equivalent of the ip4trie
523 dataset. It allows the sepecification of individual A/TXT values for
524 each CIDR range and supports exclusions. Compressed ("::") ip6 nota‐
525 tion is supported.
526 Example zone data:
528 # Default A and TXT template valuse
529 :127.0.1.2: Listed, see http://example.com/lookup?$
530 # A listing, note that trailing :0s can be omitted
532 2001:21ab:c000/36
533 # /64 range with non-default A and TXT values
535 2001:21ab:def7:4242 :127.0.1.3: This one smells funny
536 # compressed notation
538 2605:6001:42::/52
539 ::1 # localhost
540 !2605:6001:42::bead # exclusion
541 ip6tset Dataset
544 "Trivial" ip6 dataset: a set of /64 IP6 CIDR ranges (one per line), all
545 sharing a single A+TXT template. Exclusions of single IP6 (/128)
546 addresses are also supported. This dataset type is quite memory-effi‐
547 cient — it uses about 40% of the memory that the ip6trie dataset would
548 use — but has obvious limitations.
549 This dataset wants the /64s listed as four ip6 words, for example:
551 2001:20fe:23:41ed
552 abac:adab:ad00:42f
553 Exclusions are denoted with a leading exclamation mark. You may also
554 use compressed "::" notation for excluded addresses. E.g.:
555 !abac:adab:ad00:42f:face:0f:a:beef
556 !abac:adab:ad00:42f::2
557 dnset Dataset
560 Set of (possible wildcarded) domain names with associated A and TXT
561 values. Similar to ip4set, but instead of IP addresses, data consists
562 of domain names (not in reverse form). One domain name per line, pos‐
563 sible starting with wildcard (either with star-dot (*.) or just a dot).
564 Entry starting with exclamation sign is exclusion. Default value for
565 all subsequent lines may be specified by a line starting with a colon.
566 Wildcards are interpreted as follows:
568 example.com
570 only example.com domain is listed, not subdomains thereof. Not
571 a wildcard entry.
572 *.example.com
574 all subdomains of example.com are listed, but not example.com
575 itself.
576 .example.com
578 all subdomains of example.com and example.com itself are listed.
579 This is a shortcut: to list a domain name itself and all it's
580 subdomains, one may either specify two lines (example.com and
581 *.example.com), or one line (.example.com).
582 This dataset type may be used instead of ip4set, provided all CIDR
584 ranges are expanded and reversed (but in this case, TXT template will
585 be expanded differently).
586 generic Dataset
589 Generic type, simplified bind-style format. Every record should be on
590 one line (line continuations are not supported), and should be speci‐
591 fied completely (i.e. all domain names in values should be fully-quali‐
592 fied, entry name may not be omitted). No wildcards are accepted. Only
593 A, TXT, and MX records are recognized. TTL value may be specified
594 before record type. Examples:
595 # bl.ex.com
597 # specify some values for current zone
598 $NS 0 ns1.ex.com ns2.ex.com
599 # record with TTL
600 www 3000 A 127.0.0.1
601 about TXT "ex.com combined blocklist"
602 combined Dataset
605 This is a special dataset that stores no data by itself but acts like a
606 container for several other datasets of any type except of combined
607 type itself. The data file contains an optional common section, where
608 various specials are recognized like $NS, $SOA, $TTL (see above), and a
609 series of sections, each of which defines one (nested) dataset and sev‐
610 eral subzones of the base zone, for which this dataset should be con‐
611 sulted. New (nested) dataset starts with a line
612 $DATASET type[:name] subzone subzone...
613 and all subsequent lines up to the end of current file or to next
614 $DATASET line are interpreted as a part of dataset of type type, with
615 optional name (name is used for logging purposes only, and the whole
616 ":name" (without quotes or square brackets) part is optional). Note
617 that combined datasets cannot be nested. Every subzone will always be
618 relative to the base zone name specified on command line. If subzone
619 specified as single character "@", dataset will be connected to the
620 base zone itself.
621 This dataset type aims to simplify subzone maintenance, in order to be
623 able to include several subzones in one file for easy data transfer,
624 atomic operations and to be able to modify list of subzones on remote
625 secondary nameservers.
626 Example of a complete dataset that contains subzone `proxies' with a
628 list of open proxies, subzone `relays' with a list of open relays, sub‐
629 zone `multihop' with output IPs of multihop open relays, and the base
630 zone itself includes proxies and relays but not multihops:
631 # common section
632 $NS 1w ns1.ex.com ns2.ex.com
633 $SOA 1w ns1.ex.com admin.ex.com 0 2h 2h 1w 1h
634 # list of open proxies,
635 # in `proxies' subzone and in base zone
636 $DATASET ip4set:proxy proxies @
637 :2:Open proxy, see http://bl.ex.com/proxy/$
638 127.0.0.2
639 127.0.0.10
640 # list of open relays,
641 # in `relays' subzone and in base zone
642 $DATASET ip4set:relay relays @
643 :3:Open relay, see http://bl.ex.com/relay/$
644 127.0.0.2
645 127.0.2.10
646 # list of optputs of multistage relays,
647 # in `multihop' subzone only
648 $DATASET ip4set:multihop-relay multihop
649 :4:Multihop open relay, see http://bl.ex.com/relay/$
650 127.0.0.2
651 127.0.9.12
652 # for the base zone and all subzones,
653 # include several additional records
654 $DATASET generic:common proxies relays multihop @
655 @ A 127.0.0.8
656 www A 127.0.0.8
657 @ MX 10 mx.ex.com
658 # the above results in having the following records
659 # (provided that the base zone specified is bl.ex.com):
660 # proxies.bl.ex.com A 127.0.0.8
661 # www.proxies.bl.ex.com 127.0.0.8
662 # relays.bl.ex.com A 127.0.0.8
663 # www.relays.bl.ex.com 127.0.0.8
664 # multihop.bl.ex.com A 127.0.0.8
665 # www.multihop.bl.ex.com 127.0.0.8
666 # bl.ex.com A 127.0.0.8
667 # www.bl.ex.com 127.0.0.8
668 Note that $NS and $SOA values applies to the base zone only, regardless
670 of the placement in the file. Unlike the $TTL values and $n substitu‐
671 tions, which may be both global and local for a given (sub-)dataset.
672 Resulting A values and TXT templates
675 In all zone file types except generic, A values and TXT templates are
676 specified as following:
677 :127.0.0.2:Blacklisted: http://example.com/bl?$
678 If a line starts with a colon, it specifies default A and TXT for all
679 subsequent entries in this dataset. Similar format is used to specify
680 values for individual records, with the A value (enclosed by colons)
681 being optional:
682 127.0.0.2 :127.0.0.2:Blacklisted: http://example.com/bl?$
683 or, without specific A value:
684 127.0.0.2 Blacklisted: http://example.com/bl?$
685 Two parts of a line, delimited by second colon, specifies A and TXT
688 record values. Both are optional. By default (either if no default
689 line specified, or no IP address within that line), rbldnsd will return
690 127.0.0.2 as A record. 127.0.0 prefix for A value may be omitted, so
691 the above example may be simplified to:
692 :2:Blacklisted: http://example.com/bl?$
693 There is no default TXT value, so rbldnsd will not return anything for
694 TXT queries it TXT isn't specified.
695 When A value is specified for a given entry, but TXT template is omit‐
697 ted, there may be two cases interpreted differently, namely, whenever
698 there's a second semicolon (:) after the A value. If there's no second
699 semicolon, default TXT value for this scope will be used. In contrast,
700 when second semicolon is present, no TXT template will be generated at
701 all. All possible cases are outlined in the following example:
702 # default A value and TXT template
704 :127.0.0.2:IP address $ is listed
705 # 127.0.0.4 will use default A and TXT
706 127.0.0.4
707 # 127.0.0.5 will use specific A and default TXT
708 127.0.0.5 :5
709 # 127.0.0.6 will use specific a and no TXT
710 127.0.0.6 :6:
711 # 127.0.0.7 will use default A and specific TXT
712 127.0.0.7 IP address $ running an open relay
713 In a TXT template, references to substitution variables are replaced
715 with values of that variables. In particular, single dollar sign ($)
716 is replaced by a listed entry (an IP address in question for IP-based
717 datasets and the domain name for domain-based datasets). $n-style con‐
718 structs, where n is a single digit, are replaced by a substitution
719 variable $n defined for this dataset in current scope (see section
720 "Special Entries" above). To specify a dollar sign as-is, use $$.
721 For example, the following lines:
723 $1 See http://www.example.com/bl
724 $2 for details
725 127.0.0.2 $1/spammer/$ $2
726 127.0.0.3 $1/relay/$ $2
727 127.0.0.4 This spammer wants some $$$$. $1/$
728 will result in the following text to be generated:
729 See http://www.example.com/bl/spammer/127.0.0.2 for details
730 See http://www.example.com/bl/relay/127.0.0.3 for details
731 This spammer wants some $$. See http://www.example.com/bl/127.0.0.4
732 If the "base template" ($= variable) is defined, this template is used
734 for expansion, instead of the one specified for an entry being queried.
735 Inside the base template, $= construct is substituted with the text
736 given for individual entries. In order to stop usage of base template
737 $= for a single record, start it with = (which will be omitted from the
738 resulting TXT value). For example,
739 $0 See http://www.example.com/bl?$= ($) for details
740 127.0.0.2 r123
741 127.0.0.3
742 127.0.0.4 =See other blocklists for details about $
743 produces the following TXT records:
744 See http://www.example.com/bl?r123 (127.0.0.2) for details
745 See http://www.example.com/bl?127.0.0.3 (127.0.0.3) for details
746 See other blocklists for details about 127.0.0.4
747 acl Dataset
750 This is not a real dataset, while the syntax and usage is the same as
751 with other datasets. Instead of defining which records exists in a
752 given zone and which do not, the acl dataset specifies which client
753 hosts (peers) are allowed to query the given zone. The dataset speci‐
754 fies a set of IPv4 and/or IPv6 CIDR ranges (with the syntax exactly the
755 same as understood by the ip4trie and ip6trie datasets), together with
756 action specifiers. When a query is made from an IP address listed (not
757 for the IP address), the specified action changes rules used to con‐
758 struct the reply. Possible actions and their meanings are:
759 :ignore
761 ignore all queries from this IP address altogether. rbldnsd
762 acts like there was no query received at all. This is the
763 default action.
764 :refuse
766 refuse all queries from the IP in question. rbldnsd will always
767 return REFUSED DNS response code.
768 :empty pretend there's no data in all other datasets for the given
770 zone. This means that all the clients in question will always
771 receive reply from rbldnsd telling that the requested IP address
772 or domain name is not listed in a given DNSBL. rbldnsd still
773 replies to metadata queries (SOA and NS records, and to all
774 queries satisfied by generic dataset if specified for the given
775 zone) as usual.
776 :pass process the request as usual. This may be used to add a
778 "whitelisting" entry for a network/host bloked by another
779 (larger) ACL entry.
780 a_txt_template
782 usual A+TXT template as used by other datasets. This means that
783 rbldnsd will reply to any valid DNSBL query with "it is listed"
784 answer, so that the client in question will see every IP address
785 or domain name is listed in a given DNSBL. TXT record used in
786 the reply is taken from the acl dataset instead of real
787 datasets. Again, just like with empty case, rbldnsd will con‐
788 tinue replying to metadata queries (including generic datasets
789 if any) as usual.
790 Only one ACL dataset can be specified for a given zone, and each zone
792 must have at least one non-acl dataset. It is also possible to specify
793 one global ACL dataset, by specifying empty zone name (which is not
794 allowed for other dataset types), like
795 rbldnsd ... :acl:filename...
796 In this case the ACL defined in filename applies to all zones. If
797 there are both global ACL and local zone-specific ACL specified, both
798 will be consulted and actions taken in the order specified above, ie,
799 if either ACL returns ignore for this IP, the request will be ignored,
800 else if either ACL returns refuse, the query will be refused, and so
801 on. If both ACLs specifies "always listed" A+TXT template, the reply
802 will contain A+TXT from global ACL.
803 For this dataset type, only a few $-style specials are recognized. In
805 particular, $SOA and $NS keywords are not allowed. When rbldnsd per‐
806 forms $ substitution in the TXT template returned from ACL dataset, it
807 will use client IP address to substitute for a single $ character,
808 instead of the IP address or domain name found in the original query.
809
812 Rbldnsd handles the following signals:
813 SIGHUP recheck zone files and reload any outdated ones. This is done
816 automatically if enabled, see -c option. Additionally, rbldnsd
817 will reopen logfile upon receiving SIGHUP, if specified (-l
818 option).
819 SIGTERM, SIGINT
822 Terminate process.
823 SIGUSR1
826 Log current statistic counters into syslog. Rbldnsd collects
827 how many packets it handled, how many bytes was received, sent,
828 how many OK requests/replies (and how many answer records) was
829 received/sent, how many NXDOMAIN answers was sent, and how many
830 errors/refusals/etc was sent, in a period of time.
831 SIGUSR2
834 The same as SIGUSR1, but reset all counters and start new sample
835 period.
836
839 Some unsorted usage notes follows.
840 Generating and transferring data files
843 When creating a data file for rbldnsd (and for anything else, it is a
844 general advise), it is a good idea to create the data in temporary file
845 and rename the temp file when all is done. Never try to write to the
846 main file directly, it is possible that at the same time, rbldnsd will
847 try to read it and will get incomplete data as the result. The same
848 applies to copying data using cp(1) utility and similar (including
849 scp(1)), that performs copying over existing data. Even if you're sure
850 noone is reading the data while you're copying or generating it, imag‐
851 ine what will happen if you will not be able to complete the process
852 for whatever reason (interrupt, filesystem full, endless number of
853 other reasons...). In most cases is better to keep older but correct
854 data instead of leaving incomplete/corrupt data in place.
855 Right:
857 scp remote:data target.tmp && mv target.tmp target
858 Wrong:
859 scp remote:data target
860 Right:
861 ./generate.pl > target.tmp && mv target.tmp target
862 Wrong:
863 ./generate.pl > target
864 From this point of view, rsync(1) command seems to be safe, as it
866 always creates temporary file and renames it to the destination only
867 when all is ok (but note the --partial option, which is good for down‐
868 loading something but may be wrong to transfer data files -- usually
869 you don't want partial files to be loaded). In contrast, scp(1) com‐
870 mand is not safe, as it performs direct copying. You may still use
871 scp(1) in a safe manner, as shown in the example above.
872 Also try to eliminate a case when two (or more) processes performs data
875 copying/generation at the same time to the same destination. When your
876 data is generated by a cron job, use file locking (create separate lock
877 file (which should never be removed) and flock/fcntl it in exclusive
878 mode without waiting, exiting if lock fails) before attempting to do
879 other file manipulation.
880 Absolute vs relative domain names
883 All keys specified in dataset files are always relative to the zone
884 base DN. In contrast, all the values (NS and SOA records, MX records
885 in generic dataset) are absolute. This is different from BIND behav‐
886 iour, where trailing dot indicates whenever this is an absolute or rel‐
887 ative DN. Trailing dots in domain names are ignored by rbldnsd.
888 Aggregating datasets
891 Several zones may be served by rbldnsd, every zone may consist of sev‐
892 eral datasets. There are numerous ways to combine several data files
893 into several zones. For example, suppose you have a list of dialup
894 ranges in file named `dialups', and a list of spammer's ip addresses in
895 file named `spammers', and want to serve 3 zones with rbldnsd:
896 dialups.bl.ex.com, spam.bl.ex.com and bl.ex.com which is a combination
897 of the two. There are two ways to do this:
898 rbldnsd options... \
900 dialups.bl.ex.com:ip4set:dialups \
901 spam.bl.ex.com:ip4set:spammers \
902 bl.ex.com:ip4set:dialups,spammers
903 or:
905 rbldnsd options... \
907 dialups.bl.ex.com:ip4set:dialups \
908 spam.bl.ex.com:ip4set:spammers \
909 bl.ex.com:ip4set:dialups \
910 bl.ex.com:ip4set:spammers
911 (note you should specify combined bl.ex.com zone after all its subzones
913 in a command line, or else subzones will not be consulted at all).
914 In the first form, there will be 3 independent data sets, and every
916 record will be stored 2 times in memory, but only one search in inter‐
917 nal data structures will be needed to resolve queries for aggregate
918 bl.ex.com. In second form, there will be only 2 data sets, every
919 record will be stored only once (both datasets will be reused), but 2
920 searches will be performed by rbldnsd to answer queries against aggre‐
921 gate zone (but difference in speed is almost unnoticeable). Note that
922 when aggregating several data files into one dataset, an exclusion
923 entry in one file becomes exclusion entry in the whole dataset (which
924 may be a problem when aggregating dialups, where exclusions are common,
925 with open relays/proxies, where exclusions are rare if at all used).
926 Similar effect may be achieved by using combined dataset type, some‐
928 times more easily. combined dataset results in every nested dataset to
929 be used independantly, like in second form above.
930 combined dataset requires rbldnsd to be the authoritative nameserver
933 for the whole base zone. Most important, one may specify SOA and NS
934 records for the base zone only. So, some DNSBLs which does not use a
935 common subzone for the data, cannot use this dataset. An example being
936 DSBL.org DNSBL, where each of list.dsbl.org, multihop.dsbl.org and
937 unconfirmed.dsbl.org zones are separate, independant zones with differ‐
938 ent set of nameservers. But for DSBL.org, where each dataset is really
939 independant and used only once (there's no (sub)zone that is as a com‐
940 binations of other zones), combined dataset isn't necessary. In con‐
941 trast, SORBS.net zones, where several subzones used and main zone is a
942 combination of several subzones, combined dataset is a way to go.
943 All authoritative nameservers should be set up similarily
946 When you have several nameservers for your zone, set them all in a sim‐
947 ilar way. Namely, if one is set up using combined dataset, all the
948 rest should be too, or else DNS meta-data will be broken. This is
949 because metadata (SOA and NS) records returned by nameservers using
950 combined and other datasets will have different origin. With combined
951 dataset, rbldnsd return NS and SOA records for the base zone, not for
952 any subzone defined inside the dataset. Given the above example with
953 dialups.bl.ex.com, spammers.bl.ex.com and aggregate bl.ex.com zones,
954 and two nameservers, first is set up in any ways described above (using
955 individual datasets for every of the 3 zones), and second is set up for
956 the whole bl.ex.com zone using combined dataset. In this case, for
957 queries against dialups.bl.ex.com, first nameserver will return NS
958 records like
959 dialups.bl.ex.com. IN NS a.ns.ex.com.
960 while second will always use base zone, and NS records will look like
961 bl.ex.com. IN NS a.ns.ex.com.
962 All authoritative nameservers for a zone must have consistent metadata
963 records. The only way to achieve this is to use similar configuration
964 (combined or not) on all nameservers. Have this in mind when using
965 other software for a nameserver.
966 Generic dataset usage
969 generic dataset type is very rudimentary. It's purpose is to comple‐
970 ment all the other type to form complete nameserver that may answer to
971 A, TXT and MX queries. This is useful mostly to define A records for
972 HTTP access (relays.bl.example.com A, www.bl.example.com A just in
973 case), and maybe descriptive texts as a TXT record.
974 Since rbldnsd only searches one, most closely matching (sub)zone for
977 every request, one cannot specify a single e.g. generic dataset in
978 form
979 proxies TXT list of open proxies
980 www.proxies A 127.0.0.8
981 relays TXT list of open relays
982 www.relays A 127.0.0.9
983 for several (sub)zones, each of which are represented as a zone too
984 (either in command line or as combined dataset). Instead, several
985 generic datasets should be specified, separate one for every (sub)zone.
986 If the data for every subzone is the same, the same, single dataset may
987 be used, but it should be specified for every zone it should apply to
988 (see combined dataset usage example above).
989
992 Most of the bugs outlined in this section aren't really bugs, but
993 present due to non-standartized and thus unknown expected behaviour of
994 a nameserver that serves a DNSBL zone. rbldnsd matches BIND runtime
995 behaviour where appropriate, but not always.
996 rbldnsd lowercases some domain names (the ones that are lookup keys,
999 e.g. in `generic' and `dnset' datasets) when loading, to speed up
1000 lookup operations. This isn't a problem in most cases.
1001 There is no TCP mode. If a resource record does not fit in UDP packet
1004 (512 bytes), it will be silently ignored. For most usages, this isn't
1005 a problem, because there should be only a few RRs in an answer, and
1006 because one record is usually sufficient to decide whenever a given
1007 entry is "listed" or not. rbldnsd isn't a full-featured nameserver,
1008 after all.
1009 rbldnsd will not always return a list of nameserver records in the
1012 AUTHORITY section of every positive answer: NS records will be provided
1013 (if given) only if there's a room for them in single UDP packet. If
1014 records does not fit, AUTHORITY section will be empty.
1015 rbldnsd does not allow AXFR operations. For DNSBLs, AXFR is the stupi‐
1018 diest yet common thing to do - use rsync for zone transfers instead.
1019 This isn't a bug in rbldnsd itself, but in common practice of using
1020 AXFR and the like to transfer huge zones in a format which isn't suit‐
1021 able for such a task. Perhaps in the future, if there will be some
1022 real demand, I'll implement AXFR "server" support (so that rbldnsd will
1023 be able to act as master for BIND nameservers, but not as secondary),
1024 but the note remains: use rsync.
1025 rbldnsd truncates all TXT records to be at most 255 bytes. DNS specs
1028 allows longer TXTs, but long TXTs is something that should be avoided
1029 as much as possible - TXT record is used as SMTP rejection string.
1030 Note that DNS UDP packet is limited to 512 bytes. rbldnsd will log a
1031 warning when such truncation occurs.
1032
1035 This manpage corresponds to rbldnsd version 0.998.
1036
1039 The rbldnsd daemon written by Michael Tokarev <mjt+rbldnsd@corpit.ru>,
1040 based on ideas by Dan Bernstein and his djbdns package, with excellent
1041 contributions by Geoffrey T. Dairiki <dairiki@dairiki.org>.
1042
1045 Mostly GPL, with some code licensed under 3-clause BSD license.
1046 Dec 2015 rbldnsd(8)