Chapter 8   Configuring The Universal Connector

The Universal connector is included with Meta-Directory to allow administrators to configure connectors for external data sources not directly supported by Meta-Directory. The following sections are included in this chapter:

• Function of the Universal Connector
• Configuring a Universal Connector Instance
• Restarting a Connector Instance
• Implementing the Configuration

Function of the Universal Connector

---

Meta-Directory includes a generic connector named the Universal Connector (also known as the Universal Text Connector or UTC). When configured, this connector enables data transfer to and from its connector view. It is termed an indirect connector because it creates a view of the external data source in LDAP (connector view) that enables the transfer of data to and from the proprietary data sources.

Sun ONE provides the Universal Text Parser (UTP), a suite of scripts, to help the Meta-Directory administrator configure connectors for manipulating data from external data sources whose data can be exported or dumped into a text file. This enables the administrator to synchronize data to a meta view using a data source not specifically configured for Meta-Directory. Sun ONE supports data or text files in the following text file formats:

• CSV (comma-separated values)
• NVP (name-value pairs)
• LDIF

The LDIF files produced by the UTC are not fully conformant with RFC 2849 Please consult the appendix headed Data Conversion at the end of this guide on how to produce compliant RFC 2849 LDIF files

The NT Domain and Active Directory connectors are special cases of the UTC provided by Sun ONE for a specific external data source, NT Domain and Active Directory respectively. When you create an instance of either of these connectors, the UTC base is automatically installed. The interface for these connectors is very similar to that of the UTC.

Besides their dependence on the Universal Connector, the UTP, NT Domain Connector, and Active Directory Connector each require their own special configuration setup. To configure the UTP, see "Configuring the Universal Text Parser." To configure the NT Domain Connector, see "Configuring the NT Domain Connector." To configure the Active Directory Connector, see "Configuring the Active Directory Connector."

Before configuring one or more of these connectors, it is recommended that you first configure the Universal Connector, as documented in the following sections.

Creating a Universal Connector Instance

---

1. From the Sun ONE Console window, right-click Server Group. A context menu appears.





2. Select Create Instance Of, and select the desired connector. The New Instance Creation dialog box appears.





Provide input for the following data fields:

View Name	Enter a name of any length that more fully describes the View ID. The default is the View ID.
View ID	Enter up to five characters to represent the view ID. The default is CVn.
View Base DN	Enter the subtree DN where this view is located. The default is o=CVx, where x is the next successive integer following the last instance created.
Data Server URL	From the drop-down list, select the data server from which the new instance should be created. You can also type in a data server URL.
Data Server Bind DN	Enter a DN to be bound to the data server URL for access rights to the subtree. The default is cn=Directory Manager.
Data Server Bind Password	Enter the password associated with the data server bind DN.
Perl Script Absolute Path	This field only appears if you are creating an instance of the Universal Text Connector. Enter a path and file name if you want Meta-Directory to extract the Perl script and then parse a third-party database. Instead of entering the information here, you can alternatively supply the path and file name in the Script tab window. For information on this procedure, see "To include scripts for the Universal Text Connector".

3. Click OK in the New Instance Creation dialog box. If the changelog is not enabled, the following message appears:





If you click Enable Changelog NOW, the Enable Changelog dialog box appears.





1. Enter a directory where you want to store the changelog. For Solaris systems, make sure you change the directory permission mode of the file to allow the console to create the changelog directory. It is recommended that you issue the following command against the directory where you want to create the changelog directory:

chmod -R 777

2. Either accept the changelog suffix default or provide your own.
3. Click OK. A message appears reminding you to restart the Directory Server.
4. The Load Schema appears whenever you add a new view if the base entry does not exist. If the schema already exists, you do not need to click Yes. If you click Yes, a dialog box appears that informs you of progress while the installer is loading the schema. The message "Instance Creation Succeeded" appears after the instance has been created.
5. Restart the Directory Server:

1. From the Sun ONE Console, select the Directory Server object, then right-click.
2. From the context menu, select Stop Server. Click Yes in the Stop Server message box. A message appears stating that the Directory Server has been stopped.
3. Select the Directory Server object again, then right-click.
4. From the context menu, select Start Server. A message appears stating that the Directory Server has been started.

To remove a connector instance

1. From the Sun ONE Console, highlight the instance you want to delete, then right-click. A context menu appears.
2. Select Remove Server and click yes in the message box. Another message box appears.

• If you click Yes, the connector view is removed. If it is a participating view of the join engine, it will also be removed. This does not remove connector view data from the LDAP DIT, however.
• If you click No, the connector instance is removed, but the connector view will remain.

