Caution this is not a stable release, do not use on productive systems

Introduction

Thruk is a multibackend monitoring webinterface which currently supports Nagios and Icinga as backend using the MKLivestatus addon. It was designed to be a "dropin" replacement. The target is to cover 100% of the original features plus additional enhancements for large installations.

Main Features / Advantages

Installation

The clean and proper way to install Thruk is to create a new local user and install the missing perl modules with local::lib.

Use Package

Installation from a package should be easy and seemless:

  %> wget http://
  %> tar zxf Thruk-0.30-i386.tar.gz
  %> cd Thruk-0.30
  %> ./script/thruk_server.pl

For a FastCGI installation follow the steps from the source installation.

Quick Installation Guide for Debian

1.  install debian netinst
      - minimal inst, create user thruk
2.  add "contrib non-free" to /etc/apt/sources.list
3.  #> apt-get install libapache2-mod-fastcgi libfile-copy-recursive-perl libmodule-install-perl \
          make gcc git git-core libgd2-xpm-dev
4.  #> su - thruk
5.  %> cd /tmp
6.  %> wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.tar.gz
7.  %> tar zxvf local-lib-1.004009.tar.gz
8.  %> cd local-lib-1.004009
9.  %> perl Makefile.PL --bootstrap
10. %> make install
11. %> echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
12. %> . ~/.bashrc
13. %> cd && git clone http://github.com/sni/Thruk.git
14. %> cd Thruk
15. %> perl Makefile.PL && make
16. %> cp thuk.conf thruk_local.conf && vi thruk_local.conf
17. %> vi cgi.cfg
18. %> ./script/thruk_server.pl

Install from Source

Requirements

In order to install the Thruk Monitoring Webinterface from source for Nagios/Icinga you will need the following:

Create New User

refer to your systems manual on howto add new user. This guide uses the following:

  user:  thruk
  group: thruk
Important all following steps should be done by the thruk user.

Install Local::Lib

Follow the steps on http://search.cpan.org/perldoc?local::lib#The_bootstrapping_technique

quick guide:

  %> su - thruk
  %> wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.tar.gz
  %> tar zxf local-lib-1.004009.tar.gz
  %> cd local-lib-1.004009
  %> perl Makefile.PL --bootstrap && make install
Tip
proxy configuration

if you need a proxy configuration, you should answer <no> at this question:

Would you like me to configure as much as possible automatically? [yes]

Setting a proper http_proxy/ftp_proxy environment should work for the automatic configuration.

Add the following line to the thruk users .profile or .bashrc

eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)

logout and login again and verify that your perl env looks like this:

 %> env | grep perl
 PERL5LIB=/home/thruk/perl5/lib/perl5:/home/thruk/perl5/lib/perl5/x86_64-linux-gnu-thread-multi
 MODULEBUILDRC=/home/thruk/perl5/.modulebuildrc
 PATH=/home/thruk/perl5/bin:/usr/local/bin:/usr/bin:/bin:/usr/games
 PERL_MM_OPT=INSTALL_BASE=/home/thruk/perl5

Install Module::Install

  perl -MCPAN -e "install Module::Install::Catalyst"

Git Clone Thruk

    git clone http://github.com/sni/Thruk.git
    cd Thruk
    perl Makefile.PL

press <enter> here:

  ==> Auto-install the 35 mandatory module(s) from CPAN? [y]

then run make

    make

This may take a while, as there are probably several modules missing.

Press <y> at this questions:

  Do you want to build the XS Stash module? [y]
  Do you want to use the XS Stash by default? [y]

run perl Makefile.PL again to see if all dependecies are now installed properly.

    perl Makefile.PL

Install Livestatus

Refer to http://mathias-kettner.de/checkmk_livestatus.html#H1:%20Setting%20up%20and%20using%20Livestatus on how to install livestatus onto your monitoring box.

Basically you have to build the NDO addon and add it to your nagios/icinga.cfg.

 broker_module=/opt/local/livestatus/livestatus.o /tmp/live.sock

Configuration

Copy "thruk.conf" to "thruk_local.conf" and adjust the livestatus settings to your needs.

Edit "cgi.conf" and adjust settings to your needs.

See the [Configuration] section for detailed explaination of configuration options.

Start Server

After running these steps successfully, you should be able to test your installation:

    ./script/thruk_server.pl

Open your browser and open http://<your_host>:3000

Configure FastCGI Server

