Installing Icinga 2
===================
-Please note that the current version of Icinga 2 isn't much more than a tech
-demo. Expect some rough edges when installing and running Icinga 2.
+The recommended way of installing Icinga 2 is to use packages. The Icinga
+project provides both release and development packages for a number
+of operating systems.
-For the "finished" version we're planning to release packages for the most
-common Linux distributions as well as for Windows - or at least co-operate
-with the package maintainers.
+Please check the documentation in the doc/ directory for a current list
+of available packages and detailed installation instructions.
+
+There are a number of known caveats when installing from source such as
+incorrect directory and file permissions. So even if you're planning to
+not use the official packages it is advisable to build your own Debian
+or RPM packages.
Build Requirements
------------------
The following requirements need to be fulfilled in order to build the
-application using a dist tarball (package names in parenthesis):
+application using a dist tarball (package names for RHEL and Debian in
+parentheses):
-* GNU make (make on RHEL and Debian)
+* cmake
+* GNU make (make)
* C++ compiler (gcc-c++ on RHEL, build-essential on Debian)
* OpenSSL library and header files (openssl-devel on RHEL, libssl-dev
on Debian)
* Boost library and header files (boost-devel on RHEL, libboost-all-dev
on Debian)
-* optional: Doxygen (doxygen on RHEL and Debian)
+* GNU bison (bison)
+* GNU flex (flex) >= 2.5.35
+* recommended: libexecinfo on FreeBSD
+* optional: MySQL (mysql-devel on RHEL, libmysqlclient-dev on Debian)
+* optional: Python (python-devel on RHEL, python-dev on Debian)
+
+Note: RHEL5 ships an ancient flex version. Updated packages are available for
+example from the repoforge buildtools repository.
+
+http://mirror.hs-esslingen.de/repoforge/redhat/el5/en/{i386,x86_64}/buildtools/
+
+User Requirements
+-----------------
+
+By default Icinga will run as user 'icinga' and group 'icinga'. Additionally the
+external command pipe and livestatus features require a dedicated command group
+'icingacmd'. You can choose your own user/group names and pass them to the
+configure script using the --with-icinga-user, --with-icinga-group,
+--with-icingacmd-user and --with-icingacmd-group options.
+
+# groupadd icinga
+# groupadd icingacmd
+# useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga icinga
+
+Add the web server user to the icingacmd group in order to grant it write
+permissions to the external command pipe and livestatus socket:
+
+# usermod -a -G icingacmd www-data
+
+Make sure to replace "www-data" with the name of the user your web server
+is running as.
-Packaging Requirements
-----------------------
+Building Release Tarballs
+-------------------------
-In order to build a dist tarball for the application the following external
-software components need to be installed in addition to the build requirements
-mentioned above:
+In order to build a release tarball you should first check out the Git repository
+in a new directory. If you're using an existing check-out you should make sure
+that there are no local modifications:
-* GNU Automake (automake on RHEL and Debian)
-* GNU Autoconf (autoconf on RHEL and Debian)
-* GNU Libtool (libtool and libtool-ltdl-devel on RHEL, libtool and
- libltdl-dev on Debian)
-* GNU bison (bison on RHEL and Debian)
-* GNU flex (flex on RHEL and Debian)
+$ git status
-Debian Packages
----------------
+Here's a short check-list for releases:
-This program comes with its own Debian packaging scripts which may or may not
-fully comply with the official Debian packaging requirements. These scripts can
-be found in the 'debian' sub-directory. Binary packages can be built using
-'dpkg-buildpackage'.
+* Update the .mailmap and AUTHORS files
+ $ git log --use-mailmap | grep ^Author: | cut -f2- -d' ' | sort | uniq > AUTHORS
+* Bump the version in icinga2.spec.
+* Update the ChangeLog and doc/1-about.md files.
+* Commit these changes to the "next" branch and create a signed tag (tags/v<VERSION>).
+ $ git commit -v -a -m "Release version <VERSION>."
+ $ git tag -u EE8E0720 -m "Version <VERSION>" v<VERSION>
+ $ git push --tags
+* Merge the "next" branch into the "master" branch (using --ff-only).
+ $ git checkout master
+ $ git merge --ff-only next
+ $ git push origin master
+* Bump the version to "v<NEXT-VERSION>-dev" and commit this change to the "next" branch.
+
+Note: CMake determines the Icinga 2 version number using "git describe" if the
+source directory is contained in a Git repository. Otherwise the version number
+is extracted from the icinga2.spec file. This behavior can be overridden by
+creating a file called "icinga-version.h.force" in the source directory.
+Alternatively the -DICINGA2_GIT_VERSION_INFO=ON option for CMake can be used to
+disable the usage of "git describe".
+
+Use "git archive" to build the release tarball:
+
+$ git archive --format=tgz --prefix=icinga2-<VERSION>/ tags/v<VERSION>
+
+Finally you should verify that the tarball only contains the files it should contain:
+
+$ tar ztf icinga2-<VERSION>.tar.gz | less
Building Icinga 2
-----------------
Once you have installed all the necessary build requirements you can build
Icinga 2 using the following commands:
-$ ./configure
+$ mkdir build && cd build
+$ cmake ..
$ make
$ make install
-The configure script supports all the usual parameters one comes to expect
-from autoconf. In particular you may want to use --prefix to specify an
-alternative installation prefix.
+You can specify an alternative installation prefix using -DCMAKE_INSTALL_PREFIX:
-Note: The Git repository does not contain any auto-generated Autotools files,
-i.e. there is no 'configure' script. In this case you will need to regenerate
-the 'configure' script by running 'autogen.sh'. However, as an end-user you
-should reconsider whether you really want to use the code from the Git
-repository. In general it is advisable to use one of the dist tarballs instead.
+$ cmake .. -DCMAKE_INSTALL_PREFIX=/tmp/icinga2
+
+In addition to CMAKE_INSTALL_PREFIX the following Icinga-specific cmake
+variables are supported:
+
+- ICINGA2_USER: The user Icinga 2 should run as; defaults to "icinga"
+- ICINGA2_GROUP: The group Icinga 2 should run as; defaults to "icinga"
+- ICINGA2_COMMAND_USER: The command user Icinga 2 should use; defaults to "icinga"
+- ICINGA2_GIT_VERSION_INFO: Whether to use Git to determine the version number; defaults to "ON"
+- ICINGA2_COMMAND_GROUP: The command group Icinga 2 should use; default to "icingacmd"
+- CMAKE_INSTALL_SYSCONFDIR: The configuration directory; defaults to CMAKE_INSTALL_PREFIX/etc
+- CMAKE_INSTALL_LOCALSTATEDIR: The state directory; defaults to CMAKE_INSTALL_PREFIX/var
Running Icinga 2
----------------
Icinga 2 comes with a single binary that takes care of loading all the relevant
components (e.g. for check execution, notifications, etc.):
-$ /tmp/i2/bin/icinga
-[2012/09/14 10:36:12] information/icinga: Icinga application loader (version:
- 2.0, git branch master, commit 8e4bdf38 + changes)
-[2012/09/14 10:36:12] information/base: Syntax: ./bin/icinga -c <config-file> ...
+# /usr/bin/icinga2
+[2013-10-22 13:06:22 +0200] <Main Thread> information/icinga-app: Icinga application loader (version: 0.0.3, git branch master, commit 07d9a59f + changes)
+[2013-10-22 13:06:22 +0200] <Main Thread> information/base: Adding library search dir: /usr/lib/icinga2
+[2013-10-22 13:06:22 +0200] <Main Thread> information/base: Loading library 'libicinga.la'
+[2013-10-22 13:06:22 +0200] <Main Thread> information/config: Adding include search dir: /usr/share/icinga2
+[2013-10-22 13:06:22 +0200] <Main Thread> critical/icinga-app: You need to specify at least one config file (using the --config option).
+
+Icinga 2 can be started as daemon using the provided init script:
+
+# /etc/init.d/icinga2
+Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
Icinga 2 reads a single configuration file which is used to specify all
configuration settings (global settings, hosts, services, etc.). The
-configuration format is explained in detail in the docs/icinga2-config.txt
-file.
+configuration format is explained in detail in the doc/ directory.
-By default "make install" installs example configuration files to /etc/icinga2
-unless you have specified a different prefix or sysconfdir.
+By default "make install" installs example configuration files in
+/usr/local/etc/icinga2 unless you have specified a different prefix or
+sysconfdir.
projects / icinga2 / blobdiff