tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7073 from Icinga/feature/docs-development-macos-windows 

Improve docs for 2.11: Development, test snapshot packages & installation repos
This commit is contained in:
Michael Friedrich 2019-04-09 14:16:39 +02:00 committed by GitHub
parent e69e72d6af 478f087a3a
commit d459f3448d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 417 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/01-about.md
View File

@ -34,8 +34,7 @@ Please continue reading in the [Contributing chapter](https://github.com/Icinga/
The Git repository is located on [GitHub](https://github.com/Icinga/icinga2).
Icinga 2 is written in C++ and can be built on Linux/Unix and Windows.
Read more about development builds in the [INSTALL.md](https://github.com/Icinga/icinga2/blob/master/INSTALL.md)
file.
Read more about development builds in the [development chapter](21-development.md#development).
## What's New <a id="whats-new"></a>

56
doc/02-getting-started.md
View File

@ -37,6 +37,11 @@ Community repositories:
Packages for distributions other than the ones listed above may also be
available. Please contact your distribution packagers.
> **Note**
>
> Windows is only supported for agent installations. Please refer
> to the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows).
### Package Repositories <a id="package-repositories"></a>
You need to add the Icinga repository to your package management configuration.
@ -47,7 +52,8 @@ The following commands must be executed with `root` permissions unless noted oth
Debian:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
@ -63,7 +69,8 @@ apt-get update
Ubuntu:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
@ -79,7 +86,8 @@ apt-get update
Raspbian:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
@ -92,6 +100,22 @@ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
apt-get update
```
##### Debian Backports Repository <a id="package-repositories-debian-backports"></a>
> **Note**:
>
> This repository is required since v2.11.
Debian Stretch:
```
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list
apt-get update
```
#### RHEL/CentOS/Fedora Repositories <a id="package-repositories-rhel-centos-fedora"></a>
RHEL/CentOS 7:
@ -100,7 +124,7 @@ RHEL/CentOS 7:
yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
```
RHEL/CentOS 6:
RHEL/CentOS 6 x64:
```
yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
@ -112,7 +136,7 @@ Fedora 29:
dnf install https://packages.icinga.com/fedora/icinga-rpm-release-29-latest.noarch.rpm
```
#### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
##### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
The packages for RHEL/CentOS depend on other packages which are distributed
as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
@ -134,6 +158,9 @@ subscription-manager repos --enable rhel-6-server-optional-rpms
#### SLES/OpenSUSE Repositories <a id="package-repositories-sles-opensuse"></a>
The release repository also provides the required Boost 1.66+ packages
since v2.11.
SLES 15/12:
```
@ -143,15 +170,6 @@ zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
zypper ref
```
SLES 11:
```
rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo
zypper ref
```
openSUSE:
```
@ -161,16 +179,6 @@ zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
zypper ref
```
#### SLES Security Repository <a id="package-repositories-sles-security"></a>
The packages for SLES 11 depend on the `openssl1` package which is distributed
as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
#### SLES 12 SDK <a id="package-sles-sdk"></a>
Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
Linux documentation for further information.
#### Alpine Linux Repositories <a id="package-repositories-alpine"></a>
Alpine Linux:

2
doc/15-troubleshooting.md
View File

@ -861,8 +861,6 @@ Fetch the `ca.crt` file from the client node and compare it to your master's `ca
# diff -ur /var/lib/icinga2/certs/ca.crt test-client-ca.crt
```
On SLES11 you'll need to use the `openssl1` command instead of `openssl`.
<!--
### Certificate Signing <a id="troubleshooting-certificate-signing"></a>
-->

15
doc/16-upgrading-icinga-2.md
View File

@ -10,7 +10,13 @@ follow the instructions for v2.7 too.
## Upgrading to v2.11 <a id="upgrading-to-2-11"></a>
### Package Dependencies <a id="upgrading-to-2-11-package-dependencies"></a>
### Packages <a id="upgrading-to-2-11-packages"></a>
EOL distributions where no packages are available with this release:
* SLES 11
* Ubuntu 14 LTS
* RHEL/CentOS 6 x86
#### Added: Boost 1.66+
@ -20,7 +26,12 @@ details, please continue reading in [this issue](https://github.com/Icinga/icing
The package dependencies have been updated for RPM/DEB already.
On platforms where EPEL or Backports cannot satisfy this dependency,
we provide Boost as package on our [package repository](https://packages.icinga.com).
we provide Boost as package on our [package repository](https://packages.icinga.com):
* SLES 12 (this replaces the SDK requirement)
* CentOS 6 x64
* Debian Jessie
* Ubuntu Xenial/Bionic
After upgrade, you may remove the old Boost packages (1.53 or anything above)
if you don't need them anymore.

2
doc/19-technical-concepts.md
View File

@ -905,7 +905,7 @@ below have been collected too. [This thread](https://www.reddit.com/r/cpp/commen
also sheds more light in modern programming techniques.
Our main "problem" with Icinga 2 are modern compilers supporting the full C++11 feature set.
Recent analysis have proven that gcc on CentOS 6 or SLES11 are too old to use modern
Recent analysis have proven that gcc on CentOS 6 are too old to use modern
programming techniques or anything which implemens C++14 at least.
Given the below projects, we are also not fans of wrapping C interfaces into

558
doc/21-development.md
View File

@ -6,6 +6,8 @@ development, package builds and tests.
* [Debug Icinga 2](21-development.md#development-debug)
* [GDB Backtrace](21-development.md#development-debug-gdb-backtrace)
* [Core Dump](21-development.md#development-debug-core-dump)
* [Test Icinga 2](21-development.md#development-tests)
* [Snapshot Packages (Nightly Builds)](21-development.md#development-tests-snapshot-packages)
* [Develop Icinga 2](21-development.md#development-develop)
* [Linux Dev Environment](21-development.md#development-linux-dev-env)
* [macOS Dev Environment](21-development.md#development-macos-dev-env)
@ -15,7 +17,6 @@ development, package builds and tests.
* [DEB](21-development.md#development-package-builds-deb)
* [Windows](21-development.md#development-package-builds-windows)
* [Advanced Tips](21-development.md#development-advanced)
* [Tests](21-development.md#development-tests)
## Debug Icinga 2 <a id="development-debug"></a>
@ -397,6 +398,157 @@ Up/down in stacktrace:
> down
```
## Test Icinga 2 <a id="development-tests"></a>
### Snapshot Packages (Nightly Builds) <a id="development-tests-snapshot-packages"></a>
Icinga provides snapshot packages as nightly builds from [Git master](https://github.com/icinga/icinga2).
These packages contain development code which should be considered "work in progress".
While developers ensure that tests are running fine with CI actions on PRs,
things might break, or changes are not yet documented in the changelog.
You can help the developers and test the snapshot packages, e.g. when larger
changes or rewrites are taking place for a new major version. Your feedback
is very much appreciated.
Snapshot packages are available for all supported platforms including
Linux and Windows and can be obtained from [https://packages.icinga.com](https://packages.icinga.com).
The [Vagrant boxes](https://github.com/Icinga/icinga-vagrant) also use
the Icinga snapshot packages to allow easier integration tests. It is also
possible to use Docker with base OS images and installing the snapshot
packages.
If you encounter a problem, please [open a new issue](https://github.com/Icinga/icinga2/issues/new/choose)
on GitHub and mention that you're testing the snapshot packages.
#### RHEL/CentOS <a id="development-tests-snapshot-packages-rhel"></a>
2.11+ requires the [EPEL repository](02-getting-started.md#package-repositories-rhel-epel) for Boost 1.66+.
In addition to that, the `icinga-rpm-release` package already provides the `icinga-snapshot-build`
repository but it is disabled by default.
```
yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
yum -y install epel-release
yum makecache
yum install --enablerepo=icinga-snapshot-build icinga2
```
#### Debian <a id="development-tests-snapshot-packages-debian"></a>
2.11+ requires Boost 1.66+ which either is provided by the OS, backports or Icinga stable repositories.
It is advised to configure both Icinga repositories, stable and snapshot and selectively
choose the repository with the `-t` flag on `apt-get install`.
```
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \
/etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \
/etc/apt/sources.list.d/${DIST}-icinga.list
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb http://packages.icinga.com/debian icinga-${DIST}-snapshots main" > \
/etc/apt/sources.list.d/${DIST}-icinga-snapshots.list
echo "deb-src http://packages.icinga.com/debian icinga-${DIST}-snapshots main" >> \
/etc/apt/sources.list.d/${DIST}-icinga-snapshots.list
apt-get update
```
On Debian Stretch, you'll also need to add Debian Backports.
```
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list
apt-get update
```
Then install the snapshot packages.
```
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
apt-get install -t icinga-${DIST}-snapshots icinga2
```
#### Ubuntu <a id="development-tests-snapshot-packages-ubuntu"></a>
```
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \
/etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
/etc/apt/sources.list.d/${DIST}-icinga.list
. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
echo "deb https://packages.icinga.com/ubuntu icinga-${DIST}-snapshots main" > \
/etc/apt/sources.list.d/${DIST}-icinga-snapshots.list
echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST}-snapshots main" >> \
/etc/apt/sources.list.d/${DIST}-icinga-snapshots.list
apt-get update
```
Then install the snapshot packages.
```
. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
apt-get install -t icinga-${DIST}-snapshots icinga2
```
#### SLES <a id="development-tests-snapshot-packages-sles"></a>
The required Boost packages are provided with the stable release repository.
```
rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
zypper ref
zypper ar https://packages.icinga.com/SUSE/ICINGA-snapshot.repo
zypper ref
```
Selectively install the snapshot packages using the `-r` parameter.
```
zypper in -r icinga-snapshot-builds icinga2
```
### Unit Tests <a id="development-tests-unit"></a>
Build the binaries and run the tests.
```
make -j4 -C debug
make test -C debug
```
Run a specific boost test:
```
debug/Bin/Debug/boosttest-test-base --run_test=remote_url
```
## Develop Icinga 2 <a id="development-develop"></a>
@ -468,6 +620,7 @@ Here's a few books we can recommend:
* [Accelerated C++: Practical Programming by Example](https://www.amazon.com/Accelerated-C-Practical-Programming-Example/dp/020170353X) (Andrew Koenig, Barbara E. Moo)
* [Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) (Scott Meyers)
* [Boost C++ Application Development Cookbook - Second Edition: Recipes to simplify your application development](https://www.amazon.com/dp/1787282244/ref=cm_sw_em_r_mt_dp_U_dN1OCbERS00EQ) (Antony Polukhin)
* [Der C++ Programmierer](https://www.amazon.de/Programmierer-lernen-Professionell-anwenden-L%C3%B6sungen/dp/3446416447), German (Ulrich Breymann)
* [C++11 programmieren](https://www.amazon.de/gp/product/3836217325/), German (Torsten T. Will)
@ -676,24 +829,7 @@ It is advised to use Homebrew to install required build dependencies.
Macports have been reported to work as well, typically you'll get more help
with Homebrew from Icinga developers.
#### Users and Groups
First off, create the following from `Settings - Users & Groups`:
* Users: `icinga`
* Groups: `icinga` with `icinga` as member
* Groups: `icingaweb2`
Then disallow login for these users.
```
dscl
list Local/Default/Users
read Local/Default/Users/icinga
change Local/Default/Users/icinga UserShell /bin/bash /usr/bin/false
sudo dscl . create /Users/icinga IsHidden 1
sudo dseditgroup -o edit -a _www -t user icingaweb2
```
The idea is to run Icinga with the current user, avoiding root permissions.
#### Requirements
@ -711,48 +847,50 @@ sudo mkdir /opt/ccache
sudo ln -s `which ccache` /opt/ccache/clang
sudo ln -s `which ccache` /opt/ccache/clang++
vim $HOME/.bashrc
vim $HOME/.bash_profile
# ccache is managed with symlinks to avoid collision with cgo
export PATH="/opt/ccache:$PATH"
source $HOME/.bashrc
source $HOME/.bash_profile
```
#### Builds
We will build two different flavors on macOS.
Icinga is built as release (optimized build for packages) and debug (more symbols and details for debugging). Debug builds
typically run slower than release builds and must not be used for performance benchmarks.
```
mkdir -p release debug
cd debug
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 ..
cmake -DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2 -DOPENSSL_INCLUDE_DIR=/usr/local/opt/openssl@1.1/include -DOPENSSL_SSL_LIBRARY=/usr/local/opt/openssl@1.1/lib/libssl.dylib -DOPENSSL_CRYPTO_LIBRARY=/usr/local/opt/openssl@1.1/lib/libcrypto.dylib -DICINGA2_PLUGINDIR=/usr/local/sbin ..
cd ..
make -j4 -C debug
sudo make -j4 install -C debug
make -j4 install -C debug
```
##### Build Aliases
This is derived from dnsmichi's flavour and not generally best practice.
This is derived from [dnsmichi's flavour](https://github.com/dnsmichi/dotfiles) and not generally best practice.
```
vim $HOME/.bashrc
vim $HOME/.bash_profile
export PATH=/usr/local/icinga2/sbin/:$PATH
source /usr/local/icinga2/etc/bash_completion.d/icinga2
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"
export I2_GENERIC="-DCMAKE_INSTALL_PREFIX=/usr/local/icinga/icinga2 -DICINGA2_USER=`id -u -n` -DICINGA2_GROUP=`id -g -n` -DOPENSSL_INCLUDE_DIR=/usr/local/opt/openssl@1.1/include -DOPENSSL_SSL_LIBRARY=/usr/local/opt/openssl@1.1/lib/libssl.dylib -DOPENSSL_CRYPTO_LIBRARY=/usr/local/opt/openssl@1.1/lib/libcrypto.dylib -DICINGA2_PLUGINDIR=/usr/local/sbin -DICINGA2_WITH_PGSQL=OFF"
export I2_DEBUG="-DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF $I2_GENERIC"
export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DICINGA2_UNITY_BUILD=ON $I2_GENERIC"
alias i2_debug="mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j4; sudo make -j4 install; cd .."
alias i2_release="mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j4; sudo make -j4 install; cd .."
alias i2_debug="mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j4; make -j4 install; cd .."
alias i2_release="mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j4; make -j4 install; cd .."
source $HOME/.bashrc
export PATH=/usr/local/icinga/icinga2/sbin/:$PATH
test -f /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2 && source /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2
source $HOME/.bash_profile
```
#### Run
@ -767,18 +905,26 @@ icinga2 daemon
#### Plugins
```
brew install nagios-plugins
brew install monitoring-plugins
sudo vim /usr/local/icinga2/etc/icinga2/constants.conf
const PluginDir = "/usr/local/sbin"
```
#### Backends: Redis
```
brew install redis
brew services start redis
```
#### Databases: MariaDB
```
brew install mariadb
ln -sfv /usr/local/opt/mariadb/*.plist ~/Library/LaunchAgents
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mariadb.plist
mkdir -p /usr/local/etc/my.cnf.d
brew services start mariadb
mysql_secure_installation
```
@ -795,14 +941,20 @@ exit
```
```
cd $HOME/coding/icinga/icinga2
mysql -e 'create database icinga;'
mysql -e "grant all on icinga.* to 'icinga'@'localhost' identified by 'icinga';"
mysql icinga < $HOME/dev/icinga/icinga2/lib/db_ido_mysql/schema/mysql.sql
```
sudo mysql
#### API
CREATE DATABASE icinga;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
quit
sudo mysql icinga < lib/db_ido_mysql/schema/mysql.sql
```
icinga2 api setup
cd /usr/local/icinga/icinga2/var/lib/icinga2/certs
HOST_NAME=mbpmif.int.netways.de
icinga2 pki new-cert --cn ${HOST_NAME} --csr ${HOST_NAME}.csr --key ${HOST_NAME}.key
icinga2 pki sign-csr --csr ${HOST_NAME}.csr --cert ${HOST_NAME}.crt
echo "const NodeName = \"${HOST_NAME}\"" >> /usr/local/icinga/icinga2/etc/icinga2/constants.conf
```
@ -830,28 +982,47 @@ the web installer and start the installation.
You need a free Microsoft account to download and also store your preferences.
Choose the following minimal set:
Choose these individual components on Visual Studio 2017:
* .NET
* .NET Framework 3.5 development tools
* .NET Framework 4.6.1 SDK
* .NET Framework 4.6.1 targeting pack
* Code tools
* Git for Windows
* Static analysis tools
* Compilers, build tools and runtimes
* C# and Visual Basic Roslyn compilers
* C++/CU Support
* VC++ 2017 v141 toolset (x86_64)
* Debugging and testing
* C++ profiling tools
* Just-in-Time debugger
* Development activities
* Visual Studio C++ core features
* Games and Graphics
* Graphics debugger and GPU profiler for DirectX (required by C++ profiling tools)
* SDKs, libraries and frameworks
* Graphics Tools Windows 8.1 SDK (required by C++ profiling tools)
* Windows 10 SDK **10.0.10240.0 - exactly this version**
* Windows 8.1 SDK
* Windows Universal C Runtime
* Uncategorized
* GitHub Extension for Visual Studio
* .NET Framework 4.x SDK
* C# Compiler
* Visual Studio C++ core features
* VC++ toolset
* Windows 10 SDK (10.0.10240.0 - required)
* Just-in-time debugger
* Windows 8 SDK (includes mscoree.lib required by clrchecktask)
* C++/CLI support
* Windows Universal C Runtime
* Git for Windows
* .NET Framework 3.5 development tools
* Github extension for Visual Studio
After a while, Visual Studio will be ready.
#### .NET Framework 3.5
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.
Windows 10 has .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.
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.
Windows 10 provides .NET Framework 3.5 which includes .NET Framework 2.0.
Navigate into `Control Panel` -> `Programs` -> `Turn Windows features on or off`.
Select `.NET Framework 3.5 (includes .NET 2.0 and 3.0)` and wait until the installation process
is finished.
#### Flex and Bison
@ -875,42 +1046,38 @@ will automatically detect them for builds and packaging.
>
> We cannot use the chocolatey package as this one does not provide any development headers.
>
> Choose 1.0.2 LTS from manual downloads for best compatibility if unsure.
> Choose 1.1.1 LTS from manual downloads for best compatibility.
#### Boost
In order to use the boost development header and library files you need to [download](http://www.boost.org/users/download/)
Boost and then extract it to e.g. `C:\boost_1_65_1`.
Boost and then extract it to e.g. `C:\boost_1_69_0`.
> **Note**
>
> Just use `C:`, the zip file already contains the sub folder. Extraction takes a while,
> the archive contains more than 10k files.
> the archive contains more than 70k files.
For integrating Boost into Visual Studio 2017, open the `Developer Command Prompt` from the start menu,
and navigate to `C:\boost_1_65_1`.
In order to integrate Boost into Visual Studio 2017, open the `Developer Command Prompt` from the start menu,
and navigate to `C:\boost_1_69_0`.
Execute `bootstrap.bat` first.
```
cd C:\boost_1_65_1
cd C:\boost_1_69_0
bootstrap.bat
```
Once finished, specify the required `toolset` to compile boost against Visual Studio.
This takes quite some time in a Windows VM.
Visual Studio 2015:
This takes quite some time in a Windows VM. Boost Context uses Assembler code,
which isn't treated as exception safe by the VS compiler. Therefore set the
additional compilation flag according to [this entry](https://lists.boost.org/Archives/boost/2015/08/224570.php).
```
b2 --toolset=msvc-14.0
b2 --toolset=msvc-14.1 asmflags=\safeseh
```
Visual Studio 2017:
```
b2 --toolset=msvc-14.1
```
![Windows Boost Build in VS2017 Development Console](images/development/windows_boost_build_dev_cmd.png)
#### TortoiseGit
@ -928,10 +1095,9 @@ Start the setup routine and choose `OpenSSH` as default secure transport when as
Open a Windows Explorer window and navigate into
Version | Project Location
--------------------|------------------------------
Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects`
Visual Studio 2017+ | `C:\Users\michi\source\repos`
```
cd %HOMEPATH%\source\repos
```
Right click and select `Git Clone` from the context menu.
@ -943,18 +1109,14 @@ Icinga 2 uses CMake to manage the build environment. You can generate the Visual
using CMake. [Download](https://cmake.org/download/) and install CMake. Select to add it to PATH for all users
when asked.
> **Note**
>
> In order to properly detect the Boost libraries, install the CMake 3.14+.
Once setup is completed, open a command prompt and navigate to
Visual Studio 2015
```
cd C:\Users\<username>\Documents\Visual Studio 2015\Projects\icinga2
```
Visual Studio 2017
```
cd C:\Users\michi\source\repos
cd %HOMEPATH%\source\repos
```
Run CMake with the following command. This generates a new Visual Studio project file called `icinga2.sln`.
@ -963,7 +1125,8 @@ You need to specify the previously installed component paths:
Variable | Value | Description
----------------------|----------------------------------------------------------------------|-------------------------------------------------------
`BOOST_ROOT` | `C:\boost_1_65_1` | Root path where you've extracted and compiled Boost.
`BOOST_ROOT` | `C:\boost_1_69_0` | Root path where you've extracted and compiled Boost.
`BOOST_LIBRARYDIR` | `C:\boost_1_69_0\stage` | Path to the static compiled Boost libraries, directory must contain `lib`.
`BISON_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe` | Path to the Bison executable.
`FLEX_EXECUTABLE` | `C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe` | Path to the Flex executable.
`ICINGA2_WITH_MYSQL` | OFF | Requires extra setup for MySQL if set to `ON`. Not supported for client setups.
@ -973,20 +1136,34 @@ Variable | Value
Tip: If you have previously opened a terminal, run `refreshenv` to re-read updated PATH variables.
```
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
cmake . -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Debug -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
```
Best is write a small batch/Powershell script which just executes these lines.
```
@echo off
cd icinga2
mkdir debug
cd debug
del CMakeCache.txt
cmake . -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Debug -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
cmake --build . --target PACKAGE --config Debug
cd ..
```
#### Icinga 2 in Visual Studio
Navigate to
Version | Project location
--------------------|-------------------------
Visual Studio 2015 | `C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2`
Visual Studio 2017+ | `C:\Users\michi\source\repos\icinga2`
```
cd %HOMEPATH%\source\repos\icinga2
```
Open `icinga2.sln`. Log into Visual Studio when asked.
@ -997,10 +1174,8 @@ project directory.
Navigate there and run `icinga2.exe --version`.
Example for Visual Studio 2017:
```
cd C:\Users\michi\source\repos\icinga2\Bin\Release\Debug
cd %HOMEPATH%\source\repos\icinga2\Bin\Release\Debug
icinga2.exe --version
```
@ -1018,11 +1193,12 @@ choco install -y wixtoolset
```
Once completed open an administrative shell and navigate to your Visual Studio project.
Let CMake to build a release package.
```
cd "c:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2"
cmake --build . --target PACKAGE --config Release
cd %HOMEPATH%\source\repos\icinga2
cmake --build debug --target PACKAGE --config Release
```
Note: This will still use the debug builds. A yet more clean approach
@ -1030,14 +1206,37 @@ is to run CMake with changed release parameters beforehand and then
re-run the release package builder.
```
C:\Users\michi\Documents\Visual Studio 2015\Projects\icinga2>
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
cd %HOMEPATH%\source\repos\icinga2
mkdir release
cd release
cmake --build . --target PACKAGE --config Release
cmake .. -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=Release -DBOOST_ROOT=C:\boost_1_69_0 -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=OFF
cd ..
cmake --build release --target PACKAGE --config Release
```
Again, put these lines into a batch/Powershell script and execute that.
```
@echo off
cd icinga2
mkdir release
cd release
del CMakeCache.txt
; set gen=Visual Studio 15 2017 Win64
set gen=Visual Studio 15 2017
cmake .. -G "%gen%" -DCPACK_GENERATOR=WIX -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBOOST_ROOT=C:\boost_1_69_0 -DBOOST_LIBRARYDIR=C:\boost_1_69_0\stage -DBISON_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_bison.exe -DFLEX_EXECUTABLE=C:\ProgramData\chocolatey\lib\winflexbison\tools\win_flex.exe -DICINGA2_WITH_MYSQL=OFF -DICINGA2_WITH_PGSQL=OFF -DICINGA2_UNITY_BUILD=ON
cd ..
cmake --build release --target PACKAGE --config Release
cd ..
```
### Embedded Dev Env: Pi <a id="development-embedded-dev-env"></a>
@ -1085,50 +1284,50 @@ Icinga application using a dist tarball (including notes for distributions):
* cmake >= 2.6
* GNU make (make) or ninja-build
* C++ compiler which supports C++11
- RHEL/Fedora/SUSE: gcc-c++ >= 4.7 (extra Developer Tools on RHEL5/6 see below)
- Debian/Ubuntu: build-essential
- Alpine: build-base
- you can also use clang++
* RHEL/Fedora/SUSE: gcc-c++ >= 4.7 (extra Developer Tools on RHEL5/6 see below)
* Debian/Ubuntu: build-essential
* Alpine: build-base
* you can also use clang++
* pkg-config
* OpenSSL library and header files >= 1.0.1
- RHEL/Fedora: openssl-devel
- SUSE: libopenssl-devel (for SLES 11: libopenssl1-devel)
- Debian/Ubuntu: libssl-dev
- Alpine: libressl-dev
* RHEL/Fedora: openssl-devel
* SUSE: libopenssl-devel
* Debian/Ubuntu: libssl-dev
* Alpine: libressl-dev
* Boost library and header files >= 1.66.0
- RHEL/Fedora: boost166-devel
- Debian/Ubuntu: libboost-all-dev
- Alpine: boost-dev
* RHEL/Fedora: boost166-devel
* Debian/Ubuntu: libboost-all-dev
* Alpine: boost-dev
* GNU bison (bison)
* GNU flex (flex) >= 2.5.35
* systemd headers
- Only required when using systemd
- Debian/Ubuntu: libsystemd-dev
- RHEL/Fedora: systemd-devel
* Only required when using systemd
* Debian/Ubuntu: libsystemd-dev
* RHEL/Fedora: systemd-devel
### Optional features <a id="development-package-builds-optional-features"></a>
* MySQL (disable with CMake variable `ICINGA2_WITH_MYSQL` to `OFF`)
- RHEL/Fedora: mysql-devel
- SUSE: libmysqlclient-devel
- Debian/Ubuntu: default-libmysqlclient-dev | libmysqlclient-dev
- Alpine: mariadb-dev
* RHEL/Fedora: mysql-devel
* SUSE: libmysqlclient-devel
* Debian/Ubuntu: default-libmysqlclient-dev | libmysqlclient-dev
* Alpine: mariadb-dev
* PostgreSQL (disable with CMake variable `ICINGA2_WITH_PGSQL` to `OFF`)
- RHEL/Fedora: postgresql-devel
- Debian/Ubuntu: libpq-dev
- postgresql-dev on Alpine
* RHEL/Fedora: postgresql-devel
* Debian/Ubuntu: libpq-dev
* postgresql-dev on Alpine
* libedit (CLI console)
- RHEL/Fedora: libedit-devel on CentOS (RHEL requires rhel-7-server-optional-rpms)
- Debian/Ubuntu/Alpine: libedit-dev
* RHEL/Fedora: libedit-devel on CentOS (RHEL requires rhel-7-server-optional-rpms)
* Debian/Ubuntu/Alpine: libedit-dev
* Termcap (only required if libedit doesn't already link against termcap/ncurses)
- RHEL/Fedora: libtermcap-devel
- Debian/Ubuntu: (not necessary)
* RHEL/Fedora: libtermcap-devel
* Debian/Ubuntu: (not necessary)
### Special requirements <a id="development-package-builds-special-requirements"></a>
**FreeBSD**: libexecinfo (automatically used when Icinga 2 is installed via port or package)
**RHEL6** and **SLES11**: Requires a newer boost version which is available on packages.icinga.com
**RHEL6**: Requires a newer boost version which is available on packages.icinga.com
with a version suffixed name.
### Runtime user environment <a id="development-package-builds-runtime-user-env"></a>
@ -1191,66 +1390,70 @@ For all variables regarding defaults paths on in CMake, see
Also see `CMakeLists.txt` for details.
**System Environment**
- `CMAKE_INSTALL_SYSCONFDIR`: The configuration directory; defaults to `CMAKE_INSTALL_PREFIX/etc`
- `CMAKE_INSTALL_LOCALSTATEDIR`: The state directory; defaults to `CMAKE_INSTALL_PREFIX/var`
- `ICINGA2_CONFIGDIR`: Main config directory; defaults to `CMAKE_INSTALL_SYSCONFDIR/icinga2` usually `/etc/icinga2`
- `ICINGA2_CACHEDIR`: Directory for cache files; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/cache/icinga2` usually `/var/cache/icinga2`
- `ICINGA2_DATADIR`: Data directory for the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/lib/icinga2` usually `/var/lib/icinga2`
- `ICINGA2_LOGDIR`: Logfiles of the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/log/icinga2 usually `/var/log/icinga2`
- `ICINGA2_SPOOLDIR`: Spooling directory ; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/spool/icinga2` usually `/var/spool/icinga2`
- `ICINGA2_INITRUNDIR`: Runtime data for the init system; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/run/icinga2` usually `/run/icinga2`
- `ICINGA2_GIT_VERSION_INFO`: Whether to use Git to determine the version number; defaults to `ON`
- `ICINGA2_USER`: The user Icinga 2 should run as; defaults to `icinga`
- `ICINGA2_GROUP`: The group Icinga 2 should run as; defaults to `icinga`
- `ICINGA2_COMMAND_GROUP`: The command group Icinga 2 should use; defaults to `icingacmd`
- `ICINGA2_SYSCONFIGFILE`: Where to put the config file the initscript/systemd pulls it's dirs from;
defaults to `CMAKE_INSTALL_PREFIX/etc/sysconfig/icinga2`
- `ICINGA2_PLUGINDIR`: The path for the Monitoring Plugins project binaries; defaults to `/usr/lib/nagios/plugins`
#### System Environment
**Build Optimization**
- `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.
- `ICINGA2_LTO_BUILD`: Whether to use link time optimization (LTO); defaults to `OFF`
* `CMAKE_INSTALL_SYSCONFDIR`: The configuration directory; defaults to `CMAKE_INSTALL_PREFIX/etc`
* `CMAKE_INSTALL_LOCALSTATEDIR`: The state directory; defaults to `CMAKE_INSTALL_PREFIX/var`
* `ICINGA2_CONFIGDIR`: Main config directory; defaults to `CMAKE_INSTALL_SYSCONFDIR/icinga2` usually `/etc/icinga2`
* `ICINGA2_CACHEDIR`: Directory for cache files; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/cache/icinga2` usually `/var/cache/icinga2`
* `ICINGA2_DATADIR`: Data directory for the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/lib/icinga2` usually `/var/lib/icinga2`
* `ICINGA2_LOGDIR`: Logfiles of the daemon; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/log/icinga2 usually `/var/log/icinga2`
* `ICINGA2_SPOOLDIR`: Spooling directory ; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/spool/icinga2` usually `/var/spool/icinga2`
* `ICINGA2_INITRUNDIR`: Runtime data for the init system; defaults to `CMAKE_INSTALL_LOCALSTATEDIR/run/icinga2` usually `/run/icinga2`
* `ICINGA2_GIT_VERSION_INFO`: Whether to use Git to determine the version number; defaults to `ON`
* `ICINGA2_USER`: The user Icinga 2 should run as; defaults to `icinga`
* `ICINGA2_GROUP`: The group Icinga 2 should run as; defaults to `icinga`
* `ICINGA2_COMMAND_GROUP`: The command group Icinga 2 should use; defaults to `icingacmd`
* `ICINGA2_SYSCONFIGFILE`: Where to put the config file the initscript/systemd pulls it's dirs from;
* defaults to `CMAKE_INSTALL_PREFIX/etc/sysconfig/icinga2`
* `ICINGA2_PLUGINDIR`: The path for the Monitoring Plugins project binaries; defaults to `/usr/lib/nagios/plugins`
**Init System**
- `USE_SYSTEMD=ON|OFF`: Use systemd or a classic SysV initscript; defaults to `OFF`
- `INSTALL_SYSTEMD_SERVICE_AND_INITSCRIPT=ON|OFF` Force install both the systemd service definition file
#### Build Optimization
* `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.
* `ICINGA2_LTO_BUILD`: Whether to use link time optimization (LTO); defaults to `OFF`
#### Init System
* `USE_SYSTEMD=ON|OFF`: Use systemd or a classic SysV initscript; defaults to `OFF`
* `INSTALL_SYSTEMD_SERVICE_AND_INITSCRIPT=ON|OFF` Force install both the systemd service definition file
and the SysV initscript in parallel, regardless of how `USE_SYSTEMD` is set.
Only use this for special packaging purposes and if you know what you are doing.
Defaults to `OFF`.
**Features:**
- `ICINGA2_WITH_CHECKER`: Determines whether the checker module is built; defaults to `ON`
- `ICINGA2_WITH_COMPAT`: Determines whether the compat module is built; defaults to `ON`
- `ICINGA2_WITH_DEMO`: Determines whether the demo module is built; defaults to `OFF`
- `ICINGA2_WITH_HELLO`: Determines whether the hello module is built; defaults to `OFF`
- `ICINGA2_WITH_LIVESTATUS`: Determines whether the Livestatus module is built; defaults to `ON`
- `ICINGA2_WITH_NOTIFICATION`: Determines whether the notification module is built; defaults to `ON`
- `ICINGA2_WITH_PERFDATA`: Determines whether the perfdata module is built; defaults to `ON`
- `ICINGA2_WITH_TESTS`: Determines whether the unit tests are built; defaults to `ON`
#### Features
**MySQL or MariaDB:**
* `ICINGA2_WITH_CHECKER`: Determines whether the checker module is built; defaults to `ON`
* `ICINGA2_WITH_COMPAT`: Determines whether the compat module is built; defaults to `ON`
* `ICINGA2_WITH_LIVESTATUS`: Determines whether the Livestatus module is built; defaults to `ON`
* `ICINGA2_WITH_NOTIFICATION`: Determines whether the notification module is built; defaults to `ON`
* `ICINGA2_WITH_PERFDATA`: Determines whether the perfdata module is built; defaults to `ON`
* `ICINGA2_WITH_TESTS`: Determines whether the unit tests are built; defaults to `ON`
#### MySQL or MariaDB
The following settings can be tuned for the MySQL / MariaDB IDO feature.
- `ICINGA2_WITH_MYSQL`: Determines whether the MySQL IDO module is built; defaults to `ON`
- `MYSQL_CLIENT_LIBS`: Client implementation used (mysqlclient / mariadbclient); defaults searches for `mysqlclient` and `mariadbclient`
- `MYSQL_INCLUDE_DIR`: Directory containing include files for the mysqlclient; default empty -
* `ICINGA2_WITH_MYSQL`: Determines whether the MySQL IDO module is built; defaults to `ON`
* `MYSQL_CLIENT_LIBS`: Client implementation used (mysqlclient / mariadbclient); defaults searches for `mysqlclient` and `mariadbclient`
* `MYSQL_INCLUDE_DIR`: Directory containing include files for the mysqlclient; default empty -
checking multiple paths like `/usr/include/mysql`
See [FindMySQL.cmake](third-party/cmake/FindMySQL.cmake) for the implementation.
See [FindMySQL.cmake](https://github.com/Icinga/icinga2/blob/master/third-party/cmake/FindMySQL.cmake)
for implementation details.
**PostgreSQL:**
#### PostgreSQL
The following settings can be tuned for the PostgreSQL IDO feature.
- `ICINGA2_WITH_PGSQL`: Determines whether the PostgreSQL IDO module is built; defaults to `ON`
- `PostgreSQL_INCLUDE_DIR`: Top-level directory containing the PostgreSQL include directories
- `PostgreSQL_LIBRARY`: File path to PostgreSQL library : libpq.so (or libpq.so.[ver] file)
* `ICINGA2_WITH_PGSQL`: Determines whether the PostgreSQL IDO module is built; defaults to `ON`
* `PostgreSQL_INCLUDE_DIR`: Top-level directory containing the PostgreSQL include directories
* `PostgreSQL_LIBRARY`: File path to PostgreSQL library : libpq.so (or libpq.so.[ver] file)
See [FindMySQL.cmake](third-party/cmake/FindPostgreSQL.cmake) for the implementation.
See [FindPostgreSQL.cmake](https://github.com/Icinga/icinga2/blob/master/third-party/cmake/FindPostgreSQL.cmake)
for implementation details.
**Version detection:**
#### Version detection
CMake determines the Icinga 2 version number using `git describe` if the
source directory is contained in a Git repository. Otherwise the version number
@ -1380,11 +1583,6 @@ MACROS
If you prefer to build packages offline, a suitable Vagrant box is located
[here](https://atlas.hashicorp.com/mvbcoding/boxes/awslinux/).
##### SLES 11
The Icinga repository provides the required boost package version and must be
added before building.
### Build Debian/Ubuntu packages <a id="development-package-builds-deb"></a>
Setup your build environment on Debian/Ubuntu, copy the 'debian' directory from
@ -1653,19 +1851,3 @@ the duplicate import in your `~/.gdbinit` file.
RuntimeError: pretty-printer already registered: libstdc++-v6
```
## Development Tests <a id="development-tests"></a>
Build the binaries and run the tests.
```
make -j4 -C debug
make test -C debug
```
Run a specific boost test:
```
debug/Bin/Debug/boosttest-test-base --run_test=remote_url
```

BIN
doc/images/development/windows_boost_build_dev_cmd.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB