2 Installing and Configuring the LDAP Gateway

The LDAP Gateway acts as the intermediary between Oracle Identity Manager and the connector components on the mainframe. You can install the LDAP Gateway either on a Microsoft Windows or RHEL Linux platform.

Hardware Requirements for Installing the LDAP Gateway

These are the recommended hardware requirements that are designed to give you optimal system performance from the LDAP gateway.

Table 2-1 Hardware Requirements for Installing the LDAP Gateway

Requirement Type	Processor	RAM	Hard Disk	Network Interface
Minimum hardware requirement	2 GHz single-core processor	4 GB RAM	10GB hard disk drive	1
Recommended hardware requirement	2 GHz multicore processor	16 GB RAM	50GB hard disk drive	1

Installing the LDAP Gateway

You can install the LDAP Gateway on Windows and Linux platforms.

See Hardware Requirements for Installing the LDAP Gateway and the "LDAP Gateway" row of Certified Components to ensure that the computer on which you want to install the LDAP Gateway meets the recommended specifications.

To install the LDAP Gateway:

Download and save the connector installation package to any directory on the computer that will host the LDAP Gateway. You can download the connector installation package from the OTN website at http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/connectors-101674.html
Extract the contents of the connector installation package to any directory on the computer. This creates a directory named CONNECTOR_NAME-RELEASE_NUMBER.
Extract the contents of the etc/LDAP Gateway/IDF_LDAP_GATEWAY_vX.X.X.zip file from the connector installation package to a temporary directory on the computer hosting the LDAP gateway.
Depending on the operating system computer on which you want to install the LDAP Gateway, run one of the following files:
- Microsoft Windows: IDFLDAPGateway-X-windows-oracle-vX.X.X.exe
- Linux: IDFLDAPGateway-X-linux-x64-oracle-vX.X.X.run
On the Setup - LDAP Gateway screen, click Next to proceed with installation.
On the License Agreement screen, select I accept the agreement if you agree with the terms of the agreement, and then click Next.
On the Installation Location screen, specify the location where the LDAP Gateway must be installed.
- For Linux:
  When you install the gateway as a normal user, the default location is inside the Home folder (home/ubuntu/IDFLDAPGateway-X).
  
  When you install the gateway as a sudo or root user, the default location is /opt/IDFLDAPGateway-X.
- For Microsoft Windows, the default location is Program files (…\ProgramFiles (x86)\IDFLDAPGateway-X)
Click Next to proceed.
On the License File screen, browse to the location containing the license.lic file, select it and then click Next. For the license.lic file please contact the Oracle team.
The Ready to Install window is displayed.
Click Next to proceed.
The Installing screen with a progress indicator bar for the installation is displayed.
On the Completing the LDAP Gateway Setup Wizard screen, select View Readme File if you want to read the enhancements made to the gateway. Click Finish to complete the installation process.

Upgrading the LDAP Gateway

If you already have an earlier version of the LDAP Gateway (for example, version 5.x), then you can upgrade it to the latest version 6.x by running the LDAP gateway installer.

Note:

Before you begin the upgrade procedure:

On the computer hosting the gateway, stop the running instance of the gateway. If you are using a Microsoft Windows Service to run the gateway, then uninstall the Windows service.
In the target system environment, shut down any agents (for example, Pioneer or Voyager) that may be running.
Disable any cron jobs.

To upgrade the LDAP Gateway, do the following:

Download and save the connector installation package to any directory on the computer that will host the LDAP Gateway. You can download the connector installation package from the OTN website at http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/connectors-101674.html.
Extract the contents of the connector installation package to any directory on the computer. This creates a directory named CONNECTOR_NAME-RELEASE_NUMBER.
Extract the contents of the etc/LDAP Gateway/IDF_LDAP_GATEWAY_v6.4.0.zip file from the connector installation package to a temporary directory on the computer hosting the LDAP gateway.
Depending on the operating system of the computer on which the LDAP gateway is installed, run one of the following files:
- For Linux: IDFLDAPGateway-6-linux-x64-v6.4.0.run
- For Microsoft Windows: IDFLDAPGateway-6-windows-v6.4.0.exe
On the Setup - LDAP Gateway screen, click Next to proceed with upgrade.
On the License Agreement screen, select I accept the agreement if you agree with the terms of the agreement, and then click Next.
The installer detects the earlier installation of the gateway as shown in the following image:

Description of the illustration prev_install_detected.png
On the Previous Installation Detected screen, when you are prompted whether you want to upgrade the existing installation, select one of the following options:
- select Yes if you want to upgrade, and click Next to proceed. Then, on the Ready to Install screen, click Next to proceed with the upgrade.
- Select No if you want to perform a fresh installation, and then click Next to proceed.
Note:
To upgrade from version 5.x to 6.x, you need to provide the location of the existing installation folder location and the path of the valid license file. If the installation folder location is same, then the installer detects and creates a backup of the entire folder of the previous version with a suffix pre- and a timestamp. This can be verified at the installation location. The backup of the entire folder happens only once when you are upgrading from version 5.x to version 6.x. For example, if you already have a Gateway version 5.3 installed on your system, and you want to install Gateway version 6, then a backup folder for the files of 5.3 is created at the installation location.

The Ready to Install window is displayed.
If you selected No on the Previous Installation Detected screen, then on the Installation Directory screen, specify the location where the gateway must be installed.
1. For Linux:
  
  When you install the gateway as a normal user, the default location is inside the Home folder (home/ubuntu/IDFLDAPGateway-6).
  
  When you install the gateway as a sudo or root user, the default location is /opt/IDFLDAPGateway-6.
2. For Microsoft Windows, the default location is Program files (…\ProgramFiles (x86)\IDFLDAPGateway-6)
  
  Note:
  If the installation directory points to a location containing an existing gateway, that gateway is automatically upgraded during the installation process.
Click Next. In the Upgrade Previous Install dialog box, click Yes to confirm that you want to upgrade your existing installation of the gateway.
In the Ready to Install screen, click Next to proceed with the upgrade.
The Installing screen with a progress indicator bar for the installation is displayed.
On the Completing the LDAP Gateway Setup Wizard screen, select View Readme File if you want to read the enhancements made to the gateway. Click Finish to complete the upgrade process.

Configuring the LDAP Gateway

Configure the LDAP gateway to connector to the target system and access the data.

The following topics describe the procedure to configure the LDAP Gateway:

Note:

