build.rst 11.5 KB
Newer Older
Marek Vavruša's avatar
Marek Vavruša committed
1
2
3
Building project
================

Marek Vavrusa's avatar
Marek Vavrusa committed
4
5
6
7
8
9
10
Installing from packages
------------------------

The resolver is packaged for Debian, Fedora, Ubuntu and openSUSE Linux distributions.
Refer to `project page <https://www.knot-resolver.cz/pages/try.html>`_ for information about
installing from packages. If packages are not available for your OS, see following sections
to see how you can build it from sources (or package it), or use official `Docker images`_.
Marek Vavruša's avatar
Marek Vavruša committed
11
12
13
14
15
16
17

Platform considerations
-----------------------

.. csv-table::
   :header: "Project", "Platforms", "Compatibility notes"

18
19
   "``daemon``", "UNIX-like [#]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
   "``library``", "UNIX-like, Microsoft Windows [#]_ ", "MSVC_ not supported, needs MinGW_"
Marek Vavruša's avatar
Marek Vavruša committed
20
   "``modules``", "*varies*", ""
21
22
   "``tests/unit``", "*equivalent to library*", ""
   "``tests/integration``", "UNIX-like", "Depends on library injection (see [2]_)"
Marek Vavruša's avatar
Marek Vavruša committed
23

