Overview

This document describes how you can import hosts and users from Active Directory.

There are some steps you’ll need to follow in order to be able to import hosts and users : 

  • Enable the Active Directory source,
  • Configure the Active Directory module,
  • Configure the connection to Active Directory,
  • Configure the import rules,
  • Configure the mapping 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:

  1. Installation of the Active Directory import module,
  2. Availability of an example of pre configured active directory source ready to be customized.

 

Setup the pre-installed source

Installation and update script of Shinken will set up a default active directory source already configured:

  • This source use 2 kinds of configuration files 
    • Source definition files: 
    • Configuration file to customize the data mining.
      • available in folder ( /etc/shinken-user/source-data-active-directory-sample ).
  • You are now ready to be modified according to your Active Directory Infrastructure.

Source definition:

Enable the activ-dir-import Source:

  • Edit the file /etc/shinken/sources/activ-dir-import.cfg
  • Set Enabled to 1

You can find the following parameters in the source file :

 

 Property Example Description
source_name active-dirName of this source. Must be unique.
order 2Order in the merge algorithm of this source data. Look in the Synchronizer page for more information about it.
import_interval 5Launch this source every import_inverval minutes.
modulesactive-dir(module used by shinken to parse active directory data)
enabled0Activate or Disable the source.
descriptionThis source is about loading hosts from active directories

Configure the Active Directory Module

  • Edit the file /etc/shinken/modules/activ-dir-import.cfg
  • Uncomment and change the following parameters to point to the file located in /etc/shinken-user/source-data/source-data-active-directory

 

PropertyValue
connection_configuration_file/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-connection.json
rules_configuration_file/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-rules.json
mapping_configuration_file/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-mapping.json

Connection configuration

This file is used to make the connexion to your Active Directory server.

Edit the file /etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-connection.json

 

PropertyDefaultDescription
urlldap://YOUR-DC-FQDN/URL of your Active Directory server.
base dc=YOUR,dc=DOMAIN,dc=comBase OU for your objects discovery.
hosts_baseOU=DataCenter Servers,dc=YOUR,dc=DOMAIN,dc=comBase OU for the hosts discovery.
contacts_basedc=YOUR,dc=DOMAIN,dc=comBase OU for the contacts discovery.
usernameSHINKEN@YOURDOMAIN.comUsername used to connect to the Ldap server.
passwordPASSWORDPassword 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 Active Directory import module.

 

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-active-directory/_configuration/active-directory-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 :

hosts_tagwindows

 

The mandatories properties to modify are in green.

 

PropertyDefaultDescription
hosts_tagyourdomainShinken host template applied during the import
contacts_taggeneric-contactShinken contact template applied during the import
contacts_filtersCN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=com | CN=OTHERGROUPS,OU=Groups,OU=Users Groups,DC=YOUR,dc=DOMAIN,dc=comUser group to import
hosts_tag_citrixOU=Terminal Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=comhost tag citrix
hosts_tag_databaseOU=Database Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=comhost tag database
hosts_tag_exchangeOU=Email Collaboration Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=comhost tag exchange
hosts_tag_fileprintOU=Files Print Servers,OU=DataCenter Servers,DC=YOUR,dc=DOMAIN,dc=comhost tag fileprint
hosts_match_operatingSystem_windowswindowshost tag windows
hosts_match_operatingSystem_windows2008windows*.*2008(?!.*.(?:r2))host tag windows2008
hosts_match_operatingSystem_windows2008r2windows*.*2008*.*r2host tag windows 2008r2
hosts_match_operatingSystem_windows2003windows*.*2003host tag windows2003
hosts_match_operatingSystem_windows2012windows*.*2012(?!.*.(?:r2))host tag windows2012
hosts_match_operatingSystem_windows2012r2windows*.*2012*.*r2host tag windows2012r2
hosts_match_operatingSystem_windows2000windows*.*2000host tag windows 2000
hosts_match_operatingSystem_windowsxpwindows*.*xphost tag windows xp
hosts_match_operatingSystem_enterpriseEnterprisehost tag Enterprise
hosts_match_operatingSystemServicePack_sp1Service Pack 1host tag Service Pack 1
hosts_match_operatingSystemServicePack_sp2Service Pack 2host tag Service Pack 2
hosts_match_operatingSystemServicePack_sp3Service Pack 3host tag Service Pack 3
contacts_match_memberOf_domain-adminsCN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=comContact tag domains-admins

See below about the tag functionnality.

 

Example :

{
  "hosts_tag": "windows",
  "contacts_tag": "generic-contact",
  "contacts_filters": "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"
}

 

Mapping rules configuration

This file allow you to do the mapping between Active Directory 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-active-directory/_configuration/active-directory-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 Active Directory)
   "host.name": "name",
   "host.dNSHostName": "dNSHostName",
   "host.operatingSystem": "operatingSystem",
   "host.operatingSystemServicePack":"operatingSystemServicePack",
   "host.distinguishedName": "distinguishedName",
   "host.filter": "(objectClass=computer)",

# Now contact properties
    "contact.name": "name",
    "contact.telephoneNumber":"telephoneNumber",
    "contact.mobile":"mobile",
# 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 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 host with specific names

Edit the file /etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-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 Active Directory)
   "host.name": "name",
   "host.dNSHostName": "dNSHostName",
   "host.operatingSystem": "operatingSystem",
   "host.operatingSystemServicePack":"operatingSystemServicePack",
   "host.distinguishedName": "distinguishedName",
   "host.filter": "(objectClass=computer)",

# Now contact properties
    "contact.name": "name",
    "contact.telephoneNumber":"telephoneNumber",
    "contact.mobile":"mobile",
# 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":""
}

Modify the host.filter

   "host.filter": "(&(objectClass=computer)(sAMAccountName=*SERVER_NAME*))",

Change SERVER_NAME by the server name pattern you want to import.

Import users of multiple groups

Edit the file /etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-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.

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

 


 

 

 

 

 

 

 



source-data-MY-active-directory

Creation of your own configuration files

  • You should keep them unmodified and create your source in copying them.
  • Every time you have to customize Shinken Sources, you have to do it in the /etc/shinken-user folder.

 

To create your own import source, do the following :

cd /etc/shinken-user/source-data
cp -r source-data-active-directory-sample source-data-MY-active-directory

Let's consider that the folder in which you will have your new Active Directory source is : /etc/shinken-user/source-data/source-data-MY-active-directory/
inside it, the folder _configuration contain all configuration file to customize the source behavior.