The following procedures are for a fresh installation only. If you already have a running setup or if you want to upgrade, then you do not have to perform these procedures.

Setting Connection Properties

The LDAP_INSTALL_DIR/conf directory contains the tops.properties.example file that contains sample entries and is used as the basis for configuring the gateway.

The tops.properties.example file is only a sample file. Therefore, create a separate properties file (for example, tops.properties) in the LDAP_INSTALL_DIR/conf location by creating a copy of the tops.properties.example file. Use this properties file to specify connection information that the gateway uses to connect to your target system. To do so:

In the LDAP_INSTALL_DIR/conf directory, create a copy of the LDAP_INSTALL_DIR/conf/tops.properties.example file and rename it to for example, tops.properties.

Note:
If you are configuring the gateway for multiple instances of the target system, then you must create a copy of the LDAP_INSTALL_DIR/conf/tops.properties.example file and rename it for each target system instance. Ensure that the names of the renamed files are not the same.

In a text editor, open the tops.properties file for editing and set values for properties such as host, port, user credentials and so on to point to your environment.

The following table describes these properties.

Table 2-2 Properties in the tops.properties File

Property	Description
agentPort	Enter the port number on the LDAP gateway host computer that you are going to reserve for messages sent from the mainframe by the Reconciliation Agent, Voyager. The LDAP gateway will receive real-time reconciliation messages using this port. This value should match the value of the PORT parameter in the Voyager agent control file.
agentMetaRecon	This property specifies whether Voyager must reconcile user data from the target system into the legacy meta store that is located in the LDAP gateway. The reconciled data is stored in the `OU=tops` subtree of the `OU=People` tree that is located in the system backend (`DC=System,DC=Backend`). Enter `true` to reconcile user data into the legacy meta store. Otherwise, enter `false`. The default value of this property is `true`. Note: If you upgraded the LDAP gateway from release 5.x to 6.x, then this property is not available in the tops.properties file by default. If you want to use this property, then you must add it to the tops.properties file manually.
agentCachingRecon	This property specifies whether Voyager must reconcile user data from the target system into the caching store that is located in the LDAP gateway. The reconciled data is stored in the `OU=people` subtree of the `OU=tops1` tree that is located in the system backend (`DC=System,DC=Backend`). Enter `true` to reconcile user data into the caching store. Otherwise, enter `false`. The default value of this property is `true`. Note: If you upgraded the LDAP gateway from release 5.x to 6.x, then this property is not available in the tops.properties file by default. If you want to use this property, then you must add it to the tops.properties file manually. If you set the value of this property to `true`, then ensure that the caching layer is enabled. If the caching layer is not enabled, then data is reconciled into the legacy meta store instead of the caching store. See Understanding the Caching Layer for information on how to enable the caching layer.
configDNames	This property holds the name of any custom target system attributes that should be included when the LDAP gateway parses a user profile from the target system (typically performed during reconciliation). If you are using a target system attribute that is not supported out-of-the-box, then add the name of that attribute to the value of the configDNames property. The name should match the format of the attribute name when executing a LIST command on the target system and you must include the Spaces and = for each attribute. This step is mentioned in the following sections: Adding Custom Fields for Target Resource Reconciliation Adding Custom Fields for Provisioning For example, if you defined two Top Secret fields named PST15, and VEND, then you would enter: # CONFIG DISPLAY NAMES configDNames =VEND =\|PST15 =\| To enter multiple custom attributes, separate each entry with a vertical bar.
configAttrs	This property holds the name of any custom target system attributes that should be included when the LDAP gateway parses a user profile from the target system (typically performed during reconciliation). If you are using a target system attribute that is not supported out-of-the-box, then add the name of that attribute to the value of the configAttrs property. The name should match the format of the attribute name when executing a LIST command on the target system but without the data from above in the configDNames and this is that will match your LDAP and OIM attribute name when configuring. This step is mentioned in the following sections: Adding Custom Fields for Target Resource Reconciliation Adding Custom Fields for Provisioning For example, if you define three Top Secret fields named $PST15, PST VRO 16, and VEND ID, then you would enter: `# CONFIG ATTRIBUTES` `configAttrs=$PST15\|VEND\|` To enter multiple custom attributes, separate each entry with a vertical bar.
configDatasets	If you create a custom dataset on the target system, then add the name of that dataset type to the value of the configDatasets property. For example: `# CONFIG DATASETS` `configDatasets=$RAFT` To enter multiple custom dataset names, separate each entry with a vertical bar.
customDataset	This property is used to store custom dataset names when issuing a WHOHAS command to the Top Secret system. If more than one custom dataset exists, separate each entry with a vertical bar ('\|') character. Custom datasets that are added to this property will be included when the dataset lookup synchronization task ('Top Secret Find All Datasets') is run in Oracle Identity Manager. For example: `# CUSTOM DATASETS FOR WHOHAS COMMAND` `_customDataset_$XRAFT\|$RAFT\|`
host	Enter the host name or IP address of the computer that must connect to Pioneer. For example, `_host_=localhost`.
port	Enter the number of the port on the Mainframe that you are going to reserve for Pioneer. The LDAP gateway will send provisioning messages to this port. This value should match the PORT parameter specified in the Pioneer provisioning agent STC. For example, `_port_=5790`.
stcID	This property is not supported from 9.0.4.18 and later releases of this connector. This property allows the real-time agent to ignore events that have been submitted to the target system by the Pioneer STC (such as by request from Oracle Identity Manager). Enter the name given to the Pioneer STARTED TASK.
domainOu	This property stores users in the specified subtree under the ou=People tree of the internal LDAP store. This entry needs to be unique and specific for each system if multiple systems are used within one LDAP gateway. Default setting is `domainOu=tops`
internalEnt	This property allows the real-time agent to store user data in the LDAP gateway internal store. Values: `[true\|false]`
ignoreChar	Use this property to specify characters in PROFILE names that must be ignored when retrieving user data from the LDAP gateway. For example: Suppose User1 is a member of the TESTGRP1 profile until 01-Jan-2020. When a LIST function is called for User1, the output for the PROFILES section is `TESTGRP1`. If you set the value of the ignoreChar property to , then the LDAP gateway ignores the asterisk character in the name of the profile. In other words, when the LIST function is called, the output for the PROFILES section is `TESTGRP1.` You can set multiple characters to be ignored as the value of the ignoreChar property. Do not use any blank character or space as the delimiter for the set of characters that you specify. For example, if you want both the asterisk character and the dollar sign ($) to be ignored, then enter the value as shown: `ignoreChar=$` Suppose User2 is a member of the TESTGRP1, TESTGRP2, and *TESTGRP$ profiles. If a LIST function is run for User2, then the following profiles are listed: `TESTGRP1, TESTGRP2, TESTGRP`
processFailedXML	This property is used by the Top Secret Reconcile Users to Internal LDAP scheduled task and determines whether the LDAP gateway will attempt to parse any failed XML entries. Default value: `true`
isStreamingUsers	This property is used by the Top Secret Reconcile Users to Internal LDAP scheduled task. If you set the value of this property to `true,` the LDAP gateway will process the CFILE data from the mainframe. If you set the value of this property to `false,` the LDAP gateway will not process any CFILE data. Default value: `true`
revokePsuspendUsers	Use this property to specify whether users with the PSUSPEND attribute should be flagged as revoked when parsing a LIST USER result message. Set `true` as the value if you want the user to be disabled in Oracle Identity Manager as the outcome of a LIST USER reconciliation operation. Set `false` as the value if you want the PSUSPEND attribute to not factor into the user's Oracle Identity Manager Status setting as the outcome of a LIST USER reconciliation operation. For example: `# REVOKE OIM USERS WITH PSUSPEND` `revokePsuspendUsers=true`
secretKeyValue	Enter the secret key that the LDAP gateway must use to connect to the Mainframe.
includeData	This property is used when retrieving a list of all users on the Top Secret system. If you set the value of this property to true, for each ACID in TSS, the LDAP gateway will return both the ACID and the user data. If you set the value of this property to false, for each ACID in TSS, the LDAP gateway will only the ACID. Default value: `false`
resumeOnReset	This property is used when resetting a user's password. If you set the value of this property to true, the user will be enabled during a reset password operation. If you set the value of this property to false, the user will not be enabled during a reset password operation. Default value: `true`
trimOmvsUid	This property is used with the omvsUid attribute. If you set the value of this property to true, the LDAP gateway will trim leading zeros, "0", from the omvsUid value. If you set the value of this property to false, the LDAP gateway will not trim any leading zeroes from the omvsUid value. Default value: `true`
trimNum	This property is used with the trimOmvsUid property and specifies the number of leading zeroes to trim from a user's omvsUid attribute. Default value: `2`
newOmvsUidAttr	This property specifies the new name to use for the omvsUid property. Default value: `OmvsUidEmplNumber`
usePwdComplexLength	This property is used to control the length of passwords. If you set the value of this property to true, the LDAP gateway will use the properties file password length settings. If you set the value of this property to false, the LDAP gateway will use the standard password length. Default value: `true`
idMinLength	This property specifies the minimum ACID length in characters. Default value: `1`
idMaxLength	This property specifies the maximum ACID length in characters. Default value: `8`
pwdMinLength	This property specifies the minimum password length for an ACID. Default value: `1`
pwdMaxLength	This property specifies the maximum password length for an ACID. Default value: `8`
minDays	This password specifies the minimum number of days that must pass before a password can be changed. Default value: `0`
mainframeCodePage	This property specifies the mainframe code page in use on the mainframe. Default value: `CP857`
luMulti	This property is used with LU6.2 attributes. If you set the value of this property to true, the LDAP gateway will process LU6.2 attributes as multivalued attributes. If you set the value of this property to false, the LDAP gateway will process LU6.2 attributes as single-valued attributes. Default value: `true`
luMultiSep	This property is used with LU6.2 attributes and specifies the separator character used for multivalued attributes. Default value: `\|`
userTypes	This property is used to specify all the types of users that must be retrieved and added to the ou=people container when a full-blown search is performed. You must list all the user types separated by a vertical bar (\|). For example, USER\|DCA\|VCA\|SCA\|LSCA\|ZCA\|. Default value: `USER\|`
sslEnabled	Set the value of this property to `true` if the agent supports SSL messaging. Otherwise, specify `false`. Default value: `false`
tlsVersion	This property is used to specify the TLS version that is enabled for the agent. You can set the value of this property to `TLSv1.1` or `TLSv1.2` and can be extended to `TLSv1.3` in future if required. Default value: `TLSv1.2`
type isencrypted timeout authretries requestorId CPF CPF-WAIT _adminAttrs_ _adminDNames_	These properties are no longer used in Oracle installations. Do not modify their values.

