1 # Development <a id="development"></a>
3 This chapter provides hints on Icinga 2 debugging,
4 development, package builds and tests.
6 * [Debug Icinga 2](21-development.md#development-debug)
7 * [GDB Backtrace](21-development.md#development-debug-gdb-backtrace)
8 * [Core Dump](21-development.md#development-debug-core-dump)
9 * [Develop Icinga 2](21-development.md#development-develop)
10 * [Linux Dev Environment](21-development.md#development-linux-dev-env)
11 * [macOS Dev Environment](21-development.md#development-macos-dev-env)
12 * [Windows Dev Environment](21-development.md#development-windows-dev-env)
13 * [Package Builds](21-development.md#development-package-builds)
14 * [RPM](21-development.md#development-package-builds-rpms)
15 * [DEB](21-development.md#development-package-builds-deb)
16 * [Windows](21-development.md#development-package-builds-windows)
17 * [Advanced Tips](21-development.md#development-advanced)
18 * [Tests](21-development.md#development-tests)
21 ## Debug Icinga 2 <a id="development-debug"></a>
23 This chapter targets all users who have been asked by developers to provide
24 a stack trace or coredump if the application crashed. It is also useful
25 for developers working with different debuggers.
29 > This is intentionally mentioned before any development insights
30 > as debugging is a more frequent and commonly asked question.
32 ### Debug Requirements <a id="debug-requirements"></a>
34 Make sure that the debug symbols are available for Icinga 2.
35 The Icinga 2 packages provide a debug package which must be
36 installed separately for all involved binaries, like `icinga2-bin`
37 or `icinga2-ido-mysql`.
39 Distribution | Command
40 -------------------|------------------------------------------
41 Debian/Ubuntu | `apt-get install icinga2-dbg`
42 RHEL/CentOS | `yum install icinga2-debuginfo`
43 Fedora | `dnf install icinga2-debuginfo icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo`
44 SLES/openSUSE | `zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo`
46 Furthermore, you may also have to install debug symbols for Boost and your C++ library.
48 If you're building your own binaries, you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
49 build flag for debug builds.
52 ### GDB as Debugger <a id="development-debug-gdb"></a>
54 Install GDB in your development environment.
56 Distribution | Command
57 -------------------|------------------------------------------
58 Debian/Ubuntu | `apt-get install gdb`
59 RHEL/CentOS | `yum install gdb`
60 Fedora | `dnf install gdb`
61 SLES/openSUSE | `zypper install gdb`
63 #### GDB Run <a id="development-debug-gdb-run"></a>
65 Call GDB with the binary (`/usr/sbin/icinga2` is a wrapper script calling
66 `/usr/lib64/icinga2/sbin/icinga2` since 2.4) and all arguments and run it in foreground.
69 gdb --args /usr/lib64/icinga2/sbin/icinga2 daemon -x debug
72 The exact path to the Icinga 2 binary differs on each distribution. On Ubuntu
73 it is installed into `/usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2` on 64-bit systems
78 > If gdb tells you it's missing debug symbols, quit gdb and install
79 > them: `Missing separate debuginfos, use: debuginfo-install ...`
81 Run/restart the application.
87 Kill the running application.
93 Continue after breakpoint.
99 #### GDB Core Dump <a id="development-debug-gdb-coredump"></a>
101 Either attach to the running process using `gdb -p PID` or start
106 (gdb) generate-core-file
109 #### GDB Backtrace <a id="development-debug-gdb-backtrace"></a>
111 If Icinga 2 aborted its operation abnormally, generate a backtrace.
115 > Please install the [required debug symbols](21-development.md#debug-requirements)
116 > prior to generating a backtrace.
118 `thread apply all` is important here since this includes all running threads.
119 We need this information when e.g. debugging dead locks and hanging features.
123 (gdb) thread apply all bt full
126 If gdb stops at a SIGPIPE signal please disable the signal before
127 running Icinga 2. This isn't an error, but we need to workaround it.
130 (gdb) handle SIGPIPE nostop noprint pass
134 If you create a [new issue](https://github.com/Icinga/icinga2/issues),
135 make sure to attach as much detail as possible.
137 #### GDB Backtrace from Running Process <a id="development-debug-gdb-backtrace-running"></a>
139 If Icinga 2 is still running, generate a full backtrace from the running
140 process and store it into a new file (e.g. for debugging dead locks).
144 > Please install the [required debug symbols](21-development.md#debug-requirements)
145 > prior to generating a backtrace.
147 Icinga 2 runs with 2 processes: main and command executor, therefore generate two backtrace logs
148 and add them to the GitHub issue.
151 for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "thread apply all bt full" -ex "detach" -ex "q" > gdb_bt_${pid}_`date +%s`.log; done
154 #### GDB Thread List from Running Process <a id="development-debug-gdb-thread-list-running"></a>
156 Instead of a full backtrace, you sometimes just need a list of running threads.
159 for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "info threads" -ex "detach" -ex "q" > gdb_threads_${pid}_`date +%s`.log; done
162 #### GDB Backtrace Stepping <a id="development-debug-gdb-backtrace-stepping"></a>
164 Identifying the problem may require stepping into the backtrace, analysing
165 the current scope, attributes, and possible unmet requirements. `p` prints
166 the value of the selected variable or function call result.
172 (gdb) p checkable.px->m_Name
175 #### GDB Breakpoints <a id="development-debug-gdb-breakpoint"></a>
177 To set a breakpoint to a specific function call, or file specific line.
180 (gdb) b checkable.cpp:125
181 (gdb) b icinga::Checkable::SetEnablePerfdata
184 GDB will ask about loading the required symbols later, select `yes` instead
187 Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
195 In case you want to step into the next line of code, use `n`. If there is a
196 function call where you want to step into, use `s`.
204 If you want to delete all breakpoints, use `d` and select `yes`.
212 > When debugging exceptions, set your breakpoint like this: `b __cxa_throw`.
222 #11 0x00007ffff7cbf9ff in icinga::Utility::GlobRecursive(icinga::String const&, icinga::String const&, boost::function<void (icinga::String const&)> const&, int) (path=..., pattern=..., callback=..., type=1)
223 at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609
227 605 #endif /* _WIN32 */
229 607 std::sort(files.begin(), files.end());
230 608 BOOST_FOREACH(const String& cpath, files) {
234 612 std::sort(dirs.begin(), dirs.end());
235 613 BOOST_FOREACH(const String& cpath, dirs) {
237 $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615,
238 m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615,
239 m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615,
240 m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615,
241 m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615,
242 m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}
246 ### Core Dump <a id="development-debug-core-dump"></a>
248 When the Icinga 2 daemon crashes with a `SIGSEGV` signal
249 a core dump file should be written. This will help
250 developers to analyze and fix the problem.
252 #### Core Dump File Size Limit <a id="development-debug-core-dump-limit"></a>
254 This requires setting the core dump file size to `unlimited`.
260 systemctl edit icinga2.service
266 systemctl daemon-reload
268 systemctl restart icinga2
274 vim /etc/init.d/icinga2
278 service icinga2 restart
283 Verify that the Icinga 2 process core file size limit is set to `unlimited`.
286 for pid in $(pidof icinga2); do cat /proc/$pid/limits; done
289 Max core file size unlimited unlimited bytes
293 #### Core Dump Kernel Format <a id="development-debug-core-dump-format"></a>
295 The Icinga 2 daemon runs with the SUID bit set. Therefore you need
296 to explicitly enable core dumps for SUID on Linux.
299 sysctl -w fs.suid_dumpable=2
302 Adjust the coredump kernel format and file location on Linux:
305 sysctl -w kernel.core_pattern=/var/lib/cores/core.%e.%p
307 install -m 1777 -d /var/lib/cores
313 sysctl -w kern.corefile=/cores/core.%P
318 #### Core Dump Analysis <a id="development-debug-core-dump-analysis"></a>
320 Once Icinga 2 crashes again a new coredump file will be written. Please
321 attach this file to your bug report in addition to the general details.
323 Simple test case for a `SIGSEGV` simulation with `sleep`:
330 gdb `which sleep` /var/lib/cores/core.sleep.<PID>
332 rm /var/lib/cores/core.sleep.*
338 gdb /usr/lib64/icinga2/sbin/icinga2 core.icinga2.<PID>
342 ### LLDB as Debugger <a id="development-debug-lldb"></a>
344 LLDB is available on macOS with the Xcode command line tools.
347 $ xcode-select --install
350 In order to run Icinga 2 with LLDB you need to pass the binary as argument.
353 lldb -- /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
360 > b icinga::Checkable::ProcessCheckResult
393 Up/down in stacktrace:
402 ## Develop Icinga 2 <a id="development-develop"></a>
404 Icinga 2 can be built on many platforms such as Linux, Unix and Windows.
405 There are limitations in terms of support, e.g. Windows is only supported for agents,
406 not a full-featured master or satellite.
408 Before you start with actual development, there is a couple of pre-requisites.
410 ### Choose your Editor <a id="development-develop-choose-editor"></a>
412 Icinga 2 can be developed with your favorite editor. Icinga developers prefer
416 - CLion (macOS, Linux)
417 - MS Visual Studio (Windows)
420 Editors differ on the functionality. The more helpers you get for C++ development,
421 the faster your development workflow will be.
424 #### Whitespace Cleanup <a id="development-develop-choose-editor-whitespaces"></a>
426 Patches must be cleaned up and follow the indent style (tabs instead of spaces).
427 You should also remove any training whitespaces.
429 `git diff` allows to highlight such.
435 whitespace = red reverse
437 whitespace=fix,-indent-with-non-tab,trailing-space,cr-at-eol
440 `vim` also can match these and visually alert you to remove them.
445 highlight ExtraWhitespace ctermbg=red guibg=red
446 match ExtraWhitespace /\s\+$/
447 autocmd BufWinEnter * match ExtraWhitespace /\s\+$/
448 autocmd InsertEnter * match ExtraWhitespace /\s\+\%#\@<!$/
449 autocmd InsertLeave * match ExtraWhitespace /\s\+$/
450 autocmd BufWinLeave * call clearmatches()
453 ### Get to know the architecture <a id="development-develop-get-to-know-the-architecture"></a>
455 Icinga 2 can run standalone or in distributed environments. It contains a whole lot
456 more than a simple check execution engine.
458 Read more about it in the [Technical Concepts](19-technical-concepts.md#technical-concepts) chapter.
460 ### Get to know the code <a id="development-develop-get-to-know-the-code"></a>
462 First off, you really need to know C++ and portions of C++11 and the boost libraries.
463 Best is to start with a book or online tutorial to get into the basics.
464 Icinga developers gained their knowledge through studies, training and self-teaching
465 code by trying it out and asking senior developers for guidance.
467 Here's a few books we can recommend:
469 * [Accelerated C++: Practical Programming by Example](https://www.amazon.com/Accelerated-C-Practical-Programming-Example/dp/020170353X) (Andrew Koenig, Barbara E. Moo)
470 * [Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) (Scott Meyers)
471 * [Boost C++ Application Development Cookbook - Second Edition: Recipes to simplify your application development](https://www.amazon.com/dp/1787282244/ref=cm_sw_em_r_mt_dp_U_dN1OCbERS00EQ) (Antony Polukhin)
472 * [Der C++ Programmierer](https://www.amazon.de/Programmierer-lernen-Professionell-anwenden-L%C3%B6sungen/dp/3446416447), German (Ulrich Breymann)
473 * [C++11 programmieren](https://www.amazon.de/gp/product/3836217325/), German (Torsten T. Will)
475 In addition, it is a good bet to also know SQL when diving into backend development.
477 * [SQL Performance Explained](https://www.amazon.de/gp/product/3950307826/) (Markus Winand)
479 Last but not least, if you are developing on Windows, get to know the internals about services and the Win32 API.
482 ### Design Patterns <a id="development-develop-design-patterns"></a>
484 Icinga 2 heavily relies on object-oriented programming and encapsulates common
485 functionality into classes and objects. It also uses modern programming techniques
486 to e.g. work with shared pointer memory management.
488 Icinga 2 consists of libraries bundled into the main binary. Therefore you'll
489 find many code parts in the `lib/` directory wheras the actual application is
490 built from `icinga-app/`. Accompanied with Icinga 2, there's the Windows plugins
491 which are standalone and compiled from `plugins/`.
493 Library | Description
494 ---------------|------------------------------------
495 base | Objects, values, types, streams, tockets, TLS, utilities, etc.
496 config | Configuration compiler, expressions, etc.
497 cli | CLI (sub) commands and helpers.
498 icinga | Icinga specific objects and event handling.
499 remote | Cluster and HTTP client/server and REST API related code.
500 checker | Checker feature, check scheduler.
501 notification | Notification feature, notification scheduler.
502 methods | Command execution methods, plugins and built-in checks.
503 perfdata | Performance data related, including Graphite, Elastic, etc.
504 db\_ido | IDO database abstraction layer.
505 db\_ido\_mysql | IDO database driver for MySQL.
506 db\_ido\_pgsql | IDO database driver for PgSQL.
507 mysql\_shin | Library stub for linking against the MySQL client libraries.
508 pgsql\_shim | Library stub for linking against the PgSQL client libraries.
510 #### Class Compiler <a id="development-develop-design-patterns-class-compiler"></a>
512 Another thing you will recognize are the `.ti` files which are compiled
513 by our own class compiler into actual source code. The meta language allows
514 developers to easily add object attributes and specify their behaviour.
516 Some object attributes need to be stored over restarts in the state file
517 and therefore have the `state` attribute set. Others are treated as `config`
518 attribute and automatically get configuration validation functions created.
519 Hidden or read-only REST API attributes are marked with `no_user_view` and
522 The most beneficial thing are getters and setters being generated. The actual object
523 inherits from `ObjectImpl<TYPE>` and therefore gets them "for free".
528 vim lib/perfdata/gelfwriter.ti
532 vim lib/perfdata/gelfwriter.cpp
534 if (GetEnableTls()) {
537 The logic is hidden in `tools/mkclass/` in case you want to learn more about it.
538 The first steps during CMake & make also tell you about code generation.
541 ### Builds: CMake <a id="development-develop-builds-cmake"></a>
543 In its early development stages in 2012, Icinga 2 was built with autoconf/automake
544 and separate Windows project files. We've found this very fragile, and have changed
545 this into CMake as our build tool.
547 The most common benefits:
549 * Everything is described in CMakeLists.txt in each directory
550 * CMake only needs to know that a sub directory needs to be included.
551 * The global CMakeLists.txt acts as main entry point for requirement checks and library/header includes.
552 * Separate binary build directories, the actual source tree stays clean.
553 * CMake automatically generates a Visual Studio project file `icinga2.sln` on Windows.
555 ### Builds: Unity Builds <a id="development-develop-builds-unity-builds"></a>
557 Another thing you should be aware of: Unity builds on and off.
559 Typically, we already use caching mechanisms to reduce recompile time with ccache.
560 For release builds, there's always a new build needed as the difference is huge compared
561 to a previous (major) release.
563 Therefore we've invented the Unity builds, which basically concatenates all source files
564 into one big library source code file. The compiler then doesn't need to load the many small
565 files but compiles and links this huge one.
567 Unity builds require more memory which is why you should disable them for development
568 builds in small sized VMs (Linux, Windows) and also Docker containers.
570 There's a couple of header files which are included everywhere. If you touch/edit them,
571 the cache is invalidated and you need to recompile a lot more files then. `base/utility.hpp`
572 and `remote/zone.hpp` are good candidates for this.
575 ### Linux Dev Environment <a id="development-linux-dev-env"></a>
577 Based on CentOS 7, we have an early draft available inside the Icinga Vagrant boxes:
578 [centos7-dev](https://github.com/Icinga/icinga-vagrant/tree/master/centos7-dev).
580 If you're compiling Icinga 2 natively without any virtualization layer in between,
581 this usually is faster. This is also the reason why developers on macOS prefer native builds
582 over Linux or Windows VMs. Don't forget to test the actual code on Linux later! Socket specific
583 stuff like `epoll` is not available on Unix kernels.
585 Depending on your workstation and environment, you may either develop and run locally,
586 use a container deployment pipeline or put everything in a high end resource remote VM.
588 Fork https://github.com/Icinga/icinga2 into your own repository, e.g. `https://github.com/dnsmichi/icinga2`.
590 Create two build directories for different binary builds.
592 * `debug` contains the debug build binaries. They contain more debug information and run tremendously slower than release builds from packages. Don't use them for benchmarks.
593 * `release` contains the release build binaries, as you would install them on a live system. This helps comparing specific scenarios for race conditions and more.
596 mkdir -p release debug
599 Proceed with the specific distribution examples below.
601 * [CentOS 7](21-development.md#development-linux-dev-env-centos)
602 * [Debian 9](21-development.md#development-linux-dev-env-debian)
605 #### CentOS 7 <a id="development-linux-dev-env-centos"></a>
608 yum -y install gdb git bash-completion htop rpmdevtools \
609 ccache cmake make gcc-c++ flex bison \
610 openssl-devel boost-devel systemd-devel mysql-devel \
611 postgresql-devel libedit-devel libstdc++-devel
615 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
617 ln -s /bin/ccache /usr/local/bin/gcc
618 ln -s /bin/ccache /usr/local/bin/g++
620 git clone https://github.com/icinga/icinga2.git && cd icinga2
624 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
626 make -j2 install -C debug
631 chown -R icinga:icinga /usr/local/icinga2/var/
633 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
634 /usr/local/icinga2/sbin/icinga2 api setup
635 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
637 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
640 #### Debian 9 <a id="development-linux-dev-env-debian"></a>
643 apt-get -y install gdb vim git cmake make ccache build-essential libssl-dev libboost-all-dev bison flex default-libmysqlclient-dev libpq-dev libedit-dev monitoring-plugins
645 ln -s /usr/bin/ccache /usr/local/bin/gcc
646 ln -s /usr/bin/ccache /usr/local/bin/g++
650 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
652 git clone https://github.com/icinga/icinga2.git && cd icinga2
656 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
658 make -j2 install -C debug
663 chown -R icinga:icinga /usr/local/icinga2/var/
665 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
666 /usr/local/icinga2/sbin/icinga2 api setup
667 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
669 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
674 ### macOS Dev Environment <a id="development-macos-dev-env"></a>
676 It is advised to use Homebrew to install required build dependencies.
677 Macports have been reported to work as well, typically you'll get more help
678 with Homebrew from Icinga developers.
680 The idea is to run Icinga with the current user, avoiding root permissions.
684 OpenSSL 1.0.x doesn't build anymore, so we're explicitly using 1.1.x here.
687 brew install ccache boost cmake bison flex openssl@1.1 mysql-connector-c++ postgresql libpq
693 sudo mkdir /opt/ccache
695 sudo ln -s `which ccache` /opt/ccache/clang
696 sudo ln -s `which ccache` /opt/ccache/clang++
698 vim $HOME/.bash_profile
700 # ccache is managed with symlinks to avoid collision with cgo
701 export PATH="/opt/ccache:$PATH"
703 source $HOME/.bash_profile
708 Icinga is built as release (optimized build for packages) and debug (more symbols and details for debugging). Debug builds
709 typically run slower than release builds and must not be used for performance benchmarks.
712 mkdir -p release debug
715 cmake -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DOPENSSL_INCLUDE_DIR=/usr/local/opt/openssl@1.1/include -DOPENSSL_SSL_LIBRARY=/usr/local/opt/openssl@1.1/lib/libssl.dylib -DOPENSSL_CRYPTO_LIBRARY=/usr/local/opt/openssl@1.1/lib/libcrypto.dylib -DICINGA2_PLUGINDIR=/usr/local/sbin ..
719 make -j4 install -C debug
724 This is derived from [dnsmichi's flavour](https://github.com/dnsmichi/dotfiles) and not generally best practice.
727 vim $HOME/.bash_profile
729 export I2_GENERIC="-DCMAKE_INSTALL_PREFIX=/usr/local/icinga/icinga2 -DICINGA2_USER=`id -u -n` -DICINGA2_GROUP=`id -g -n` -DOPENSSL_INCLUDE_DIR=/usr/local/opt/openssl@1.1/include -DOPENSSL_SSL_LIBRARY=/usr/local/opt/openssl@1.1/lib/libssl.dylib -DOPENSSL_CRYPTO_LIBRARY=/usr/local/opt/openssl@1.1/lib/libcrypto.dylib -DICINGA2_PLUGINDIR=/usr/local/sbin -DICINGA2_WITH_PGSQL=OFF"
731 export I2_DEBUG="-DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF $I2_GENERIC"
732 export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DICINGA2_UNITY_BUILD=ON $I2_GENERIC"
734 alias i2_debug="mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j4; make -j4 install; cd .."
735 alias i2_release="mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j4; make -j4 install; cd .."
737 export PATH=/usr/local/icinga/icinga2/sbin/:$PATH
738 test -f /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2 && source /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2
741 source $HOME/.bash_profile
747 chown -R icinga:icinga /usr/local/icinga2
748 chown -R icinga:_www /usr/local/icinga2/var/run/icinga2/cmd
756 brew install monitoring-plugins
758 sudo vim /usr/local/icinga2/etc/icinga2/constants.conf
759 const PluginDir = "/usr/local/sbin"
766 brew services start redis
769 #### Databases: MariaDB
773 mkdir -p /usr/local/etc/my.cnf.d
774 brew services start mariadb
776 mysql_secure_installation
784 password = supersecurerootpassword
787 ln -s /Users/michi/.my.cnf $HOME/.my.cnf
792 mysql -e 'create database icinga;'
793 mysql -e "grant all on icinga.* to 'icinga'@'localhost' identified by 'icinga';"
794 mysql icinga < $HOME/dev/icinga/icinga2/lib/db_ido_mysql/schema/mysql.sql
801 cd /usr/local/icinga/icinga2/var/lib/icinga2/certs
802 HOST_NAME=mbpmif.int.netways.de
803 icinga2 pki new-cert --cn ${HOST_NAME} --csr ${HOST_NAME}.csr --key ${HOST_NAME}.key
804 icinga2 pki sign-csr --csr ${HOST_NAME}.csr --cert ${HOST_NAME}.crt
805 echo "const NodeName = \"${HOST_NAME}\"" >> /usr/local/icinga/icinga2/etc/icinga2/constants.conf
811 ### Windows Dev Environment <a id="development-windows-dev-env"></a>
813 The following sections explain how to setup the required build tools
814 and how to run and debug the code.
818 Open an administrative command prompt (Win key, type “cmd”, right-click and “run as administrator”) and paste the following instructions:
821 @powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
826 Thanks to Microsoft they’ll now provide their Professional Edition of Visual Studio 2017
827 as community version, free for use for open source projects such as Icinga.
828 The installation requires ~9GB disk space. [Download](https://www.visualstudio.com/downloads/)
829 the web installer and start the installation.
831 You need a free Microsoft account to download and also store your preferences.
833 Choose these individual components on Visual Studio 2017:
836 * .NET Framework 3.5 development tools
837 * .NET Framework 4.6.1 SDK
838 * .NET Framework 4.6.1 targeting pack
841 * Static analysis tools
842 * Compilers, build tools and runtimes
843 * C# and Visual Basic Roslyn compilers
845 * VC++ 2017 v141 toolset (x86_64)
846 * Debugging and testing
847 * C++ profiling tools
848 * Just-in-Time debugger
849 * Development activities
850 * Visual Studio C++ core features
852 * Graphics debugger and GPU profiler for DirectX (required by C++ profiling tools)
853 * SDKs, libraries and frameworks
854 * Graphics Tools Windows 8.1 SDK (required by C++ profiling tools)
855 * Windows 10 SDK **10.0.10240.0 - exactly this version**
857 * Windows Universal C Runtime
859 * GitHub Extension for Visual Studio
862 After a while, Visual Studio will be ready.
864 #### .NET Framework 3.5
866 Windows 10 has .NET Framework >= 4.6 installed by default. The Icinga Agent Wizard
867 is built on .NET Framework 2.0 which is not included in .NET Framework 4.6.
869 Windows 10 provides .NET Framework 3.5 which includes .NET Framework 2.0.
871 Navigate into `Control Panel` -> `Programs` -> `Turn Windows features on or off`.
872 Select `.NET Framework 3.5 (includes .NET 2.0 and 3.0)` and wait until the installation process
877 Install it using [chocolatey](https://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html):
880 choco install -y winflexbison
883 Chocolatey installs these tools into the hidden directory `C:\ProgramData\chocolatey\lib\winflexbison\tools`.
887 Icinga 2 requires the OpenSSL library. [Download](http://slproweb.com/products/Win32OpenSSL.html)
888 and install it into the default path.
890 Once asked for `Copy OpenSSLs DLLs to` select `The Windows system directory`. That way CMake/Visual Studio
891 will automatically detect them for builds and packaging.
895 > We cannot use the chocolatey package as this one does not provide any development headers.
897 > Choose 1.1.1 LTS from manual downloads for best compatibility.
901 In order to use the boost development header and library files you need to [download](http://www.boost.org/users/download/)
902 Boost and then extract it to e.g. `C:\boost_1_69_0`.
906 > Just use `C:`, the zip file already contains the sub folder. Extraction takes a while,
907 > the archive contains more than 70k files.
909 In order to integrate Boost into Visual Studio 2017, open the `Developer Command Prompt` from the start menu,
910 and navigate to `C:\boost_1_69_0`.
912 Execute `bootstrap.bat` first.
919 Once finished, specify the required `toolset` to compile boost against Visual Studio.
920 This takes quite some time in a Windows VM. Boost Context uses Assembler code,
921 which isn't treated as exception safe by the VS compiler. Therefore set the
922 additional compilation flag according to [this entry](https://lists.boost.org/Archives/boost/2015/08/224570.php).
925 b2 --toolset=msvc-14.1 asmflags=\safeseh
928 ![Windows Boost Build in VS2017 Development Console](images/development/windows_boost_build_dev_cmd.png)
932 TortoiseGit provides a graphical integration into the Windows explorer. This makes it easier to checkout, commit
935 [Download](https://tortoisegit.org/download/) TortoiseGit on your system.
937 In order to clone via Git SSH you also need to create a new directory called `.ssh`
938 inside your user's home directory.
939 Therefore open a command prompt (win key, type `cmd`, enter) and run `mkdir .ssh`.
940 Add your `id_rsa` private key and `id_rsa.pub` public key files into that directory.
942 Start the setup routine and choose `OpenSSH` as default secure transport when asked.
944 Open a Windows Explorer window and navigate into
947 cd %HOMEPATH%\source\repos
950 Right click and select `Git Clone` from the context menu.
952 Use `ssh://git@github.com/icinga/icinga2.git` for SSH clones, `https://github.com/icinga/icinga2.git` otherwise.
956 Icinga 2 uses CMake to manage the build environment. You can generate the Visual Studio project files
957 using CMake. [Download](https://cmake.org/download/) and install CMake. Select to add it to PATH for all users
962 > In order to properly detect the Boost libraries, install the CMake 3.14+.
964 Once setup is completed, open a command prompt and navigate to
967 cd %HOMEPATH%\source\repos
970 Run CMake with the following command. This generates a new Visual Studio project file called `icinga2.sln`.
972 You need to specify the previously installed component paths:
974 Variable | Value | Description
975 ----------------------|----------------------------------------------------------------------|-------------------------------------------------------
976 `BOOST_ROOT` | `C:\boost_1_69_0` | Root path where you've extracted and compiled Boost.
977 `BOOST_LIBRARYDIR` | `C:\boost_1_69_0\stage` | Path to the static compiled Boost libraries, directory must contain `lib`.
978 `BISON_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe` | Path to the Bison executable.
979 `FLEX_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe` | Path to the Flex executable.
980 `ICINGA2_WITH_MYSQL` | OFF | Requires extra setup for MySQL if set to `ON`. Not supported for client setups.
981 `ICINGA2_WITH_PGSQL` | OFF | Requires extra setup for PgSQL if set to `ON`. Not supported for client setups.
982 `ICINGA2_UNITY_BUILD` | OFF | Disable unity builds for development environments.
984 Tip: If you have previously opened a terminal, run `refreshenv` to re-read updated PATH variables.
987 cmake . -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Debug -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
990 Best is write a small batch/Powershell script which just executes these lines.
1000 cmake . -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Debug -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
1002 cmake --build . --target PACKAGE --config Debug
1008 #### Icinga 2 in Visual Studio
1013 cd %HOMEPATH%\source\repos\icinga2
1016 Open `icinga2.sln`. Log into Visual Studio when asked.
1018 On the right panel, select to build the `Bin/icinga-app` solution.
1020 The executable binaries are located in `Bin\Release\Debug` in your `icinga2`
1023 Navigate there and run `icinga2.exe --version`.
1026 cd %HOMEPATH%\source\repos\icinga2\Bin\Release\Debug
1027 icinga2.exe --version
1031 #### Release Package
1033 CMake uses CPack and NSIS to create the setup executable including all binaries and libraries
1034 in addition to setup dialogues and configuration. Therefore we’ll need to install [NSIS](http://nsis.sourceforge.net/Download)
1037 We also need to install the Windows Installer XML (WIX) toolset.
1040 choco install -y wixtoolset
1043 Once completed open an administrative shell and navigate to your Visual Studio project.
1045 Let CMake to build a release package.
1048 cd %HOMEPATH%\source\repos\icinga2
1049 cmake --build debug --target PACKAGE --config Release
1052 Note: This will still use the debug builds. A yet more clean approach
1053 is to run CMake with changed release parameters beforehand and then
1054 re-run the release package builder.
1057 cd %HOMEPATH%\source\repos\icinga2
1061 cmake .. -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Release -DBOOST_ROOT=C:\boost_1_69_0 -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
1064 cmake --build release --target PACKAGE --config Release
1067 Again, put these lines into a batch/Powershell script and execute that.
1078 ; set gen=Visual Studio 15 2017 Win64
1079 set gen=Visual Studio 15 2017
1081 cmake .. -G "%gen%" -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=ON
1084 cmake --build release --target PACKAGE --config Release
1090 ### Embedded Dev Env: Pi <a id="development-embedded-dev-env"></a>
1094 > This isn't officially supported yet, just a few hints how you can do it yourself.
1096 The following examples source from armhf on Raspberry Pi.
1101 apt install -y ccache
1103 /usr/sbin/update-ccache-symlinks
1105 echo 'export PATH="/usr/lib/ccache:$PATH"' | tee -a ~/.bashrc
1107 source ~/.bashrc && echo $PATH
1112 Copy the icinga2 source code into `$HOME/icinga2`. Clone the `deb-icinga2` repository into `debian/`.
1115 git clone https://github.com/Icinga/icinga2 $HOME/icinga2
1116 git clone https://github.com/Icinga/deb-icinga2 $HOME/icinga2/debian
1119 Then build a Debian package and install it like normal.
1121 dpkg-buildpackage -uc -us
1124 ## Package Builds <a id="development-package-builds"></a>
1126 This documentation is explicitly meant for packagers and the Icinga
1127 build infrastructure.
1129 The following requirements need to be fulfilled in order to build the
1130 Icinga application using a dist tarball (including notes for distributions):
1133 * GNU make (make) or ninja-build
1134 * C++ compiler which supports C++11
1135 * RHEL/Fedora/SUSE: gcc-c++ >= 4.7 (extra Developer Tools on RHEL5/6 see below)
1136 * Debian/Ubuntu: build-essential
1137 * Alpine: build-base
1138 * you can also use clang++
1140 * OpenSSL library and header files >= 1.0.1
1141 * RHEL/Fedora: openssl-devel
1142 * SUSE: libopenssl-devel (for SLES 11: libopenssl1-devel)
1143 * Debian/Ubuntu: libssl-dev
1144 * Alpine: libressl-dev
1145 * Boost library and header files >= 1.66.0
1146 * RHEL/Fedora: boost166-devel
1147 * Debian/Ubuntu: libboost-all-dev
1150 * GNU flex (flex) >= 2.5.35
1152 * Only required when using systemd
1153 * Debian/Ubuntu: libsystemd-dev
1154 * RHEL/Fedora: systemd-devel
1156 ### Optional features <a id="development-package-builds-optional-features"></a>
1158 * MySQL (disable with CMake variable `ICINGA2_WITH_MYSQL` to `OFF`)
1159 * RHEL/Fedora: mysql-devel
1160 * SUSE: libmysqlclient-devel
1161 * Debian/Ubuntu: default-libmysqlclient-dev | libmysqlclient-dev
1162 * Alpine: mariadb-dev
1163 * PostgreSQL (disable with CMake variable `ICINGA2_WITH_PGSQL` to `OFF`)
1164 * RHEL/Fedora: postgresql-devel
1165 * Debian/Ubuntu: libpq-dev
1166 * postgresql-dev on Alpine
1167 * libedit (CLI console)
1168 * RHEL/Fedora: libedit-devel on CentOS (RHEL requires rhel-7-server-optional-rpms)
1169 * Debian/Ubuntu/Alpine: libedit-dev
1170 * Termcap (only required if libedit doesn't already link against termcap/ncurses)
1171 * RHEL/Fedora: libtermcap-devel
1172 * Debian/Ubuntu: (not necessary)
1174 ### Special requirements <a id="development-package-builds-special-requirements"></a>
1176 **FreeBSD**: libexecinfo (automatically used when Icinga 2 is installed via port or package)
1178 **RHEL6** and **SLES11**: Requires a newer boost version which is available on packages.icinga.com
1179 with a version suffixed name.
1181 ### Runtime user environment <a id="development-package-builds-runtime-user-env"></a>
1183 By default Icinga will run as user `icinga` and group `icinga`. Additionally the
1184 external command pipe and livestatus features require a dedicated command group
1185 `icingacmd`. You can choose your own user/group names and pass them to CMake
1186 using the `ICINGA2_USER`, `ICINGA2_GROUP` and `ICINGA2_COMMAND_GROUP` variables.
1190 # groupadd icingacmd
1191 # useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
1194 On Alpine (which uses ash busybox) you can run:
1197 # addgroup -S icinga
1198 # addgroup -S icingacmd
1199 # adduser -S -D -H -h /var/spool/icinga2 -s /sbin/nologin -G icinga -g icinga icinga
1200 # adduser icinga icingacmd
1203 Add the web server user to the icingacmd group in order to grant it write
1204 permissions to the external command pipe and livestatus socket:
1207 # usermod -a -G icingacmd www-data
1210 Make sure to replace "www-data" with the name of the user your web server
1213 ### Building Icinga 2: Example <a id="development-package-builds-example"></a>
1215 Once you have installed all the necessary build requirements you can build
1216 Icinga 2 using the following commands:
1219 $ mkdir release && cd release
1223 $ make install -C release
1226 You can specify an alternative installation prefix using `-DCMAKE_INSTALL_PREFIX`:
1229 $ cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2
1232 ### CMake Variables <a id="development-package-builds-cmake-variables"></a>
1234 In addition to `CMAKE_INSTALL_PREFIX` here are most of the supported Icinga-specific cmake variables.
1236 For all variables regarding defaults paths on in CMake, see
1237 [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html).
1239 Also see `CMakeLists.txt` for details.
1241 #### System Environment
1243 * `CMAKE_INSTALL_SYSCONFDIR`: The configuration directory; defaults to `CMAKE_INSTALL_PREFIX/etc`
1244 * `CMAKE_INSTALL_LOCALSTATEDIR`: The state directory; defaults to `CMAKE_INSTALL_PREFIX/var`
1245 * `ICINGA2_CONFIGDIR`: Main config directory; defaults to `CMAKE_INSTALL_SYSCONFDIR/icinga2` usually `/etc/icinga2`
1246 * `ICINGA2_CACHEDIR`: Directory for cache files; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/cache/icinga2` usually `/var/cache/icinga2`
1247 * `ICINGA2_DATADIR`: Data directory for the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/lib/icinga2` usually `/var/lib/icinga2`
1248 * `ICINGA2_LOGDIR`: Logfiles of the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/log/icinga2 usually `/var/log/icinga2`
1249 * `ICINGA2_SPOOLDIR`: Spooling directory ; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/spool/icinga2` usually `/var/spool/icinga2`
1250 * `ICINGA2_INITRUNDIR`: Runtime data for the init system; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/run/icinga2` usually `/run/icinga2`
1251 * `ICINGA2_GIT_VERSION_INFO`: Whether to use Git to determine the version number; defaults to `ON`
1252 * `ICINGA2_USER`: The user Icinga 2 should run as; defaults to `icinga`
1253 * `ICINGA2_GROUP`: The group Icinga 2 should run as; defaults to `icinga`
1254 * `ICINGA2_COMMAND_GROUP`: The command group Icinga 2 should use; defaults to `icingacmd`
1255 * `ICINGA2_SYSCONFIGFILE`: Where to put the config file the initscript/systemd pulls it's dirs from;
1256 * defaults to `CMAKE_INSTALL_PREFIX/etc/sysconfig/icinga2`
1257 * `ICINGA2_PLUGINDIR`: The path for the Monitoring Plugins project binaries; defaults to `/usr/lib/nagios/plugins`
1259 #### Build Optimization
1261 * `ICINGA2_UNITY_BUILD`: Whether to perform a unity build; defaults to `ON`. Note: This requires additional memory and is not advised for building VMs, Docker for Mac and embedded hardware.
1262 * `ICINGA2_LTO_BUILD`: Whether to use link time optimization (LTO); defaults to `OFF`
1266 * `USE_SYSTEMD=ON|OFF`: Use systemd or a classic SysV initscript; defaults to `OFF`
1267 * `INSTALL_SYSTEMD_SERVICE_AND_INITSCRIPT=ON|OFF` Force install both the systemd service definition file
1268 and the SysV initscript in parallel, regardless of how `USE_SYSTEMD` is set.
1269 Only use this for special packaging purposes and if you know what you are doing.
1274 * `ICINGA2_WITH_CHECKER`: Determines whether the checker module is built; defaults to `ON`
1275 * `ICINGA2_WITH_COMPAT`: Determines whether the compat module is built; defaults to `ON`
1276 * `ICINGA2_WITH_LIVESTATUS`: Determines whether the Livestatus module is built; defaults to `ON`
1277 * `ICINGA2_WITH_NOTIFICATION`: Determines whether the notification module is built; defaults to `ON`
1278 * `ICINGA2_WITH_PERFDATA`: Determines whether the perfdata module is built; defaults to `ON`
1279 * `ICINGA2_WITH_TESTS`: Determines whether the unit tests are built; defaults to `ON`
1281 #### MySQL or MariaDB
1283 The following settings can be tuned for the MySQL / MariaDB IDO feature.
1285 * `ICINGA2_WITH_MYSQL`: Determines whether the MySQL IDO module is built; defaults to `ON`
1286 * `MYSQL_CLIENT_LIBS`: Client implementation used (mysqlclient / mariadbclient); defaults searches for `mysqlclient` and `mariadbclient`
1287 * `MYSQL_INCLUDE_DIR`: Directory containing include files for the mysqlclient; default empty -
1288 checking multiple paths like `/usr/include/mysql`
1290 See [FindMySQL.cmake](https://github.com/Icinga/icinga2/blob/master/third-party/cmake/FindMySQL.cmake)
1291 for implementation details.
1295 The following settings can be tuned for the PostgreSQL IDO feature.
1297 * `ICINGA2_WITH_PGSQL`: Determines whether the PostgreSQL IDO module is built; defaults to `ON`
1298 * `PostgreSQL_INCLUDE_DIR`: Top-level directory containing the PostgreSQL include directories
1299 * `PostgreSQL_LIBRARY`: File path to PostgreSQL library : libpq.so (or libpq.so.[ver] file)
1301 See [FindPostgreSQL.cmake](https://github.com/Icinga/icinga2/blob/master/third-party/cmake/FindPostgreSQL.cmake)
1302 for implementation details.
1304 #### Version detection
1306 CMake determines the Icinga 2 version number using `git describe` if the
1307 source directory is contained in a Git repository. Otherwise the version number
1308 is extracted from the [VERSION](VERSION) file. This behavior can be
1309 overridden by creating a file called `icinga-version.h.force` in the source
1310 directory. Alternatively the `-DICINGA2_GIT_VERSION_INFO=OFF` option for CMake
1311 can be used to disable the usage of `git describe`.
1314 ### Building RPMs <a id="development-package-builds-rpms"></a>
1316 #### Build Environment on RHEL, CentOS, Fedora, Amazon Linux
1318 Setup your build environment:
1321 yum -y install rpmdevtools
1324 #### Build Environment on SuSE/SLES
1329 zypper addrepo http://download.opensuse.org/repositories/devel:tools/SLE_12_SP4/devel:tools.repo
1331 zypper install rpmdevtools spectool
1337 zypper addrepo http://download.opensuse.org/repositories/devel:tools/openSUSE_Leap_15.0/devel:tools.repo
1339 zypper install rpmdevtools spectool
1342 #### Package Builds <a id="development-package-builds-rpms-package-builds"></a>
1344 Prepare the rpmbuild directory tree:
1354 curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o $HOME/rpmbuild/SPECS/icinga2.spec
1359 > The above command builds snapshot packages. Change to the `release` branch
1360 > for release package builds.
1362 Copy the tarball to `rpmbuild/SOURCES` e.g. by using the `spectool` binary
1363 provided with `rpmdevtools`:
1366 cd $HOME/rpmbuild/SOURCES
1367 spectool -g ../SPECS/icinga2.spec
1372 Install the build dependencies. Example for CentOS 7:
1375 yum -y install libedit-devel ncurses-devel gcc-c++ libstdc++-devel openssl-devel \
1376 cmake flex bison boost-devel systemd mysql-devel postgresql-devel httpd \
1377 selinux-policy-devel checkpolicy selinux-policy selinux-policy-doc
1380 Note: If you are using Amazon Linux, systemd is not required.
1382 A shorter way is available using the `yum-builddep` command on RHEL based systems:
1385 yum-builddep SPECS/icinga2.spec
1391 rpmbuild -ba SPECS/icinga2.spec
1394 #### Additional Hints <a id="development-package-builds-rpms-additional-hints"></a>
1396 ##### SELinux policy module
1398 The following packages are required to build the SELinux policy module:
1401 * selinux-policy (selinux-policy on CentOS 6, selinux-policy-devel on CentOS 7)
1402 * selinux-policy-doc
1406 The RedHat Developer Toolset is required for building Icinga 2 beforehand.
1407 This contains a modern version of flex and a C++ compiler which supports
1410 cat >/etc/yum.repos.d/devtools-2.repo <<REPO
1411 [testing-devtools-2-centos-\$releasever]
1412 name=testing 2 devtools for CentOS $releasever
1413 baseurl=https://people.centos.org/tru/devtools-2/\$releasever/\$basearch/RPMS
1418 Dependencies to devtools-2 are used in the RPM SPEC, so the correct tools
1419 should be used for building.
1421 As an alternative, you can use newer Boost packages provided on
1422 [packages.icinga.com](https://packages.icinga.com/epel).
1424 cat >$HOME/.rpmmacros <<MACROS
1431 If you prefer to build packages offline, a suitable Vagrant box is located
1432 [here](https://atlas.hashicorp.com/mvbcoding/boxes/awslinux/).
1436 The Icinga repository provides the required boost package version and must be
1437 added before building.
1439 ### Build Debian/Ubuntu packages <a id="development-package-builds-deb"></a>
1441 Setup your build environment on Debian/Ubuntu, copy the 'debian' directory from
1442 the Debian packaging Git repository (https://github.com/Icinga/deb-icinga2)
1443 into your source tree and run the following command:
1446 dpkg-buildpackage -uc -us
1449 ### Build Alpine Linux packages <a id="development-package-builds-alpine"></a>
1451 A simple way to setup a build environment is installing Alpine in a chroot.
1452 In this way, you can set up an Alpine build environment in a chroot under a
1453 different Linux distro.
1454 There is a script that simplifies these steps with just two commands, and
1455 can be found [here](https://github.com/alpinelinux/alpine-chroot-install).
1457 Once the build environment is installed, you can setup the system to build
1458 the packages by following [this document](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package).
1460 ### Build Post Install Tasks <a id="development-package-builds-post-install-tasks"></a>
1462 After building Icinga 2 yourself, your package build system should at least run the following post
1463 install requirements:
1465 * enable the `checker`, `notification` and `mainlog` feature by default
1466 * run 'icinga2 api setup' in order to enable the `api` feature and generate SSL certificates for the node
1468 ### Run Icinga 2 <a id="development-package-builds-run-icinga"></a>
1470 Icinga 2 comes with a binary that takes care of loading all the relevant
1471 components (e.g. for check execution, notifications, etc.):
1476 [2016-12-08 16:44:24 +0100] information/cli: Icinga application loader (version: v2.5.4-231-gb10a6b7; debug)
1477 [2016-12-08 16:44:24 +0100] information/cli: Loading configuration file(s).
1478 [2016-12-08 16:44:25 +0100] information/ConfigItem: Committing config item(s).
1482 #### Init Script <a id="development-package-builds-init-script"></a>
1484 Icinga 2 can be started as a daemon using the provided init script:
1488 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1491 #### Systemd <a id="development-package-builds-systemd"></a>
1493 If your distribution uses systemd:
1496 systemctl {start|stop|reload|status|enable|disable} icinga2
1499 In case the distribution is running systemd >227, you'll also
1500 need to package and install the `etc/initsystem/icinga2.service.limits.conf`
1501 file into `/etc/systemd/system/icinga2.service.d`.
1503 #### openrc <a id="development-package-builds-openrc"></a>
1505 Or if your distribution uses openrc (like Alpine):
1509 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1512 Note: the openrc's init.d is not shipped by default.
1513 A working init.d with openrc can be found here: (https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd). If you have customized some path, edit the file and adjust it according with your setup.
1514 Those few steps can be followed:
1517 wget https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd
1518 mv icinga2.initd /etc/init.d/icinga2
1519 chmod +x /etc/init.d/icinga2
1522 Icinga 2 reads a single configuration file which is used to specify all
1523 configuration settings (global settings, hosts, services, etc.). The
1524 configuration format is explained in detail in the [doc/](doc/) directory.
1526 By default `make install` installs example configuration files in
1527 `/usr/local/etc/icinga2` unless you have specified a different prefix or
1531 ### Windows Builds <a id="development-package-builds-windows"></a>
1533 The Windows MSI packages are located at https://packages.icinga.com/windows/
1535 #### Requirements <a id="development-package-builds-windows-requirements"></a>
1537 * 32 or 64-bit system
1538 * Visual Studio >= 14 2015
1545 Download the community edition from [visualstudio.com](https://www.visualstudio.com/en/downloads/)
1547 Workloads to install:
1551 ##### OpenSSL for Icinga
1553 Download custom OpenSSL builds from [openssl-windows GitHub project](https://github.com/Icinga/openssl-windows/releases).
1555 You need to install a binary dist version to 'C:\\Program Files\\OpenSSL'.
1557 The Powershell script `.\tools\win32\download-openssl.ps1` can be used for automated downloads.
1561 A simple package manager for Windows, please see [install instructions](https://chocolatey.org/install).
1565 Use Chocolatey, see [package details](https://chocolatey.org/packages/git).
1573 Use Chocolatey, see [package details](https://chocolatey.org/packages/winflexbison3).
1576 choco install winflexbison3
1581 Use Chocolatey, see [package details](https://chocolatey.org/packages/cmake)
1582 or download from: [cmake.org](https://cmake.org/download/)
1590 Use Chocolatey, see [package details](https://chocolatey.org/packages/wixtoolset).
1593 choco install wixtoolset
1598 Download third party Windows binaries from: [boost.org](http://www.boost.org/users/download/)
1600 For example: `https://dl.bintray.com/boostorg/release/1.65.1/binaries/boost_1_65_1-msvc-14.1-64.exe`
1603 * Must match your Visual Studio version!
1604 * CMake might not support the latest Boost version (we used CMake 3.10 and Boost 1_65_1)
1606 Run the installer exe.
1611 Run with VC Native x64 Command Prompt:
1614 powershell .\tools\win32\configure.ps1
1615 powershell .\tools\win32\build.ps1
1616 powershell .\tools\win32\test.ps1
1619 See these scripts for details.
1623 We are building [Icinga 2 with AppVeyor](https://ci.appveyor.com/project/icinga/icinga2) for testing and CI integration.
1625 Please check `appveyor.yml` for instructions.
1629 ## Advanced Development Tips <a id="development-advanced"></a>
1631 ### GDB Pretty Printers <a id="development-advanced-gdb-pretty-printer"></a>
1633 Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required,
1634 so please make sure to update the installation paths accordingly (`pwd`).
1637 $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
1640 Boost Pretty Printers compatible with Python 3:
1643 $ git clone https://github.com/mateidavid/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
1644 $ git checkout python-3
1646 /home/michi/.gdb_printers/Boost-Pretty-Printer
1649 Python Pretty Printers:
1652 $ cd ~/.gdb_printers
1653 $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
1656 Icinga 2 Pretty Printers:
1659 $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
1660 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
1663 Now you'll need to modify/setup your `~/.gdbinit` configuration file.
1664 You can download the one from Icinga 2 and modify all paths.
1666 Example on Fedora 22:
1669 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
1676 sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
1677 from icingadbg import register_icinga_printers
1678 register_icinga_printers()
1683 sys.path.insert(0, '/home/michi/.gdb_printers/python')
1684 from libstdcxx.v6.printers import register_libstdcxx_printers
1686 register_libstdcxx_printers(None)
1693 sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
1695 boost_print.register_printers()
1699 If you are getting the following error when running gdb, the `libstdcxx`
1700 printers are already preloaded in your environment and you can remove
1701 the duplicate import in your `~/.gdbinit` file.
1704 RuntimeError: pretty-printer already registered: libstdc++-v6
1707 ## Development Tests <a id="development-tests"></a>
1709 Build the binaries and run the tests.
1717 Run a specific boost test:
1720 debug/Bin/Debug/boosttest-test-base --run_test=remote_url