contrib/unbound/doc/README

   1 README for Unbound 1.10.1
   2 Copyright 2007 NLnet Labs
   3 http://unbound.net
   4
   5 This software is under BSD license, see LICENSE for details.
   6 The DNS64 module has BSD license in dns64/dns64.c.
   7 The DNSTAP code has BSD license in dnstap/dnstap.c.
   8
   9 * Download the latest release version of this software from
  10         http://unbound.net
  11   or get a beta version from the svn repository at
  12         http://unbound.net/svn/
  13
  14 * Uses the following libraries;
  15   * libevent    http://www.monkey.org/~provos/libevent/         (BSD license)
  16     (optional) can use builtin alternative instead.
  17   * libexpat    (for the unbound-anchor helper program)         (MIT license)
  18
  19 * Make and install: ./configure; make; make install
  20   * --with-libevent=/path/to/libevent
  21         Can be set to either the system install or the build directory.
  22         --with-libevent=no (default) gives a builtin alternative
  23         implementation. libevent is useful when having many (thousands)
  24         of outgoing ports. This improves randomization and spoof
  25         resistance. For the default of 16 ports the builtin alternative
  26         works well and is a little faster.
  27   * --with-libexpat=/path/to/libexpat
  28         Can be set to the install directory of libexpat.
  29   * --without-pthreads
  30         This disables pthreads. Without this option the pthreads library
  31         is detected automatically. Use this option to disable threading
  32         altogether, or, on Solaris, also use --with(out)-solaris-threads.
  33   * --enable-checking
  34         This enables assertions in the code that guard against a variety of
  35         programming errors, among which buffer overflows.  The program exits
  36         with an error if an assertion fails (but the buffer did not overflow).
  37   * --enable-static-exe
  38         This enables a debug option to statically link against the
  39         libevent library.
  40   * --enable-lock-checks
  41         This enables a debug option to check lock and unlock calls. It needs
  42         a recent pthreads library to work.
  43   * --enable-alloc-checks
  44         This enables a debug option to check malloc (calloc, realloc, free).
  45         The server periodically checks if the amount of memory used fits with
  46         the amount of memory it thinks it should be using, and reports
  47         memory usage in detail.
  48   * --with-conf-file=filename
  49         Set default location of config file,
  50         the default is /usr/local/etc/unbound/unbound.conf.
  51   * --with-pidfile=filename
  52         Set default location of pidfile,
  53         the default is /usr/local/etc/unbound/unbound.pid.
  54   * --with-run-dir=path
  55         Set default working directory,
  56         the default is /usr/local/etc/unbound.
  57   * --with-chroot-dir=path
  58         Set default chroot directory,
  59         the default is /usr/local/etc/unbound.
  60   * --with-rootkey-file=path
  61         Set the default root.key path.  This file is read and written.
  62         the default is /usr/local/etc/unbound/root.key
  63   * --with-rootcert-file=path
  64         Set the default root update certificate path.  A builtin certificate
  65         is used if this file is empty or does not exist.
  66         the default is /usr/local/etc/unbound/icannbundle.pem
  67   * --with-username=user
  68         Set default user name to change to,
  69         the default is the "unbound" user.
  70   * --with-pyunbound
  71         Create libunbound wrapper usable from python.
  72         Needs python-devel and swig development tools.
  73   * --with-pythonmodule
  74         Compile the python module that processes responses in the server.
  75   * --disable-sha2
  76         Disable support for RSASHA256 and RSASHA512 crypto.
  77   * --disable-gost
  78         Disable support for GOST crypto, RFC 5933.
  79   * --enable-subnet
  80         Enable EDNS client subnet processing.
  81
  82 * 'make test' runs a series of self checks.
  83
  84 Known issues
  85 ------------
  86 o If there are no replies for a forward or stub zone, for a reverse zone,
  87   you may need to add a local-zone: name transparent or nodefault to the
  88   server: section of the config file to unblock the reverse zone.
  89   Only happens for (sub)zones that are blocked by default; e.g. 10.in-addr.arpa
  90 o If libevent is older (before 1.3c), unbound will exit instead of reload
  91   on sighup. On a restart 'did not exit gracefully last time' warning is
  92   printed. Perform ./configure --with-libevent=no or update libevent, rerun
  93   configure and recompile unbound to make sighup work correctly.
  94   It is strongly suggested to use a recent version of libevent.
  95 o If you are not receiving the correct source IP address on replies (e.g.
  96   you are running a multihomed, anycast server), the interface-automatic
  97   option can be enabled to set socket options to achieve the correct
  98   source IP address on UDP replies. Listing all IP addresses explicitly in
  99   the config file is an alternative. The interface-automatic option uses
 100   non portable socket options, Linux and FreeBSD should work fine.
 101 o The warning 'openssl has no entropy, seeding with time', with chroot
 102   enabled, may be solved with a symbolic link to /dev/urandom from <chrootdir>.
 103 o On Solaris 5.10 some libtool packages from repositories do not work with
 104   gcc, showing errors gcc: unrecognized option `-KPIC'
 105   To solve this do ./configure libtool=./libtool [your options...].
 106   On Solaris you may pass CFLAGS="-xO4 -xtarget=generic" if you use sun-cc.
 107 o If unbound-control (or munin graphs) do not work, this can often be because
 108   the unbound-control-setup script creates the keys with restricted
 109   permissions, and the files need to be made readable or ownered by both the
 110   unbound daemon and unbound-control.
 111 o Crosscompile seems to hang.  You tried to install unbound under wine.
 112   wine regedit and remove all the unbound entries from the registry or
 113   delete .wine/drive_c.
 114
 115 Acknowledgements
 116 ----------------
 117 o Unbound was written in portable C by Wouter Wijngaards (NLnet Labs).
 118 o Thanks to David Blacka and Matt Larson (Verisign) for the unbound-java
 119   prototype. Design and code from that prototype has been used to create
 120   this program. Such as the iterator state machine and the cache design.
 121 o Other code origins are from the NSD (NLnet Labs) and LDNS (NLnet Labs)
 122   projects. Such as buffer, region-allocator and red-black tree code.
 123 o See Credits file for contributors.
 124
 125
 126 Your Support
 127 ------------
 128 NLnet Labs offers all of its software products as open source, most are
 129 published under a BSD license. You can download them, not only from the
 130 NLnet Labs website but also through the various OS distributions for
 131 which NSD, ldns, and Unbound are packaged. We therefore have little idea
 132 who uses our software in production environments and have no direct ties
 133 with 'our customers'.
 134
 135 Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
 136 whether you use one of our products in your production environment,
 137 what that environment looks like, and maybe even share some praise.
 138 We would like to refer to the fact that your organization is using our
 139 products. We will only do that if you explicitly allow us. In all other
 140 cases we will keep the information you share with us to ourselves.
 141
 142 In addition to the moral support you can also support us
 143 financially. NLnet Labs is a recognized not-for-profit charity foundation
 144 that is chartered to develop open-source software and open-standards
 145 for the Internet. If you use our software to satisfaction please express
 146 that by giving us a donation. For small donations PayPal can be used. For
 147 larger and regular donations please contact us at users@NLnetLabs.nl. Also
 148 see http://www.nlnetlabs.nl/labs/contributors/.
 149
 150
 151 * mailto:unbound-bugs@nlnetlabs.nl