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
|
.TH dnstap 8
.SH NAME
dnstap \- Capture, display, and relay Dnstap data.
.SH SYNOPSIS
.B dnstap [ -u \fIsocket-path\fB [ -u \fIsocket2-path\fB ... ] ]
.br
.B " [ -l \fIhost:port\fB [ -l \fIhost2:port2\fB ... ] ]"
.br
.B " [ -r \fIfile\fB [ -r \fIfile2\fB ... ] ]"
.br
.B " [ -U \fIsocket-path\fB [ -U \fIsocket2-path\fB ... ] ]"
.br
.B " [ -T \fIhost:port\fB [ -T \fIhost2:port2\fB ... ] ]"
.br
.B " [ -w \fIfile\fB ] [ -q | -y | -j ] [-a]"
.br
.B " [ -t \fItimeout\fB ]"
.br
.SH DESCRIPTION
.B dnstap
reads data in the Dnstap export format from Frame Streams files or
receives data on Frame Streams connections to TCP/IP or unix domain
socket addresses.
.B dnstap
can display this data in a compact text (the default), JSON, or YAML
formats. It can also save data to a file in display or Frame Streams
binary format, or relay the data to other Dnstap processes over unix
domain socket or TCP/IP connections.
.SH OPTIONS
.TP
.B -a
When opening an file (\fB-w\fR) for text format output
(\fB-j\fR, \fB-q\fR, or \fB-y\fR), append to the file rather
truncating.
.B -a
does not apply when writing binary Frame Streams data to a file.
.TP
.B -j
Write data in JSON format. Encapsulated DNS messages are
rendered in text form similar to the output of \fBdig(1)\fR.
At most one text format (\fB-j\fR, \fB-q\fR, or \fB-y\fR) option may be
given.
.TP
.B -l \fIhost:port\fR
Listen for Dnstap data on TCP/IP port \fBport\fR on address \fIhost\fR.
The \fB-l\fR option may be given multiple times to listen on multiple
addresses.
At least one input (\fB-l\fR, \fB-r\fR, or \fB-u\fR) option must be given.
.TP
.B -q
Write or display data in compact (quiet) text format.
At most one text format (\fB-j\fR, \fB-q\fR, or \fB-y\fR) option may be given.
.TP
.B -r \fIfile\fR
Read Dnstap data from the given \fIfile\fR. The \fB-r\fR option
may be given multiple times to read from multiple files.
At least one input (\fB-l\fR, \fB-r\fR, or \fB-u\fR) option must be given.
.TP
.B -T \fIhost:port\fR
Relay Dnstap data over a TCP/IP connection to \fIhost:port\fR.
\fBdnstap\fR will establish or re-establish this connection as needed.
The \fB-T\fR option may be given multiple times to relay Dnstap data
to multiple addresses.
.TP
.B -t \fItimeout\fR
Apply i/o \fItimeout\fR to TCP/IP and unix domain socket
connections. \fItimeout\fR is given as a number followed by a unit
abbreviation (e.g., \fIms\fR for milliseconds, \fIs\fR for seconds,
\fIm\fR for minutes).
.TP
.B -u \fIsocket-path\fR
Listen for Dnstap data on the unix domain socket at
\fIsocket-path\fR. \fBdnstap\fR will remove any file or socket
\fIsocket-path\fR before listening.
The \fB-u\fR option may be given multiple times to listen on multiple
socket paths.
At least one input (\fB-l\fR, \fB-r\fR, or \fB-u\fR) option must be given.
.TP
.B -U \fIsocket-path\fR
Relay Dnstap data over a unix domain socket connection to
\fIsocket-path\fR. \fBdnstap\fR will establish or re-establish this
connection as needed.
The \fB-U\fR option may be given multiple times to relay Dnstap data to
multiple socket paths.
.TP
.B -w \fIfile\fR
Write Dnstap data to \fIfile\fR.
If \fIfile\fR is "-" or no \fB-w\fR, \fB-T\fR, or \fB-U\fR output
options are present, data will be written to standard output in quiet
text format (\fB-q\fR), unless the YAML or JSON format is specified
with the \fB-y\fR or \fB-j\fR options, respectively.
If \fIfile\fR is a filename other than "-", Dnstap data is written to the
named file in Frame Streams binary format by default, unless quiet text,
JSON, or YAML formats are specified.
.B dnstap
will reopen \fIfile\fR on \fBSIGHUP\fR, for file rotation purposes.
.TP
.B -y
Write Dnstap output in YAML format. Encapsulated DNS messages are rendered in text
form similar to the output of \fBdig(1)\fR.
At most one text format (\fB-j\fR, \fB-q\fR, or \fB-y\fR) option may be given.
.SH EXAMPLES
Listen for Dnstap data from a local name server and print quiet text format
to standard output.
.nf
dnstap -u /var/named/dnstap.sock
.fi
Listen for Dnstap data from a local name server, save a local binary copy, and
relay it to a remote host over TCP.
.nf
dnstap -u /usr/local/unbound/dnstap.sock -w dnstap.fstrm \\
-T dns-admin.example.com:5353
.fi
.SH SEE ALSO
.B dig(1)
|