start your fcgi server:

    %>./script/thruk_fastcgi.pl -n 5 \
                -l /tmp/thruk_fastcgi.socket \
                -p /tmp/thruk_fastcgi.pid

you may want to copy the init.d script to /etc/init.d and adjust its paths:

    %> sudo cp ./script/thruk_fastcgi_server.sh /etc/init.d/thruk_fastcgi_server
    %> vi /etc/init.d/thruk_fastcgi_server
    %> sudo chown root: /etc/init.d/thruk_fastcgi_server

Or create a custom init.d script (additional modules required) with:

    %> ./script/thruk_create.pl FastCGI::ExternalServer l=/tmp/thruk_fastcgi.socket n=5 p=/tmp/thruk_fastcgi.pid

Apache Configuration

use this apache example configuration:

Example: Apache configuration within existing vhost
<VirtualHost *:80>
    # ... existing configuration

    # thruk configuration
    <Directory /home/thruk/Thruk/root/>
        order allow,deny
        allow from all
    </Directory>

    Alias /thruk/ /home/thruk/Thruk/root/thruk/
    <Location "/thruk">
        AuthName "Monitoring Access"
        AuthType Basic
        AuthUserFile /home/thruk/Thruk/htpasswd.users
        Order Allow,Deny
        Allow from all
        require valid-user
    </Location>

    # Load fastcgi module unless already loaded
    LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so

    # fastcgi configuration
    FastCGIExternalServer /tmp/thruk_fastcgi.fcgi -socket /tmp/thruk_fastcgi.socket -idle-timeout 120

    # Load rewrite module unless already loaded
    LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

    # rewrite configuration
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^/thruk(.*)$ /tmp/thruk_fastcgi.fcgi/thruk$1 [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]

</VirtualHost>
Example: Apache configuration with own vhost
<VirtualHost *:80>
    ServerName   thruk.your-host.local

    DocumentRoot /home/thruk/Thruk/root/
    CustomLog    /home/thruk/Thruk/logs/access.log combined
    ErrorLog     /home/thruk/Thruk/logs/error.log

    <Directory />
        order deny,allow
        deny from all
    </Directory>

    <Directory /home/thruk/Thruk/root/>
        order allow,deny
        allow from all
    </Directory>

    # authorization
    <Location "/">
        AuthName "Monitoring Access"
        AuthType Basic
        AuthUserFile /home/thruk/Thruk/htpasswd.users
        Order Allow,Deny
        Allow from all
        require valid-user
    </Location>

    # Load fastcgi module unless already loaded
    LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so

    # fastcgi configuration
    FastCGIExternalServer /tmp/thruk_fastcgi.fcgi -socket /tmp/thruk_fastcgi.socket -idle-timeout 120

    # Load rewrite module unless already loaded
    LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

    # rewrite configuration
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^/(.*)$ /tmp/thruk_fastcgi.fcgi/$1 [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]
</VirtualHost>

Configuration

Configuration is managed mainly in two configuration files.

thruk_local.conf

The thruk_local.conf is a copy of the thruk.conf. Both files are used by thruk. The idea is, that the thruk.conf is provided with the packaged defaults and the thruk_local.conf is to override these settings where needed.

documentation_link

This link is used in the side navigation menu as link to the documentation. Replace it with whatever your documentation is located. Set it to a blank value if you don't want a documentation link in the menu at all.

ex.:

documentation_link = /thruk/docs/

cgi_cfg

The path to your cgi.cfg. See [cgi.cfg] for details.

ex.:

cgi_cfg = cgi.cfg

use_frames

Set whether you want to use a framed navigation or not. With using frames it's sometimes easier to include addons.

ex.:

use_frames = 0

default_theme

Default theme to use for all users. Must be a valid subdirectory in the themes folder.

ex.:

default_theme = Classic

use_pager

Using the pager will make huge pages much faster as most people don't want a services page with 100.000 services displayed. Can be disabled if you don't need it.

ex.:

use_pager = 1

default_page_size

Set the default value for paging. Only used when paging is enabled. Should be a value of the paging_steps.

ex.:

default_page_size = 100

paging_steps

Define the single selectable values for paging sizes.

ex.:

paging_steps        = 100
paging_steps        = 500
paging_steps        = 1000
paging_steps        = 5000
paging_steps        = all

can_submit_commands

Set here if a contact should be allowed to send commands unless defined for the contact itself. This is the default value for all contacts unless the user has a can_submit_commands setting in your monitoring configuration.

ex.:

