Novell Doc: Designer 2.1 for Identity Manager 3.5.1

9.6.1 Driver General Settings

Figure 9-8 The Driver’s General Property Page

Table 9-7 The Driver’s General Settings

Setting	Description
Name	Displays the driver name, which you can change.
Notes	Enables you to type notes about your driver implementation.
Basic configuration file	Displays the configuration filename that this driver uses. Contains the filename of the configuration file that was used during import. To view the path to this file, click the information icon next to the filename. You might want to view the file to find out version information. If you haven’t yet run the import wizard, this field is set to None.
Supported DN format	Displays the format (for example, LDAP) that is supported for each driver. This DN information is important for policy building and simulation. For additional details, click the information icon next to the format field.

The driver property page is dynamic. Labels and descriptions are dynamically read from the driver configuration file for the Authentication ID an. connection information

9.6.2 Driver Global Configuration Values

Global configuration values (GCVs) are settings that are similar to driver parameters. Global configuration values can be specified for an individual driver as well as a driver set. If a driver does not have a GCV, the driver inherits the value for that GCV from the driver set.

GCVs allow you to specify settings for Identity Manager features such as password synchronization and driver heartbeat, as well as settings that are specific to the function of an individual driver configuration. Some GCVs are provided with the drivers, but you can also add your own. You can refer to these values in a policy to help you customize your driver configuration.

To edit the driver set's GCV settings, double-click the Driver object. From the Global Configuration Values page, you can add, edit, remove, or edit the XML for GCVs.

To view or change the driver’s GCV settings, double-click the driver. From the Global Configuration Values page, you can add, edit, or remove values, or edit the XML file for the driver.

9.6.3 Driver Log Level

The Driver Log Level options enable you to view high-level information. For lower-level information, use the Trace option. See Section 9.6.8, Driver Trace Levels.

Figure 9-9 Settings for the Driver Log Level

By default, logging inherits the setting from the driver set. To change the default:

Double-click the driver.
Select Driver Log Level.
Select a logging option.

The option that you select determines which information is available in the log.

To configure the audit instrumentation, select Log specific events, click the event selector button, select events, then click OK.
Specify the number of entries in the log.

The default is 50 entries (lines) in the log. If you want a longer history, increase the number.
Save changes by clicking OK.

The driver log contains messages from the driver. The messages are related to operations that the driver performed or tried to perform. To view the log, use iManager. Select the log icon on the Driver object in the Identity Manager Overview.

9.6.4 Driver Configuration

Driver Module

Table 9-8 Driver Module Settings

Setting	Description
J ava: Name of the Java class	Specify the name of the Java class that will be instantiated for the shim component of the driver. This class can be located in the classes directory as a class file, or in the lib directory as a . jar file.
Native: Name of the DLL	Specify the name of the . dll file that will be instantiated for the application shim component of the driver.
Connect to Remote Loader	Select this option if you want to connect the driver to the Metadirectory engine that uses the Remote Loader.
Driver object password: Set Password	Set a password for the Driver object. If you are using the Remote Loader, you must enter a password on this page or the remote driver cannot run. The Remote Loader uses this password to authenticate itself to the remote driver.
Remote Loader client configuration for documentation: Include in documentation	Enables you to document your Remote Loader configuration for the driver. From the drop-down list, select a name that you specified on the driver’s documentation property page. To use this option, see Section 9.6.9, Engine Control Values.

Authentication

Table 9-9 Authentication Settings

Setting	Description
Authentication information for server	The server that the driver is associated with.
Authentication ID	Enter the application user ID. This ID is used to pass Identity Vault subscription information to the application. If you have enabled SSL/TLS for eDirectory drivers, this option is dimmed.
Remote tree address and port	Enter the address or name and port of the server that the application shim should communicate with.
Set Password	Enables you to set or change an application password (for example, Active Directory).
Remove Password	Deletes the password to the application.
Host name	Specifies the address or name of the machine where the Remote Loader runs. For example, enter hostname=192.168.0.1. If you don't enter this communication parameter, this value defaults to localhost.
Port	Specifies the port that the Remote Loader uses to accept connections from the remote interface shim. For example, enter port=8090. If you don't enter this communication parameter, this value defaults to 8090.
KMO	Specifies the Key Name of the Key Material Object containing the keys and certificate used for SSL. For example, enter kmo=remote driver cert. If you don't enter this communication parameter, no value is stored for this parameter. SSL won’t be available.
Other parameters	Provides reference information. It is included when you document your entire project.

