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`.
221 #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)
222 at /home/michi/coding/icinga/icinga2/lib/base/utility.cpp:609
226 605 #endif /* _WIN32 */
228 607 std::sort(files.begin(), files.end());
229 608 BOOST_FOREACH(const String& cpath, files) {
233 612 std::sort(dirs.begin(), dirs.end());
234 613 BOOST_FOREACH(const String& cpath, dirs) {
236 $3 = std::vector of length 11, capacity 16 = {{static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/agent.conf"}, {static NPos = 18446744073709551615,
237 m_Data = "/etc/icinga2/conf.d/commands.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/downtimes.conf"}, {static NPos = 18446744073709551615,
238 m_Data = "/etc/icinga2/conf.d/groups.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/notifications.conf"}, {static NPos = 18446744073709551615,
239 m_Data = "/etc/icinga2/conf.d/satellite.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/services.conf"}, {static NPos = 18446744073709551615,
240 m_Data = "/etc/icinga2/conf.d/templates.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/test.conf"}, {static NPos = 18446744073709551615,
241 m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}
244 ### Core Dump <a id="development-debug-core-dump"></a>
246 When the Icinga 2 daemon crashes with a `SIGSEGV` signal
247 a core dump file should be written. This will help
248 developers to analyze and fix the problem.
250 #### Core Dump File Size Limit <a id="development-debug-core-dump-limit"></a>
252 This requires setting the core dump file size to `unlimited`.
258 systemctl edit icinga2.service
264 systemctl daemon-reload
266 systemctl restart icinga2
272 vim /etc/init.d/icinga2
276 service icinga2 restart
281 Verify that the Icinga 2 process core file size limit is set to `unlimited`.
284 for pid in $(pidof icinga2); do cat /proc/$pid/limits; done
287 Max core file size unlimited unlimited bytes
291 #### Core Dump Kernel Format <a id="development-debug-core-dump-format"></a>
293 The Icinga 2 daemon runs with the SUID bit set. Therefore you need
294 to explicitly enable core dumps for SUID on Linux.
297 sysctl -w fs.suid_dumpable=2
300 Adjust the coredump kernel format and file location on Linux:
303 sysctl -w kernel.core_pattern=/var/lib/cores/core.%e.%p
305 install -m 1777 -d /var/lib/cores
311 sysctl -w kern.corefile=/cores/core.%P
316 #### Core Dump Analysis <a id="development-debug-core-dump-analysis"></a>
318 Once Icinga 2 crashes again a new coredump file will be written. Please
319 attach this file to your bug report in addition to the general details.
321 Simple test case for a `SIGSEGV` simulation with `sleep`:
328 gdb `which sleep` /var/lib/cores/core.sleep.<PID>
330 rm /var/lib/cores/core.sleep.*
336 gdb /usr/lib64/icinga2/sbin/icinga2 core.icinga2.<PID>
340 ### LLDB as Debugger <a id="development-debug-lldb"></a>
342 LLDB is available on macOS with the Xcode command line tools.
345 $ xcode-select --install
348 In order to run Icinga 2 with LLDB you need to pass the binary as argument.
351 lldb -- /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
358 > b icinga::Checkable::ProcessCheckResult
391 Up/down in stacktrace:
400 ## Develop Icinga 2 <a id="development-develop"></a>
402 Icinga 2 can be built on many platforms such as Linux, Unix and Windows.
403 There are limitations in terms of support, e.g. Windows is only supported for agents,
404 not a full-featured master or satellite.
406 Before you start with actual development, there is a couple of pre-requisites.
408 ### Choose your Editor <a id="development-develop-choose-editor"></a>
410 Icinga 2 can be developed with your favorite editor. Icinga developers prefer
414 - CLion (macOS, Linux)
415 - MS Visual Studio (Windows)
418 Editors differ on the functionality. The more helpers you get for C++ development,
419 the faster your development workflow will be.
422 #### Whitespace Cleanup <a id="development-develop-choose-editor-whitespaces"></a>
424 Patches must be cleaned up and follow the indent style (tabs instead of spaces).
425 You should also remove any training whitespaces.
427 `git diff` allows to highlight such.
433 whitespace = red reverse
435 whitespace=fix,-indent-with-non-tab,trailing-space,cr-at-eol
438 `vim` also can match these and visually alert you to remove them.
443 highlight ExtraWhitespace ctermbg=red guibg=red
444 match ExtraWhitespace /\s\+$/
445 autocmd BufWinEnter * match ExtraWhitespace /\s\+$/
446 autocmd InsertEnter * match ExtraWhitespace /\s\+\%#\@<!$/
447 autocmd InsertLeave * match ExtraWhitespace /\s\+$/
448 autocmd BufWinLeave * call clearmatches()
451 ### Get to know the architecture <a id="development-develop-get-to-know-the-architecture"></a>
453 Icinga 2 can run standalone or in distributed environments. It contains a whole lot
454 more than a simple check execution engine.
456 Read more about it in the [Technical Concepts](19-technical-concepts.md#technical-concepts) chapter.
458 ### Get to know the code <a id="development-develop-get-to-know-the-code"></a>
460 First off, you really need to know C++ and portions of C++11 and the boost libraries.
461 Best is to start with a book or online tutorial to get into the basics.
462 Icinga developers gained their knowledge through studies, training and self-teaching
463 code by trying it out and asking senior developers for guidance.
465 Here's a few books we can recommend:
467 * [Accelerated C++: Practical Programming by Example](https://www.amazon.com/Accelerated-C-Practical-Programming-Example/dp/020170353X) (Andrew Koenig, Barbara E. Moo)
468 * [Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) (Scott Meyers)
469 * [Der C++ Programmierer](https://www.amazon.de/Programmierer-lernen-Professionell-anwenden-L%C3%B6sungen/dp/3446416447), German (Ulrich Breymann)
470 * [C++11 programmieren](https://www.amazon.de/gp/product/3836217325/), German (Torsten T. Will)
472 In addition, it is a good bet to also know SQL when diving into backend development.
474 * [SQL Performance Explained](https://www.amazon.de/gp/product/3950307826/) (Markus Winand)
476 Last but not least, if you are developing on Windows, get to know the internals about services and the Win32 API.
479 ### Design Patterns <a id="development-develop-design-patterns"></a>
481 Icinga 2 heavily relies on object-oriented programming and encapsulates common
482 functionality into classes and objects. It also uses modern programming techniques
483 to e.g. work with shared pointer memory management.
485 Icinga 2 consists of libraries bundled into the main binary. Therefore you'll
486 find many code parts in the `lib/` directory wheras the actual application is
487 built from `icinga-app/`. Accompanied with Icinga 2, there's the Windows plugins
488 which are standalone and compiled from `plugins/`.
490 Library | Description
491 ---------------|------------------------------------
492 base | Objects, values, types, streams, tockets, TLS, utilities, etc.
493 config | Configuration compiler, expressions, etc.
494 cli | CLI (sub) commands and helpers.
495 icinga | Icinga specific objects and event handling.
496 remote | Cluster and HTTP client/server and REST API related code.
497 checker | Checker feature, check scheduler.
498 notification | Notification feature, notification scheduler.
499 methods | Command execution methods, plugins and built-in checks.
500 perfdata | Performance data related, including Graphite, Elastic, etc.
501 db\_ido | IDO database abstraction layer.
502 db\_ido\_mysql | IDO database driver for MySQL.
503 db\_ido\_pgsql | IDO database driver for PgSQL.
504 mysql\_shin | Library stub for linking against the MySQL client libraries.
505 pgsql\_shim | Library stub for linking against the PgSQL client libraries.
507 #### Class Compiler <a id="development-develop-design-patterns-class-compiler"></a>
509 Another thing you will recognize are the `.ti` files which are compiled
510 by our own class compiler into actual source code. The meta language allows
511 developers to easily add object attributes and specify their behaviour.
513 Some object attributes need to be stored over restarts in the state file
514 and therefore have the `state` attribute set. Others are treated as `config`
515 attribute and automatically get configuration validation functions created.
516 Hidden or read-only REST API attributes are marked with `no_user_view` and
519 The most beneficial thing are getters and setters being generated. The actual object
520 inherits from `ObjectImpl<TYPE>` and therefore gets them "for free".
525 vim lib/perfdata/gelfwriter.ti
529 vim lib/perfdata/gelfwriter.cpp
531 if (GetEnableTls()) {
534 The logic is hidden in `tools/mkclass/` in case you want to learn more about it.
535 The first steps during CMake & make also tell you about code generation.
538 ### Builds: CMake <a id="development-develop-builds-cmake"></a>
540 In its early development stages in 2012, Icinga 2 was built with autoconf/automake
541 and separate Windows project files. We've found this very fragile, and have changed
542 this into CMake as our build tool.
544 The most common benefits:
546 * Everything is described in CMakeLists.txt in each directory
547 * CMake only needs to know that a sub directory needs to be included.
548 * The global CMakeLists.txt acts as main entry point for requirement checks and library/header includes.
549 * Separate binary build directories, the actual source tree stays clean.
550 * CMake automatically generates a Visual Studio project file `icinga2.sln` on Windows.
552 ### Builds: Unity Builds <a id="development-develop-builds-unity-builds"></a>
554 Another thing you should be aware of: Unity builds on and off.
556 Typically, we already use caching mechanisms to reduce recompile time with ccache.
557 For release builds, there's always a new build needed as the difference is huge compared
558 to a previous (major) release.
560 Therefore we've invented the Unity builds, which basically concatenates all source files
561 into one big library source code file. The compiler then doesn't need to load the many small
562 files but compiles and links this huge one.
564 Unity builds require more memory which is why you should disable them for development
565 builds in small sized VMs (Linux, Windows) and also Docker containers.
567 There's a couple of header files which are included everywhere. If you touch/edit them,
568 the cache is invalidated and you need to recompile a lot more files then. `base/utility.hpp`
569 and `remote/zone.hpp` are good candidates for this.
572 ### Linux Dev Environment <a id="development-linux-dev-env"></a>
574 Based on CentOS 7, we have an early draft available inside the Icinga Vagrant boxes:
575 [centos7-dev](https://github.com/Icinga/icinga-vagrant/tree/master/centos7-dev).
577 If you're compiling Icinga 2 natively without any virtualization layer in between,
578 this usually is faster. This is also the reason why developers on macOS prefer native builds
579 over Linux or Windows VMs. Don't forget to test the actual code on Linux later! Socket specific
580 stuff like `epoll` is not available on Unix kernels.
582 Depending on your workstation and environment, you may either develop and run locally,
583 use a container deployment pipeline or put everything in a high end resource remote VM.
585 Fork https://github.com/Icinga/icinga2 into your own repository, e.g. `https://github.com/dnsmichi/icinga2`.
587 Create two build directories for different binary builds.
589 * `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.
590 * `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.
593 mkdir -p release debug
596 Proceed with the specific distribution examples below.
598 * [CentOS 7](21-development.md#development-linux-dev-env-centos)
599 * [Debian 9](21-development.md#development-linux-dev-env-debian)
602 #### CentOS 7 <a id="development-linux-dev-env-centos"></a>
605 yum -y install gdb git bash-completion htop rpmdevtools \
606 ccache cmake make gcc-c++ flex bison \
607 openssl-devel boost-devel systemd-devel mysql-devel \
608 postgresql-devel libedit-devel libstdc++-devel
612 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
614 ln -s /bin/ccache /usr/local/bin/gcc
615 ln -s /bin/ccache /usr/local/bin/g++
617 git clone https://github.com/icinga/icinga2.git && cd icinga2
621 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
623 make -j2 install -C debug
628 chown -R icinga:icinga /usr/local/icinga2/var/
630 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
631 /usr/local/icinga2/sbin/icinga2 api setup
632 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
634 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
637 ##### Debian 9 <a id="development-linux-dev-env-debian"></a>
640 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
642 ln -s /usr/bin/ccache /usr/local/bin/gcc
643 ln -s /usr/bin/ccache /usr/local/bin/g++
647 useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
649 git clone https://github.com/icinga/icinga2.git && cd icinga2
653 cmake .. -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DICINGA2_PLUGINDIR=/usr/local/sbin
655 make -j2 install -C debug
660 chown -R icinga:icinga /usr/local/icinga2/var/
662 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
663 /usr/local/icinga2/sbin/icinga2 api setup
664 vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
666 gdb --args /usr/local/icinga2/lib/icinga2/sbin/icinga2 daemon
671 ### macOS Dev Environment <a id="development-macos-dev-env"></a>
673 It is advised to use Homebrew to install required build dependencies.
674 Macports have been reported to work as well, typically you'll get more help
675 with Homebrew from Icinga developers.
677 #### Users and Groups
679 First off, create the following from `Settings - Users & Groups`:
682 * Groups: `icinga` with `icinga` as member
683 * Groups: `icingaweb2`
685 Then disallow login for these users.
689 list Local/Default/Users
690 read Local/Default/Users/icinga
691 change Local/Default/Users/icinga UserShell /bin/bash /usr/bin/false
692 sudo dscl . create /Users/icinga IsHidden 1
693 sudo dseditgroup -o edit -a _www -t user icingaweb2
698 OpenSSL 1.0.x doesn't build anymore, so we're explicitly using 1.1.x here.
701 brew install ccache boost cmake bison flex yajl openssl@1.1 mysql-connector-c++ postgresql libpq
707 sudo mkdir /opt/ccache
709 sudo ln -s `which ccache` /opt/ccache/clang
710 sudo ln -s `which ccache` /opt/ccache/clang++
714 # ccache is managed with symlinks to avoid collision with cgo
715 export PATH="/opt/ccache:$PATH"
722 We will build two different flavors on macOS.
725 mkdir -p release debug
728 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 ..
732 sudo make -j4 install -C debug
737 This is derived from dnsmichi's flavour and not generally best practice.
742 export PATH=/usr/local/icinga2/sbin/:$PATH
743 source /usr/local/icinga2/etc/bash_completion.d/icinga2
745 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"
747 export I2_DEBUG="-DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF $I2_GENERIC"
748 export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DICINGA2_UNITY_BUILD=ON $I2_GENERIC"
750 alias i2_debug="mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j4; sudo make -j4 install; cd .."
751 alias i2_release="mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j4; sudo make -j4 install; cd .."
759 chown -R icinga:icinga /usr/local/icinga2
760 chown -R icinga:_www /usr/local/icinga2/var/run/icinga2/cmd
768 brew install nagios-plugins
770 sudo vim /usr/local/icinga2/etc/icinga2/constants.conf
771 const PluginDir = "/usr/local/sbin"
774 #### Databases: MariaDB
778 ln -sfv /usr/local/opt/mariadb/*.plist ~/Library/LaunchAgents
779 launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist
780 mysql_secure_installation
788 password = supersecurerootpassword
791 ln -s /Users/michi/.my.cnf $HOME/.my.cnf
796 cd $HOME/coding/icinga/icinga2
800 CREATE DATABASE icinga;
801 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
803 sudo mysql icinga < lib/db_ido_mysql/schema/mysql.sql
809 ### Windows Dev Environment <a id="development-windows-dev-env"></a>
811 The following sections explain how to setup the required build tools
812 and how to run and debug the code.
816 Open an administrative command prompt (Win key, type “cmd”, right-click and “run as administrator”) and paste the following instructions:
819 @powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
824 Thanks to Microsoft they’ll now provide their Professional Edition of Visual Studio 2017
825 as community version, free for use for open source projects such as Icinga.
826 The installation requires ~9GB disk space. [Download](https://www.visualstudio.com/downloads/)
827 the web installer and start the installation.
829 You need a free Microsoft account to download and also store your preferences.
831 Choose the following minimal set:
833 * .NET Framework 4.x SDK
835 * Visual Studio C++ core features
837 * Windows 10 SDK (10.0.10240.0 - required)
838 * Just-in-time debugger
839 * Windows 8 SDK (includes mscoree.lib required by clrchecktask)
841 * Windows Universal C Runtime
843 * .NET Framework 3.5 development tools
844 * Github extension for Visual Studio
846 After a while, Visual Studio will be ready.
848 #### .NET Framework 3.5
850 Windows 10 only have .NET Framework >= 4.6 installed by default, the Icinga Agent Wizard is built on .NET Framework 2.0 which is not included in .NET Framework 4.6. Thankfully Windows 10 have .NET Framework 3.5 (which includes .NET Framework 2.0) as a component on board, you just need to activate it.
852 Go to `Control Panel` -> `Programs` -> `Turn Windows features on or off`. Tick `.NET Framework 3.5 (includes .NET 2.0 and 3.0)` and wait until the installation process succseded.
856 Install it using [chocolatey](https://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html):
859 choco install -y winflexbison
862 Chocolatey installs these tools into the hidden directory `C:\ProgramData\chocolatey\lib\winflexbison\tools`.
866 Icinga 2 requires the OpenSSL library. [Download](http://slproweb.com/products/Win32OpenSSL.html)
867 and install it into the default path.
869 Once asked for `Copy OpenSSLs DLLs to` select `The Windows system directory`. That way CMake/Visual Studio
870 will automatically detect them for builds and packaging.
874 > We cannot use the chocolatey package as this one does not provide any development headers.
876 > Choose 1.0.2 LTS from manual downloads for best compatibility if unsure.
880 In order to use the boost development header and library files you need to [download](http://www.boost.org/users/download/)
881 Boost and then extract it to e.g. `C:\boost_1_65_1`.
885 > Just use `C:`, the zip file already contains the sub folder. Extraction takes a while,
886 > the archive contains more than 10k files.
888 For integrating Boost into Visual Studio 2017, open the `Developer Command Prompt` from the start menu,
889 and navigate to `C:\boost_1_65_1`.
891 Execute `bootstrap.bat` first.
898 Once finished, specify the required `toolset` to compile boost against Visual Studio.
899 This takes quite some time in a Windows VM.
904 b2 --toolset=msvc-14.0
910 b2 --toolset=msvc-14.1
915 TortoiseGit provides a graphical integration into the Windows explorer. This makes it easier to checkout, commit
918 [Download](https://tortoisegit.org/download/) TortoiseGit on your system.
920 In order to clone via Git SSH you also need to create a new directory called `.ssh`
921 inside your user's home directory.
922 Therefore open a command prompt (win key, type `cmd`, enter) and run `mkdir .ssh`.
923 Add your `id_rsa` private key and `id_rsa.pub` public key files into that directory.
925 Start the setup routine and choose `OpenSSH` as default secure transport when asked.
927 Open a Windows Explorer window and navigate into
929 Version | Project Location
930 --------------------|------------------------------
931 Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects`
932 Visual Studio 2017+ | `C:\Users\michi\source\repos`
934 Right click and select `Git Clone` from the context menu.
936 Use `ssh://git@github.com/icinga/icinga2.git` for SSH clones, `https://github.com/icinga/icinga2.git` otherwise.
940 Icinga 2 uses CMake to manage the build environment. You can generate the Visual Studio project files
941 using CMake. [Download](https://cmake.org/download/) and install CMake. Select to add it to PATH for all users
944 Once setup is completed, open a command prompt and navigate to
949 cd C:\Users\<username>\Documents\Visual Studio 2015\Projects\icinga2
955 cd C:\Users\michi\source\repos
958 Run CMake with the following command. This generates a new Visual Studio project file called `icinga2.sln`.
960 You need to specify the previously installed component paths:
962 Variable | Value | Description
963 ----------------------|----------------------------------------------------------------------|-------------------------------------------------------
964 `BOOST_ROOT` | `C:\boost_1_65_1` | Root path where you've extracted and compiled Boost.
965 `BISON_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe` | Path to the Bison executable.
966 `FLEX_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe` | Path to the Flex executable.
967 `ICINGA2_WITH_MYSQL` | OFF | Requires extra setup for MySQL if set to `ON`. Not supported for client setups.
968 `ICINGA2_WITH_PGSQL` | OFF | Requires extra setup for PgSQL if set to `ON`. Not supported for client setups.
969 `ICINGA2_UNITY_BUILD` | OFF | Disable unity builds for development environments.
971 Tip: If you have previously opened a terminal, run `refreshenv` to re-read updated PATH variables.
974 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
977 Best is write a small batch/Powershell script which just executes these lines.
980 #### Icinga 2 in Visual Studio
984 Version | Project location
985 --------------------|-------------------------
986 Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2`
987 Visual Studio 2017+ | `C:\Users\michi\source\repos\icinga2`
989 Open `icinga2.sln`. Log into Visual Studio when asked.
991 On the right panel, select to build the `Bin/icinga-app` solution.
993 The executable binaries are located in `Bin\Release\Debug` in your `icinga2`
996 Navigate there and run `icinga2.exe --version`.
998 Example for Visual Studio 2017:
1001 cd C:\Users\michi\source\repos\icinga2\Bin\Release\Debug
1002 icinga2.exe --version
1006 #### Release Package
1008 CMake uses CPack and NSIS to create the setup executable including all binaries and libraries
1009 in addition to setup dialogues and configuration. Therefore we’ll need to install [NSIS](http://nsis.sourceforge.net/Download)
1012 We also need to install the Windows Installer XML (WIX) toolset.
1015 choco install -y wixtoolset
1018 Once completed open an administrative shell and navigate to your Visual Studio project.
1019 Let CMake to build a release package.
1022 cd "c:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2"
1023 cmake --build . --target PACKAGE --config Release
1026 Note: This will still use the debug builds. A yet more clean approach
1027 is to run CMake with changed release parameters beforehand and then
1028 re-run the release package builder.
1031 C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2>
1032 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
1034 cmake --build . --target PACKAGE --config Release
1037 Again, put these lines into a batch/Powershell script and execute that.
1041 ### Embedded Dev Env: Pi <a id="development-embedded-dev-env"></a>
1045 > This isn't officially supported yet, just a few hints how you can do it yourself.
1047 The following examples source from armhf on Raspberry Pi.
1052 apt install -y ccache
1054 /usr/sbin/update-ccache-symlinks
1056 echo 'export PATH="/usr/lib/ccache:$PATH"' | tee -a ~/.bashrc
1058 source ~/.bashrc && echo $PATH
1063 Copy the icinga2 source code into `$HOME/icinga2`. Clone the `deb-icinga2` repository into `debian/`.
1066 git clone https://github.com/Icinga/icinga2 $HOME/icinga2
1067 git clone https://github.com/Icinga/deb-icinga2 $HOME/icinga2/debian
1070 Then build a Debian package and install it like normal.
1072 dpkg-buildpackage -uc -us
1075 ## Package Builds <a id="development-package-builds"></a>
1077 This documentation is explicitly meant for packagers and the Icinga
1078 build infrastructure.
1080 The following requirements need to be fulfilled in order to build the
1081 Icinga application using a dist tarball (including notes for distributions):
1084 * GNU make (make) or ninja-build
1085 * C++ compiler which supports C++11
1086 - RHEL/Fedora/SUSE: gcc-c++ >= 4.7 (extra Developer Tools on RHEL5/6 see below)
1087 - Debian/Ubuntu: build-essential
1088 - Alpine: build-base
1089 - you can also use clang++
1091 * OpenSSL library and header files >= 1.0.1
1092 - RHEL/Fedora: openssl-devel
1093 - SUSE: libopenssl-devel (for SLES 11: libopenssl1-devel)
1094 - Debian/Ubuntu: libssl-dev
1095 - Alpine: libressl-dev
1096 * Boost library and header files >= 1.53.0
1097 - RHEL/Fedora: boost153-devel
1098 - Debian/Ubuntu: libboost-all-dev
1101 * GNU flex (flex) >= 2.5.35
1103 - Only required when using Systemd
1104 - Debian/Ubuntu: libsystemd-dev
1105 - RHEL/Fedora: systemd-devel
1107 ### Optional features <a id="development-package-builds-optional-features"></a>
1109 * MySQL (disable with CMake variable `ICINGA2_WITH_MYSQL` to `OFF`)
1110 - RHEL/Fedora: mysql-devel
1111 - SUSE: libmysqlclient-devel
1112 - Debian/Ubuntu: default-libmysqlclient-dev | libmysqlclient-dev
1113 - Alpine: mariadb-dev
1114 * PostgreSQL (disable with CMake variable `ICINGA2_WITH_PGSQL` to `OFF`)
1115 - RHEL/Fedora: postgresql-devel
1116 - Debian/Ubuntu: libpq-dev
1117 - postgresql-dev on Alpine
1118 * YAJL (Faster JSON library)
1119 - RHEL/Fedora: yajl-devel
1120 - Debian: libyajl-dev
1122 * libedit (CLI console)
1123 - RHEL/Fedora: libedit-devel on CentOS (RHEL requires rhel-7-server-optional-rpms)
1124 - Debian/Ubuntu/Alpine: libedit-dev
1125 * Termcap (only required if libedit doesn't already link against termcap/ncurses)
1126 - RHEL/Fedora: libtermcap-devel
1127 - Debian/Ubuntu: (not necessary)
1129 ### Special requirements <a id="development-package-builds-special-requirements"></a>
1131 **FreeBSD**: libexecinfo (automatically used when Icinga 2 is installed via port or package)
1133 **RHEL6**: Requires a newer boost version which is available on packages.icinga.com
1134 with a version suffixed name.
1136 ### Runtime user environment <a id="development-package-builds-runtime-user-env"></a>
1138 By default Icinga will run as user `icinga` and group `icinga`. Additionally the
1139 external command pipe and livestatus features require a dedicated command group
1140 `icingacmd`. You can choose your own user/group names and pass them to CMake
1141 using the `ICINGA2_USER`, `ICINGA2_GROUP` and `ICINGA2_COMMAND_GROUP` variables.
1145 # groupadd icingacmd
1146 # useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
1149 On Alpine (which uses ash busybox) you can run:
1152 # addgroup -S icinga
1153 # addgroup -S icingacmd
1154 # adduser -S -D -H -h /var/spool/icinga2 -s /sbin/nologin -G icinga -g icinga icinga
1155 # adduser icinga icingacmd
1158 Add the web server user to the icingacmd group in order to grant it write
1159 permissions to the external command pipe and livestatus socket:
1162 # usermod -a -G icingacmd www-data
1165 Make sure to replace "www-data" with the name of the user your web server
1168 ### Building Icinga 2: Example <a id="development-package-builds-example"></a>
1170 Once you have installed all the necessary build requirements you can build
1171 Icinga 2 using the following commands:
1174 $ mkdir release && cd release
1178 $ make install -C release
1181 You can specify an alternative installation prefix using `-DCMAKE_INSTALL_PREFIX`:
1184 $ cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2
1187 ### CMake Variables <a id="development-package-builds-cmake-variables"></a>
1189 In addition to `CMAKE_INSTALL_PREFIX` here are most of the supported Icinga-specific cmake variables.
1191 For all variables regarding defaults paths on in CMake, see
1192 [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html).
1194 Also see `CMakeLists.txt` for details.
1196 **System Environment**
1197 - `CMAKE_INSTALL_SYSCONFDIR`: The configuration directory; defaults to `CMAKE_INSTALL_PREFIX/etc`
1198 - `CMAKE_INSTALL_LOCALSTATEDIR`: The state directory; defaults to `CMAKE_INSTALL_PREFIX/var`
1199 - `ICINGA2_CONFIGDIR`: Main config directory; defaults to `CMAKE_INSTALL_SYSCONFDIR/icinga2` usually `/etc/icinga2`
1200 - `ICINGA2_CACHEDIR`: Directory for cache files; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/cache/icinga2` usually `/var/cache/icinga2`
1201 - `ICINGA2_DATADIR`: Data directory for the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/lib/icinga2` usually `/var/lib/icinga2`
1202 - `ICINGA2_LOGDIR`: Logfiles of the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/log/icinga2 usually `/var/log/icinga2`
1203 - `ICINGA2_SPOOLDIR`: Spooling directory ; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/spool/icinga2` usually `/var/spool/icinga2`
1204 - `ICINGA2_INITRUNDIR`: Runtime data for the init system; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/run/icinga2` usually `/run/icinga2`
1205 - `ICINGA2_GIT_VERSION_INFO`: Whether to use Git to determine the version number; defaults to `ON`
1206 - `ICINGA2_USER`: The user Icinga 2 should run as; defaults to `icinga`
1207 - `ICINGA2_GROUP`: The group Icinga 2 should run as; defaults to `icinga`
1208 - `ICINGA2_COMMAND_GROUP`: The command group Icinga 2 should use; defaults to `icingacmd`
1209 - `ICINGA2_SYSCONFIGFILE`: Where to put the config file the initscript/systemd pulls it's dirs from;
1210 defaults to `CMAKE_INSTALL_PREFIX/etc/sysconfig/icinga2`
1211 - `ICINGA2_PLUGINDIR`: The path for the Monitoring Plugins project binaries; defaults to `/usr/lib/nagios/plugins`
1213 **Build Optimization**
1214 - `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.
1215 - `ICINGA2_LTO_BUILD`: Whether to use link time optimization (LTO); defaults to `OFF`
1218 - `USE_SYSTEMD=ON|OFF`: Use systemd or a classic SysV initscript; defaults to `OFF`
1219 - `INSTALL_SYSTEMD_SERVICE_AND_INITSCRIPT=ON|OFF` Force install both the systemd service definition file
1220 and the SysV initscript in parallel, regardless of how `USE_SYSTEMD` is set.
1221 Only use this for special packaging purposes and if you know what you are doing.
1225 - `ICINGA2_WITH_CHECKER`: Determines whether the checker module is built; defaults to `ON`
1226 - `ICINGA2_WITH_COMPAT`: Determines whether the compat module is built; defaults to `ON`
1227 - `ICINGA2_WITH_DEMO`: Determines whether the demo module is built; defaults to `OFF`
1228 - `ICINGA2_WITH_HELLO`: Determines whether the hello module is built; defaults to `OFF`
1229 - `ICINGA2_WITH_LIVESTATUS`: Determines whether the Livestatus module is built; defaults to `ON`
1230 - `ICINGA2_WITH_NOTIFICATION`: Determines whether the notification module is built; defaults to `ON`
1231 - `ICINGA2_WITH_PERFDATA`: Determines whether the perfdata module is built; defaults to `ON`
1232 - `ICINGA2_WITH_TESTS`: Determines whether the unit tests are built; defaults to `ON`
1234 **MySQL or MariaDB:**
1236 The following settings can be tuned for the MySQL / MariaDB IDO feature.
1238 - `ICINGA2_WITH_MYSQL`: Determines whether the MySQL IDO module is built; defaults to `ON`
1239 - `MYSQL_CLIENT_LIBS`: Client implementation used (mysqlclient / mariadbclient); defaults searches for `mysqlclient` and `mariadbclient`
1240 - `MYSQL_INCLUDE_DIR`: Directory containing include files for the mysqlclient; default empty -
1241 checking multiple paths like `/usr/include/mysql`
1243 See [FindMySQL.cmake](third-party/cmake/FindMySQL.cmake) for the implementation.
1247 The following settings can be tuned for the PostgreSQL IDO feature.
1249 - `ICINGA2_WITH_PGSQL`: Determines whether the PostgreSQL IDO module is built; defaults to `ON`
1250 - `PostgreSQL_INCLUDE_DIR`: Top-level directory containing the PostgreSQL include directories
1251 - `PostgreSQL_LIBRARY`: File path to PostgreSQL library : libpq.so (or libpq.so.[ver] file)
1253 See [FindMySQL.cmake](third-party/cmake/FindPostgreSQL.cmake) for the implementation.
1255 **Version detection:**
1257 CMake determines the Icinga 2 version number using `git describe` if the
1258 source directory is contained in a Git repository. Otherwise the version number
1259 is extracted from the [VERSION](VERSION) file. This behavior can be
1260 overridden by creating a file called `icinga-version.h.force` in the source
1261 directory. Alternatively the `-DICINGA2_GIT_VERSION_INFO=OFF` option for CMake
1262 can be used to disable the usage of `git describe`.
1265 ### Building RPMs <a id="development-package-builds-rpms"></a>
1267 #### Build Environment on RHEL, CentOS, Fedora, Amazon Linux
1269 Setup your build environment:
1272 yum -y install rpmdevtools
1275 #### Build Environment on SuSE/SLES
1280 zypper addrepo http://download.opensuse.org/repositories/devel:tools/SLE_12_SP4/devel:tools.repo
1282 zypper install rpmdevtools spectool
1288 zypper addrepo http://download.opensuse.org/repositories/devel:tools/openSUSE_Leap_15.0/devel:tools.repo
1290 zypper install rpmdevtools spectool
1293 #### Package Builds <a id="development-package-builds-rpms-package-builds"></a>
1295 Prepare the rpmbuild directory tree:
1305 curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o $HOME/rpmbuild/SPECS/icinga2.spec
1310 > The above command builds snapshot packages. Change to the `release` branch
1311 > for release package builds.
1313 Copy the tarball to `rpmbuild/SOURCES` e.g. by using the `spectool` binary
1314 provided with `rpmdevtools`:
1317 cd $HOME/rpmbuild/SOURCES
1318 spectool -g ../SPECS/icinga2.spec
1323 Install the build dependencies. Example for CentOS 7:
1326 yum -y install libedit-devel ncurses-devel gcc-c++ libstdc++-devel openssl-devel \
1327 cmake flex bison boost-devel systemd mysql-devel postgresql-devel httpd \
1328 selinux-policy-devel checkpolicy selinux-policy selinux-policy-doc
1331 Note: If you are using Amazon Linux, systemd is not required.
1333 A shorter way is available using the `yum-builddep` command on RHEL based systems:
1336 yum-builddep SPECS/icinga2.spec
1342 rpmbuild -ba SPECS/icinga2.spec
1345 #### Additional Hints <a id="development-package-builds-rpms-additional-hints"></a>
1347 ##### SELinux policy module
1349 The following packages are required to build the SELinux policy module:
1352 * selinux-policy (selinux-policy on CentOS 6, selinux-policy-devel on CentOS 7)
1353 * selinux-policy-doc
1357 The RedHat Developer Toolset is required for building Icinga 2 beforehand.
1358 This contains a modern version of flex and a C++ compiler which supports
1361 cat >/etc/yum.repos.d/devtools-2.repo <<REPO
1362 [testing-devtools-2-centos-\$releasever]
1363 name=testing 2 devtools for CentOS $releasever
1364 baseurl=https://people.centos.org/tru/devtools-2/\$releasever/\$basearch/RPMS
1369 Dependencies to devtools-2 are used in the RPM SPEC, so the correct tools
1370 should be used for building.
1372 As an alternative, you can use newer Boost packages provided on
1373 [packages.icinga.com](https://packages.icinga.com/epel).
1375 cat >$HOME/.rpmmacros <<MACROS
1382 If you prefer to build packages offline, a suitable Vagrant box is located
1383 [here](https://atlas.hashicorp.com/mvbcoding/boxes/awslinux/).
1387 The Icinga repository provides the required boost package version and must be
1388 added before building.
1390 ### Build Debian/Ubuntu packages <a id="development-package-builds-deb"></a>
1392 Setup your build environment on Debian/Ubuntu, copy the 'debian' directory from
1393 the Debian packaging Git repository (https://github.com/Icinga/deb-icinga2)
1394 into your source tree and run the following command:
1397 dpkg-buildpackage -uc -us
1400 ### Build Alpine Linux packages <a id="development-package-builds-alpine"></a>
1402 A simple way to setup a build environment is installing Alpine in a chroot.
1403 In this way, you can set up an Alpine build environment in a chroot under a
1404 different Linux distro.
1405 There is a script that simplifies these steps with just two commands, and
1406 can be found [here](https://github.com/alpinelinux/alpine-chroot-install).
1408 Once the build environment is installed, you can setup the system to build
1409 the packages by following [this document](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package).
1411 ### Build Post Install Tasks <a id="development-package-builds-post-install-tasks"></a>
1413 After building Icinga 2 yourself, your package build system should at least run the following post
1414 install requirements:
1416 * enable the `checker`, `notification` and `mainlog` feature by default
1417 * run 'icinga2 api setup' in order to enable the `api` feature and generate SSL certificates for the node
1419 ### Run Icinga 2 <a id="development-package-builds-run-icinga"></a>
1421 Icinga 2 comes with a binary that takes care of loading all the relevant
1422 components (e.g. for check execution, notifications, etc.):
1427 [2016-12-08 16:44:24 +0100] information/cli: Icinga application loader (version: v2.5.4-231-gb10a6b7; debug)
1428 [2016-12-08 16:44:24 +0100] information/cli: Loading configuration file(s).
1429 [2016-12-08 16:44:25 +0100] information/ConfigItem: Committing config item(s).
1433 #### Init Script <a id="development-package-builds-init-script"></a>
1435 Icinga 2 can be started as a daemon using the provided init script:
1438 # /etc/init.d/icinga2
1439 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1442 ### Systemd <a id="development-package-builds-systemd"></a>
1444 If your distribution uses Systemd:
1447 # systemctl {start|stop|reload|status|enable|disable} icinga2
1450 In case the distribution is running Systemd >227, you'll also
1451 need to package and install the `etc/initsystem/icinga2.service.limits.conf`
1452 file into `/etc/systemd/system/icinga2.service.d`.
1454 ### openrc <a id="development-package-builds-openrc"></a>
1456 Or if your distribution uses openrc (like Alpine):
1459 # rc-service icinga2
1460 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1463 Note: the openrc's init.d is not shipped by default.
1464 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.
1465 Those few steps can be followed:
1468 # wget https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd
1469 # mv icinga2.initd /etc/init.d/icinga2
1470 # chmod +x /etc/init.d/icinga2
1473 Icinga 2 reads a single configuration file which is used to specify all
1474 configuration settings (global settings, hosts, services, etc.). The
1475 configuration format is explained in detail in the [doc/](doc/) directory.
1477 By default `make install` installs example configuration files in
1478 `/usr/local/etc/icinga2` unless you have specified a different prefix or
1482 ### Windows Builds <a id="development-package-builds-windows"></a>
1484 The Windows MSI packages are located at https://packages.icinga.com/windows/
1486 #### Requirements <a id="development-package-builds-windows-requirements"></a>
1488 * 32 or 64-bit system
1489 * Visual Studio >= 14 2015
1496 Download the community edition from [visualstudio.com](https://www.visualstudio.com/en/downloads/)
1498 Workloads to install:
1502 ##### OpenSSL for Icinga
1504 Download custom OpenSSL builds from [openssl-windows GitHub project](https://github.com/Icinga/openssl-windows/releases).
1506 You need to install a binary dist version to 'C:\\Program Files\\OpenSSL'.
1508 The Powershell script `.\tools\win32\download-openssl.ps1` can be used for automated downloads.
1512 A simple package manager for Windows, please see [install instructions](https://chocolatey.org/install).
1516 Use Chocolatey, see [package details](https://chocolatey.org/packages/git).
1524 Use Chocolatey, see [package details](https://chocolatey.org/packages/winflexbison3).
1527 choco install winflexbison3
1532 Use Chocolatey, see [package details](https://chocolatey.org/packages/cmake)
1533 or download from: [cmake.org](https://cmake.org/download/)
1541 Use Chocolatey, see [package details](https://chocolatey.org/packages/wixtoolset).
1544 choco install wixtoolset
1549 Download third party Windows binaries from: [boost.org](http://www.boost.org/users/download/)
1551 For example: `https://dl.bintray.com/boostorg/release/1.65.1/binaries/boost_1_65_1-msvc-14.1-64.exe`
1554 * Must match your Visual Studio version!
1555 * CMake might not support the latest Boost version (we used CMake 3.10 and Boost 1_65_1)
1557 Run the installer exe.
1562 Run with VC Native x64 Command Prompt:
1565 powershell .\tools\win32\configure.ps1
1566 powershell .\tools\win32\build.ps1
1567 powershell .\tools\win32\test.ps1
1570 See these scripts for details.
1574 We are building [Icinga 2 with AppVeyor](https://ci.appveyor.com/project/icinga/icinga2) for testing and CI integration.
1576 Please check `appveyor.yml` for instructions.
1580 ## Advanced Development Tips <a id="development-advanced"></a>
1582 ### GDB Pretty Printers <a id="development-advanced-gdb-pretty-printer"></a>
1584 Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required,
1585 so please make sure to update the installation paths accordingly (`pwd`).
1587 $ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
1589 Boost Pretty Printers compatible with Python 3:
1591 $ git clone https://github.com/mateidavid/Boost-Pretty-Printer.git && cd Boost-Pretty-Printer
1592 $ git checkout python-3
1594 /home/michi/.gdb_printers/Boost-Pretty-Printer
1596 Python Pretty Printers:
1598 $ cd ~/.gdb_printers
1599 $ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
1601 Icinga 2 Pretty Printers:
1603 $ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
1604 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
1606 Now you'll need to modify/setup your `~/.gdbinit` configuration file.
1607 You can download the one from Icinga 2 and modify all paths.
1609 Example on Fedora 22:
1611 $ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/gdbinit -O ~/.gdbinit
1618 sys.path.insert(0, '/home/michi/.gdb_printers/icinga2')
1619 from icingadbg import register_icinga_printers
1620 register_icinga_printers()
1625 sys.path.insert(0, '/home/michi/.gdb_printers/python')
1626 from libstdcxx.v6.printers import register_libstdcxx_printers
1628 register_libstdcxx_printers(None)
1635 sys.path.insert(0, '/home/michi/.gdb_printers/Boost-Pretty-Printer')
1637 boost_print.register_printers()
1641 If you are getting the following error when running gdb, the `libstdcxx`
1642 printers are already preloaded in your environment and you can remove
1643 the duplicate import in your `~/.gdbinit` file.
1645 RuntimeError: pretty-printer already registered: libstdc++-v6
1648 ## Development Tests <a id="development-tests"></a>
1650 Build the binaries and run the tests.
1658 Run a specific boost test:
1661 debug/Bin/Debug/boosttest-test-base --run_test=remote_url