If you want to include custom segment as a part of the TSS LIST command set, then set a value for the _configDatasets_ property.
Use the following components to set a value for the _configDatasets_ property:
- Use fn to represent the first name.
- Use sp to represent the space character.
- Use ln to represent the last name.
- Use a comma (,) to represent the comma.
- Use a period (.) to represent the period.
- Use the vertical bar (|) as the separator for the other components.
Save and close the file.

Creating the Connector Configuration

To allow the gateway to work with the target system, you must create and configure the customer-configuration.properties file for the type of connector and its related parameters for the operations.

Note:

In this guide, LDAP_INSTALL_DIR is the standard term used to refer to the directory in which the gateway has been installed. For example, for a Microsoft Windows host machine, the default installation directory for the gateway is . .\Program Files (x86)\IDFLDAPGateway-6\.

The LDAP_INSTALL_DIR/conf directory has the customer-configuration.properties.example file that contains sample configuration entries and is used as the basis for creating the connector configuration. As the customer-configuration.properties.example file is only a sample file, you must create a separate properties file (for example, customer-configuration.properties) in the LDAP_INSTALL_DIR/conf directory to include and configure entries specific to your connector from the customer-configuration.properties.example file.

Create an empty customer-configuration.properties text file in the LDAP_INSTALL_DIR/conf directory.

Note:
If you have upgraded the gateway, then skip this step as the customer-configuration.properties file already exists and contains all the connector configurations present in the beans.xml file.
In the LDAP_INSTALL_DIR/conf directory, locate and open the customer-configuration.properties.example file.
The customer-configuration.properties.example file contains sample definitions (configuration properties) in various sections for each connector that the LDAP Gateway can be used with.

Search for and copy the following snippet from the customer-configuration.properties.example file, and paste it into the customer-configuration.properties file located in the LDAP_INSTALL_DIR/conf directory.

