tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-27 07:34:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: enable syntax highlighting

Browse Source 
refs #8146
This commit is contained in:
Alexander A. Klimov 2020-12-09 12:32:09 +01:00
parent f2a532de32
commit 51b3d88d22
17 changed files with 621 additions and 603 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
CONTRIBUTING.md
View File

@ -43,20 +43,20 @@ Please continue reading in the following sections for a step by step guide.
[Fork the project](https://help.github.com/articles/fork-a-repo/) to your GitHub account [Fork the project](https://help.github.com/articles/fork-a-repo/) to your GitHub account
and clone the repository: and clone the repository:
``` ```bash
git clone git@github.com:dnsmichi/icinga2.git git clone git@github.com:dnsmichi/icinga2.git
cd icinga2 cd icinga2
``` ```
Add a new remote `upstream` with this repository as value. Add a new remote `upstream` with this repository as value.
``` ```bash
git remote add upstream https://github.com/icinga/icinga2.git git remote add upstream https://github.com/icinga/icinga2.git
``` ```
You can pull updates to your fork's master branch: You can pull updates to your fork's master branch:
``` ```bash
git fetch --all git fetch --all
git pull upstream HEAD git pull upstream HEAD
``` ```
@ -71,7 +71,7 @@ Generally a branch name should include a topic such as `bugfix` or `feature` fol
by a description and an issue number if applicable. Branches should have only changes by a description and an issue number if applicable. Branches should have only changes
relevant to a specific issue. relevant to a specific issue.
``` ```bash
git checkout -b bugfix/service-template-typo-1234 git checkout -b bugfix/service-template-typo-1234
git checkout -b feature/config-handling-1235 git checkout -b feature/config-handling-1235
``` ```
@ -116,7 +116,7 @@ Don't worry, you can squash those changes into a single commit later on.
Once you've commited your changes, please update your local master Once you've commited your changes, please update your local master
branch and rebase your bugfix/feature branch against it before submitting a PR. branch and rebase your bugfix/feature branch against it before submitting a PR.
``` ```bash
git checkout master git checkout master
git pull upstream HEAD git pull upstream HEAD
@ -128,12 +128,14 @@ Once you've resolved any conflicts, push the branch to your remote repository.
It might be necessary to force push after rebasing - use with care! It might be necessary to force push after rebasing - use with care!
New branch: New branch:
```
```bash
git push --set-upstream origin bugfix/notifications git push --set-upstream origin bugfix/notifications
``` ```
Existing branch: Existing branch:
```
```bash
git push -f origin bugfix/notifications git push -f origin bugfix/notifications
``` ```
@ -162,7 +164,7 @@ developers might ask you to rebase your PR.
First off, fetch and pull `upstream` master. First off, fetch and pull `upstream` master.
``` ```bash
git checkout master git checkout master
git fetch --all git fetch --all
git pull upstream HEAD git pull upstream HEAD
@ -170,7 +172,7 @@ git pull upstream HEAD
Then change to your working branch and start rebasing it against master: Then change to your working branch and start rebasing it against master:
``` ```bash
git checkout bugfix/notifications git checkout bugfix/notifications
git rebase master git rebase master
``` ```
@ -187,21 +189,21 @@ Edit the file and search for `>>>`. Fix, build, test and save as needed.
Add the modified file(s) and continue rebasing. Add the modified file(s) and continue rebasing.
``` ```bash
git add path/to/conflict.cpp git add path/to/conflict.cpp
git rebase --continue git rebase --continue
``` ```
Once succeeded ensure to push your changed history remotely. Once succeeded ensure to push your changed history remotely.
``` ```bash
git push -f origin bugfix/notifications git push -f origin bugfix/notifications
``` ```
If you fear to break things, do the rebase in a backup branch first and later replace your current branch. If you fear to break things, do the rebase in a backup branch first and later replace your current branch.
``` ```bash
git checkout bugfix/notifications git checkout bugfix/notifications
git checkout -b bugfix/notifications-rebase git checkout -b bugfix/notifications-rebase
@ -225,7 +227,7 @@ Say you want to squash the last 3 commits in your branch into a single one.
Start an interactive (`-i`) rebase from current HEAD minus three commits (`HEAD~3`). Start an interactive (`-i`) rebase from current HEAD minus three commits (`HEAD~3`).
``` ```bash
git rebase -i HEAD~3 git rebase -i HEAD~3
``` ```
@ -239,7 +241,7 @@ squash b37fd5377 Doc updates
Save and let rebase to its job. Then force push the changes to the remote origin. Save and let rebase to its job. Then force push the changes to the remote origin.
``` ```bash
git push -f origin bugfix/notifications git push -f origin bugfix/notifications
``` ```
@ -267,19 +269,19 @@ The documentation is written in GitHub flavored [Markdown](https://guides.github
It is located in the `doc/` directory and can be edited with your preferred editor. You can also It is located in the `doc/` directory and can be edited with your preferred editor. You can also
edit it online on GitHub. edit it online on GitHub.
``` ```bash
vim doc/2-getting-started.md vim doc/2-getting-started.md
``` ```
In order to review and test changes, you can install the [mkdocs](https://www.mkdocs.org) Python library. In order to review and test changes, you can install the [mkdocs](https://www.mkdocs.org) Python library.
``` ```bash
pip install mkdocs pip install mkdocs
``` ```
This allows you to start a local mkdocs viewer instance on http://localhost:8000 This allows you to start a local mkdocs viewer instance on http://localhost:8000
``` ```bash
mkdocs serve mkdocs serve
``` ```
@ -288,7 +290,7 @@ Changes on the chapter layout can be done inside the `mkdocs.yml` file in the ma
There also is a script to ensure that relative URLs to other sections are updated. This script There also is a script to ensure that relative URLs to other sections are updated. This script
also checks for broken URLs. also checks for broken URLs.
``` ```bash
./doc/update-links.py doc/*.md ./doc/update-links.py doc/*.md
``` ```
@ -335,7 +337,7 @@ Your patch should consist of 2 parts:
Create a new fix or feature branch and start your work. Create a new fix or feature branch and start your work.
``` ```bash
git checkout -b feature/itl-check-printer git checkout -b feature/itl-check-printer
``` ```
@ -344,14 +346,14 @@ git checkout -b feature/itl-check-printer
There already exists a defined structure for contributed plugins. Navigate to `itl/plugins-contrib.d` There already exists a defined structure for contributed plugins. Navigate to `itl/plugins-contrib.d`
and verify where your command definitions fits into. and verify where your command definitions fits into.
``` ```bash
cd itl/plugins-contrib.d/ cd itl/plugins-contrib.d/
ls ls
``` ```
If you want to add or modify an existing Monitoring Plugin please use `itl/command-plugins.conf` instead. If you want to add or modify an existing Monitoring Plugin please use `itl/command-plugins.conf` instead.
``` ```bash
vim itl/command-plugins-conf vim itl/command-plugins-conf
``` ```
@ -359,7 +361,7 @@ vim itl/command-plugins-conf
Just edit it, and add your CheckCommand definition. Just edit it, and add your CheckCommand definition.
``` ```bash
vim operating-system.conf vim operating-system.conf
``` ```
@ -369,8 +371,8 @@ Proceed to the documentation.
Create a new file with .conf suffix. Create a new file with .conf suffix.
``` ```bash
$ vim printer.conf vim printer.conf
``` ```
Add the file to `itl/CMakeLists.txt` in the FILES line in **alpha-numeric order**. Add the file to `itl/CMakeLists.txt` in the FILES line in **alpha-numeric order**.
@ -385,7 +387,7 @@ vim CMakeLists.txt
Add the newly created file to your git commit. Add the newly created file to your git commit.
``` ```bash
git add printer.conf git add printer.conf
``` ```
@ -396,7 +398,7 @@ Do not commit it yet but finish with the documentation.
Edit the documentation file in the `doc/` directory. More details on documentation Edit the documentation file in the `doc/` directory. More details on documentation
updates can be found [here](CONTRIBUTING.md#contributing-documentation). updates can be found [here](CONTRIBUTING.md#contributing-documentation).
``` ```bash
vim doc/10-icinga-template-library.md vim doc/10-icinga-template-library.md
``` ```
@ -424,9 +426,10 @@ Explain its purpose and possible enhancements/shortcomings.
refs #existingticketnumberifany refs #existingticketnumberifany
``` ```
Push the branch to the remote origin and create a [pull request](https://help.github.com/articles/using-pull-requests/). Push the branch to the remote origin and create a [pull request](https://help.github.com/articles/using-pull-requests/).
``` ```bash
git push --set-upstream origin feature/itl-check-printer git push --set-upstream origin feature/itl-check-printer
hub pull-request hub pull-request
``` ```
@ -464,14 +467,14 @@ At the bottom it says "Add more commits by pushing to the bugfix/persistent-comm
First off, add the remote repository as additional origin and fetch its content: First off, add the remote repository as additional origin and fetch its content:
``` ```bash
git remote add theflyingcorpse https://github.com/TheFlyingCorpse/icinga2 git remote add theflyingcorpse https://github.com/TheFlyingCorpse/icinga2
git fetch --all git fetch --all
``` ```
Checkout the mentioned remote branch into a local branch (Note: `theflyingcorpse` is the name of the remote): Checkout the mentioned remote branch into a local branch (Note: `theflyingcorpse` is the name of the remote):
``` ```bash
git checkout theflyingcorpse/bugfix/persistent-comments-are-not-persistent -b bugfix/persistent-comments-are-not-persistent git checkout theflyingcorpse/bugfix/persistent-comments-are-not-persistent -b bugfix/persistent-comments-are-not-persistent
``` ```
@ -480,12 +483,12 @@ Rebase, amend, squash or add your own commits on top.
Once you are satisfied, push the changes to the remote `theflyingcorpse` and its branch `bugfix/persistent-comments-are-not-persistent`. Once you are satisfied, push the changes to the remote `theflyingcorpse` and its branch `bugfix/persistent-comments-are-not-persistent`.
The syntax here is `git push <remote> <localbranch>:<remotebranch>`. The syntax here is `git push <remote> <localbranch>:<remotebranch>`.
``` ```bash
git push theflyingcorpse bugfix/persistent-comments-are-not-persistent:bugfix/persistent-comments-are-not-persistent git push theflyingcorpse bugfix/persistent-comments-are-not-persistent:bugfix/persistent-comments-are-not-persistent
``` ```
In case you've changed the commit history (rebase, amend, squash), you'll need to force push. Be careful, this can't be reverted! In case you've changed the commit history (rebase, amend, squash), you'll need to force push. Be careful, this can't be reverted!
``` ```bash
git push -f theflyingcorpse bugfix/persistent-comments-are-not-persistent:bugfix/persistent-comments-are-not-persistent git push -f theflyingcorpse bugfix/persistent-comments-are-not-persistent:bugfix/persistent-comments-are-not-persistent
``` ```

44
RELEASE.md
View File

@ -24,7 +24,7 @@
Specify the release version. Specify the release version.
``` ```bash
VERSION=2.11.0 VERSION=2.11.0
``` ```
@ -53,7 +53,7 @@ master branch which should be part of this release.
Update the version: Update the version:
``` ```bash
perl -pi -e "s/Version: .*/Version: $VERSION/g" VERSION perl -pi -e "s/Version: .*/Version: $VERSION/g" VERSION
``` ```
@ -65,26 +65,26 @@ issues/PRs. At the start include a link to the milestone's closed issues.
## Git Tag <a id="git-tag"></a> ## Git Tag <a id="git-tag"></a>
``` ```bash
git commit -v -a -m "Release version $VERSION" git commit -v -a -m "Release version $VERSION"
``` ```
Create a signed tag (tags/v<VERSION>) on the `master` branch (for major Create a signed tag (tags/v<VERSION>) on the `master` branch (for major
releases) or the `support` branch (for minor releases). releases) or the `support` branch (for minor releases).
``` ```bash
git tag -s -m "Version $VERSION" v$VERSION git tag -s -m "Version $VERSION" v$VERSION
``` ```
Push the tag: Push the tag:
``` ```bash
git push origin v$VERSION git push origin v$VERSION
``` ```
**For major releases:** Create a new `support` branch: **For major releases:** Create a new `support` branch:
``` ```bash
git checkout master git checkout master
git push git push
@ -95,32 +95,32 @@ git push -u origin support/2.12
## Package Builds <a id="package-builds"></a> ## Package Builds <a id="package-builds"></a>
``` ```bash
mkdir $HOME/dev/icinga/packaging mkdir $HOME/dev/icinga/packaging
cd $HOME/dev/icinga/packaging cd $HOME/dev/icinga/packaging
``` ```
### RPM Packages <a id="rpm-packages"></a> ### RPM Packages <a id="rpm-packages"></a>
``` ```bash
git clone git@git.icinga.com:packaging/rpm-icinga2.git && cd rpm-icinga2 git clone git@git.icinga.com:packaging/rpm-icinga2.git && cd rpm-icinga2
``` ```
### DEB Packages <a id="deb-packages"></a> ### DEB Packages <a id="deb-packages"></a>
``` ```bash
git clone git@git.icinga.com:packaging/deb-icinga2.git && cd deb-icinga2 git clone git@git.icinga.com:packaging/deb-icinga2.git && cd deb-icinga2
``` ```
#### Raspbian Packages #### Raspbian Packages
``` ```bash
git clone git@git.icinga.com:packaging/raspbian-icinga2.git && cd raspbian-icinga2 git clone git@git.icinga.com:packaging/raspbian-icinga2.git && cd raspbian-icinga2
``` ```
### Windows Packages ### Windows Packages
``` ```bash
git clone git@git.icinga.com:packaging/windows-icinga2.git && cd windows-icinga2 git clone git@git.icinga.com:packaging/windows-icinga2.git && cd windows-icinga2
``` ```
@ -146,7 +146,7 @@ variables:
Commit the change. Commit the change.
``` ```bash
git commit -av -m "Switch build type for 2.13" git commit -av -m "Switch build type for 2.13"
``` ```
@ -191,7 +191,7 @@ perl -pi -e "s/^ ICINGA_FORCE_VERSION: .*/ ICINGA_FORCE_VERSION: v$VERSION/g"
Commit the changes and push the branch. Commit the changes and push the branch.
``` ```bash
git commit -av -m "Release $VERSION-1" git commit -av -m "Release $VERSION-1"
git push origin 2.11 git push origin 2.11
``` ```
@ -218,14 +218,14 @@ tag the release commit and push it.
RPM/DEB/Raspbian: RPM/DEB/Raspbian:
``` ```bash
git tag -s $VERSION-1 -m "Release v$VERSION-1" git tag -s $VERSION-1 -m "Release v$VERSION-1"
git push origin $VERSION-1 git push origin $VERSION-1
``` ```
Windows: Windows:
``` ```bash
git tag -s $VERSION -m "Release v$VERSION" git tag -s $VERSION -m "Release v$VERSION"
git push origin $VERSION git push origin $VERSION
``` ```
@ -258,7 +258,7 @@ are triggered and automatically published to packages.icinga.com
### CentOS ### CentOS
``` ```bash
docker run -ti centos:7 bash docker run -ti centos:7 bash
yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
@ -269,7 +269,7 @@ icinga2 daemon -C
### Ubuntu ### Ubuntu
``` ```bash
docker run -ti ubuntu:bionic bash docker run -ti ubuntu:bionic bash
apt-get update apt-get update
@ -336,7 +336,7 @@ Navigate to `puppet-customer/icinga.git` and do the following steps:
#### Testing #### Testing
``` ```bash
git checkout testing && git pull git checkout testing && git pull
vim files/var/www/docs/config/icinga2-latest.yml vim files/var/www/docs/config/icinga2-latest.yml
@ -347,7 +347,7 @@ git push
SSH into the webserver and do a manual Puppet dry run with the testing environment. SSH into the webserver and do a manual Puppet dry run with the testing environment.
``` ```bash
puppet agent -t --environment testing --noop puppet agent -t --environment testing --noop
``` ```
@ -355,7 +355,7 @@ Once succeeded, continue with production deployment.
#### Production #### Production
``` ```bash
git checkout master && git pull git checkout master && git pull
git merge testing git merge testing
git push git push
@ -363,7 +363,7 @@ git push
SSH into the webserver and do a manual Puppet run from the production environment (default). SSH into the webserver and do a manual Puppet run from the production environment (default).
``` ```bash
puppet agent -t puppet agent -t
``` ```
@ -371,7 +371,7 @@ puppet agent -t
SSH into the webserver or ask @bobapple. SSH into the webserver or ask @bobapple.
``` ```bash
cd /usr/local/icinga-docs-tools && ./build-docs.rb -c /var/www/docs/config/icinga2-latest.yml cd /usr/local/icinga-docs-tools && ./build-docs.rb -c /var/www/docs/config/icinga2-latest.yml
``` ```

166
doc/02-installation.md
View File

@ -51,7 +51,7 @@ The following commands must be executed with `root` permissions unless noted oth
Debian: Debian:
``` ```bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -68,7 +68,7 @@ apt-get update
Ubuntu: Ubuntu:
``` ```bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -85,7 +85,7 @@ apt-get update
Raspbian Buster: Raspbian Buster:
``` ```bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -108,7 +108,7 @@ apt-get update
Debian Stretch: Debian Stretch:
``` ```bash
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \ echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list /etc/apt/sources.list.d/${DIST}-backports.list
@ -120,25 +120,25 @@ apt-get update
RHEL/CentOS 8: RHEL/CentOS 8:
``` ```bash
dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm
``` ```
RHEL/CentOS 7: RHEL/CentOS 7:
``` ```bash
yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
``` ```
RHEL/CentOS 6 x64: RHEL/CentOS 6 x64:
``` ```bash
yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
``` ```
Fedora 31: Fedora 31:
``` ```bash
dnf install https://packages.icinga.com/fedora/icinga-rpm-release-31-latest.noarch.rpm dnf install https://packages.icinga.com/fedora/icinga-rpm-release-31-latest.noarch.rpm
``` ```
@ -149,7 +149,7 @@ as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
CentOS 8 additionally needs the PowerTools repository for EPEL: CentOS 8 additionally needs the PowerTools repository for EPEL:
``` ```bash
dnf install 'dnf-command(config-manager)' dnf install 'dnf-command(config-manager)'
dnf config-manager --set-enabled PowerTools dnf config-manager --set-enabled PowerTools
@ -158,7 +158,7 @@ dnf install epel-release
CentOS 7/6: CentOS 7/6:
``` ```bash
yum install epel-release yum install epel-release
``` ```
@ -167,7 +167,7 @@ repository before installing the [EPEL rpm package](https://fedoraproject.org/wi
RHEL 8: RHEL 8:
``` ```bash
ARCH=$( /bin/arch ) ARCH=$( /bin/arch )
subscription-manager repos --enable rhel-8-server-optional-rpms subscription-manager repos --enable rhel-8-server-optional-rpms
@ -178,14 +178,14 @@ dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.r
RHEL 7: RHEL 7:
``` ```bash
subscription-manager repos --enable rhel-7-server-optional-rpms subscription-manager repos --enable rhel-7-server-optional-rpms
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
``` ```
RHEL 6: RHEL 6:
``` ```bash
subscription-manager repos --enable rhel-6-server-optional-rpms subscription-manager repos --enable rhel-6-server-optional-rpms
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
``` ```
@ -197,7 +197,7 @@ since v2.11.
SLES 15/12: SLES 15/12:
``` ```bash
rpm --import https://packages.icinga.com/icinga.key rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
@ -206,7 +206,7 @@ zypper ref
openSUSE: openSUSE:
``` ```bash
rpm --import https://packages.icinga.com/icinga.key rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
@ -215,7 +215,7 @@ zypper ref
#### Alpine Linux Repositories <a id="package-repositories-alpine"></a> #### Alpine Linux Repositories <a id="package-repositories-alpine"></a>
``` ```bash
echo "http://dl-cdn.alpinelinux.org/alpine/edge/main" >> /etc/apk/repositories echo "http://dl-cdn.alpinelinux.org/alpine/edge/main" >> /etc/apk/repositories
echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk update apk update
@ -234,13 +234,13 @@ with `root` permissions unless noted otherwise.
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install icinga2 apt-get install icinga2
``` ```
RHEL/CentOS 8 and Fedora: RHEL/CentOS 8 and Fedora:
``` ```bash
dnf install icinga2 dnf install icinga2
systemctl enable icinga2 systemctl enable icinga2
systemctl start icinga2 systemctl start icinga2
@ -248,7 +248,7 @@ systemctl start icinga2
RHEL/CentOS 7: RHEL/CentOS 7:
``` ```bash
yum install icinga2 yum install icinga2
systemctl enable icinga2 systemctl enable icinga2
systemctl start icinga2 systemctl start icinga2
@ -256,7 +256,7 @@ systemctl start icinga2
RHEL/CentOS 6: RHEL/CentOS 6:
``` ```bash
yum install icinga2 yum install icinga2
chkconfig icinga2 on chkconfig icinga2 on
service icinga2 start service icinga2 start
@ -264,19 +264,19 @@ service icinga2 start
SLES/openSUSE: SLES/openSUSE:
``` ```bash
zypper install icinga2 zypper install icinga2
``` ```
FreeBSD: FreeBSD:
``` ```bash
pkg install icinga2 pkg install icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
apk add icinga2 apk add icinga2
``` ```
@ -316,7 +316,7 @@ to determine where to find the plugin binaries.
### Debian/Ubuntu <a id="setting-up-check-plugins-debian-ubuntu"></a> ### Debian/Ubuntu <a id="setting-up-check-plugins-debian-ubuntu"></a>
``` ```bash
apt-get install monitoring-plugins apt-get install monitoring-plugins
``` ```
@ -327,19 +327,19 @@ as part of the [EPEL repository](02-installation.md#package-repositories-rhel-ep
RHEL/CentOS 8: RHEL/CentOS 8:
``` ```bash
dnf install nagios-plugins-all dnf install nagios-plugins-all
``` ```
RHEL/CentOS 7/6: RHEL/CentOS 7/6:
``` ```bash
yum install nagios-plugins-all yum install nagios-plugins-all
``` ```
Fedora: Fedora:
``` ```bash
dnf install nagios-plugins-all dnf install nagios-plugins-all
``` ```
@ -349,19 +349,19 @@ The packages for SLES/OpenSUSE depend on other packages which are distributed
as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring). as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
Please make sure to enable this repository beforehand. Please make sure to enable this repository beforehand.
``` ```bash
zypper install monitoring-plugins zypper install monitoring-plugins
``` ```
### FreeBSD <a id="setting-up-check-plugins-freebsd"></a> ### FreeBSD <a id="setting-up-check-plugins-freebsd"></a>
``` ```bash
pkg install monitoring-plugins pkg install monitoring-plugins
``` ```
### Alpine Linux <a id="setting-up-check-plugins-alpine"></a> ### Alpine Linux <a id="setting-up-check-plugins-alpine"></a>
``` ```bash
apk add monitoring-plugins apk add monitoring-plugins
``` ```
@ -423,7 +423,7 @@ Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'jour
If you're stuck with configuration errors, you can manually invoke the If you're stuck with configuration errors, you can manually invoke the
[configuration validation](11-cli-commands.md#config-validation). [configuration validation](11-cli-commands.md#config-validation).
``` ```bash
icinga2 daemon -C icinga2 daemon -C
``` ```
@ -462,7 +462,7 @@ using the init script. Using Debian packages the user and group are set to
On FreeBSD you need to enable icinga2 in your rc.conf On FreeBSD you need to enable icinga2 in your rc.conf
``` ```bash
sysrc icinga2_enable=yes sysrc icinga2_enable=yes
service icinga2 restart service icinga2 restart
@ -480,13 +480,13 @@ which confines Icinga 2 including enabled features and running commands.
RHEL/CentOS 8 and Fedora: RHEL/CentOS 8 and Fedora:
``` ```bash
dnf install icinga2-selinux dnf install icinga2-selinux
``` ```
RHEL/CentOS 7: RHEL/CentOS 7:
``` ```bash
yum install icinga2-selinux yum install icinga2-selinux
``` ```
@ -514,25 +514,25 @@ Info: installing removed addon 'icinga2' to /var/lib/vim/addons
RHEL/CentOS 8 and Fedora: RHEL/CentOS 8 and Fedora:
``` ```bash
dnf install vim-icinga2 dnf install vim-icinga2
``` ```
RHEL/CentOS 7/6: RHEL/CentOS 7/6:
``` ```bash
yum install vim-icinga2 yum install vim-icinga2
``` ```
SLES/openSUSE: SLES/openSUSE:
``` ```bash
zypper install vim-icinga2 zypper install vim-icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
apk add icinga2-vim apk add icinga2-vim
``` ```
@ -546,8 +546,8 @@ syntax on
Test it: Test it:
``` ```bash
# vim /etc/icinga2/conf.d/templates.conf vim /etc/icinga2/conf.d/templates.conf
``` ```
![Vim with syntax highlighting](images/installation/vim-syntax.png "Vim with Icinga 2 syntax highlighting") ![Vim with syntax highlighting](images/installation/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
@ -563,26 +563,26 @@ Debian/Ubuntu:
RHEL/CentOS 8 and Fedora: RHEL/CentOS 8 and Fedora:
``` ```bash
dnf install nano-icinga2 dnf install nano-icinga2
``` ```
RHEL/CentOS 7/6: RHEL/CentOS 7/6:
``` ```bash
yum install nano-icinga2 yum install nano-icinga2
``` ```
SLES/openSUSE: SLES/openSUSE:
``` ```bash
zypper install nano-icinga2 zypper install nano-icinga2
``` ```
Copy the `/etc/nanorc` sample file to your home directory. Copy the `/etc/nanorc` sample file to your home directory.
``` ```bash
$ cp /etc/nanorc ~/.nanorc cp /etc/nanorc ~/.nanorc
``` ```
Include the `icinga2.nanorc` file. Include the `icinga2.nanorc` file.
@ -596,8 +596,8 @@ include "/usr/share/nano/icinga2.nanorc"
Test it: Test it:
``` ```bash
$ nano /etc/icinga2/conf.d/templates.conf nano /etc/icinga2/conf.d/templates.conf
``` ```
![Nano with syntax highlighting](images/installation/nano-syntax.png "Nano with Icinga 2 syntax highlighting") ![Nano with syntax highlighting](images/installation/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
@ -624,7 +624,7 @@ exporting all configuration and status information into a database.
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install mariadb-server mariadb-client apt-get install mariadb-server mariadb-client
mysql_secure_installation mysql_secure_installation
@ -632,7 +632,7 @@ mysql_secure_installation
RHEL/CentOS and Fedora: RHEL/CentOS and Fedora:
``` ```bash
yum install mariadb-server mariadb yum install mariadb-server mariadb
systemctl enable mariadb systemctl enable mariadb
systemctl start mariadb systemctl start mariadb
@ -641,7 +641,7 @@ mysql_secure_installation
SUSE: SUSE:
``` ```bash
zypper install mysql mysql-client zypper install mysql mysql-client
chkconfig mysqld on chkconfig mysqld on
service mysqld start service mysqld start
@ -649,7 +649,7 @@ service mysqld start
FreeBSD: FreeBSD:
``` ```bash
pkg install mysql56-server pkg install mysql56-server
sysrc mysql_enable=yes sysrc mysql_enable=yes
service mysql-server restart service mysql-server restart
@ -658,7 +658,7 @@ mysql_secure_installation
Alpine Linux: Alpine Linux:
``` ```bash
apk add mariadb apk add mariadb
rc-service mariadb setup rc-service mariadb setup
rc-update add mariadb default rc-update add mariadb default
@ -672,19 +672,19 @@ distribution's package manager.
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install icinga2-ido-mysql apt-get install icinga2-ido-mysql
``` ```
RHEL/CentOS: RHEL/CentOS:
``` ```bash
yum install icinga2-ido-mysql yum install icinga2-ido-mysql
``` ```
SUSE: SUSE:
``` ```bash
zypper install icinga2-ido-mysql zypper install icinga2-ido-mysql
``` ```
@ -721,7 +721,7 @@ quit
After creating the database you can import the Icinga 2 IDO schema using the After creating the database you can import the Icinga 2 IDO schema using the
following command. Enter the root password into the prompt when asked. following command. Enter the root password into the prompt when asked.
``` ```bash
mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
``` ```
@ -746,13 +746,13 @@ Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2. Restart Icinga 2.
``` ```bash
systemctl restart icinga2 systemctl restart icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
rc-service icinga2 restart rc-service icinga2 restart
``` ```
@ -764,13 +764,13 @@ Continue with the [webserver setup](02-installation.md#icinga2-user-interface-we
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install postgresql apt-get install postgresql
``` ```
RHEL/CentOS: RHEL/CentOS:
``` ```bash
yum install postgresql-server postgresql yum install postgresql-server postgresql
postgresql-setup initdb postgresql-setup initdb
systemctl enable postgresql systemctl enable postgresql
@ -779,7 +779,7 @@ systemctl start postgresql
SUSE: SUSE:
``` ```bash
zypper install postgresql postgresql-server zypper install postgresql postgresql-server
chkconfig postgresql on chkconfig postgresql on
service postgresql initdb service postgresql initdb
@ -788,7 +788,7 @@ service postgresql start
FreeBSD: FreeBSD:
``` ```bash
pkg install postgresql93-server pkg install postgresql93-server
sysrc postgresql_enable=yes sysrc postgresql_enable=yes
service postgresql initdb service postgresql initdb
@ -797,7 +797,7 @@ service postgresql start
Alpine Linux: Alpine Linux:
``` ```bash
apk add postgresql apk add postgresql
rc-update add postgresql default rc-update add postgresql default
rc-service postgresql setup rc-service postgresql setup
@ -811,19 +811,19 @@ distribution's package manager.
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install icinga2-ido-pgsql apt-get install icinga2-ido-pgsql
``` ```
RHEL/CentOS: RHEL/CentOS:
``` ```bash
yum install icinga2-ido-pgsql yum install icinga2-ido-pgsql
``` ```
SUSE: SUSE:
``` ```bash
zypper install icinga2-ido-pgsql zypper install icinga2-ido-pgsql
``` ```
@ -847,7 +847,7 @@ and located at `/usr/share/icinga2-ido-pgsql/schema/pgsql.sql`.
Set up a PostgreSQL database for Icinga 2: Set up a PostgreSQL database for Icinga 2:
``` ```bash
cd /tmp cd /tmp
sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
sudo -u postgres createdb -O icinga -E UTF8 icinga sudo -u postgres createdb -O icinga -E UTF8 icinga
@ -875,7 +875,7 @@ host all all 127.0.0.1/32 ident
host all all ::1/128 ident host all all ::1/128 ident
``` ```
``` ```bash
systemctl restart postgresql systemctl restart postgresql
``` ```
@ -883,7 +883,7 @@ systemctl restart postgresql
After creating the database and permissions you need to import the IDO database After creating the database and permissions you need to import the IDO database
schema using the following command: schema using the following command:
``` ```bash
export PGPASSWORD=icinga export PGPASSWORD=icinga
psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
``` ```
@ -912,13 +912,13 @@ Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2. Restart Icinga 2.
``` ```bash
systemctl restart icinga2 systemctl restart icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
rc-service icinga2 restart rc-service icinga2 restart
``` ```
@ -937,13 +937,13 @@ documentation.
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
apt-get install apache2 apt-get install apache2
``` ```
RHEL/CentOS/Fedora: RHEL/CentOS/Fedora:
``` ```bash
yum install httpd yum install httpd
systemctl enable httpd systemctl enable httpd
systemctl start httpd systemctl start httpd
@ -951,7 +951,7 @@ systemctl start httpd
SUSE: SUSE:
``` ```bash
zypper install apache2 zypper install apache2
chkconfig apache2 on chkconfig apache2 on
service apache2 start service apache2 start
@ -959,7 +959,7 @@ service apache2 start
FreeBSD (Nginx, but you could also use the `apache24` package): FreeBSD (Nginx, but you could also use the `apache24` package):
``` ```bash
pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl
sysrc php_fpm_enable=yes sysrc php_fpm_enable=yes
sysrc nginx_enable=yes sysrc nginx_enable=yes
@ -973,7 +973,7 @@ service nginx start
Alpine Linux: Alpine Linux:
``` ```bash
apk add apache2 php7-apache2 apk add apache2 php7-apache2
sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
rc-update add apache2 default rc-update add apache2 default
@ -986,14 +986,14 @@ Enable port 80 (http). Best practice is to only enable port 443 (https) and use
firewall-cmd: firewall-cmd:
``` ```bash
firewall-cmd --add-service=http firewall-cmd --add-service=http
firewall-cmd --permanent --add-service=http firewall-cmd --permanent --add-service=http
``` ```
iptables: iptables:
``` ```bash
iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
service iptables save service iptables save
``` ```
@ -1012,7 +1012,7 @@ You can run the CLI command `icinga2 api setup` to enable the
certificates as well as a new API user `root` with an auto-generated password in the certificates as well as a new API user `root` with an auto-generated password in the
`/etc/icinga2/conf.d/api-users.conf` configuration file: `/etc/icinga2/conf.d/api-users.conf` configuration file:
``` ```bash
icinga2 api setup icinga2 api setup
``` ```
@ -1030,13 +1030,13 @@ object ApiUser "icingaweb2" {
Restart Icinga 2 to activate the configuration. Restart Icinga 2 to activate the configuration.
``` ```bash
systemctl restart icinga2 systemctl restart icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
rc-service icinga2 restart rc-service icinga2 restart
``` ```
@ -1169,13 +1169,13 @@ Make sure to restart Icinga 2 for these changes to take effect.
Restart Icinga 2. Restart Icinga 2.
``` ```bash
systemctl restart icinga2 systemctl restart icinga2
``` ```
Alpine Linux: Alpine Linux:
``` ```bash
rc-service icinga2 restart rc-service icinga2 restart
``` ```

12
doc/03-monitoring-basics.md
View File

@ -2244,7 +2244,7 @@ The service specifies the [custom variable](03-monitoring-basics.md#custom-varia
This results in this command line without the `--process` parameter: This results in this command line without the `--process` parameter:
``` ```bash
'/bin/icingacli' 'businessprocess' 'process' 'check' 'bp-shop-web' '/bin/icingacli' 'businessprocess' 'process' 'check' 'bp-shop-web'
``` ```
@ -2272,7 +2272,7 @@ This can be used for the following scenarios:
Whenever a host/service object sets the `http_sni` [custom variable](03-monitoring-basics.md#custom-variables) Whenever a host/service object sets the `http_sni` [custom variable](03-monitoring-basics.md#custom-variables)
to `true`, the parameter is added to the command line. to `true`, the parameter is added to the command line.
``` ```bash
'/usr/lib64/nagios/plugins/check_http' '--sni' '/usr/lib64/nagios/plugins/check_http' '--sni'
``` ```
@ -2311,7 +2311,7 @@ object Host "postgresql-cluster" {
... use the following command line: ... use the following command line:
``` ```bash
'/usr/lib64/nagios/plugins/check_postgres.pl' '-H' '192.168.56.200' '/usr/lib64/nagios/plugins/check_postgres.pl' '-H' '192.168.56.200'
``` ```
@ -2454,7 +2454,7 @@ object CheckCommand "mysql" {
The executed command line visible with `ps` or `top` looks like this and hides The executed command line visible with `ps` or `top` looks like this and hides
the database credentials in the user's environment. the database credentials in the user's environment.
``` ```bash
/usr/lib/nagios/plugins/check_mysql -H 192.168.56.101 -d icinga /usr/lib/nagios/plugins/check_mysql -H 192.168.56.101 -d icinga
``` ```
@ -2912,14 +2912,14 @@ object Service "businessprocess" {
In order to test this scenario you can run: In order to test this scenario you can run:
``` ```bash
nc -l 8080 nc -l 8080
``` ```
This allows to catch the web request. You can also enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) This allows to catch the web request. You can also enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output)
and search for the event command execution log message. and search for the event command execution log message.
``` ```bash
tail -f /var/log/icinga2/debug.log | grep EventCommand tail -f /var/log/icinga2/debug.log | grep EventCommand
``` ```

18
doc/05-service-monitoring.md
View File

@ -53,13 +53,13 @@ by trying to run it on the console using whichever user Icinga 2 is running as:
RHEL/CentOS/Fedora RHEL/CentOS/Fedora
``` ```bash
sudo -u icinga /usr/lib64/nagios/plugins/check_mysql_health --help sudo -u icinga /usr/lib64/nagios/plugins/check_mysql_health --help
``` ```
Debian/Ubuntu Debian/Ubuntu
``` ```bash
sudo -u nagios /usr/lib/nagios/plugins/check_mysql_health --help sudo -u nagios /usr/lib/nagios/plugins/check_mysql_health --help
``` ```
@ -123,7 +123,7 @@ and reference this in the created CheckCommand objects.
Create a common directory e.g. `/opt/monitoring/plugins` Create a common directory e.g. `/opt/monitoring/plugins`
and install the plugin there. and install the plugin there.
``` ```bash
mkdir -p /opt/monitoring/plugins mkdir -p /opt/monitoring/plugins
cp check_snmp_int.pl /opt/monitoring/plugins cp check_snmp_int.pl /opt/monitoring/plugins
chmod +x /opt/monitoring/plugins/check_snmp_int.pl chmod +x /opt/monitoring/plugins/check_snmp_int.pl
@ -155,7 +155,7 @@ with the required parameters first.
Example for database size checks with [check_mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health). Example for database size checks with [check_mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health).
``` ```bash
/usr/lib64/nagios/plugins/check_mysql_health --hostname '127.0.0.1' --username root --password icingar0xx --mode sql --name 'select sum(data_length + index_length) / 1024 / 1024 from information_schema.tables where table_schema = '\''icinga'\'';' '--name2' 'db_size' --units 'MB' --warning 4096 --critical 8192 /usr/lib64/nagios/plugins/check_mysql_health --hostname '127.0.0.1' --username root --password icingar0xx --mode sql --name 'select sum(data_length + index_length) / 1024 / 1024 from information_schema.tables where table_schema = '\''icinga'\'';' '--name2' 'db_size' --units 'MB' --warning 4096 --critical 8192
``` ```
@ -520,7 +520,7 @@ add them to the argument parser.
Example for Python: Example for Python:
``` ```python
import argparse import argparse
import signal import signal
import sys import sys
@ -538,7 +538,7 @@ Users might call plugins only with the critical threshold parameter,
leaving out the warning parameter. Keep this in mind when evaluating leaving out the warning parameter. Keep this in mind when evaluating
the thresholds, always check if the parameters have been defined before. the thresholds, always check if the parameters have been defined before.
``` ```python
if args.critical: if args.critical:
if ptc_value > args.critical: if ptc_value > args.critical:
print("CRITICAL - ...") print("CRITICAL - ...")
@ -693,7 +693,7 @@ and provide a clear message followed by the Unknown state.
Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py): Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py):
``` ```python
import argparse import argparse
import signal import signal
import sys import sys
@ -721,7 +721,7 @@ too old or new versions on the community support channels.
Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py): Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py):
``` ```python
import argparse import argparse
import signal import signal
import sys import sys
@ -745,7 +745,7 @@ the plugin.
Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py): Example in Python taken from [check_tinkerforge](https://github.com/NETWAYS/check_tinkerforge/blob/master/check_tinkerforge.py):
``` ```python
import argparse import argparse
import signal import signal
import sys import sys

14
doc/06-distributed-monitoring.md
View File

@ -148,7 +148,7 @@ and `accept_config` can be configured here.
In order to use the `api` feature you need to enable it and restart Icinga 2. In order to use the `api` feature you need to enable it and restart Icinga 2.
``` ```bash
icinga2 feature enable api icinga2 feature enable api
``` ```
@ -3012,8 +3012,8 @@ have the `checker` feature enabled.
Example: Example:
``` ```bash
# icinga2 feature enable checker icinga2 feature enable checker
``` ```
All nodes in the same zone load-balance the check execution. If one instance shuts down, All nodes in the same zone load-balance the check execution. If one instance shuts down,
@ -3026,8 +3026,8 @@ have the `notification` feature enabled.
Example: Example:
``` ```bash
# icinga2 feature enable notification icinga2 feature enable notification
``` ```
Notifications are load-balanced amongst all nodes in a zone. By default this functionality Notifications are load-balanced amongst all nodes in a zone. By default this functionality
@ -3043,8 +3043,8 @@ have the DB IDO feature enabled.
Example DB IDO MySQL: Example DB IDO MySQL:
``` ```bash
# icinga2 feature enable ido-mysql icinga2 feature enable ido-mysql
``` ```
By default the DB IDO feature only runs on one node. All other nodes in the same zone disable By default the DB IDO feature only runs on one node. All other nodes in the same zone disable

10
doc/07-agent-based-monitoring.md
View File

@ -73,7 +73,7 @@ CheckCommand already.
SSH key pair for the Icinga daemon user. In case the user has no shell, temporarily enable this. SSH key pair for the Icinga daemon user. In case the user has no shell, temporarily enable this.
When asked for a passphrase, **do not set it** and press enter. When asked for a passphrase, **do not set it** and press enter.
``` ```bash
sudo su - icinga sudo su - icinga
ssh-keygen -b 4096 -t rsa -C "icinga@$(hostname) user for check_by_ssh" -f $HOME/.ssh/id_rsa ssh-keygen -b 4096 -t rsa -C "icinga@$(hostname) user for check_by_ssh" -f $HOME/.ssh/id_rsa
@ -81,7 +81,7 @@ ssh-keygen -b 4096 -t rsa -C "icinga@$(hostname) user for check_by_ssh" -f $HOME
On the remote agent, create the icinga user and generate a temporary password. On the remote agent, create the icinga user and generate a temporary password.
``` ```bash
useradd -m icinga useradd -m icinga
passwd icinga passwd icinga
``` ```
@ -90,7 +90,7 @@ Copy the public key from the Icinga server to the remote agent, e.g. with `ssh-c
or manually into `/home/icinga/.ssh/authorized_keys`. or manually into `/home/icinga/.ssh/authorized_keys`.
This will ask for the password once. This will ask for the password once.
``` ```bash
sudo su - icinga sudo su - icinga
ssh-copy-id -i $HOME/.ssh/id_rsa icinga@ssh-agent1.localdomain ssh-copy-id -i $HOME/.ssh/id_rsa icinga@ssh-agent1.localdomain
@ -100,7 +100,7 @@ After the SSH key is copied, test at the connection **at least once** and
accept the host key verification. If you forget about this step, checks will accept the host key verification. If you forget about this step, checks will
become UNKNOWN later. become UNKNOWN later.
``` ```bash
ssh -i $HOME/.ssh/id_rsa icinga@ssh-agent1.localdomain ssh -i $HOME/.ssh/id_rsa icinga@ssh-agent1.localdomain
``` ```
@ -273,7 +273,7 @@ Create the `coldstart_reset_event.sh` shell script to pass the expanded variable
data in. The `$service.state_id$` is important in order to prevent an endless loop data in. The `$service.state_id$` is important in order to prevent an endless loop
of event firing after the service has been reset. of event firing after the service has been reset.
``` ```bash
#!/bin/bash #!/bin/bash
SERVICE_STATE_ID="" SERVICE_STATE_ID=""

24
doc/11-cli-commands.md
View File

@ -75,28 +75,28 @@ You need to install the `bash-completion` package if not already installed.
RHEL/CentOS/Fedora: RHEL/CentOS/Fedora:
``` ```bash
# yum install bash-completion yum install bash-completion
``` ```
SUSE: SUSE:
``` ```bash
# zypper install bash-completion zypper install bash-completion
``` ```
Debian/Ubuntu: Debian/Ubuntu:
``` ```bash
# apt-get install bash-completion apt-get install bash-completion
``` ```
Ensure that the `bash-completion.d` directory is added to your shell Ensure that the `bash-completion.d` directory is added to your shell
environment. You can manually source the icinga2 bash-completion file environment. You can manually source the icinga2 bash-completion file
into your current session and test it: into your current session and test it:
``` ```bash
# source /etc/bash-completion.d/icinga2 source /etc/bash-completion.d/icinga2
``` ```
@ -305,8 +305,8 @@ On operating systems without the `libedit` library installed there is no
support for line-editing or a command history. However you can support for line-editing or a command history. However you can
use the `rlwrap` program if you require those features: use the `rlwrap` program if you require those features:
``` ```bash
$ rlwrap icinga2 console rlwrap icinga2 console
``` ```
The debug console can be used to connect to a running Icinga 2 instance using The debug console can be used to connect to a running Icinga 2 instance using
@ -725,8 +725,8 @@ Every time you have changed your configuration you should first tell Icinga 2
to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
safely reload the Icinga 2 daemon. safely reload the Icinga 2 daemon.
``` ```bash
# systemctl reload icinga2 systemctl reload icinga2
``` ```
The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon

347
doc/12-icinga2-api.md
View File

@ -23,14 +23,14 @@ You can run the CLI command `icinga2 api setup` to enable the
certificates as well as a new API user `root` with an auto-generated password in the certificates as well as a new API user `root` with an auto-generated password in the
`/etc/icinga2/conf.d/api-users.conf` configuration file: `/etc/icinga2/conf.d/api-users.conf` configuration file:
``` ```bash
# icinga2 api setup icinga2 api setup
``` ```
Make sure to restart Icinga 2 to enable the changes you just made: Make sure to restart Icinga 2 to enable the changes you just made:
``` ```bash
# systemctl restart icinga2 systemctl restart icinga2
``` ```
If you prefer to set up the API manually, you will have to perform the following steps: If you prefer to set up the API manually, you will have to perform the following steps:
@ -96,7 +96,7 @@ list. Depending on the number of affected objects in your request, the
The output will be sent back as a JSON object: The output will be sent back as a JSON object:
``` ```json
{ {
"results": [ "results": [
{ {
@ -114,14 +114,14 @@ The output will be sent back as a JSON object:
You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool` You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool`
in combination with curl on the CLI. in combination with curl on the CLI.
``` ```bash
curl ... | jq curl ... | jq
curl ... | python -m json.tool curl ... | python -m json.tool
``` ```
jq also has additional filter capabilities, as shown in [this blogpost](https://www.netways.de/blog/2018/08/24/json-in-bequem/). jq also has additional filter capabilities, as shown in [this blogpost](https://www.netways.de/blog/2018/08/24/json-in-bequem/).
``` ```bash
curl ... |jq '{name: .results[].name}' curl ... |jq '{name: .results[].name}'
``` ```
@ -198,8 +198,8 @@ An `ApiUser` object can have both authentication methods configured.
You can test authentication by sending a GET request to the API: You can test authentication by sending a GET request to the API:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1'
``` ```
In case you get an error message make sure to check the API user credentials. In case you get an error message make sure to check the API user credentials.
@ -207,8 +207,8 @@ In case you get an error message make sure to check the API user credentials.
When using client certificates for authentication you'll need to pass your client certificate When using client certificates for authentication you'll need to pass your client certificate
and private key to the curl call: and private key to the curl call:
``` ```bash
$ curl -k --cert example.localdomain.crt --key example.localdomain.key 'https://example.localdomain:5665/v1/status' curl -k --cert example.localdomain.crt --key example.localdomain.key 'https://example.localdomain:5665/v1/status'
``` ```
In case of an error make sure to verify the client certificate and CA. In case of an error make sure to verify the client certificate and CA.
@ -217,8 +217,8 @@ The curl parameter `-k` disables certificate verification and should therefore
only be used for testing. In order to securely check each connection you'll need to only be used for testing. In order to securely check each connection you'll need to
specify the trusted CA certificate using the curl parameter`--cacert`: specify the trusted CA certificate using the curl parameter`--cacert`:
``` ```bash
$ curl -u root:icinga --cacert ca.crt 'icinga2.node1.localdomain:5665/v1' curl -u root:icinga --cacert ca.crt 'icinga2.node1.localdomain:5665/v1'
``` ```
Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions) Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions)
@ -319,7 +319,7 @@ Example for a URL-encoded query string:
Here are the exact same query parameters as a JSON object: Here are the exact same query parameters as a JSON object:
``` ```json
{ "filter": "match(\"example.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] } { "filter": "match(\"example.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] }
``` ```
@ -349,7 +349,7 @@ Example as URL parameter:
Example as JSON object: Example as JSON object:
``` ```json
{ "pretty": true } { "pretty": true }
``` ```
@ -361,16 +361,16 @@ header. This comes in handy when you are using HTTP proxies disallowing `PUT` or
Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header: Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
``` ```bash
$ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/hosts' 'https://localhost:5665/v1/objects/hosts'
``` ```
Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header: Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
``` ```bash
$ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: DELETE' -X POST \ -H 'X-HTTP-Method-Override: DELETE' -X POST \
'https://localhost:5665/v1/objects/hosts/example.localdomain' 'https://localhost:5665/v1/objects/hosts/example.localdomain'
``` ```
@ -378,7 +378,7 @@ $ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
Query objects with complex filters. For a detailed introduction into filter, please Query objects with complex filters. For a detailed introduction into filter, please
read the [following chapter](12-icinga2-api.md#icinga2-api-filters). read the [following chapter](12-icinga2-api.md#icinga2-api-filters).
``` ```bash
curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/services' \ 'https://localhost:5665/v1/objects/services' \
@ -481,8 +481,8 @@ Some queries can be performed for more than just one object type. One example is
action which can be used for both hosts and services. When using advanced filters you will also have to specify the action which can be used for both hosts and services. When using advanced filters you will also have to specify the
type using the `type` parameter: type using the `type` parameter:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X POST \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X POST \
'https://localhost:5665/v1/actions/reschedule-check' \ 'https://localhost:5665/v1/actions/reschedule-check' \
-d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }' -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }'
``` ```
@ -511,8 +511,8 @@ assign its value inside the `filter_vars` dictionary.
That way you can also keep the `filter` string the same for different That way you can also keep the `filter` string the same for different
requests with only changing the `filter_vars`. requests with only changing the `filter_vars`.
``` ```bash
$ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/hosts' \ 'https://localhost:5665/v1/objects/hosts' \
-d '{ "filter": "group in host.groups", "filter_vars": { "group": "linux-servers" }, "pretty": true }' -d '{ "filter": "group in host.groups", "filter_vars": { "group": "linux-servers" }, "pretty": true }'
@ -527,7 +527,7 @@ a URL parameter because there is no way to specify a dictionary in a URL.
The example from [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) The example from [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
can be enhanced to avoid additional parameter value escaping. can be enhanced to avoid additional parameter value escaping.
``` ```bash
curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/services' \ 'https://localhost:5665/v1/objects/services' \
@ -569,8 +569,8 @@ a `GET` query to the `/v1/objects/<type>` URL endpoint. `<type` has
to be replaced with the plural name of the object type you are interested to be replaced with the plural name of the object type you are interested
in: in:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts'
``` ```
A list of all available configuration types is available in the A list of all available configuration types is available in the
@ -590,22 +590,22 @@ Instead of using a filter you can optionally specify the object name in the
URL path when querying a single object. For objects with composite names URL path when querying a single object. For objects with composite names
(e.g. services) the full name (e.g. `example.localdomain!http`) must be specified: (e.g. services) the full name (e.g. `example.localdomain!http`) must be specified:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services/example.localdomain!http' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services/example.localdomain!http'
``` ```
You can limit the output to specific attributes using the `attrs` URL parameter: You can limit the output to specific attributes using the `attrs` URL parameter:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address&pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address&pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
"attrs": { "attrs": {
"name": "example.localdomain" "name": "example.localdomain",
"address": "192.168.1.1" "address": "192.168.1.1"
}, },
"joins": {}, "joins": {},
@ -676,11 +676,11 @@ custom variable set to `Linux`. The result set contains the `display_name` and `
attributes for the service. The query also returns the host's `name` and `address` attribute attributes for the service. The query also returns the host's `name` and `address` attribute
via a join: via a join:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=display_name&attrs=check_command&joins=host.name&joins=host.address&filter=host.vars.os==%22Linux%22&pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=display_name&attrs=check_command&joins=host.name&joins=host.address&filter=host.vars.os==%22Linux%22&pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -722,8 +722,8 @@ $ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/objects/services?at
> Use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) > Use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
> and pass everything in the request body like this: > and pass everything in the request body like this:
``` ```bash
$ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/services' \ 'https://localhost:5665/v1/objects/services' \
-d '{ "attrs": [ "display_name", "check_command" ], "joins": [ "host.name", "host.address" ], "filter": "host.vars.os==\"Linux\"", "pretty": true }' -d '{ "attrs": [ "display_name", "check_command" ], "joins": [ "host.name", "host.address" ], "filter": "host.vars.os==\"Linux\"", "pretty": true }'
@ -741,14 +741,14 @@ This is another example for listing all service objects which are unhandled prob
and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here because we want to pass all query attributes in the request body. here because we want to pass all query attributes in the request body.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://127.0.0.1:5665/v1/objects/services' \ 'https://127.0.0.1:5665/v1/objects/services' \
-d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }' -d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -776,14 +776,14 @@ In order to list all acknowledgements without expire time, you query the `/v1/ob
URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
method: method:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5665/v1/objects/comments' \ 'https://localhost:5665/v1/objects/comments' \
-d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }' -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -828,13 +828,13 @@ If attributes are of the Dictionary type, you can also use the indexer format. T
Example for creating the new host object `example.localdomain`: Example for creating the new host object `example.localdomain`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
-d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }' -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -849,13 +849,13 @@ If the configuration validation fails, the new object will not be created and th
contains a detailed error message. The following example is missing the `check_command` attribute contains a detailed error message. The following example is missing the `check_command` attribute
which is required for host objects: which is required for host objects:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
-d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }' -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -871,16 +871,16 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Service objects must be created using their full name ("hostname!servicename") referencing an existing host object: Service objects must be created using their full name ("hostname!servicename") referencing an existing host object:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \ -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \
-d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }' -d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }'
``` ```
Example for a new CheckCommand object: Example for a new CheckCommand object:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \ -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \
-d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }' -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }'
``` ```
@ -917,13 +917,13 @@ If attributes are of the [Dictionary](17-language-reference.md#dictionary) type,
The following example updates the `address` attribute and the custom variable `os` for the `example.localdomain` host: The following example updates the `address` attribute and the custom variable `os` for the `example.localdomain` host:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \ -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
-d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }' -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -949,12 +949,12 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for deleting the host object `example.localdomain`: Example for deleting the host object `example.localdomain`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -987,8 +987,8 @@ notification on a program-wide basis must be applied by updating the
[IcingaApplication object](12-icinga2-api.md#icinga2-api-config-objects) [IcingaApplication object](12-icinga2-api.md#icinga2-api-config-objects)
called `app`. called `app`.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/objects/icingaapplications/app' \ -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' \
-d '{ "attrs": { "enable_notifications": false } }' -d '{ "attrs": { "enable_notifications": false } }'
``` ```
@ -998,8 +998,11 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
If you don't want to write JSON manually, especially for adding the `start_time` If you don't want to write JSON manually, especially for adding the `start_time`
and `end_time` parameters, you can use [jo](https://github.com/jpmens/jo) to format this. and `end_time` parameters, you can use [jo](https://github.com/jpmens/jo) to format this.
```bash
jo -p pretty=true type=Service filter="service.name==\"ping4\"" author=icingaadmin comment="IPv4 network maintenance" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour")
``` ```
$ jo -p pretty=true type=Service filter="service.name==\"ping4\"" author=icingaadmin comment="IPv4 network maintenance" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour")
```json
{ {
"pretty": true, "pretty": true,
"type": "Service", "type": "Service",
@ -1014,8 +1017,8 @@ $ jo -p pretty=true type=Service filter="service.name==\"ping4\"" author=icingaa
Now wrap this into the actual curl command: Now wrap this into the actual curl command:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/schedule-downtime' \ -X POST 'https://localhost:5665/v1/actions/schedule-downtime' \
-d "$(jo -p pretty=true type=Service filter="service.name==\"ping4\"" author=icingaadmin comment="IPv4 network maintanence" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour"))" -d "$(jo -p pretty=true type=Service filter="service.name==\"ping4\"" author=icingaadmin comment="IPv4 network maintanence" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour"))"
``` ```
@ -1043,13 +1046,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for the service `passive-ping`: Example for the service `passive-ping`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/process-check-result' \ -X POST 'https://localhost:5665/v1/actions/process-check-result' \
-d '{ "type": "Service", "filter": "host.name==\"icinga2-master1.localdomain\" && service.name==\"passive-ping\"", "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }' -d '{ "type": "Service", "filter": "host.name==\"icinga2-master1.localdomain\" && service.name==\"passive-ping\"", "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1064,8 +1067,8 @@ You can avoid URL encoding of white spaces in object names by using the `filter`
Example for using the `Host` type and filter by the host name: Example for using the `Host` type and filter by the host name:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/process-check-result' \ -X POST 'https://localhost:5665/v1/actions/process-check-result' \
-d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }' -d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }'
``` ```
@ -1094,13 +1097,13 @@ The example reschedules all services with the name "ping6" to immediately perfor
(`next_check` default), ignoring any time periods or whether active checks are (`next_check` default), ignoring any time periods or whether active checks are
allowed for the service (`force=true`). allowed for the service (`force=true`).
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/reschedule-check' \ -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
-d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }' -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1129,13 +1132,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for a custom host notification announcing a global maintenance to Example for a custom host notification announcing a global maintenance to
host owners: host owners:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/send-custom-notification' \ -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
-d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }' -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1146,6 +1149,7 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
"code": 200.0, "code": 200.0,
"status": "Successfully sent custom notification for object 'host1'." "status": "Successfully sent custom notification for object 'host1'."
} }
]
} }
``` ```
@ -1166,13 +1170,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/delay-notification' \ -X POST 'https://localhost:5665/v1/actions/delay-notification' \
-d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }' -d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1183,6 +1187,7 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
"code": 200.0, "code": 200.0,
"status": "Successfully delayed notifications for object 'host1!service1'." "status": "Successfully delayed notifications for object 'host1!service1'."
} }
]
} }
``` ```
@ -1208,13 +1213,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
The following example acknowledges all services which are in a hard critical state and sends out The following example acknowledges all services which are in a hard critical state and sends out
a notification for them: a notification for them:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/acknowledge-problem' \ -X POST 'https://localhost:5665/v1/actions/acknowledge-problem' \
-d '{ "type": "Service", "filter": "service.state==2&service.state_type=1", "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }' -d '{ "type": "Service", "filter": "service.state==2&service.state_type=1", "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1225,6 +1230,7 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
"code": 200.0, "code": 200.0,
"status": "Successfully acknowledged problem for object 'icinga2-satellite2.localdomain!ping4'." "status": "Successfully acknowledged problem for object 'icinga2-satellite2.localdomain!ping4'."
} }
]
} }
``` ```
@ -1243,13 +1249,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
The example removes all service acknowledgements: The example removes all service acknowledgements:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-acknowledgement' \ -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement' \
-d '{ "type": "Service", "pretty": true }' -d '{ "type": "Service", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1260,6 +1266,7 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
"code": 200.0, "code": 200.0,
"status": "Successfully removed acknowledgement for object 'example2.localdomain!aws-health'." "status": "Successfully removed acknowledgement for object 'example2.localdomain!aws-health'."
} }
]
} }
``` ```
@ -1278,13 +1285,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
The following example adds a comment for all `ping4` services: The following example adds a comment for all `ping4` services:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/add-comment' \ -X POST 'https://localhost:5665/v1/actions/add-comment' \
-d '{ "type": "Service", "filter": "service.name==\"ping4\"", "author": "icingaadmin", "comment": "Troubleticket #123456789 opened.", "pretty": true }' -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "author": "icingaadmin", "comment": "Troubleticket #123456789 opened.", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1320,13 +1327,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for a simple filter using the `comment` URL parameter: Example for a simple filter using the `comment` URL parameter:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-comment' \ -X POST 'https://localhost:5665/v1/actions/remove-comment' \
-d '{ "comment": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f", "pretty": true }' -d '{ "comment": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1339,13 +1346,13 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Example for removing all service comments using a service name filter for `ping4`: Example for removing all service comments using a service name filter for `ping4`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-comment' -X POST 'https://localhost:5665/v1/actions/remove-comment'
-d '{ "type": "Service", "filter": "service.name==\"ping4\"", "pretty": true }' -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1382,13 +1389,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for scheduling a downtime for all `ping4` services: Example for scheduling a downtime for all `ping4` services:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/schedule-downtime' \ -X POST 'https://localhost:5665/v1/actions/schedule-downtime' \
-d '{ "type": "Service", "filter": "service.name==\"ping4\"", "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance", "pretty": true }' -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1419,8 +1426,8 @@ like this:
Schedule a downtime for one (or multiple) hosts and all of their services. Schedule a downtime for one (or multiple) hosts and all of their services.
Note the `all_services` attribute. Note the `all_services` attribute.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/schedule-downtime' \ -X POST 'https://localhost:5665/v1/actions/schedule-downtime' \
-d "$(jo -p pretty=true type=Host filter="match(\"*satellite*\", host.name)" all_services=true author=icingaadmin comment="Cluster upgrade maintenance" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour"))" -d "$(jo -p pretty=true type=Host filter="match(\"*satellite*\", host.name)" all_services=true author=icingaadmin comment="Cluster upgrade maintenance" fixed=true start_time=$(date +%s -d "+0 hour") end_time=$(date +%s -d "+1 hour"))"
``` ```
@ -1442,13 +1449,13 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
Example for a simple filter using the `downtime` URL parameter: Example for a simple filter using the `downtime` URL parameter:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-downtime' \ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
-d '{ "downtime": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347", "pretty": true }' -d '{ "downtime": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1461,13 +1468,13 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Example for removing all host downtimes using a host name filter for `icinga2-satellite2.localdomain`: Example for removing all host downtimes using a host name filter for `icinga2-satellite2.localdomain`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-downtime' \ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
-d '{ "type": "Host", "filter": "host.name==\"icinga2-satellite2.localdomain\"", "pretty": true }' -d '{ "type": "Host", "filter": "host.name==\"icinga2-satellite2.localdomain\"", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1481,8 +1488,8 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Example for removing a downtime from a host but not the services filtered by the author name. This example uses Example for removing a downtime from a host but not the services filtered by the author name. This example uses
filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-api-advanced-filters) chapter. filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-api-advanced-filters) chapter.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/remove-downtime' \ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
-d $'{ -d $'{
"type": "Downtime", "type": "Downtime",
@ -1495,7 +1502,7 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
}' }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1516,12 +1523,12 @@ This action does not support a target type or filter.
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1' -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1542,12 +1549,12 @@ This action does not support a target type or filter.
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1' -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1577,13 +1584,13 @@ Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/generate-ticket' \ -X POST 'https://localhost:5665/v1/actions/generate-ticket' \
-d '{ "cn": "icinga2-agent1.localdomain", "pretty": true }' -d '{ "cn": "icinga2-agent1.localdomain", "pretty": true }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1618,13 +1625,13 @@ Send a `POST` request to the URL endpoint `/v1/actions/execute-command`.
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/execute-command' \ -X POST 'https://localhost:5665/v1/actions/execute-command' \
-d '{"type": "Service", "service": "agent!custom_service", "ttl": 15, "macros": { "command_endpoint": "master", "ls_dir": "/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }' -d '{"type": "Service", "service": "agent!custom_service", "ttl": 15, "macros": { "command_endpoint": "master", "ls_dir": "/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1849,8 +1856,8 @@ must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/events' \ -X POST 'https://localhost:5665/v1/events' \
-d '{ "queue": "myqueue", "types": [ "CheckResult" ], "filter": "event.check_result.exit_status==2" }' -d '{ "queue": "myqueue", "types": [ "CheckResult" ], "filter": "event.check_result.exit_status==2" }'
``` ```
@ -1867,8 +1874,8 @@ Send a `GET` request to the URL endpoint `/v1/status` to retrieve status informa
Example: Example:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/status?pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/status?pretty=1'
``` ```
``` ```
@ -1892,11 +1899,11 @@ $ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/status?pretty=1'
You can limit the output by specifying a status type in the URL, e.g. `IcingaApplication`: You can limit the output by specifying a status type in the URL, e.g. `IcingaApplication`:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication?pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -1945,12 +1952,12 @@ deploy global templates in [global cluster zones](06-distributed-monitoring.md#d
Send a `POST` request to a new config package called `example-cmdb` in this example. This Send a `POST` request to a new config package called `example-cmdb` in this example. This
creates a new empty configuration package. creates a new empty configuration package.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1' -X POST 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2011,13 +2018,13 @@ The example below will create a new file called `test.conf` in the `conf.d`
directory. Note: This example contains an error (`chec_command`). This is directory. Note: This example contains an error (`chec_command`). This is
intentional. intentional.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X POST \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X POST \
-d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" }, "pretty": true }' \ -d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" }, "pretty": true }' \
'https://localhost:5665/v1/config/stages/example-cmdb' 'https://localhost:5665/v1/config/stages/example-cmdb'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2066,11 +2073,11 @@ A list of packages and their stages can be retrieved by sending a `GET` request
The following example contains one configuration package `example-cmdb`. The package does not currently The following example contains one configuration package `example-cmdb`. The package does not currently
have an active stage. have an active stage.
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2090,8 +2097,8 @@ In order to retrieve a list of files for a stage you can send a `GET` request to
the URL endpoint `/v1/config/stages`. You need to include the URL endpoint `/v1/config/stages`. You need to include
the package name (`example-cmdb`) and stage name (`7e7861c8-8008-4e8d-9910-2a0bb26921bd`) in the URL: the package name (`example-cmdb`) and stage name (`7e7861c8-8008-4e8d-9910-2a0bb26921bd`) in the URL:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1'
``` ```
``` ```
@ -2133,8 +2140,8 @@ the package name, the stage name and the relative path to the file to the URL pa
The following example fetches the configuration file `conf.d/test.conf`: The following example fetches the configuration file `conf.d/test.conf`:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf'
``` ```
``` ```
@ -2153,8 +2160,8 @@ In order to check for validation errors you can fetch the `startup.log` file
by sending a `GET` request to the URL endpoint `/v1/config/files`. You must include by sending a `GET` request to the URL endpoint `/v1/config/files`. You must include
the package name, stage name and the `startup.log` in the URL path. the package name, stage name and the `startup.log` in the URL path.
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/startup.log' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/startup.log'
``` ```
``` ```
@ -2183,12 +2190,12 @@ stage name inside the URL path.
The following example removes the failed configuration stage `7e7861c8-8008-4e8d-9910-2a0bb26921bd` The following example removes the failed configuration stage `7e7861c8-8008-4e8d-9910-2a0bb26921bd`
in the `example-cmdb` configuration package: in the `example-cmdb` configuration package:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X DELETE 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1' -X DELETE 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2207,12 +2214,12 @@ with the package name in the URL path.
This example entirely deletes the configuration package `example-cmdb`: This example entirely deletes the configuration package `example-cmdb`:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X DELETE \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' -X DELETE \
'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1' 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2242,11 +2249,11 @@ Each response entry in the results array contains the following attributes:
In order to view a specific configuration object type specify its name inside the URL path: In order to view a specific configuration object type specify its name inside the URL path:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/types/Object?pretty=1' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/types/Object?pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2293,8 +2300,8 @@ a `GET` query to the `/v1/templates/<type>` URL endpoint. `<type` has
to be replaced with the plural name of the object type you are interested to be replaced with the plural name of the object type you are interested
in: in:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts'
``` ```
A list of all available configuration types is available in the A list of all available configuration types is available in the
@ -2307,8 +2314,8 @@ check a wildcard string pattern against `tmpl.name`.
The `filter` attribute is passed inside the request body thus requiring to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) The `filter` attribute is passed inside the request body thus requiring to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here. here.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5661/v1/templates/hosts' \ 'https://localhost:5661/v1/templates/hosts' \
-d '{ "filter": "match(\"g*\", tmpl.name)" }' -d '{ "filter": "match(\"g*\", tmpl.name)" }'
@ -2317,8 +2324,8 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Instead of using a filter you can optionally specify the template name in the Instead of using a filter you can optionally specify the template name in the
URL path when querying a single object: URL path when querying a single object:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts/generic-host' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/templates/hosts/generic-host'
``` ```
The result set contains the type, name as well as the location of the template. The result set contains the type, name as well as the location of the template.
@ -2334,8 +2341,8 @@ Provides methods to manage global variables:
You can request information about global variables by sending You can request information about global variables by sending
a `GET` query to the `/v1/variables/` URL endpoint: a `GET` query to the `/v1/variables/` URL endpoint:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/variables' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/variables'
``` ```
A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The
@ -2343,8 +2350,8 @@ variable information object can be accessed in the filter using the `variable` v
The `filter` attribute is passed inside the request body thus requiring to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) The `filter` attribute is passed inside the request body thus requiring to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here. here.
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-H 'X-HTTP-Method-Override: GET' -X POST \ -H 'X-HTTP-Method-Override: GET' -X POST \
'https://localhost:5661/v1/variables' \ 'https://localhost:5661/v1/variables' \
-d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }' -d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }'
@ -2353,8 +2360,8 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Instead of using a filter you can optionally specify the variable name in the Instead of using a filter you can optionally specify the variable name in the
URL path when querying a single variable: URL path when querying a single variable:
``` ```bash
$ curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/variables/PrefixDir' curl -k -s -S -i -u root:icinga 'https://localhost:5665/v1/variables/PrefixDir'
``` ```
The result set contains the type, name and value of the global variable. The result set contains the type, name and value of the global variable.
@ -2390,12 +2397,12 @@ If you specify a session identifier, the same script context can be reused for m
Example for fetching the command line from the local host's last check result: Example for fetching the command line from the local host's last check result:
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1' -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2418,12 +2425,12 @@ $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
Example for fetching auto-completion suggestions for the `Host.` type. This works in a Example for fetching auto-completion suggestions for the `Host.` type. This works in a
similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console): similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console):
``` ```bash
$ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1' -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
``` ```
``` ```json
{ {
"results": [ "results": [
{ {
@ -2820,7 +2827,7 @@ func main() {
Build the binary: Build the binary:
``` ```bash
go build icinga.go go build icinga.go
./icinga ./icinga
``` ```

14
doc/13-addons.md
View File

@ -40,8 +40,8 @@ You need to install Graphite first, then proceed with configuring it in Icinga 2
Use the [GraphiteWriter](14-features.md#graphite-carbon-cache-writer) feature Use the [GraphiteWriter](14-features.md#graphite-carbon-cache-writer) feature
for sending real-time metrics from Icinga 2 to Graphite. for sending real-time metrics from Icinga 2 to Graphite.
``` ```bash
# icinga2 feature enable graphite icinga2 feature enable graphite
``` ```
A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org). A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org).
@ -59,8 +59,8 @@ It’s written in Go and has no external dependencies.
Use the [InfluxdbWriter](14-features.md#influxdb-writer) feature Use the [InfluxdbWriter](14-features.md#influxdb-writer) feature
for sending real-time metrics from Icinga 2 to InfluxDB. for sending real-time metrics from Icinga 2 to InfluxDB.
``` ```bash
# icinga2 feature enable influxdb icinga2 feature enable influxdb
``` ```
A popular frontend for InfluxDB is for example [Grafana](https://grafana.org). A popular frontend for InfluxDB is for example [Grafana](https://grafana.org).
@ -86,13 +86,13 @@ data files which Icinga 2 generates.
Enable performance data writer in icinga 2 Enable performance data writer in icinga 2
``` ```bash
# icinga2 feature enable perfdata icinga2 feature enable perfdata
``` ```
Configure npcd to use the performance data created by Icinga 2: Configure npcd to use the performance data created by Icinga 2:
``` ```bash
vim /etc/pnp4nagios/npcd.cfg vim /etc/pnp4nagios/npcd.cfg
``` ```

58
doc/14-features.md
View File

@ -198,7 +198,7 @@ mariadb> OPTIMIZE TABLE icinga_statehistory;
If you want to optimize all tables in a specified database, there is a script called `mysqlcheck`. If you want to optimize all tables in a specified database, there is a script called `mysqlcheck`.
This also allows to repair broken tables in the case of emergency. This also allows to repair broken tables in the case of emergency.
``` ```bash
mysqlcheck --optimize icinga mysqlcheck --optimize icinga
``` ```
@ -241,8 +241,8 @@ TCP port, defaulting to `2003`.
You can enable the feature using You can enable the feature using
``` ```bash
# icinga2 feature enable graphite icinga2 feature enable graphite
``` ```
By default the [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) feature By default the [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) feature
@ -372,8 +372,8 @@ defined InfluxDB HTTP API.
You can enable the feature using You can enable the feature using
``` ```bash
# icinga2 feature enable influxdb icinga2 feature enable influxdb
``` ```
By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature
@ -488,8 +488,8 @@ The check results include parsed performance data metrics if enabled.
Enable the feature and restart Icinga 2. Enable the feature and restart Icinga 2.
``` ```bash
# icinga2 feature enable elasticsearch icinga2 feature enable elasticsearch
``` ```
The default configuration expects an Elasticsearch instance running on `localhost` on port `9200` The default configuration expects an Elasticsearch instance running on `localhost` on port `9200`
@ -572,8 +572,8 @@ While it has been specified by the [Graylog](https://www.graylog.org) project as
You can enable the feature using You can enable the feature using
``` ```bash
# icinga2 feature enable gelf icinga2 feature enable gelf
``` ```
By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`. By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
@ -612,8 +612,8 @@ write them to the defined TSDB TCP socket.
You can enable the feature using You can enable the feature using
``` ```bash
# icinga2 feature enable opentsdb icinga2 feature enable opentsdb
``` ```
By default the `OpenTsdbWriter` object expects the TSD to listen at By default the `OpenTsdbWriter` object expects the TSD to listen at
@ -888,8 +888,8 @@ service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOS
The default templates are already provided with the Icinga 2 feature configuration The default templates are already provided with the Icinga 2 feature configuration
which can be enabled using which can be enabled using
``` ```bash
# icinga2 feature enable perfdata icinga2 feature enable perfdata
``` ```
By default all performance data files are rotated in a 15 seconds interval into By default all performance data files are rotated in a 15 seconds interval into
@ -936,8 +936,8 @@ interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
the `StatusDataWriter` object which dumps all configuration objects and the `StatusDataWriter` object which dumps all configuration objects and
status updates in a regular interval. status updates in a regular interval.
``` ```bash
# icinga2 feature enable statusdata icinga2 feature enable statusdata
``` ```
If you are not using any web interface or addon which uses these files, If you are not using any web interface or addon which uses these files,
@ -961,8 +961,8 @@ for answering queries to historical tables.
The `CompatLogger` object can be enabled with The `CompatLogger` object can be enabled with
``` ```bash
# icinga2 feature enable compatlog icinga2 feature enable compatlog
``` ```
By default, the Icinga 1.x log file called `icinga.log` is located By default, the Icinga 1.x log file called `icinga.log` is located
@ -988,8 +988,8 @@ through the web interface).
In order to enable the `ExternalCommandListener` configuration use the In order to enable the `ExternalCommandListener` configuration use the
following command and restart Icinga 2 afterwards: following command and restart Icinga 2 afterwards:
``` ```bash
# icinga2 feature enable command icinga2 feature enable command
``` ```
Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd` Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
@ -1067,14 +1067,14 @@ in the [Livestatus Schema](24-appendix.md#schema-livestatus) section.
You can enable Livestatus using icinga2 feature enable: You can enable Livestatus using icinga2 feature enable:
``` ```bash
# icinga2 feature enable livestatus icinga2 feature enable livestatus
``` ```
After that you will have to restart Icinga 2: After that you will have to restart Icinga 2:
``` ```bash
# systemctl restart icinga2 systemctl restart icinga2
``` ```
By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`. By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
@ -1082,8 +1082,8 @@ By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatu
In order for queries and commands to work you will need to add your query user In order for queries and commands to work you will need to add your query user
(e.g. your web server) to the `icingacmd` group: (e.g. your web server) to the `icingacmd` group:
``` ```bash
# usermod -a -G icingacmd www-data usermod -a -G icingacmd www-data
``` ```
The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
@ -1096,8 +1096,8 @@ In order to use the historical tables provided by the livestatus feature (for ex
are expected to be in `/var/log/icinga2/compat`. A different path can be set using the are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
`compat_log_path` configuration attribute. `compat_log_path` configuration attribute.
``` ```bash
# icinga2 feature enable compatlog icinga2 feature enable compatlog
``` ```
#### Livestatus Sockets <a id="livestatus-sockets"></a> #### Livestatus Sockets <a id="livestatus-sockets"></a>
@ -1143,8 +1143,8 @@ EOF
A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail) A list of available external commands and their parameters can be found [here](24-appendix.md#external-commands-list-detail)
``` ```bash
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558 echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
``` ```
#### Livestatus Filters <a id="livestatus-filters"></a> #### Livestatus Filters <a id="livestatus-filters"></a>

121
doc/15-troubleshooting.md
View File

@ -54,7 +54,7 @@ Install tools which help you to do so. Opinions differ, let us know if you have
[htop](https://hisham.hm/htop/) is a better replacement for `top` and helps to analyze processes [htop](https://hisham.hm/htop/) is a better replacement for `top` and helps to analyze processes
interactively. interactively.
``` ```bash
yum install htop yum install htop
apt-get install htop apt-get install htop
``` ```
@ -68,32 +68,33 @@ Attach it when posting a question to the community channels.
The [sysstat](https://github.com/sysstat/sysstat) package provides a number of tools to The [sysstat](https://github.com/sysstat/sysstat) package provides a number of tools to
analyze the performance on Linux. On FreeBSD you could use `systat` for example. analyze the performance on Linux. On FreeBSD you could use `systat` for example.
``` ```bash
yum install sysstat yum install sysstat
apt-get install sysstat apt-get install sysstat
``` ```
Example for `vmstat` (summary of memory, processes, etc.): Example for `vmstat` (summary of memory, processes, etc.):
``` ```bash
// summary # summary
vmstat -s vmstat -s
// print timestamps, format in MB, stats every 1 second, 5 times # print timestamps, format in MB, stats every 1 second, 5 times
vmstat -t -S M 1 5 vmstat -t -S M 1 5
``` ```
Example for `iostat`: Example for `iostat`:
``` ```bash
watch -n 1 iostat watch -n 1 iostat
``` ```
Example for `sar`: Example for `sar`:
```
sar //cpu ```bash
sar -r //ram sar # cpu
sar -q //load avg sar -r # ram
sar -b //I/O sar -q # load avg
sar -b # I/O
``` ```
`sysstat` also provides the `iostat` binary. On FreeBSD you could use `systat` for example. `sysstat` also provides the `iostat` binary. On FreeBSD you could use `systat` for example.
@ -124,16 +125,16 @@ Get-Content .\icinga2.log -tail 10 -wait
Enable the `debuglog` feature: Enable the `debuglog` feature:
``` ```bash
# icinga2 feature enable debuglog icinga2 feature enable debuglog
# service icinga2 restart service icinga2 restart
``` ```
The debug log file can be found in `/var/log/icinga2/debug.log`. The debug log file can be found in `/var/log/icinga2/debug.log`.
You can tail the log files with an administrative shell: You can tail the log files with an administrative shell:
``` ```bash
cd /var/log/icinga2 cd /var/log/icinga2
tail -f debug.log tail -f debug.log
``` ```
@ -141,8 +142,8 @@ tail -f debug.log
Alternatively you may run Icinga 2 in the foreground with debugging enabled. Specify the console Alternatively you may run Icinga 2 in the foreground with debugging enabled. Specify the console
log severity as an additional parameter argument to `-x`. log severity as an additional parameter argument to `-x`.
``` ```bash
# /usr/sbin/icinga2 daemon -x notice /usr/sbin/icinga2 daemon -x notice
``` ```
The [log severity](09-object-types.md#objecttype-filelogger) can be one of `critical`, `warning`, `information`, `notice` The [log severity](09-object-types.md#objecttype-filelogger) can be one of `critical`, `warning`, `information`, `notice`
@ -290,8 +291,8 @@ encapsulated by `/* ... */`).
Run the [configuration validation](11-cli-commands.md#config-validation) and add `notice` as log severity. Run the [configuration validation](11-cli-commands.md#config-validation) and add `notice` as log severity.
Search for the file which should be included i.e. using the `grep` CLI command. Search for the file which should be included i.e. using the `grep` CLI command.
``` ```bash
# icinga2 daemon -C -x notice | grep command icinga2 daemon -C -x notice | grep command
``` ```
### Configuration attributes are inherited from <a id="configuration-attribute-inheritance"></a> ### Configuration attributes are inherited from <a id="configuration-attribute-inheritance"></a>
@ -382,10 +383,10 @@ $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:
Example for searching the debug log: Example for searching the debug log:
``` ```bash
# icinga2 feature enable debuglog icinga2 feature enable debuglog
# systemctl restart icinga2 systemctl restart icinga2
# tail -f /var/log/icinga2/debug.log | grep "notice/Process" tail -f /var/log/icinga2/debug.log | grep "notice/Process"
``` ```
@ -404,8 +405,8 @@ and verify why the checks are not executed there.
Test a plugin as icinga user. Test a plugin as icinga user.
``` ```bash
# sudo -u icinga /usr/lib/nagios/plugins/check_ping -4 -H 127.0.0.1 -c 5000,100% -w 3000,80% sudo -u icinga /usr/lib/nagios/plugins/check_ping -4 -H 127.0.0.1 -c 5000,100% -w 3000,80%
``` ```
> **Note** > **Note**
@ -425,8 +426,8 @@ The feature 'checker' is already enabled.
Fetch all check result events matching the `event.service` name `random`: Fetch all check result events matching the `event.service` name `random`:
``` ```bash
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29' 'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29'
``` ```
@ -579,7 +580,7 @@ The error message could look like this:
In order to solve the problem, increase the value for `DefaultTasksMax` In order to solve the problem, increase the value for `DefaultTasksMax`
or set it to `infinity`. or set it to `infinity`.
``` ```bash
mkdir /etc/systemd/system/icinga2.service.d mkdir /etc/systemd/system/icinga2.service.d
cat >/etc/systemd/system/icinga2.service.d/limits.conf <<EOF cat >/etc/systemd/system/icinga2.service.d/limits.conf <<EOF
[Service] [Service]
@ -639,8 +640,8 @@ a dashboard overview for `overdue checks`.
The REST API provides the [status](12-icinga2-api.md#icinga2-api-status) URL endpoint with some generic metrics The REST API provides the [status](12-icinga2-api.md#icinga2-api-status) URL endpoint with some generic metrics
on Icinga and its features. on Icinga and its features.
``` ```bash
# curl -k -s -u root:icinga 'https://localhost:5665/v1/status?pretty=1' | less curl -k -s -u root:icinga 'https://localhost:5665/v1/status?pretty=1' | less
``` ```
You can also calculate late check results via the REST API: You can also calculate late check results via the REST API:
@ -755,17 +756,17 @@ Examples:
The feature 'notification' is already enabled. The feature 'notification' is already enabled.
``` ```
``` ```bash
# icinga2 feature enable debuglog icinga2 feature enable debuglog
# systemctl restart icinga2 systemctl restart icinga2
# grep Notification /var/log/icinga2/debug.log > /root/analyze_notification_problem.log grep Notification /var/log/icinga2/debug.log > /root/analyze_notification_problem.log
``` ```
You can use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event-streams) to receive live notification streams: You can use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event-streams) to receive live notification streams:
``` ```bash
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification' curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification'
``` ```
@ -869,19 +870,19 @@ to `features-enabled` and that the latter is included in [icinga2.conf](04-confi
Look up the [object type](09-object-types.md#object-types) for the required feature and verify it is enabled: Look up the [object type](09-object-types.md#object-types) for the required feature and verify it is enabled:
``` ```bash
# icinga2 object list --type <feature object type> icinga2 object list --type <feature object type>
``` ```
Example for the `graphite` feature: Example for the `graphite` feature:
``` ```bash
# icinga2 object list --type GraphiteWriter icinga2 object list --type GraphiteWriter
``` ```
Look into the log and check whether the feature logs anything specific for this matter. Look into the log and check whether the feature logs anything specific for this matter.
``` ```bash
grep GraphiteWriter /var/log/icinga2/icinga2.log grep GraphiteWriter /var/log/icinga2/icinga2.log
``` ```
@ -958,7 +959,7 @@ again, carefully do the following steps with creating a backup before:
Navigate into the API package prefix. Navigate into the API package prefix.
``` ```bash
cd /var/lib/icinga2/api/packages cd /var/lib/icinga2/api/packages
``` ```
@ -983,20 +984,20 @@ If you have more than one stage directory here, pick the latest modified
directory. Copy the directory name `abcd-ef12-3456-7890` and directory. Copy the directory name `abcd-ef12-3456-7890` and
add it into a new file `active-stage`. This can be done like this: add it into a new file `active-stage`. This can be done like this:
``` ```bash
echo "dbe0bef8-c72c-4cc9-9779-da7c4527c5b2" > active-stage echo "dbe0bef8-c72c-4cc9-9779-da7c4527c5b2" > active-stage
``` ```
`active.conf` needs to have the correct active stage too, add it again `active.conf` needs to have the correct active stage too, add it again
like this. Note: This is deep down in the code, use with care! like this. Note: This is deep down in the code, use with care!
``` ```bash
sed -i 's/ActiveStages\["_api"\] = .*/ActiveStages\["_api"\] = "dbe0bef8-c72c-4cc9-9779-da7c4527c5b2"/g' /var/lib/icinga2/api/packages/_api/active.conf sed -i 's/ActiveStages\["_api"\] = .*/ActiveStages\["_api"\] = "dbe0bef8-c72c-4cc9-9779-da7c4527c5b2"/g' /var/lib/icinga2/api/packages/_api/active.conf
``` ```
Restart Icinga 2. Restart Icinga 2.
``` ```bash
systemctl restart icinga2 systemctl restart icinga2
``` ```
@ -1034,8 +1035,8 @@ Print the CA and client certificate and ensure that the following attributes are
Navigate into the local certificate store: Navigate into the local certificate store:
``` ```bash
$ cd /var/lib/icinga2/certs/ cd /var/lib/icinga2/certs/
``` ```
Make sure to verify the agents' certificate and its stored `ca.crt` in `/var/lib/icinga2/certs` and ensure that Make sure to verify the agents' certificate and its stored `ca.crt` in `/var/lib/icinga2/certs` and ensure that
@ -1274,13 +1275,13 @@ SSL-Session:
You can specifically use one cipher or a list with the `-cipher` parameter: You can specifically use one cipher or a list with the `-cipher` parameter:
``` ```bash
openssl s_client -connect 192.168.33.5:5665 -cipher 'ECDHE-RSA-AES256-GCM-SHA384' openssl s_client -connect 192.168.33.5:5665 -cipher 'ECDHE-RSA-AES256-GCM-SHA384'
``` ```
In order to fully simulate a connecting client, provide the certificates too: In order to fully simulate a connecting client, provide the certificates too:
``` ```bash
CERTPATH='/var/lib/icinga2/certs' CERTPATH='/var/lib/icinga2/certs'
HOSTNAME='icinga2.vagrant.demo.icinga.com' HOSTNAME='icinga2.vagrant.demo.icinga.com'
openssl s_client -connect 192.168.33.5:5665 -cert "${CERTPATH}/${HOSTNAME}.crt" -key "${CERTPATH}/${HOSTNAME}.key" -CAfile "${CERTPATH}/ca.crt" -cipher 'ECDHE-RSA-AES256-GCM-SHA384' openssl s_client -connect 192.168.33.5:5665 -cert "${CERTPATH}/${HOSTNAME}.crt" -key "${CERTPATH}/${HOSTNAME}.key" -CAfile "${CERTPATH}/ca.crt" -cipher 'ECDHE-RSA-AES256-GCM-SHA384'
@ -1301,8 +1302,8 @@ the child node actively connectsm, you can still simulate a TLS handshake.
Use `openssl s_server` instead of `openssl s_client` on the master during the connection Use `openssl s_server` instead of `openssl s_client` on the master during the connection
attempt. attempt.
``` ```bash
$ openssl s_server -connect 192.168.56.101:5665 openssl s_server -connect 192.168.56.101:5665
``` ```
Since the server role chooses the preferred cipher suite in Icinga, Since the server role chooses the preferred cipher suite in Icinga,
@ -1385,12 +1386,12 @@ General connection errors could be one of the following problems:
Use tools like `netstat`, `tcpdump`, `nmap`, etc. to make sure that the cluster communication Use tools like `netstat`, `tcpdump`, `nmap`, etc. to make sure that the cluster communication
works (default port is `5665`). works (default port is `5665`).
``` ```bash
# tcpdump -n port 5665 -i any tcpdump -n port 5665 -i any
# netstat -tulpen | grep icinga netstat -tulpen | grep icinga
# nmap icinga2-agent1.localdomain nmap icinga2-agent1.localdomain
``` ```
### Cluster Troubleshooting TLS Errors <a id="troubleshooting-cluster-tls-errors"></a> ### Cluster Troubleshooting TLS Errors <a id="troubleshooting-cluster-tls-errors"></a>
@ -1473,8 +1474,8 @@ Additional tasks:
Fetch all check result events matching the `event.service` name `remote-client`: Fetch all check result events matching the `event.service` name `remote-client`:
``` ```bash
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=debugcommandendpoint&types=CheckResult&filter=match%28%22remote-client*%22,event.service%29' curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=debugcommandendpoint&types=CheckResult&filter=match%28%22remote-client*%22,event.service%29'
``` ```
@ -1508,19 +1509,19 @@ object Zone "master" {
Then create a new directory in `zones.d` called `master`, if not existing. Then create a new directory in `zones.d` called `master`, if not existing.
``` ```bash
mkdir -p /etc/icinga2/zones.d/master mkdir -p /etc/icinga2/zones.d/master
``` ```
Now move the directory tree from `conf.d` into the `master` zone. Now move the directory tree from `conf.d` into the `master` zone.
``` ```bash
mv conf.d/* /etc/icinga2/zones.d/master/ mv conf.d/* /etc/icinga2/zones.d/master/
``` ```
Validate the configuration and reload Icinga. Validate the configuration and reload Icinga.
``` ```bash
icinga2 daemon -C icinga2 daemon -C
systemctl restart icinga2 systemctl restart icinga2
``` ```

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

@ -51,7 +51,7 @@ config files for the zone(s). **If your config master is 2.11.x already, you are
In order to fix this, upgrade to at least 2.11.1, and purge away the local config sync storage once, then restart. In order to fix this, upgrade to at least 2.11.1, and purge away the local config sync storage once, then restart.
``` ```bash
yum install icinga2 yum install icinga2
rm -rf /var/lib/icinga2/api/zones/* rm -rf /var/lib/icinga2/api/zones/*
@ -872,10 +872,10 @@ $ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql` There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
which must be applied incrementally to your IDO database. which must be applied incrementally to your IDO database.
``` ```bash
# mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.5.0.sql mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.5.0.sql
# mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.6.0.sql mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.6.0.sql
# mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.8.0.sql mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.8.0.sql
``` ```
## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a> ## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a>
@ -908,9 +908,9 @@ $ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql` There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
which must be applied incrementally to your IDO database. which must be applied incrementally to your IDO database.
``` ```bash
# export PGPASSWORD=icinga export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.5.0.sql psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.5.0.sql
# psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.6.0.sql psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.6.0.sql
# psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.8.0.sql psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.8.0.sql
``` ```

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

@ -422,7 +422,7 @@ is a list with multiple indexes with the keys for scheduling info and the object
Each check command execution logs the start and end time where Each check command execution logs the start and end time where
Icinga 2 (and the end user) is able to calculate the plugin execution time from it. Icinga 2 (and the end user) is able to calculate the plugin execution time from it.
``` ```cpp
GetExecutionEnd() - GetExecutionStart() GetExecutionEnd() - GetExecutionStart()
``` ```
@ -438,7 +438,7 @@ and computed from inside the check result.
The difference between the two deltas is called `check latency`. The difference between the two deltas is called `check latency`.
``` ```cpp
(GetScheduleEnd() - GetScheduleStart()) - CalculateExecutionTime() (GetScheduleEnd() - GetScheduleStart()) - CalculateExecutionTime()
``` ```
@ -454,7 +454,7 @@ The higher the severity number is, the more important the problem is.
Flags: Flags:
``` ```cpp
/** /**
* Severity Flags * Severity Flags
* *
@ -476,7 +476,7 @@ enum SeverityFlag
Host: Host:
``` ```cpp
/* OK/Warning = Up, Critical/Unknown = Down */ /* OK/Warning = Up, Critical/Unknown = Down */
if (!HasBeenChecked()) if (!HasBeenChecked())
severity |= SeverityFlagPending; severity |= SeverityFlagPending;
@ -496,7 +496,7 @@ Host:
Service: Service:
``` ```cpp
if (!HasBeenChecked()) if (!HasBeenChecked())
severity |= SeverityFlagPending; severity |= SeverityFlagPending;
else if (state == ServiceWarning) else if (state == ServiceWarning)
@ -702,7 +702,7 @@ This index is used to lookup the corresponding endpoint in the connected endpoin
including the local endpoint. Whether the local endpoint is equal to the selected endpoint, including the local endpoint. Whether the local endpoint is equal to the selected endpoint,
or not, this sets the authority to `true` or `false`. or not, this sets the authority to `true` or `false`.
``` ```cpp
authority = endpoints[Utility::SDBM(object->GetName()) % endpoints.size()] == my_endpoint; authority = endpoints[Utility::SDBM(object->GetName()) % endpoints.size()] == my_endpoint;
``` ```
@ -1106,7 +1106,7 @@ RelayMessageOne() takes care of the routing. This involves fetching the targetZo
With passing the `origin` the following condition prevents sending a message back to sender: With passing the `origin` the following condition prevents sending a message back to sender:
``` ```cpp
if (origin && origin->FromClient && targetEndpoint == origin->FromClient->GetEndpoint()) { if (origin && origin->FromClient && targetEndpoint == origin->FromClient->GetEndpoint()) {
``` ```

16
doc/20-script-debugger.md
View File

@ -3,8 +3,8 @@
You can run the Icinga 2 daemon with the `-X` (`--script-debugger`) You can run the Icinga 2 daemon with the `-X` (`--script-debugger`)
parameter to enable the script debugger: parameter to enable the script debugger:
``` ```bash
# icinga2 daemon -X icinga2 daemon -X
``` ```
When an exception occurs or the [debugger](17-language-reference.md#breakpoints) When an exception occurs or the [debugger](17-language-reference.md#breakpoints)
@ -13,8 +13,8 @@ allows the user to debug the script.
You can also attach the script debugger to the [configuration validation](11-cli-commands.md#config-validation): You can also attach the script debugger to the [configuration validation](11-cli-commands.md#config-validation):
``` ```bash
# icinga2 daemon -C -X icinga2 daemon -C -X
``` ```
Here is a list of common errors which can be diagnosed with the script debugger: Here is a list of common errors which can be diagnosed with the script debugger:
@ -135,8 +135,8 @@ The following example tries filter for all host objects where the custom variabl
`host.vars.os != ""`. Another idea is to use the [contains](18-library-reference.md#dictionary-contains) method on the custom `host.vars.os != ""`. Another idea is to use the [contains](18-library-reference.md#dictionary-contains) method on the custom
attribute dictionary like this: `host.vars.contains("os")`. attribute dictionary like this: `host.vars.contains("os")`.
``` ```bash
$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' \ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' \
-X POST 'https://localhost:5665/v1/objects/services' \ -X POST 'https://localhost:5665/v1/objects/services' \
-d '{ "filter": "host.vars.contains(\"os\")", "attrs": [ "__name" ], "joins": [ "host.name", "host.vars" ], "pretty": true }' -d '{ "filter": "host.vars.contains(\"os\")", "attrs": [ "__name" ], "joins": [ "host.name", "host.vars" ], "pretty": true }'
``` ```
@ -170,8 +170,8 @@ In order to stay safe, add more checks to the API filter:
Example: Example:
``` ```bash
$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' \ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' \
-X POST 'https://localhost:5665/v1/objects/services' \ -X POST 'https://localhost:5665/v1/objects/services' \
-d '{ "filter": "host.vars && typeof(host.vars) == Dictionary && host.vars.contains(\"os\")", "attrs": [ "__name" ], "joins": [ "host.name", "host.vars" ], "pretty": true }' -d '{ "filter": "host.vars && typeof(host.vars) == Dictionary && host.vars.contains(\"os\")", "attrs": [ "__name" ], "joins": [ "host.name", "host.vars" ], "pretty": true }'
``` ```

225
doc/21-development.md
View File

@ -88,7 +88,7 @@ process and can safely be ignored.
> Since v2.11 we would attach to the umbrella process spawned with `/usr/lib/icinga2/sbin/icinga2`, > Since v2.11 we would attach to the umbrella process spawned with `/usr/lib/icinga2/sbin/icinga2`,
> therefore rather attach to a running process. > therefore rather attach to a running process.
> >
``` ```bash
# Typically the order of PIDs is: 1) umbrella 2) spawn helper 3) main process # Typically the order of PIDs is: 1) umbrella 2) spawn helper 3) main process
pidof icinga2 pidof icinga2
@ -169,7 +169,7 @@ process and store it into a new file (e.g. for debugging dead locks).
Icinga 2 runs with 2 processes: main and command executor, therefore generate two backtrace logs Icinga 2 runs with 2 processes: main and command executor, therefore generate two backtrace logs
and add them to the GitHub issue. and add them to the GitHub issue.
``` ```bash
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 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
``` ```
@ -177,7 +177,7 @@ for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "thread apply all bt full
Instead of a full backtrace, you sometimes just need a list of running threads. Instead of a full backtrace, you sometimes just need a list of running threads.
``` ```bash
for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "info threads" -ex "detach" -ex "q" > gdb_threads_${pid}_`date +%s`.log; done for pid in $(pidof icinga2); do gdb -p $pid -batch -ex "info threads" -ex "detach" -ex "q" > gdb_threads_${pid}_`date +%s`.log; done
``` ```
@ -317,13 +317,13 @@ Max core file size unlimited unlimited bytes
The Icinga 2 daemon runs with the SUID bit set. Therefore you need The Icinga 2 daemon runs with the SUID bit set. Therefore you need
to explicitly enable core dumps for SUID on Linux. to explicitly enable core dumps for SUID on Linux.
``` ```bash
sysctl -w fs.suid_dumpable=2 sysctl -w fs.suid_dumpable=2
``` ```
Adjust the coredump kernel format and file location on Linux: Adjust the coredump kernel format and file location on Linux:
``` ```bash
sysctl -w kernel.core_pattern=/var/lib/cores/core.%e.%p sysctl -w kernel.core_pattern=/var/lib/cores/core.%e.%p
install -m 1777 -d /var/lib/cores install -m 1777 -d /var/lib/cores
@ -331,7 +331,7 @@ install -m 1777 -d /var/lib/cores
MacOS: MacOS:
``` ```bash
sysctl -w kern.corefile=/cores/core.%P sysctl -w kern.corefile=/cores/core.%P
chmod 777 /cores chmod 777 /cores
@ -365,15 +365,15 @@ gdb /usr/lib64/icinga2/sbin/icinga2 core.icinga2.<PID>
LLDB is available on macOS with the Xcode command line tools. LLDB is available on macOS with the Xcode command line tools.
``` ```bash
$ xcode-select --install xcode-select --install
``` ```
In order to run Icinga 2 with LLDB you need to pass the binary as argument. In order to run Icinga 2 with LLDB you need to pass the binary as argument.
Since v2.11 we would attach to the umbrella process, therefore rather Since v2.11 we would attach to the umbrella process, therefore rather
attach to a running process. attach to a running process.
``` ```bash
# Typically the order of PIDs is: 1) umbrella 2) spawn helper 3) main process # Typically the order of PIDs is: 1) umbrella 2) spawn helper 3) main process
pidof icinga2 pidof icinga2
@ -390,7 +390,7 @@ Closed FD 6 which we inherited from our parent process.
[2020-01-29 12:22:33 +0100] information/RunWorker: DEBUG: Current PID: 85253. Sleeping for 120 seconds to allow lldb/gdb -p <PID> attachment. [2020-01-29 12:22:33 +0100] information/RunWorker: DEBUG: Current PID: 85253. Sleeping for 120 seconds to allow lldb/gdb -p <PID> attachment.
``` ```
``` ```bash
lldb -p 85253 lldb -p 85253
``` ```
@ -544,7 +544,7 @@ on GitHub and mention that you're testing the snapshot packages.
In addition to that, the `icinga-rpm-release` package already provides the `icinga-snapshot-builds` In addition to that, the `icinga-rpm-release` package already provides the `icinga-snapshot-builds`
repository but it is disabled by default. repository but it is disabled by default.
``` ```bash
yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
yum -y install epel-release yum -y install epel-release
yum makecache yum makecache
@ -558,7 +558,7 @@ yum install --enablerepo=icinga-snapshot-builds icinga2
It is advised to configure both Icinga repositories, stable and snapshot and selectively It is advised to configure both Icinga repositories, stable and snapshot and selectively
choose the repository with the `-t` flag on `apt-get install`. choose the repository with the `-t` flag on `apt-get install`.
``` ```bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -581,7 +581,7 @@ apt-get update
On Debian Stretch, you'll also need to add Debian Backports. On Debian Stretch, you'll also need to add Debian Backports.
``` ```bash
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \ echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list /etc/apt/sources.list.d/${DIST}-backports.list
@ -591,14 +591,14 @@ apt-get update
Then install the snapshot packages. Then install the snapshot packages.
``` ```bash
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
apt-get install -t icinga-${DIST}-snapshots icinga2 apt-get install -t icinga-${DIST}-snapshots icinga2
``` ```
#### Ubuntu <a id="development-tests-snapshot-packages-ubuntu"></a> #### Ubuntu <a id="development-tests-snapshot-packages-ubuntu"></a>
``` ```bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -621,7 +621,7 @@ apt-get update
Then install the snapshot packages. Then install the snapshot packages.
``` ```bash
. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \ . /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 apt-get install -t icinga-${DIST}-snapshots icinga2
``` ```
@ -630,7 +630,7 @@ apt-get install -t icinga-${DIST}-snapshots icinga2
The required Boost packages are provided with the stable release repository. The required Boost packages are provided with the stable release repository.
``` ```bash
rpm --import https://packages.icinga.com/icinga.key rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
@ -642,7 +642,7 @@ zypper ref
Selectively install the snapshot packages using the `-r` parameter. Selectively install the snapshot packages using the `-r` parameter.
``` ```bash
zypper in -r icinga-snapshot-builds icinga2 zypper in -r icinga-snapshot-builds icinga2
``` ```
@ -652,14 +652,14 @@ zypper in -r icinga-snapshot-builds icinga2
Build the binaries and run the tests. Build the binaries and run the tests.
``` ```bash
make -j4 -C debug make -j4 -C debug
make test -C debug make test -C debug
``` ```
Run a specific boost test: Run a specific boost test:
``` ```bash
debug/Bin/Debug/boosttest-test-base --run_test=remote_url debug/Bin/Debug/boosttest-test-base --run_test=remote_url
``` ```
@ -848,9 +848,11 @@ current year as this implies yearly updates we don't want.
Depending on the file type, this must be a comment. Depending on the file type, this must be a comment.
``` ```cpp
/* Icinga 2 | (c) 2012 Icinga GmbH | GPLv2+ */ /* Icinga 2 | (c) 2012 Icinga GmbH | GPLv2+ */
```
```bash
# Icinga 2 | (c) 2012 Icinga GmbH | GPLv2+ # Icinga 2 | (c) 2012 Icinga GmbH | GPLv2+
``` ```
@ -863,7 +865,7 @@ We follow the clang format, with some exceptions.
- Curly braces for functions and classes always start at a new line. - Curly braces for functions and classes always start at a new line.
``` ```cpp
String ConfigObjectUtility::EscapeName(const String& name) String ConfigObjectUtility::EscapeName(const String& name)
{ {
//... //...
@ -878,7 +880,7 @@ String ConfigObjectUtility::CreateObjectConfig(const Type::Ptr& type, const Stri
- Too long lines break at a parameter, the new line needs a tab indent. - Too long lines break at a parameter, the new line needs a tab indent.
``` ```cpp
static String CreateObjectConfig(const Type::Ptr& type, const String& fullName, static String CreateObjectConfig(const Type::Ptr& type, const String& fullName,
bool ignoreOnError, const Array::Ptr& templates, const Dictionary::Ptr& attrs); bool ignoreOnError, const Array::Ptr& templates, const Dictionary::Ptr& attrs);
``` ```
@ -886,7 +888,7 @@ String ConfigObjectUtility::CreateObjectConfig(const Type::Ptr& type, const Stri
- Conditions require curly braces if it is not a single if with just one line. - Conditions require curly braces if it is not a single if with just one line.
``` ```cpp
if (s == "OK") { if (s == "OK") {
//... //...
} else { } else {
@ -917,7 +919,7 @@ use that information as a summary and link over to it on purpose.
- Single line comments may use `//` or `/* ... */` - Single line comments may use `//` or `/* ... */`
- Multi line comments must use this format: - Multi line comments must use this format:
``` ```cpp
/* Ensure to check for XY /* Ensure to check for XY
* This relies on the fact that ABC has been set before. * This relies on the fact that ABC has been set before.
*/ */
@ -937,7 +939,7 @@ The `return` value should describe the value type and additional details.
Example: Example:
``` ```cpp
/** /**
* Reads a message from the connected peer. * Reads a message from the connected peer.
* *
@ -983,7 +985,7 @@ Always use an empty line after the header include parts.
The icinga namespace is used globally, as otherwise we would need to write `icinga::Utility::FormatDateTime()`. The icinga namespace is used globally, as otherwise we would need to write `icinga::Utility::FormatDateTime()`.
``` ```cpp
using namespace icinga; using namespace icinga;
``` ```
@ -991,7 +993,7 @@ Other namespaces must be declared in the scope they are used. Typically
this is inside the function where `boost::asio` and variants would this is inside the function where `boost::asio` and variants would
complicate the code. complicate the code.
``` ```cpp
namespace ssl = boost::asio::ssl; namespace ssl = boost::asio::ssl;
auto context (std::make_shared<ssl::context>(ssl::context::sslv23)); auto context (std::make_shared<ssl::context>(ssl::context::sslv23));
@ -1003,7 +1005,7 @@ Ensure to pass values and pointers as const reference. By default, all
values will be copied into the function scope, and we want to avoid this values will be copied into the function scope, and we want to avoid this
wherever possible. wherever possible.
``` ```cpp
std::vector<EventQueue::Ptr> EventQueue::GetQueuesForType(const String& type) std::vector<EventQueue::Ptr> EventQueue::GetQueuesForType(const String& type)
``` ```
@ -1034,7 +1036,7 @@ optimizes this anyways.
Wrong: Wrong:
``` ```cpp
int res = s == "OK" ? 0 : s == "WARNING" ? 1; int res = s == "OK" ? 0 : s == "WARNING" ? 1;
return res; return res;
@ -1042,7 +1044,7 @@ Wrong:
Better: Better:
``` ```cpp
int res = 3; int res = 3;
if (s == "OK") { if (s == "OK") {
@ -1055,7 +1057,7 @@ Better:
Even better: Create a lookup map instead of if branches. The complexity Even better: Create a lookup map instead of if branches. The complexity
is reduced to O(log(n)). is reduced to O(log(n)).
``` ```cpp
std::map<String, unsigned int> stateMap = { std::map<String, unsigned int> stateMap = {
{ "OK", 1 }, { "OK", 1 },
{ "WARNING", 2 } { "WARNING", 2 }
@ -1083,7 +1085,7 @@ Icinga objects can be locked with the `ObjectLock` class.
Object locks and guards must be limited to the scope where they are needed. Otherwise we could create dead locks. Object locks and guards must be limited to the scope where they are needed. Otherwise we could create dead locks.
``` ```cpp
{ {
ObjectLock olock(frame.Locals); ObjectLock olock(frame.Locals);
for (const Dictionary::Pair& kv : frame.Locals) { for (const Dictionary::Pair& kv : frame.Locals) {
@ -1112,7 +1114,7 @@ which are made available in the DSL too.
- Always use `String` instead of `std::string`. If you need a C-string, use the `CStr()` method. - Always use `String` instead of `std::string`. If you need a C-string, use the `CStr()` method.
- Avoid casts and rather use the `Convert` class methods. - Avoid casts and rather use the `Convert` class methods.
``` ```cpp
double s = static_cast<double>(v); //Wrong double s = static_cast<double>(v); //Wrong
double s = Convert::ToDouble(v); //Correct, ToDouble also provides overloads with different value types double s = Convert::ToDouble(v); //Correct, ToDouble also provides overloads with different value types
@ -1243,7 +1245,7 @@ they are allowed:
Typedefs allow developers to use shorter names for specific types, Typedefs allow developers to use shorter names for specific types,
classes and structs. classes and structs.
``` ```cpp
typedef std::map<String, std::shared_ptr<NamespaceValue> >::iterator Iterator; typedef std::map<String, std::shared_ptr<NamespaceValue> >::iterator Iterator;
``` ```
@ -1258,7 +1260,7 @@ is required.
The following example iterates over a map returned from `GetTypes()`. The following example iterates over a map returned from `GetTypes()`.
``` ```cpp
for (const auto& kv : GetTypes()) { for (const auto& kv : GetTypes()) {
result.insert(kv.second); result.insert(kv.second);
} }
@ -1267,7 +1269,7 @@ The following example iterates over a map returned from `GetTypes()`.
The long example would require us to define a map iterator, and a slightly The long example would require us to define a map iterator, and a slightly
different algorithm. different algorithm.
``` ```cpp
typedef std::map<String, DbType::Ptr> TypeMap; typedef std::map<String, DbType::Ptr> TypeMap;
typedef std::map<String, DbType::Ptr>::const_iterator TypeMapIterator; typedef std::map<String, DbType::Ptr>::const_iterator TypeMapIterator;
@ -1281,7 +1283,7 @@ different algorithm.
We could also use a pair here, but requiring to know We could also use a pair here, but requiring to know
the specific types of the map keys and values. the specific types of the map keys and values.
``` ```cpp
typedef std::pair<String, DbType::Ptr> kv_pair; typedef std::pair<String, DbType::Ptr> kv_pair;
for (const kv_pair& kv : GetTypes()) { for (const kv_pair& kv : GetTypes()) {
@ -1347,7 +1349,7 @@ Create two build directories for different binary builds.
* `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. * `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.
* `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. * `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.
``` ```bash
mkdir -p release debug mkdir -p release debug
``` ```
@ -1361,7 +1363,7 @@ are best effort and sometimes out-of-date. Git Master may contain updates.
#### CentOS 7 <a id="development-linux-dev-env-centos"></a> #### CentOS 7 <a id="development-linux-dev-env-centos"></a>
``` ```bash
yum -y install gdb vim git bash-completion htop yum -y install gdb vim git bash-completion htop
yum -y install rpmdevtools ccache \ yum -y install rpmdevtools ccache \
@ -1388,19 +1390,19 @@ build inside the `release` directory.
First, off export some generics for Boost. First, off export some generics for Boost.
``` ```bash
export I2_BOOST="-DBoost_NO_BOOST_CMAKE=TRUE -DBoost_NO_SYSTEM_PATHS=TRUE -DBOOST_LIBRARYDIR=/usr/lib64/boost169 -DBOOST_INCLUDEDIR=/usr/include/boost169 -DBoost_ADDITIONAL_VERSIONS='1.69;1.69.0'" export I2_BOOST="-DBoost_NO_BOOST_CMAKE=TRUE -DBoost_NO_SYSTEM_PATHS=TRUE -DBOOST_LIBRARYDIR=/usr/lib64/boost169 -DBOOST_INCLUDEDIR=/usr/include/boost169 -DBoost_ADDITIONAL_VERSIONS='1.69;1.69.0'"
``` ```
Second, add the prefix path to it. Second, add the prefix path to it.
``` ```bash
export I2_GENERIC="$I2_BOOST -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2" export I2_GENERIC="$I2_BOOST -DCMAKE_INSTALL_PREFIX=/usr/local/icinga2"
``` ```
Third, define the two build types with their specific CMake variables. Third, define the two build types with their specific CMake variables.
``` ```bash
export I2_DEBUG="-DCMAKE_BUILD_TYPE=Debug -DICINGA2_UNITY_BUILD=OFF $I2_GENERIC" 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" export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DICINGA2_UNITY_BUILD=ON $I2_GENERIC"
``` ```
@ -1408,7 +1410,7 @@ export I2_RELEASE="-DCMAKE_BUILD_TYPE=RelWithDebInfo -DICINGA2_WITH_TESTS=ON -DI
Fourth, depending on your likings, you may add a bash alias for building, Fourth, depending on your likings, you may add a bash alias for building,
or invoke the commands inside: or invoke the commands inside:
``` ```bash
alias i2_debug="cd /root/icinga2; mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j2; sudo make -j2 install; cd .." alias i2_debug="cd /root/icinga2; mkdir -p debug; cd debug; cmake $I2_DEBUG ..; make -j2; sudo make -j2 install; cd .."
alias i2_release="cd /root/icinga2; mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j2; sudo make -j2 install; cd .." alias i2_release="cd /root/icinga2; mkdir -p release; cd release; cmake $I2_RELEASE ..; make -j2; sudo make -j2 install; cd .."
``` ```
@ -1419,7 +1421,7 @@ This is taken from the [centos7-dev](https://github.com/Icinga/icinga-vagrant/tr
The source installation doesn't set proper permissions, this is The source installation doesn't set proper permissions, this is
handled in the package builds which are officially supported. handled in the package builds which are officially supported.
``` ```bash
chown -R icinga:icinga /usr/local/icinga2/var/ chown -R icinga:icinga /usr/local/icinga2/var/
/usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
@ -1435,8 +1437,8 @@ Debian Buster doesn't need updated Boost packages from packages.icinga.com,
the distribution already provides 1.66+. For older versions such as Stretch, the distribution already provides 1.66+. For older versions such as Stretch,
include the release repository for packages.icinga.com as shown in the [setup instructions](02-installation.md#package-repositories-debian-ubuntu-raspbian). include the release repository for packages.icinga.com as shown in the [setup instructions](02-installation.md#package-repositories-debian-ubuntu-raspbian).
``` ```bash
$ docker run -ti debian:buster bash docker run -ti debian:buster bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -1445,7 +1447,7 @@ apt-get -y install gdb vim git cmake make ccache build-essential libssl-dev biso
apt-get -y install libboost-all-dev apt-get -y install libboost-all-dev
``` ```
``` ```bash
ln -s /usr/bin/ccache /usr/local/bin/gcc ln -s /usr/bin/ccache /usr/local/bin/gcc
ln -s /usr/bin/ccache /usr/local/bin/g++ ln -s /usr/bin/ccache /usr/local/bin/g++
@ -1472,7 +1474,7 @@ make -j2 install -C debug
The source installation doesn't set proper permissions, this is The source installation doesn't set proper permissions, this is
handled in the package builds which are officially supported. handled in the package builds which are officially supported.
``` ```bash
chown -R icinga:icinga /usr/local/icinga2/var/ chown -R icinga:icinga /usr/local/icinga2/var/
/usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
@ -1487,8 +1489,8 @@ vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf
Requires Boost packages from packages.icinga.com. Requires Boost packages from packages.icinga.com.
``` ```bash
$ docker run -ti ubuntu:bionic bash docker run -ti ubuntu:bionic bash
apt-get update apt-get update
apt-get -y install apt-transport-https wget gnupg apt-get -y install apt-transport-https wget gnupg
@ -1504,7 +1506,7 @@ wget -O - https://packages.icinga.com/icinga.key | apt-key add -
apt-get update apt-get update
``` ```
``` ```bash
apt-get -y install gdb vim git cmake make ccache build-essential libssl-dev bison flex default-libmysqlclient-dev libpq-dev libedit-dev monitoring-plugins apt-get -y install gdb vim git cmake make ccache build-essential libssl-dev bison flex default-libmysqlclient-dev libpq-dev libedit-dev monitoring-plugins
apt-get install -y libboost1.67-icinga-all-dev apt-get install -y libboost1.67-icinga-all-dev
@ -1529,14 +1531,14 @@ cmake .. $I2_DEBUG
cd .. cd ..
``` ```
``` ```bash
make -j2 install -C debug make -j2 install -C debug
``` ```
The source installation doesn't set proper permissions, this is The source installation doesn't set proper permissions, this is
handled in the package builds which are officially supported. handled in the package builds which are officially supported.
``` ```bash
chown -R icinga:icinga /usr/local/icinga2/var/ chown -R icinga:icinga /usr/local/icinga2/var/
/usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2 /usr/local/icinga2/lib/icinga2/prepare-dirs /usr/local/icinga2/etc/sysconfig/icinga2
@ -1569,13 +1571,13 @@ This requires at least v2.11.
Explicitly use OpenSSL 1.1.x, older versions are out of support. Explicitly use OpenSSL 1.1.x, older versions are out of support.
``` ```bash
brew install ccache boost cmake bison flex openssl@1.1 mysql-connector-c++ postgresql libpq brew install ccache boost cmake bison flex openssl@1.1 mysql-connector-c++ postgresql libpq
``` ```
##### ccache ##### ccache
``` ```bash
sudo mkdir /opt/ccache sudo mkdir /opt/ccache
sudo ln -s `which ccache` /opt/ccache/clang sudo ln -s `which ccache` /opt/ccache/clang
@ -1596,7 +1598,7 @@ typically run slower than release builds and must not be used for performance be
The preferred installation prefix is `/usr/local/icinga/icinga2`. This allows to put e.g. Icinga Web 2 into the `/usr/local/icinga` directory as well. The preferred installation prefix is `/usr/local/icinga/icinga2`. This allows to put e.g. Icinga Web 2 into the `/usr/local/icinga` directory as well.
``` ```bash
mkdir -p release debug mkdir -p release debug
export I2_USER=$(id -u -n) export I2_USER=$(id -u -n)
@ -1616,7 +1618,7 @@ make -j4 install -C debug
In order to run Icinga without any path prefix, and also use Bash completion it is advised to source additional In order to run Icinga without any path prefix, and also use Bash completion it is advised to source additional
things into the local dev environment. things into the local dev environment.
``` ```bash
export PATH=/usr/local/icinga/icinga2/sbin/:$PATH 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 test -f /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2 && source /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2
@ -1626,7 +1628,7 @@ test -f /usr/local/icinga/icinga2/etc/bash_completion.d/icinga2 && source /usr/l
This is derived from [dnsmichi's flavour](https://github.com/dnsmichi/dotfiles) and not generally best practice. This is derived from [dnsmichi's flavour](https://github.com/dnsmichi/dotfiles) and not generally best practice.
``` ```bash
vim $HOME/.bash_profile vim $HOME/.bash_profile
export I2_USER=$(id -u -n) export I2_USER=$(id -u -n)
@ -1650,7 +1652,7 @@ source $HOME/.bash_profile
`make install` doesn't set all required permissions, override this. `make install` doesn't set all required permissions, override this.
``` ```bash
chown -R $I2_USER:$I2_GROUP /usr/local/icinga/icinga2 chown -R $I2_USER:$I2_GROUP /usr/local/icinga/icinga2
``` ```
@ -1658,7 +1660,7 @@ chown -R $I2_USER:$I2_GROUP /usr/local/icinga/icinga2
Start Icinga in foreground. Start Icinga in foreground.
``` ```bash
icinga2 daemon icinga2 daemon
``` ```
@ -1666,23 +1668,26 @@ Reloads triggered with HUP or cluster syncs just put the process into background
#### Plugins #### Plugins
``` ```bash
brew install monitoring-plugins brew install monitoring-plugins
sudo vim /usr/local/icinga/icinga2/etc/icinga2/constants.conf sudo vim /usr/local/icinga/icinga2/etc/icinga2/constants.conf
```
```
const PluginDir = "/usr/local/sbin" const PluginDir = "/usr/local/sbin"
``` ```
#### Backends: Redis #### Backends: Redis
``` ```bash
brew install redis brew install redis
brew services start redis brew services start redis
``` ```
#### Databases: MariaDB #### Databases: MariaDB
``` ```bash
brew install mariadb brew install mariadb
mkdir -p /usr/local/etc/my.cnf.d mkdir -p /usr/local/etc/my.cnf.d
brew services start mariadb brew services start mariadb
@ -1702,7 +1707,7 @@ ln -s /Users/michi/.my.cnf $HOME/.my.cnf
exit exit
``` ```
``` ```bash
mysql -e 'create database icinga;' mysql -e 'create database icinga;'
mysql -e "grant all on icinga.* to 'icinga'@'localhost' identified by '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 mysql icinga < $HOME/dev/icinga/icinga2/lib/db_ido_mysql/schema/mysql.sql
@ -1710,7 +1715,7 @@ mysql icinga < $HOME/dev/icinga/icinga2/lib/db_ido_mysql/schema/mysql.sql
#### API #### API
``` ```bash
icinga2 api setup icinga2 api setup
cd /usr/local/icinga/icinga2/var/lib/icinga2/certs cd /usr/local/icinga/icinga2/var/lib/icinga2/certs
HOST_NAME=mbpmif.int.netways.de HOST_NAME=mbpmif.int.netways.de
@ -2131,7 +2136,7 @@ The following examples source from armhf on Raspberry Pi.
#### ccache #### ccache
``` ```bash
apt install -y ccache apt install -y ccache
/usr/sbin/update-ccache-symlinks /usr/sbin/update-ccache-symlinks
@ -2145,13 +2150,14 @@ source ~/.bashrc && echo $PATH
Copy the icinga2 source code into `$HOME/icinga2`. Clone the `deb-icinga2` repository into `debian/`. Copy the icinga2 source code into `$HOME/icinga2`. Clone the `deb-icinga2` repository into `debian/`.
``` ```bash
git clone https://github.com/Icinga/icinga2 $HOME/icinga2 git clone https://github.com/Icinga/icinga2 $HOME/icinga2
git clone https://github.com/Icinga/deb-icinga2 $HOME/icinga2/debian git clone https://github.com/Icinga/deb-icinga2 $HOME/icinga2/debian
``` ```
Then build a Debian package and install it like normal. Then build a Debian package and install it like normal.
```
```bash
dpkg-buildpackage -uc -us dpkg-buildpackage -uc -us
``` ```
@ -2219,26 +2225,26 @@ external command pipe and livestatus features require a dedicated command group
`icingacmd`. You can choose your own user/group names and pass them to CMake `icingacmd`. You can choose your own user/group names and pass them to CMake
using the `ICINGA2_USER`, `ICINGA2_GROUP` and `ICINGA2_COMMAND_GROUP` variables. using the `ICINGA2_USER`, `ICINGA2_GROUP` and `ICINGA2_COMMAND_GROUP` variables.
``` ```bash
# groupadd icinga groupadd icinga
# groupadd icingacmd groupadd icingacmd
# useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
``` ```
On Alpine (which uses ash busybox) you can run: On Alpine (which uses ash busybox) you can run:
``` ```bash
# addgroup -S icinga addgroup -S icinga
# addgroup -S icingacmd addgroup -S icingacmd
# adduser -S -D -H -h /var/spool/icinga2 -s /sbin/nologin -G icinga -g icinga icinga adduser -S -D -H -h /var/spool/icinga2 -s /sbin/nologin -G icinga -g icinga icinga
# adduser icinga icingacmd adduser icinga icingacmd
``` ```
Add the web server user to the icingacmd group in order to grant it write Add the web server user to the icingacmd group in order to grant it write
permissions to the external command pipe and livestatus socket: permissions to the external command pipe and livestatus socket:
``` ```bash
# usermod -a -G icingacmd www-data usermod -a -G icingacmd www-data
``` ```
Make sure to replace "www-data" with the name of the user your web server Make sure to replace "www-data" with the name of the user your web server
@ -2249,18 +2255,18 @@ is running as.
Once you have installed all the necessary build requirements you can build Once you have installed all the necessary build requirements you can build
Icinga 2 using the following commands: Icinga 2 using the following commands:
``` ```bash
$ mkdir release && cd release mkdir release && cd release
$ cmake .. cmake ..
$ cd .. cd ..
$ make -C release make -C release
$ make install -C release make install -C release
``` ```
You can specify an alternative installation prefix using `-DCMAKE_INSTALL_PREFIX`: You can specify an alternative installation prefix using `-DCMAKE_INSTALL_PREFIX`:
``` ```bash
$ cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2 cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2
``` ```
### CMake Variables <a id="development-package-builds-cmake-variables"></a> ### CMake Variables <a id="development-package-builds-cmake-variables"></a>
@ -2351,7 +2357,7 @@ can be used to disable the usage of `git describe`.
Setup your build environment: Setup your build environment:
``` ```bash
yum -y install rpmdevtools yum -y install rpmdevtools
``` ```
@ -2359,7 +2365,7 @@ yum -y install rpmdevtools
SLES: SLES:
``` ```bash
zypper addrepo http://download.opensuse.org/repositories/devel:tools/SLE_12_SP4/devel:tools.repo zypper addrepo http://download.opensuse.org/repositories/devel:tools/SLE_12_SP4/devel:tools.repo
zypper refresh zypper refresh
zypper install rpmdevtools spectool zypper install rpmdevtools spectool
@ -2367,7 +2373,7 @@ zypper install rpmdevtools spectool
OpenSuSE: OpenSuSE:
``` ```bash
zypper addrepo http://download.opensuse.org/repositories/devel:tools/openSUSE_Leap_15.0/devel:tools.repo zypper addrepo http://download.opensuse.org/repositories/devel:tools/openSUSE_Leap_15.0/devel:tools.repo
zypper refresh zypper refresh
zypper install rpmdevtools spectool zypper install rpmdevtools spectool
@ -2377,14 +2383,14 @@ zypper install rpmdevtools spectool
Prepare the rpmbuild directory tree: Prepare the rpmbuild directory tree:
``` ```bash
cd $HOME cd $HOME
rpmdev-setuptree rpmdev-setuptree
``` ```
Snapshot builds: Snapshot builds:
``` ```bash
curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o $HOME/rpmbuild/SPECS/icinga2.spec curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o $HOME/rpmbuild/SPECS/icinga2.spec
``` ```
@ -2396,7 +2402,7 @@ curl https://raw.githubusercontent.com/Icinga/rpm-icinga2/master/icinga2.spec -o
Copy the tarball to `rpmbuild/SOURCES` e.g. by using the `spectool` binary Copy the tarball to `rpmbuild/SOURCES` e.g. by using the `spectool` binary
provided with `rpmdevtools`: provided with `rpmdevtools`:
``` ```bash
cd $HOME/rpmbuild/SOURCES cd $HOME/rpmbuild/SOURCES
spectool -g ../SPECS/icinga2.spec spectool -g ../SPECS/icinga2.spec
@ -2405,7 +2411,7 @@ cd $HOME/rpmbuild
Install the build dependencies. Example for CentOS 7: Install the build dependencies. Example for CentOS 7:
``` ```bash
yum -y install libedit-devel ncurses-devel gcc-c++ libstdc++-devel openssl-devel \ yum -y install libedit-devel ncurses-devel gcc-c++ libstdc++-devel openssl-devel \
cmake flex bison boost-devel systemd mysql-devel postgresql-devel httpd \ cmake flex bison boost-devel systemd mysql-devel postgresql-devel httpd \
selinux-policy-devel checkpolicy selinux-policy selinux-policy-doc selinux-policy-devel checkpolicy selinux-policy selinux-policy-doc
@ -2415,13 +2421,13 @@ Note: If you are using Amazon Linux, systemd is not required.
A shorter way is available using the `yum-builddep` command on RHEL based systems: A shorter way is available using the `yum-builddep` command on RHEL based systems:
``` ```bash
yum-builddep SPECS/icinga2.spec yum-builddep SPECS/icinga2.spec
``` ```
Build the RPM: Build the RPM:
``` ```bash
rpmbuild -ba SPECS/icinga2.spec rpmbuild -ba SPECS/icinga2.spec
``` ```
@ -2441,7 +2447,7 @@ The RedHat Developer Toolset is required for building Icinga 2 beforehand.
This contains a modern version of flex and a C++ compiler which supports This contains a modern version of flex and a C++ compiler which supports
C++11 features. C++11 features.
``` ```bash
cat >/etc/yum.repos.d/devtools-2.repo <<REPO cat >/etc/yum.repos.d/devtools-2.repo <<REPO
[testing-devtools-2-centos-\$releasever] [testing-devtools-2-centos-\$releasever]
name=testing 2 devtools for CentOS $releasever name=testing 2 devtools for CentOS $releasever
@ -2455,7 +2461,8 @@ should be used for building.
As an alternative, you can use newer Boost packages provided on As an alternative, you can use newer Boost packages provided on
[packages.icinga.com](https://packages.icinga.com/epel). [packages.icinga.com](https://packages.icinga.com/epel).
```
```bash
cat >$HOME/.rpmmacros <<MACROS cat >$HOME/.rpmmacros <<MACROS
%build_icinga_org 1 %build_icinga_org 1
MACROS MACROS
@ -2472,7 +2479,7 @@ Setup your build environment on Debian/Ubuntu, copy the 'debian' directory from
the Debian packaging Git repository (https://github.com/Icinga/deb-icinga2) the Debian packaging Git repository (https://github.com/Icinga/deb-icinga2)
into your source tree and run the following command: into your source tree and run the following command:
``` ```bash
dpkg-buildpackage -uc -us dpkg-buildpackage -uc -us
``` ```
@ -2543,7 +2550,7 @@ Note: the openrc's init.d is not shipped by default.
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. 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.
Those few steps can be followed: Those few steps can be followed:
``` ```bash
wget https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd wget https://git.alpinelinux.org/cgit/aports/plain/community/icinga2/icinga2.initd
mv icinga2.initd /etc/init.d/icinga2 mv icinga2.initd /etc/init.d/icinga2
chmod +x /etc/init.d/icinga2 chmod +x /etc/init.d/icinga2
@ -2618,8 +2625,8 @@ file for details.
Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required, Install the `boost`, `python` and `icinga2` pretty printers. Absolute paths are required,
so please make sure to update the installation paths accordingly (`pwd`). so please make sure to update the installation paths accordingly (`pwd`).
``` ```bash
$ mkdir -p ~/.gdb_printers && cd ~/.gdb_printers mkdir -p ~/.gdb_printers && cd ~/.gdb_printers
``` ```
Boost Pretty Printers compatible with Python 3: Boost Pretty Printers compatible with Python 3:
@ -2633,16 +2640,16 @@ $ pwd
Python Pretty Printers: Python Pretty Printers:
``` ```bash
$ cd ~/.gdb_printers cd ~/.gdb_printers
$ svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
``` ```
Icinga 2 Pretty Printers: Icinga 2 Pretty Printers:
``` ```bash
$ mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2 mkdir -p ~/.gdb_printers/icinga2 && cd ~/.gdb_printers/icinga2
$ wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py wget https://raw.githubusercontent.com/Icinga/icinga2/master/tools/debug/gdb/icingadbg.py
``` ```
Now you'll need to modify/setup your `~/.gdbinit` configuration file. Now you'll need to modify/setup your `~/.gdbinit` configuration file.

56
doc/22-selinux.md
View File

@ -37,8 +37,8 @@ You can change the configured mode by editing `/etc/selinux/config` and the curr
Simply add the `icinga2-selinux` package to your installation. Simply add the `icinga2-selinux` package to your installation.
``` ```bash
# yum install icinga2-selinux yum install icinga2-selinux
``` ```
Ensure that the `icinga2` process is running in its own `icinga2_t` domain after installing the policy package: Ensure that the `icinga2` process is running in its own `icinga2_t` domain after installing the policy package:
@ -55,23 +55,23 @@ This section describes the installation to support development and testing. It a
As a prerequisite install the `git`, `selinux-policy-devel` and `audit` packages. Enable and start the audit daemon afterwards: As a prerequisite install the `git`, `selinux-policy-devel` and `audit` packages. Enable and start the audit daemon afterwards:
``` ```bash
# yum install git selinux-policy-devel audit yum install git selinux-policy-devel audit
# systemctl enable auditd.service systemctl enable auditd.service
# systemctl start auditd.service systemctl start auditd.service
``` ```
After that clone the icinga2 git repository: After that clone the icinga2 git repository:
``` ```bash
# git clone https://github.com/icinga/icinga2 git clone https://github.com/icinga/icinga2
``` ```
To create and install the policy package run the installation script which also labels the resources. (The script assumes Icinga 2 was started once after system startup, the labeling of the port will only happen once and fail later on.) To create and install the policy package run the installation script which also labels the resources. (The script assumes Icinga 2 was started once after system startup, the labeling of the port will only happen once and fail later on.)
``` ```bash
# cd tools/selinux/ cd tools/selinux/
# ./icinga.sh ./icinga.sh
``` ```
After that restart Icinga 2 and verify it running in its own domain `icinga2_t`. After that restart Icinga 2 and verify it running in its own domain `icinga2_t`.
@ -144,13 +144,13 @@ Make sure to report the bugs in the policy afterwards.
Download and install a plugin, for example check_mysql_health. Download and install a plugin, for example check_mysql_health.
``` ```bash
# wget https://labs.consol.de/download/shinken-nagios-plugins/check_mysql_health-2.1.9.2.tar.gz wget https://labs.consol.de/download/shinken-nagios-plugins/check_mysql_health-2.1.9.2.tar.gz
# tar xvzf check_mysql_health-2.1.9.2.tar.gz tar xvzf check_mysql_health-2.1.9.2.tar.gz
# cd check_mysql_health-2.1.9.2/ cd check_mysql_health-2.1.9.2/
# ./configure --libexecdir /usr/lib64/nagios/plugins ./configure --libexecdir /usr/lib64/nagios/plugins
# make make
# make install make install
``` ```
It is labeled `nagios_unconfined_plugins_exec_t` by default, so it runs without restrictions. It is labeled `nagios_unconfined_plugins_exec_t` by default, so it runs without restrictions.
@ -195,9 +195,9 @@ object GraphiteWriter "graphite" {
Before you restart the icinga2 service allow it to connect to all ports by enabling the boolean `icinga2_can_connect_all` (now and permanent). Before you restart the icinga2 service allow it to connect to all ports by enabling the boolean `icinga2_can_connect_all` (now and permanent).
``` ```bash
# setsebool icinga2_can_connect_all true setsebool icinga2_can_connect_all true
# setsebool -P icinga2_can_connect_all true setsebool -P icinga2_can_connect_all true
``` ```
If you restart the daemon now it will successfully connect to graphite. If you restart the daemon now it will successfully connect to graphite.
@ -233,15 +233,15 @@ this user. This is completly optional!
Start by adding the Icinga 2 administrator role `icinga2adm_r` to the administrative SELinux user `staff_u`. Start by adding the Icinga 2 administrator role `icinga2adm_r` to the administrative SELinux user `staff_u`.
``` ```bash
# semanage user -m -R "staff_r sysadm_r system_r unconfined_r icinga2adm_r" staff_u semanage user -m -R "staff_r sysadm_r system_r unconfined_r icinga2adm_r" staff_u
``` ```
Confine your user login and create a sudo rule. Confine your user login and create a sudo rule.
``` ```bash
# semanage login -a dirk -s staff_u semanage login -a dirk -s staff_u
# echo "dirk ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/dirk echo "dirk ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/dirk
``` ```
Login to the system using ssh and verify your id. Login to the system using ssh and verify your id.
@ -278,8 +278,8 @@ $ sudo -r icinga2adm_r -t icinga2adm_t systemctl reload icinga2.service
Now the commands will work, but you have always to remember to add the arguments, so change the sudo rule to set it by default. Now the commands will work, but you have always to remember to add the arguments, so change the sudo rule to set it by default.
``` ```bash
# echo "dirk ALL=(ALL) ROLE=icinga2adm_r TYPE=icinga2adm_t NOPASSWD: ALL" > /etc/sudoers.d/dirk echo "dirk ALL=(ALL) ROLE=icinga2adm_r TYPE=icinga2adm_t NOPASSWD: ALL" > /etc/sudoers.d/dirk
``` ```
Now try the commands again without providing the role and type and they will work, but if you try to read apache logs or restart apache for example it will still fail. Now try the commands again without providing the role and type and they will work, but if you try to read apache logs or restart apache for example it will still fail.