Novell IDENTITY MANAGER Common Driver Administration Guide
Novell®
www.novell.com
Common Driver Administration Guide
Identity Manager
novdocx (en) 17 September 2009
AUTHORIZED DOCUMENTATION
3.6.1
December 24, 2009
Identity Manager 3.6.1 Common Driver Administration Guide
Legal Notices
Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time,
without obligation to notify any person or entity of such revisions or changes.
Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims
any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc.
reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to
notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the
trade laws of other countries. You agree to comply with all export control regulations and to obtain any required
licenses or classification to export, re-export, or import deliverables. You agree not to export or re-export to entities
on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export
laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses.
Please refer to the International Trade Services (http://www.novell.com/company/policies/trade_services) for more
information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary
export approvals.
novdocx (en) 17 September 2009
Copyright © 2008-2009 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied,
stored on a retrieval system, or transmitted without the express written consent of the publisher.
Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this
document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S.
patents listed on the Novell Legal Patents Web page (http://www.novell.com/company/legal/patents/) and one or
more additional patents or pending patent applications in the U.S. and in other countries.
Novell, Inc.
404 Wyman Street, Suite 500
Waltham, MA 02451
U.S.A.
www.novell.com
Online Documentation: To access the latest online documentation for this and other Novell products, see
the Novell Documentation Web page (http://www.novell.com/documentation).
Novell Trademarks
For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/
trademarks/tmlist.html).
Third-Party Materials
All third-party trademarks are the property of their respective owners.
novdocx (en) 17 September 2009
novdocx (en) 17 September 2009
4 Identity Manager 3.6.1 Common Driver Administration Guide
Contents
About This Guide 9
1 Starting, Stopping, or Restarting the Driver 11
1.1 Starting the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.2 Starting the Driver in iManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3 Stopping the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 Stopping the Driver in iManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 Restarting the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6 Restarting the Driver in iManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 Activating the Driver 13
3 Viewing Version Information 15
novdocx (en) 17 September 2009
3.1 Viewing a Hierarchical Display of Version Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Viewing the Version Information as a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3 Saving Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.4 Driver Configuration Files Naming Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4 Backing Up a Driver 21
4.1 Exporting the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.2 Exporting the Driver in iManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5 Monitoring Driver Health 23
5.1 Creating a Driver Health Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Creating a Driver Health Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.3 Modifying the Driver Health Job’s Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.4 Modifying the Conditions for a Health State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5 Modifying the Actions for a Health State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.6 Creating a Custom State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.7 Memory Requirements for Driver Health . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6 Viewing Driver Statistics 35
6.1 Viewing Statistics for an Individual Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.2 Viewing Statistics for a Driver Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7 Managing Associations between Drivers and Objects 39
7.1 Inspecting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.2 Inspecting Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Contents 5
8 Inspecting a Driver’s Cache File 45
9 Securely Storing Driver Passwords with Named Passwords 47
9.1 Using Designer to Configure Named Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
9.2 Using iManager to Configure Named Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
9.3 Using Named Passwords in Driver Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.3.1 Using the Policy Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.3.2 Using XSLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.4 Using the DirXML Command Line Utility to Configure Named Passwords . . . . . . . . . . . . . . . 50
9.4.1 Creating a Named Password in the DirXML Command Line Utility . . . . . . . . . . . . . . 50
9.4.2 Removing a Named Password in the DirXML Command Line Utility . . . . . . . . . . . . 52
10 Configuring Java Environment Parameters 55
10.1 Using iManager to Configure the Java Environment Parameters . . . . . . . . . . . . . . . . . . . . . . 55
10.2 Using Designer to Configure the Java Environment Parameters. . . . . . . . . . . . . . . . . . . . . . . 56
11 Reassociating a Driver Set Object with a Server 59
novdocx (en) 17 September 2009
12 Using the DirXML Command Line Utility 61
12.1 Interactive Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
12.2 Command Line Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
13 Synchronizing Objects 77
13.1 What Is Synchronization? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
13.2 When Is Synchronization Done? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
13.3 How Does the Metadirectory Engine Decide Which Object to Synchronize? . . . . . . . . . . . . . 78
13.4 How Does Synchronization Work?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
13.4.1 Scenario One. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
13.4.2 Scenario Two. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
13.4.3 Scenario Three . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
14 Migrating and Resynchronizing Data 85
15 Viewing Identity Manager Processes 87
15.1 Adding Trace Levels in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
15.1.1 Driver Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
15.1.2 Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
15.2 Adding Trace Levels in iManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
15.2.1 Driver Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
15.2.2 Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
15.3 Capturing Identity Manager Processes to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
15.3.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
15.3.2 UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
15.3.3 iMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
15.3.4 Remote Loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
16 Editing Driver Configuration Files 95
16.1 Variables in a Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6 Identity Manager 3.6.1 Common Driver Administration Guide
16.1.1 General Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
16.1.2 Import Driver Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
16.2 Flexible Prompting in a Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
16.3 Viewing the Informal Identity Manager Driver Configuration DTD . . . . . . . . . . . . . . . . . . . . . 100
17 Troubleshooting the Driver 101
17.1 Using Novell Sentinel to Log Identity Manager Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
17.2 Troubleshooting Driver Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
17.3 Removing a Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
17.4 Driver Shim Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
17.5 Identity Manager Driver Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
17.6 Java Customization Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
18 When and How to Use Global Configuration Values 109
18.1 Using GCVs to Adapt the Driver Configuration File to Changing Environments . . . . . . . . . . 109
18.2 When Not to Use GCVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
18.3 When to Use Driver Set GCVs Versus Driver GCVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
18.4 Naming Convention for GCVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
novdocx (en) 17 September 2009
A Driver Properties 111
A.1 Accessing the Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
A.2 Named Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
A.3 Engine Control Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
A.4 Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
A.5 Driver Image/iManager Icon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
A.6 Security Equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
A.7 Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
A.8 Edit Filter XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
A.9 Misc/Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A.10 Excluded Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A.11 Driver Health Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A.12 Driver Manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A.13 Driver Cache Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A.14 Driver Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
A.15 Server Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Contents 7
novdocx (en) 17 September 2009
8 Identity Manager 3.6.1 Common Driver Administration Guide
About This Guide
This guide contains administration tasks that are common to all Identity Manager drivers. The guide
is organized as follows:
Chapter 1, “Starting, Stopping, or Restarting the Driver,” on page 11
Chapter 2, “Activating the Driver,” on page 13
Chapter 3, “Viewing Version Information,” on page 15
Chapter 4, “Backing Up a Driver,” on page 21
Chapter 5, “Monitoring Driver Health,” on page 23
Chapter 6, “Viewing Driver Statistics,” on page 35
Chapter 7, “Managing Associations between Drivers and Objects,” on page 39
Chapter 8, “Inspecting a Driver’s Cache File,” on page 45
Chapter 9, “Securely Storing Driver Passwords with Named Passwords,” on page 47
Chapter 10, “Configuring Java Environment Parameters,” on page 55
novdocx (en) 17 September 2009
Chapter 11, “Reassociating a Driver Set Object with a Server,” on page 59
Chapter 12, “Using the DirXML Command Line Utility,” on page 61
Chapter 13, “Synchronizing Objects,” on page 77
Chapter 14, “Migrating and Resynchronizing Data,” on page 85
Chapter 15, “Viewing Identity Manager Processes,” on page 87
Chapter 16, “Editing Driver Configuration Files,” on page 95
Chapter 17, “Troubleshooting the Driver,” on page 101
Chapter 18, “When and How to Use Global Configuration Values,” on page 109
Appendix A, “Driver Properties,” on page 111
Audience
This guide is intended for administrators, consultants, and network engineers who require a highlevel introduction to Identity Manager business solutions, technologies, and tools.
Documentation Updates
For the most recent version of this document, see the Identity Manager Documentation Web site
(http://www.novell.com/documentation/idm36/index.html).
Additional Documentation
For additional Identity Manager documentation, see the Identity Manager Documentation Web site
(http://www.novell.com/documentation/idm36/index.html)
For information about specific Identity Manager drivers, see the Identity Manager Drivers Web site
(http://www.novell.com/documentation/idm36drivers/index.html).
About This Guide 9
Documentation Conventions
In Novell® documentation, a greater-than symbol (>) is used to separate actions within a step and
items in a cross-reference path.
®
A trademark symbol (
, TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party
trademark.
When a single pathname can be written with a backslash for some platforms or a forward slash for
other platforms, the pathname is presented with a backslash. Users of platforms that require a
forward slash, such as Linux* or UNIX*, should use forward slashes as required by your software.
novdocx (en) 17 September 2009
10 Identity Manager 3.6.1 Common Driver Administration Guide
1
Starting, Stopping, or Restarting
novdocx (en) 17 September 2009
the Driver
The following sections describe how to start, stop, and restart a driver in Designer and iManager.
Section 1.1, “Starting the Driver in Designer,” on page 11
Section 1.2, “Starting the Driver in iManager,” on page 11
Section 1.3, “Stopping the Driver in Designer,” on page 11
Section 1.4, “Stopping the Driver in iManager,” on page 11
Section 1.5, “Restarting the Driver in Designer,” on page 12
Section 1.6, “Restarting the Driver in iManager,” on page 12
1.1 Starting the Driver in Designer
1 Open a project in the Modeler, then right-click the driver line.
2 Click Live > Start Driver.
1.2 Starting the Driver in iManager
1 In the Roles and Tasks view, click Identity Manager > Identity Manager Overview.
1
2 In the Search in field, specify the fully distinguished name of the container where you want to
start searching and then click , or click to browse for and select the container in the tree
structure.
3 Click the upper right corner of the driver icon whose status you want to change, then click Start
driver.
1.3 Stopping the Driver in Designer
1 Open a project in the Modeler, then right-click the driver line.
2 Click Live > Stop Driver.
1.4 Stopping the Driver in iManager
1 In the Roles and Tasks view, click Identity Manager > Identity Manager Overview.
2 In the Search in field, specify the fully distinguished name of the container where you want to
start searching and then click , or click to browse for and select the container in the tree
structure.
3 Click the upper right corner of the driver icon whose status you want to change, then click Stop
driver.
Starting, Stopping, or Restarting the Driver
11
1.5 Restarting the Driver in Designer
1 Open a project in the Modeler, then right-click the driver line.
2 Click Live > Restart Driver.
1.6 Restarting the Driver in iManager
1 In the Roles and Tasks view, click Identity Manager > Identity Manager Overview.
2 In the Search in field, specify the fully distinguished name of the container where you want to
start searching and then click , or click to browse for and select the container in the tree
structure.
3 Click the upper right corner of the driver icon, then click Restart driver.
novdocx (en) 17 September 2009
12 Identity Manager 3.6.1 Common Driver Administration Guide
2
Activating the Driver
Novell® Identity Manager, Integration Modules (drivers), and the Roles Based Provisioning Module
must be activated within 90 days of installation, or they shut down. At any time during the 90 days,
or afterward, you can choose to activate Identity Manager products.
To activate the driver, see “Activating Novell Identity Manager Products” in the Identity Manager
3.6.1 Installation Guide.
novdocx (en) 17 September 2009
2
Activating the Driver
13
novdocx (en) 17 September 2009
14 Identity Manager 3.6.1 Common Driver Administration Guide
3
Viewing Version Information
The Metadirectory engine, the driver shims, and the driver configuration files each contain a
separate version number. The Version Discovery Tool in iManager helps you find the versions of the
Metadirectory engine and the driver shims versions. The driver configuration files contain there own
naming convention.
Section 3.1, “Viewing a Hierarchical Display of Version Information,” on page 15
Section 3.2, “Viewing the Version Information as a Text File,” on page 17
Section 3.3, “Saving Version Information,” on page 19
Section 3.4, “Driver Configuration Files Naming Convention,” on page 20
3.1 Viewing a Hierarchical Display of Version Information
novdocx (en) 17 September 2009
3
1 In iManager, click Identity Manager > Identity Manager Overview, then click Search to find
the driver sets in the Identity Vault.
2 Click the specific driver set in the list.
3 Click Driver Set > Version information in the Driver Set Overview page.
You can also select Identity Manager Utilities > Versions Discovery, browse to and select the
driver set, then click OK.
4 View a top-level or unexpanded display of versioning information.
Viewing Version Information
15
The unexpanded hierarchical view displays the following:
The eDirectory
TM
tree that you are authenticated to
The driver set that you selected
Servers that are associated with the driver set
novdocx (en) 17 September 2009
If the driver set is associated with two or more servers, you can view Identity Manager
information on each server.
Drivers
5 View version information related to servers by expanding the server icon.
The expanded view of a top-level server icon displays the following:
Last log time
Version of Identity Manager that is running on the server
6 View version information related to drivers by expanding the driver icon.
16 Identity Manager 3.6.1 Common Driver Administration Guide
The expanded view of a top-level driver icon displays the following:
The driver name
novdocx (en) 17 September 2009
The driver module (for example, com.novell.nds.dirxml.driver.nds.DriverShimImpl)
The expanded view of a server under a driver icon displays the following:
The driver ID
The version of the instance of the driver running on that server
3.2 Viewing the Version Information as a Text File
Identity Manager publishes versioning information to a file. You can view this information in text
format. The textual representation is the same information contained in the hierarchical view.
1 In iManager, click Identity Manager > Identity Manager Overview, then click Search to find
the driver sets in the Identity Vault.
2 Click the specific driver set in the list.
3 Click Driver Set > Version information in the Driver Set Overview page.
Viewing Version Information 17
You can also select Identity Manager Utilities > Versioning Discovery, then browse to and
select the driver set, then click Information.
4 In the Versioning Discovery Tool dialog box, click View.
novdocx (en) 17 September 2009
The information is displayed as a text file in the Report Viewer window.
18 Identity Manager 3.6.1 Common Driver Administration Guide
3.3 Saving Version Information
You can save version information to a text file on your local or network drive.
1 In iManager, click Identity Manager > Identity Manager Overview, then click Search to find
the driver sets in the Identity Vault.
2 Click the specific driver set in the list.
3 Click Driver Set > Version information in the Driver Set Overview page.
novdocx (en) 17 September 2009
You can also select Identity Manager Utilities > Versioning Discovery, browse to and select the
driver set, then click Information.
4 In the Versioning Discovery Tool dialog box, click Save As.
5 In the File Download dialog box, click Save.
6 Navigate to the desired directory, type a filename, then click Save.
Identity Manager saves the data to a text file.
Viewing Version Information 19
3.4 Driver Configuration Files Naming Convention
The driver configuration file naming convention is:
<base name>[-<type>]-IDM<min. engine version>-V<config version>.xml
Base Name: The name of the connected system or service the driver provides. For example,
Active Directory or Delimited Text.
Type: An additional descriptor for the driver configuration file. If there are multiple
configuration files, the type distinguishes among the different files.
Minimum Engine Version: Lists the minimum engine version that the driver can run against.
The elements to date are:
IDM2_0_0
IDM2_0_1
IDM2_0_2
IDM3_0_0
IDM3_0_1
IDM3_5_0
novdocx (en) 17 September 2009
IDM3_5_1
IDM3_6_0
Configuration Version: Specifies the particular driver configuration file version. It is a
number that is incriminated with each release of a new driver configuration file.
V1
V2
V11
V23
For example:
ActiveDirectory-IDM3_6_0-V4.xml
DelimitedText-CSVSample-IDM3_6_0-V2.xml
20 Identity Manager 3.6.1 Common Driver Administration Guide
4
Backing Up a Driver
After you have created a driver, it is important to create a backup of the driver. You can use Designer
or iManager to create an XML file of the driver. The file contains all of the information entered into
the driver during configuration. If the driver becomes corrupted, the exported file can be imported to
restore the configuration information.
IMPORTANT: If the driver has been deleted, all of the associations on the objects are purged.
When the XML file is imported again, new associations are created through the migration process.
Not all server-specific information stored on the driver is contained in the XML file. Make sure this
information is documented through the Doc Gen process in Designer. See Documenting Projects
(http://www.novell.com/documentation/designer35/admin_guide/data/docgenoverview.html) in the
Designer 3.5 for Identity Manager Administration Guide.
Section 4.1, “Exporting the Driver in Designer,” on page 21
novdocx (en) 17 September 2009
4
Section 4.2, “Exporting the Driver in iManager,” on page 21
4.1 Exporting the Driver in Designer
1 Open a project in Designer, then right-click the driver object.
2 Select Export to Configuration File.
3 Specify a unique name for the configuration file, browse to location where it should be saved,
then click Save.
4 Click OK in the Export Configuration Results window.
4.2 Exporting the Driver in iManager
1 In iManager, click Identity Manager > Identity Manager Overview.
2 Browse to and select the driver set object, then click Search.
3 Click the driver icon.
4 Select Export in the Identity Manager Driver Overview page.
5 Browse to and select the driver object you want to export, then click Next.
6 Select Export all policies, linked to the configuration or not or select Only export policies that
are linked to the configuration, depending upon the information you want to have stored in the
XML file.
7 Click Next.
8 Click Save As, then click Save.
9 Browse and select a location to save the XML file, then click Save.
10 Click Finish.
Backing Up a Driver
21
novdocx (en) 17 September 2009
22 Identity Manager 3.6.1 Common Driver Administration Guide
5
Monitoring Driver Health
Driver health monitoring allows you to view a driver’s current state of health as green, yellow, or
red, and to define the actions to perform in response to each of these health states.
You create the conditions (criteria) that determine each of the health states, and you also define the
actions you want performed whenever the driver’s health state changes. For example, if the driver’s
health changes from a green state to a yellow state (based on the conditions you’ve established), you
can perform such actions as restarting the driver, shutting down the driver, and sending an e-mail to
the person designated to resolve issues with the driver.
You can also define custom states. Whenever the conditions for the custom state are met, the
associated actions are performed regardless of the driver’s current state of green, yellow, or red.
The driver’s health state is not monitored unless both a health configuration and a health job exist
and the health job is running. If the configuration and job exist and the job is running, the driver icon
displays a semaphore (green, yellow, or red indicator). Otherwise, the semaphore is not displayed or
is displayed without a colored indicator.
novdocx (en) 17 September 2009
5
Figure 5-1 Driver health indicator
To turn on health monitoring for the driver, complete the steps provided in the following three
sections:
Section 5.1, “Creating a Driver Health Configuration,” on page 23
Section 5.2, “Creating a Driver Health Job,” on page 25
Section 5.3, “Modifying the Driver Health Job’s Settings,” on page 26
After you’ve created the driver’s health configuration and health job, you can use the steps in the
following sections to modify the conditions and actions associated with each health state and to
create one or more custom states:
Section 5.4, “Modifying the Conditions for a Health State,” on page 27
Section 5.5, “Modifying the Actions for a Health State,” on page 30
Section 5.6, “Creating a Custom State,” on page 31
5.1 Creating a Driver Health Configuration
The health configuration for version 3.6 or newer drivers is automatically configured. Skip this
section if your drivers are version 3.6 or newer.
Monitoring Driver Health
23
If you have drivers that are older than version 3.6, you need to create the health configuration for
each driver you want to monitor.
1 In iManager, click to display the Identity Manager Administration page.
2 In the Administration list, click Driver Health Configuration.
3 In the Driver to configure health checking field, select the driver for which you want to create
the health configuration, then click OK to display the Driver Health Configuration page.
If the driver’s health configuration does not yet exist, the Driver Health Configuration page
displays a Create a basic health configuration for it now prompt.
novdocx (en) 17 September 2009
4 Click Create a basic health configuration for it now.
A basic health configuration is created and displayed. Sample conditions are created for the
green and yellow states (not the red).
5 Continue with Section 5.2, “Creating a Driver Health Job,” on page 25.
24 Identity Manager 3.6.1 Common Driver Administration Guide
5.2 Creating a Driver Health Job
The health of a driver is evaluated during the periodic execution of a Driver Health job. The job
evaluates the conditions for the health states and assigns the driver the appropriate state. The job
also executes any actions associated with the assigned state.
If a Driver Health job does not exist, the Driver Health Configuration page displays a Run the New
Driver wizard and import the Driver Health Job’s configuration prompt, as shown in the following
screenshot. If the page does not display this prompt, the Driver Health job already exists; you can
skip to Section 5.4, “Modifying the Conditions for a Health State,” on page 27.
novdocx (en) 17 September 2009
To create a Driver Health job:
1 Open the Driver Health Configuration page for a driver you want to monitor.
For help opening the Driver Health Configuration page, see Step 1 through Step 3 on page 24.
2 Click New Driver, then follow the prompts to import the configuration file for the Driver
Health job. Refer to the following information for details:
Where to place the driver: Place the job in the same driver set as the driver. The correct
driver set is selected by default.
Import a configuration: Import the configuration from the server. In the Show field,
select Identity Manager 3.6.1 configurations, then select the Driver Health job in the
Configurations field.
Email server: Select the e-mail server that you want used for any actions that initiate e-
mail. If you have not defined additional e-mail servers, select the Default Notification
Collection server.
Monitoring Driver Health 25
Servers: If the driver set is associated with only one server, that server is selected and
cannot be changed. If the driver set is associated with multiple servers, select the server
where you want to run the job.
After the job is created, you can adjust the job settings as desired. For example, you can modify how
often the job runs, which drivers use the job, and how much data the job maintains to support
transaction history. For instructions, continue with Section 5.3, “Modifying the Driver Health Job’s
Settings,” on page 26.
5.3 Modifying the Driver Health Job’s Settings
The Driver Health job evaluates the conditions for the health states and assigns the driver the
appropriate state. The job also executes any actions associated with the assigned state.
As with all driver jobs, there are several Driver Health job settings that you can modify to optimize
health monitoring performance for your environment, including settings for how often the job runs,
which drivers use the job, and how much data the job maintains to support transaction history.
To modify the job settings:
novdocx (en) 17 September 2009
1 Open the Driver Health Configuration page for a driver that uses the Driver Health job you
want to modify.
For help opening the Driver Health Configuration page, see Step 1 through Step 3 on page 24.
2 Click the Driver Health job.
3 Change the desired settings on the following tabs:
Schedule: The Driver Health job is a continuously running job, meaning that it does not
stop unless a health state action shuts it down or it is shut down manually. The job must
run continuously to be able to support transaction data collection for use in Transactions
History conditions.
If the job does stop, it is restarted based on the schedule. The default schedule checks
every minute to see if the job is running. If the job is not running, it is started.
Scope: By default, the job applies to all drivers in the driver set. This means that you only
need one Driver Health job per driver set. However, you can create multiple Driver Health
jobs for different drivers within the same driver set. For example, you might have some
drivers whose health you want updated more frequently than other drivers, in which case
you would need at least two Driver Health jobs.
Parameters: You can change any of the following parameters:
Login ID: This defaults to the login ID that was used when creating the driver job.
You should only change this if you want the driver to authenticate with different
credentials.
Login password: This is the password required for the login ID that you supplied in
the Login ID field.
Subscriber Heartbeat: Controls whether the Driver Health job does a heartbeat
query on a driver’s Subscriber channel before performing a health check on the
driver.
Polling interval: Determines how often the job evaluates the conditions for the
health states, assigns the driver the appropriate state, executes any actions associated
with the assigned state, and stores the driver’s transaction data. The default polling
interval is one minute.
26 Identity Manager 3.6.1 Common Driver Administration Guide
Polling interval units: Specifies the time unit (minutes, hours, days, weeks) for the
number specified in the Polling interval setting.
Duration sampling data is kept: Specifies how long a driver’s transaction data is
kept. The default, two weeks, causes a transaction to be retained for two weeks
before being deleted. A longer duration provides a greater time period that can be
used in Transactions History conditions, but requires more memory. For example, to
use a Transactions History condition that evaluates of the number of publisher
reported events for the last 10 days, you need to keep transaction data for at least 10
days.
Duration units: Specifies the time unit (minutes, hours, days, weeks) for the number
specified in the Duration transaction data is kept setting.
4 Click OK to save your changes.
5.4 Modifying the Conditions for a Health State
You control the conditions that determine each health state. The green state is intended to represent a
healthy driver, and a red state is intended to represent an unhealthy driver.
novdocx (en) 17 September 2009
The conditions for the green state are evaluated first. If the driver fails to meet the green conditions,
the yellow conditions are evaluated. If the driver fails to meet the yellow conditions, the driver is
automatically assigned a red health state.
To modify the conditions for a state:
1 Open the Driver Health Configuration page for a driver whose conditions you want to modify.
For help opening the Driver Health Configuration page, see Step 1 through Step 3 on page 24.
2 Click the tab for the state (Green or Yellow) you want to modify.
The tab displays the current conditions for the health state. Conditions are organized into
groups, and logical operators, either AND or OR, are used to combine each condition and each
group. Consider the following example for the green state:
Monitoring Driver Health 27
GROUP1
Condition1 and
Condition2
Or
GROUP2
Condition1 and
Condition2 and
Condition3
In the example, the driver is assigned a green state if either the GROUP1 conditions or the
GROUP2 conditions evaluate as true. If neither group of conditions is true, then the conditions
for the yellow state are evaluated.
The conditions that can be evaluated are:
Driver State: Running, stopped, starting, not running, or shutting down. For example, one
of the default conditions for the green health state is that the driver is running.
Driver in Cache Overflow: The state of the cache used for holding driver transactions. If
the driver is in cache overflow, all available cache has been used. For example, the default
condition for the green health state is that the Driver in Cache Overflow condition is false
and the default for the yellow health state is that the Driver in Cache Overflow condition is
true.
Newest: The age of the newest transaction in the cache.
Oldest: The age of the oldest transaction in the cache.
novdocx (en) 17 September 2009
Tot a l S iz e: The size of the cache.
Unprocessed Size: The size of all unprocessed transactions in the cache.
Unprocessed Transactions: The number of unprocessed transactions in the cache. You
can specify all transactions types or specific transaction types (such as adds, removes, or
renames).
Transactions History: The number of transactions processed at various points in the
Subscriber or Publisher channel over a given period of time. This condition uses multiple
elements in the following format:
<transaction type> <transaction location and time period > <relational operator>
<transaction number>.
<transaction type>: Specifies the type of transaction being evaluated. This can be all
transactions, adds, removes, renames, and so forth.
<transaction location and time period>: Specifies the place in the Subscriber or
Publisher channel and the time period being evaluated. For example, you might
evaluate the total number of transactions processed as Publisher reported events over
the last 48 hours. By default, transaction history data is kept for two weeks, which
means that you cannot specify a time period greater than two weeks unless you
change the default Transaction Data Duration setting. This setting is specified on the
Driver Health job. See Section 5.3, “Modifying the Driver Health Job’s Settings,” on
page 26 for information about changing the setting.
<relational operator>: Specifies that the identified transactions must be equal to, not
equal to, less than, less than or equal to, greater than, or greater than or equal to the
<transaction number>.
<transaction number>: Specifies the number of transactions being used in the
evaluation.
The following provides an example of a Transactions History condition:
28 Identity Manager 3.6.1 Common Driver Administration Guide
<number of adds> <as publisher commands> <over the last 10 minutes> <is
less than> <1000>
Available History: The amount of transaction history data that is available for evaluation.
The primary purpose for this condition is to ensure that a Transactions History condition
does not cause the current state to fail because it does not have enough transaction history
data collected for the time period being evaluated.
For example, assume that you want to use the Transactions History condition to evaluate
the number of adds as Publisher commands over the last 48 hours (the example shown in
the Transactions History section above). However, you don't want the condition to fail if
there is not yet 48 hours worth of data, which can be the case after the initial setup of the
driver's health configuration or if the driver's server restarts (because transaction history
data is kept in memory). Therefore, you create condition groups similar to the following:
Group1
Available History <is less than> <48 hours>
or
Group2
Available History <is greater than or equal to> <48 hours> and
Transactions History <number of adds> <as publisher commands> <over
the last 48 hours> <is less than> <1000>
novdocx (en) 17 September 2009
The state evaluates to true if either condition group is true, meaning that a) there is less
than 48 hours of data, or b) there is at least 48 hours of data and the number of adds as
Publisher commands over the last 48 hours is less than 1000.
The state evaluates to false if both conditions evaluate to false, meaning that a) there is at
least 48 hours of data and b) the number of adds as publisher commands over the last 48
hours is greater than 1000.
3 Modify the criteria as desired.
To add a new group, click New Group.
To add a condition, click the button next to the group heading.
To reorder condition groups or individual conditions, select the check box next to the
group or condition you want to move, then click the and buttons to move it up and
down. You can also use the and buttons to move a condition from one group to
another.
To copy condition groups or individual conditions, select the check box next to the group
or condition you want to copy, click Edit > Copy selections to clipboard, click the tab for
the health state where you want to copy the group or condition, then click Edit > Append
items on clipboard. For example, assume that you want to copy a condition from one
condition group to another. You would select the condition, copy it to the clipboard, then
append it. The condition is added as its own condition group; if desired, use the and
buttons to move it into another condition group.
To move condition groups or individual conditions, select the check box next to the group
or condition you want to move, click Edit > Cut selections to clipboard, click the tab for
the health state where you want to move the group or condition, then click Edit > Append
items on clipboard. For example, assume that you want to move a condition group from
the green health state to the yellow health state. You would select the condition group, cut
it to the Clipboard, open the yellow health state, then append it.
Monitoring Driver Health 29
4 Click Apply to save your changes.
5 If you want to change the actions associated with the conditions you’ve set, continue with
Section 5.5, “Modifying the Actions for a Health State,” on page 30.
5.5 Modifying the Actions for a Health State
You can determine the actions that you want performed when the driver health state changes. For
example, if the state changes from green to yellow, you can shut down or restart the driver, generate
an event, or start a workflow. Or, if the state changes from yellow to green, any actions associated
with the green state are performed.
A health state’s actions are performed only once each time the conditions are met; as long as the
state remains true, the actions are not repeated. If the state changes because its conditions are no
longer met, the actions are performed again the next time the conditions are met.
1 Open the Driver Health Configuration page for a driver whose actions you want to modify.
For help opening the Driver Health Configuration page, see Step 1 through Step 3 on page 24.
2 Click the tab for the state whose actions you want to modify.
novdocx (en) 17 September 2009
3 Click the button next to the Actions heading to add an action, then select the type of action
you want:
Start Driver: Starts the driver.
Stop Driver: Stops the driver.
Restart Driver: Stops and then starts the driver.
Clear Driver Cache: Removes all transactions, including unprocessed transactions, from
the cache.
Send Email: Sends an e-mail to one or more recipients. The template you want to use in
the e-mail message body must already exist. To include the driver name, server name, and
current health state information in the e-mail, add the
$HealthState$
tokens to the e-mail template and then include the tokens in the message
text. For example:
The current health state of the $Driver$ driver running on $Server$ is
$HealthState$.
30 Identity Manager 3.6.1 Common Driver Administration Guide
$Driver$, $Server$
, and
Loading...