cnctr.tops.class=com.identityforge.idfserver.backend.tops.TopsModule
cnctr.tops.tops1.schema=schemas
cnctr.tops.tops1.suffix=dc=tops,dc=com
cnctr.tops.tops1.adminUserDN=cn=idfTopsAdmin,dc=tops,dc=com
cnctr.tops.tops1.adminUserPassword=idfTopsPwd
cnctr.tops.tops1.altAdminUserDN=cn=oimTopsAdmin,dc=tops,dc=com
cnctr.tops.tops1.altAdminUserPassword=oimTopsPwd
cnctr.tops.tops1.configLocation=../conf/tops.properties
cnctr.tops.tops1.allowAnonymous=false
cnctr.tops.tops1.metaBackend=ldapds
cnctr.tops.tops1.agent=true
cnctr.tops.tops1.customSchemaLocation=
cnctr.tops.tops1.people.multiCallAttributes=userpassword,attributes,uid,userpassword|userpassword,userpassword|passwordexpire|passwordexpiredays
# Simple equality filters using the following attributes will be passed through to the target
cnctr.tops.tops1.cachingAllowedTargetFilterAttributes=uid,objectClass,alldata

In the customer-configuration.properties file, rename the connector qualifier for the newly pasted entries to match the name of the connection properties file that you created in Setting Connection Properties. Suppose you created a properties file named topsecret.properties, then rename all instances of tops in the newly pasted configuration entries to topsecret. For example, in the cnctr.tops.tops1.suffix=dc=tops,dc=com property, rename tops to topsecret. So the entry will now be cnctr.topsecret.tops1.suffix=dc=tops,dc=com
Similarly, rename the instance ID for all the configuration properties. For example, in the cnctr.tops.tops1.schema=schemas property, rename tops1 to tops2.
Edit the value of the cnctr.tops.tops1.configLocation= property to point to the connection properties file that you created in Setting Connection Properties. For example, if you created a file named topsecret.properties, then replace cnctr.tops.tops1.configLocation= ../conf/tops.properties with cnctr.tops.tops1.configLocation= ../conf/topsecret.properties
Change the default system administrator credentials that the gateways uses to connect to the target system as follows:
1. Locate the following properties:
```
cnctr.tops.tops1.adminUserDN=cn=idfTopsAdmin,dc=tops,dc=com
cnctr.tops.tops1.adminUserPassword=idfTopsPwd
```
2. Set new values for the adminUserDN and adminUserPassword properties and note them down. You must enter the same values for the idfPrincipalDn and idfPrincipalPwd parameters of the IT resource.
  Note:
  - By default, all sensitive data is automatically encrypted when you start the gateway.
  - For the adminUserDN property:
    
    It is mandatory to that you use cn as the RDN identifier.
    
    If you put spaces after the commas in the DN, then you must match that when using that ID to connect to the gateway. For example, if the required format is cn=adminId,dc=tops,dc=com, then dc=tops,dc=com must match the suffix property.
Save and close the file.
Restart the gateway for the changes to take effect.

Configuring the LDAP Gateway for Multiple Installations of the Target System

You can instantiate the same type of connector multiple times to represent multiple different endpoints of the same target system. This is in addition to the gateway supporting the ability to run connectors for various target systems within a single gateway instance.

If you have already configured a single instance of the connector for one target system installation and want to configure an additional instance, then:

For each target system installation in your environment, create a properties file in the LDAP_INSTALL_DIR/conf directory by creating a copy of the LDAP_INSTALL_DIR/conf/tops.properties file. Then, edit the newly created properties file to specify all connection properties.

Open the customer-configuration.properties.example file located in the LDAP_INSTALL_DIR/conf directory, copy the following configuration properties specific to your connector and paste it into the LDAP_INSTALL_DIR/conf/customer-configuration.properties file, below the existing set of configuration properties.

cnctr.tops.class=com.identityforge.idfserver.backend.tops.TopsModule
cnctr.tops.tops1.schema=schemas
cnctr.tops.tops1.suffix=dc=tops,dc=com
cnctr.tops.tops1.adminUserDN=cn=idfTopsAdmin,dc=tops,dc=com
cnctr.tops.tops1.adminUserPassword=idfTopsPwd
cnctr.tops.tops1.altAdminUserDN=cn=oimTopsAdmin,dc=tops,dc=com
cnctr.tops.tops1.altAdminUserPassword=oimTopsPwd
cnctr.tops.tops1.configLocation=../conf/tops.properties
cnctr.tops.tops1.allowAnonymous=false
cnctr.tops.tops1.metaBackend=ldapds
cnctr.tops.tops1.agent=true
cnctr.tops.tops1.customSchemaLocation=
cnctr.tops.tops1.people.multiCallAttributes=userpassword,attributes,uid,userpassword|userpassword,userpassword|passwordexpire|passwordexpiredays
# Simple equality filters using the following attributes will be passed through to the target
cnctr.tops.tops1.cachingAllowedTargetFilterAttributes=uid,objectClass,alldata

Close the customer-configuration.properties.example file.

In the LDAP_INSTALL_DIR/conf/customer-configuration.properties file, rename the instance ID for all the newly pasted configuration properties. For example, in the cnctr.tops.tops1.schema=schemas property, replace tops1 with tops2.

Note:

Ensure that the connector name qualifier in the configuration properties matches the one that you specified while performing the procedure described in Creating the Connector Configuration. For example, in the cnctr.tops.tops1.suffix=dc=tops,dc=com configuration property, if you renamed tops to topsecret, then you must do the same for all newly added configuration properties here.
Modify the following properties:
- adminUserPassword - change the default value for security reasons.
- suffix - Enter the unique baseDN that you want to use in OIM. The default value is dc=tops,dc=com. You can change the default value to a baseDN of your choice.
- adminUserDN - Enter the full DN of an administrative user account that is allowed to use the connector for reconciliation and provisioning operations. Note that the DN suffix must match the value that you set for suffix property.
- altAdminUserDN - Enter the full DN of the alternative administrative user account that is allowed to use the connector for reconciliation and provisioning operations. Note that the DN suffix must match the value that you set for suffix property.
- configLocation - Enter the location of the property file (created in Step 1) for the instance of the target system. For example, . . conf/topsecret10.properties. If the intent is to point these two connectors to different target systems, then the configLocation property should point to a different connector properties file (created in Step 1) for each target system instance. The new properties file can be a copy of the original properties file with changes in the necessary properties to point to the new system.
Save and close the customer-configuration.properties file and then restart the gateway for the changes to take effect.

Overriding the Default System Configuration

