Sun logo      Previous      Contents      Index      Next     

Sun ONE Meta-Directory 5.1.1 Administration Guide

Chapter 4
Configuring the Universal Connector

Universal 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 Connector

Meta-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

  1. From the Sun ONE Console, right-click Server Group.
  2. Click Create Instance Of, and then click the appropriate connector. The ‘New Instance Creation’ dialog box displays.
    Figure shows the ’New Instance Creation’ dialog box.
  3. Enter appropriate values in the fields as described:
  4. 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".

  5. Once complete, click OK. If the changelog is not enabled, this message displays:
    Figure shows the ’Enabling changelog...’ dialog box.
  6. If you click Enable Changelog NOW, the ‘Enable Changelog’ dialog box displays.

    1. 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
    2. Either accept the changelog suffix default or provide an appropriate value.
    3. Click OK. A message displays suggesting to restart the Directory Server.
  7. 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.
  8. Restart the Directory Server:
    1. From the Sun ONE Console, select the Directory Server object, and then right-click.
    2. Click Stop Server. Click Yes when the ‘Stop Server’ message is displayed. A confirmation message displays once the Directory Server is stopped.
    3. Select the Directory Server object again, and then right-click.
    4. Click Start Server. A confirmation message displays once the Directory Server is started.
    To remove a connector instance
  1. From the Sun ONE Console, select the instance to delete, and then right-click.
  2. Click Remove Server. Click Yes when prompted. 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.)
    • If you click No, the connector instance is removed, but the Connector View remains.


Configuring Universal Connector Instance