Driver Cache Limit

Figure 9-10 Options for the Driver Cache

The driver cache is a file that holds Identity Vault events until a driver can process them.

This file can become very large in the following situations:

Events occur at a steady rate that is faster than Identity Manager can process them over a long period of time.
The driver is shut down for long period of time but is not disabled.

By default, the driver cache (file) size is limited only by available disk space. This is the recommended setting.

The only reason to set some other limit is to protect against accidentally filling up the disk. The number that you use depends on the difference between projected amount of available disk space without anything in the cache and the amount of free disk space that you want to ensure will always be left available, divided by the number of drivers on the server.

The primary reason that the cache file becomes very large is if the driver is left not running over a long period of time. In this case, the recommendation is to disable the driver rather than set a cache limit. After the limit is reached, all the cached events are discarded.

Startup Option

Table 9-10 Startup Settings

Setting	Description
Auto start	The driver starts automatically when the Metadirectory engine loads.
Manual	You must start the driver manually from the driver state location.
Disabled	Disables the driver.
Do not automatically synchronize the driver	If you don't select this option, a driver that has been deployed but disabled resynchronizes on startup. If you select this option, a driver that has been deployed but disabled does not resynchronize.

Driver Parameters

From this tab, you can enter common driver options, Subscriber and Publisher channel options, as well as edit XML. Because the options here differ between drivers, refer to the Identity Manager Drivers for configuration information.

9.6.5 Driver Manifest

The driver manifest is like a resume for the driver. The driver manifest states what the driver supports, and includes a few configuration settings. The driver developer should provide the driver manifest. Usually a network administrator does not need to edit the driver manifest.

For more information, see the developer documentation for Identity Manager drivers.

9.6.6 Driver Named Passwords

You can store multiple passwords securely for each of your drivers. This functionality is referred to as Named Passwords because each different password is accessed by a key, or name.

Named Passwords are useful because you can refer to the password by name in a driver policy. When the driver needs to use the password, it requests the password from the Metadirectory engine. This method lets you avoid revealing the actual password in the code for a driver policy.

The following example shows how a Named Password can be referenced in a driver policy on the Subscriber channel in XSLT: <xsl:value-of select=”query:getNamedPassword($srcQueryProcessor,’mynamedpassword’)” xmlns:query=”http://www.novell.com/java/com.novell.nds.dirxml.driver.XdsQueryProcessor/>

You can store and retrieve Named Passwords for any driver without making changes to the driver shim.

As a security measure, in addition to using Named Passwords, you should control access to all Identity Manager objects in eDirectory.

NOTE:A driver developer can also customize a driver to use Named Passwords in other ways, such as retrieving Named Passwords when the driver starts up, instead of requesting them from the Metadirectory engine each time they are needed.

For example, the Identity Manager Driver for Lotus Notes* driver has been customized to support additional ways of using Named Passwords, and examples of those methods are included in the sample driver configurations. For more information, see the Identity Manager driver guides.

9.6.7 Editing or Creating a Driver iManager Icon

You can see and edit the iManager icons that each driver uses. This is important because iManager renders driver icons in a particular way. However, those icons don't appear anywhere in Designer. Conversely, Designer's application icons don't appear anywhere in iManager's user interface.

To help bridge that gap, you can view the iManager icon to be used in Designer:

Figure 9-11 The Option to View the iManager Icon

Right-click a driver (for example, eDirectory) in the Modeler, then select Properties.
Select iManager Icon.

Designer displays an icon. It is associated with the driver in Designer, unless a different one was imported and stored on the driver.
To change the icon, click Browse or New, browse to and select an image file, then click OK twice.

The next time that the driver deploys, Designer sets the icon in eDirectory, and iManager uses it.