You can override the default system configuration by modifying the LDAP_INSTALL_DIR/conf/customer-configuration.properties file.

To change the default system properties, locate that property in the configuration.properties file (located in the conf/ folder) and copy it to customer-configuration.properties file and provide a new value.

Note:

Not all properties can be modified and must be done in consultation with Support.

By default, all system configurations are stored in the LDAP_INSTALL_DIR/conf/configuration.properties file. If required, you can override any of these system configurations by copying relevant properties from the LDAP_INSTALL_DIR/conf/configuration.properties file to the LDAP_INSTALL_DIR/conf/customer-configuration.properties file, and then providing a new value.

Note:

Do not edit LDAP_INSTALL_DIR/conf/configuration.properties file directly as it will be overwritten when you upgrade the gateway.

There can be several reasons when you want to override the default system configuration. For example, you may want to change the default passwords for the system backend persistence store or change the listening port when the default collides with another service or when the policies of the company require using a different port.

To change the default system backend passwords, add the following properties to the LDAP_INSTALL_DIR/conf/customer-configuration.properties file:
```
cnctr.proxy.ldapds.adminUserPassword=<admin-password>
cnctr.proxy.ldapds.altAdminUserPassword=<alt-admin-password>
```
In the preceding lines, replace <admin-password> with the password for accessing the system backend. Similarly, replace <alt-admin-password> with the alternative password for accessing the system backend (dc=system,dc=backend)

Not all properties can be modified and must be done in consultation with Support.
To change the default port, add the following properties to the LDAP_INSTALL_DIR/conf/customer-configuration.properties file:
```
system.port=6389
system.ssl_port=7389
```
In the preceding lines, replace 6386 with the desired listening port for LDAP. Similarly, replace 7389 with the desired listening port for LDAPS.

Configuring the Windows Service for the LDAP Gateway

In a Windows environment, the LDAP Gateway can also be installed as a Windows Service. The Windows Service for the LDAP Gateway is installed using the IdentityForge batch file (IDF-Win-Service) that is included in the installation media.

Installing and Configuring the Windows Service for the LDAP Gateway

You can install the Windows Service by running the IDF-Win-Service install command.

To install the Windows service, switch to the LDAP_INSTALL_DIR/win_service directory in a command window and then run the IDF-Win-Service install command. If you encounter any issues with the installation, then uncomment the CG_PATH_TO_JVM variable in theLDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file and ensure that the path is accurate. The following is the code snippet from the LDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file that you need to uncomment:

rem -- 7. Set this if you want to use a different JVM than the one
configured in your registry, or if it is not configured in the windows
registry
rem set CG_PATH_TO_JVM=C:\Program Files\Java\jre7\bin\server\jvm.dll

If you need to modify the Windows service settings, then it is recommended to first uninstall the service, make the modifications, and then reinstall the service until it installs and runs correctly.

After installing the service, you can start, stop, or restart it anytime by using the Windows Services console. Alternatively, run the following command to start the service:

> net start IdentityForgeService

Run the following command to stop the service:

> net stop IdentityForgeService

Uninstalling the Windows Service for the LDAP Gateway

Uninstall the Windows service for the LDAP Gateway by running the IDF-Win-Service remove command.

To uninstall the Windows service, switch to the LDAP_INSTALL_DIR/win_service directory in a command window and then run the IDF-Win-Service remove command.

Configuring Memory Pool Settings

You can configure the memory pool size for the Windows service by setting values for the CG_JVMMS and CG_JVMMX variables in the LDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file.

By default, the CG_JVMMS and CG_JVMMX variables are set to 1024 MB and 2048 MB, respectively. If the LDAP gateway processes a large number of records, then you might encounter the "Out of memory" exception. In such a scenario, you can allocate higher memory for your Windows service by increasing the values of the CG_JVMMS and CG_JVMMX variables.

To do so:

Stop the LDAP gateway Windows service and then uninstall it.
In a text editor, open the LDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file for editing.
Set the JVM minimum and maximum values by modifying values for the following lines:
```
rem Initial memory pool size in MB.
set CG_JVMMS=1024

rem Maximum memory pool size in MB.
set CG_JVMMX=2048
```
Note:
When you receive the "Out of memory" exception, start with increasing the minimum and maximum values to 2048 and 4096, respectively. If the number of records is greater than 40k, then use higher minimum and maximum values.
In the LDAP_INSTALL_DIR/conf/log4j.properties file, set the gateway debug level to ERROR as follows:
```
rootLogger.level = ERROR
```
Install the LDAP gateway Windows service.
Start the LDAP gateway through the Windows service.

Configuring Transformation of the LDAP Gateway Attributes

You can configure transformation of LDAP Gateway attributes in search results by adding relevant entries to the LDAP_INSTALL_DIR/conf/customer-configuration.properties file.

You must include the transformation rule within the LDAP_INSTALL_DIR/conf/customer-configuration.properties file as an inline Jtwig template. For more information about Jtwig templates, see http://jtwig.org/documentation.

For example, you can add a transformation rule to render the value of the sn attribute in the People OU in uppercase. To do so, you must add the following line in the LDAP_INSTALL_DIR/conf/customer-configuration.properties file:

cnctr.tops.tops1.transformation.People.read.sn.template.inline={{sn|upper}}

This entry will render all the letters in the sn attribute in uppercase.

To configure transformation of LDAP gateway attributes:

In a text editor, open the customer-configuration.properties file located in the LDAP_INSTALL_DIR/conf directory.
Add the transformation rule in the following format:
```
cnctr.CONNECTOR_QUALIFIER.INSTANCE_ID.transformation.OU.read.ATTR_NAME.template.inline=JTwig_TEMPLATE
```
In this format, replace:
- CONNECTOR_QUALIFIER with the name of the connection properties file that you created in Setting Connection Properties.
- INSTANCE_ID with the instance ID for your target.
- OU with the organizational unit against which the connector must perform transformation. The supported OU values are People, Groups, Resources, and Datasets.
- ATTR_NAME with the name of the LDAP Gateway attribute in which the transformed value must be stored.
- Jtwig_TEMPLATE with the Jtwig template for transformation.
Save and close the file.

Configuring Multiple Instances of the LDAP Gateway

You can configure and run multiple instances of the LDAP Gateway on the same host by entering unique port values for each instance of the LDAP Gateway.

To do so, install and configure the LDAP Gateway for each instance that you want to run. While installing the LDAP Gateway, ensure that the installation directory is different for each instance of the gateway.

