LConf for icinga-web - Documentation

1. Table of content

2. Introduction

LConf for icinga-web is a powerful web-based ldap configuration application. Mainly, it's been designed for use with the Netways LConf export tool, which allows you to easily manage your Icinga/Nagios® configuration in an LDAP tree.

The key features are

  • A modern, easy-to-use web-interface that allows you to easily create, modify or delete ldap-nodes or attributes
  • Copy, move nodes and create aliases via drag&drop
  • Optional integration to the general Host/Service view of icinga-web
  • LDAP Alias toolkit (Show me aliases pointing to this node, Jump to the node aliased by this node, etc)
  • A simple to use element search if you just search occurences of a string, or
  • Support for multiple connections, allowing move/copy of nodes from one connection to another
  • Administrate connections and grant usage to users or groups
  • RegExp and searchFilter based Search/Replace for your elements
  • if you need a more complicated filter, a comprehensive filter template editor that allows you to create nested searches without nesting limitations.
  • Icons, creation wizards, ajax-proposals, attribute inheritance, etc. are fully customizable
  • Export your config via the LconfDeploy script from the LConf package, or your own script.

3. Installation

This chapter entails the installation and software requirements of the LConf module.

Requirements

The following Software is required for installing the lconf-module
  • Mysql, PostgreSQL, SQLite3 or higher
  • PHP 5.2+ including
  • php5-ldap
  • A running LDAP Server (for example OpenLDAP), best being configured with LConf
  • Icinga-web 1.5+
The following Software is not required for installing the lconf-module, but recommended for use:

Getting and installing LConf for icinga-web

The installation is carried out by phing, which is delivered with the module.

1. Download the LConf-module.
The module is available on http://www.netways.org [https://www.netways.org/projects/lconf-for-icinga/files]
or via git :

# git clone git://git.netways.org/lconf/icinga-module.git

2. (When using the tarball) Extract the downloaded archive.

# tar xvf lconf-icinga-mod.tgz

Dependencies

Installing the required packages from the distribution Debian Lenny (may differ depending on your distribution):

# aptitude install libapache2-mod-php5 \ 
    php5-ldap 

Your database dependencies should be fulfilled as you should already have icinga-web installed.

Installation of the module (since 1.3.2)

Since Version 1.3.2, Installation is performed using configure and make.

1. Call ./configure. See ./configure --help for installation options

# ./configure --with-icinga-web-path=/usr/local/icinga-web

2. Install the module by calling make install

# make install

3. When installing for the first time, type 'make install-db' to setup your database, otherwise look at the etc/sql/updates directory if there's an update for your current version available.

# make install-db
or
# cd etc/sql/updates

4. Add the credentials for the users who should be allowed to use the lconf module (Admin->Users->select user->Rights->Credentials)

5. Now you should see a "LConf" Entry in the main toolbar. If not, logout/login and try clearing the Icinga web cache (path may differ depending on where you've installed Icinga Web)

# /usr/local/icinga-web/bin/clearcache.sh

Installation of the module (pre 1.3.2)

The installation in former versions is performed by a phing-based installation wizard shipped with the module. Please note that you need write-access to <Path_to_icinga>.
As the installer will create additional tables in your database, you'll need to change the database settings by typing

vi <LConf_module_DIR>/db.ini

Change the settings to fit to your connection.

Notice: The database user must have rights to execute the CREATE TABLE order.

Now you can execute the installation by typing:

cd <LConf_module_DIR>. ./install.sh

When asked for the prefix, type in the prefix chosen by the lconf script. If you have an older lconf setup, use 'nagios' as prefix.

Setup icinga-web credentials

Now log in to your icinga-web frontend, you'll notice that you'll notice nothing.
This is because you haven't got any permissions to view the LConf module. To change this, login as an admin and add all the lconf.access credentials to your root user.
When you now log out and log in again you should see a new entry in the menu called "LConf".

Updating to a newer version

When updating, you should be able to just reinstall the LConf package without database-setup. You should take a look at the etc/sql/update folder if there is an update script available. Depending on your database backend:
  • mysql: mysql -u %icinga_user% -p icinga_web (or your icinga db) < update_v.%X%_v.%Y%
  • pgsql: pgsq -U %icinga_user% -f update_v.%X%_v.%Y%
  • oracle:
    
        sqlplus %icinga_user%@icinga_web 
        @update_v.%X%_v.%Y%
    
  • sqlite:
    
        sqlite3 %your_db_file%
        .read update_v.%X%_v.%Y%
    

Some of those commands can vary depending on your configuration.

Chapter 3. Creating Connections

Before you (or your colleagues) can start browsing through your lconf-tree, you must defina one or more connections. LConf for icinga offers both the admin and the normal user a connection manager, where you can create and manage your connections.

Managing connections

Admins generally see all connections and are able to grant or deny access to groups or users for each
connection. "Normal" users are only allowed to manage connections created by them self and are not able
to grant any access to other users.


Connection list overview

In the connection manager, you can

  • Create new connections
Located at the top toolbar of the connection list, this allows you to create a new connection.
  • Remove connections Located at the top toolbar of the connection list. With this button you can delete one or more selected connections.
  • Edit connections To edit a connection, perform a left-click on the connection and select the 'edit' item.
  • Manage access to connections Click on a connection and select 'Manage access' to grant or deny this connection for users/groups

Creating and editing connections

When you want to create or edit connections, you'll see the following mask:

  • Connection name (required) The name that should be shown for your connection.
  • Connection Description The description for the connection, if any.
  • Bind DN (required) The Bind DN with which to access the ldap server.
  • Bind Pass The password to use in order to identify at the server
  • Host (required) The host address of the ldap serverCreating Connections
  • Port (required) The port of the ldap server
  • RootDN The DN to use as your trees root, if any
  • Use TLS If checked, STARTTLS will be used to start the connection
  • Enable SSL If checked, ldaps:// will be used for the connection (check your port
    then)
  • Check Connection Check whether a connection can be established. You must enter the
    password in order to check the connection
  • Save Saves the changes