24
25
.. [#] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
.. [#] Modules are not supported yet, as the PE/DLL loading is different. Library injection is working with ELF *(or Mach-O flat namespace)* only.
Marek Vavruša's avatar
Marek Vavruša committed
26
27
28
29

Requirements
------------

Marek Vavruša's avatar
Marek Vavruša committed
30
The following is a list of software required to build Knot DNS Resolver from sources.
Marek Vavruša's avatar
Marek Vavruša committed
31

Marek Vavruša's avatar
Marek Vavruša committed
32
.. csv-table::
Marek Vavruša's avatar
Marek Vavruša committed
33
34
35
   :header: "Requirement", "Required by", "Notes"

   "`GNU Make`_ 3.80+", "*all*", "*(build only)*"
36
37
   "`pkg-config`_", "*all*", "*(build only)* [#]_"
   "C compiler", "*all*", "*(build only)* [#]_"
38
   "libknot_ 2.1+", "*all*", "Knot DNS library (requires autotools, GnuTLS and Jansson)."
39
   "LuaJIT_ 2.0+", "``daemon``", "Embedded scripting language."
40
   "libuv_ 1.7+", "``daemon``", "Multiplatform I/O and services (libuv_ 1.0 with limitations [#]_)."
Marek Vavruša's avatar
Marek Vavruša committed
41

Marek Vavruša's avatar
Marek Vavruša committed
42
There are also *optional* packages that enable specific functionality in Knot DNS Resolver, they are useful mainly for developers to build documentation and tests.
Marek Vavruša's avatar
Marek Vavruša committed
43

Marek Vavruša's avatar
Marek Vavruša committed
44
.. csv-table::
Marek Vavruša's avatar
Marek Vavruša committed
45
   :header: "Optional", "Needed for", "Notes"
Marek Vavruša's avatar
Marek Vavruša committed
46

47
   "`lua-http`_", "``modules/http``", "HTTP/2 client/server for Lua."
48
49
   "luasocket_", "``trust anchors, modules/stats``", "Sockets for Lua."
   "luasec_", "``trust anchors``", "TLS for Lua."
Marek Vavruša's avatar
Marek Vavruša committed
50
51
   "libmemcached_", "``modules/memcached``", "To build memcached backend module."
   "hiredis_", "``modules/redis``", "To build redis backend module."
52
   "geoip_", "``modules/tinyweb``", "To build a proof-of-concept web interface (needs Go as well)."
53
   "Go_ 1.5+", "``modules``", "Build modules written in Go."
Marek Vavruša's avatar
Marek Vavruša committed
54
   "cmocka_", "``unit tests``", "Unit testing framework."
55
56
   "Doxygen_", "``documentation``", "Generating API documentation."
   "Sphinx_", "``documentation``", "Building this HTML/PDF documentation."
57
   "breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
58
   "libsystemd_", "``daemon``", "Systemd socket activation support."
Marek Vavruša's avatar
Marek Vavruša committed
59

60
61
.. [#] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for dependency file generation. GCC, Clang and ICC are supported.
.. [#] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS`` to configure dependencies manually (i.e. ``libknot_CFLAGS`` and ``libknot_LIBS``).
62
.. [#] libuv 1.7 brings SO_REUSEPORT support that is needed for multiple forks. libuv < 1.7 can be still used, but only in single-process mode. Use :ref:`different method <daemon-reuseport>` for load balancing.
Marek Vavruša's avatar
Marek Vavruša committed
63

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
Packaged dependencies
~~~~~~~~~~~~~~~~~~~~~

Most of the dependencies can be resolved from packages, here's an overview for several platforms.

* **Debian** (since *sid*) - current stable doesn't have libknot and libuv, which must be installed from sources.

.. code-block:: bash

   sudo apt-get install pkg-config libknot-dev libuv1-dev libcmocka-dev libluajit-5.1-dev

* **Ubuntu** - unknown.
* **RHEL/CentOS** - unknown.
* **openSUSE** - there is an `experimental package <https://build.opensuse.org/package/show/server:dns/knot-resolver>`_.
* **RHEL** - unknown.
* **FreeBSD** - unknown.
* **NetBSD** - unknown.
* **OpenBSD** - unknown.
* **Mac OS X** - most of the dependencies can be found through `Homebrew <http://brew.sh/>`_, with the exception of libknot.

.. code-block:: bash

   brew install pkg-config libuv luajit cmocka

Marek Vavruša's avatar
Marek Vavruša committed
88
Building from sources 
89
---------------------
Marek Vavruša's avatar
Marek Vavruša committed
90

91
The Knot DNS Resolver depends on the the Knot DNS library, recent version of libuv_, and LuaJIT_.
Marek Vavruša's avatar
Marek Vavruša committed
92
93
94

.. code-block:: bash

95
   $ make info # See what's missing
Marek Vavruša's avatar
Marek Vavruša committed
96

97
98
99
100
101
When you have all the dependencies ready, you can build and install.

.. code-block:: bash

   $ make PREFIX="/usr/local"
Marek Vavrusa's avatar
Marek Vavrusa committed
102
   $ make install PREFIX="/usr/local"
103

104
.. note:: Always build with ``PREFIX`` if you want to install, as it is hardcoded in the executable for module search path. If you build the binary with ``-DNDEBUG``, verbose logging will be disabled as well.
105
106
107
108
109
110
111
112
113
114

Alternatively you can build only specific parts of the project, i.e. ``library``.

.. code-block:: bash

   $ make lib
   $ make lib-install

.. note:: Documentation is not built by default, run ``make doc`` to build it.

115
116
117
118
119
120
121
122
123
124
125
126
127
128
Building with security compiler flags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Knot DNS Resolver enables certain `security compile-time flags <https://wiki.debian.org/Hardening#Notes_on_Memory_Corruption_Mitigation_Methods>`_ that do not affect performance.
You can add more flags to the build by appending them to `CFLAGS` variable, e.g. ``make CFLAGS="-fstack-protector"``.

  .. csv-table::
   :header: "Method", "Status", "Notes"

   "-fstack-protector", "*disabled*", "(must be specifically enabled in CFLAGS)"
   "-D_FORTIFY_SOURCE=2", "**enabled**", ""
   "-pie", "**enabled**", "enables ASLR for kresd (disable with ``make HARDENING=no``)"
   "RELRO", "**enabled**", "full [#]_"

129
You can also disable linker hardening when it's unsupported with ``make HARDENING=no``.
130
131
132

.. [#] See `checksec.sh <http://www.trapkit.de/tools/checksec.html>`_

Marek Vavruša's avatar
Marek Vavruša committed
133
134
135
136
137
138
139
140
141
142
Building for packages
~~~~~~~~~~~~~~~~~~~~~

The build system supports both DESTDIR_ and `amalgamated builds <https://www.sqlite.org/amalgamation.html>`_.

.. code-block:: bash

   $ make install DESTDIR=/tmp/stage # Staged install
   $ make all install AMALG=yes # Amalgamated build

143
144
145
Amalgamated build assembles everything in one source file and compiles it. It is useful for packages, as the compiler sees the whole program and is able to produce a smaller and faster binary. On the other hand, it complicates debugging.

.. tip:: There is a template for service file and AppArmor profile to help you kickstart the package.
Marek Vavruša's avatar
Marek Vavruša committed
146

Marek Vavruša's avatar
Marek Vavruša committed
147
148
149
150
151
152
153
154
155
Default paths
~~~~~~~~~~~~~

The default installation follows FHS with several custom paths for configuration and modules.
All paths are prefixed with ``PREFIX`` variable by default if not specified otherwise.

  .. csv-table::
   :header: "Component", "Variable", "Default", "Notes"

156
   "library", "``LIBDIR``", "``$(PREFIX)/lib``", "pkg-config is auto-generated [#]_"
157
   "daemon",  "``SBINDIR``", "``$(PREFIX)/sbin``", ""
Marek Vavruša's avatar
Marek Vavruša committed
158
159
160
161
   "configuration", "``ETCDIR``", "``$(PREFIX)/etc/kresd``", "Configuration file, templates."
   "modules", "``MODULEDIR``", "``$(LIBDIR)/kdns_modules``", "[#]_"
   "work directory", "", "``$(PREFIX)/var/run/kresd``", "Run directory for daemon."

162
.. [#] The ``libkres.pc`` is installed in ``$(LIBDIR)/pkgconfig``.
Marek Vavruša's avatar
Marek Vavruša committed
163
164
165
166
.. [#] Users may install additional modules in ``~/.local/lib/kdns_modules`` or in the rundir of a specific instance.

.. note:: Each module is self-contained and may install additional bundled files within ``$(MODULEDIR)/$(modulename)``. These files should be read-only, non-executable.

167
168
169
170
171
172
173
174
175
176
177
178
Static or dynamic?
~~~~~~~~~~~~~~~~~~

By default the resolver library is built as a dynamic library with versioned ABI. You can revert to static build with ``BUILDMODE`` variable.

.. code-block:: bash

   $ make BUILDMODE=dynamic # Default, create dynamic library
   $ make BUILDMODE=static  # Create static library

When the library is linked statically, it usually produces a smaller binary. However linking it to various C modules might violate ODR and increase the size. 

179
180
Resolving dependencies
~~~~~~~~~~~~~~~~~~~~~~
181

182
183
The build system relies on `pkg-config`_ to find dependencies.
You can override it to force custom versions of the software by environment variables.
Marek Vavruša's avatar
Marek Vavruša committed
184
185
186

.. code-block:: bash

187
   $ make libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -ldnssec"
188

189
Optional dependencies may be disabled as well using ``HAS_x=yes|no`` variable.
190

191
.. code-block:: bash
192

193
   $ make HAS_go=no HAS_cmocka=no
194

195
196
197
.. warning:: If the dependencies lie outside of library search path, you need to add them somehow.
   Try ``LD_LIBRARY_PATH`` on Linux/BSD, and ``DYLD_FALLBACK_LIBRARY_PATH`` on OS X.
   Otherwise you need to add the locations to linker search path.
198

199
200
201
202
203
204
205
206
207
208
209
Several dependencies may not be in the packages yet, the script pulls and installs all dependencies in a chroot.
You can avoid rebuilding dependencies by specifying `BUILD_IGNORE` variable, see the Dockerfile_ for example.
Usually you only really need to rebuild libknot_.

.. code-block:: bash

   $ export FAKEROOT="${HOME}/.local"
   $ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
   $ export BUILD_IGNORE="..." # Ignore installed dependencies
   $ ./scripts/bootstrap-depends.sh ${FAKEROOT}

210
211
212
213
Building extras
~~~~~~~~~~~~~~~

The project can be built with code coverage tracking using the ``COVERAGE=1`` variable.
Marek Vavruša's avatar
Marek Vavruša committed
214

215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
Running unit and integration tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The unit tests require cmocka_ and are executed with ``make check``.

The integration tests use Deckard, the `DNS test harness <deckard>`_.

.. code-block:: bash

	$  make check-integration

Note that the daemon and modules must be installed first before running integration tests, the reason is that the daemon
is otherwise unable to find and load modules.

Read the `documentation <deckard_doc>`_ for more information about requirements, how to run it and extend it.

231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
Getting Docker image
--------------------

Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X).

.. code-block:: bash

   $ docker run cznic/knot-resolver

See the `Docker images`_ page for more information and options.
You can hack on the container by changing the container entrypoint to shell like:

.. code-block:: bash

   $ docker run -it --entrypoint=/bin/bash cznic/knot-resolver

.. tip:: You can build the Docker image yourself with ``docker build -t knot-resolver scripts``.

Vladimír Čunát's avatar
Vladimír Čunát committed
249
.. _Docker images: https://hub.docker.com/r/cznic/knot-resolver
Marek Vavruša's avatar
Marek Vavruša committed
250
251
252
253
254
.. _libuv: https://github.com/libuv/libuv
.. _MSVC: https://msdn.microsoft.com/en-us/vstudio/hh386302.aspx
.. _MinGW: http://www.mingw.org/
.. _Dockerfile: https://registry.hub.docker.com/u/cznic/knot-resolver/dockerfile/

255
256
.. _Lua: http://www.lua.org/about.html
.. _LuaJIT: http://luajit.org/luajit.html
257
.. _Go: https://golang.org
Marek Vavruša's avatar
Marek Vavruša committed
258
259
.. _libmemcached: http://libmemcached.org/libMemcached.html
.. _hiredis: https://github.com/redis/hiredis
260
.. _geoip: https://github.com/abh/geoip
261
262
263
.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/manual/index.html
.. _breathe: https://github.com/michaeljones/breathe
.. _Sphinx: http://sphinx-doc.org/
Marek Vavruša's avatar
Marek Vavruša committed
264
265
266
267
268
.. _GNU Make: http://www.gnu.org/software/make/
.. _pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
.. _libknot: https://gitlab.labs.nic.cz/labs/knot
.. _cmocka: https://cmocka.org/
.. _Python: https://www.python.org/
269
270
.. _luasec: https://luarocks.org/modules/luarocks/luasec
.. _luasocket: https://luarocks.org/modules/luarocks/luasocket
271
.. _lua-http: https://luarocks.org/modules/daurnimator/http
Marek Vavruša's avatar
Marek Vavruša committed
272

273
.. _boot2docker: http://boot2docker.io/
274
275
276

.. _deckard: https://gitlab.labs.nic.cz/knot/deckard
.. _deckard_doc: https://gitlab.labs.nic.cz/knot/resolver/blob/master/tests/README.rst
Marek Vavruša's avatar
Marek Vavruša committed
277

278
279
.. _libsystemd: https://www.freedesktop.org/wiki/Software/systemd/

Marek Vavruša's avatar
Marek Vavruša committed
280
.. _DESTDIR: https://www.gnu.org/prep/standards/html_node/DESTDIR.html