1<!-- 2 - Copyright (C) 2004, 2005, 2007-2009, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000, 2001 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<html> 18<head> 19<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 20<title>lwresd</title> 21<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> 22</head> 23<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"> 24<a name="man.lwresd"></a><div class="titlepage"></div> 25<div class="refnamediv"> 26<h2>Name</h2> 27<p><span class="application">lwresd</span> — lightweight resolver daemon</p> 28</div> 29<div class="refsynopsisdiv"> 30<h2>Synopsis</h2> 31<div class="cmdsynopsis"><p><code class="command">lwresd</code> [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-C <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-d <em class="replaceable"><code>debug-level</code></em></code>] [<code class="option">-f</code>] [<code class="option">-g</code>] [<code class="option">-i <em class="replaceable"><code>pid-file</code></em></code>] [<code class="option">-m <em class="replaceable"><code>flag</code></em></code>] [<code class="option">-n <em class="replaceable"><code>#cpus</code></em></code>] [<code class="option">-P <em class="replaceable"><code>port</code></em></code>] [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] [<code class="option">-s</code>] [<code class="option">-t <em class="replaceable"><code>directory</code></em></code>] [<code class="option">-u <em class="replaceable"><code>user</code></em></code>] [<code class="option">-v</code>] [<code class="option">-4</code>] [<code class="option">-6</code>]</p></div> 32</div> 33<div class="refsection"> 34<a name="id-1.7"></a><h2>DESCRIPTION</h2> 35<p><span class="command"><strong>lwresd</strong></span> 36 is the daemon providing name lookup 37 services to clients that use the BIND 9 lightweight resolver 38 library. It is essentially a stripped-down, caching-only name 39 server that answers queries using the BIND 9 lightweight 40 resolver protocol rather than the DNS protocol. 41 </p> 42<p><span class="command"><strong>lwresd</strong></span> 43 listens for resolver queries on a 44 UDP port on the IPv4 loopback interface, 127.0.0.1. This 45 means that <span class="command"><strong>lwresd</strong></span> can only be used by 46 processes running on the local machine. By default, UDP port 47 number 921 is used for lightweight resolver requests and 48 responses. 49 </p> 50<p> 51 Incoming lightweight resolver requests are decoded by the 52 server which then resolves them using the DNS protocol. When 53 the DNS lookup completes, <span class="command"><strong>lwresd</strong></span> encodes 54 the answers in the lightweight resolver format and returns 55 them to the client that made the request. 56 </p> 57<p> 58 If <code class="filename">/etc/resolv.conf</code> contains any 59 <code class="option">nameserver</code> entries, <span class="command"><strong>lwresd</strong></span> 60 sends recursive DNS queries to those servers. This is similar 61 to the use of forwarders in a caching name server. If no 62 <code class="option">nameserver</code> entries are present, or if 63 forwarding fails, <span class="command"><strong>lwresd</strong></span> resolves the 64 queries autonomously starting at the root name servers, using 65 a built-in list of root server hints. 66 </p> 67</div> 68<div class="refsection"> 69<a name="id-1.8"></a><h2>OPTIONS</h2> 70<div class="variablelist"><dl class="variablelist"> 71<dt><span class="term">-4</span></dt> 72<dd><p> 73 Use IPv4 only even if the host machine is capable of IPv6. 74 <code class="option">-4</code> and <code class="option">-6</code> are mutually 75 exclusive. 76 </p></dd> 77<dt><span class="term">-6</span></dt> 78<dd><p> 79 Use IPv6 only even if the host machine is capable of IPv4. 80 <code class="option">-4</code> and <code class="option">-6</code> are mutually 81 exclusive. 82 </p></dd> 83<dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt> 84<dd><p> 85 Use <em class="replaceable"><code>config-file</code></em> as the 86 configuration file instead of the default, 87 <code class="filename">/etc/lwresd.conf</code>. 88 89 <code class="option">-c</code> can not be used with <code class="option">-C</code>. 90 </p></dd> 91<dt><span class="term">-C <em class="replaceable"><code>config-file</code></em></span></dt> 92<dd><p> 93 Use <em class="replaceable"><code>config-file</code></em> as the 94 configuration file instead of the default, 95 <code class="filename">/etc/resolv.conf</code>. 96 <code class="option">-C</code> can not be used with <code class="option">-c</code>. 97 </p></dd> 98<dt><span class="term">-d <em class="replaceable"><code>debug-level</code></em></span></dt> 99<dd><p> 100 Set the daemon's debug level to <em class="replaceable"><code>debug-level</code></em>. 101 Debugging traces from <span class="command"><strong>lwresd</strong></span> become 102 more verbose as the debug level increases. 103 </p></dd> 104<dt><span class="term">-f</span></dt> 105<dd><p> 106 Run the server in the foreground (i.e. do not daemonize). 107 </p></dd> 108<dt><span class="term">-g</span></dt> 109<dd><p> 110 Run the server in the foreground and force all logging 111 to <code class="filename">stderr</code>. 112 </p></dd> 113<dt><span class="term">-i <em class="replaceable"><code>pid-file</code></em></span></dt> 114<dd><p> 115 Use <em class="replaceable"><code>pid-file</code></em> as the 116 PID file instead of the default, 117 <code class="filename">/var/run/lwresd/lwresd.pid</code>. 118 </p></dd> 119<dt><span class="term">-m <em class="replaceable"><code>flag</code></em></span></dt> 120<dd><p> 121 Turn on memory usage debugging flags. Possible flags are 122 <em class="replaceable"><code>usage</code></em>, 123 <em class="replaceable"><code>trace</code></em>, 124 <em class="replaceable"><code>record</code></em>, 125 <em class="replaceable"><code>size</code></em>, and 126 <em class="replaceable"><code>mctx</code></em>. 127 These correspond to the ISC_MEM_DEBUGXXXX flags described in 128 <code class="filename"><isc/mem.h></code>. 129 </p></dd> 130<dt><span class="term">-n <em class="replaceable"><code>#cpus</code></em></span></dt> 131<dd><p> 132 Create <em class="replaceable"><code>#cpus</code></em> worker threads 133 to take advantage of multiple CPUs. If not specified, 134 <span class="command"><strong>lwresd</strong></span> will try to determine the 135 number of CPUs present and create one thread per CPU. 136 If it is unable to determine the number of CPUs, a 137 single worker thread will be created. 138 </p></dd> 139<dt><span class="term">-P <em class="replaceable"><code>port</code></em></span></dt> 140<dd><p> 141 Listen for lightweight resolver queries on port 142 <em class="replaceable"><code>port</code></em>. If 143 not specified, the default is port 921. 144 </p></dd> 145<dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt> 146<dd><p> 147 Send DNS lookups to port <em class="replaceable"><code>port</code></em>. If not 148 specified, the default is port 53. This provides a 149 way of testing the lightweight resolver daemon with a 150 name server that listens for queries on a non-standard 151 port number. 152 </p></dd> 153<dt><span class="term">-s</span></dt> 154<dd> 155<p> 156 Write memory usage statistics to <code class="filename">stdout</code> 157 on exit. 158 </p> 159<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 160<h3 class="title">Note</h3> 161<p> 162 This option is mainly of interest to BIND 9 developers 163 and may be removed or changed in a future release. 164 </p> 165</div> 166</dd> 167<dt><span class="term">-t <em class="replaceable"><code>directory</code></em></span></dt> 168<dd> 169<p>Chroot 170 to <em class="replaceable"><code>directory</code></em> after 171 processing the command line arguments, but before 172 reading the configuration file. 173 </p> 174<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> 175<h3 class="title">Warning</h3> 176<p> 177 This option should be used in conjunction with the 178 <code class="option">-u</code> option, as chrooting a process 179 running as root doesn't enhance security on most 180 systems; the way <code class="function">chroot(2)</code> is 181 defined allows a process with root privileges to 182 escape a chroot jail. 183 </p> 184</div> 185</dd> 186<dt><span class="term">-u <em class="replaceable"><code>user</code></em></span></dt> 187<dd><p>Setuid 188 to <em class="replaceable"><code>user</code></em> after completing 189 privileged operations, such as creating sockets that 190 listen on privileged ports. 191 </p></dd> 192<dt><span class="term">-v</span></dt> 193<dd><p> 194 Report the version number and exit. 195 </p></dd> 196</dl></div> 197</div> 198<div class="refsection"> 199<a name="id-1.9"></a><h2>FILES</h2> 200<div class="variablelist"><dl class="variablelist"> 201<dt><span class="term"><code class="filename">/etc/resolv.conf</code></span></dt> 202<dd><p> 203 The default configuration file. 204 </p></dd> 205<dt><span class="term"><code class="filename">/var/run/lwresd.pid</code></span></dt> 206<dd><p> 207 The default process-id file. 208 </p></dd> 209</dl></div> 210</div> 211<div class="refsection"> 212<a name="id-1.10"></a><h2>SEE ALSO</h2> 213<p><span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>, 214 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, 215 <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>. 216 </p> 217</div> 218</div></body> 219</html> 220