Grant usage for connections

When you have the lconf.admin credential, you are allowed to manage the access for users. This can be
done by dragging Users/Groups from the 'available' field to the 'selected' field.


Granting access

Chapter 4. The LDAP Editor - a quick overview

In this chapter you'll get a basic overview over the interface elements in the LConf LDAP editor.

The main interface

The main interface of the LDAP Editor consists of the following parts


The LDAP Main interface

  • The LDAP Tree (1) The LDAP Tree displays the structure of you ldap server in a handy
    tree view. In this tree you can create, delete, modify, move or clone
    entries via Drag&Drop, create aliases and perform search/replace
    operations.
    You can switch between the trees of different connections via the
    tabbar on top of the tree. It's even possible to drag nodes from
    one tree to another. Please note that all trees are affected by filters
    (which we will discuss later).
  • The connection overview (2) Here you see all connections you are granted for and connect to
    them via clicking on them and selecting "connect".
  • The property editor (3) This editor assists you by modifying ldap entries. It features ajaxdriven combofields for some entries.The LDAP Editor - a quick overvie

Please note that the editor does not check if your modification makes sense. But the LDAP server will and you'll get a error message with the appropriate ldap-error message your server returns.
If you want to customize the proposed items of the comobofield,

refer to chapter 10 - Pimpin' your LConf-config files

  • The quick search (4) Enter a search word here and LConf for icinga will search every
    entry containing this text snippet, showing it in a nice groupable
    view.
  • The filter editor (5) If you only want to see specific entries, you can create a filter for it
    here and save it. There should be some default filters shipped with
    your installation.

Chapter 5. The LDAP Tree

LConf for icinga displays the content of your ldap database in a tree view, like almost any other LDAP Tool does (perhaps because it makes sense).
We tried to achieve a very high grade of usability in this tree, and, as you will see in this chapter, therefore tried to make every action as simple as possible (but not simpler).

Modify nodes

If you want to edit the properties of a node, just click on it. It's properties will be loaded to the property manager. When you perform a right click on a node, you'll see the following context menu (note that 'delete all nodes' only is shown when more than one node is selected). Some of these options are not available when working on alias nodes.:


Node context-menu

  • Refresh this part of the tree
    Reloads the content of this node and its subnodes from the server
    and displays it.
  • Create new node on same level
    Creates a new node on the same level like this node.
  • Create new node as child
    Creates a new node below this node.
  • Remove only this node
    Removes this node and its subnodes. Aliases to these nodes will be
    deleted, too.
    *Remove all selected nodes
    Removes all selected nodes and their subnodes. Aliases to these nodes will be deleted, too. If only one node is selected, this won't be displayed.
  • Display aliases to this node
    Shows all aliases pointing to this node (if any).
  • Jump to alias target
    Only displayed if this node is an alias (or below one). Jumps to the node represented by this alias.
  • Resolve Alias (_only on aliases)
    Copies the alias content on this

The LDAP Tree

Moving and copying nodes

When you drag a node to another part of the tree, you can choose between one of these actions (note that when working with aliases or copying your node to other connections, some of these may not be available):


Node drag context-menu

  • Clone node here Copies the node to this location (if it already exists here, copy_of will
    be prepended)
  • Move node on same level Moves the node to this location. Aliases to this node (or its subnodes)
    will point to the new position of the node.
  • Clone node as subnode (Only if applied on leaf) Creates a copy of the dragged node below
    this node.
  • Move node as subnode (Only if applied on leaf) Moves the dragged node below this node.
  • Aliases to this node (or its subnodes) will point to the new position
    of the node.
  • Create alias here Create a aliasedObject node pointing to the dragged node here.

