1. Overview

Ldap Connection Check tool is a command line tool that helps Ranger admin to configure Ldap properties for UserSync module. This tool collects minimal input from admin about the ldap/AD server and discovers various properties for users and groups in order to successfully pull only targeted Users and Groups from the Ldap/AD server. It provides various options like discovering/verifying user sync related properties as well as authentication properties, generating install properties for manual installation, etc. Once all the required properties are discovered and tested, these properties can be applied in Ranger config either through Ambari or manual install.

2. Details

Ldap Connection check tool is a command line tool and can be run on any machine where Java is installed and Ldap/AD server access is available. This tool can be used to discover not only  user sync related properties but also authentication properties if needed. It also generates ambari configuration properties as well as install properties for manual installation. User is also provided an option to discover both the user and group properties together or separately. As part of the tool, a template properties file is provided for the user to update the values specific to the setup.


Following are the various options provided by the tool:

  1. Discover usersync related properties

  2. Discover authentication related properties

  3. Retrieve total count as well as details of first 20 users or groups or both by providing corresponding usersync properties.

  4. Read the input properties either from an input file or from the command line.


2.1 Building and installation

Ldap connection check tool is built as part of regular ranger build and is packed with ranger UserSync module. Following are the installation steps for this tool:

  1. Extract UserSync build to an installation folder (Apache Ranger 0.5.0 Installation#InstallingtheRangerUserSyncProcess)
  2. cd <installation folder>/ldaptool
  3. ./run.sh

Content of ldaptool directory:

  1. conf/ - This folder contains input.properties file that provided a template format.
  2. lib/ - Contains ldapconfigcheck.jar file which is the actual executable.
  3. output/ - If not specified as part of the command line, then all the output files (ambari.properties, install.properties, and ldapConfigCheck.log) are written to this folder.
  4. run.sh - this is the actual script that is used to run the tool.

2.2 Tool usage

In order to learn details on how to use the tool, the tool also provides an “help” option (-h) as follows:

usage: run.sh

-a         ignore authentication properties

-d <arg>   {all|users|groups}

-h                       show help.

-i <arg>            Input file name

-o <arg>            Output directory

-r <arg>             {all|users|groups}

All these above parameters are optional.

  1. If “-i” (for input file) is not specified, the tool will fall back to CLI option for collecting values for mandatory properties

  2. if “-o” (for output directory) is not specified, the tool will write all the output files to the <install dir>/ranger-0.5.0-usersync/ldaptool/output directory

  3. if “-a” (for ignoring authentication) is not specified, the tool will discovery & verify authentication related properties.

  4. if “-d” (for discovering usersync properties) is not specified, the tool will default to discovering all the usersync related properties

  5. if “-r” (for retrieving users and/or groups) is not specified, the tool will fallback to “-d” option.

2.3 Input properties

In order to discover the usersync and authentication related properties, tool collects some mandatory information as part of the input properties. These Mandatory properties include:

Mandatory properties include:

1. ranger.usersync.ldap.url (<ldap or ldaps>://<server ip/fqdn>:<port>

2. ranger.usersync.ldap.binddn (ldap user like AD user or ldap admin user)

3. ranger.usersync.ldap.bindpassword (user password or ldap admin password)

4. ranger.usersync.ldap.user.searchbase (Mandatory only for non AD environment)

5. ranger.usersync.ldap.user.searchfilter (Mandatory only for non AD environment)

6. ranger.admin.auth.sampleuser (Mandatory only for discovering authentication properties)

7. ranger.admin.auth.samplepassword (Mandatory only for discovering authentication properties)

This tool provides two options for collecting values for these mandatory properties:

  1. Modify the input.properties file provided as part of the tool installation and provide that file (with complete path as the command line argument while running the tool.

  2. Use CLI to input the values for these mandatory properties.

CLI option is provided to the user when the input file is not provided as the command line option (-i <arg>) while running the tool. Once the values are collected from the CLI, these values are stored in the input.properties file (in the conf dir of the installation folder) for later use.

Following is the CLI provided by the tool when input file is not specified:

Ldap url [ldap://ldap.example.com:389]:

Bind DN [cn=admin,ou=users,dc=example,dc=com]:

Bind Password:

User Search Base [ou=users,dc=example,dc=com]:

User Search Filter [cn=user1]:

Sample Authentication User [user1]:

Sample Authentication Password:

Note:- In order to use secure ldap, the java default truststore must be updated with the server’s self signed certificate or the CA certificate for validating the server connection. The truststore should be updated before running the tool.

2.4 Discovery of usersync properties

Usersync related properties are divided into two categories - User search related properties and group search related properties. This tool provides an option (“-d”) to discover user related and group related properties separately or at once. Following is the discover properties option:

-d,--discoverProperties <arg>   {all|user|group}

where <arg> can be

  1. all: discover all the properties at once or

  2. user: discover only user search related properties or

  3. group: discover only group search related properties

These properties are discovered based on the values provided in the input file for all the mandatory properties.


Following are the user search related properties that are discovered using this tool:

  1. Basic properties -

    1. ranger.usersync.ldap.user.objectclass

    2.  ranger.usersync.ldap.user.groupnameattribute

    3. ranger.usersync.ldap.user.nameattribute

  2. Advanced properties -

    1. ranger.usersync.ldap.user.searchbase

    2. ranger.usersync.ldap.user.searchfilter

Group search related properties that are discovered by this tool are as follows:

  1. Basic properties -

    1. ranger.usersync.group.searchenabled

    2. ranger.usersync.group.objectclass

    3. ranger.usersync.group.memberattributename

    4. ranger.usersync.group.nameattribute

  2. Advanced properties -

    1. ranger.usersync.group.searchbase

    2. ranger.usersync.group.searchfilter

Once all the properties are discovered, the tool also retrieves the total count and details of first  20 users and/or groups and displayed in the output.

  1. Value for user search base is derived as the OU with max. no of users (from the first 20 users that are retrieved).

  2. Value for user search filter is derived as <user name attribute>=*

  3. Value for group search base is derived as the OU with max. no of groups (from the first 20 retrieved groups).

  4. Value for group search filter is derived as <group name attribute>=*

2.5 Discovery of authentication properties

This tool provides an option (-a) to skip discovery of authentication properties. When admin runs the tool with this option, the tool will not suggest the values for authentication related properties. The authentication option is as follows:

-a          Ignore authentication properties

If the ldap server is of type active directory, following properties are suggested:

  1. ranger.authentication.method

  2. ranger.ldap.ad.domain

Whereas, if the ldap server is not an active directory, following properties are suggested:

  1. ranger.authentication.method

  2. ranger.ldap.user.dnpattern

  3. ranger.ldap.group.roleattribute

  4. ranger.ldap.group.searchbase

  5. ranger.ldap.group.searchfilter

These authentication properties can be discovered either by providing the values in the input file for just mandatory properties or for all the user and/or group related properties. After discovering the authentication properties, the tool also validates those properties by authenticating the given user and provides authentication success or failure result in the output.

2.6 Retrieval of users and/or groups

In order to test the user and/or group related properties, this tool provides an option (-r) to retrieve top 20 users/groups by providing the values for corresponding properties in the input file. Following is the retrieve option:

-r,--retrieve <arg>             {all|users|groups}

where arg can be:

  1. users: retrieve total count and details of first 20 users and associated groups, given the user search related properties in the input file

  2. groups: retrieve total count and details of first 20 groups and associated users, given the group search related properties in the input file

  3. all: retrieve both users and groups, given all the corresponding properties in the input file.

2.7 Output directory content

This tool generates three files in the specified output directory or by default to <install dir>/ranger-0.5.0-usersync/ldaptool/output -

  1. ambari.properties

  2. install.properties

  3. ldapConfigCheck.log

All the discovered properties (related to usersync and/or authentication) are written to both ambari.properties and install.properties files with the corresponding property names.

All the other information like any retrieved users/groups, total count, authentication result, etc… are written to ldapConfigCheck.log file. This log file also contains any errors or warning generated while running the tool.

2.8 Other usersync related properties

Some of the other usersync related properties that are used by the tool and left with default values are:

  1. ranger.usersync.ldap.authentication.mechanism - Default authentication mechanism used is “simple”.

  2. ranger.usersync.pagedresultsenabled - Default is set to “true”.

  3. ranger.usersync.pagedresultssize - Default value for this property is “500”. This value can be tweaked depending on the bandwidth and resource availability in the deployment.

  4. ranger.usersync.ldap.username.caseconversion - Default value is set to “lower”

  5. ranger.usersync.ldap.groupname.caseconversion - Default value is set to “lower”

  6. ranger.usersync.ldap.user.searchscope - Default is set to “sub”. This value can be set to either “base” or “one” depending on how the user search to be performed.

  7. ranger.usersync.group.searchscope - Default is set to “sub”. This value can be set to either “base” or “one” depending on how the group search to be performed.

Following are the remaining usersync related properties. These are not currently used by the tool and the values are left empty in the input file.

  1. ranger.usersync.credstore.filename - this property is unused as the tool supports only cleartext password.

  2. ranger.usersync.ldap.bindalias - this property is also not used by the tool.

  3. ranger.usersync.ldap.searchBase - This property is used as user search base or group search base when they are not configured. Hence this value is left blank and not used by the tool.

  4. ranger.usersync.group.usermapsyncenabled - Mainly used for computing group memberships while retrieving users. Currently this value is set to “true”, but not used by the tool.

3. Assumptions


Some of the properties are assumed to have one or more values as follows:

1. User name attribute  - "sAMAccountName", "uid", "cn"

2. User Object class value - "person", "posixAccount"

3. User group member attribute - "memberOf", "ismemberOf"

4. Group Object class - "group", "groupOfNames", "posixGroup"

5. Group name attribute - "distinguishedName", "cn"

6. Group member attribute - "member", "memberUid"

4. Sample input.properties

# Mandatory ldap configuration properties.




# Mandatory only for openLdap



# For verifying authentication please provide sample username and password



# Optional properties will be determined based on the above search

# User attributes




# Group attributes







# Other UserSync related attributes












# Authentication properties










  • No labels

1 Comment

  1. Sailaja Polavarapu For ignoring authentication, the parameter is "-a", instead of "noauth" when running run.sh