Also see Section 22.0, Editing Icons for Drivers and Applications.

9.6.8 Driver Trace Levels

Through the Modeler, you can add a trace level to your driver or driver set. With the trace level set, DSTRACE displays the Identity Manager events as the engine processes the events. The trace level only affects the driver or driver set it is set on.

Use the trace level for testing or for troubleshooting issues with the drivers when they are deployed. If you run DSTRACE while the drivers are in production, the Identity Manager server might process events slowly.

DSTRACE displays the output of the specified trace level.

The following tables describes each trace field:

Table 9-11 Driver Trace Settings

Field	Description
Trace level	As the driver trace level increases, the amount of information displayed in DSTRACE increases. Trace level 1 shows errors, but not the cause of the errors. To see password synchronization information, set the trace level to 5.
Trace level: Use setting from the driver set	If you select this option, all trace levels set at the driver set level take precedence over any driver settings. Otherwise, settings at the driver level are effective.
Trace file	Specify a filename and location where the Identity Manager information is written for the selected driver. When a value is set in this field, all Java information for the driver is written to file. As long as the file is specified, Java information is written to this file. If you do not need to debug Java, leave this field blank.
Trace file: Use setting from the driver set	If you select this option, all trace levels set at the driver set level take precedence over any driver settings. Otherwise, settings at the driver level are effective.
Trace file size limit	Allows you to set a limit for the Java trace file. If you set the file size to Unlimited, the file grows in size until no disk space is available. NOTE:The trace file is created in multiple files. Identity Manager automatically divides the maximum file size by ten and creates ten separate files. The combined size of these files equals the maximum trace file size.
Trace name	Helps you track trace messages. The name that you specify here appears with the driver trace messages. Use a trace name if the driver name is very long.

NetWare

Use dstrace.nlm to display trace messages on the system console or trace messages to a file ( sys:\system\dstrace.log). Dstrace.nlm displays the trace messages to a screen labeled DSTrace Console.

Use the following commands at the server console:

DSTRACE SCREEN ON: Allows trace messages to appear on the DSTRACE Console.

DSTRACE FILE ON: Captures trace messages sent to the DSTRACE Console to the dstrace.log file.

DSTRACE FILE OFF: Stops capture trace messages to the log file.

DSTRACE -ALL: Turns off all Trace flags.

DSTRACE +DXML DSTRACE +DVRS: Displays the Identity Manager (DirXML) events.

DSTRACE +TAGS DSTRACE +TIME: Displays the message tags and times tamps.

Windows

Open the Control Panel, select NDS Services, then click DSTRACE.DLM > Start. A window named NDS Server Trace Utility opens.

To set the filters to capture the DirXML trace information:

Click Edit > Options > Clear All.
Click the boxes next to DirXML and DirXML Drivers, then click OK.

To save the information to a file:

Click File > New.

A dialog box prompts for a filename.
Enter a filename with the extension of . log.
To stop capturing information, click File > Close.

The file is saved.

UNIX

Use the ndstrace command at the console to display the Identity Manager events. The exit command quits the trace utility.

Table 9-12 ndstrace Commands

Command	Description
Set ndstrace=nodebug	Turns off all trace flags.
Set ndstrace on	Displays trace messages to the console.
Set ndstrace file on	Captures trace message to the ndstrace.log file in the /var/nds directory.
Set ndstrace file off	Stops capturing trace messages to the file.
Set ndstrace=+dxml	Displays the Identity Manager events
Set ndstrace=+dvrs	Displays the Identity Manager driver events.

iMonitor

Use iMonitor to get DSTRACE information from a Web browser.

Table 9-13 Platforms and Commands for Web Browsers

Platform	Command
NetWare®	ndsimon.nlm
Windows	ndsimon.dlm
Linux/Solaris/AIX/HP-UX	ndsimonitor

Access iMonitor from http://server_ip:8008/nds (the default port).
Click Trace Configuration.
Click Clear All.
Click DirXML and DirXML Drivers.
Click Trace On, then click Trace History.
Click the Current document icon to view the live trace.

