forked from rspamd/rbldnsd
-
Notifications
You must be signed in to change notification settings - Fork 0
/
rbldnsd.8
1161 lines (1073 loc) · 46.6 KB
/
rbldnsd.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" rbldnsd manpage
.\"
.TH rbldnsd 8 "Dec 2015"
.SH NAME
rbldnsd \- DNS daemon suitable for running DNS\-based blocklists
.SH SYNOPSIS
.B rbldnsd
options
.IR zone : dataset ...
.SH DESCRIPTION
.PP
.B rbldnsd
is a small DNS\-protocol daemon which is designed to handle
queries to DNS\-based IP\-listing or NAME\-listing services.
Such services are a simple way to share/publish a list of
IP addresses or (domain) names which are "listed" for for
some reason, for example in order to be able to refuse a
service to a client which is "listed" in some blocklist.
.PP
.B rbldnsd
is not a general\-purpose nameserver. It will answer to
A and TXT (and SOA and NS if such RRs are specified) queries,
and has limited ability to answer to some other types of queries.
.PP
.B rbldnsd
tries to handle data from two different perspectives: given
a set (or several) of "listed entries" (e.g. IP address ranges
or domain names), it builds and serves a DNS zone. Note the
two are not the same: list of spammer's IPs is NOT a DNS zone,
but may be represented and used as such, provided that some
additional information necessary to build complete DNS zone
(e.g. NS and SOA records, maybe A records necessary for http
to work) is available. In this context, \fBrbldnsd\fR is very
different from other general\-purpose nameservers such as BIND
or NSD: \fBrbldnsd\fR operates with \fIdatasets\fR (sets of
entries \- IP addresses or domain names, logically grouped
together), while other general\-purpose nameservers operates
with zones. The way how \fBrbldnsd\fR operates may be somewhat
confusing to BIND experts.
.PP
For \fBrbldnsd\fR, a building block is a dataset: e.g., set of
insecure/abuseable hosts (IP addresses), set of network ranges
that belongs to various spam operations (IP ranges), domain
names that belong to spammers (RHSBL) and so on. Usually,
different kind of information is placed into separate file,
for easy maintenance. From a number of such datasets, \fBrbldnsd\fR
constructs a number of DNS zones as specified on command line.
A single dataset may be used for several zones, and a single
zone may be constructed from several datasets.
.PP
.B rbldnsd
will answer queries to DNS zones specified on the command
line as a set of zone specifications.
Each zone specification consists of zone basename, dataset type
and a comma\-separated list of files that forms a given dataset:
.IR zone : type : file , file ,...
.PP
Several zones may be specified in command line, so that
.B rbldnsd
will answer queries to any of them. Also, a single zone
may be specified several times with different datasets,
so it is possible to form a zone from a combination
of several different dataset. The same dataset may be
reused for several zones too (and in this case, it will
be read into memory only once).
.PP
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:
.IP
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,
.B rbldnsd
will return A and TXT records specified in data for that IP.
This is a classical IP\-based blocklist.
.IP
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.
.IP
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.
.IP
combined set, different datasets from the list above combined
in the single (set of) source files, for easy maintenance.
.IP
acl, or Access Control List. This is a pseudo dataset, that works
by overweriting query results based on the requestor (peer) IP address.
.SH OPTIONS
.PP
The following options may be specified:
.IP "\fB\-u\fR \fIuser\fR[:\fIgroup\fR]"
\fBrbldnsd\fR will change its userid to the specified \fIuser\fR, which
defaults to \fBrbldns\fR, and \fIgroup\fR, which by default is the
primary group of a \fIuser\fR. \fBrbldnsd\fR will refuse to run as the root
user, since this is insecure.
.IP "\fB\-r\fR \fIrootdir\fR"
\fBrbldnsd\fR will chroot to \fIrootdir\fR if specified. Data files
should be available inside \fIrootdir\fR.
.IP "\fB\-w\fR \fIworkdir\fR"
\fBrbldnsd\fR will change its working directory to \fIworkdir\fR
(after chrooting to \fIrootdir\fR if \fB\-r\fR option is also specified).
May be used to shorten filename paths.
.IP "\fB\-b\fR \fIaddress\fR/\fIport\fR"
This option is \fIrequired\fR. \fBrbldnsd\fR will bind to specified
\fIaddress\fR and \fIport\fR (port defaults to port 53, domain).
Either numeric IP address or a hostname may be specified, and either
port number or service name is accepted.
It is possible to specify several addresses to listen on this way, by
repeating \fB\-b\fR option. Additionally, if there are several addresses
listed for a hostname, \fBrbldnsd\fR will listen on all of them.
Note that \fBrbldnsd\fR will work slightly faster if only one listening
address is specified.
Note the delimiter between host and port is a slash (/), not a colon,
to be able to correctly handle IPv6 addresses.
.IP \fB\-4\fR
Use IPv4 listening socket/transport, do not attempt to use IPv6
(ignored if \fBrbldnsd\fR was built without IPv6 support).
.IP \fB\-6\fR
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).
.IP "\fB\-t\fR \fIdefttl\fR:\fIminttl\fR:\fImaxttl\fR"
Set default reply time\-to\-live (TTL) value to be \fIdefttl\fR,
and set constraints for TTL to \fIminttl\fR and \fImaxttl\fR. Default
applies when there's no TTL defined in a given scope (in data file),
and constraints are applied when such value provided in data.
Any of the values may be omitted, including trailing colon (:) characters,
e.g. "\fB\-t\fR\ 30" set default TTL to be 30 secound, and "\fB\-t\fR\ ::120"
or "\fB\-t\fR\ ::2m" sets maximum allowed TTL to 2 minutes.
All 3 values are in time units, with optional suffix:
\fBs\fR (secounds, default), \fBm\fR (minutes), \fBh\fR (hours),
\fBd\fR (days) or \fBw\fR (weeks). Zero \fIminttl\fR or \fRmaxttl\fR
means no corresponding constraint will be enforced.
Default \fIdefttl\fR is 35m.
.IP "\fB\-c\fR \fIcheck\fR"
Set interval between checking for zone file changes to be \fIcheck\fR,
default is 1m (one minute). \fBrbldnsd\fR will check zone file's last
modification time every so often, and if it detects a change, zone will
be automatically reloaded. Setting this value to 0 disables automatic
zone change detection. This procedure may also be triggered by sending
a SIGHUP signal to \fBrbldnsd\fR (see SIGNALS section below).
.IP \fB\-e\fR
Allow non\-network addresses to be used in CIDR ranges. Normally,
\fBrbldnsd\fR rejects addresses such as 127.2.3.4/24, where prefix
is not within the network mask derived from bit number (in this
case, correct form is 127.2.3.0/24, note the trailing zero in prefix).
This is done in order to catch possible typos in zones (\fBrbldnsd\fR
will warn about a problem and will ignore such entry). This option
disables checking whether the CIDR prefix fits within the network mask.
.IP \fB\-q\fR
Quick and quiet start. Normally,
.B rbldnsd
does socket initialization and zone load in foreground, writing progress
and statistic to standard output, and aborts in case of any errors.
With this flag, nothing will be printed and first zone load will be done
in background (unless \fB\-n\fR option is also given), and zone load
errors will be non\-fatal.
.IP "\fB\-p\fR \fIpidfile\fR"
Write rbldnsd's pid to the specified \fIpidfile\fR, so it will be easily
findable. This file gets written before entering a chroot jail (if specified)
and before changing userid, so it's ok to specify e.g. /var/run/rbldnsd.pid
here.
.IP "\fB\-l\fR \fIlogfile\fR"
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 (\fBrbldnsd\fR will log \fIevery\fR recognized
request if this option is specified). This option is mainly intended for
debugging purposes. Upon receiption of SIGHUP signal, \fBrbldnsd\fR
reopens its logfile. If \fIlogfile\fR prefixed with a plus sign (+),
logging will not be buffered (i.e. each line will be flushed to disk);
by default, logging is buffered to reduce system load. Specify a single
hyphen (\-) as a filename to log to standard output (filedescriptor 1),
either buffered by default, or line-buffered if specified as `+\-'
(standard output will not be "reopened" upon receiving SIGHUP signal,
but will be flushed in case logging is buffered).
.IP "\fB\-s\fR \fIstatsfile\fR"
Specifies a file where \fBrbldnsd\fR will write a line with short statistic
summary of queries made per zone, every check (\fB\-c\fR) interval.
Format of each line is:
.nf
\fItimestamp\fR \fIzone\fR:\fIqtot\fR:\fIqok\fR:\fIqnxd\fR:\fIbin\fR:\fIbout\fR \fIzone\fR:...
.fi
where
\fItimestamp\fR is unix time (secounds since epoch),
\fIzone\fR is the name of the base zone,
\fIqtot\fR is the total number of queries received,
\fIqok\fR \- number of positive replies,
\fIqnxd\fR \- number of NXDOMAIN replies,
\fIbin\fR is the total number of bytes read from network
(excluding IP/UDP overhead and dropped packets),
\fIbout\fR is the total number of bytes written to network.
Ther are as many such tuples as there are zones, and one extra, total
typle at the end, with \fIzone\fR being "*", like:
.nf
1234 bl1.ex:10:5:4:311:432 bl2.ex:24:13:7:248:375 *:98:35:12:820:987
.fi
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.
\fBRbldnsd\fR will write bare timestamp to \fIstatsfile\fR when it
is starting up, shutting down or when statistic counters are being
reset after receiving SIGUSR2 signal (see below), to indicate the
points where the counters are starting back from zero.
By default, \fBrbldnsd\fR writes absolute counter values into
\fIstatsfile\fR (number of packets (bytes) since startup or
last reset). \fIstatsfile\fR may be prefixed with plus sign (+),
in which case \fBrbldnsd\fR will write delta values, that is,
number of packets or bytes since last write, or number of
packets (bytes) per unit of time ("incremental" mode, hence
the "+" sign).
.IP \fB\-n\fR
Do not become a daemon. Normally, \fBrbldnsd\fR will fork and go to the
background after successful initialization. This option disables this
behaviour.
.IP \fB\-f\fR
Request \fBrbldnsd\fR to continue processing requests during data reloads.
\fBRbldnsd\fR forks a child process to handle requests while parent
reloads the data. This ensures smooth operations, but requires
more memory, since two copies of data is keept in memory during
reload process.
.IP \fB\-d\fR
Dump all zones to stdout in BIND format and exit. This may be suitable
to convert easily editable rbldnsd-style data into BIND zone. \fBrbldnsd\fR
dumps all zones as one stream, so one may want to specify only one zone
with \fB\-d\fR. Zone file will have appropriate $ORIGIN tags. Note
that data generated may be really huge (as BIND format isn't appropriate
for this sort of things), and some entries may not be really the same
in BIND as in \fBrbldnsd\fR (e.g., IP netblocks of large size will be
represented as wildcard entries \- 10.0.0.0/8 will become *.10; excluded
entries will be represented by a CNAME to `excluded' name, so such name
should not be present in a data set). In this mode, \fBrbldnsd\fR ignores
\fB\-r\fR (root directory) option.
.IP \fB\-v\fR
Do not show exact version information in response to version.bind CH TXT
queries (by default \fBrbldnsd\fR responds to such queries since version
0.98). With single \fB\-v\fR, \fBrbldnsd\fR will only return "rbldnsd"
to the caller, without the version number. Second \fB\-v\fR disables
providing any information in response to such requests, i.e. \fBrbldnsd\fR
will return REFUSE code.
.IP \fB\-C\fR
Disable automatic on\-the\-fly uncompression of data files if this feature
is compiled in (see below).
.IP \fB\-A\fR
.IP \fB\-a\fR
Controls "laziness" of \fBrbldnsd\fR when constructing replies.
With \fB\-a\fR specified, \fBrbldnsd\fR does not add AUTH section
(containing NS records) to replies unless explicitly asked for NS
records. It is equivalent to BIND9 "minimal\-answers" configuration
setting. While with \fB\-A\fR specified, \fBrbldnsd\fR will always
fill in AUTH section, increasing size of replies dramatically but
allowing (caching) resolver clients to react faster to changes in
nameserver lists. Currently (as of 0.998 version), non\-lazy
(as with \fB\-A\fR) mode is the default, but it will change in
future release.
.IP "\fB\-x\fR \fIextension\fR"
Load the given \fIextension\fR file (a dynamically-linked library, usually
with ".so" suffix). This allows to gather custom statistics or perform other
custom tasks. See separate document for details about building and using
extensions. This feature is not available on all platforms, and can be
disabled at compile time.
.IP "\fB\-X\fR \fIextarg\fR"
Pass the given argument, \fIextarg\fR, to the extension loaded with \fB\-x\fR.
.SH "DATASET TYPES AND FORMATS"
.PP
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".
.PP
A (comma\-separated) list of files in dataset specification
(in \fItype\fR:\fIfile\fR,\fIfile\fR,...) is interpreted as if
all files where logically combined into one single file.
.PP
When compiled with zlib support,
.B rbldnsd
is able to read gzip\-compressed data files. So, every \fIfile\fR in
dataset specification can be compressed with \fBgzip\fR(1), and
.B rbldnsd
will read such a file decompressing it on\-the\-fly. This feature
may be turned off by specifying \fB\-C\fR option.
.PP
.B rbldnsd
is designed to service a DNSBL, where each entry have single
A record and optional TXT record assotiated with it.
.B rbldnsd
allows to specify A value and TXT \fItemplate\fR either for each
entry individually, or to use default A value and TXT template
pair for a group of entries. See section "Resulting A values
and TXT templates" below for a way to specify them.
.SS "Special Entries"
.PP
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 \fBrbldnsd\fR and
for DJB's rbldns). The following keywords, following a dollar sign,
are recognized:
.IP "\fB$SOA\fR \fIttl 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, \fBrbldnsd\fR 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 \fIfirst\fR 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 \fIprepending\fR
small local file to the dataset in question, listing it before any other
files.
.IP
If \fIserial\fR value specified is zero, timestamp of most recent
modified file will be substituted as \fIserial\fR.
.IP
If \fIttl\fR field is zero, default ttl (\fB\-t\fR option or last \fB$TTL\fR
value, see below) will be used.
.IP
All time fields (ttl, refresh, retry, expire, minttl) may be specified
in time units. See \fB\-t\fR option for details.
.IP "\fB$NS\fR \fIttl\fR \fInameserverdn\fR \fInameserverdn\fI..."
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 \fBrbldnsd\fR. This
is useful to temporary comment out one nameserver entry without removing
it from the list. If \fIttl\fR is zero, default ttl will be used.
The list of NS records, just like $SOA value, are taken from the \fIfirst\fR
data file in a dataset where the $NS line is found, subsequent $NS lines,
if any, are ignored.
.IP "\fB$TTL\fR \fItime-to-live\fR"
Specifies TTL (time-to-live) value for all records in current dataset.
See also \fB\-t\fR option. \fB$TTL\fR special overrides \fB\-t\fR value
on a per-dataset basis.
.IP "\fB$TIMESTAMP\fR \fIdstamp\fR [\fIexpires\fR]"
(experimental)
Specifies the data timestamp \fIdstamp\fR when the data has been generated,
and optionally when it will expire. The timestamps are in form
\fIyyyy\fR:\fImm\fR:\fIdd\fR[:\fIhh\fR[:\fImi\fR[:\fIss\fR]]], where
\fIyyyy\fR is the year like 2005, \fImm\fR is the month number (01..12),
\fIdd\fR is the month day number (01..31), \fIhh\fR is hour (00..23),
\fImi\fR and \fIss\fR 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 \fIdstamp\fR and/or
\fIexpires\fR, indicating the value is not given. \fIexpires\fR may also
be specified as \fB+\fIrel\fR, where \fIrel\fR is a time specification
(probably with suffix like s, m, h, d) as an offset to \fIdstamp\fR.
.B rbldnsd
compares \fIdstamp\fR with current timestamp and refuses to load the file
if \fIdstamp\fR specifies time in the future. And if \fIexpires\fR is
specified,
.B rbldnsd
will refuse to service requests for that data if current time is greather
than the value specified in \fIexpires\fR field.
.IP
Note that
.B rbldnsd
will check the data expiry time every time it checks for data file
updates (when receiving SIGHUP signal or every \fB\-c\fR interval).
If automatic data reload timer (\fB\-c\fR option) is disabled,
zones will not be exipired automatically.
.IP "\fB$MAXRANGE4\fR \fIrange-size\fR"
Specifies maximum size of IPv4 range allowed for IPv4\-based datasets.
If an entry covers more IP addresses than \fIrange-size\fR, it will
be ignored (and a warning will be logged). \fIrange-size\fR may be
specified as a number of hosts, like 256, or as network prefix lenght,
like /24 (the two are the same):
.nf
$MAXRANGE4 /24
$MAXRANGE4 256
.fi
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.
.IP "\fB$\fIn\fR \fItext\fR"
(\fIn\fR is a single digit).
Specifies a \fIsubstitution variable\fR for use as $\fIn\fR placeholders
(the \fB$\fIn\fR entries are ignored in generic daaset).
See section "Resulting A values and TXT templates" below for description
and usage examples.
.IP "\fB$=\fR \fItext\fR"
Set the base template for all individual TXT records. See section
"Resulting A values and TXT templates" below for more information.
.SS "ip4set Dataset"
.PP
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:
.nf
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
.fi
to specify 127.16.0.0\-127.31.255.255:
.nf
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
.fi
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 \fIspecified\fR octet of the first boundary
prefix (127.16.0\-31 is treated as 127.16.0.0\-127.16.31.255, i.e.
127.16.0.0/19).
.PP
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.
.PP
IP address range may be followed by a comment char (either hash character (#)
or semicolon (;)), e.g.:
.nf
127/8 ; loopback network
.fi
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.
.PP
Every IP address that fits within any of specified ranges is "listed", and
.B 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
.I 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.
.PP
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, \fBrbldnsd\fR 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.
.SS "ip4trie Dataset"
.PP
Set of IP4 CIDR ranges with corresponding (A, TXT) values. This
dataset is similar to ip4set, but uses a different internal
representation. It accepts CIDR ranges only (not a.b.c.d\-e.f.g.h),
and allows for the specification of A/TXT values on a per CIDR range
basis. (If multiple CIDR ranges match a query, the value for longest
matching prefix is returned.) Exclusions are supported too.
.PP
This dataset is not particularly memory-efficient for storing many
single IP addresses \(em 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.)
.SS "ip4tset Dataset"
.PP
"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 \fBip4set\fR.
.SS "ip6trie Dataset"
.PP
Set of IP6 CIDR ranges.
This is the IP6 equivalent of the ip4trie dataset.
It allows the sepecification of individual A/TXT values for each CIDR range
and supports exclusions. Compressed ("::") ip6 notation is supported.
.PP
Example zone data:
.nf
# 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
.fi
.SS "ip6tset Dataset"
.PP
"Trivial" ip6 dataset: a set of /64 IP6 CIDR ranges (one per line),
all sharing a single A+TXT template.
Exclusions of single IP6 (/128) addresses are also supported.
This dataset type is quite memory-efficient \(em it uses about 40%
of the memory that the ip6trie dataset would use \(em but has obvious
limitations.
.PP
This dataset wants the /64s listed as four ip6 words, for example:
.nf
2001:20fe:23:41ed
abac:adab:ad00:42f
.fi
Exclusions are denoted with a leading exclamation mark.
You may also use compressed "::" notation for excluded addresses.
E.g.:
.nf
!abac:adab:ad00:42f:face:0f:a:beef
!abac:adab:ad00:42f::2
.fi
.SS "dnset Dataset"
.PP
Set of (possible wildcarded) domain names with associated A and TXT values.
Similar to \fBip4set\fR, but instead of IP addresses, data consists of
domain names (\fInot\fR in reverse form). One domain name per line,
possible starting with wildcard (either with star\-dot (*.) or just a dot).
Entry starting with exclamation sign is exclusion. Default value for
all subsequent lines may be specified by a line starting with a colon.
.PP
Wildcards are interpreted as follows:
.IP example.com
only example.com domain is listed, not subdomains thereof. Not a wildcard
entry.
.IP *.example.com
all subdomains of example.com are listed, but not example.com itself.
.IP .example.com
all subdomains of example.com \fIand\fR 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).
.PP
This dataset type may be used instead of \fBip4set\fR,
provided all CIDR ranges are expanded and reversed (but in
this case, TXT template will be expanded differently).
.SS "generic Dataset"
.PP
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:
.IP
.nf
# 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"
.fi
.SS "combined Dataset"
.PP
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
.nf
$DATASET \fItype\fR[:\fIname\fR] \fIsubzone\fR \fIsubzone\fR...
.fi
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 \fItype\fR,
with optional \fIname\fR (name is used for logging purposes only,
and the whole ":\fIname\fR" (without quotes or square brackets)
part is optional). Note that combined datasets cannot be nested.
Every \fIsubzone\fR will always be relative to the base zone name
specified on command line. If \fIsubzone\fR specified as single
character "@", dataset will be connected to the base zone itself.
.PP
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.
.PP
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:
.nf
# 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
.fi
.PP
Note that $NS and $SOA values applies to the base zone \fIonly\fR,
regardless of the placement in the file. Unlike the $TTL values and
$\fIn\fR substitutions, which may be both global and local for a
given (sub\-)dataset.
.SS "Resulting A values and TXT templates"
.PP
In all zone file types except generic, A values and TXT templates are
specified as following:
.nf
:127.0.0.2:Blacklisted: http://example.com/bl?$
.fi
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:
.nf
127.0.0.2 :127.0.0.2:Blacklisted: http://example.com/bl?$
.fi
or, without specific A value:
.nf
127.0.0.2 Blacklisted: http://example.com/bl?$
.fi
.PP
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), \fBrbldnsd\fR 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:
.nf
:2:Blacklisted: http://example.com/bl?$
.fi
There is no default TXT value, so
.B rbldnsd
will not return anything for TXT queries unless TXT isn't
specified.
.PP
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:
.PP
.nf
# 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 \fIno\fR 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
.fi
.PP
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). \fB$\fIn\fR\-style constructs, where \fIn\fR is a single
digit, are replaced by a substitution variable $\fIn\fR defined for
this dataset in current scope (see section "Special Entries" above).
To specify a dollar sign as\-is, use \fB$$\fR.
.PP
For example, the following lines:
.nf
$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/$
.fi
will result in the following text to be generated:
.nf
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
.fi
.PP
If the "base template" (\fB$=\fR variable) is defined, this template is used
for expansion, instead of the one specified for an entry being queried.
Inside the base template, \fB$=\fR construct is substituted with the
text given for individual entries. In order to stop usage of base template
\fB$=\fR for a single record, start it with \fB=\fR (which will be omitted
from the resulting TXT value). For example,
.nf
$= 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 $
.fi
produces the following TXT records:
.nf
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
.fi
.SS "acl Dataset"
.PP
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 do not, the
.B acl
dataset specifies which client hosts (peers) are allowed to query the
given zone. The dataset specifies a set of IPv4 and/or IPv6 CIDR ranges
(with the syntax exactly the same as understood by the
.B ip4trie
and
.B ip6trie
datasets), together with action specifiers. When a query is made from
an IP address listed (not
.I for
the IP address), the specified action changes rules used to construct the
reply. Possible actions and their meanings are:
.IP :\fBignore\fR
ignore all queries from this IP address altogether.
.B rbldnsd
acts like there was no query received at all.
This is the default action.
.IP :\fBrefuse\fR
refuse all queries from the IP in question.
.B rbldnsd
will always return REFUSED DNS response code.
.IP :\fBempty\fR
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
.B rbldnsd
telling that the requested IP address or domain name is not listed in
a given DNSBL.
.B 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.
.IP :\fBpass\fR
process the request as usual. This may be used to add a "whitelisting"
entry for a network/host bloked by another (larger) ACL entry.
.IP \fIa_txt_template\fR
usual A+TXT template as used by other datasets. This means that
.B 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 \fBempty\fR case, \fBrbldnsd\fR will continue
replying to metadata queries (including generic datasets if any) as
usual.
.PP
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
.br
.nf
\fBrbldnsd\fR ... :\fBacl\fR:\fIfilename\fR...
.fi
.br
In this case the ACL defined in \fIfilename\fR applies to all zones.
If there are both global ACL and local zone-specific ACL specified,
both will be consulted and actions taken in the order specified above,
ie, if either ACL returns \fBignore\fR for this IP, the request will
be ignored, else if either ACL returns \fBrefuse\fR, the query will
be refused, and so on. If both ACLs specifies "always listed" A+TXT
template, the reply will contain A+TXT from global ACL.
.PP
For this dataset type, only a few $-style specials are recognized.
In particular, $SOA and $NS keywords are not allowed.
When
.B rbldnsd
performs \fB$\fR 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.
.SH SIGNALS
.B Rbldnsd
handles the following signals:
.IP \fBSIGHUP\fR
recheck zone files and reload any outdated ones. This is done
automatically if enabled, see \fB\-c\fR option. Additionally,
.B rbldnsd
will reopen logfile upon receiving SIGHUP, if specified
(\fB\-l\fR option).
.IP "\fBSIGTERM\fR, \fBSIGINT\fR"
Terminate process.
.IP \fBSIGUSR1\fR
Log current statistic counters into syslog.
.B Rbldnsd
collects how many packets it handled, how many bytes was received,
sent, how many OK requests/replies (and how many answer records)
was received/sent, how many NXDOMAIN answers was sent, and how
many errors/refusals/etc was sent, in a period of time.
.IP \fBSIGUSR2\fR
The same as SIGUSR1, but reset all counters and start new sample
period.
.SH NOTES
.PP
Some unsorted usage notes follows.
.SS "Generating and transferring data files"
.PP
When creating a data file for \fBrbldnsd\fR (and for anything
else, it is a general advise), it is a good idea to create the
data in temporary file and rename the temp file when all is
done. \fINever\fR try to write to the main file directly,
it is possible that at the same time, \fBrbldnsd\fR will try
to read it and will get incomplete data as the result. The
same applies to copying data using \fBcp\fR(1) utility and
similar (including \fBscp\fR(1)), that performs copying over
existing data. Even if you're sure noone is reading the data
while you're copying or generating it, imagine what will happen
if you will not be able to complete the process for whatever
reason (interrupt, filesystem full, endless number of other
reasons...). In most cases is better to keep older but correct
data instead of leaving incomplete/corrupt data in place.
.PP
Right:
.nf
scp remote:data target.tmp && mv target.tmp target
.fi
\fIWrong\fR:
.nf
scp remote:data target
.fi
Right:
.nf
./generate.pl > target.tmp && mv target.tmp target
.fi
\fIWrong\fR:
.nf
./generate.pl > target
.fi
.PP
From this point of view, \fBrsync\fR(1) command seems
to be safe, as it \fIalways\fR 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, \fBscp\fR(1) command is
\fInot\fR safe, as it performs direct copying. You
may still use \fBscp\fR(1) in a safe manner, as shown
in the example above.
.PP
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.
.SS "Absolute vs relative domain names"
.PP
All \fIkeys\fR specified in dataset files are always relative
to the zone base DN. In contrast, all the \fIvalues\fR (NS
and SOA records, MX records in generic dataset) are absolute.
This is different from BIND behaviour, where trailing dot
indicates whenever this is an absolute or relative DN.
Trailing dots in domain names are ignored by \fBrbldnsd\fR.
.SS "Aggregating datasets"
.PP
Several zones may be served by \fBrbldnsd\fR,
every zone may consist of several datasets. There are numerous
ways to combine several data files into several zones. For
example, suppose you have a list of dialup ranges in file
named `dialups', and a list of spammer's ip addresses in file
named `spammers', and want to serve 3 zones with \fBrbldnsd\fR:
dialups.bl.ex.com, spam.bl.ex.com and bl.ex.com which is a
combination of the two. There are two ways to do this:
.PP
.nf
rbldnsd \fIoptions...\fR \\
dialups.bl.ex.com:ip4set:dialups \\
spam.bl.ex.com:ip4set:spammers \\
bl.ex.com:ip4set:dialups,spammers
.fi
.PP
or:
.PP
.nf
rbldnsd \fIoptions...\fR \\
dialups.bl.ex.com:ip4set:dialups \\
spam.bl.ex.com:ip4set:spammers \\
bl.ex.com:ip4set:dialups \\
bl.ex.com:ip4set:spammers
.fi
.PP
(note you should specify combined bl.ex.com zone
.I after
all its subzones in a command line, or else subzones
will not be consulted at all).