Overview
This document describes how you can import hosts and users from OpenLDAP.
There are some steps you’ll need to follow in order to be able to import users :
- Enable the OpenLDAP source,
- Configure the OpenLDAP module,
- Configure the connection to OpenLDAP,
- Configure the mapping rules,
- Configure the import rules.
What is already available in the Shinken Installation
To make your life a bit easier, a few configuration tasks have already been done for you:
- Installation of the OpenLDAP import module,
- Availability of an example of pre configured OpenLDAP source ready to be customized.
Setup the pre-installed source
Installation and update script of Shinken will set up a default OpenLDAP source already configured:
- You can see it in the source table of the UI Configuration home page.
- This source uses 2 kinds of configuration files
- Source definition files
- Configuration files to customize the data mining.
- available in folder ( /etc/shinken-user/source-data/source-data-open-ldap-sample ).
- available in folder ( /etc/shinken-user/source-data/source-data-open-ldap-sample ).
The first time, we are advising you to only update Configuration files.
You will then decide if you want to have 1 or more active directory sources ( if you have a big directory, it might be interesting to have many sources pointing of specific entries for performance gain).
Source definitions:
Enable the openldap-import Source:
In the Automatic Detection Modules panel, clic on the button to enable the module. |  |
You can find the following parameters in the source file /etc/shinken/sources/openldap.cfg :
| Property | Example | Description |
|---|---|---|
| source_name | openldap-example | Name of this source. Must be unique. |
| order | 2 | Order in the merge algorithm of this source data. Look in the Synchronizer page for more information about it. |
| import_interval | 5 | Launch this source every import_inverval minutes. |
| modules | openldap-example | (module used by shinken to parse OpenLDAP data) |
| enabled | 0 | Activate or Disable the source. |
| description | This source is about loading hosts and contacts from OpenLDAP |
Configure the OpenLDAP Module
Modify if necessary, the file /etc/shinken/modules/openldap-import.cfg
| Property | Value | Description |
|---|---|---|
| module_name | openldap-example | Module's name. Must be unique. |
| module_type | ldap-import | Type of module. |
| connection_configuration_file | /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-connection.json | Connection information. |
| rules_configuration_file | /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-rules.json | Rules configuration. |
| mapping_configuration_file | /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-mapping.json | Mapping rules. |
Connection configuration
This file is used to make the connexion to your OpenLDAP server.
 | Edit the file /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-connection.json |
