Sun ONE Meta-Directory 5.1.1 Administration Guide |
Chapter 4
Configuring the Universal ConnectorUniversal Connector helps integrate Meta-Directory with external data sources that have data stored in text formats.
The following sections are included in this chapter:
About Universal ConnectorMeta-Directory includes a generic connector named the Universal Connector (Universal Text Connector or UTC). This connector allows data transfer (bi-directional) between external data source and UTC Connector View. It is an indirect connector because it creates a view of the external data source in its Connector View that enables the transfer of data to and from the proprietary data sources. The Connector View can be considered a working area that is only used by the UTC and Join Engine components. Typically, other LDAP compliant applications would not require access to the Connector View.
The Universal Text Parser (UTP) is a component of the Universal Connector that is considered a collection of perl scripts that can be configured. You can configure the UTP to parse and manipulate data from the external data source. UTP is also used to write data from the Connector View to an external text file. Once the external data is loaded to the Connector View, the Join Engine synchronizes the data to Meta View. UTP includes pre-configured task.cfg templates to support data or text files in these formats:
The LDIF files (produced by the UTC) does not completely conform with RFC 2849. See Appendix D, "Data Conversion" on how to produce fully compliant RFC 2849 LDIF files.
The Meta-Directory NT Domain and Active Directory connectors are special implementations of the UTC for specific external data sources - NT Domain and Active Directory respectively. When you create an instance of one of these connectors, the UTC base is automatically installed.
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 Chapter 5, "Configuring the Universal Text Parser." To configure the NT Domain Connector, see Chapter 6, "Configuring the NT Domain Connector." To configure the Active Directory Connector, see Chapter 7, "Configuring the Active Directory Connector."
Before configuring one or more of these connectors, it is recommended that you first configure the Universal Connector, as discussed in the following sections.
Creating the Universal Connector Instance
- From the Sun ONE Console, right-click Server Group.
- Click Create Instance Of, and then click the appropriate connector. The ‘New Instance Creation’ dialog box displays.
- Enter appropriate values in the fields as described:
Table 4-1 Description of the options and the tasks to perform for each option
Field
Do This
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 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 is displayed if you are creating an instance of the Universal Text Connector.
Enter a path and file name to locate the Perl script (default, template.pl) that parses the third-party database. You can alternatively enter the path and file name in the Script tab window, once the UTC instance has been created. For information on this procedure, see "To include scripts for the Universal Text Connector".
- Once complete, click OK. If the changelog is not enabled, this message displays:
If you click Enable Changelog NOW, the ‘Enable Changelog’ dialog box displays.
- Enter a directory 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 execute the following command against the directory to create the changelog directory:
chmod -R 777- Either accept the changelog suffix default or provide an appropriate value.
- Click OK. A message displays suggesting to restart the Directory Server.
- The Load Schema is displayed when 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 displays that informs you of progress while the installer is loading the schema. The message “Instance Creation Succeeded” displays after the instance has been created.
- Restart the Directory Server:
- From the Sun ONE Console, select the Directory Server object, and then right-click.
- Click Stop Server. Click Yes when the ‘Stop Server’ message is displayed. A confirmation message displays once the Directory Server is stopped.
- Select the Directory Server object again, and then right-click.
- Click Start Server. A confirmation message displays once the Directory Server is started.
To remove a connector instance
Configuring Universal Connector InstancePerform the following tasks to configure a Universal Connector instance:
To specify how updates are processed
- Click the instance to configure. The ‘General’ window displays.
- Select the appropriate attribute flow, filter, and default values from the list boxes. You configured these values in Chapter 3, "Connectors and Connector Rules."
- Indicate how you want to send and receive updates by selecting the appropriate option, and then click Save before you continue. 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
- Select the Schedule tab. The ‘Schedule’ window displays:
- Select either ‘To Connector View’ or ‘From Connector View’ and indicate in the text boxes when updates should be sent.
For every scheduled synchronization cycle, the Universal Connector starts 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 is empty, the Universal Connector assumes that all entries from the external directory are deleted.
Thus, the Universal Connector then attempts to delete the external owned entries from the Connector View. However, after restarting the server and UTC, the accessor starts and a new dump file is created. All the external owned entries are then synchronized back to the Connector View.
Optional: Alternatively, you can manually enter settings. To do this, click Advanced. The ‘Advanced Schedule Options’ dialog box displays. Enter appropriate values in the following fields:
Sample data in different fields and their interpretation:
Example 1:
second specifier:12/30
minute specifier:5/15
hour specifier :7-9
day specifier: *
month specifier:*
day of week specifier:0-6Schedule starts at 5 minutes 12 seconds past 7 and runs every 30 seconds. Schedule ends at 9. This schedule runs every day. As both seconds and minute frequency were specified minute frequency was ignored.
Example 2:
second specifier:*
minute specifier:*/45
hour specifier :7-10
day specifier: *
month specifier:*
day of week specifier:0-6Schedule starts at 0 minutes past 7 and runs every 45 minutes till 10 every day. Schedule runs at 7:00, 7:45, 8:30, 9:15
Example 3:
second specifier:*
minute specifier:*/30
hour specifier :7-9, 15-17
day specifier:*
month specifier:*
day of week specifier:0Schedule runs at 7:00, 7:30, 8:00, 8:30,15:00,15:30,16:00,16:30 every sunday.
Example 4:
second specifier: *
minute specifier:10/15
hour specifier :22-3
day specifier:*
month specifier:*
day of week specifier:0-6Schedule runs at 22:10, 22:25,22:40,22:55,23:10,23:25,23:40,23:55 every day. 22-3 in hour range was rounded off to 22-23:59 as x > y in the hour range.
- Click OK, and then click Save to complete.
To configure attributes for log files
- Select the Log tab. The ‘Log’ window displays:
- Enter appropriate values in the fields as described:
- Once complete, click Save.
To add external attributes for connectors
You can create a list of attributes that must 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 corresponds to the schema defined in the directory DIT.
You can store the external attributes as described:
- Select the Attributes tab. The ‘Attributes’ window displays.
- Click New.
- Type the name of an external attribute to map to an internal attribute.
- Perform Step 1 through Step 3 to add other attributes, and then click Save. The order of the attributes you create is not important. After you click Save, it is sorted when the console is refreshed.
- To map the external attributes with Connector View attributes, see "To configure an attribute flow rule (to achieve attribute-level granularity)".
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.
- Select the Script tab. The ‘Script’ window displays.
- Specify a path and file name in the field or click Browse to located 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 option is enabled and error checking implemented only if the Universal Connector is installed on the same system as the console. If the Browse option is disabled, you need to type the complete path for the script where the connector is installed.
- Once complete, click Save.
Restarting the Connector InstanceYou must restart the connector instance to activate the configuration. Both instance-specific and shared configurations does not become effective for a given instance until the instance is restarted.
About Directory to External Flow OperationDetails on the manual and scheduled refresh operations of Connector View to external data source is described in Table 4-4. It also contains a summary of the changes that occur in different scenarios of refresh opearation. Factors such as: Attributed Level Granularity (ALG) and Entry Level Granularity (ELG), with or without filters are also considered. For more details on ALG and ELG, see "About Granularity and Ownership".
Table 4-4 Directory to External Flow
Operation in Connector View 1
Manual Refresh (ALG) without Filter 2
Manual Refresh (ALG) with Filter
Manual Refresh (ELG) without Filter
Manual Refresh (ELG) with Filter
Schedule Synchronization (ALG) 3
Schedule Synchronization (ELG)
Add Entry
Entry in out file with ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix.
Delete Connector View owned entry (legal)
Entry in out file with DELETE operation as a line prefix.
No entry in out file. However, the DELETE entry appears in the out file on the next Connector View to external. scheduled synchronization or manual refresh without filter.
Entry in out file with DELETE operation as a line prefix.
No entry in out file. However, the DELETE entry appears in the out file on the next Connector View to external scheduled synchronization or manual refresh without filter.
Entry in out file with DELETE operation as a line prefix.
Entry in out file with DELETE operation as a line prefix.
Delete external owned entry (Illegal)
No entry in out file. 4
No entry in out file. 4.
No entry in out file. 4.
No entry in out file. 4.
No entry in out file, but entry is added back in the next external to Connector View scheduled synchronization.
No entry in out file, but entry is added back in the next exteranl to Connector View scheduled synchronization.
Modify Connector View owned entry (legal)
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
Modify external owned entry (Illegal)
Entry in out file with MODIFY operation as a line prefix.
Entry in out file with MODIFY operation as a line prefix.
No entry in the out file.
No entry in the out file.
Entry in out file with MODIFY operation as a line prefix.
No entry in the out file.
Rename Connector View owned entry (legal)
Entry in out file with DELETE and ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix only. However, the DELETE entry appears in the out file on the next Connector View to external scheduled synchronization or manual refresh without filter.
Entry in out file with DELETE and ADD operation as a line prefix.
Entry in out file with ADD operation as a line prefix only. However, the DELETE entry appears in the out file on the next Connector View to external scheduled synchronization or manual refresh without filter.
Entry in out file with DELETE and ADD operation as a line prefix.
Entry in out file with DELETE and ADD operation as a line prefix.
Rename external owned entry (Illegal)
Not supported.
Not supported.
Not supported.
Not supported.
Not supported.
Not supported.
1When using bi-direction synchronization, the contents of the out file depends on the contents on the input file. Thus, using this connector in bi-direction synchronization requires understanding the functional aspects in detail.
2Any manual refresh operation, the out file also displays all unmodified Connector View owned entries with MODIFY operation as a line prefix.
3Due to differences in DCNS cycle and scheduled refresh cycle, if the UTC Connector shuts down, all changes made at Connector View before the shutdown (but processed by DCNS) does not flow to the out file; although the Active Directory connector has started successfully again.
4In these cases, the entry will not be added back in the Connector View. It is important to note that an external owned entry will never get deleted in the Connector View in the first place. Because an illegal delete will actually be initiated at the Meta View, as the Connector View is internal staging point of the Meta-Directory system. When this illegal delete occurs, the Join Engine will add back the entry to the Meta View, since the Join Engine level owner of the entry is the Connector View. In any case, when the next Connector View to external scheduled synchronization happens, the illegal delete will be picked up and marked for ’Add Back’ to the Connector View, upon the subsequent external to Connector View scheduled synchronization. Lastly, as a final backup of the entry not getting lost in the Connector View, the next external to Connector View manual refresh will add the entry back to the Connector View.
Implementing the ConfigurationOnce the Join Engine is started and the Participating (Connector) View enabled, the data then flows to the Meta View. These sections discusses the procedures to perform this task.
Before you start the Join Engine, ensure that you have enabled the retro-changelog in the Directory Server.
To start the Join Engine
To enable the Connector View
- From the Meta-Directory window, select the Status tab.
- Click the Join Engine object. The ‘Operations’ window displays.
- Select the Participating View to enable.
- Select Enable from the Operation list, and then click Submit Request.
This option disables the 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.
- Select Refresh from the Operation list box, and then select either Meta View or Connector View from the list.
- Once complete, click Start.
Refreshing the View
You can optionally refresh the view to view 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.
- From the Meta-Directory window, select the Status tab.
- Click the NT Domain connector instance object. The ‘Operations’ window displays. The only operation available is Refresh.
- From the ‘Updates to the’ list box, select either External Directory or Connector.
- Click Start. The ‘Modify Task Status’ dialog box displays.
You must select a filter for the second and third option. Only filters configured for the ‘NoSubtreesExcept’ option are displayed when you click ‘Select Filter’, not filters configured for the ‘AllSubtreesExcept’ option.