-
Notifications
You must be signed in to change notification settings - Fork 1
/
dnstap-sensor.8
244 lines (194 loc) · 6.16 KB
/
dnstap-sensor.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
.TH dnstap-sensor 8
.SH NAME
dnstap-sensor \- Convert dnstap data to NMSG for UDP output or SIE upload
.SH SYNOPSIS
.B dnstap-sensor --apikey (\fIkey\fB|\fIkeyfile-path\fB)
.br
.B " --channel \fInumber\fB --input \fIsocket-path\fB [--trace]"
.br
.B " [--filter_qname \fIdomain\fR ... ]"
.br
.B " [--stats_interval \fIduration\fB] [--heartbeat \fIduration\fB]"
.br
.B " [--retry \fIduration\fB] [--flush \fIduration\fB]"
.br
.B " \fIserver-uri\fB [ \fIserver-uri ...\fB ]"
.B dnstap-sensor --input \fIsocket-path\fB [--trace]
.br
.B " --udp_output udp:\fIaddr\fB:\fIport\fB [-mtu \fIsize\fB]"
.br
.B " [--filter_qname \fIdomain\fR ... ]"
.br
.B " [--stats_interval \fIduration\fB]"
.br
.B " [--flush \fIduration\fB]"
.B dnstap-sensor --config \fI/path/to/conffile\fB
.SH DESCRIPTION
.B dnstap-sensor
collects Dnstap data from a socket, encapsulates
it in NMSG messages, and uploads the data over one or more persistent
HTTP connections for distribution on the Farsight SIE.
Only Dnstap messages of type RESOLVER_RESPONSE are uploaded, so that
.B dnstap-sensor
can coexist with other Dnstap applications.
.SH OPTIONS
.TP
.B --apikey (\fIkey\fB|\fIkeyfile-path\fB)
Specify the API key for authentication to the server. The key
may be provided in the argument, or a path to a file containing the key
to keep the key out of
.I ps
output.
The API key must be provided either through the command line
option or the optional configuration file if any upload
\fIserver-uri\fRs are configured.
.TP
.B --input \fIsocket-path\fB
Collect dnstap input from the UNIX domain socket at \fIsocket-path\fR.
\fBdnstap-sensor\fR will create this socket and accept connections
from the DNS server. Note that this requires \fBdnstap-sensor\fR be
invoked as the same user as the DNS server.
An input must be specified on the command line or in the optional
configuration file.
.TP
.B --channel \fIchannel-number\fB
Address the Dnstap data to SIE channel \fIchannel-number\fR.
The channel number must be specified on the command line or in the
optional config file if any upload \fIserver-uri\fRs are configured.
.TP
.B --filter_qname \fIdomain\fB
Filter out responses to queries under \fIdomain\fR in addition to non
RESOLVER_RESPONSE messages. Multiple \fB--filter_qname\fR options
may be used to filter out responses to queries in multiple domains.
.TP
.B --flush \fIduration\fB
Buffer the Dnstap data for at most \fIduration\fR. The duration
argument format is a number followed by a unit, e.g. "300ms",
"1.5s". The default value is "500ms".
.TP
.B --heartbeat \fIduration\fB
Send heartbeat messages every \fIduration\fR. The HTTP/websocket
protocol used by \fBdnstap-sensor\fR sends periodic heartbeats
to keep the connection alive and detect node and network failures.
The duration argument specifies how frequently to send these
messages. The default value is "30s".
.TP
.B --retry \fIduration\fB
Retry a failed connection after \fIduration\fR. The default value is "30s".
.TP
.B --stats_interval \fIduration\fB
Log statistics every \fIduration\fR. The default value is "15m". A value
of "0" turns off statistics logging.
.TP
.B --trace
Output additional logging to standard error for debugging.
.TP
.B --udp_output udp:\fIaddress\fB:\fIport\fB
Send output NMSG data via UDP to \fIaddress\fR:\fIport\fR. The prefix \fBudp\fR
may be replaced with \fBudp4\fR or \fBudp6\fR to force IPv4 or IPv6 transport.
A \fB--udp_output\fR may be specified instead of or in addition to server URIs.
If both are specified, data will be sent to both the UDP output and one of the
configured server URIs.
.Tp
.B --mtu \fIsize\fB
Specify the buffer size to use when sending NMSG data to \fB--udp_output\fR.
In practice, this number should be lower than the actual interface MTU. The
default value is 1280 for transport over Ethernet with a 1500 byte MTU.
.TP
.B --config \fIfile\fB
Load configuration from \fIfile\fR.
See section \fBCONFIGURATION FILE\fR for details.
.SH SERVER URI
The \fIserver-uri\fR arguments to \fBdnstap-sensor\fR must have
a web sockets or secure websockets (\fBws://\fR or \fBwss://\fR)
scheme. The URI path may be left blank, or \fBdnstap-sensor\fR may
associate an alternate name for its session with a path of
\fB/session/\fIsession-name\fR. The default \fIsession-name\fR
is "dnstap-sensor-upload".
.SH CONFIGURATION FILE
.B dnstap-sensor
may load configuration from a file specified by the
.B --config
option. This file is in YAML format, and supports the
following top-level keys:
.TP
.B api_key
Corresponds to the
.B --apikey
command line option.
.TP
.B dnstap_input
Corresponds to the
.B --input
command line option.
.TP
.B channel
Corresponds to the
.B --channel
command line option.
.TP
.B filter_qnames
Corresponds to the
.B --filter_qname
command line option, a YAML-format list of one or more \fIdomain\fR
names.
.TP
.B flush
Corresponds to the
.B --flush
command line option.
.TP
.B heartbeat
Corresponds to the
.B --heartbeat
command line option.
.TP
.B retry
Corresponds to the
.B --retry
command line option.
.TP
.B stats_interval
Corresponds to the
.B --stats_interval
command line option.
.TP
.B servers
A YAML-format list of one or more \fIserver-uri\fRs.
.TP
.B udp_output
Corresponds to the
.B --udp_output
command line option
.P
Values specified with command line options override any corresponding
values loaded from the configuration file.
.SH EXAMPLES
Read from unbound, publish to channel 203, using command line options:
.nf
% dnstap-sensor --channel 203 --input /var/unbound/dnstap.sock \\
--apikey 2415cd1c-77ae-4538-9dd6-3ba2b8f8ea0a \\
wss://submit.sie-network.net/
.fi
Same as above, using config file, apikey file:
.nf
% cat /etc/dnstap-sensor/apikey
2415cd1c-77ae-4538-9dd6-3ba2b8f8ea0a
% cat /etc/dnstap-sensor/dnstap-sensor.conf
api_key: /etc/dnstap-sensor/apikey
channel: 203
dnstap_input: /var/unbound/dnstap.sock
servers:
- wss://submit.sie-network.net/
% dnstap-sensor -config /etc/dnstap-sensor/dnstap-sensor.conf
.fi
The following is a configuration example of sending to UDP via IPv6 at
port 9999 while excluding some domains:
.nf
dnstap_input: /var/run/dnstap.sock
udp_output: udp:[2001:0db8:1234:5678:90ab:cdef:1234:5678]:9999
filter_qnames:
- host.example
- foo.invalid
- abcd.example.net
.fi