9.6.9 Engine Control Values

The engine control values enable you to change certain default behaviors of the Metadirectory engine can be changed. You can access the values only if a server is associated with the Driver Set object.

In Designer:

In the Modeler, right-click the driver line.
Select Properties > Engine Control Values.
Click the tooltip icon to the right of the Engine Controls for Server field. If a server is associated with the Identity Vault, and if you are authenticated, the engine control values display in the large pane.

Table 9-14 Engine Control Values

Option	Description
Subscriber channel retry interval in seconds	The Subscriber channel retry interval controls how frequently the Metadirectory engine retries the processing of a cached transaction after the application shim's Subscriber object returns a retry status.
Qualified form for DN-syntax attribute values	The qualified specification for DN-syntax attribute values controls whether values for DN-syntax attribute values are presented in unqualified slash form or qualified slash form. A True setting means the values are presented in qualified form.
Qualified form from rename events	The qualified form for rename events controls whether the new-name portion of rename events coming from the Identity Vault is presented to the Subscriber channel with type qualifiers. For example, CN=. A True setting means the names are presented in qualified form.
Maximum eDirectory replication wait time in seconds	The maximum eDirectory™ replication wait time controls the maximum time that the Metadirectory engine waits for a particular change to replicate between the local replica and a remote replica. This only affects operations where the Metadirectory engine is required to contact a remote eDirectory server in the same tree to perform an operation and might need to wait until some change has replicated to or from the remote server before the operation can be completed (for example, object moves when the Identity Manager server does not hold the master replica of the moved object; file system rights operations for Users created from a template.)
Use non-compliant backwards-compatible mode for XSLT	This control sets the XSLT processor used by the Metadirectory engine to a backward-compatible mode. The backward-compatible mode causes the XSLT processor to use one or more behaviors that are not XPath 1.0 and XSLT 1.0 standards-compliant. This is done in the interest of backward-compatibility with existing DirXML® style sheets that depend on the non-standard behaviors. For example, the behavior of the XPath “!=” operator when one operand is a node set and the other operand is other than a node set is incorrect in DirXML releases up to and including Identity Manager 2.0. This behavior has been corrected; however, the corrected behavior is disabled by default through this control in favor of backward-compatibility with existing DirXML style sheets.
Maximum application objects to migrate at once	This control is used to limit the number of application objects that the Metadirectory engine requests from an application during a single query that is performed as part of a Migrate Objects from Application operation. If java.lang.OutOfMemoryError errors are encountered during a Migrate from Application operation, this number should be set lower than the default. The default is 50. NOTE:This control does not limit the number of application objects that can be migrated; it merely limits the batch size.
Set creatorsName on objects created in Identity Vault	This control is used by the Identity Manager engine to determine if the creatorsName attribute should be set to the DN of this driver on all objects created in the Identity Vault by this driver. Setting the creatorsName attribute allows for easily identifying objects created by this driver, but also carries a performance penalty. If not set, the creatorsName attribute defaults to the DN of the NCP™ Server object that is hosting the driver.
Write pending associations	This control determines whether the Identity Manager engine writes a pending association on an object during Subscriber channel processing. Writing a pending association confers little or no benefit but does incur a performance penalty. Nevertheless, the option exists to turn it on for backward compatibility.
Use password event values	This control determines the source of the value reported for the nspmDistributionPassword attribute for Subscriber channel Add and Modify events. Setting the control to False means that the current value of the nspmDistributionPassword is obtained and reported as the value of the attribute event. This means that only the current password value is available. This is the default behavior. Setting the control to True means that the value recorded with the eDirectory event is decrypted and is reported as the value of the attribute event. This means that both the old password value (if it exists) and the replacement password value at the time of the event are available. This is useful for synchronizing passwords to certain applications that require the old password to enable setting a new password.
Enable password synchronization status reporting	This control determines whether the Identity Manager engine reports the status of Subscriber channel password change events. Reporting the status of Subscriber channel password change events allows applications such as the Identity Manager User Application to monitor the synchronization progress of a password change that should be synchronized to the connected application.

9.6 Configuring Drivers