Then, update the default values for each property listed in Table 2-3 so that the value is unique for each instance of the LDAP Gateway that is installed on the host. Suppose you are using the default values in the property files for instance 1, then for instance 2, replace the default value with a unique value for the property. For example, for instance 2, change the default value 6398 of the system system.port property in theLDAP_INSTALL_DIR/conf/customer-configuration.properties file to a unique value such as 8389.

Table 2-3 Property Values To Be Updated for Running Multiple Instances of the LDAP Gateway

Property Name and Location	Property Description	Default Value
The `system.port` property in the`LDAP_INSTALL_DIR/conf/customer-configuration.properties` file	Gateway listening port (LDAP)	`6389`
The `system.ssl_port` property value in the `LDAP_INSTALL_DIR/conf/customer-configuration.properties` file	Gateway listening port (LDAPS)	`7389`
The `ds-cfg-listen-port` property under `dn: cn=LDAP Connection Handler,cn=Connection Handlers,cn=config` in the `LDAP_INSTALL_DIR/dsroot/config/config.ldif` file	OpenDJ listening port (LDAP)	`1389`
Set the value of the `ldap.port` property in the `LDAP_INSTALL_DIR/conf/ldapds.properties` file to the value set for the `ds-cfg-listen-port` property (in the preceding row)	Gateway config to read OpenDJ	`1389`
The `ds-cfg-listen-port` property under `dn: cn=LDAPS Connection Handler,cn=Connection Handlers,cn=config` in the `LDAP_INSTALL_DIR/dsroot/config/config.ldif` file	OpenDJ listening port (LDAPS)	`1636`
The `ds-cfg-listen-port` property under `dn: cn=Administration Connector,cn=config` in the `LDAP_INSTALL_DIR/dsroot/config/config.ldif` file	OpenDJ Administration port	`4444`
The `ds-cfg-replication-server` property under `dn: cn=localhost,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config` in the `LDAP_INSTALL_DIR/dsroot/config/config.ldif` file	OpenDJ Replication Server	`localhost:8989`
The `ds-cfg-replication-port` property value under `dn: cn=replication server,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config` in the `LDAP_INSTALL_DIR/dsroot/config/config.ldif` file	OpenDJ Replication Server Port	`8989`

Encrypting Data

Learn about encryption performed by the LDAP gateway and how to configure it.

Understanding Encryption

The LDAP_INSTALL_DIR/conf/encryption.properties file allows the ability to configure what properties, associated with the connector, must the LDAP Gateway manage as encrypted values.

The LDAP_INSTALL_DIR/conf/encryption.properties file is a common file containing properties of various modules that need to be securely protected. Use this file to define and encrypt any property located in the following files:

connection properties file (created in Setting Connection Properties)
LDAP_INSTALL_DIR/conf/customer-configuration.properties

When the LDAP gateway starts, it uses the encryption.properties file to examine the properties that it must represent in encrypted format.

For example, when the LDAP gateway starts, it reads the following entry from the encryption.properties file:

file.customer-configuration=adminUserPassword,altAdminUserPassword

This entry implies that there exists a properties file called customer-configuration.properties that contains sensitive properties adminUserPassword and altAdminPassword. The LDAP gateway searches for the customer-configuration.properties file, and if found, replaces any clear-text values for the adminUserPassword and altAdminPassword properties with an encrypted version.

Similarly, at start up, the LDAP gateway also reads the following entry from the encryption.properties file:

class.TopsModule=_secretKeyValue_

This entry implies that there exists a connector called TopsModule and its associated properties file (the one created in Setting Connection Properties) contains the sensitive property _secretKeyValue_ . The LDAP gateway searches for this properties file and replaces the clear-text value for the _secretKeyValue_ property with an encrypted value.

Encrypted values within property files are always represented using the ENC(ENCRYPTED_STRING) format. To add or replace an existing encrypted value with a new value, replace the entire encryption string if present (including the ENC(ENCRYPTED_STRING)) with a new clear-text value, and then restart the gateway. Once the gateway restarts, the newly added clear-text value goes through an encryption process with the result being written back out to the property file replacing the original clear-text value.

During the encryption process, the encryption framework that the gateway uses automatically detects the highest level of encryption possible by examining the version of the Java Virtual Machine running, along with any additional encryption libraries that may have been installed alongside the JVM. By default, Java 1.8 supports 128-bit AES encryption and Java 1.7 supports 40-bit AES encryption. You can install additional encryption libraries by BouncyCastle into the JVM allowing for up to 256-bit AES encryption.

The encryption process in the LDAP gateway also allows for automatic migration of encryption values from a lower bit strength to a higher strength as it becomes available. For example, if the gateway is initially deployed on a system running Java 1.7 with 40-bit AES and that system is upgraded to Java 1.8 running 128-bit AES, then upon the next restart of the gateway, all encrypted values remaining at the 40-bit AES level are automatically re-encrypted at the higher 128-bit and stored back out in the property files. This process eliminates the need to manually replace the values in every property file in order to take advantage of the higher bit strength.

The gateway uses the private key located in the LDAP_INSTALL_DIR/conf/idf.properties file for all the encryption and decryption that it performs. The idf.properties file is created in the conf directory when the LDAP gateway is started for the first time. It is recommended that access to this file is restricted.

Note:

Once the gateway is deployed and started for the first time, the value of the autogenerated encryption key in the idf.properties file should not be changed. However, you can change the file name and its location. For example, to store the idf.properties file to a more secure location, the default location (where the gateway resides) can be overwritten and defined as system.idfprops.filepath=ABSOLUTE_PATH_OF_THE_NEW_FILE in the customer-configuration.properties file.

Configuring Encryption

You can configure encryption by editing the encryption.properties file located in the LDAP_INSTALL_DIR/conf/ directory.

By default, the LDAP gateway encrypts the values of:

the adminUserPassword and altAdminPassword properties in the LDAP_INSTALL_DIR/conf/customer-configuration.properties file.
the _secretKeyValue_ property in the connection properties file (created in Setting Connection Properties).

If you want to encrypt additional properties in the customer-configuration.properties file, then you must include them as a comma-separated list in the following property of the encryption.properties file:

file.customer-configuration=adminUserPassword,altAdminUserPassword

For example, if you want to encrypt the schema and suffix properties of the customer-configuration.properties file, then include them in thefile.customer-configuration property of the encryption.properties file as follows:

