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

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY unbound-download-http "https://nlnetlabs.nl/downloads/unbound/unbound-&unbound-version;.tar.gz">
  <!ENTITY unbound-download-ftp  " ">
  <!ENTITY unbound-md5sum        "f0a767b32058ae67311e5d3665139d15">
  <!ENTITY unbound-size          "5.9 MB">
  <!ENTITY unbound-buildsize     "139 MB (with docs; add 11 MB for tests)">
  <!ENTITY unbound-time          "0.4 SBU (Using parallelism=4; with docs; add 0.4 SBU for tests)">
]>

<sect1 id="unbound" xreflabel="Unbound-&unbound-version;">
  <?dbhtml filename="unbound.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>Unbound-&unbound-version;</title>

  <indexterm zone="unbound">
    <primary sortas="a-Unbound">Unbound</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Unbound</title>

    <para>
      <application>Unbound</application> is a validating, recursive, and caching
      DNS resolver. It is designed as a set of modular components that
      incorporate modern features, such as enhanced security (DNSSEC)
      validation, Internet Protocol Version 6 (IPv6), and a client resolver
      library API as an integral part of the architecture.
    </para>

    &lfs112_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&unbound-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&unbound-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &unbound-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &unbound-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &unbound-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &unbound-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Unbound Dependencies</bridgehead>
<!--
    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="openssl"/>
 broken?
      or <xref linkend="nss"/>
    </para>
-->

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="libevent"/>,
      <xref linkend="nettle"/>,
      <xref linkend="python2"/>,
      <xref linkend="swig"/> (for Python bindings),
      <xref linkend="doxygen"/> (for html documentation),
      <ulink url="https://dnstap.info/">dnstap</ulink>, and
      <ulink url="https://pypi.python.org/pypi/Sphinx">Sphinx</ulink> (for
      Python bindings documentation)
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/unbound"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Unbound</title>

    <para>
      There should be a dedicated user and group to take control of the
      <command>unbound</command> daemon after it is started. Issue the following
      commands as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>groupadd -g 88 unbound &amp;&amp;
useradd -c "Unbound DNS Resolver" -d /var/lib/unbound -u 88 \
        -g unbound -s /bin/false unbound</userinput></screen>

    <para>
      Install <application>Unbound</application> by running the following
      commands:
    </para>

<screen><userinput>./configure --prefix=/usr     \
            --sysconfdir=/etc \
            --disable-static  \
            --with-pidfile=/run/unbound.pid &amp;&amp;
make</userinput></screen>

    <para>
      If you have <xref linkend="doxygen"/> package installed and want to build
      html documentation, run the following command:
    </para>

<screen remap="doc"><userinput>make doc</userinput></screen>

    <para>
      To test the results, issue <command>make check</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
mv -v /usr/sbin/unbound-host /usr/bin/</userinput></screen>

    <para>
      If you built the documentation, install it by running the following
      commands as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"
        remap="doc"><userinput>install -v -m755 -d /usr/share/doc/unbound-&unbound-version; &amp;&amp;
