Versions Compared

Old Version 41

changes.mady.by.user Jroy

Saved on

compared with

New Version 42

changes.mady.by.user David Labardin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 mapping rules,
  • Configure the mapping 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:

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

 

Panel
titleOn this page

Table of Contents

Setup the pre-installed source

Installation and update script of Shinken will set up a default active directory 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-active-directory-sample ).
         
    Tip
    titleAdvice

    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 active directory, it might be interesting to have many sources pointing of specific entries for performance gain).

 

Source definitions:

Enable the activ-dir-import Source:

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

    In the Automatic Detection Modules panel, clic on the selector to enable the module.

    		Image Added


     



    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

    • The source If neccessary, 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
    module_nameactive-dir
    module_typeactive-dir-import
    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

    Code Block
    languagejs
    title/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-connection.json
    {
  "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"
}
    Tip
    titleTip

    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

    Mapping rules configuration

    This file is used to apply host template, contact template and tags to the hosts and contacts while the import.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 Edit the file /etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-rulesmapping.json

    Code Block
    title/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 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

     

    Tip
    titleTip

    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.

     

     

    Tip
    titleTip

    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
    Tip
    titleTip

    See below about the tag functionnality.

     

    Example :

    Code Block
    languagejs
    title/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-rules.json
    { "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": "
    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_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", "
    2000host tag windows 2000
    hosts_match_operatingSystem_windowsxp
    ": "
    windows*.*
    xp", "
    xphost tag windows xp
    hosts_match_operatingSystem_enterprise
    ": "Enterprise", "
    Enterprisehost tag Enterprise
    hosts_match_operatingSystemServicePack_sp1
    ": "Service Pack 1", "
    Service Pack 1host tag Service Pack 1
    hosts_match_operatingSystemServicePack_sp2
    ": "Service Pack 2", "
    Service Pack 2host tag Service Pack 2
    hosts_match_operatingSystemServicePack_sp3
    ": "Service Pack 3", "
    Service Pack 3host tag Service Pack 3
    contacts_match_memberOf_domain-admins
    ": "OU=shinken_admins,OU=utilisateurs,DC=shinkendom,DC=local" }
    CN=Domain Admins,CN=Users,DC=YOUR,dc=DOMAIN,dc=comContact tag domains-admins
    Tip
    titleTip

    See below about the tag functionnality.

     

    Example :

    Code Block
    languagejs

     

    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

    code
    title/etc/shinken-user/source-data/source-data-active-directory/_configuration/active-directory-mapping.json-rules.json
    {
  "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"
}
# 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

    Code Block
    title/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

    Code Block
       "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


    Code Block
    title/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

    sources

    EXPLIQUER POURQUOI CREER PLUSIEURS SOURCES

     

    • 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 :

    Code Block
    languagebash
    cd /etc/shinken-user/source-data
cp -r source-data-active-directory-sample source-data-MY-active-directory
    Tip
    titleTip

    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.