|Previous Contents Index Next|
|iPlanet Meta-Directory Configuration and Administration Guide|
Appendix C Troubleshooting Meta-Directory
This appendix describes troubleshooting techniques for Meta-Directory. In addition, it addresses some common configuration problems and how they can be fixed. This chapter contains the following sections:
Verifying End-to-End Flow
Verifying End-to-End Flow
To determine whether a Meta-Directory event occurred as expected, use the Meta-Directory console to systematically verify the attribute flow from the meta view to the connector view and then to the external data source. If the window is not available to verify that an entry has been modified, added, or deleted, invoke the related view in Netscape Communicator by typing the entry's LDAP URL in the location window and pressing Return. You can also use any LDAP viewer application.
Viewing Link Information
The attributes of an entry indicate whether the Meta-Directory link information between the connector view and the meta view was added correctly. Note that the join engine adds several attributes to each entry that contain useful debugging information.
You can use the mdsEntityOwner attribute for an entry to determine whether the connector view is properly configured, including which view owns the entry. For example:
mdsEntityOwner: MV, MYMV
If you cannot delete an entry from a connector view, it may be because the meta view owns the entry. Only a view that owns an entry can delete the entry.
Viewing this attribute is useful in determining where the entry is linked and to what it is linked. It points to a meta view entry's corresponding entry in a connector view. For example:
Multiple values for this attribute are possible, one for each connector view to which the entry is linked.
Viewing this attribute is useful in determining where the entry is linked and to what it is linked. It points to a connector view entry's corresponding entry in the meta view. For example:
Checking Operational Status
To make sure a connector view is working correctly, you can check the Status and Statistics windows in the Meta-Directory console. More information on these windows can be found in Chapter 14 "Monitoring Meta-Directory Components".
When a problem occurs between the meta view and a connector view, check the status of the connector view in the Meta-Directory console. The Status window indicates whether the view is enabled, disabled, or performing a refresh operation. For flow problems occurring between the meta view and the connector view:
If the connector view is enabled and remains enabled, the likely cause is a misconfigured join rule. You can check each of the rules for questionable syntax by using the Join Rule Tester (Configuration > Join Rules > Rule Tester). To find out exactly what failed, you can view the logs.Normally, a view is automatically disabled when the join engine encounters an error with one of the rules that would compromise data integrity.
If the connector view is enabled but becomes disabled, the likely cause is a bad DN mapping rule, attribute flow rule, or corrupted data. This causes a flow problem to occur between the meta view and the connector view.
The Statistics window usually indicates whether or not errors are presently occurring. Here is a guide for what to look for in the Statistics window:
When many errors appear during a refresh, the likely cause is a bad rule or rule set. Make sure you have added rules to the rule set. You can use the Join Rule Tester to check each of the rules or rule sets for incorrect syntax. You can also check the logs as described above under Status Window.
Data Server Test Connect Button
This button is a useful tool when you want to check if the configuration for your data server is correct. This button provides feedback on your configuration.
Examining Log Files
You can track the flow of information between connector and meta view by examining the logs.
Most problems with flow involve a failure in the configuration of flow rules. Join engine logs are helpful in determining the cause of the problem if, for example, the join engine couldn't contact a server or if a bind operation failed.
The join engine log reports the transactions between the meta view and connector views. Each transaction is time-stamped and includes the relationship between the meta view and the connector view and a message. When a new entry is added, the join engine detects the changes and initiates action using all the rules defined for the enabled connector views. The join engine evaluates rules in the following order:
Filter configuration rulesTo see how each rule executed, you can increase the logging level of data access to 3 (Configuration > join-engine > Log > Verbosity). This should enable you to see exactly which rule failed and why it failed, thereby assisting you in correcting your rules grammar. However, for the case of a faulty constructed attribute, the log does not indicate the problem directly. If a constructed attribute fails, the information at the highest logging level (3) only states that the mapping failed for the rule.
For more information about monitoring log files, refer to Chapter 14 "Monitoring Meta-Directory Components."
Turning Off UID Uniqueness
UID uniqueness is one of the constraint violations that can occur, and is the most common one with Directory Server 4.x. If you have multiple views on one Directory Server, and the entries are using UID, you could have two entries in two different views with the same UID. To Meta-Directory, this is acceptable, but to a Directory Server with the UID plug-in turned on, this is an error.
By default, UID uniqueness is turned on for Directory Server 4.x, but turned off for Directory Server 5.x. For constraint violations in Directory Server 4.x, you should turn off UID uniqueness.
Use the following methodology to resolve a problem that might occur when your data has an attribute UID.
Open the Directory Server through the Console.
Click on the Configuration tab.
Click on the topology tree at Plugins.
Scroll down to "uid uniqueness" and click to open.
Uncheck the Enable plugin box.
Restart the Server.
Fixing Join Problems
If you are experiencing unexplained incorrect joining, make sure that data is not flowing directly from the connector into the meta view.
If the join engine won't install, the most common reason is that the Directory Server is improperly configured. During installation, the join engine must point to a Directory Server instance that contains the configuration directory o=NetscapeRoot.
The following error messages, when received during join engine configuration, indicate a Directory Server configuration problem:
You have not created the 4.x changelog (retro changelog plug-in 5.x), or you have created, configured, and enabled it through instance creation, but have not restarted the Directory Server. Check that the path and suffix/subtree you provided for the changelog is valid.
Fixing Data Flow Problems
Use the following methodology to resolve problems that you might encounter with data flow.
View the data source and make sure that data exists. To check that the data hasn't already synchronized, use refresh the view to see updates.
For indirect connectors where no data appears to synchronize to the connector view, check the scheduled time the data is configured to synchronize. Wait until that time has elapsed, then schedule the task to run more frequently.
Examine the relevant log files. The join engine log keeps track of errors resulting from rules that aren't configured properly. The Directory Server logs show objectclass violations, constraint violations, or other LDAP problems. You can also increase the log level to check rules (Configuration > join-engine > Log > Verbosity).
Fixing Large Synchronization Failures
Large synchronizations can fail on very slow systems or networks. You can initiate the debug process by increasing the log level to 3 (Configuration > join-engine > Log > Verbosity) if you see the message USER_TIMELIMIT_EXCEEDED. You can also go to Configuration > Meta-Directory > Data Servers > Tuning and increase the value in the Maximum Operation Result Time field.
This section discusses common configuration problems and their possible solutions. Tabular information is presented for problems associated with the following components:
lists troubleshooting tips for problems you might encounter while creating instances.
Provided a valid changelog path for the Directory Server changelog enabling dialog. The path given should have the .dbb files in it, and you should be able to search the changelog suffix. (The default is cn=changelog.)
If you are using Directory Server 5.x and you enabled the changelog through the Directory Server console (and not Meta-Directory instance creation), make sure to enable the retro changelog, rather than the normal replication changelog.
Is your Directory Server culling changelog entries before the join engine can process them? The changelog cleanup has to be set to infinity, or large enough to not delete changes before the join engine examines them.
Use the Directory Server console and specify o=MV suffix, then during instance creation specify ou=MV1,ou=MvEntries,o=MV as the base dn. To make this work, you would need to add the entries o=MV and ou=MvEntries.
The following tables list troubleshooting tips for problems you might encounter after configuring iPlanet Meta-Directory.
Are all your rules being applied in the correct direction? The rules usually will only make sense going one way (meta view to connector view, for example), but not the other way, so if you didn't assign them to the correct direction, nothing will function.
Did you wait long enough for the join engine to re-read the configuration? If the join engine is busy, it might not read the configuration for some time, since it relies on the DCNS queue, and there could be a lot of data changes ahead of your config changes.
Did you try refreshing the console after adding your new rule that didn't show up in other parts of the interface? When you invoke a console refresh, it re-reads everything from the LDAP configuration. As a last resort, restart the console.
Check that your DN construction is based on a unique attribute for all entries to which this rule applies. You've created a problem if two entries have the same attribute value upon which the DN is formed.
Either your DN is not creating a unique DN and you should redesign it, or you actually want to join or link these two entries. In this case, you're using the wrong type of rule. You're missing a join rule which would do this join or link.
Check that your Attribute Flow selection criteria are selecting the correct entries. Possibly the selection criteria are identifying the wrong entries or missing some, or there is a typo and you created the wrong mapping between the source view and the target view. Another reason may be that you are trying to map to an attribute that is the wrong data type for your source data.
Check that your attribute flow is complete and that you haven't missed any attributes. What objectclasses are you trying to flow? Does your attribute flow produce objectclass compliant entries? Does your attribute flow produce LDAP-compliant entries? Do they have objectclasses?
Check that your attribute flow rule is configured for the correct direction. Each rule has a specific direction associated with it. Open the rule through the interface and make sure that the direction is correct.
lists troubleshooting tips for problems you might encounter with connector views.
Did you create a browsing index in the Directory Server console for the suffix of the view with a lot of entries that you are trying to browse? The console can't handle too many entries at once, so it has to rely on the server to give it a Virtual List View, for which you need a special index. See your Directory Server documentation for more information.
The following tables list troubleshooting tips for problems you might encounter after configuring connectors.
Make sure to wait for the default 15-minute polling interval for the UTC to flow your changes. Everything the UTC does is based on the polling interval, including refresh. Consequently, you'll have to change the 15-minute default if you want results sooner.
Do you have a UTC attribute flow defined for the connector view to FDS that doesn't handle the attributes that are being rejected by the FDS? When going from the connector view to FDS, everything flows.
Do you have different object types and your default values/attribute mapping isn't taking this into account? If you have multiple object types, you should be careful with the UTC rules. You may want to create this material in Perl script/task.cfg.
Is your Perl attribute mapping compatible with your UTC attribute mapping? If you've set up Perl script attribute mapping (like LineFormat in task.cfg), you need to make sure your UTC mapping takes that into account.
The text editor you used to edit task.cfg should not remove trailing white spaces from the end of lines. Did you specify DN as your IndexAttribute in task.cfg? IndexAttribute must be a unique attribute, but not DN.
Was the Join Engine trying to synchronize Oracle when you ran the Delete Data Server SQL scripts? This is because the join engine is probably connected to Oracle. Remove all views based on the data server from the meta view's participating views list first, and then wait for the join engine to finish before re-running the SQL commands. As a last resort, stop the join engine.
Are your DN mapping rules for DB-based views based on the Primary or Nominated Key(s)? The DN must be based on the Primary Key/Nominated Key when flowing from the meta view to the connector view. This is also recommended when flowing from the connector view to the meta view.
Did you duplicate mappings between DN Mapping and Attribute Flow for the Database Connector? You should not duplicate mappings. If you've mapped EMPNO to employeeNumber in attribute flow and then made your DN mapping rule look like:
Did you change the structure of any of your instrumented Oracle tables, such as removing a column? If you change the structure of the table, such as deleting an instrumented column, the Database Connector will cease to function. You will need to uninstrument and reinstrument.
Did you run the same DBC SQL script twice? Ask this if the user tells you no flow to/from Oracle is happening or if they notice that the changelog is broken (no changes are being logged) or if they see trigger-related error messages in Oracle. If you run the same script twice, the triggers cease to function.
lists general troubleshooting tips for iPlanet Meta-Directory.
lists general troubleshooting tips for Directory Server.
You are experiencing poor performance, especially during large synchronizations, and errors such as DA_E_UNWILLING_TO_PERFORM, DA_E_USER_TIMELIMIT_EXCEEDED might appear, or other time-out messages might appear.
You are experiencing poor performance and hear disk thrashing on the machine hosting the Directory Server, or you see the Directory Server warning at start-up or at the beginning of a database import about your cachesize/dbcachsize being too large for physical memory.
While loading the Meta-Directory schema to a Directory Server instance that does not contain the join engine and meta view configuration information, ldapmodify attempted to delete an entry that does not exist. When ldapmodify applied the Meta-Directory schema, it attempted to delete the attribute type before a new one was added.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated April 08, 2002