Configuring a Universal Connector Instance

---

You can use the windows associated with the instance to perform the following tasks:

• Specify how updates are handled
• Configure the schedule from and to connector views
• To configure attributes for log files
• Add external attributes for connectors
• Include scripts

The examples for the procedures below apply to the Universal Text Connector. This connector has an extra window, called Script, that is not present when you configure the NT Domain Connector or Active Directory Connector.

To specify how updates are handled

1. Click on the instance you want to configure. The General tab window appears. The Name and Connector View Location fields are read-only. You specified this information when you created the instance.





2. Select the desired attribute flow, filter, and default values from the drop-down lists. You configured these values in "Connectors and Connector Rules."
3. Indicate how you want to send and receive updates by selecting the appropriate radio button, then clicking Save before continuing. The updates can be modifications, deletions, and additions to the external directory and/or to the connector view.

To configure the schedule from and to connector views

1. Click the Schedule tab. The Schedule window appears.





2. Select either To Connector View or From Connector View, and indicate in the text boxes when updates should be sent.

For every scheduled synch cycle, the Universal Connector launches the accessor to create a dump file of all the external directory entries. If the accessor did not succeed in creating the dump file and it is empty, the Universal Connector thinks that all the entries from the external directory are deleted.

Consequently, the Universal Connector then attempts to delete the external directory-owned entries from the connector view. However, after restarting the server and restarting the Universal UTC, the accessor launches and a new dump file is created. All the external directory-owned entries are then resynchronized back to the connector view.

3. Optional: Alternatively, you can manually provide settings in a tabular format. To do so, click Advanced. The Advanced Schedule Options dialog box appears.





Provide values for the following fields:

Second Specifier	Enter a value from 0 to 59.
Minute Specifier	Enter a value from 0 to 59.
Hour Specifier	Enter a value from 0 to 23.
Day Specifier	Enter a value from 1 to 31.
Month Specifier	Enter a value from 1 to 12.
Day of the Week Specifier	Enter a value from 0 to 6, where 0 is Sunday and 6 is Saturday.

You can use either a single number or an expression as described below.

Expression	Definition
*	Matches any value.
*/step	Matches any value in steps. For example, */2 matches 0,2,4,6 ... up to the maximum allowed value for values that start with zero, or it matches 1,3,5,7 ... up to the maximum value allowed.
x-y	Specifies a range where: Both x and y are greater than or equal to the minimum allowed value. y is less than or equal to the maximum allowed value. x is less than y. The expression matches any value in the range.
x-y/step	Specifies a range as above, but with a step value that is not necessarily 1.
x	Specifies a single number within the allowed range.
x/step	Matches any value starting at x and then at x + step, x + 2*step, and so forth.
x,y,z...	Specifies a comma-separated list of values.
x-y,z-q	Specifies a comma-separated list of ranges.
Lists can also contain both single values and ranges such as 1,2,5-7,10/5. The scheduler operates once every second, so the finest granularity occurs every second.

4. Click OK to return to the Schedule window, then click Save before continuing.

To configure attributes for log files

1. Click the Log tab. The Log window appears.





2. Provide information for the following fields:

Log File Location	Specifies the directory in which the log files reside. To specify a directory other than the default, enter the full path name of the directory from the system where the connector is installed.
Prefix for Log File Name	Specifies the name you want to precede the log file of the form: name-yyyymmdd-nn.log For example, if you chose delta as the prefix, it would appear as shown in the following example: delta-20010521-01.log
Maximum Size of Each File	Specifies the maximum size of the log file. After the file reaches this size, the service creates a new log file. The default is 4096 KB.
Maximum Disk usage	Specifies the maximum disk usage set aside for logging. When the maximum disk usage is reached, the oldest log file is deleted. By default, the maximum disk usage is 100 KB. The maximum available disk space must be at least twice the size of the maximum log file size, because the service always stores one backup log file. If the maximum available disk space is less than twice the maximum log file size, the new file cannot reach its maximum size.
Minimum Reserved Free Space	The service reserves disk space to use for log file storage. By default, the service reserves a minimum of 5000 KB of space.
New Log File Every	Determines the length of time that a log file should record the service's activities before creating a new log file. If the maximum size of the log file is reached first, a new log file is created. This value must be less than the value in the Delete Log Files Older Than field.
Delete Log Files Older Than	Determines when the service should automatically delete old log files. This value must be greater than the value in the New Log File Every field.
Flush Buffered Log Data to Disk at	Determines when the log data buffered in memory is to be flushed to the disk. If you enter 0 in this field, every message is flushed. Although this is helpful for debugging, a performance degradation will occur.
Log Level	The choices are Off, Normal, and Debug. Off suppresses logging. Normal logs minimal information. Maximum disk space may be small, and new files are created infrequently. Debug logs maximum information. Maximum disk space is large, and new files may be created frequently. You can switch modes without restarting the connector.
Verbosity	Specifies how much information is logged for a given module. The modules are functional areas of the Join Engine and connector, and are created during installation. Choose a verbosity level of 0 - 3 by selecting a module, then clicking on its corresponding level until you have selected the desired number. The higher the number, the greater the amount of information displayed.

