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`.
42 apt-get install icinga2-dbg
48 yum install icinga2-debuginfo
54 dnf install icinga2-debuginfo icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
60 zypper install icinga2-bin-debuginfo icinga2-ido-mysql-debuginfo
63 Furthermore, you may also have to install debug symbols for Boost and your C++ library.
65 If you're building your own binaries, you should use the `-DCMAKE_BUILD_TYPE=Debug` cmake
66 build flag for debug builds.
69 ### GDB as Debugger <a id="development-debug-gdb"></a>
71 Install GDB in your development environment.
91 #### GDB Run <a id="development-debug-gdb-run"></a>
93 Call GDB with the binary (`/usr/sbin/icinga2` is a wrapper script calling
94 `/usr/lib64/icinga2/sbin/icinga2` since 2.4) and all arguments and run it in foreground.
97 gdb --args /usr/lib64/icinga2/sbin/icinga2 daemon -x debug
100 The exact path to the Icinga 2 binary differs on each distribution. On Ubuntu
101 it is installed into `/usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2` on 64-bit systems
106 > If gdb tells you it's missing debug symbols, quit gdb and install
107 > them: `Missing separate debuginfos, use: debuginfo-install ...`
109 Run/restart the application.
115 Kill the running application.
121 Continue after breakpoint.
127 #### GDB Core Dump <a id="development-debug-gdb-coredump"></a>
129 Either attach to the running process using `gdb -p PID` or start
134 (gdb) generate-core-file
137 #### GDB Backtrace <a id="development-debug-gdb-backtrace"></a>
139 If Icinga 2 aborted its operation abnormally, generate a backtrace.
143 > Please install the [required debug symbols](21-development.md#debug-requirements)
144 > prior to generating a backtrace.
146 `thread apply all` is important here since this includes all running threads.
147 We need this information when e.g. debugging dead locks and hanging features.
151 (gdb) thread apply all bt full
154 If gdb stops at a SIGPIPE signal please disable the signal before
155 running Icinga 2. This isn't an error, but we need to workaround it.
158 (gdb) handle SIGPIPE nostop noprint pass
162 If you create a [new issue](https://github.com/Icinga/icinga2/issues),
163 make sure to attach as much detail as possible.
165 #### GDB Backtrace from Running Process <a id="development-debug-gdb-backtrace-running"></a>
167 If Icinga 2 is still running, generate a full backtrace from the running
168 process and store it into a new file (e.g. for debugging dead locks).
172 > Please install the [required debug symbols](21-development.md#debug-requirements)
173 > prior to generating a backtrace.
175 Icinga 2 runs with 2 processes: main and command executor, therefore generate two backtrace logs
176 and add them to the GitHub issue.
179 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
182 #### GDB Thread List from Running Process <a id="development-debug-gdb-thread-list-running"></a>
184 Instead of a full backtrace, you sometimes just need a list of running threads.
187 for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "info threads" -ex "detach" -ex "q" > gdb_threads_${pid}_`date +%s`.log; done
190 #### GDB Backtrace Stepping <a id="development-debug-gdb-backtrace-stepping"></a>
192 Identifying the problem may require stepping into the backtrace, analysing
193 the current scope, attributes, and possible unmet requirements. `p` prints
194 the value of the selected variable or function call result.
200 (gdb) p checkable.px->m_Name
203 #### GDB Breakpoints <a id="development-debug-gdb-breakpoint"></a>
205 To set a breakpoint to a specific function call, or file specific line.
208 (gdb) b checkable.cpp:125
209 (gdb) b icinga::Checkable::SetEnablePerfdata
212 GDB will ask about loading the required symbols later, select `yes` instead
215 Then run Icinga 2 until it reaches the first breakpoint. Continue with `c`
223 In case you want to step into the next line of code, use `n`. If there is a
224 function call where you want to step into, use `s`.
232 If you want to delete all breakpoints, use `d` and select `yes`.
240 > When debugging exceptions, set your breakpoint like this: `b __cxa_throw`.
249 #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)
250 at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609
254 605 #endif /* _WIN32 */
256 607 std::sort(files.begin(), files.end());
257 608 BOOST_FOREACH(const String& cpath, files) {
261 612 std::sort(dirs.begin(), dirs.end());
262 613 BOOST_FOREACH(const String& cpath, dirs) {
264 $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615,
265 m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615,
266 m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615,
267 m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615,
268 m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615,
269 m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}
272 ### Core Dump <a id="development-debug-core-dump"></a>
274 When the Icinga 2 daemon crashes with a `SIGSEGV` signal
275 a core dump file should be written. This will help
276 developers to analyze and fix the problem.
278 #### Core Dump File Size Limit <a id="development-debug-core-dump-limit"></a>
280 This requires setting the core dump file size to `unlimited`.
286 systemctl edit icinga2.service
292 systemctl daemon-reload
294 systemctl restart icinga2
300 vim /etc/init.d/icinga2
304 service icinga2 restart
309 Verify that the Icinga 2 process core file size limit is set to `unlimited`.
312 for pid in $(pidof icinga2); do cat /proc/$pid/limits; done
315 Max core file size unlimited unlimited bytes
319 #### Core Dump Kernel Format <a id="development-debug-core-dump-format"></a>
321 The Icinga 2 daemon runs with the SUID bit set. Therefore you need
322 to explicitly enable core dumps for SUID on Linux.
325 sysctl -w fs.suid_dumpable=2
328 Adjust the coredump kernel format and file location on Linux:
331 sysctl -w kernel.core_pattern=/var/lib/cores/core.%e.%p
333 install -m 1777 -d /var/lib/cores
339 sysctl -w kern.corefile=/cores/core.%P
344 #### Core Dump Analysis <a id="development-debug-core-dump-analysis"></a>
346 Once Icinga 2 crashes again a new coredump file will be written. Please
347 attach this file to your bug report in addition to the general details.
349 Simple test case for a `SIGSEGV` simulation with `sleep`:
356 gdb `which sleep` /var/lib/cores/core.sleep.<PID>
358 rm /var/lib/cores/core.sleep.*
364 gdb /usr/lib64/icinga2/sbin/icinga2 core.icinga2.<PID>
368 ### LLDB as Debugger <a id="development-debug-lldb"></a>
370 LLDB is available on macOS with the Xcode command line tools.
373 $ xcode-select --install
376 In order to run Icinga 2 with LLDB you need to pass the binary as argument.
379 lldb -- /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
386 > b icinga::Checkable::ProcessCheckResult
419 Up/down in stacktrace:
428 ## Develop Icinga 2 <a id="development-develop"></a>
430 Icinga 2 can be built on many platforms such as Linux, Unix and Windows.
431 There are limitations in terms of support, e.g. Windows is only supported for agents,
432 not a full-featured master or satellite.
434 Before you start with actual development, there is a couple of pre-requisites.
436 ### Choose your Editor <a id="development-develop-choose-editor"></a>
438 Icinga 2 can be developed with your favorite editor. Icinga developers prefer
442 - CLion (macOS, Linux)
443 - MS Visual Studio (Windows)
446 Editors differ on the functionality. The more helpers you get for C++ development,
447 the faster your development workflow will be.
450 #### Whitespace Cleanup <a id="development-develop-choose-editor-whitespaces"></a>
452 Patches must be cleaned up and follow the indent style (tabs instead of spaces).
453 You should also remove any training whitespaces.
455 `git diff` allows to highlight such.
461 whitespace = red reverse
463 whitespace=fix,-indent-with-non-tab,trailing-space,cr-at-eol
466 `vim` also can match these and visually alert you to remove them.
471 highlight ExtraWhitespace ctermbg=red guibg=red
472 match ExtraWhitespace /\s\+$/
473 autocmd BufWinEnter * match ExtraWhitespace /\s\+$/
474 autocmd InsertEnter * match ExtraWhitespace /\s\+\%#\@<!$/
475 autocmd InsertLeave * match ExtraWhitespace /\s\+$/
476 autocmd BufWinLeave * call clearmatches()
479 ### Get to know the architecture <a id="development-develop-get-to-know-the-architecture"></a>
481 Icinga 2 can run standalone or in distributed environments. It contains a whole lot
482 more than a simple check execution engine.
484 Read more about it in the [Technical Concepts](19-technical-concepts.md#technical-concepts) chapter.
486 ### Get to know the code <a id="development-develop-get-to-know-the-code"></a>
488 First off, you really need to know C++ and portions of C++11 and the boost libraries.
489 Best is to start with a book or online tutorial to get into the basics.
490 Icinga developers gained their knowledge through studies, training and self-teaching
491 code by trying it out and asking senior developers for guidance.
493 Here's a few books we can recommend:
495 * [Accelerated C++: Practical Programming by Example](https://www.amazon.com/Accelerated-C-Practical-Programming-Example/dp/020170353X) (Andrew Koenig, Barbara E. Moo)
496 * [Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) (Scott Meyers)
497 * [Der C++ Programmierer](https://www.amazon.de/Programmierer-lernen-Professionell-anwenden-L%C3%B6sungen/dp/3446416447), German (Ulrich Breymann)
498 * [C++11 programmieren](https://www.amazon.de/gp/product/3836217325/), German (Torsten T. Will)
500 In addition, it is a good bet to also know SQL when diving into backend development.
502 * [SQL Performance Explained](https://www.amazon.de/gp/product/3950307826/) (Markus Winand)
504 Last but not least, if you are developing on Windows, get to know the internals about services and the Win32 API.
507 ### Design Patterns <a id="development-develop-design-patterns"></a>
509 Icinga 2 heavily relies on object-oriented programming and encapsulates common
510 functionality into classes and objects. It also uses modern programming techniques
511 to e.g. work with shared pointer memory management.
513 Icinga 2 consists of libraries bundled into the main binary. Therefore you'll
514 find many code parts in the `lib/` directory wheras the actual application is
515 built from `icinga-app/`. Accompanied with Icinga 2, there's the Windows plugins
516 which are standalone and compiled from `plugins/`.
518 Library | Description
519 ---------------|------------------------------------
520 base | Objects, values, types, streams, tockets, TLS, utilities, etc.
521 config | Configuration compiler, expressions, etc.
522 cli | CLI (sub) commands and helpers.
523 icinga | Icinga specific objects and event handling.
524 remote | Cluster and HTTP client/server and REST API related code.
525 checker | Checker feature, check scheduler.
526 notification | Notification feature, notification scheduler.
527 methods | Command execution methods, plugins and built-in checks.
528 perfdata | Performance data related, including Graphite, Elastic, etc.
529 db\_ido | IDO database abstraction layer.
530 db\_ido\_mysql | IDO database driver for MySQL.
531 db\_ido\_pgsql | IDO database driver for PgSQL.
532 mysql\_shin | Library stub for linking against the MySQL client libraries.
533 pgsql\_shim | Library stub for linking against the PgSQL client libraries.
535 #### Class Compiler <a id="development-develop-design-patterns-class-compiler"></a>
537 Another thing you will recognize are the `.ti` files which are compiled
538 by our own class compiler into actual source code. The meta language allows
539 developers to easily add object attributes and specify their behaviour.
541 Some object attributes need to be stored over restarts in the state file
542 and therefore have the `state` attribute set. Others are treated as `config`
543 attribute and automatically get configuration validation functions created.
544 Hidden or read-only REST API attributes are marked with `no_user_view` and
547 The most beneficial thing are getters and setters being generated. The actual object
548 inherits from `ObjectImpl<TYPE>` and therefore gets them "for free".
553 vim lib/perfdata/gelfwriter.ti
557 vim lib/perfdata/gelfwriter.cpp
559 if (GetEnableTls()) {
562 The logic is hidden in `tools/mkclass/` in case you want to learn more about it.
563 The first steps during CMake & make also tell you about code generation.
566 ### Builds: CMake <a id="development-develop-builds-cmake"></a>
568 In its early development stages in 2012, Icinga 2 was built with autoconf/automake
569 and separate Windows project files. We've found this very fragile, and have changed
570 this into CMake as our build tool.
572 The most common benefits:
574 * Everything is described in CMakeLists.txt in each directory
575 * CMake only needs to know that a sub directory needs to be included.
576 * The global CMakeLists.txt acts as main entry point for requirement checks and library/header includes.
577 * Separate binary build directories, the actual source tree stays clean.
578 * CMake automatically generates a Visual Studio project file `icinga2.sln` on Windows.
580 ### Builds: Unity Builds <a id="development-develop-builds-unity-builds"></a>
582 Another thing you should be aware of: Unity builds on and off.
584 Typically, we already use caching mechanisms to reduce recompile time with ccache.
585 For release builds, there's always a new build needed as the difference is huge compared
586 to a previous (major) release.
588 Therefore we've invented the Unity builds, which basically concatenates all source files
589 into one big library source code file. The compiler then doesn't need to load the many small
590 files but compiles and links this huge one.
592 Unity builds require more memory which is why you should disable them for development
593 builds in small sized VMs (Linux, Windows) and also Docker containers.
595 There's a couple of header files which are included everywhere. If you touch/edit them,
596 the cache is invalidated and you need to recompile a lot more files then. `base/utility.hpp`
597 and `remote/zone.hpp` are good candidates for this.
600 ### Linux Dev Environment <a id="development-linux-dev-env"></a>
602 Based on CentOS 7, we have an early draft available inside the Icinga Vagrant boxes:
603 [centos7-dev](https://github.com/Icinga/icinga-vagrant/tree/master/centos7-dev).
605 If you're compiling Icinga 2 natively without any virtualization layer in between,
606 this usually is faster. This is also the reason why developers on macOS prefer native builds
607 over Linux or Windows VMs. Don't forget to test the actual code on Linux later! Socket specific
608 stuff like `epoll` is not available on Unix kernels.
610 Depending on your workstation and environment, you may either develop and run locally,
611 use a container deployment pipeline or put everything in a high end resource remote VM.
613 Fork https://github.com/Icinga/icinga2 into your own repository, e.g. `https://github.com/dnsmichi/icinga2`.
615 Create two build directories for different binary builds.
617 * `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.
618 * `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.
621 mkdir -p release debug
624 Proceed with the specific distribution examples below.
626 * [CentOS 7](21-development.md#development-linux-dev-env-centos)
627 * [Debian 9](21-development.md#development-linux-dev-env-debian)
630 #### CentOS 7 <a id="development-linux-dev-env-centos"></a>
633 yum -y install gdb git bash-completion htop rpmdevtools \
634 ccache cmake make gcc-c++ flex bison \
635 openssl-devel boost-devel systemd-devel mysql-devel \
636 postgresql-devel libedit-devel libstdc++-devel
640 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
642 ln -s /bin/ccache /usr/local/bin/gcc
643 ln -s /bin/ccache /usr/local/bin/g++
645 git clone https://github.com/icinga/icinga2.git && cd icinga2
649 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
651 make -j2 install -C debug
656 chown -R icinga:icinga /usr/local/icinga2/var/
658 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
659 /usr/local/icinga2/sbin/icinga2 api setup
660 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
662 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
665 ##### Debian 9 <a id="development-linux-dev-env-debian"></a>
668 apt-get -y install gdb vim git cmake make ccache build-essential libssl-dev libboost-all-dev bison flex default-libmysqlclient-dev libpq-dev libyajl-dev libedit-dev monitoring-plugins
670 ln -s /usr/bin/ccache /usr/local/bin/gcc
671 ln -s /usr/bin/ccache /usr/local/bin/g++
675 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
677 git clone https://github.com/icinga/icinga2.git && cd icinga2
681 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
683 make -j2 install -C debug
688 chown -R icinga:icinga /usr/local/icinga2/var/
690 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
691 /usr/local/icinga2/sbin/icinga2 api setup
692 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
694 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
699 ### macOS Dev Environment <a id="development-macos-dev-env"></a>
701 It is advised to use Homebrew to install required build dependencies.
702 Macports have been reported to work as well, typically you'll get more help
703 with Homebrew from Icinga developers.
705 #### Users and Groups
707 First off, create the following from `Settings - Users & Groups`:
710 * Groups: `icinga` with `icinga` as member
711 * Groups: `icingaweb2`
713 Then disallow login for these users.
717 list Local/Default/Users
718 read Local/Default/Users/icinga
719 change Local/Default/Users/icinga UserShell /bin/bash /usr/bin/false
720 sudo dscl . create /Users/icinga IsHidden 1
721 sudo dseditgroup -o edit -a _www -t user icingaweb2
726 OpenSSL 1.0.x doesn't build anymore, so we're explicitly using 1.1.x here.
729 brew install ccache boost cmake bison flex yajl openssl@1.1 mysql-connector-c++ postgresql libpq
735 sudo mkdir /opt/ccache
737 sudo ln -s `which ccache` /opt/ccache/clang
738 sudo ln -s `which ccache` /opt/ccache/clang++
742 # ccache is managed with symlinks to avoid collision with cgo
743 export PATH="/opt/ccache:$PATH"
750 We will build two different flavors on macOS.
753 mkdir -p release debug
756 cmake -DICINGA2_UNITY_BUILD=OFF -DICINGA2_WITH_STUDIO=ON -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 ..
760 sudo make -j4 install -C debug
765 This is derived from dnsmichi's flavour and not generally best practice.
770 export PATH=/usr/local/icinga2/sbin/:$PATH
771 source /usr/local/icinga2/etc/bash_completion.d/icinga2
773 export I2_GENERIC="-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"
775 export I2_DEBUG="-DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF $I2_GENERIC"
776 export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DICINGA2_UNITY_BUILD=ON $I2_GENERIC"
778 alias i2_debug="mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j4; sudo make -j4 install; cd .."
779 alias i2_release="mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j4; sudo make -j4 install; cd .."
787 chown -R icinga:icinga /usr/local/icinga2
788 chown -R icinga:_www /usr/local/icinga2/var/run/icinga2/cmd
796 brew install nagios-plugins
798 sudo vim /usr/local/icinga2/etc/icinga2/constants.conf
799 const PluginDir = "/usr/local/sbin"
802 #### Databases: MariaDB
806 ln -sfv /usr/local/opt/mariadb/*.plist ~/Library/LaunchAgents
807 launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist
808 mysql_secure_installation
816 password = supersecurerootpassword
819 ln -s /Users/michi/.my.cnf $HOME/.my.cnf
824 cd $HOME/coding/icinga/icinga2
828 CREATE DATABASE icinga;
829 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
831 sudo mysql icinga < lib/db_ido_mysql/schema/mysql.sql
837 ### Windows Dev Environment <a id="development-windows-dev-env"></a>
839 The following sections explain how to setup the required build tools
840 and how to run and debug the code.
844 Open an administrative command prompt (Win key, type “cmd”, right-click and “run as administrator”) and paste the following instructions:
847 @powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
852 Thanks to Microsoft they’ll now provide their Professional Edition of Visual Studio 2017
853 as community version, free for use for open source projects such as Icinga.
854 The installation requires ~9GB disk space. [Download](https://www.visualstudio.com/downloads/)
855 the web installer and start the installation.
857 You need a free Microsoft account to download and also store your preferences.
859 Choose the following minimal set:
861 * .NET Framework 4.x SDK
863 * Visual Studio C++ core features
865 * Windows 10 SDK (10.0.10240.0 - required)
866 * Just-in-time debugger
867 * Windows 8 SDK (includes mscoree.lib required by clrchecktask)
869 * Windows Universal C Runtime
871 * .NET Framework 3.5 development tools
872 * Github extension for Visual Studio
874 After a while, Visual Studio will be ready.
878 Install it using [chocolatey](https://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html):
881 choco install -y winflexbison
884 Chocolatey installs these tools into the hidden directory `C:\ProgramData\chocolatey\lib\winflexbison\tools`.
888 Icinga 2 requires the OpenSSL library. [Download](http://slproweb.com/products/Win32OpenSSL.html)
889 and install it into the default path.
891 Once asked for `Copy OpenSSLs DLLs to` select `The Windows system directory`. That way CMake/Visual Studio
892 will automatically detect them for builds and packaging.
896 > We cannot use the chocolatey package as this one does not provide any development headers.
898 > Choose 1.0.2 LTS from manual downloads for best compatibility if unsure.
902 In order to use the boost development header and library files you need to [download](http://www.boost.org/users/download/)
903 Boost and then extract it to e.g. `C:\boost_1_65_1`.
907 > Just use `C:`, the zip file already contains the sub folder. Extraction takes a while,
908 > the archive contains more than 10k files.
910 For integrating Boost into Visual Studio 2017, open the `Developer Command Prompt` from the start menu,
911 and navigate to `C:\boost_1_65_1`.
913 Execute `bootstrap.bat` first.
920 Once finished, specify the required `toolset` to compile boost against Visual Studio.
921 This takes quite some time in a Windows VM.
926 b2 --toolset=msvc-14.0
932 b2 --toolset=msvc-14.1
937 TortoiseGit provides a graphical integration into the Windows explorer. This makes it easier to checkout, commit
940 [Download](https://tortoisegit.org/download/) TortoiseGit on your system.
942 In order to clone via Git SSH you also need to create a new directory called `.ssh`
943 inside your user's home directory.
944 Therefore open a command prompt (win key, type `cmd`, enter) and run `mkdir .ssh`.
945 Add your `id_rsa` private key and `id_rsa.pub` public key files into that directory.
947 Start the setup routine and choose `OpenSSH` as default secure transport when asked.
949 Open a Windows Explorer window and navigate into
951 Version | Project Location
952 --------------------|------------------------------
953 Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects`
954 Visual Studio 2017+ | `C:\Users\michi\source\repos`
956 Right click and select `Git Clone` from the context menu.
958 Use `ssh://git@github.com/icinga/icinga2.git` for SSH clones, `https://github.com/icinga/icinga2.git` otherwise.
962 Icinga 2 uses CMake to manage the build environment. You can generate the Visual Studio project files
963 using CMake. [Download](https://cmake.org/download/) and install CMake. Select to add it to PATH for all users
966 Once setup is completed, open a command prompt and navigate to
971 cd C:\Users\<username>\Documents\Visual Studio 2015\Projects\icinga2
977 cd C:\Users\michi\source\repos
980 Run CMake with the following command. This generates a new Visual Studio project file called `icinga2.sln`.
982 You need to specify the previously installed component paths:
984 Variable | Value | Description
985 ----------------------|----------------------------------------------------------------------|-------------------------------------------------------
986 BOOST_ROOT | `C:\boost_1_65_1` | Root path where you've extracted and compiled Boost.
987 BISON_EXECUTABLE | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe` | Path to the Bison executable.
988 FLEX_EXECUTABLE | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe` | Path to the Flex executable.
989 ICINGA2_WITH_MYSQL | OFF | Requires extra setup for MySQL if set to `ON`. Not supported for client setups.
990 ICINGA2_WITH_PGSQL | OFF | Requires extra setup for PgSQL if set to `ON`. Not supported for client setups.
991 ICINGA2_UNITY_BUILD | OFF | Disable unity builds for development environments.
993 Tip: If you have previously opened a terminal, run `refreshenv` to re-read updated PATH variables.
996 cmake . -DBOOST_ROOT=C:\boost_1_65_1 -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
999 Best is write a small batch/Powershell script which just executes these lines.
1002 #### Icinga 2 in Visual Studio
1006 Version | Project location
1007 --------------------|-------------------------
1008 Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2`
1009 Visual Studio 2017+ | `C:\Users\michi\source\repos\icinga2`
1011 Open `icinga2.sln`. Log into Visual Studio when asked.
1013 On the right panel, select to build the `Bin/icinga-app` solution.
1015 The executable binaries are located in `Bin\Release\Debug` in your `icinga2`
1018 Navigate there and run `icinga2.exe --version`.
1020 Example for Visual Studio 2017:
1023 cd C:\Users\michi\source\repos\icinga2\Bin\Release\Debug
1024 icinga2.exe --version
1028 #### Release Package
1030 CMake uses CPack and NSIS to create the setup executable including all binaries and libraries
1031 in addition to setup dialogues and configuration. Therefore we’ll need to install [NSIS](http://nsis.sourceforge.net/Download)
1034 We also need to install the Windows Installer XML (WIX) toolset.
1037 choco install -y wixtoolset
1040 Once completed open an administrative shell and navigate to your Visual Studio project.
1041 Let CMake to build a release package.
1044 cd "c:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2"
1045 cmake --build . --target PACKAGE --config Release
1048 Note: This will still use the debug builds. A yet more clean approach
1049 is to run CMake with changed release parameters beforehand and then
1050 re-run the release package builder.
1053 C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2>
1054 cmake . -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Release -DBOOST_ROOT=C:\boost_1_65_1 -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
1056 cmake --build . --target PACKAGE --config Release
1059 Again, put these lines into a batch/Powershell script and execute that.
1063 ### Embedded Dev Env: Pi <a id="development-embedded-dev-env"></a>
1067 > This isn't officially supported yet, just a few hints how you can do it yourself.
1069 The following examples source from armhf on Raspberry Pi.
1074 apt install -y ccache
1076 /usr/sbin/update-ccache-symlinks
1078 echo 'export PATH="/usr/lib/ccache:$PATH"' | tee -a ~/.bashrc
1080 source ~/.bashrc && echo $PATH
1085 Copy the icinga2 source code into `$HOME/icinga2`. Clone the `deb-icinga2` repository into `debian/`.
1088 git clone https://github.com/Icinga/icinga2 $HOME/icinga2
1089 git clone https://github.com/Icinga/deb-icinga2 $HOME/icinga2/debian
1092 Then build a Debian package and install it like normal.
1094 dpkg-buildpackage -uc -us
1097 ## Package Builds <a id="development-package-builds"></a>
1099 This documentation is explicitly meant for packagers and the Icinga
1100 build infrastructure.
1102 The following requirements need to be fulfilled in order to build the
1103 Icinga application using a dist tarball (including notes for distributions):
1106 * GNU make (make) or ninja-build
1107 * C++ compiler which supports C++11
1108 - RHEL/Fedora/SUSE: gcc-c++ >= 4.7 (extra Developer Tools on RHEL5/6 see below)
1109 - Debian/Ubuntu: build-essential
1110 - Alpine: build-base
1111 - you can also use clang++
1113 * OpenSSL library and header files >= 1.0.1
1114 - RHEL/Fedora: openssl-devel
1115 - SUSE: libopenssl-devel (for SLES 11: libopenssl1-devel)
1116 - Debian/Ubuntu: libssl-dev
1117 - Alpine: libressl-dev
1118 * Boost library and header files >= 1.48.0
1119 - RHEL/Fedora: boost148-devel
1120 - Debian/Ubuntu: libboost-all-dev
1123 * GNU flex (flex) >= 2.5.35
1125 - Only required when using Systemd
1126 - Debian/Ubuntu: libsystemd-dev
1127 - RHEL/Fedora: systemd-devel
1129 ### Optional features <a id="development-package-builds-optional-features"></a>
1131 * MySQL (disable with CMake variable `ICINGA2_WITH_MYSQL` to `OFF`)
1132 - RHEL/Fedora: mysql-devel
1133 - SUSE: libmysqlclient-devel
1134 - Debian/Ubuntu: default-libmysqlclient-dev | libmysqlclient-dev
1135 - Alpine: mariadb-dev
1136 * PostgreSQL (disable with CMake variable `ICINGA2_WITH_PGSQL` to `OFF`)
1137 - RHEL/Fedora: postgresql-devel
1138 - Debian/Ubuntu: libpq-dev
1139 - postgresql-dev on Alpine
1140 * YAJL (Faster JSON library)
1141 - RHEL/Fedora: yajl-devel
1142 - Debian: libyajl-dev
1144 * libedit (CLI console)
1145 - RHEL/Fedora: libedit-devel on CentOS (RHEL requires rhel-7-server-optional-rpms)
1146 - Debian/Ubuntu/Alpine: libedit-dev
1147 * Termcap (only required if libedit doesn't already link against termcap/ncurses)
1148 - RHEL/Fedora: libtermcap-devel
1149 - Debian/Ubuntu: (not necessary)
1151 ### Special requirements <a id="development-package-builds-special-requirements"></a>
1153 **FreeBSD**: libexecinfo (automatically used when Icinga 2 is installed via port or package)
1155 **RHEL6**: Requires a newer boost version which is available on packages.icinga.com
1156 with a version suffixed name.
1158 ### Runtime user environment <a id="development-package-builds-runtime-user-env"></a>
1160 By default Icinga will run as user `icinga` and group `icinga`. Additionally the
1161 external command pipe and livestatus features require a dedicated command group
1162 `icingacmd`. You can choose your own user/group names and pass them to CMake
1163 using the `ICINGA2_USER`, `ICINGA2_GROUP` and `ICINGA2_COMMAND_GROUP` variables.
1167 # groupadd icingacmd
1168 # useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
1171 On Alpine (which uses ash busybox) you can run:
1174 # addgroup -S icinga
1175 # addgroup -S icingacmd
1176 # adduser -S -D -H -h /var/spool/icinga2 -s /sbin/nologin -G icinga -g icinga icinga
1177 # adduser icinga icingacmd
1180 Add the web server user to the icingacmd group in order to grant it write
1181 permissions to the external command pipe and livestatus socket:
1184 # usermod -a -G icingacmd www-data
1187 Make sure to replace "www-data" with the name of the user your web server
1190 ### Building Icinga 2: Example <a id="development-package-builds-example"></a>
1192 Once you have installed all the necessary build requirements you can build
1193 Icinga 2 using the following commands:
1196 $ mkdir release && cd release
1200 $ make install -C release
1203 You can specify an alternative installation prefix using `-DCMAKE_INSTALL_PREFIX`:
1206 $ cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2
1209 ### CMake Variables <a id="development-package-builds-cmake-variables"></a>
1211 In addition to `CMAKE_INSTALL_PREFIX` here are most of the supported Icinga-specific cmake variables.
1213 For all variables regarding defaults paths on in CMake, see
1214 [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html).
1216 Also see `CMakeLists.txt` for details.
1218 **System Environment**
1219 - `CMAKE_INSTALL_SYSCONFDIR`: The configuration directory; defaults to `CMAKE_INSTALL_PREFIX/etc`
1220 - `CMAKE_INSTALL_LOCALSTATEDIR`: The state directory; defaults to `CMAKE_INSTALL_PREFIX/var`
1221 - `ICINGA2_CONFIGDIR`: Main config directory; defaults to `CMAKE_INSTALL_SYSCONFDIR/icinga2` usually `/etc/icinga2`
1222 - `ICINGA2_CACHEDIR`: Directory for cache files; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/cache/icinga2` usually `/var/cache/icinga2`
1223 - `ICINGA2_DATADIR`: Data directory for the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/lib/icinga2` usually `/var/lib/icinga2`
1224 - `ICINGA2_LOGDIR`: Logfiles of the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/log/icinga2 usually `/var/log/icinga2`
1225 - `ICINGA2_SPOOLDIR`: Spooling directory ; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/spool/icinga2` usually `/var/spool/icinga2`
1226 - `ICINGA2_INITRUNDIR`: Runtime data for the init system; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/run/icinga2` usually `/run/icinga2`
1227 - `ICINGA2_GIT_VERSION_INFO`: Whether to use Git to determine the version number; defaults to `ON`
1228 - `ICINGA2_USER`: The user Icinga 2 should run as; defaults to `icinga`
1229 - `ICINGA2_GROUP`: The group Icinga 2 should run as; defaults to `icinga`
1230 - `ICINGA2_COMMAND_GROUP`: The command group Icinga 2 should use; defaults to `icingacmd`
1231 - `ICINGA2_SYSCONFIGFILE`: Where to put the config file the initscript/systemd pulls it's dirs from;
1232 defaults to `CMAKE_INSTALL_PREFIX/etc/sysconfig/icinga2`
1233 - `ICINGA2_PLUGINDIR`: The path for the Monitoring Plugins project binaries; defaults to `/usr/lib/nagios/plugins`
1235 **Build Optimization**
1236 - `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.
1237 - `ICINGA2_LTO_BUILD`: Whether to use link time optimization (LTO); defaults to `OFF`
1240 - `USE_SYSTEMD=ON|OFF`: Use systemd or a classic SysV initscript; defaults to `OFF`
1241 - `INSTALL_SYSTEMD_SERVICE_AND_INITSCRIPT=ON|OFF` Force install both the systemd service definition file
1242 and the SysV initscript in parallel, regardless of how `USE_SYSTEMD` is set.
1243 Only use this for special packaging purposes and if you know what you are doing.
1247 - `ICINGA2_WITH_CHECKER`: Determines whether the checker module is built; defaults to `ON`
1248 - `ICINGA2_WITH_COMPAT`: Determines whether the compat module is built; defaults to `ON`
1249 - `ICINGA2_WITH_DEMO`: Determines whether the demo module is built; defaults to `OFF`
1250 - `ICINGA2_WITH_HELLO`: Determines whether the hello module is built; defaults to `OFF`
1251 - `ICINGA2_WITH_LIVESTATUS`: Determines whether the Livestatus module is built; defaults to `ON`
1252 - `ICINGA2_WITH_NOTIFICATION`: Determines whether the notification module is built; defaults to `ON`
1253 - `ICINGA2_WITH_PERFDATA`: Determines whether the perfdata module is built; defaults to `ON`
1254 - `ICINGA2_WITH_TESTS`: Determines whether the unit tests are built; defaults to `ON`
1256 **MySQL or MariaDB:**
1258 The following settings can be tuned for the MySQL / MariaDB IDO feature.
1260 - `ICINGA2_WITH_MYSQL`: Determines whether the MySQL IDO module is built; defaults to `ON`
1261 - `MYSQL_CLIENT_LIBS`: Client implementation used (mysqlclient / mariadbclient); defaults searches for `mysqlclient` and `mariadbclient`
1262 - `MYSQL_INCLUDE_DIR`: Directory containing include files for the mysqlclient; default empty -
1263 checking multiple paths like `/usr/include/mysql`
1265 See [FindMySQL.cmake](third-party/cmake/FindMySQL.cmake) for the implementation.
1269 The following settings can be tuned for the PostgreSQL IDO feature.
1271 - `ICINGA2_WITH_PGSQL`: Determines whether the PostgreSQL IDO module is built; defaults to `ON`
1272 - `PostgreSQL_INCLUDE_DIR`: Top-level directory containing the PostgreSQL include directories
1273 - `PostgreSQL_LIBRARY`: File path to PostgreSQL library : libpq.so (or libpq.so.[ver] file)
1275 See [FindMySQL.cmake](third-party/cmake/FindPostgreSQL.cmake) for the implementation.
1277 **Version detection:**
1279 CMake determines the Icinga 2 version number using `git describe` if the
1280 source directory is contained in a Git repository. Otherwise the version number
1281 is extracted from the [VERSION](VERSION) file. This behavior can be
1282 overridden by creating a file called `icinga-version.h.force` in the source
1283 directory. Alternatively the `-DICINGA2_GIT_VERSION_INFO=OFF` option for CMake
1284 can be used to disable the usage of `git describe`.
1287 ### Building RPMs <a id="development-package-builds-rpms"></a>
1289 #### Build Environment on RHEL, CentOS, Fedora, Amazon Linux
1291 Setup your build environment:
1294 yum -y install rpmdevtools
1297 #### Build Environment on SuSE/SLES
1302 zypper addrepo http://download.opensuse.org/repositories/devel:tools/SLE_12_SP4/devel:tools.repo
1304 zypper install rpmdevtools spectool
1310 zypper addrepo http://download.opensuse.org/repositories/devel:tools/openSUSE_Leap_15.0/devel:tools.repo
1312 zypper install rpmdevtools spectool
1315 #### Package Builds <a id="development-package-builds-rpms-package-builds"></a>
1317 Prepare the rpmbuild directory tree:
1327 curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o $HOME/rpmbuild/SPECS/icinga2.spec
1332 > The above command builds snapshot packages. Change to the `release` branch
1333 > for release package builds.
1335 Copy the tarball to `rpmbuild/SOURCES` e.g. by using the `spectool` binary
1336 provided with `rpmdevtools`:
1339 cd $HOME/rpmbuild/SOURCES
1340 spectool -g ../SPECS/icinga2.spec
1345 Install the build dependencies. Example for CentOS 7:
1348 yum -y install libedit-devel ncurses-devel gcc-c++ libstdc++-devel openssl-devel \
1349 cmake flex bison boost-devel systemd mysql-devel postgresql-devel httpd \
1350 selinux-policy-devel checkpolicy selinux-policy selinux-policy-doc
1353 Note: If you are using Amazon Linux, systemd is not required.
1355 A shorter way is available using the `yum-builddep` command on RHEL based systems:
1358 yum-builddep SPECS/icinga2.spec
1364 rpmbuild -ba SPECS/icinga2.spec
1367 #### Additional Hints <a id="development-package-builds-rpms-additional-hints"></a>
1369 ##### SELinux policy module
1371 The following packages are required to build the SELinux policy module:
1374 * selinux-policy (selinux-policy on CentOS 6, selinux-policy-devel on CentOS 7)
1375 * selinux-policy-doc
1379 The RedHat Developer Toolset is required for building Icinga 2 beforehand.
1380 This contains a modern version of flex and a C++ compiler which supports
1383 cat >/etc/yum.repos.d/devtools-2.repo <<REPO
1384 [testing-devtools-2-centos-\$releasever]
1385 name=testing 2 devtools for CentOS $releasever
1386 baseurl=https://people.centos.org/tru/devtools-2/\$releasever/\$basearch/RPMS
1391 Dependencies to devtools-2 are used in the RPM SPEC, so the correct tools
1392 should be used for building.
1394 As an alternative, you can use newer Boost packages provided on
1395 [packages.icinga.com](https://packages.icinga.com/epel).
1397 cat >$HOME/.rpmmacros <<MACROS
1404 If you prefer to build packages offline, a suitable Vagrant box is located
1405 [here](https://atlas.hashicorp.com/mvbcoding/boxes/awslinux/).
1409 The Icinga repository provides the required boost package version and must be
1410 added before building.
1412 ### Build Debian/Ubuntu packages <a id="development-package-builds-deb"></a>
1414 Setup your build environment on Debian/Ubuntu, copy the 'debian' directory from
1415 the Debian packaging Git repository (https://github.com/Icinga/deb-icinga2)
1416 into your source tree and run the following command:
1419 dpkg-buildpackage -uc -us
1422 ### Build Alpine Linux packages <a id="development-package-builds-alpine"></a>
1424 A simple way to setup a build environment is installing Alpine in a chroot.
1425 In this way, you can set up an Alpine build environment in a chroot under a
1426 different Linux distro.
1427 There is a script that simplifies these steps with just two commands, and
1428 can be found [here](https://github.com/alpinelinux/alpine-chroot-install).
1430 Once the build environment is installed, you can setup the system to build
1431 the packages by following [this document](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package).
1433 ### Build Post Install Tasks <a id="development-package-builds-post-install-tasks"></a>
1435 After building Icinga 2 yourself, your package build system should at least run the following post
1436 install requirements:
1438 * enable the `checker`, `notification` and `mainlog` feature by default
1439 * run 'icinga2 api setup' in order to enable the `api` feature and generate SSL certificates for the node
1441 ### Run Icinga 2 <a id="development-package-builds-run-icinga"></a>
1443 Icinga 2 comes with a binary that takes care of loading all the relevant
1444 components (e.g. for check execution, notifications, etc.):
1449 [2016-12-08 16:44:24 +0100] information/cli: Icinga application loader (version: v2.5.4-231-gb10a6b7; debug)
1450 [2016-12-08 16:44:24 +0100] information/cli: Loading configuration file(s).
1451 [2016-12-08 16:44:25 +0100] information/ConfigItem: Committing config item(s).
1455 #### Init Script <a id="development-package-builds-init-script"></a>
1457 Icinga 2 can be started as a daemon using the provided init script:
1460 # /etc/init.d/icinga2
1461 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1464 ### Systemd <a id="development-package-builds-systemd"></a>
1466 If your distribution uses Systemd:
1469 # systemctl {start|stop|reload|status|enable|disable} icinga2
1472 In case the distribution is running Systemd >227, you'll also
1473 need to package and install the `etc/initsystem/icinga2.service.limits.conf`
1474 file into `/etc/systemd/system/icinga2.service.d`.
1476 ### openrc <a id="development-package-builds-openrc"></a>
1478 Or if your distribution uses openrc (like Alpine):
1481 # rc-service icinga2
1482 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1485 Note: the openrc's init.d is not shipped by default.
1486 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.
1487 Those few steps can be followed:
1490 # wget https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd
1491 # mv icinga2.initd /etc/init.d/icinga2
1492 # chmod +x /etc/init.d/icinga2
1495 Icinga 2 reads a single configuration file which is used to specify all
1496 configuration settings (global settings, hosts, services, etc.). The
1497 configuration format is explained in detail in the [doc/](doc/) directory.
1499 By default `make install` installs example configuration files in
1500 `/usr/local/etc/icinga2` unless you have specified a different prefix or
1504 ### Windows Builds <a id="development-package-builds-windows"></a>
1506 The Windows MSI packages are located at https://packages.icinga.com/windows/
1508 #### Requirements <a id="development-package-builds-windows-requirements"></a>
1510 * 32 or 64-bit system
1511 * Visual Studio >= 14 2015
1518 Download the community edition from [visualstudio.com](https://www.visualstudio.com/en/downloads/)
1520 Workloads to install:
1524 ##### OpenSSL for Icinga
1526 Download custom OpenSSL builds from [openssl-windows GitHub project](https://github.com/Icinga/openssl-windows/releases).
1528 You need to install a binary dist version to 'C:\\Program Files\\OpenSSL'.
1530 The Powershell script `.\tools\win32\download-openssl.ps1` can be used for automated downloads.
1534 A simple package manager for Windows, please see [install instructions](https://chocolatey.org/install).
1538 Use Chocolatey, see [package details](https://chocolatey.org/packages/git).
1546 Use Chocolatey, see [package details](https://chocolatey.org/packages/winflexbison3).
1549 choco install winflexbison3
1554 Use Chocolatey, see [package details](https://chocolatey.org/packages/cmake)
1555 or download from: [cmake.org](https://cmake.org/download/)
1563 Use Chocolatey, see [package details](https://chocolatey.org/packages/wixtoolset).
1566 choco install wixtoolset
1571 Download third party Windows binaries from: [boost.org](http://www.boost.org/users/download/)
1573 For example: `https://dl.bintray.com/boostorg/release/1.65.1/binaries/boost_1_65_1-msvc-14.1-64.exe`
1576 * Must match your Visual Studio version!
1577 * CMake might not support the latest Boost version (we used CMake 3.10 and Boost 1_65_1)
1579 Run the installer exe.
1584 Run with VC Native x64 Command Prompt:
1587 powershell .\tools\win32\configure.ps1
1588 powershell .\tools\win32\build.ps1
1589 powershell .\tools\win32\test.ps1
1592 See these scripts for details.
1596 We are building [Icinga 2 with AppVeyor](https://ci.appveyor.com/project/icinga/icinga2) for testing and CI integration.
1598 Please check `appveyor.yml` for instructions.
1602 ## Advanced Development Tips <a id="development-advanced"></a>
1604 ### GDB Pretty Printers <a id="development-advanced-gdb-pretty-printer"></a>
1606 Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required,
1607 so please make sure to update the installation paths accordingly (`pwd`).
1609 $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
1611 Boost Pretty Printers compatible with Python 3:
1613 $ git clone https://github.com/mateidavid/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
1614 $ git checkout python-3
1616 /home/michi/.gdb_printers/Boost-Pretty-Printer
1618 Python Pretty Printers:
1620 $ cd ~/.gdb_printers
1621 $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
1623 Icinga 2 Pretty Printers:
1625 $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
1626 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
1628 Now you'll need to modify/setup your `~/.gdbinit` configuration file.
1629 You can download the one from Icinga 2 and modify all paths.
1631 Example on Fedora 22:
1633 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
1640 sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
1641 from icingadbg import register_icinga_printers
1642 register_icinga_printers()
1647 sys.path.insert(0, '/home/michi/.gdb_printers/python')
1648 from libstdcxx.v6.printers import register_libstdcxx_printers
1650 register_libstdcxx_printers(None)
1657 sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
1659 boost_print.register_printers()
1663 If you are getting the following error when running gdb, the `libstdcxx`
1664 printers are already preloaded in your environment and you can remove
1665 the duplicate import in your `~/.gdbinit` file.
1667 RuntimeError: pretty-printer already registered: libstdc++-v6
1670 ## Development Tests <a id="development-tests"></a>
1672 Build the binaries and run the tests.
1680 Run a specific boost test:
1683 debug/Bin/Debug/boosttest-test-base --run_test=remote_url