Table of Contents

1. Overview

...

2. Details

2.1 Tool usage

...

2.3 Discovery of usersync properties

2.4 Discovery of authentication properties

2.5 Retrieval of users and/or groups

2.6 Output directory content

2.7 Other usersync related properties

3. Assumptions

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.

...

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

-noauth         ignore a         ignore authentication properties

...

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 “-noauth” 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:

...

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:

...

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 (-noautha) 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:

-noauth          Ignore a          Ignore authentication properties

...

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:

...

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 -

...

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:

...