Perform the following tasks to configure a Universal Connector instance:

    To specify how updates are processed
  1. Click the instance to configure. The ‘General’ window displays.
    Figure displays the contents of the ’General’ window.
  2. Select the appropriate attribute flow, filter, and default values from the list boxes. You configured these values in Chapter 3, "Connectors and Connector Rules."
  3. 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
  1. Select the Schedule tab. The ‘Schedule’ window displays:
    Figure displays the contents of the ’Schedule’ window.
  2. Select either ‘To Connector View’ or ‘From Connector View’ and indicate in the text boxes when updates should be sent.
  3. 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:

    Table 4-2  Description of the options and the tasks to perform for each option

    Field

    Value

    Example

    Second Specifier

    Accepts data in x/y format. x represents the ‘second’ at which schedule should start.

    x is interpreted as ‘start x seconds past minute’.

    y represents the repeat frequency of schedule in seconds.

    • ’*’ is allowed as a valid value for either x or y.
    • ’*’ in x is interpreted as ‘start at 0 seconds past minute’.
    • ’*’ in y is interpreted as repeat every second.
      Value of x should be between 0 and 59.
    • y can have any numeric value.

    2/15 means start 2 seconds past the minute and run every 15 seconds.

    */15 means start 0 seconds past the minute and run every 15 seconds.

    2/* means start 2 seconds past the minute and run every second.

    Minute Specifier

    Accepts data in x/y format. x represents the’ minute’ at which schedule should start. x is interpreted as ‘start x minutes past the hour.

    y represents the repeat frequency of schedule in minutes.

    • ‘*’ is allowed as a valid value for either x or y.
    • ‘*’ in x is interpreted as ‘start at 0 minutes past the hour.
    • ‘*’ in y is interpreted as repeat every minute.
    • Value of x should be between 0 and 59.
    • y can have any numeric value.

    Frequency of the schedule should be specified either in second specifier or minute specifier. If frequency is entered in both seconds and minute specifier, seconds frequency takes precedence over minutes frequency and minutes frequency is ignored.

    2/15 means start 2 minutes past the hour and run every 15 minutes.

    */15 means start 0 minute past the hour and run every 15 minutes.

    2/* means start 2 minutes past the hour and run every minute.

    Hour Specifier

    Accepts data in a regular expression format.
    Valid numeric values that can be entered are 0 to 23.
    Valid data formats are

    • x
    • x-y
    • x-y/z
    • a-b, x-y
    • x,y,z

    Interpretation of data in various formats:

    x: Is interpreted as run at x hour.

    ‘*’ in x is interpreted as 0-23.

    x-y: Is interpreted as begin at x hours and end at y hours.

    • ‘*’ is not a valid value in a range.
    • If x > y in hour range then the effective range is considered as x-23:59.
      that is, start at x hour and run till 23 hour 59 minutes.

    x-y/z: Is interpreted as begin at x hours and end at y hours at z step.
    This means valid hours to run are x, x+z, x+(2*z), x+(3*z).... till x+(n*z) < y.

    a-b, x-y: Is interpreted as multiple ranges.
    Multiple hour ranges can be specified in the hour specifier. Ranges specified should be in ascending order.

    x,y,z: Is interpreted as run at x, y, and z hours.

    Any of the above combinations can be used in hour specifier.

    Sample:

    9-4 is interpreted as 19-23:59

    Sample:

    10-16/2 is interpreted as run at 10, 12, 14 hours.

    Sample:

    8-10, 12-18, 20-22 is a valid schedule.
    8-10, 2-3, 12-18 is invalid as the ranges are not in ascending order.

    Sample:

    2,10-12,16-22/3 is a valid value in hour specifier.

    Day Specifier

    Accepts data in a regular expression format.
    Valid numeric values that can be entered are 1 to 31.

    Valid data formats are

    • x
    • x-y
    • x-y/z
    • a-b, x-y
    • x,y,z

    Interpretation of data in various formats:

    x: Is interpreted as run on x day.

    ’*’ in x is interpreted as 1-31.

    x-y: Is interpreted as run between x and y days.

    • ‘*’ is not a valid value in a range.
    • x should be less than y in the range.
      x-y/z: Is interpreted as begin on x day and end on y day every z days.
      This means valid days to run are x, x+z, x+(2*z), x+(3*z).... till x+(n*z) < y.

    a-b, x-y: Is interpreted as multiple ranges.
    Multiple day ranges can be specified in the day specifier. Ranges specified
    should be in ascending order.

    x,y,z: Is interpreted as run on x,y and z days.

    Any of the above combinations can be used in day specifier.

    10-16/2 means run on 10th, 12th, 14th, 16th day of the month.

    Sample:

    8-10, 12-18, 20-22 is a valid schedule.

    8-10, 2-3, 12-18 is invalid as the ranges are not in ascending order.

    Sample:

    2,10-12,16-22/3 is a valid value in day specifier.

    Month Specifier

    Accepts data in a regular expression format.

    Valid numeric values that can be entered are 1 to 12.

    Valid data formats are

    • x
    • x-y
    • x-y/z
    • a-b, x-y
    • x,y,z

    Interpretation of data in various formats:

    x: Is interpreted as run in x month.

    ’*’ in x is interpreted as 1-12.

    x-y: Is interpreted as run between x and y months.

    • ‘*’ is not a valid value in a range.
      x should be less than y in the range.
    • x-y/z: Is interpreted as begin in x month and end in y month every z months.
      This means valid months to run are x, x+z, x+(2*z), x+(3*z).... till x+(n*z) < y.

    a-b, x-y: Is interpreted as multiple ranges.
    Multiple month ranges can be specified in the month specifier.
    Ranges specified should be in ascending order.

    x,y,z: Is interpreted as run in x,y and z months.

    Any of the above combinations can be used in day specifier.

    Sample:

    1-8/2 means run in 1,3,5,7 months. (Run in Jan, Mar, May, Jul)

    Sample:

    1-2,6-9 is a valid schedule.
    6-9, 1-2 is invalid as the ranges are not in ascending order.

    Day of the Week Specifier

    Accepts data in a regular expression format. Valid numeric values that can be entered are 0 to 6. 0 stands for sunday. 6 stands for saturday.

    Valid data formats are:

    • x
    • x-y
    • x-y/z
    • a-b, x-y
    • x, y, z

    Interpretation of data in various formats:

    x: Is interpreted as run on x weekday.
    ’*’ in x is interpreted as 0-6.

    x-y: Is interpreted as run between x and y weekdays.

    • ’*’ is not a valid value in a range.
    • x should be less than y in the range.

    x-y/z: Is interpreted as begin on x weekday and end on y weekday every z days.
    This means valid weekdays to run are x, x+z, x+(2*z), x+(3*z).... till x+(n*z) < y.

    a-b, x-y: Is interpreted as multiple ranges.
    Multiple weekday ranges can be specified in the day of week specifier. Ranges specified should be in ascending order.

    x, y, z: Is interpreted as run on x,y and z weekdays.

    Any of the above combinations can be used in weekday specifier.

    Sample:

    0-5/2 means run on 0,2,4 weekdays. (Run on sunday, tuesday, thursday)

    Sample:

    0-2,4-6 is a valid schedule.

    4-6, 1-2 is invalid as the ranges are not in ascending order.

    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-6

    Schedule 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-6

    Schedule 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:0

    Schedule 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-6

    Schedule 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.

  4. Click OK, and then click Save to complete.
    To configure attributes for log files
  1. Select the Log tab. The ‘Log’ window displays:
    Figure displays the contents of the ’Log’ window.
  2. Enter appropriate values in the fields as described:
  3. Table 4-3  Description of the options and the tasks to perform for each option

    Field

    Do This

    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 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 value is 8192 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 15000 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 4096 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. The default value is 1 day.

    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. The default value is 7 days.

    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. The default value is 15 seconds

    Log Level

    Select Off, Normal, or 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.

  4. 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:

  1. Select the Attributes tab. The ‘Attributes’ window displays.
  2. Click New.
  3. Type the name of an external attribute to map to an internal attribute.
  4. 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.
  5. 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.

  1. Select the Script tab. The ‘Script’ window displays.
  2. 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.
  3. 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.

  4. Once complete, click Save.


Restarting the Connector Instance

You 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.

  1. Right-click the connector instance, and click Stop Server. A confirmation message displays once the instance is stopped.
  2. Right-click the connector instance again, and click Start Server. A confirmation message displays once the instance is started.


About Directory to External Flow Operation

Details 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 Configuration

Once 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
  1. Select the Join Engine object from the navigation tree and right-click.
  2. Click Start Server. A confirmation message displays.
  3. You can also start the server from the Sun ONE Console. To do this, select the Join Engine object and right-click. Click Start Server.

    To enable the Connector View
  1. From the Meta-Directory window, select the Status tab.
  2. Click the Join Engine object. The ‘Operations’ window displays.
  3. Select the Participating View to enable.
  4. Select Enable from the Operation list, and then click Submit Request.
  5. 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.

  6. Select Refresh from the Operation list box, and then select either Meta View or Connector View from the list.
  7. 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.

  1. From the Meta-Directory window, select the Status tab.
  2. Click the NT Domain connector instance object. The ‘Operations’ window displays. The only operation available is Refresh.
  3. From the ‘Updates to the’ list box, select either External Directory or Connector.
  4. Click Start. The ‘Modify Task Status’ dialog box displays.
  5. 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.



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.