| Property | Default | Description |
|---|---|---|
| url | ldap://YOUR-DC-FQDN/ | URL of your Active Directory server. |
| base | dc=YOUR,dc=DOMAIN,dc=com | Base OU for your objects discovery. |
| hosts_base | OU=DataCenter Servers,dc=YOUR,dc=DOMAIN,dc=com | Base OU for the hosts discovery. |
| contacts_base | dc=YOUR,dc=DOMAIN,dc=com | Base OU for the contacts discovery. |
| username | SHINKEN@YOURDOMAIN.com | Username used to connect to the Ldap server. |
| password | PASSWORD | Password used by the user to connect to the Ldap server. |
Example
{
"url": "ldap://vm-w2k8r2.shinkendom.local/",
"base": "dc=shinkendom,dc=local",
"hosts_base": "OU=serveurs,dc=shinkendom,dc=local",
"hostgroups_base": "OU=serveurs,dc=shinkendom,dc=local",
"contacts_base": " OU=utilisateurs,DC=shinkendom,DC=local",
"username": "administrateur@shinkendom.local",
"password": "P@ssword1"
}
|
The account used to request LDAP only need read-only access. You should create a user account with read-only access dedicated to the OpenLDAP import module. |
Mapping rules configuration
This file allow you to do the mapping between OpenLDAP and Shinken properties.
Unless you know what you're doing here, you should keep this file unmodified.
You can find some customization in the How to section.
File /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-mapping.json
# IMPORTANT: Do not edit this file.
# To have your own mapping, copy it under the /etc/shinken-users directory and edit your copy instead.
# Note: comments should be with a # starting the line, NOT after a value
{
# first hosts propertyes (computer object in openldap)
"host.name": "name",
"host.dNSHostName": "dNSHostName",
"host.operatingSystem": "operatingSystem",
"host.operatingSystemServicePack":"operatingSystemServicePack",
"host.distinguishedName": "distinguishedName",
"host.filter": "(objectClass=computer)",
# Now contact properties
"contact.categoryFilter":"Person",
"contact.name": "uid",
"contact.telephoneNumber":"telephoneNumber",
"contact.mobile":"mobile",
"contact.member":"uniqueMember",
# Co: for country
"contact.co":"co",
# l: for city
"contact.l":"l",
"contact;company":"company",
"contact.filter":"(&(objectCategory=person)(objectClass=user))",
# By default hostgroup are not requested. Setup a filter to enabled it
"hostgroup.filter":""
}
|
Import rules configuration
This file is used to apply host template, contact template and tags to the hosts and contacts while the import.
| Edit the file /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-rules.json |
A host template called windows is already available in Shinken checking : Cpu, Disks, EventLogApplication, EventLogSystem, Memory, Network Interface, Reboot, Services, Swap. As a good start, you can configure the property hosts_tag in this way :
|
The mandatories properties to modify are in green.
| Property | Default | Description |
|---|---|---|
| hosts_tag | yourdomain | Shinken host template applied during the import |
| contacts_tag | generic-contact | Shinken contact template applied during the import |
| contacts_group_filter | CN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=com | CN=OTHERGROUPS,OU=Groups,OU=Users Groups,DC=YOUR,dc=DOMAIN,dc=com | User group to import |
| hosts_tag_citrix | OU=Terminal Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com | host tag citrix |
| hosts_tag_database | OU=Database Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com | host tag database |
| hosts_tag_exchange | OU=Email Collaboration Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com | host tag exchange |
| hosts_tag_fileprint | OU=Files Print Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com | host tag fileprint |
| hosts_match_operatingSystem_windows | windows | host tag windows |
| hosts_match_operatingSystem_windows2008 | windows*.*2008(?!.*.(?:r2)) | host tag windows2008 |
| hosts_match_operatingSystem_windows2008r2 | windows*.*2008*.*r2 | host tag windows 2008r2 |
| hosts_match_operatingSystem_windows2003 | windows*.*2003 | host tag windows2003 |
| hosts_match_operatingSystem_windows2012 | windows*.*2012(?!.*.(?:r2)) | host tag windows2012 |
| hosts_match_operatingSystem_windows2012r2 | windows*.*2012*.*r2 | host tag windows2012r2 |
| hosts_match_operatingSystem_windows2000 | windows*.*2000 | host tag windows 2000 |
| hosts_match_operatingSystem_windowsxp | windows*.*xp | host tag windows xp |
| hosts_match_operatingSystem_enterprise | Enterprise | host tag Enterprise |
| hosts_match_operatingSystemServicePack_sp1 | Service Pack 1 | host tag Service Pack 1 |
| hosts_match_operatingSystemServicePack_sp2 | Service Pack 2 | host tag Service Pack 2 |
| hosts_match_operatingSystemServicePack_sp3 | Service Pack 3 | host tag Service Pack 3 |
| contacts_match_memberOf_domain-admins | CN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=com | Contact tag domains-admins |
See below about the tag functionnality. |
Example :
{
"hosts_tag": "windows",
"contacts_tag": "generic-contact",
"contacts_group_filter": "CN=paris_shinken_users,OU=utilisateurs,DC=shinkendom,DC=local | CN=bordeaux_shinken_users,OU=utilisateurs,DC=shinkendom,DC=local",
"hosts_tag_citrix": "OU=citrix,OU=serveurs,dc=shinken,dc=local",
"hosts_tag_database": "OU=database,OU=serveurs,dc=shinken,dc=local",
"hosts_tag_exchange": "OU=exchange,OU=serveurs,dc=shinken,dc=local",
"hosts_tag_fileprint": "OU=fileprint,OU=serveurs,dc=shinken,dc=local",
"hosts_tag_windows": "OU=infra,OU=serveurs,dc=shinken,dc=local",
"hosts_match_operatingSystem_windows": "windows",
"hosts_match_operatingSystem_windows2008": "windows*.*2008(?!.*.(?:r2))",
"hosts_match_operatingSystem_windows2008r2": "windows*.*2008*.*r2",
"hosts_match_operatingSystem_windows2003": "windows*.*2003",
"hosts_match_operatingSystem_windows2012": "windows*.*2012(?!.*.(?:r2))",
"hosts_match_operatingSystem_windows2012r2": "windows*.*2012*.*r2",
"hosts_match_operatingSystem_windows2000": "windows*.*2000",
"hosts_match_operatingSystem_windowsxp": "windows*.*xp",
"hosts_match_operatingSystem_enterprise": "Enterprise",
"hosts_match_operatingSystemServicePack_sp1": "Service Pack 1",
"hosts_match_operatingSystemServicePack_sp2": "Service Pack 2",
"hosts_match_operatingSystemServicePack_sp3": "Service Pack 3",
"contacts_match_memberOf_domain-admins": "OU=shinken_admins,OU=utilisateurs,DC=shinkendom,DC=local"
}
|
If you want to import all objects of an OU instead of groups, set no contact_group_filter. All objects inside contacts_base (file openldap-connection.json) filtered via contact.filter (file openldap-mapping.json) will be imported. |
Import the objects
Go in the Administration website, if your configuration is ok you should have an ouput "OK: Import clean."
Now do a "Force import" in clicking on 
In the "Elements >" panel you will see new elements appearing (Hosts and Contacts).
The next step will be to import those new objects.
HOW TO
Import users of multiple groups
| Edit the file /etc/shinken-user/source-data/source-data-openldap/_configuration/openldap-rules.json |
"contacts_filters": "CN=shinken_admins,OU=utilisateurs,DC=shinkendom,DC=local | CN=shinken_users,OU=utilisateurs,DC=shinkendom,DC=local", |
In contact_filters, add the LDAP path to the different user groups separated by a pipe.
hosts_tag_exchange OU=Email Collaboration Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com |
Tag hosts and users to add more properties before import
This source also includes other parameters that will allow you to automatically “tag” your servers based on your active directory information:
- hosts_tag: each loaded hosts will have at least this tag
- contacts_tag: each loaded contacts will have at least this tag
Contacts to load can be easily filtered with the contacts_filters parameter.
Tagging hosts based on their OU (Organization Unit) is possible. This is done with the hosts_tag_* parameters.
For example, if you want to add the exchange tag to all the servers which are below
the OU=Email Collaboration Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com OU,
you can set this parameter:
hosts_tag_exchange OU=Email Collaboration Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=com
Setting up ldap object matching with the hosts_match_* parameters is also possible.
For example, if you want to add the enterprise tag to all the ldap object that match the string Enterprise in their operatingSystemproperty,
you only need to setup :
hosts_match_operatingSystem_enterprise Enterprise
This also works with groups.
For example, if you want to add the domain-admins tag to the users that are in the CN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=com OU,
setup :
contacts_match_memberOf_domain-admins CN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=com
Creation of your own sources
Having multiple sources can help you if you have a huge directory and want to have the control on what to import at any time. As an example, you have an OU containing Paris users and another OU containing Bordeaux users. At a given time, you want to import only Bordeaux users. If you create two sources, you can activate just the Bordeaux source and import its objects.
Every time you have to customize Shinken Sources, you have to do it in the /etc/shinken-user folder. |
You will have to do the following to create your own source :
- Create a module
- Create a source
- Configure the source-data
- Configure the Synchronizer daemon to take the new module in consideration
Create a module
cd /etc/shinken/modules/ cp openldap-import.cfg openldap-import-Bordeaux.cfg |
| Edit the file openldap-import-Bordeaux.cfg Delete the 4 lines beginning from # Shinken Enterprise to # End of Shinken Enterprise part
|
Modify
module_name openldap-example |
With
module_name openldap-Bordeaux |
Modify the following lines to point to the new source data (see below for the source data configuration)
connection_configuration_file rules_configuration_file mapping_configuration_file |
Example :
# Configuration file for your Active Directory connection (server, user, password, ...)
connection_configuration_file /etc/shinken-user/source-data/source-data-openldap-Bordeaux/_configuration/openldap-connection.json
# Configuration file for your import rules (like OU=>template rules)
rules_configuration_file /etc/shinken-user/source-data/source-data-openldap-Bordeaux/_configuration/openldap-rules.json
# Configuration file for your ldap fields mapping (like for openldap users)
mapping_configuration_file /etc/shinken-user/source-data/source-data-openldap-Bordeaux/_configuration/openldap-mapping.json
|
Create a source
cd /etc/shinken/modules/ cp openldap.cfg openldap-Bordeaux.cfg |
| Edit the file openldap-Bordeaux.cfg Delete the 4 lines beginning from # Shinken Enterprise to # End of Shinken Enterprise part |
Modify
source_name openldap-example modules openldap-example |
With
source_name openldap-Bordeaux
modules openldap-Bordeaux |
Configure the source data
To create your own import source, do the following :
cd /etc/shinken-user/source-data cp -r source-data-openldap-sample source-data-openldap-Bordeaux |
In our example :
cp -r source-data-openldap-sample source-data-openldap-Bordeaux |
Let's consider that the folder in which you will have your new OpenLDAP source is : /etc/shinken-user/source-data/source-data-openldap-Bordeaux/ |
See above on how to configure the source data
Configure the Synchronizer Daemon
| Edit the file /etc/shinken/synchronizers/synchronizer-master.cfg At the end of the "sources" lien, add you new source. |
Example :
sources syncui,cfg-file-shinken,active-dir-example,sync-vmware,cfg-file-nagios,discovery,openldap-example,openldap-Bordeaux |
| Restart the Synchronizer Daemon /etc/init.d/shinken-synchronizer restart
|
you can see your now source :