Chapter 6. Editing properties


Edit properties

When you select a node, it's properties will be loaded into the property editor. here you can modify, delete or add properties. Via the buttons at the button you can add properties or remove the selected. The changes will only be applied if you press the "Save Changes" button.
By clicking on a cell (except the dn cell, which can't be modified manually), you can edit the property. If a data provider is defined for the property type, you'll be assisted by a combobox delivering you proposals.

Note:
If the properties are invalid, the editor won't notice until the ldap server will inform you.

Note
Changing the objecttype is not possible, you'll have to create a new element with the same properties and delete this one manually.

Chapter 7. Searching the tree

There are two ways of finding entries in the tree: Perform searches or create filters. In this chapter the use of the search field, which can be used for simple text-occurence search, will be described. The search field is located at the bottom of the LDAP Tree.


The search field

After you've entered the text snippet you want to search, you'll see the result window, nicely grouping the found nodes in categories. If you click on an entry, you can directly jump to the position in the tree where this node is located.


The result view

If you wan't to change the group field, just click on the field header and select "Group By This Field".Searching the tree

Changing the grouping parameter.

Chapter 8. Creating and managing filters

Filters offer you a great possibility of making your ldap tree more clear
Filters can be rather easy, like 'Show me all hostgroups starting with "local"', but can also get complex, like 'Show me all hostgroups, hosts starting with 'local' or all services with checkcoomands starting with PING except services havin g 'dummy' in their name'

Filters can be easily created via Drag&Drop. Just click on the 'New' Button in the filterdialog and the filter
manager will appear.


Creating a filter that only displays hosts and hostgroups not havingf srv2 in the name.

Notice that you can use previous defined filters as parts of your new filter. You can build complex filters
out of smaller simple filters and keep the filter tree clear.
Click on a filter in the filterlist to activate it. Active filters are displayed with a green icon.Creating and managing filters


Activate a filter

At the top of the filterlist there is a bypass button, which allowes you to temporary disable all filters. Filter
modification or activation/deactivation is not possible when in bypass mode.

Chapter 9. Search&Replace

The last feature we'll describe here is the search&replace function. It's located at the context menu of the
root node


The search/replace function is located at the tree root.

The search/replace mask looks like this:


Search replace

  • Search RegExp A regular expression which should be replaced with the replace string.
    Backreferences can be achieved with \1.
  • Attributes to include The attributes to include in the search/replace process.
  • Replace String The String to replace the regexp with (grouped fields can be accessed
    with $1, $2,..,,$9).
  • Sissy Mode Shows which fields will be affected by the operation. It's better to be a sissy than messing up your tree.
  • Execute Execute the query.

Note
Filters will be respected when you use search/replace17

Chapter 10. Integration to icinga-web

host/service view (optional)

You have the possibility to execute the additional CronkIntegration script, which allows you to jump
directly from a host/service in the host/service view to it's appropriate ldap entry. In the module folder,
type


cd CronkIntegration
./install.sh

And follow the instructions.

Note
You need a CustomVariable entry named "DN" and containing the DN for each host that is in the tree

Chapter 11. Support

If you find any issues or have a feature request, feel free to open an issue at http://www.netways.org
[https://www.netways.org/projects/list_files/lconf-icinga-mod]

Additional features

Setup the export-config button

To export your config from the web interface (available in the current dev snapshot), you have to do three steps:

1.) Modify your access.xml and app/modules/LConf/config/access.xml, so the lconf_export entry points to the LConf Deploy script.

NOTE: Clear the web cache after modifying the configuration!!!

For example, on a standard installation, if your web user has to sudo to icinga in order to execute the command, your config would look like this:

...
                <execute>
                    <folders>

                    </folders>
                    <files>
                        <resource name="lconf_export">sudo -u icinga /usr/local/LConf/bin/LConfDeploy.sh</resource>
                    </files>
                </execute>

...

Use the seperate deploy script for Icinga 2.x export shipped with LConf >= 1.4.0

...
                <execute>
                    <folders>

                    </folders>
                    <files>
                        <resource name="lconf_export">sudo -u icinga /usr/local/LConf/bin/LConfDeployIcinga2.sh</resource>
                    </files>
                </execute>

...

In Versions <= LConf 1.3.0 it looks like

...
                <execute>
                    <folders>

                    </folders>
                    <files>
                        <resource name="lconf_export">sudo -u icinga /usr/local/LConf/lconf_deploy.sh</resource>
                    </files>
                </execute>

...

2.) Grant your www-user rights to create icinga-configs and deploy them or grant him the right to execute sudo as the icinga user (in this case use the command as above, otherwise you can leave the sudo out)