install -v -m644 doc/html/* /usr/share/doc/unbound-&unbound-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

    <para>
      <option>--with-libevent</option>: This option enables libevent support
      allowing use of large outgoing port ranges.
    </para>

    <para>
      <option>--with-pyunbound</option>: This option enables building of the Python
      bindings.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Unbound</title>

    <sect3 id="unbound-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/unbound/unbound.conf</filename>
      </para>

      <indexterm zone="unbound unbound-config">
        <primary sortas="e-etc-unbound-unbound.conf">/etc/unbound/unbound.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        In the default configuration, <command>unbound</command> will bind to
        localhost (127.0.0.1 IP address) and allow recursive queries only from
        localhost clients. If you want to use <command>unbound</command> for
        local DNS resolution, run the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>echo "nameserver 127.0.0.1" > /etc/resolv.conf</userinput></screen>

      <para>
        If you are using a DHCP client for connecting to a network,
        <filename>/etc/resolv.conf</filename> gets overwritten with values
        provided by DHCP server. You can override this, for example in <xref
        linkend="dhcp"/>, by running the following command as the <systemitem
        class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>sed -i '/request /i\supersede domain-name-servers 127.0.0.1;' \
       /etc/dhcp/dhclient.conf</userinput></screen>

      <para>
        For advanced configuration see
        <filename>/etc/unbound/unbound.conf</filename> file and the
        documentation.
      </para>

      <para revision="sysv">
        When <application>Unbound</application> is installed, some package
        builds fail if the file <filename>/etc/unbound/root.key</filename> is
        not found. This file is created by running the boot script (install
        instructions below).  Alternatively, it can be created by running the
        following command as the <systemitem class="username">root</systemitem>
        user:
      </para>

      <para revision="systemd">
        When <application>Unbound</application> is installed, some package
        builds fail if the file <filename>/etc/unbound/root.key</filename> is
        not found. Create this file by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="nodump"><userinput>unbound-anchor</userinput></screen>

    </sect3>

    <sect3 id="unbound-init">
      <title><phrase revision="sysv">Boot Script</phrase>
             <phrase revision="systemd">Systemd Unit</phrase></title>

      <para>
        If you want the <application>Unbound</application> server to
        start automatically when the system is booted, install the
        <phrase revision="sysv"><filename>/etc/rc.d/init.d/unbound</filename>
        init script</phrase>
        <phrase revision="systemd"><filename>unbound.service</filename>
        unit</phrase> included
        in the <xref linkend="bootscripts" revision="sysv"/>
        <xref linkend="systemd-units" revision="systemd"/> package:
      </para>

      <indexterm zone="unbound unbound-init">
        <primary sortas="f-unbound">unbound</primary>
      </indexterm>

<screen role="root"><userinput>make install-unbound</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          unbound, unbound-anchor, unbound-checkconf, unbound-control,
          unbound-control-setup, and unbound-host
        </seg>
        <seg>
          libunbound.so and (optional)
          /usr/lib/python&python2-majorver;/site-packages/_unbound.so
        </seg>
        <seg>
          /etc/unbound and /usr/share/doc/unbound-&unbound-version; (optional)
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="unbound-prog">
        <term><command>unbound</command></term>
        <listitem>
          <para>
            is a DNS resolver daemon
          </para>
          <indexterm zone="unbound unbound-prog">
            <primary sortas="b-unbound">unbound</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unbound-anchor">
        <term><command>unbound-anchor</command></term>
        <listitem>
          <para>
            performs setup or update of the root trust anchor for DNSSEC
            validation
          </para>
          <indexterm zone="unbound unbound-anchor">
            <primary sortas="b-unbound-anchor">unbound-anchor</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unbound-checkconf">
        <term><command>unbound-checkconf</command></term>
        <listitem>
          <para>
            checks the <command>unbound</command> configuration file for syntax
            and other errors
          </para>
          <indexterm zone="unbound unbound-checkconf">
            <primary sortas="b-unbound-checkconf">unbound-checkconf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unbound-control">
        <term><command>unbound-control</command></term>
        <listitem>
          <para>
            performs remote administration on the <command>unbound</command> DNS
            resolver
          </para>
          <indexterm zone="unbound unbound-control">
            <primary sortas="b-unbound-control">unbound-control</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unbound-control-setup">
        <term><command>unbound-control-setup</command></term>
        <listitem>
          <para>
            generates a self-signed certificate and private keys for the server
            and client
          </para>
          <indexterm zone="unbound unbound-control-setup">
            <primary sortas="b-unbound-control-setup">unbound-control-setup</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="unbound-host">
        <term><command>unbound-host</command></term>
        <listitem>
          <para>
            is a DNS lookup utility similar to <command>host</command> from
            <xref linkend="bind-utils"/>
          </para>
          <indexterm zone="unbound unbound-host">
            <primary sortas="b-unbound-host">unbound-host</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libunbound">
        <term><filename class="libraryfile">libunbound.so</filename></term>
        <listitem>
          <para>
            provides the <application>Unbound</application> API functions to
            programs
          </para>
          <indexterm zone="unbound libunbound">
            <primary sortas="c-libunbound">libunbound.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>