can_submit_commands = 1

command_disabled

Use this to disabled specific commands. Can be use multiple times to disabled multiple commands. Use the number from the cmd_typ cgi parameter.

ex.:

command_disabled = 14
command_disabled = 35

datetime_format

Default timeformat. Use POSIX format.

ex.:

datetime_format = %Y-%m-%d  %H:%M:%S

datetime_format_long

Default long timeformat.

ex.:

datetime_format_long = %a %b %e %H:%M:%S %Z %Y

datetime_format_log

Default log timeformat.

ex.:

datetime_format_log = %B %d, %Y  %H

datetime_format_trends

Default trends timeformat.

ex.:

datetime_format_trends = %a %b %e %H:%M:%S %Y

Component Monitoring::Livestatus

Enter your livestatus connection settings here. The port is the port from the xinetd.conf. You can enter local unix sockets too.

ex.:

<Component Monitoring::Livestatus>
  keepalive   = 1
  use_threads = 0
  <peer>
    name = Local Nagios
    peer = /tmp/livestatus.socket
  </peer>
  <peer>
    name = External Nagios
    peer = 172.16.0.1:9999
  </peer>
  <peer>
    name = External Icinga
    peer = 172.16.0.2:9999
  </peer>
</Component>

Component Catalyst::Log::Log4perl

Basically a normal log4perl configuration. You can configure whatever is possible in log4perl. Refer to the log4perl manual for detailed information.

ex.:

<Component Catalyst::Log::Log4perl>
  conf = log4perl.logger=ALL, ErrorLog, DebugLog
  conf = log4perl.appender.ErrorLog=Log::Dispatch::File
  conf = log4perl.appender.ErrorLog.filename=logs/error.log
  conf = log4perl.appender.ErrorLog.mode=append
  conf = log4perl.appender.ErrorLog.Threshold=ERROR
  conf = log4perl.appender.ErrorLog.layout=Log::Log4perl::Layout::PatternLayout
  conf = log4perl.appender.ErrorLog.layout.ConversionPattern=[%d][%H][%p][%c] %m%n
</Component>

cgi.cfg

The cgi.cfg is mainly the same as in Nagios or Icinga itself stripped down some unneeded values.

show_context_help

Displays an icon with context specific help on most pages.

ex.:

show_context_help = 1

use_authentication

Determines whether to use authentication or not. If enabled, Thruk will use the REMOTE_USER from the apache environment as authenticated user name. So the authentication has to be done by the webserver. Authorization is done by Thruk.

ex.:

use_authentication = 1

use_ssl_authentication

If enabled, the authenticated username is taken from the SSL_CLIENT_S_DN_CN environment instead of the remote user.

ex.:

use_ssl_authentication = 1

default_user_name

The default user will be used if no username has been provided by the webserver. You don't have to set a default user.

ex.:

default_user_name = thrukadmin

authorized_for_system_information

List of usernames who have access to the system and process information pages. You may use wildcards here.

ex.:

authorized_for_system_information = thrukadmin

authorized_for_configuration_information

List of usernames who have access to the configuration information pages. You may use wildcards here.

ex.:

authorized_for_configuration_information = thrukadmin

authorized_for_system_commands

List of usernames who are allowed to send system commands. You may use wildcards here.

ex.:

authorized_for_system_commands = thrukadmin

authorized_for_all_services

List of usernames who are authorized to view all services. You may use wildcards here.

ex.:

authorized_for_all_services = thrukadmin

authorized_for_all_hosts

List of usernames who are authorized to view all hosts. You may use wildcards here.

ex.:

authorized_for_all_hosts = thrukadmin

authorized_for_all_service_commands

List of usernames who are authorized to send commands for all services. You may use wildcards here.

ex.:

authorized_for_all_service_commands = thrukadmin

authorized_for_all_host_commands

List of usernames who are authorized to send commands for all hosts. You may use wildcards here.

ex.:

authorized_for_all_host_commands = thrukadmin

refresh_rate

Number of seconds after which most pages are refreshed automatically.

ex.:

refresh_rate = 90

escape_html_tags

Determines whether html output from plugins is escaped or not.

ex.:

escape_html_tags = 1

action_url_target

Sets the target of the action url links.

ex.:

action_url_target = _blank

notes_url_target

Sets the target of the notes url links.

ex.:

notes_url_target = _blank

lock_author_names

If enabled, user are not allowed to change the author name for commands.

ex.:

lock_author_names = 1