source: server/other/unbound.xml@ 0a96698

plabs/python-mods qt5new trunk
Last change on this file since 0a96698 was 0a96698, checked in by Douglas R. Reno <renodr@…>, 4 months ago

Unbound: on systemd, unbound-anchor is not generated by the unit.

On SysV however, that paragraph is still valid, since it's generated by
the bootscript. On systemd, we need to run that command unconditionally.

  • Property mode set to 100644
File size: 12.4 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY unbound-download-http "https://nlnetlabs.nl/downloads/unbound/unbound-&unbound-version;.tar.gz">
8 <!ENTITY unbound-download-ftp " ">
9 <!ENTITY unbound-md5sum "f0a767b32058ae67311e5d3665139d15">
10 <!ENTITY unbound-size "5.9 MB">
11 <!ENTITY unbound-buildsize "139 MB (with docs; add 11 MB for tests)">
12 <!ENTITY unbound-time "0.4 SBU (Using parallelism=4; with docs; add 0.4 SBU for tests)">
13]>
14
15<sect1 id="unbound" xreflabel="Unbound-&unbound-version;">
16 <?dbhtml filename="unbound.html"?>
17
18 <sect1info>
19 <date>$Date$</date>
20 </sect1info>
21
22 <title>Unbound-&unbound-version;</title>
23
24 <indexterm zone="unbound">
25 <primary sortas="a-Unbound">Unbound</primary>
26 </indexterm>
27
28 <sect2 role="package">
29 <title>Introduction to Unbound</title>
30
31 <para>
32 <application>Unbound</application> is a validating, recursive, and caching
33 DNS resolver. It is designed as a set of modular components that
34 incorporate modern features, such as enhanced security (DNSSEC)
35 validation, Internet Protocol Version 6 (IPv6), and a client resolver
36 library API as an integral part of the architecture.
37 </para>
38
39 &lfs112_checked;
40
41 <bridgehead renderas="sect3">Package Information</bridgehead>
42 <itemizedlist spacing="compact">
43 <listitem>
44 <para>
45 Download (HTTP): <ulink url="&unbound-download-http;"/>
46 </para>
47 </listitem>
48 <listitem>
49 <para>
50 Download (FTP): <ulink url="&unbound-download-ftp;"/>
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download MD5 sum: &unbound-md5sum;
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Download size: &unbound-size;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Estimated disk space required: &unbound-buildsize;
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Estimated build time: &unbound-time;
71 </para>
72 </listitem>
73 </itemizedlist>
74
75 <bridgehead renderas="sect3">Unbound Dependencies</bridgehead>
76<!--
77 <bridgehead renderas="sect4">Required</bridgehead>
78 <para role="required">
79 <xref linkend="openssl"/>
80 broken?
81 or <xref linkend="nss"/>
82 </para>
83-->
84
85 <bridgehead renderas="sect4">Optional</bridgehead>
86 <para role="optional">
87 <xref linkend="libevent"/>,
88 <xref linkend="nettle"/>,
89 <xref linkend="python2"/>,
90 <xref linkend="swig"/> (for Python bindings),
91 <xref linkend="doxygen"/> (for html documentation),
92 <ulink url="https://dnstap.info/">dnstap</ulink>, and
93 <ulink url="https://pypi.python.org/pypi/Sphinx">Sphinx</ulink> (for
94 Python bindings documentation)
95 </para>
96
97 <para condition="html" role="usernotes">User Notes:
98 <ulink url="&blfs-wiki;/unbound"/>
99 </para>
100 </sect2>
101
102 <sect2 role="installation">
103 <title>Installation of Unbound</title>
104
105 <para>
106 There should be a dedicated user and group to take control of the
107 <command>unbound</command> daemon after it is started. Issue the following
108 commands as the <systemitem class="username">root</systemitem> user:
109 </para>
110
111<screen role="root"><userinput>groupadd -g 88 unbound &amp;&amp;
112useradd -c "Unbound DNS Resolver" -d /var/lib/unbound -u 88 \
113 -g unbound -s /bin/false unbound</userinput></screen>
114
115 <para>
116 Install <application>Unbound</application> by running the following
117 commands:
118 </para>
119
120<screen><userinput>./configure --prefix=/usr \
121 --sysconfdir=/etc \
122 --disable-static \
123 --with-pidfile=/run/unbound.pid &amp;&amp;
124make</userinput></screen>
125
126 <para>
127 If you have <xref linkend="doxygen"/> package installed and want to build
128 html documentation, run the following command:
129 </para>
130
131<screen remap="doc"><userinput>make doc</userinput></screen>
132
133 <para>
134 To test the results, issue <command>make check</command>.
135 </para>
136
137 <para>
138 Now, as the <systemitem class="username">root</systemitem> user:
139 </para>
140
141<screen role="root"><userinput>make install &amp;&amp;
142mv -v /usr/sbin/unbound-host /usr/bin/</userinput></screen>
143
144 <para>
145 If you built the documentation, install it by running the following
146 commands as the <systemitem class="username">root</systemitem> user:
147 </para>
148
149<screen role="root"
150 remap="doc"><userinput>install -v -m755 -d /usr/share/doc/unbound-&unbound-version; &amp;&amp;
151install -v -m644 doc/html/* /usr/share/doc/unbound-&unbound-version;</userinput></screen>
152
153 </sect2>
154
155 <sect2 role="commands">
156 <title>Command Explanations</title>
157
158 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
159 href="../../xincludes/static-libraries.xml"/>
160
161 <para>
162 <option>--with-libevent</option>: This option enables libevent support
163 allowing use of large outgoing port ranges.
164 </para>
165
166 <para>
167 <option>--with-pyunbound</option>: This option enables building of the Python
168 bindings.
169 </para>
170
171 </sect2>
172
173 <sect2 role="configuration">
174 <title>Configuring Unbound</title>
175
176 <sect3 id="unbound-config">
177 <title>Config Files</title>
178
179 <para>
180 <filename>/etc/unbound/unbound.conf</filename>
181 </para>
182
183 <indexterm zone="unbound unbound-config">
184 <primary sortas="e-etc-unbound-unbound.conf">/etc/unbound/unbound.conf</primary>
185 </indexterm>
186
187 </sect3>
188
189 <sect3>
190 <title>Configuration Information</title>
191
192 <para>
193 In the default configuration, <command>unbound</command> will bind to
194 localhost (127.0.0.1 IP address) and allow recursive queries only from
195 localhost clients. If you want to use <command>unbound</command> for
196 local DNS resolution, run the following command as the
197 <systemitem class="username">root</systemitem> user:
198 </para>
199
200<screen role="root"><userinput>echo "nameserver 127.0.0.1" > /etc/resolv.conf</userinput></screen>
201
202 <para>
203 If you are using a DHCP client for connecting to a network,
204 <filename>/etc/resolv.conf</filename> gets overwritten with values
205 provided by DHCP server. You can override this, for example in <xref
206 linkend="dhcp"/>, by running the following command as the <systemitem
207 class="username">root</systemitem> user:
208 </para>
209
210<screen role="root"><userinput>sed -i '/request /i\supersede domain-name-servers 127.0.0.1;' \
211 /etc/dhcp/dhclient.conf</userinput></screen>
212
213 <para>
214 For advanced configuration see
215 <filename>/etc/unbound/unbound.conf</filename> file and the
216 documentation.
217 </para>
218
219 <para revision="sysv">
220 When <application>Unbound</application> is installed, some package
221 builds fail if the file <filename>/etc/unbound/root.key</filename> is
222 not found. This file is created by running the boot script (install
223 instructions below). Alternatively, it can be created by running the
224 following command as the <systemitem class="username">root</systemitem>
225 user:
226 </para>
227
228 <para revision="systemd">
229 When <application>Unbound</application> is installed, some package
230 builds fail if the file <filename>/etc/unbound/root.key</filename> is
231 not found. Create this file by running the following command as the
232 <systemitem class="username">root</systemitem> user:
233 </para>
234
235<screen role="nodump"><userinput>unbound-anchor</userinput></screen>
236
237 </sect3>
238
239 <sect3 id="unbound-init">
240 <title><phrase revision="sysv">Boot Script</phrase>
241 <phrase revision="systemd">Systemd Unit</phrase></title>
242
243 <para>
244 If you want the <application>Unbound</application> server to
245 start automatically when the system is booted, install the
246 <phrase revision="sysv"><filename>/etc/rc.d/init.d/unbound</filename>
247 init script</phrase>
248 <phrase revision="systemd"><filename>unbound.service</filename>
249 unit</phrase> included
250 in the <xref linkend="bootscripts" revision="sysv"/>
251 <xref linkend="systemd-units" revision="systemd"/> package:
252 </para>
253
254 <indexterm zone="unbound unbound-init">
255 <primary sortas="f-unbound">unbound</primary>
256 </indexterm>
257
258<screen role="root"><userinput>make install-unbound</userinput></screen>
259
260 </sect3>
261
262 </sect2>
263
264 <sect2 role="content">
265 <title>Contents</title>
266
267 <segmentedlist>
268 <segtitle>Installed Programs</segtitle>
269 <segtitle>Installed Library</segtitle>
270 <segtitle>Installed Directories</segtitle>
271
272 <seglistitem>
273 <seg>
274 unbound, unbound-anchor, unbound-checkconf, unbound-control,
275 unbound-control-setup, and unbound-host
276 </seg>
277 <seg>
278 libunbound.so and (optional)
279 /usr/lib/python&python2-majorver;/site-packages/_unbound.so
280 </seg>
281 <seg>
282 /etc/unbound and /usr/share/doc/unbound-&unbound-version; (optional)
283 </seg>
284 </seglistitem>
285 </segmentedlist>
286
287 <variablelist>
288 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
289 <?dbfo list-presentation="list"?>
290 <?dbhtml list-presentation="table"?>
291
292 <varlistentry id="unbound-prog">
293 <term><command>unbound</command></term>
294 <listitem>
295 <para>
296 is a DNS resolver daemon
297 </para>
298 <indexterm zone="unbound unbound-prog">
299 <primary sortas="b-unbound">unbound</primary>
300 </indexterm>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry id="unbound-anchor">
305 <term><command>unbound-anchor</command></term>
306 <listitem>
307 <para>
308 performs setup or update of the root trust anchor for DNSSEC
309 validation
310 </para>
311 <indexterm zone="unbound unbound-anchor">
312 <primary sortas="b-unbound-anchor">unbound-anchor</primary>
313 </indexterm>
314 </listitem>
315 </varlistentry>
316
317 <varlistentry id="unbound-checkconf">
318 <term><command>unbound-checkconf</command></term>
319 <listitem>
320 <para>
321 checks the <command>unbound</command> configuration file for syntax
322 and other errors
323 </para>
324 <indexterm zone="unbound unbound-checkconf">
325 <primary sortas="b-unbound-checkconf">unbound-checkconf</primary>
326 </indexterm>
327 </listitem>
328 </varlistentry>
329
330 <varlistentry id="unbound-control">
331 <term><command>unbound-control</command></term>
332 <listitem>
333 <para>
334 performs remote administration on the <command>unbound</command> DNS
335 resolver
336 </para>
337 <indexterm zone="unbound unbound-control">
338 <primary sortas="b-unbound-control">unbound-control</primary>
339 </indexterm>
340 </listitem>
341 </varlistentry>
342
343 <varlistentry id="unbound-control-setup">
344 <term><command>unbound-control-setup</command></term>
345 <listitem>
346 <para>
347 generates a self-signed certificate and private keys for the server
348 and client
349 </para>
350 <indexterm zone="unbound unbound-control-setup">
351 <primary sortas="b-unbound-control-setup">unbound-control-setup</primary>
352 </indexterm>
353 </listitem>
354 </varlistentry>
355
356 <varlistentry id="unbound-host">
357 <term><command>unbound-host</command></term>
358 <listitem>
359 <para>
360 is a DNS lookup utility similar to <command>host</command> from
361 <xref linkend="bind-utils"/>
362 </para>
363 <indexterm zone="unbound unbound-host">
364 <primary sortas="b-unbound-host">unbound-host</primary>
365 </indexterm>
366 </listitem>
367 </varlistentry>
368
369 <varlistentry id="libunbound">
370 <term><filename class="libraryfile">libunbound.so</filename></term>
371 <listitem>
372 <para>
373 provides the <application>Unbound</application> API functions to
374 programs
375 </para>
376 <indexterm zone="unbound libunbound">
377 <primary sortas="c-libunbound">libunbound.so</primary>
378 </indexterm>
379 </listitem>
380 </varlistentry>
381
382 </variablelist>
383
384 </sect2>
385
386</sect1>
Note: See TracBrowser for help on using the repository browser.