file.customer-configuration=adminUserPassword,altAdminUserPassword,schema,suffix

If you want to encrypt additional properties in the connection properties file, then include them as a comma-separated list in the following property of the encryption.properties file:

class.TopsModule=_secretKeyValue_

For example, if you want to encrypt the _host_ and _port_ properties of the connection properties file, then include them in the class.TopsModule=_secretKeyValue_ property of the encryption.properties file as follows:

class.TopsModule=_secretKeyValue_,_host_,_port_

If you want to change the values any encrypted properties, then remove the ENC along with the value and then add the new value.

For example, if the value of the adminUserPassword property in the customer-configuration.properties file is encrypted, then from the adminUserPassword=ENC(t8+B0TbafPKyFFf0KoTlAmde82aRnwtf) value, remove ENC(t8+B0TbafPKyFFf0KoTlAmde82aRnwtf) and replace it with the new value, without the prefix ENC. Whenever the gateway is restarted, it automatically overwrites the clear-text value with its encrypted counterpart.

Understanding the Caching Layer

The LDAP gateway features an optional and configurable caching layer, which is a temporary storage area where frequently accessed data is stored for rapid access.

An expiration policy defines the time dependency for the cached resource. For example, the cachingMaxAge parameter specifies the maximum time in minutes when the data is not in sync with the target system. You can pair the caching layer with an incremental reconciliation (to maintain the most recently updated data in the caching layer. This improves the performance of the LDAP gateway. In addition, the caching layer opens the LDAP gateway for more advanced features defined by the LDAPv3 RFC.

Benefits of Using the Caching Layer

Using the caching layer provides the following benefits:

Faster search operations (when the cache is primed)
A unified Base DN for both provisioning and reconciliation data

When paired with an embedded directory server, the caching layer offers these additional benefits:

The ability to perform advanced LDAP search filters against the gateway.
The ability to query an RFC compliant ChangeLog for delta reconciliation.

Note:
In an environment where the items noted above may not be required, you can disable the caching layer.

Considerations for Using the Caching Layer

The LDAP gateway can suffer a performance penalty when all of the following conditions are met:

There is no data in the cache, or the cache is stale based on the configuration.
An LDAP search operation is performed to retrieve the children of an Organizational Unit. For example, the contents of ou=People. Such an LDAP search operation returns only DNs (along with RDN components).
The connector only returns key information when returning a list of objects.

The cachingIterateBehavior property in the LDAP_INSTALL_DIR/conf/configuration.properties file remains set to the default of AUTO and not overwritten within the customer-configuration.properties file.
In such a scenario, an LDAP search operation initially retrieves the list of results, containing only DN and RDN values. The caching layer then iterates through each result, fetching and caching the details from the target system. Finally, the full set of results are returned to Oracle Identity Manager.

To avoid this scenario, it is recommended that you use the caching layer in combination with scheduled reconciliation. With reconciliation setup and the staleness settings configured properly the above conditions will not be met.

How to Enable or Disable the Caching Layer?

The caching layer is enabled by default. To override this default setting or disable the caching layer, copy the cnctr.coreBean.nexus.cachingEnabled property from the LDAP_INSTALL_DIR/conf/configuration.properties file to the LDAP_INSTALL_DIR/conf/customer-configuration.properties file and then set its value to false.

You can enable the caching layer by setting the value of the cnctr.coreBean.nexus.cachingEnabled property in the LDAP_INSTALL_DIR/conf/customer-configuration.properties file to true .

Configuring Scheduled Reconciliation

Scheduled reconciliation allows for establishing a periodic synchronization between the Identity Store associated with the LDAP Gateway and that represented by your target system reachable by way of the connector.

The Scheduled Recon Utility (provided by LDAP_INSTALL_DIR/dist/scheduled-recon.jar) is a tool that ships with the IdentityForge LDAP Gateway. It provides the ability to perform a full recon against a configurable target system, placing the results in the internal identity store of the gateway. This utility provides a basic scheduling service for kicking off the built-in batched reconciliation of the connector on a configurable interval.

An example properties file, scheduled-recon.properties.example file that defines the reconciliation setup and behavior is available in the LDAP_INSTALL_DIR/conf folder. Use this file to configure scheduled reconciliation.

In the LDAP_INSTALL_DIR/conf directory, create a copy of the LDAP_INSTALL_DIR/conf/scheduled-recon.example file and rename it scheduled-recon.properties.
If required, open the LDAP_INSTALL_DIR/conf/scheduled-recon.properties file in a text editor and configure it to meet your requirements.

Run the LDAP_INSTALL_DIR/bin/run-recon.bat file to start the scheduled recon utility.

You can run this batch file with the following options

Argument	Description
`-h`	Use this argument for help.
`-loglevel <level>`	Use this argument to define the logging level. Possible values are: `severe` `warning` `info` `fine` `finer` `finest` Default value is `warning`.
`-logfile <filepath>`	Use this argument to specify the path to the log file.
`-p <properties filepath>`	Use this argument to specify the path to the scheduled-recon.properties file.

The following is the basic command structure for executing this batch file:

…\ldapgateway6\bin>run-recon.bat -loglevel "warning" -logfile <location of the log file> -p "D:\ldapgateway6\conf\scheduled-recon.properties"

About Parsing Grammar Protocol 1.0

Grammar is necessary for properly parsing user and group listings that come into the gateway from the mainframe agent during search requests and reconciliation events.

The grammar represents line-by-line parsing instructions that convert the semi-structured textual data into LDAP attributes and their respective values. Each line (ending in CRLF) of the listing received from the agent can be represented by an individual grammar definition and specified in the grammar file. The grammar file is present in the <conf/parser-grammar/ > folder.

Grammar files with the default grammar are present in the LDAP_INSTALL_DIR/conf/parser-grammars/tops directory. It parses user and group listings that come into the gateway from the mainframe agent during search requests and reconciliation events.

For example, following is the user listing for CA Top Secret:

ACCESSORID = 0518AA NAME = 0518AA
TYPE = USER SIZE = 1024 BYTES
DEPT ACID = DEPTX DEPARTMENT = LARGE-DEPT-TEST
CREATED = 05/19/15 16:50 LAST MOD = 07/29/15 22:02
----------- SEGMENT CICS
OPCLASS = 09
OPIDENT = ABC
OPPRTY = 010
SCTYKEY = 001,005,007,009,011,097
SITRAN = F FACILITY = *ALL*
----------- SEGMENT LU6.2
#APPL = APTRA_VISION_USER|ATM_CONFIG_USER|CS_REVIEW
SET1DISP = AB|AC|AD|AE|
------------ SEGMENT NETVIEW
DOMAINS = 09
INIT CMD = 09
----------- SEGMENT OMVS
ROOT = 09
----------- SEGMENT WORKATTR
ACCOUNT = 123
ADDRESS1 = ADDR 1
ADDRESS2 = ADDR 2
ADDRESS3 = ADDR 3
ADDRESS4 = ADDR 4
BUILDING = BLDG 17
DEPARTMENT = DEPART 1
NAME = NAME
ROOM NUMBER= ROOM B1
XA DATASET = ADBFLE OWNER(00123 21322 )
ACCESS = READ,WRITE
XA DATASET = TDBFLE OWNER(00123 54232 )
ACCESS = READ,DELETE,WRITE
XA DATASET = TDBFLE OWNER(00123 )
PASSWORD = EXPIRES = 06/18/15 INTERVAL = 030

Using the above listing, if you want to parse out the OPCLASS value from the listing and assign it to an LDAP attribute called “opcls”, then you can construct the following <Line> element in the grammar file:

<Line id=”opclassVal” enabled=”yes” sig=”[ ]*OPCLASS = (?<opcls>.*)"/>

The signature attribute (sig) in the Line element above is a regex that represents the rules for pulling out the value and assigning it to an LDAP attribute. Regex named groups are used as the convention for assigning the discovered values to LDAP attributes exposed through the connector.

The following table lists the attributes of a line element. The allowed values for these attributes are yesor no.

String	Mandatory?	Definition
id	Yes	Unique ID that is given to the line definition. Used primarily for internal referencing purposes, such as with the 'dependson' attribute. Values allowed: `any`
enabled	No	Specifies whether the line is eligible for participating in the parsing process. Use this flag to override files (turn off lines). Default value: yes
signature	Yes	Defines the rules for what values are to be extracted for each line of the listing and which LDAP attributes should be assigned the values.
required	No	Defines whether an attribute is required or not. Default to: `yes`
multiline_sig	No	An optional regex expression to define the signature of a follow-on line that could represent whether the value was wrapped around two additional lines in the document. Values allowed: Any valid regex containing attribute matching key and attribute name. Defaults to: `empty value`
repeats	No	Represents whether the line can show up multiple times in the document. If set to `no`, then once the line is found, this Line definition is not evaluated again for the rest of the document. Defaults to: `No`
overflow	No	Represents whether data for an associated attribute can overflow to the next line. In case of an overflow, the final value of an attribute is derived by concatenating all values. Defaults to: `No`
multivalue_parser	No	An optional regex expression that defines how the found values are to be parsed out and turned into a multivalued list, such as using '(\S+)' to parse values that are space delimited. Values Allowed: Any valid regex Defaults to: `empty value`
applyCompositeRef	no	An optional comma-separated list of composite attributes to be built immediately after processing the line. Each value in the comma-separated list must correspond to the "id" attribute of a CompositeAttribute definition.
defaultvalue	No	Defines the default value for an attribute. If this line does not match with any line of input, then this default value will be assigned to attribute.

Customizing Grammar Rules

The grammar file with the default grammar is present in the conf folder. It parses user and group listings that come into the gateway from the mainframe agent during search requests and reconciliation events. You can apply new grammar rules to append to or override rules that come out of the box. To define new grammar rules or override the existing rules, create a grammar file parser-grammars.cust file in the <conf/parser-grammar/ > folder.

You can apply new grammar rules to append to or override rules that are available by default in the LDAP_INSTALL_DIR/conf/parser-grammars/tops directory.

To define new grammar rules or override the existing rules, you must create a custom grammar file (for example, tops_FindAllUsers.cust) in the LDAP_INSTALL_DIR/conf/parser-grammars/tops directory.

Note:

If the Id of the existing attribute matches with the attribute in the grammar line, it overrides the existing grammar definition.
If the Id of the existing attribute does not match with the attribute in the grammar line, it creates a new grammar definition.

Key Considerations

The parser-grammars.cust grammar file must be at the same location where the default grammar files are located (LDAP_INSTALL_DIR/conf/parser-grammars/tops).
The name of the grammar file must be the same except the cust extension.
The name of the grammar file must be the same except the cust extension. For example, if you need to customize the grammar for the LDAP_INSTALL_DIR/conf/parser-grammars/tops/tops_FindAllUsers.xml file, then create a custom grammar file LDAP_INSTALL_DIR/conf/parser-grammars/tops/tops_FindAllPeople.cust.
For the grammar definitions to override, the ID attribute from both the files should match.

Nomenclature of the parsing grammar files

Each grammar file is named for the type of operation and listing it is responsible for parsing.

For example, for CA Top Secret, use the following for user extraction:

tops_FindAllUsers.xml – fetches the IDs of all users.
tops_FindUserById.xml – fetches all the details of a single user (for the given ID).

Overriding default existing grammar definitions

The grammar definitions specified in the grammar file parser-grammars.cust override the default grammar definitions specified in the property files. To enable overriding of the particular line, the ID attribute in the custom provided attribute should match with the default grammar definition.

The grammar definitions specified in the custom grammar file override the default grammar definitions. To enable overriding of a particular line, the ID attribute in the custom provided attribute should match with the default grammar definition.

For example, if the default grammar definition in the property file and the definition specified in the custom grammar file is as shown in the following lines, then the definition is disabled and the line is not parsed.

<Protocol><Lines>
<Line id="elId" enabled="yes" sig="[ ]*ELID[ ]*=[ ]*(?<ELID>.*)"/>
</Lines>/Lines>

<Protocol><Lines>
<Line id="elId" enabled="no" sig="[ ]*ELID[ ]*=[ ]*(?<ELID>.*)"/>
</Lines></Protocol>

New grammar definitions

You can specify new grammar definitions in the custom grammar file that you create. For example, the following grammar definition is used to get values of DEPT_ACID=001 DEPT_NAME=hr.

<Protocol><Lines>
="deptAcid" enabled="yes" sig="[ ]*DEPT_ACID[ ]*=[ ]*(?&lt;deptacid&gt;.*?)
[ ]*DEPT_NAME[ ]*=[ ]*(?&lt;department&gt;.*)" />
</Lines></Protocol>