LConf for icinga-web - Documentation¶
1. Table of content¶
- LConf for icinga-web - Documentation
- Updating to a newer version
- Chapter 3. Creating Connections
- Chapter 4. The LDAP Editor - a quick overview
- Chapter 5. The LDAP Tree
- Chapter 6. Editing properties
- Chapter 7. Searching the tree
- Chapter 8. Creating and managing filters
- Chapter 9. Search&Replace
- Chapter 10. Integration to icinga-web
- Chapter 11. Support
- Additional features
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.
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
- A running LDAP Server (for example OpenLDAP), best being configured with LConf
- Icinga-web 1.5+
- The Netways LConf tool (see www.netways.org/projects/lconf)
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
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)
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
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 -u %icinga_user% -p icinga_web (or your icinga db) < update_v.%X%_v.%Y%
pgsq -U %icinga_user% -f update_v.%X%_v.%Y%
sqlplus %icinga_user%@icinga_web @update_v.%X%_v.%Y%
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.
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
- 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
- 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.
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
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
- 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
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).
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.:
- 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
*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
- 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
- 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¶
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.
If the properties are invalid, the editor won't notice until the ldap server will inform you.
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
The search/replace function is located at the tree root.
The search/replace mask looks like this:
- 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.
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,
cd CronkIntegration ./install.sh
And follow the instructions.
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
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).