lwresd.8 7.17 KB
Newer Older
Tinderbox User's avatar
Tinderbox User committed
1
.\" Copyright (C) 2004, 2005, 2007-2009, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
regen  
Mark Andrews committed
2
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
Rob Austein's avatar
regen  
Rob Austein committed
3
.\" 
Automatic Updater's avatar
regen  
Automatic Updater committed
4
.\" Permission to use, copy, modify, and/or distribute this software for any
5 6
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
Rob Austein's avatar
regen  
Rob Austein committed
7
.\" 
Mark Andrews's avatar
Mark Andrews committed
8 9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
Rob Austein's avatar
regen  
Rob Austein committed
10
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
Mark Andrews's avatar
Mark Andrews committed
11 12 13 14
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
Rob Austein's avatar
regen  
Rob Austein committed
15
.\"
Rob Austein's avatar
regen  
Rob Austein committed
16 17
.hy 0
.ad l
Tinderbox User's avatar
Tinderbox User committed
18
'\" t
Mark Andrews's avatar
regen  
Mark Andrews committed
19 20
.\"     Title: lwresd
.\"    Author: 
Tinderbox User's avatar
Tinderbox User committed
21
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
Tinderbox User's avatar
Tinderbox User committed
22
.\"      Date: 2009-01-20
Mark Andrews's avatar
regen  
Mark Andrews committed
23
.\"    Manual: BIND9
Tinderbox User's avatar
Tinderbox User committed
24 25
.\"    Source: ISC
.\"  Language: English
Mark Andrews's avatar
regen  
Mark Andrews committed
26
.\"
Tinderbox User's avatar
Tinderbox User committed
27 28 29 30 31 32 33 34 35 36 37 38 39
.TH "LWRESD" "8" "2009\-01\-20" "ISC" "BIND9"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
Mark Andrews's avatar
regen  
Mark Andrews committed
40 41 42 43
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
Tinderbox User's avatar
Tinderbox User committed
44 45 46
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
Mark Andrews's avatar
regen  
Mark Andrews committed
47
.SH "NAME"
Bob Halley's avatar
Bob Halley committed
48
lwresd \- lightweight resolver daemon
Rob Austein's avatar
regen  
Rob Austein committed
49
.SH "SYNOPSIS"
Tinderbox User's avatar
Tinderbox User committed
50
.HP \w'\fBlwresd\fR\ 'u
Mark Andrews's avatar
regen  
Mark Andrews committed
51
\fBlwresd\fR [\fB\-c\ \fR\fB\fIconfig\-file\fR\fR] [\fB\-C\ \fR\fB\fIconfig\-file\fR\fR] [\fB\-d\ \fR\fB\fIdebug\-level\fR\fR] [\fB\-f\fR] [\fB\-g\fR] [\fB\-i\ \fR\fB\fIpid\-file\fR\fR] [\fB\-m\ \fR\fB\fIflag\fR\fR] [\fB\-n\ \fR\fB\fI#cpus\fR\fR] [\fB\-P\ \fR\fB\fIport\fR\fR] [\fB\-p\ \fR\fB\fIport\fR\fR] [\fB\-s\fR] [\fB\-t\ \fR\fB\fIdirectory\fR\fR] [\fB\-u\ \fR\fB\fIuser\fR\fR] [\fB\-v\fR] [\fB\-4\fR] [\fB\-6\fR]
Bob Halley's avatar
Bob Halley committed
52 53
.SH "DESCRIPTION"
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
54
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
55
is the daemon providing name lookup services to clients that use the BIND 9 lightweight resolver library\&. It is essentially a stripped\-down, caching\-only name server that answers queries using the BIND 9 lightweight resolver protocol rather than the DNS protocol\&.
Bob Halley's avatar
Bob Halley committed
56
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
57
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
58
listens for resolver queries on a UDP port on the IPv4 loopback interface, 127\&.0\&.0\&.1\&. This means that
Mark Andrews's avatar
regen  
Mark Andrews committed
59
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
60
can only be used by processes running on the local machine\&. By default, UDP port number 921 is used for lightweight resolver requests and responses\&.
Bob Halley's avatar
Bob Halley committed
61
.PP
Tinderbox User's avatar
Tinderbox User committed
62
Incoming lightweight resolver requests are decoded by the server which then resolves them using the DNS protocol\&. When the DNS lookup completes,
Mark Andrews's avatar
regen  
Mark Andrews committed
63
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
64
encodes the answers in the lightweight resolver format and returns them to the client that made the request\&.
Bob Halley's avatar
Bob Halley committed
65
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
66
If
Tinderbox User's avatar
Tinderbox User committed
67
/etc/resolv\&.conf
Mark Andrews's avatar
regen  
Mark Andrews committed
68 69 70 71
contains any
\fBnameserver\fR
entries,
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
72
sends recursive DNS queries to those servers\&. This is similar to the use of forwarders in a caching name server\&. If no
Mark Andrews's avatar
regen  
Mark Andrews committed
73 74 75
\fBnameserver\fR
entries are present, or if forwarding fails,
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
76
resolves the queries autonomously starting at the root name servers, using a built\-in list of root server hints\&.
Bob Halley's avatar
Bob Halley committed
77
.SH "OPTIONS"
Mark Andrews's avatar
regen  
Mark Andrews committed
78
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
79 80
\-4
.RS 4
Tinderbox User's avatar
Tinderbox User committed
81
Use IPv4 only even if the host machine is capable of IPv6\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
82 83 84
\fB\-4\fR
and
\fB\-6\fR
Tinderbox User's avatar
Tinderbox User committed
85
are mutually exclusive\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
86 87 88 89
.RE
.PP
\-6
.RS 4
Tinderbox User's avatar
Tinderbox User committed
90
Use IPv6 only even if the host machine is capable of IPv4\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
91 92 93
\fB\-4\fR
and
\fB\-6\fR
Tinderbox User's avatar
Tinderbox User committed
94
are mutually exclusive\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
95 96 97 98 99 100 101
.RE
.PP
\-c \fIconfig\-file\fR
.RS 4
Use
\fIconfig\-file\fR
as the configuration file instead of the default,
Tinderbox User's avatar
Tinderbox User committed
102
/etc/lwresd\&.conf\&.
Automatic Updater's avatar
regen  
Automatic Updater committed
103
\fB\-c\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
104
can not be used with
Tinderbox User's avatar
Tinderbox User committed
105
\fB\-C\fR\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
106 107
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
108
\-C \fIconfig\-file\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
109
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
110 111 112
Use
\fIconfig\-file\fR
as the configuration file instead of the default,
Tinderbox User's avatar
Tinderbox User committed
113
/etc/resolv\&.conf\&.
Automatic Updater's avatar
regen  
Automatic Updater committed
114
\fB\-C\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
115
can not be used with
Tinderbox User's avatar
Tinderbox User committed
116
\fB\-c\fR\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
117 118
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
119
\-d \fIdebug\-level\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
120
.RS 4
Tinderbox User's avatar
Tinderbox User committed
121 122
Set the daemon\*(Aqs debug level to
\fIdebug\-level\fR\&. Debugging traces from
Mark Andrews's avatar
regen  
Mark Andrews committed
123
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
124
become more verbose as the debug level increases\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
125 126
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
127
\-f
Mark Andrews's avatar
regen  
Mark Andrews committed
128
.RS 4
Tinderbox User's avatar
Tinderbox User committed
129
Run the server in the foreground (i\&.e\&. do not daemonize)\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
130 131
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
132
\-g
Mark Andrews's avatar
regen  
Mark Andrews committed
133
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
134
Run the server in the foreground and force all logging to
Tinderbox User's avatar
Tinderbox User committed
135
stderr\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
136 137
.RE
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
138 139 140 141 142
\-i \fIpid\-file\fR
.RS 4
Use
\fIpid\-file\fR
as the PID file instead of the default,
Tinderbox User's avatar
Tinderbox User committed
143
/var/run/lwresd/lwresd\&.pid\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
144 145 146 147
.RE
.PP
\-m \fIflag\fR
.RS 4
Tinderbox User's avatar
Tinderbox User committed
148
Turn on memory usage debugging flags\&. Possible flags are
Mark Andrews's avatar
regen  
Mark Andrews committed
149 150 151 152
\fIusage\fR,
\fItrace\fR,
\fIrecord\fR,
\fIsize\fR, and
Tinderbox User's avatar
Tinderbox User committed
153 154
\fImctx\fR\&. These correspond to the ISC_MEM_DEBUGXXXX flags described in
<isc/mem\&.h>\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
155 156
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
157
\-n \fI#cpus\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
158
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
159 160
Create
\fI#cpus\fR
Tinderbox User's avatar
Tinderbox User committed
161
worker threads to take advantage of multiple CPUs\&. If not specified,
Mark Andrews's avatar
regen  
Mark Andrews committed
162
\fBlwresd\fR
Tinderbox User's avatar
Tinderbox User committed
163
will try to determine the number of CPUs present and create one thread per CPU\&. If it is unable to determine the number of CPUs, a single worker thread will be created\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
164 165
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
166
\-P \fIport\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
167
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
168
Listen for lightweight resolver queries on port
Tinderbox User's avatar
Tinderbox User committed
169
\fIport\fR\&. If not specified, the default is port 921\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
170 171
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
172
\-p \fIport\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
173
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
174
Send DNS lookups to port
Tinderbox User's avatar
Tinderbox User committed
175
\fIport\fR\&. If not specified, the default is port 53\&. This provides a way of testing the lightweight resolver daemon with a name server that listens for queries on a non\-standard port number\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
176 177
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
178
\-s
Mark Andrews's avatar
regen  
Mark Andrews committed
179
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
180
Write memory usage statistics to
Tinderbox User's avatar
Tinderbox User committed
181 182
stdout
on exit\&.
Tinderbox User's avatar
Tinderbox User committed
183 184 185 186 187 188 189 190 191 192 193 194
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Tinderbox User's avatar
Tinderbox User committed
195
This option is mainly of interest to BIND 9 developers and may be removed or changed in a future release\&.
Tinderbox User's avatar
Tinderbox User committed
196
.sp .5v
Bob Halley's avatar
Bob Halley committed
197
.RE
Mark Andrews's avatar
regen  
Mark Andrews committed
198 199
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
200
\-t \fIdirectory\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
201
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
202
Chroot to
Mark Andrews's avatar
regen  
Mark Andrews committed
203
\fIdirectory\fR
Tinderbox User's avatar
Tinderbox User committed
204
after processing the command line arguments, but before reading the configuration file\&.
Tinderbox User's avatar
Tinderbox User committed
205 206 207 208 209 210 211 212 213 214 215 216
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
Mark Andrews's avatar
regen  
Mark Andrews committed
217 218
This option should be used in conjunction with the
\fB\-u\fR
Tinderbox User's avatar
Tinderbox User committed
219
option, as chrooting a process running as root doesn\*(Aqt enhance security on most systems; the way
Mark Andrews's avatar
regen  
Mark Andrews committed
220
\fBchroot(2)\fR
Tinderbox User's avatar
Tinderbox User committed
221
is defined allows a process with root privileges to escape a chroot jail\&.
Tinderbox User's avatar
Tinderbox User committed
222
.sp .5v
Bob Halley's avatar
Bob Halley committed
223
.RE
Mark Andrews's avatar
regen  
Mark Andrews committed
224 225
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
226
\-u \fIuser\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
227
.RS 4
Mark Andrews's avatar
regen  
Mark Andrews committed
228
Setuid to
Mark Andrews's avatar
regen  
Mark Andrews committed
229
\fIuser\fR
Tinderbox User's avatar
Tinderbox User committed
230
after completing privileged operations, such as creating sockets that listen on privileged ports\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
231 232
.RE
.PP
Rob Austein's avatar
regen  
Rob Austein committed
233
\-v
Mark Andrews's avatar
regen  
Mark Andrews committed
234
.RS 4
Tinderbox User's avatar
Tinderbox User committed
235
Report the version number and exit\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
236
.RE
Bob Halley's avatar
Bob Halley committed
237
.SH "FILES"
Mark Andrews's avatar
regen  
Mark Andrews committed
238
.PP
Tinderbox User's avatar
Tinderbox User committed
239
/etc/resolv\&.conf
Mark Andrews's avatar
regen  
Mark Andrews committed
240
.RS 4
Tinderbox User's avatar
Tinderbox User committed
241
The default configuration file\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
242 243
.RE
.PP
Tinderbox User's avatar
Tinderbox User committed
244
/var/run/lwresd\&.pid
Mark Andrews's avatar
regen  
Mark Andrews committed
245
.RS 4
Tinderbox User's avatar
Tinderbox User committed
246
The default process\-id file\&.
Mark Andrews's avatar
regen  
Mark Andrews committed
247
.RE
Bob Halley's avatar
Bob Halley committed
248 249
.SH "SEE ALSO"
.PP
Mark Andrews's avatar
regen  
Mark Andrews committed
250 251
\fBnamed\fR(8),
\fBlwres\fR(3),
Tinderbox User's avatar
Tinderbox User committed
252
\fBresolver\fR(5)\&.
Bob Halley's avatar
Bob Halley committed
253 254
.SH "AUTHOR"
.PP
Tinderbox User's avatar
Tinderbox User committed
255
\fBInternet Systems Consortium, Inc\&.\fR
Mark Andrews's avatar
regen  
Mark Andrews committed
256
.SH "COPYRIGHT"
Tinderbox User's avatar
Tinderbox User committed
257
.br
Tinderbox User's avatar
Tinderbox User committed
258
Copyright \(co 2004, 2005, 2007-2009, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
regen  
Mark Andrews committed
259 260 261
.br
Copyright \(co 2000, 2001 Internet Software Consortium.
.br