summaryrefslogtreecommitdiffstats
path: root/dnsdist.1
blob: 71c1400eab478ef1e0d3f2dc69efb847d297c63e (plain)
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
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "DNSDIST" "1" "May 13, 2024" "" "dnsdist"
.SH NAME
dnsdist \- A DNS and DoS aware, scriptable loadbalancer
.SH SYNOPSIS
.sp
dnsdist [<option>...] [address]...
.SH DESCRIPTION
.sp
\fBdnsdist\fP receives DNS queries and relays them to one or more
downstream servers. It subsequently sends back responses to the original
requestor.
.sp
\fBdnsdist\fP operates over TCP and UDP, and strives to deliver very high
performance over both.
.sp
Currently, queries are sent to the downstream server with the least
outstanding queries. This effectively implies load balancing, making
sure that slower servers get less queries.
.sp
If a reply has not come in after a few seconds, it is removed from the
queue, but in the short term, timeouts do cause a server to get less
traffic.
.sp
IPv4 and IPv6 operation can be mixed and matched, in other words,
queries coming in over IPv6 could be forwarded to IPv4 and vice versa.
.sp
\fBdnsdist\fP is scriptable in Lua, see the dnsdist documentation for more
information on this.
.SH SCOPE
.sp
\fBdnsdist\fP does not \(aqthink\(aq about DNS queries, it restricts itself to
measuring response times and error codes and routing questions
accordingly. It comes with a very high performance packet\-cache.
.sp
The goal for dnsdist is to remain simple. If more powerful loadbalancing
is required, dedicated hardware or software is recommended. Linux
Virtual Server for example is often mentioned.
.SH OPTIONS
.INDENT 0.0
.TP
.BI \-a \ <netmask>\fR,\fB \ \-\-acl \ <netmask>
Add \fInetmask\fP to the ACL.
.TP
.BI \-C \ <file>\fR,\fB \ \-\-config \ <file>
Load configuration from \fIfile\fP\&.
.TP
.B  \-\-check\-config
Test the configuration file (which may be set with \fB\-\-config\fP or \fB\-C\fP)
for errors. dnsdist will show the errors and exit with a non\-zero
exit\-code when errors are found.
.TP
.BI \-c \ <address>\fR,\fB \ \-\-client \ <address>
Operate as a client, connect to dnsdist. This will read the dnsdist
configuration for the \fBcontrolSocket\fP statement and connect to it.
When \fIaddress\fP (with an optional port number) is set, dnsdist will connect
to that instead.
.TP
.BI \-k \ <key>\fR,\fB \ \-\-setkey \ <key>
When operating as a client(\fB\-c\fP, \fB\-\-client\fP), use \fIkey\fP as
shared secret to connect to dnsdist. This should be the same key
that is used on the server (set with \fBsetKey()\fP). Note that this
will leak the key into your shell\(aqs history and into the systems
running process list. Only available when dnsdist is compiled with
libsodium or libcrypto support.
.TP
.BI \-e\fP,\fB  \-\-execute \ <command>
Connect to dnsdist and execute \fIcommand\fP\&.
.TP
.B  \-h\fP,\fB  \-\-help
Display a helpful message and exit.
.TP
.BI \-l\fP,\fB  \-\-local \ <address>
Bind to \fIaddress\fP, Supply as many addresses (using multiple
\fB\-\-local\fP statements) to listen on as required. Specify IPv4 as
0.0.0.0:53 and IPv6 as [::]:53.
.TP
.B  \-\-supervised
Run in foreground, but do not spawn a console. Use this switch to
run dnsdist inside a supervisor (use with e.g. systemd and
daemontools).
.TP
.B  \-\-disable\-syslog
Disable logging to syslog. Use this when running inside a supervisor
that handles logging (like systemd).
.TP
.B  \-\-log\-timestamps
Prepend timestamps to messages logged to standard out.
.TP
.BI \-u\fP,\fB  \-\-uid \ <uid>
Change the process user to \fIuid\fP after binding sockets. \fIuid\fP can be
a name or number.
.TP
.BI \-g\fP,\fB  \-\-gid \ <gid>
Change the process group to \fIgid\fP after binding sockets. \fIgid\fP Can
be a name or number.
.TP
.B  \-V\fP,\fB  \-\-version
Show the dnsdist version and exit.
.TP
.B  \-v\fP,\fB  \-\-verbose
Be verbose.
.UNINDENT
.sp
\fBaddress\fP are any number of downstream DNS servers, in the same syntax as used
with \fB\-\-local\fP\&. If the port is not specified, 53 is used.
.SH BUGS
.sp
Right now, the TCP support has some rather arbitrary limits.
.SH RESOURCES
.sp
Website: \fI\%https://dnsdist.org\fP
.SH AUTHOR
PowerDNS.COM BV and its contributors
.SH COPYRIGHT
PowerDNS.COM BV and its contributors
.\" Generated by docutils manpage writer.
.