3. Click Save.

To add external attributes for connectors

You can create a list of attributes that you want to flow from the external data source for UTC-based connectors. For example, in a task.cfg file for the Universal Text Parser, you might have the following line format:

LineFormat=ALTEREGO:uid,REALNAME:cn,LASTNAME:sn

Since ALTEREGO, REALNAME, and LASTNAME are not LDAP attribute names, you would want to declare uid, cn, and sn as attribute names, which will correspond to the schema defined in the directory DIT.

You can store the external attributes as described in the following procedure.

1. Click the Attributes tab. The Attributes window appears.





2. Click New. A blank field appears below the Attribute label.
3. Click within the blank field, then type the name of an external attribute you want to map to an internal attribute.
4. Repeat the steps above to add other attributes, then click Save. The order of the attributes you create is unimportant. After you click Save, they are sorted when you refresh the console.
5. See "To Configure an Attribute Flow Rule" to map the external attributes with connector view attributes.

To include scripts for the Universal Text Connector

You can provide special settings for the Universal Text Connector specific to the source directory on which it operates. This is handled by a plug-in tab called Script.

1. Click the Script tab. The Script window appears.





2. Specify a path and file name in the field, or click Browse to select the path. Meta-Directory will extract the Perl script and parse a third-party database. Do not specify a package name in the script.

The Browse button is enabled and error checking implemented only if the Universal Connector is installed on the same system as the console. If the Browse button is disabled, you need to type in the absolute path for the script where the connection is installed.

3. Click Save.

Restarting a Connector Instance

---

You must restart the connector instance to activate your configuration. Both instance-specific and shared configurations will not become effective for a given instance until you have restarted the instance.

1. Stop the connector by right-clicking on the connector instance. A context menu appears.
2. Select Stop Server. A message appears stating that the stop command has been issued to the component.
3. Start the connector by right-clicking on the connector instance. A context menu appears.
4. Select Start Server. A message appears stating that the start command has been issued to the component.

Implementing the Configuration

---

After you start the join engine and enable the connector view, your data can flow to the meta view. The following sections provide procedures for doing these tasks.

Starting the Join Engine

Before you start the join engine, ensure that you have already enabled the changelog in the Directory Server configuration.

To start the join engine

1. Select the join-engine object from the navigation tree and right-click. A context menu appears.
2. Select Start Server. A message appears stating that the server has been started.

You can also start the server from the Sun ONE Console. To do this, select the Join Engine object and right-click. Select Start Server from the context menu.

Enabling the Connector View

1. From the Sun ONE Meta-Directory window, click on the Status tab.
2. Click on the Join Engine object. The Operations tab window appears.





3. Select the participating view you want to enable.
4. Select Enable from the Operation list menu, then click Submit Request.

This option disables the Traverse drop-down menu. You can only enable the participating view if the configuration for setting up the view is valid. Any error in the configuration automatically changes the view to a disable status.

5. Select Refresh from the Operation List Window, then select either Meta View or Connector View from the Traverse menu list.
6. Click Start.

Refreshing the View

You can optionally refresh the view if you want to observe updates immediately and bypass the regularly scheduled refresh synchronization. Note that after any type of refresh, you might see a "None" group in the meta view Contents or connector view Contents, particularly with non Primary Domain Controller systems. "None" is a valid group in Windows NT.

1. From the SUn ONE Meta-Directory window, click on the Status tab.
2. Click on the NT Domain connector instance object. The Operations tab window appears. The only operation available is Refresh.





3. In the "Updates to the" drop-down list, select either External Directory or Connector.
4. Click Start. The Modify Task Status dialog box appears.

If you are refreshing the external directory, the following version of the box appears:





You must select a filter for the second and third options. Only filters configured for the "NoSubtreesExcept" option are displayed when you click Select Filter, not filters configured for the "AllSubtreesExcept" option.