Example inspired by this blog entry. The example grants the www-user run permissions to the deploy script, therefore you'll only need 'sudo /usr/local/LConf/bin/LConfDeploy.sh' in the example above. But that merely depends on your security policies.

# visudo

## BEGIN: Lconf sudo
User_Alias      LCONF=apache,icinga
Defaults:LCONF !requiretty
# allow icinga to reload the icinga config
LCONF ALL=(icinga) NOPASSWD: /etc/init.d/icinga reload
# allow icinga to touch the diag file
LCONF ALL=(icinga) NOPASSWD: /bin/touch /var/icinga/icinga.chk
# allow icinga to test the config
LCONF ALL=(icinga) NOPASSWD: /usr/bin/icinga -v *
# allow apache to execute the deployment bash script
LCONF ALL=(apache) NOPASSWD: /usr/local/LConf/bin/LConfDeploy.sh
# allow icinga to execute the deployment perl script
LCONF ALL=(icinga) NOPASSWD: /usr/local/LConf/bin/LConfExport.pl -o /etc/icinga/lconf -v
## END: Lconf sudo

3.) Try to export - only modified satellites will be exported by default. If you want some satellites to be always updated, add them to the lconf_deploy.sh script

Test checkcommands from the webinterface

Note: This allows a user to execute commands on your machine. Although we made sure to escape parameters, backticks, you need explicit sudo rights for the allowed commands etc. there's no 100% guarantee a user can execute malicious commands. This is why there's a special credential lconf.testCheck and the check doesn't work without manual setup.

Since version 1.3 there's the possibility to execute check commands in order to test your setup without exporting. This can be found in the properties dialog of services if your user has the lconf.testcheck credential assigned:

In order to work, a few setup steps are required:
- Your web user needs password-less sudo access to your plugin path and - if you want user defined macros to be resolved automatically - the resource.cfg. Read the manual of your sudo implementation on how to accomplish this.
- In your access.xml, you need to allow icinga-web to:
-- read the resource.cfg
-- execute files in the plugin folder
-- execute /bin/cat

you can find these definition commented out in the [[source]], the easiest way is change the paths according to your setup and clear the cache. If you want to know more about the semantic of the access.xml, take a look at the [[icinga-web documentation]].

Now you should see a mask showing the command and allows you to enter definitions to the placeholders. If you have granted access to the resource.cfg, you needn't to fill out definitions found here (they will be substituted on the server side, in order to prevent passwords showing in the frontend).

LConf_Logo.jpg (31.4 KB) jmosshammer, 05/18/2011 11:23 AM

activate_filter.png (7.54 KB) jmosshammer, 05/18/2011 11:23 AM

admindd1.png (24.8 KB) jmosshammer, 05/18/2011 11:23 AM

connection_test.png (20.4 KB) jmosshammer, 05/18/2011 11:23 AM

activate_filter.png (7.54 KB) jmosshammer, 07/29/2011 10:14 PM

admindd1.png (24.8 KB) jmosshammer, 07/29/2011 10:14 PM

change_group.png (11.7 KB) jmosshammer, 07/29/2011 10:14 PM

connection_overview.png (20 KB) jmosshammer, 07/29/2011 10:14 PM

connection_test.png (20.4 KB) jmosshammer, 07/29/2011 10:14 PM

create_filter.png (29.3 KB) jmosshammer, 07/29/2011 10:15 PM

dd_inTree.png (76.4 KB) jmosshammer, 07/29/2011 10:15 PM

interface_overview.png (47.9 KB) jmosshammer, 07/29/2011 10:15 PM

LConf_Logo.jpg (31.4 KB) jmosshammer, 07/29/2011 10:15 PM

menu_icon.png (10.1 KB) jmosshammer, 07/29/2011 10:15 PM

s_replace.png (21.8 KB) jmosshammer, 07/29/2011 10:16 PM

search_field.png (8.12 KB) jmosshammer, 07/29/2011 10:16 PM

simpleSearch.png (67.9 KB) jmosshammer, 07/29/2011 10:16 PM

move_node.png (19.2 KB) jmosshammer, 07/29/2011 10:16 PM

new_connection.png (44.1 KB) jmosshammer, 07/29/2011 10:16 PM

nodeoptions.png (14.6 KB) jmosshammer, 07/29/2011 10:16 PM

propertyeditor.png (43 KB) jmosshammer, 07/29/2011 10:16 PM

s_replace_field.png (13.3 KB) jmosshammer, 07/29/2011 10:16 PM

connection_set.png (33.8 KB) cniemann, 08/15/2012 10:52 AM

connection_set.png (36.7 KB) cniemann, 08/15/2012 10:56 AM

checkcomment_test.png (279 KB) jmosshammer, 10/15/2012 04:32 PM

lconf_icinga_web_credentials_add.png (70.5 KB) mfriedrich, 07/27/2013 12:37 PM