DOCSEARCHbyAlgolia
Submit Docs

Unbound DNS Resolver Documentation

repository·master·Indexed 26 days ago

https://github.com/nlnetlabs/unbound

A fast, lean, validating, recursive, and caching DNS resolver designed around modern open standards. Documentation covers source compilation, configuration via unbound.conf, and the libunbound library for synchronous and asynchronous DNS resolution. Includes guides for managing the DNS cache, Prometheus metrics integration, trust anchor updates, and platform-specific setup for systemd, MacOSX, FreeBSD, Yocto Project, and Solaris.

Tokens
38.6K
Snippets
43
Records
257
Agent score
89%

What's inside Unbound

  1. Overview of pyUnbound Python extension

    master
    pyUnbound is an object-oriented Python extension module for libunbound. It provides a thread-safe, caching DNS resolver capable of performing DNSSEC validation. It supports both synchronous (blocking) and asynchronous (non-blocking) resolution, allowing the application to continue processing while results are being fetched.

  2. Overview of the Unbound Python module

    master

    The Unbound Python module provides a scriptable interface for Unbound, enabling rapid development of dynamic DNS-based applications. It uses an extensible SWIG interface to allow Python scripts to interact with Unbound's core functionality.

    Key capabilities include:

    • Scripting query events.
    • Producing authoritative answers.
    • Logging and generating detailed statistics (e.g., per query or per domain).
    • Monitoring Unbound using Python ecosystem tools (database backends, HTTP servers, etc.).
    • Manipulating the contents of the Unbound cache memory.
    • Using Unbound as a debugging and analysis tool.

  4. Use unbound-control for remote administration

    master
    The unbound-control utility allows for remote administration of an Unbound DNS server. It works by reading a local configuration file, establishing a TLS connection to the Unbound server, sending the requested command, and displaying the result. This is used to manage the server state and configuration remotely.

  5. Use Unbound on Windows

    master

    Unbound is a recursive DNS server providing caching, full recursion, stub recursion, DNSSEC validation, NSEC3, and IPv6 support.

    On Windows, you can manage the Unbound daemon through the following interfaces:

    • Service Management: Use ControlPanels\SystemTasks\Services to start or stop the daemon.
    • Log Viewing: Use ControlPanels\SystemTasks\Logbooks to view log entries (unless you have configured Unbound to log directly to a file).
    • Command Line: Unbound and its utilities can be used directly from the command line, similar to Unix-based systems.

    Note: By default, the daemon only provides service to localhost. To allow other clients, you must edit the configuration file.

  6. Cross-compile Unbound for Android

    master

    To cross-compile Unbound for Android, you must set up an environment that includes the Android NDK and SDK, and builds prerequisites (OpenSSL and Expat) for the target architecture.

    Prerequisites and Environment

    1. Set Paths: Ensure ANDROID_NDK_ROOT and ANDROID_SDK_ROOT are set correctly. Do not use ANDROID_NDK_HOME or ANDROID_SDK_HOME.
    2. Install Tools: Run ./contrib/android/install_tools.sh to install required tools like curl, tar, zip, unzip, and java.
    3. Install NDK/SDK: Run ./contrib/android/install_ndk.sh to place the NDK and SDK in the $HOME directory.
    4. Set Environment: Source the environment script: source ./contrib/android/setenv_android.sh. This script sets CC, CXX, AS, AR, CFLAGS, and sysroot based on your ANDROID_CPU and ANDROID_API variables.

    Build Process

    After setting the environment and installing OpenSSL/Expat via their respective scripts (./contrib/android/install_openssl.sh and ./contrib/android/install_expat.sh), run the following build sequence:

    export AUTOTOOLS_BUILD="$(./config.guess)"
export PKG_CONFIG_PATH="$ANDROID_PREFIX/lib/pkgconfig"
source ./contrib/android/setenv_android.sh
./contrib/android/install_openssl.sh
./contrib/android/install_expat.sh
./configure \
  --build="$AUTOTOOLS_BUILD" \
  --host="$AUTOTOOLS_HOST" \
  --prefix="$ANDROID_PREFIX" \
  --with-ssl="$ANDROID_PREFIX" \
  --with-libexpat="$ANDROID_PREFIX" \
  --disable-gost
make -j 2
make install

  7. Set up unbound-control

    master

    To use unbound-control, you must generate a self-signed certificate and private keys for both the server and the client.

    Use the unbound-control-setup script to generate these files. By default, they are created in the current run directory, but you can specify a different directory using the -d flag.

    Permissions:

    • The script preserves existing private keys in the target directory.
    • You can control access to unbound-control by adjusting the file permissions on the generated key files (default is owner and group access).
    • To ensure the Unbound daemon can read the files, run the setup script as the same user configured in unbound.conf or as root.

    Activation: After running the setup script as root, you must enable remote control in your unbound.conf by setting remote-control-enable: yes (or the equivalent configuration for your version).

    sudo -u unbound unbound-control-setup

  9. Cross-compile Unbound for Windows

    master

    You can cross-compile Unbound to produce .exe files.

    Prerequisites (Fedora 11 package names): mingw32-binutils, mingw32-cpp, mingw32-filesystem, mingw32-gcc, mingw32-openssl, mingw32-openssl-static, mingw32-runtime, zip, mingw32-termcap, mingw32-w32api, mingw32-zlib, mingw32-zlib-static, mingw32-nsis.

    Dynamic Linking: Use mingw32-configure and make. Install to a destination directory using make install DESTDIR=/path/to/dir to find DLLs and executables.

    Static Linking: Use the --enable-staticexe flag with mingw32-configure. Alternatively, use makedist.sh to create a setup.exe via NSIS.

  10. Setup or update the DNSSEC root trust anchor with unbound-anchor

    master

    The unbound-anchor utility is used to initialize or update the root trust anchor required for DNSSEC validation in Unbound. It can be used as a standalone tool or integrated into startup scripts to ensure the DNS server has a valid root key before it starts.

    If you are using the auto-trust-anchor-file option in unbound.conf to enable RFC 5011 automatic updates, the user running Unbound (typically unbound) must have write permissions to both the root anchor file and its parent directory.

  11. Build OpenSSL and Expat for iOS

    master

    Unbound requires OpenSSL and Expat to be built for the target iOS architecture before Unbound itself can be compiled. Use the provided scripts to download, configure, and install them into the $IOS_PREFIX directory.

    • OpenSSL: Installed via contrib/ios/install_openssl.sh. It uses a custom configuration file contrib/ios/15-ios.conf which disables engines (no-engine) to support the iOS environment.
    • Expat: Installed via contrib/ios/install_expat.sh.

    Headers are placed in $IOS_PREFIX/include and libraries in $IOS_PREFIX/lib.

    ./contrib/ios/install_openssl.sh
./contrib/ios/install_expat.sh

  12. Enable libevent support during compilation

    master
    By default, Unbound uses a builtin alternative that opens a maximum of 256 ports at a time. If you need to handle a large number of outgoing ports (e.g., 10,000), you should compile Unbound with libevent support using the --with-libevent configure option.