eTrust Directory Administrator Guide - CA Technologies
eTrust Directory Administrator Guide - CA Technologies
eTrust Directory Administrator Guide - CA Technologies
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
<strong>eTrust</strong> <strong>Directory</strong><br />
<strong>Administrator</strong> <strong>Guide</strong><br />
r8, Service Pack 1<br />
G00505-4E
This documentation and related computer software program (hereinafter referred to as the “Documentation”) is for<br />
the end user’s informational purposes only and is subject to change or withdrawal by Computer Associates<br />
International, Inc. (“<strong>CA</strong>”) at any time.<br />
This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without<br />
the prior written consent of <strong>CA</strong>. This documentation is proprietary information of <strong>CA</strong> and protected by the copyright<br />
laws of the United States and international treaties.<br />
Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for<br />
their own internal use, provided that all <strong>CA</strong> copyright notices and legends are affixed to each reproduced copy. Only<br />
authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the<br />
license for the software are permitted to have access to such copies.<br />
This right to print copies is limited to the period during which the license for the product remains in full force and<br />
effect. Should the license terminate for any reason, it shall be the user’s responsibility to return to <strong>CA</strong> the reproduced<br />
copies or to certify to <strong>CA</strong> that same have been destroyed.<br />
To the extent permitted by applicable law, <strong>CA</strong> provides this documentation “as is” without warranty of any kind,<br />
including without limitation, any implied warranties of merchantability, fitness for a particular purpose or<br />
noninfringement. In no event will <strong>CA</strong> be liable to the end user or any third party for any loss or damage, direct or<br />
indirect, from the use of this documentation, including without limitation, lost profits, business interruption,<br />
goodwill, or lost data, even if <strong>CA</strong> is expressly advised of such loss or damage.<br />
The use of any product referenced in this documentation and this documentation is governed by the end user’s<br />
applicable license agreement.<br />
The manufacturer of this documentation is Computer Associates International, Inc.<br />
Provided with “Restricted Rights” as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or<br />
DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.<br />
© 2005 Computer Associates International, Inc.<br />
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Contents<br />
Chapter 1: Introduction<br />
<strong>eTrust</strong> <strong>Directory</strong> Modules ..................................................................... 1-2<br />
DXserver ................................................................................. 1-2<br />
The Relational Database Management System (RDBMS) ...................................... 1-3<br />
Configuration Files........................................................................ 1-3<br />
DXtools .................................................................................. 1-3<br />
Samples .................................................................................. 1-4<br />
RDBMS Tools............................................................................. 1-5<br />
DXwebserver ............................................................................. 1-5<br />
<strong>eTrust</strong> <strong>Directory</strong> Glossary ..................................................................... 1-6<br />
Chapter 2: DXserver Overview<br />
What is DXserver? ............................................................................ 2-1<br />
DXserver Configuration Files .................................................................. 2-2<br />
DXserver File Directories .................................................................. 2-2<br />
Sample Configuration Files ................................................................ 2-4<br />
Configuration File Types .................................................................. 2-4<br />
The Initialization File ...................................................................... 2-5<br />
Configuration Grouping Files .............................................................. 2-6<br />
Knowledge Files .......................................................................... 2-7<br />
DXserver Commands ......................................................................... 2-9<br />
The dxserver Command - Install, Start, or Stop the DXserver .................................. 2-9<br />
DXserver Script Language .................................................................... 2-11<br />
Configuration Files....................................................................... 2-11<br />
Command Syntax ........................................................................ 2-12<br />
Script Files .............................................................................. 2-13<br />
Script File Errors and Debugging .......................................................... 2-13<br />
DXconsole .................................................................................. 2-14<br />
DXconsole Security....................................................................... 2-14<br />
Opening DXconsole ...................................................................... 2-14<br />
Contents<br />
iii
Closing DXconsole........................................................................ 2-15<br />
Configuring DXconsole ................................................................... 2-16<br />
Help Command .......................................................................... 2-21<br />
Command Shortcuts ...................................................................... 2-22<br />
Databases ................................................................................... 2-23<br />
Multiple DSA Processes to One DIT/DIB ................................................... 2-23<br />
Multiple <strong>Directory</strong> Databases on One Machine .............................................. 2-24<br />
Hot Swap ................................................................................ 2-24<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> ........................................................ 2-25<br />
Ports Used by <strong>eTrust</strong> <strong>Directory</strong> Components ................................................ 2-25<br />
Ports Used by Sample Tools and Sample DSAs .............................................. 2-26<br />
Chapter 3: General Administration<br />
Defining DSAs with the set dsa Command....................................................... 3-1<br />
The set dsa Command Syntax............................................................... 3-2<br />
The set dsa Command Parameters .......................................................... 3-3<br />
Setting DSA Port Numbers ................................................................. 3-4<br />
Viewing Communications Settings .......................................................... 3-4<br />
Alarms, Traces, and Logs ...................................................................... 3-5<br />
Alarms ................................................................................... 3-5<br />
Traces .................................................................................... 3-5<br />
Logs...................................................................................... 3-8<br />
Associations ................................................................................. 3-13<br />
The assoc Command Options .............................................................. 3-13<br />
Viewing Association Configuration ........................................................ 3-15<br />
Viewing Associations ..................................................................... 3-16<br />
Tracing Associations ...................................................................... 3-16<br />
Stopping a DSA .......................................................................... 3-16<br />
Association Times ........................................................................ 3-17<br />
Controlling Binds......................................................................... 3-17<br />
Aborting Associations .................................................................... 3-18<br />
Concurrent Associations .................................................................. 3-18<br />
Association Queues ....................................................................... 3-19<br />
Local Operations ............................................................................. 3-20<br />
The oper Commands...................................................................... 3-20<br />
Viewing Operation Configuration.......................................................... 3-22<br />
Viewing Operation Statistics............................................................... 3-22<br />
Concurrent Operations.................................................................... 3-23<br />
Administration Limits .................................................................... 3-23<br />
Operational Attributes .................................................................... 3-23<br />
iv<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Access Controls .......................................................................... 3-23<br />
Read Only............................................................................... 3-24<br />
Abandoning Operations .................................................................. 3-24<br />
The <strong>Directory</strong> Information Base ............................................................... 3-25<br />
Viewing DIB Configuration ............................................................... 3-26<br />
Database Name .......................................................................... 3-26<br />
Manage Connections to the Database ...................................................... 3-27<br />
Alias Integrity ........................................................................... 3-27<br />
Counting Entries ......................................................................... 3-28<br />
Rejecting All list Commands .............................................................. 3-28<br />
Rejecting All Unfiltered Searches .......................................................... 3-29<br />
Password Storage ........................................................................ 3-29<br />
Indexing Options ........................................................................ 3-30<br />
DXcache .................................................................................... 3-32<br />
How DXcache Works..................................................................... 3-32<br />
Design the DXcache System ............................................................... 3-33<br />
Enable and Configure DXcache............................................................ 3-33<br />
View the DXcache Configuration .......................................................... 3-37<br />
Keep DXcache Synchronized with the Database ............................................. 3-37<br />
Use <strong>eTrust</strong> <strong>Directory</strong> in Cache-Only Mode.................................................. 3-38<br />
Virtual Attributes ............................................................................ 3-40<br />
Dynamic Groups......................................................................... 3-40<br />
Class of Service Templates ................................................................ 3-43<br />
Knowledge Flags ............................................................................ 3-48<br />
The Three Kinds of Knowledge Flags ...................................................... 3-48<br />
List of all DSA Flags...................................................................... 3-52<br />
List of all Trust Flags ..................................................................... 3-53<br />
List of all Link Flags ...................................................................... 3-54<br />
Chapter 4: Schema Definition<br />
Configuring Schema .......................................................................... 4-2<br />
Grouping Schema ......................................................................... 4-2<br />
Managing Schema ........................................................................ 4-3<br />
Schema Commands ....................................................................... 4-3<br />
Viewing Schema .......................................................................... 4-4<br />
Schema Prefixes........................................................................... 4-4<br />
Attributes .................................................................................... 4-5<br />
Attribute Syntaxes ........................................................................ 4-6<br />
Attribute Checking ........................................................................ 4-7<br />
Syntax Aliases for Unsupported Attribute Syntax ............................................ 4-7<br />
Contents<br />
v
Attribute Sets ............................................................................. 4-8<br />
Attribute Names .......................................................................... 4-8<br />
Unique Attributes ......................................................................... 4-9<br />
Changing the Schema Definition for Attributes in Use........................................ 4-12<br />
Object Classes................................................................................ 4-14<br />
Object Class Kind......................................................................... 4-14<br />
Object Class Checking .................................................................... 4-15<br />
Object Class Storage ...................................................................... 4-16<br />
Name Bindings .............................................................................. 4-18<br />
Name Binding Checks .................................................................... 4-18<br />
Name Bindings and Structural Object Classes ............................................... 4-19<br />
Name Bindings and Aliases ............................................................... 4-19<br />
Considerations for Schemas that Do Not Support Name Binding .............................. 4-19<br />
Defining Local Schema........................................................................ 4-20<br />
Chapter 5: Distribution and DSP<br />
Managing DSP ................................................................................ 5-2<br />
DSP Command Options .................................................................... 5-2<br />
Knowledge References ..................................................................... 5-3<br />
Remote Operations ........................................................................ 5-4<br />
Limiting Remote Operations................................................................ 5-4<br />
Remote Connections ....................................................................... 5-5<br />
Unbinding Remote Connections ............................................................ 5-5<br />
Incoming DSP Credentials.................................................................. 5-6<br />
Outgoing DSP Credentials.................................................................. 5-6<br />
Distributed Searches (Multi-Chaining)....................................................... 5-6<br />
Limiting Multi-Chaining ................................................................... 5-6<br />
Viewing DSP Configuration ................................................................ 5-7<br />
Configuring a DSA ............................................................................ 5-8<br />
Configuring a Subordinate DSA ............................................................ 5-8<br />
Proxy DSAs ............................................................................... 5-9<br />
Configuring Another DXserver ................................................................ 5-10<br />
Configuring Alternative Network Addresses ................................................ 5-10<br />
Configuring a Third-party DSA ............................................................ 5-11<br />
DXlink .................................................................................. 5-11<br />
Configuring Multiple Local DSAs .......................................................... 5-12<br />
Configuring a Domain of DXservers ........................................................... 5-13<br />
A Domain of DXservers ................................................................... 5-13<br />
Sharing DXserver Configuration ........................................................... 5-14<br />
Configuring a First-level DSA.............................................................. 5-14<br />
vi<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring a Router DSA ................................................................ 5-15<br />
Transparent Routing ..................................................................... 5-15<br />
Configuring a Relay DSA ................................................................. 5-16<br />
Caching Entries from Subordinate DSAs ................................................... 5-16<br />
Alternative DSAs ............................................................................ 5-17<br />
DSA Failover ............................................................................ 5-18<br />
DSA Load-Sharing ....................................................................... 5-20<br />
DSA Query Streaming .................................................................... 5-24<br />
Chapter 6: Security<br />
Secure Socket Layer (SSL) Encryption........................................................... 6-2<br />
About the SSL Protocol .................................................................... 6-2<br />
SSL Encryption and Authentication Using SSLD ............................................. 6-3<br />
DXserver Personality Certificates ........................................................... 6-5<br />
Setting Up SSL For DXserver ............................................................... 6-6<br />
Client Encryption ........................................................................ 6-11<br />
DSA-to-DSA Encryption (DSP and DISP) ................................................... 6-11<br />
Authentication .............................................................................. 6-12<br />
Setting the Minimum Authentication Level ................................................. 6-12<br />
Anonymous Authentication............................................................... 6-13<br />
Simple Authentication.................................................................... 6-13<br />
SSL Authentication....................................................................... 6-14<br />
Distributed User Authentication........................................................... 6-16<br />
DSP Simple Authentication ............................................................... 6-17<br />
DSP SSL Authentication .................................................................. 6-19<br />
DISP Authentication ..................................................................... 6-19<br />
Bypassing Mutual Authentication ......................................................... 6-20<br />
Conveying User Authentication ........................................................... 6-21<br />
DSP Link Authentication ................................................................. 6-22<br />
Impersonation Protection ................................................................. 6-23<br />
Managing Passwords ........................................................................ 6-24<br />
How Password Rules Are Applied......................................................... 6-24<br />
Password Protection ..................................................................... 6-25<br />
Password Command Options ............................................................. 6-25<br />
Enabling or Disabling Password Management .............................................. 6-28<br />
Checking Password Quality............................................................... 6-28<br />
Setting the Life Span of Passwords......................................................... 6-29<br />
Resetting a Password ..................................................................... 6-30<br />
Locking an Account after Incorrect Login Attempts ......................................... 6-31<br />
Suspending an Account Manually ......................................................... 6-31<br />
Contents<br />
vii
Preventing Users from Re-using Passwords ................................................. 6-32<br />
Some Password Controls Require an LDAP Client ........................................... 6-32<br />
Example Password Policy ................................................................. 6-33<br />
Access Control Overview ..................................................................... 6-34<br />
Access Control Policies.................................................................... 6-34<br />
Access Control Rules...................................................................... 6-35<br />
Designing Your Access Control Scheme .................................................... 6-35<br />
Working with Access Controls ............................................................. 6-37<br />
Static Access Controls......................................................................... 6-38<br />
Overview of Static Access Control Rules .................................................... 6-38<br />
Setting Up Static Access Controls .......................................................... 6-40<br />
Defining Superusers ...................................................................... 6-42<br />
Defining Administrative Users............................................................. 6-43<br />
Defining Registered Users ................................................................. 6-45<br />
Defining Public Users ..................................................................... 6-47<br />
Protecting Items .......................................................................... 6-48<br />
Dynamic Access Controls ..................................................................... 6-51<br />
Enabling and Disabling Dynamic Access Controls ........................................... 6-51<br />
Dynamic Access Control Rules............................................................. 6-52<br />
Groups, Roles, and Proxies .................................................................... 6-53<br />
Defining Groups of Users ................................................................. 6-53<br />
Role-Based Access Controls ............................................................... 6-54<br />
Secure Proxies............................................................................ 6-56<br />
Access Controls and Aliases ............................................................... 6-57<br />
Access-Controlled Routing .................................................................... 6-58<br />
Chapter 7: Replication<br />
Replication Concepts .......................................................................... 7-2<br />
Compare Distribution and Replication....................................................... 7-2<br />
Compare Multimaster and Master–Slave Replication.......................................... 7-2<br />
Compare Real-Time and Write-Behind Replication ........................................... 7-3<br />
Compare Replay-Based and State-Based Replication .......................................... 7-3<br />
Three Types of Replication Used with <strong>eTrust</strong> <strong>Directory</strong> ....................................... 7-4<br />
Keep System Clocks Synchronized .......................................................... 7-4<br />
Multiwrite Replication ......................................................................... 7-5<br />
How Multiwrite Replication Works ......................................................... 7-5<br />
Multiwrite Can Work Asynchronously ...................................................... 7-6<br />
How Multiwrite Groups Work .............................................................. 7-7<br />
Set Up a Multiwrite System................................................................ 7-10<br />
Recovering a Multiwrite System Using Queues .............................................. 7-12<br />
viii<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Recovering a Multiwrite System Using DISP................................................ 7-14<br />
Multiwrite Replication to an LDAP <strong>Directory</strong> ............................................... 7-17<br />
Multiwrite and DXcache .................................................................. 7-17<br />
Re-synchronize Databases Manually ....................................................... 7-18<br />
Example: Multiwrite Replication .......................................................... 7-19<br />
DISP Replication............................................................................. 7-21<br />
Configuring a DISP Responder ............................................................ 7-21<br />
DISP Agreements ........................................................................ 7-21<br />
Setting DISP Agreements ................................................................. 7-22<br />
Viewing DISP Agreements ................................................................ 7-23<br />
Shared DISP Configuration ............................................................... 7-23<br />
Manual Initiation of DISP ................................................................. 7-24<br />
Shadow DSAs ........................................................................... 7-24<br />
DISP Routing ............................................................................ 7-24<br />
Selective Shadowing ..................................................................... 7-25<br />
Manually Synchronizing Replicas Using Database Tools......................................... 7-27<br />
How Manual Synchronization Works ...................................................... 7-27<br />
How to Manually Synchronize <strong>eTrust</strong> <strong>Directory</strong> Databases................................... 7-27<br />
Chapter 8: LDAP and DXlink<br />
LDAP Clients................................................................................. 8-2<br />
Defining the LDAP Port ................................................................... 8-2<br />
Configuring LDAP Names ................................................................. 8-2<br />
Handling LDAP Strings ................................................................... 8-3<br />
Transparent Routing ...................................................................... 8-3<br />
Schema Publishing............................................................................ 8-4<br />
Integrating Other LDAP Servers................................................................ 8-6<br />
User Credentials on DXlink Binds .......................................................... 8-7<br />
Prefix Mapping ........................................................................... 8-9<br />
Working with Microsoft Exchange ......................................................... 8-10<br />
Chapter 9: Monitoring the <strong>Directory</strong><br />
General Monitoring ........................................................................... 9-2<br />
DXconsole................................................................................ 9-2<br />
Log Files ................................................................................. 9-2<br />
Databases ................................................................................ 9-3<br />
Disk Space ............................................................................... 9-3<br />
Contents<br />
ix
SNMP and the <strong>Directory</strong> Monitoring MIB ....................................................... 9-4<br />
Configuring the SNMP Agent .............................................................. 9-5<br />
SNMP Monitor Utility ..................................................................... 9-6<br />
Configuring the SNMP Trap Destination..................................................... 9-8<br />
CMIP and X.700 Management .................................................................. 9-9<br />
Configuring the CMIP Agent ............................................................... 9-9<br />
CMIP Monitor Utility ...................................................................... 9-9<br />
Chapter 10: Using DXtools<br />
Database Tools ............................................................................... 10-2<br />
Creating a DSA: DXnewdsa ............................................................... 10-4<br />
Creating a Database: DXnewdb ............................................................ 10-5<br />
Extending a Database: DXextenddb ........................................................ 10-5<br />
Destroying a Database: DXdestroydb ....................................................... 10-6<br />
Emptying a Database: DXemptydb ......................................................... 10-6<br />
Backing Up a Database: DXbackupdb ...................................................... 10-7<br />
Restoring a Database: DXrestoredb ......................................................... 10-8<br />
Tuning a Database: DXtunedb ............................................................. 10-9<br />
Managing Indexes: DXindexdb ........................................................... 10-10<br />
Displaying Database Statistics: DXstatdb................................................... 10-13<br />
Listing Existing Databases: DXlistdb ...................................................... 10-14<br />
Adding a Database User: DXadduser ...................................................... 10-14<br />
Deleting a Database User: DXdeluser ...................................................... 10-15<br />
Loading a Database: DXloaddb ........................................................... 10-16<br />
Dumping a Database: DXdumpdb ........................................................ 10-18<br />
Granting Access to a Database: DXgrantdb................................................. 10-19<br />
Revoking Access to a Database: DXrevokedb ............................................... 10-19<br />
Upgrading Previous Versions of a Database: DXupgradedb ................................. 10-20<br />
Initializing Multiwrite–DISP Recovery: DXdisp............................................. 10-20<br />
Reporting On and Generating Certificates: DXcertgen....................................... 10-21<br />
LDIF Tools ................................................................................. 10-27<br />
CSV Source Data ........................................................................ 10-27<br />
Template Files (LDT) .................................................................... 10-28<br />
LDIF Files .............................................................................. 10-29<br />
Converting CSV Data to LDIF Format: csv2ldif ............................................. 10-30<br />
Sorting an LDIF File: ldifsort.............................................................. 10-31<br />
Calculating the Change Between Two LDIF Files: ldifdelta .................................. 10-33<br />
DAP Tools.................................................................................. 10-35<br />
Common Command Options ............................................................. 10-36<br />
Searching a <strong>Directory</strong>: DXsearch .......................................................... 10-37<br />
x<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Reporting on Certificate and CRL Indexes: DXcert ......................................... 10-38<br />
Modifying a <strong>Directory</strong>: DXmodify ........................................................ 10-39<br />
Loading Binary Files: DXmodify.......................................................... 10-40<br />
Renaming a <strong>Directory</strong> Entry: DXrename................................................... 10-41<br />
Deleting a <strong>Directory</strong> Entry: DXdelete...................................................... 10-42<br />
Bulk Loading Options ................................................................... 10-42<br />
Schema Tools............................................................................... 10-43<br />
Extracting Schema in LDIF Format: DXschemaldif ......................................... 10-44<br />
Converting Schema from LDIF to DXserver Format: ldif2dxc ................................ 10-45<br />
Converting Schema from DXserver Format to DXtools Format: DXschematxt ................. 10-49<br />
<strong>Directory</strong> Administration Tools .............................................................. 10-50<br />
Checking DSA configuration: DXsyntax ................................................... 10-50<br />
Chapter 11: Using JXplorer<br />
The JXplorer Browser ........................................................................ 11-2<br />
Menu Bar ............................................................................... 11-3<br />
Button Bar............................................................................... 11-5<br />
Quick Search Bar......................................................................... 11-6<br />
Displaying the <strong>Directory</strong> Tree ............................................................. 11-6<br />
Browsing a <strong>Directory</strong>......................................................................... 11-7<br />
Starting JXplorer ......................................................................... 11-7<br />
Connecting to a <strong>Directory</strong>................................................................. 11-7<br />
Reading Schema ......................................................................... 11-8<br />
Navigating the <strong>Directory</strong> Tree ............................................................. 11-8<br />
Displaying an Entry ...................................................................... 11-9<br />
Refreshing Entries....................................................................... 11-11<br />
Searching .............................................................................. 11-11<br />
Exploring Schema ....................................................................... 11-14<br />
Editing the <strong>Directory</strong> ........................................................................ 11-16<br />
<strong>Directory</strong> Tree Operations ............................................................... 11-16<br />
Modifying Attributes in an Entry ......................................................... 11-18<br />
Using Binary Values..................................................................... 11-20<br />
Adding a New Entry .................................................................... 11-23<br />
Submitting an Entry to the <strong>Directory</strong> ...................................................... 11-24<br />
Using LDIF Files ............................................................................ 11-25<br />
Importing and Exporting an LDIF File .................................................... 11-25<br />
Using an LDIF File Without a <strong>Directory</strong> ................................................... 11-25<br />
Binary Values in LDIF Files .............................................................. 11-26<br />
Using SSL and SASL ........................................................................ 11-27<br />
Server Authenticated SSL ................................................................ 11-27<br />
Contents<br />
xi
Client Authenticated SSL and SASL ....................................................... 11-27<br />
Managing Certificates and Keystores ...................................................... 11-28<br />
Online Help ................................................................................ 11-28<br />
Configuring JXplorer ........................................................................ 11-29<br />
View Menu ............................................................................. 11-29<br />
Options Menu........................................................................... 11-29<br />
Creating HTML Viewing Templates ....................................................... 11-34<br />
Configuring Tree Icons................................................................... 11-35<br />
Extending the Java Binary Editor.......................................................... 11-35<br />
Internationalization...................................................................... 11-35<br />
Troubleshooting ......................................................................... 11-36<br />
Other LDAP and <strong>Directory</strong> Resources ..................................................... 11-36<br />
Chapter 12: Using DXmanager<br />
How DXmanager Works ...................................................................... 12-2<br />
How You Can Use DXmanager ................................................................ 12-3<br />
Monitor DSA Status ...................................................................... 12-3<br />
Check DSA Configuration ................................................................. 12-3<br />
Track DSA Statistics ...................................................................... 12-3<br />
Check Namespace Design ................................................................. 12-3<br />
How DXmanager Presents Information......................................................... 12-4<br />
Starting DXmanager .......................................................................... 12-4<br />
Troubleshooting ............................................................................. 12-5<br />
Connectivity ............................................................................. 12-5<br />
DXwebserver Port Numbers ............................................................... 12-5<br />
Chapter 13: Using JXweb<br />
Connecting to JXweb ......................................................................... 13-2<br />
Connecting to a <strong>Directory</strong> ..................................................................... 13-3<br />
The JXweb Environment ...................................................................... 13-4<br />
Customizing JXweb .......................................................................... 13-4<br />
Using JXweb in Languages Other Than English ................................................. 13-5<br />
Displaying Non-English Characters in Internet Explorer...................................... 13-5<br />
Displaying Non-English Characters in Mozilla Browsers ..................................... 13-5<br />
Online Help ................................................................................. 13-5<br />
xii<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter 14: Using The UDDI Server<br />
About UDDI Registries ....................................................................... 14-2<br />
What a UDDI Registry Can Do ............................................................ 14-2<br />
About the <strong>eTrust</strong> <strong>Directory</strong> UDDI Server ................................................... 14-2<br />
<strong>eTrust</strong> <strong>Directory</strong> UDDI Server................................................................. 14-3<br />
Connecting to the UDDI Client................................................................ 14-4<br />
Connecting to a UDDI Registry ............................................................... 14-5<br />
Using tModels............................................................................... 14-5<br />
Using the UDDI Client in Languages Other Than English........................................ 14-6<br />
Displaying Non-English Characters in Internet Explorer ..................................... 14-6<br />
Displaying Non-English Characters in Mozilla Browsers ..................................... 14-6<br />
Chapter 15: Using the Sample DSAs, Applications, and Tools<br />
Implementing the Samples ................................................................... 15-2<br />
The Sample DSAs............................................................................ 15-3<br />
What the Sample DSAs Are Useful For ..................................................... 15-3<br />
When the Sample DSAs Are Installed ...................................................... 15-3<br />
How the Sample DSAs Work Together ..................................................... 15-3<br />
The Democorp DSAs ..................................................................... 15-4<br />
The UNSPSC DSAs ...................................................................... 15-5<br />
The Router DSAs ........................................................................ 15-6<br />
Sample Web Applications .................................................................... 15-7<br />
Customized Version of JXweb: democorp .................................................. 15-7<br />
Sample DSML Server: dsml ............................................................... 15-8<br />
Sample SAML Server: saml-sample ........................................................ 15-9<br />
Sample SPML Server: spml-sample ....................................................... 15-10<br />
Sample Use of UDDI: uddiv3-demo....................................................... 15-11<br />
Sample Configuration Files .................................................................. 15-13<br />
Sample Tools ............................................................................... 15-13<br />
The DXcmip Tool ....................................................................... 15-13<br />
The dua Tool ........................................................................... 15-14<br />
The DXtoolsgui Tool .................................................................... 15-14<br />
The ldua Tool........................................................................... 15-15<br />
The schema Tool ........................................................................ 15-15<br />
The snmp Tool.......................................................................... 15-17<br />
The soak Tool........................................................................... 15-18<br />
The ssl Tool ............................................................................ 15-21<br />
The test Tool............................................................................ 15-23<br />
The DXtrap Tool ........................................................................ 15-25<br />
Contents<br />
xiii
Chapter 16: Deploying a <strong>Directory</strong><br />
<strong>Directory</strong> Design ............................................................................. 16-2<br />
Requirements Analysis.................................................................... 16-2<br />
Service Definition......................................................................... 16-2<br />
Schema Design ........................................................................... 16-2<br />
<strong>Directory</strong> Enabled Applications ............................................................ 16-3<br />
Namespace Design ....................................................................... 16-3<br />
Security ................................................................................. 16-3<br />
Dimensioning ............................................................................ 16-4<br />
Performance ............................................................................. 16-4<br />
Availability .............................................................................. 16-4<br />
Synchronization .......................................................................... 16-5<br />
Scalability and Distribution................................................................ 16-5<br />
Complexity .............................................................................. 16-5<br />
Operations and Practices ...................................................................... 16-6<br />
Management ............................................................................. 16-6<br />
Monitoring .............................................................................. 16-6<br />
Capacity Planning ........................................................................ 16-6<br />
Backup and Restore....................................................................... 16-7<br />
Journaling ............................................................................... 16-7<br />
Database Tuning ......................................................................... 16-8<br />
Change Control .......................................................................... 16-8<br />
Upgrades ................................................................................ 16-9<br />
Maintenance ............................................................................. 16-9<br />
Troubleshooting ............................................................................ 16-10<br />
Optimizing Performance ................................................................. 16-10<br />
Managing Large Numbers of Users........................................................ 16-10<br />
Managing Large Numbers of Entries ...................................................... 16-11<br />
Limiting Users .......................................................................... 16-11<br />
Appendix A: Tailoring the RDBMS<br />
Changing the Default Page Size................................................................ A-2<br />
Increasing the Number of Cache Pages ......................................................... A-3<br />
Increasing the Number of Database Connections ................................................ A-4<br />
Step 1. Increase the Shared Memory Maximum (Optional) .................................... A-4<br />
Step 2. Increase the Database Connection Limit .............................................. A-5<br />
Other Customizations ........................................................................ A-5<br />
xiv<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Appendix B: DXserver Command Language<br />
Command Categories ......................................................................... B-1<br />
Add Command ............................................................................... B-2<br />
Clear Commands ............................................................................. B-2<br />
Close Commands ............................................................................. B-2<br />
Set Commands ............................................................................... B-3<br />
The set admin-user Command ............................................................. B-8<br />
The set agreement Command .............................................................. B-8<br />
The set attribute Command ................................................................ B-9<br />
The set dsa Command ..................................................................... B-9<br />
The set name-binding Command .......................................................... B-11<br />
The set object-class Command............................................................. B-11<br />
The set protected-items Command......................................................... B-12<br />
The set public-user Command............................................................. B-12<br />
The set reg-user Command ............................................................... B-13<br />
The set super-user Command ............................................................. B-13<br />
Source Commands ........................................................................... B-14<br />
Trace Commands ............................................................................ B-15<br />
Appendix C: Messages and Logs<br />
UNIX System Error Log ....................................................................... C-1<br />
Windows Event Log .......................................................................... C-1<br />
DXserver Logs................................................................................ C-2<br />
Advantage Ingres Logs ........................................................................ C-3<br />
DXserver Alarm Messages ..................................................................... C-7<br />
DXserver Warning Messages.................................................................. C-13<br />
Alias Errors ................................................................................. C-16<br />
Service Errors ............................................................................... C-17<br />
Advantage Ingres Errors ..................................................................... C-17<br />
Appendix D: Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows<br />
Installation Overview ......................................................................... D-2<br />
<strong>eTrust</strong> <strong>Directory</strong> Components .............................................................. D-2<br />
Default Installation Locations .............................................................. D-3<br />
The %DXHOME% Location ................................................................ D-3<br />
Installation Logging ....................................................................... D-3<br />
Upgrade <strong>eTrust</strong> <strong>Directory</strong>.................................................................. D-4<br />
Upgrade Advantage Ingres ................................................................ D-4<br />
Contents<br />
xv
Embedded <strong>eTrust</strong> Identity and Access Management ......................................... D-5<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer.............................................. D-6<br />
Step 1. Check System and Disk Requirements ............................................... D-6<br />
Step 2. Install <strong>eTrust</strong> <strong>Directory</strong> ............................................................. D-7<br />
Step 3. (Optional) Install <strong>eTrust</strong> <strong>Directory</strong> Web Components .................................. D-8<br />
Step 4. (Optional) Install the Samples and Technology Previews............................... D-9<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands ..................................................... D-11<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Silently ............................................................... D-14<br />
Install Silently Using Commands.......................................................... D-14<br />
Install Silently Using Response Files ....................................................... D-15<br />
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product ............................................... D-17<br />
How Installation Codes Work ............................................................ D-17<br />
Install <strong>eTrust</strong> <strong>Directory</strong> as an Embedded Module ........................................... D-17<br />
Uninstall <strong>eTrust</strong> <strong>Directory</strong> After an Embedded Installation .................................. D-18<br />
Troubleshooting ............................................................................ D-19<br />
Appendix E: Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX<br />
Installation Overview..........................................................................E-2<br />
<strong>eTrust</strong> <strong>Directory</strong> Components ..............................................................E-2<br />
Default Installation Locations ...............................................................E-3<br />
The $DXHOME Location ...................................................................E-3<br />
Installation Logging .......................................................................E-3<br />
Upgrade <strong>eTrust</strong> <strong>Directory</strong> ..................................................................E-4<br />
Upgrade Advantage Ingres .................................................................E-4<br />
User Accounts.............................................................................E-5<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program ...........................................E-6<br />
Step 1. Check System and Disk Requirements ................................................E-6<br />
Step 2. Install <strong>eTrust</strong> <strong>Directory</strong> .............................................................E-10<br />
Step 3: (Optional) Install the Web Components ..............................................E-16<br />
Step 4: (Optional) Install the Technology Previews and Sample Tools ..........................E-17<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands ......................................................E-19<br />
The dxsetup Command ...................................................................E-19<br />
The dxwebsetup Command ...............................................................E-20<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Silently ................................................................E-21<br />
Install Using Commands ..................................................................E-21<br />
Install Using Response Files ...............................................................E-22<br />
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product ................................................E-24<br />
How Installation Codes Work .............................................................E-24<br />
Install the Main <strong>eTrust</strong> <strong>Directory</strong> Components as an Embedded Module .......................E-24<br />
Install the Web Components as an Embedded Module .......................................E-24<br />
xvi<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Uninstall <strong>eTrust</strong> <strong>Directory</strong> after an Embedded Installation ................................... E-25<br />
Troubleshooting ............................................................................. E-26<br />
Appendix F: Licenses for Third-Party Products<br />
Apache ...................................................................................... F-1<br />
Morten’s JavaScript Tree Menu v2.3.2........................................................... F-3<br />
OpenLDAP .................................................................................. F-4<br />
The OpenLDAP Public License ............................................................. F-4<br />
The OpenLDAP Copyright Notice .......................................................... F-5<br />
OpenSSL..................................................................................... F-6<br />
Sun Microsystems, Inc. Java Web Services Developer Pack........................................ F-8<br />
Tom Sawyer Layout Assistant................................................................. F-13<br />
Contents<br />
xvii
Chapter<br />
1 Introduction<br />
The <strong>eTrust</strong> <strong>Directory</strong> consists of a suite of products that lets you build an<br />
industrial-strength directory service for directory-enabled applications. The<br />
product suite includes a high performance, state-of-the-art <strong>Directory</strong> server,<br />
graphical <strong>Directory</strong> browsers, and a set of tools for importing, exporting, and<br />
synchronizing data with other information systems.<br />
<strong>eTrust</strong> <strong>Directory</strong> advanced features are:<br />
■<br />
■<br />
■<br />
Lightweight <strong>Directory</strong> Access Protocol (LDAP) support for access and the<br />
X.500 distributed directory model for distribution, which lets you build highcapacity<br />
global directory systems<br />
Its underlying information repository (on each server) that uses a relational<br />
database to apply a patented meta-data design, thus ensuring reliability and<br />
data integrity<br />
Its unique ability to connect and integrate smaller scale LDAP Servers to<br />
create a unified directory backbone service with legacy directory servers<br />
The system is highly scalable and robust, and meets the needs of large corporate<br />
organizations, Internet Service Providers (ISPs), carriers, the military, and the<br />
smaller office automation directory applications.<br />
Introduction 1–1
<strong>eTrust</strong> <strong>Directory</strong> Modules<br />
<strong>eTrust</strong> <strong>Directory</strong> Modules<br />
The following diagram shows the relationships between the major components<br />
of <strong>eTrust</strong> <strong>Directory</strong>:<br />
JXplorer<br />
LDAP<br />
DAP<br />
DSP<br />
DISP<br />
SSL<br />
TLS<br />
SNMP<br />
CMIP<br />
DXconsole<br />
DSML<br />
SAML<br />
SPML<br />
Web Services<br />
Examples<br />
UDDI Server<br />
LDAP<br />
telnet<br />
UDDI<br />
DXmanager<br />
LDAP<br />
DXserver<br />
SQL<br />
Ingres<br />
Database<br />
HTTP<br />
JXweb<br />
UDDI Client<br />
Config<br />
. Files<br />
DAP<br />
SQL<br />
DXwebserver<br />
LDAP<br />
DXadmind<br />
SSLD<br />
DXtools<br />
DXserver<br />
The DXserver process uses highly efficient techniques for managing directory<br />
information and processing the directory protocols. The <strong>eTrust</strong> <strong>Directory</strong><br />
supports the following protocols:<br />
Protocol<br />
LDAP<br />
DAP (X.511)<br />
DSP (X.518)<br />
DISP (X.525)<br />
CMIP (X.700)<br />
SNMP<br />
Description<br />
Lightweight <strong>Directory</strong> Access Protocol<br />
<strong>Directory</strong> Access Protocol<br />
<strong>Directory</strong> System Protocol<br />
<strong>Directory</strong> Information Shadowing Protocol<br />
Common Management Information Protocol<br />
Simple Network Management Protocol<br />
The DSA fully supports all mandatory requirements of the approved protocols.<br />
See the appendix Supported Standards in the <strong>eTrust</strong> <strong>Directory</strong> Getting Started<br />
guide for a list of all standards supported by <strong>eTrust</strong> <strong>Directory</strong>.<br />
1–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>eTrust</strong> <strong>Directory</strong> Modules<br />
The Relational Database Management System (RDBMS)<br />
The RDBMS stores and maintains the <strong>Directory</strong> Information Base (DIB) within<br />
specially designed tables. Each DIT or DIB image stores its own set of tables in<br />
the RDBMS’s portion of the file system.<br />
The RDBMS contributes to the performance, reliability, and management of the<br />
DXserver system with the following features:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Caching<br />
Query optimization<br />
Multiprocessing and locking<br />
Check-pointing and recovery<br />
International character sets and collating sequences<br />
Database table and indexing management<br />
Housekeeping and tuning utilities<br />
Unlike other X.500 and LDAP implementations, particularly in-memory<br />
implementations, the DXserver does not load directory information and other<br />
indexes into memory on startup, unless DXcache is configured. See the chapter<br />
“General Administration” for more information about DXcache.<br />
Configuration Files<br />
When a DSA starts up, it initializes with commands stored in configuration files.<br />
The configuration files are organized into logical groups corresponding to their<br />
function (for example, logging, schema, knowledge).<br />
DXtools<br />
The DXtools provide general data management facilities, including:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Managing databases<br />
Tuning and backing up directory data<br />
Importing and exporting directory data<br />
Bulk loading databases from a prepared LDIF file<br />
Bulk extracting a database to an LDIF file for comparison<br />
LDIF sorting and comparison<br />
For descriptions of these tools, see the chapter "Using DXtools".<br />
Introduction 1–3
<strong>eTrust</strong> <strong>Directory</strong> Modules<br />
Samples<br />
A number of sample configurations and utilities are provided for testing and<br />
demonstration purposes. These reside in the ../dxserver/samples subdirectories:<br />
Subdirectory<br />
cmip<br />
democorp<br />
dua<br />
dxtoolsgui<br />
ldua<br />
router<br />
schema<br />
snmp<br />
soak<br />
ssl<br />
test<br />
trap<br />
unspsc<br />
Purpose<br />
An executable to request CMIP counters from the directory.<br />
DemoCorp example, run the setup script to automatically<br />
configure the DemoCorp DSA.<br />
Sample text-based <strong>Directory</strong> User Agent (DUA) that runs<br />
over DAP<br />
Java GUI interface to the DXtools—run dxtoolsgui.bat on<br />
Windows or dxtoolsgui.sh on UNIX.<br />
Note: This requires Java Runtime Environment (JRE).<br />
Sample text-based DUA that runs over LDAP<br />
An example router DSA that does not use a database and has the<br />
prefix c = AU, and is aware of the DemoCorp and UNSPSC DSAs.<br />
A Perl schema translation tool to update schema.txt for the<br />
DXtools<br />
An executable to request SNMP information from the directory.<br />
An executable to measure the throughput (in searches per<br />
second) of a DSA.<br />
Examples of using DUA-DSA and DSA-DSA SSL<br />
authentication and encryption.<br />
A selection of <strong>Directory</strong> scripts to modify the directory<br />
using the supplied DUA or LDUA clients. Run the setup<br />
script to automatically configure the Test DSA and execute<br />
the DUA and LDUA client scripts.<br />
Information and an example program that can receive<br />
triggers from the directory.<br />
United Nations Standard Product and Services Classification<br />
(UNSPSC) Code System. Run the setup script to automatically<br />
configure the UNSPSC DSA and populate it with UNSPSC data.<br />
For more information see .../dxserver/samples/README.TXT, and the<br />
README.TXT files within each sample sub-directory.<br />
1–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>eTrust</strong> <strong>Directory</strong> Modules<br />
RDBMS Tools<br />
The RDBMS tools provide support for the RDBMS. See the Advantage Ingres<br />
product documentation set for further details.<br />
DXwebserver<br />
The DXwebserver enables access to the DXserver process through web-based<br />
GUIs, including:<br />
DXmanager<br />
A graphical, web-based <strong>eTrust</strong> <strong>Directory</strong> administration tool<br />
JXweb<br />
A graphical web-based LDAP directory browser and editor<br />
UDDI Client<br />
A graphical web-based browser for a UDDI Server<br />
You can also create your own web-based GUIs to suit your organization.<br />
Three technology previews are also provided for testing and demonstration<br />
purposes. These reside in the ../dxwebserver/samples subdirectories:<br />
democorp<br />
This is a version of JXweb that has been customized to work well with the<br />
fictional company Democorp.<br />
dsml<br />
This is a sample DSML server that converts DSML to LDAP and vice versa.<br />
This allows client applications that use DSML (including web services) to<br />
communicate with <strong>eTrust</strong> <strong>Directory</strong> without using LDAP directly.<br />
uddi<br />
This is a demonstration of a typical application of a UDDI server. It shows a<br />
web site that compares prices on airline flights by looking up the prices on<br />
different web servers, which are registered with a UDDI server.<br />
Each sample includes a Readme that describes how to install the sample.<br />
Introduction 1–5
<strong>eTrust</strong> <strong>Directory</strong> Glossary<br />
<strong>eTrust</strong> <strong>Directory</strong> Glossary<br />
This section defines some terms that are commonly used in this guide.<br />
Attribute<br />
Entries are comprised of attributes. Each attribute consists of a type and a<br />
value.<br />
For example, in a staff directory, each entry would include attributes that<br />
defines the person’s name, phone number, office location, etc.<br />
Distinguished name (DN)<br />
A name that uniquely identifies an entry. The DN includes the name of the<br />
entry, plus the names of all superior entries and domains. Thus, the DN<br />
identifies the entry, and its location within the directory information tree<br />
(DIT).<br />
<strong>Directory</strong> system agent (DSA)<br />
A hierarchy of parent-child entries, built from the data stored in the<br />
directory. One unified directory might actually consist of many linked DSAs.<br />
<strong>Directory</strong> system protocol (DSP)<br />
A server-to-server protocol used by X.500 for distributed operations. This is<br />
the protocol used for chaining. LDAP does not have a DSP equivalent.<br />
Entry<br />
The basic unit of information storage in a directory. All information in a<br />
directory is stored in the form of entries. Also sometimes named objects.<br />
For example, in a directory listing all staff members at a company, each staff<br />
member would have an entry.<br />
Latency<br />
The delay caused by the round-trip time taken between sending a network<br />
packet and receiving a response.<br />
Multiwrite<br />
A mechanism for replicating updates to a number of DSAs to ensure they are<br />
synchronized. When DXserver receives an update, this will be written to<br />
itself and then its peers. If a peer DSA cannot be reached, the updates will be<br />
queued and replayed when the DSA becomes available.<br />
Multiwrite groups<br />
Tiered replication will be implemented using multi-write groups. DSAs on<br />
either side of a slow link (e.g. different continents) can be grouped.<br />
Replication will occur in the group and sent to elected hubs from another<br />
group asynchronously.<br />
Namespace<br />
A namespace is a set of names in which all names are unique. Each name<br />
contains enough information to identify where the named entry appears in<br />
the structure of all entries.<br />
1–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>eTrust</strong> <strong>Directory</strong> Glossary<br />
Replicating hub<br />
In a tiered replication scheme, a hub given responsibility for cascading<br />
updates to its peers. The DSA that originated the update offloads replicating<br />
responsibility to the hub.<br />
Schema<br />
A formal definition of the contents and structure of the directory data. This<br />
governs where each entry can be placed within the directory structure, how<br />
entries are to be named, and what attributes each entry can contain.<br />
Tiered replication<br />
During normal replication of an update, an entity will cycle through and<br />
update all mates. In a tiered model the update will be passed on to a mate<br />
outside the group, which will write to its mates.<br />
Introduction 1–7
Chapter<br />
2<br />
DXserver Overview<br />
This chapter describes how the <strong>eTrust</strong> <strong>Directory</strong> server component works.<br />
What is DXserver?<br />
The <strong>eTrust</strong> <strong>Directory</strong> server component is named DXserver.<br />
DXserver can be operated as a directory in a standalone mode similar to other<br />
LDAP servers. DXserver can also be configured to operate in a distributed<br />
environment as a full featured X.500 <strong>Directory</strong> System Agent (DSA) supporting<br />
all the powerful X.500 features such as chaining, parallel searching, distributed<br />
management and advanced security.<br />
DXserver supports many communications protocols and management facilities,<br />
including:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
User access protocols (DAP, LDAP)<br />
System (inter server) protocols (DSP, DISP)<br />
Management protocols (SNMP, CMIP)<br />
Input commands (from script files or management console)<br />
Logging Services (alarms, traces, management responses)<br />
DXserver Overview 2–1
DXserver Configuration Files<br />
DXserver Configuration Files<br />
DXserver stores configuration information in a structured directory tree. The<br />
easy-to-use, hierarchical tree defines the conventions and the strategy for<br />
managing the directory system that can extend to multiple servers, multiple<br />
machines, and multiple platforms.<br />
The configuration files should be managed from a central station. The directories<br />
are shared across all servers to ensure consistency in system operation. This<br />
architecture also lets you manage version of the configuration files, because you<br />
can store these files in a document or source control system.<br />
DXserver File Directories<br />
After installation, DXserver uses the following directories:<br />
DXserver<br />
|__ bin<br />
|__ config<br />
| |__ access<br />
| |__ autostart (UNIX only)<br />
| |__ database<br />
| |__ knowledge<br />
| |__ limits<br />
| |__ logging<br />
| |__ replication<br />
| |__ schema<br />
| |__ servers<br />
| |__ settings<br />
| |__ ssld<br />
|__ logs<br />
|__ samples<br />
|__ pid<br />
|__ install (UNIX only)<br />
|__ uninstall (UNIX only)<br />
bin<br />
This directory holds all binary executables and batch files for the product.<br />
config<br />
This directory holds the current configuration files, and some Readme files<br />
for your reference. DXserver always starts with the configuration<br />
information stored in this directory. We recommend that you give read-only<br />
permissions to files in these directories to prevent accidental overwriting.<br />
Each subdirectory contains the configuration file(s) that deal with a<br />
component of the DXserver configuration.<br />
access<br />
Access control rules.<br />
autostart<br />
(UNIX only) DXserver uses the autostart directory to track the servers<br />
that must start at the same time as the operating system.<br />
2–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Configuration Files<br />
database<br />
Database name information.<br />
knowledge<br />
Access-point information for all DSAs.<br />
limits<br />
Administrative limits, such as size limits and time limits.<br />
logging<br />
Trace levels and log file names.<br />
replication<br />
Replication agreements.<br />
schema<br />
Schema definitions.<br />
servers<br />
Startup information for each server. An initialization file must exist for<br />
each defined DSA.<br />
settings<br />
Operational settings and controls.<br />
ssld<br />
Trusted <strong>CA</strong> and server certificates.<br />
logs<br />
This directory is the default log output directory for DXserver, which<br />
generates all log files at this location unless you specify another directory.<br />
samples<br />
This directory contains demonstration utilities and test script files. Each<br />
sample has its own subdirectory and associated README file.<br />
pid<br />
This directory is for DXserver use only, and contains information about<br />
currently running processes. The pid directory does not contain any files<br />
after an installation, but when the services are run, files are created in that<br />
directory.<br />
install<br />
(UNIX only) This directory is for DXserver use only, and contains installation<br />
files and environment information.<br />
uninstall<br />
(UNIX only) This directory contains uninstallation scripts..<br />
DXserver Overview 2–3
DXserver Configuration Files<br />
Sample Configuration Files<br />
DXserver contains a working example DSA configuration. You can use the<br />
example server without modification as described in the appendixes “Installing<br />
DXserver for Windows” and “Installing DXserver for UNIX.” The example<br />
contains three DXserver configurations—Router, DemoCorp and UNSPSC.<br />
Configuration File Types<br />
You can identify file types within the directory configuration structure by their<br />
file name extensions. It is important to use the correct file name extensions when<br />
creating new files.<br />
Use the following file types in a DXserver configuration set:<br />
Extension File type Description<br />
.dxc Configuration Contains one or more commands that set<br />
configuration parameters.<br />
.dxg Group Groups a selection of one or more .dxc<br />
files (in the current directory) using the<br />
DXserver source command.<br />
.dxi Initialization DXserver initialization file. A .dxi file<br />
contains commands to source other (.dxg<br />
and .dxc) files.<br />
.dxs Script Contains commands supported by the<br />
DXcli. You usually use script files for<br />
testing.<br />
2–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Configuration Files<br />
The Initialization File<br />
Each server’s initialization file sources (refers to and reads) selected files from the<br />
config subdirectories.<br />
Important points to notice are:<br />
■<br />
■<br />
The initialization file is a template in which the DSA sources a single file<br />
from each of the config subdirectories appropriately.<br />
You can organize the contents of the config directories as required—from<br />
one file to many files—typically creating a specific file in each of the config<br />
directories for each new DSA definition.<br />
Here is the DemoCorp initialization file:<br />
# Computer Associates DXserver/config/servers<br />
#<br />
# DXserver initialization file.<br />
#<br />
# logging and tracing<br />
close summary-log;<br />
close trace-log;<br />
source "../logging/default.dxc";<br />
# schema<br />
clear schema;<br />
source "../schema/default.dxg";<br />
# access controls<br />
clear access;<br />
# source "../access/";<br />
# knowledge<br />
clear dsas;<br />
source "../knowledge/sample.dxg";<br />
# operational settings<br />
source "../settings/default.dxc";<br />
# service limits<br />
source "../limits/default.dxc";<br />
# database<br />
source "../database/democorp.dxc";<br />
# replication agreements (rarely used)<br />
# source "../replication/";<br />
DXserver Overview 2–5
DXserver Configuration Files<br />
Configuration Grouping Files<br />
Each component directory can consist of one or more configuration (.dxc) files.<br />
For complex configurations typically involving multiple DSAs, you might need a<br />
number of configuration files, grouped in a convenient manner using grouping<br />
(.dxg) files:<br />
Group 1 Group 2<br />
commands A commands B commands C<br />
As an example, suppose the DSAs TestCorp1, TestCorp2, and TestCorp3 all<br />
require the schema files x500.dxc, cosine.dxc, and inetop.dxc. Rather than<br />
“sourcing” each of these files from each of the DSA initialization files, it is more<br />
convenient to create a TestCorp.dxg file containing the following lines:<br />
source “x500.dxc”;<br />
source “cosine.dxc”;<br />
source “inetop.dxc”;<br />
Each DSA initialization file would then contain the following line:<br />
source “../schema/TestCorp.dxg”;<br />
The advantage of this approach is that, if these DSAs require additional schema,<br />
only a single file—TestCorp.dxg—needs editing.<br />
Reasons for grouping files are:<br />
■<br />
■<br />
To present a view that abstracts any internal organization within the<br />
component<br />
To manage ordering of the configuration files—especially important in<br />
schema where definitions in one file depend on definitions in another file<br />
Typically the schema and knowledge files are grouped.<br />
2–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Configuration Files<br />
Knowledge Files<br />
This section describes what knowledge files are, and how to use them.<br />
Knowledge files are text files that include commands that affect how DSAs work.<br />
Each DSA has a single knowledge file, which is named dsaname.dxc, where<br />
dsaname is the case-insensitive name of the DSA. These knowledge files are kept<br />
in the config/knowledge directory.<br />
Each DSA must source its own knowledge file, which includes what operations<br />
from remote DSAs are to be permitted or denied.<br />
Each DSA can also source the knowledge files for other, remote DSAs. These files<br />
define how the local DSA works with the remote DSA.<br />
For information about knowledge flags, see Knowledge Flags in the chapter<br />
General Administration.<br />
Using Knowledge Files in a Single-Server Environment<br />
If your directory includes more than one DSA, you need to consider how you<br />
work with your knowledge files.<br />
If all of the DSAs happen to be one the same computer, they can all source the<br />
same copy of the knowledge files.<br />
Server A<br />
Router DSA<br />
router.dxc<br />
unspsc.dxc<br />
democorp<br />
.dxc<br />
Democorp<br />
DSA<br />
UNSPSC DSA<br />
Three DSAs on one server, sharing the same knowledge files<br />
DXserver Overview 2–7
DXserver Configuration Files<br />
Using Knowledge Files in a Distributed Environment<br />
However, it is more likely that the DSAs in a distributed system are on different<br />
computers. To make sure that operations are not slowed down by network<br />
limitations, each DSA should use its own local copy of the knowledge files.<br />
We recommend that you make any changes to only one of these sets of<br />
knowledge files, and then copy the changed files to the other locations.<br />
This will help you keep the knowledge files synchronized.<br />
For example, in the system shown here, you could use the knowledge files on<br />
Server A as the master copies. Whenever you need to change a knowledge file,<br />
you would make the change on Server A. You could then copy the changed files<br />
to the other two servers.<br />
Server A<br />
router.dxc<br />
Router DSA<br />
unspsc.dxc<br />
democorp<br />
.dxc<br />
Democorp<br />
DSA<br />
Server B<br />
router.dxc<br />
unspsc.dxc<br />
democorp<br />
.dxc<br />
UNSPSC DSA<br />
Server C<br />
router.dxc<br />
unspsc.dxc<br />
democorp<br />
.dxc<br />
Three DSAs on separate servers, using local copies of the same knowledge files<br />
2–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Commands<br />
DXserver Commands<br />
When a server starts up, it reads an initialization file (.dxi) from the servers<br />
subdirectory. The initialization file name is derived from the DSA name. For<br />
example, democorp.dxi defines a DSA named DemoCorp. Thus, the following<br />
command causes DXserver to search the servers subdirectory for a file called<br />
democorp.dxi:<br />
dxserver start democorp<br />
When found, it is read and the commands are executed (usually instructions to<br />
read other files in the other subdirectories of the config tree).<br />
See the appendixes “Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows” and “Installing<br />
<strong>eTrust</strong> <strong>Directory</strong> for UNIX” for information about starting and stopping a<br />
DXserver process.<br />
The dxserver Command - Install, Start, or Stop the DXserver<br />
You can run the DXserver from the command line using the following command:<br />
dxserver options<br />
Important! You must start the RDBMS before starting DXserver. If an error occurs<br />
while reading the configuration files, DXserver cannot start. You can find information<br />
about this error in both the operating system error log and the DXserver alarm and trace<br />
log files in the dxserver/logs directory.<br />
The options of the dxserver command are:<br />
Option<br />
init serverName<br />
init all<br />
install serverName<br />
Meaning<br />
Signals serverName to reread its configuration files (if<br />
running). For example:<br />
dxserver init democorp<br />
Signals all DSAs to reread its configuration files<br />
Adds serverName to the list of servers to start at system<br />
startup. For example:<br />
dxserver install democorp<br />
Note: On Windows, the dxserver start command implicitly<br />
installs <strong>eTrust</strong> <strong>Directory</strong><br />
remove serverName<br />
start serverName<br />
Removes serverName from the auto-startup list, for example:<br />
dxserver remove democorp<br />
Starts the DXserver serverName. For example:<br />
dxserver start democorp<br />
DXserver Overview 2–9
DXserver Commands<br />
Option<br />
start all<br />
status serverName<br />
Meaning<br />
Starts all DSAs.<br />
Reports the running status of serverName. For example:<br />
dxserver status democorp<br />
If you omit the serverName, the status of all servers is<br />
reported.<br />
stop serverName<br />
stop all<br />
version<br />
Stops the DXserver serverName. For example:<br />
dxserver stop democorp<br />
Stops all DSAs<br />
Displays version information<br />
2–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Script Language<br />
DXserver Script Language<br />
You can use the DXserver commands to control every aspect of DXserver<br />
operation. The DSA supports an extensive set of configuration and management<br />
commands that you can use in configuration files or enter interactively through<br />
the management console.<br />
The complete command language is defined in the appendix “DXserver<br />
Command Language.”<br />
You can organize commands into script files. Script files have the following<br />
general uses:<br />
■<br />
■<br />
■<br />
■<br />
Configuration—A group of DSAs can share the same configuration<br />
information.<br />
Prototyping—X.500 operations you can automate.<br />
Testing—The command language supports conditional statements.<br />
Shortcuts—Storage of often used commands.<br />
Configuration Files<br />
In order to describe the large number of DXserver commands, you can separate<br />
commands into individual files according to their function. These separate files<br />
should then reside in the appropriate config subdirectory.<br />
A description of each set of related commands is in subsequent chapters:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
General administrative commands—see the chapter “General<br />
Administration”<br />
Schema commands—see the chapter “Schema Definition”)<br />
DSA and distribution commands—see the chapter “Distribution and DSP”<br />
Security commands—see the chapter “Security”<br />
Replication commands—see the chapter “Replication”<br />
X.500 commands—see the appendix “DXconsole DUA”<br />
DXserver Overview 2–11
DXserver Script Language<br />
Command Syntax<br />
Typically, commands have one of the following formats:<br />
■<br />
■<br />
■<br />
set item = value;<br />
get item;<br />
action parameters;<br />
Some commands are hyphenated (for example, add-entry-req). You can spread<br />
each command over many lines. You must terminate each command with a<br />
semicolon.<br />
You do not need to quote simple (one-word) strings. You must quote more<br />
complex (many-word) strings. Within a quoted string, you can use a backslash<br />
(\) as an escape mechanism for the following cases:<br />
Case Example String<br />
Quote my “favorite” car "my \"favorite\" car"<br />
Backslash c:\myfile "c:\\myfile"<br />
Hex number touché "Touch\xC2e"<br />
There is often a need to specify attribute values in character sets other than<br />
ASCII. For example, you can perform the following modification:<br />
mod-entry-req entry= add-attr { description "a description" };<br />
But how is this done in other languages?<br />
LDAPv3 has standardized on UTF-8 for internationalization. An example, using<br />
UTF-8, is now:<br />
mod-entry-req entry= add-attr { description utf8 "touch\xC3\xA9" };<br />
The Latin-1 character e-acute (E9) in UTF-8 (C3A9) has been encoded. The<br />
following example would search for all entries with common names beginning<br />
with e-acute.<br />
search-req base-object= whole-subtree filter = { attr = commonName substrings [<br />
initial utf8 "\xC3\xA9" };<br />
Commands can continue over multiple lines. If you enter an incomplete<br />
command at the management console, a continuation prompt, as shown below,<br />
displays until you enter a semicolon:<br />
---><br />
Tip: You can interrupt the execution of a script file from the management<br />
console using the telnet commands Ctrl-c or Ctrl-x. (See DXconsole in this<br />
chapter.)<br />
2–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Script Language<br />
Script Files<br />
Script files store frequently used or complex commands (such as schema<br />
initialization commands). You can then execute these files from the management<br />
console or from inside other command files using the command:<br />
source "script-file";<br />
or the short form of the command:<br />
! "script-file";<br />
Tip: A configuration file (.dxi, .dxc, or .dxg) is a special form of script file.<br />
Within a script file, the # sign introduces a comment. DXserver treats the # and<br />
all text after it, to the end of the line, as a comment.<br />
A script file can source other script files. The source command is relative to the<br />
file that invokes it. For example, when you source the file schema.dxg using the<br />
command:<br />
source "../schema/schema.dxg";<br />
then the schema.dxg script can source a file in its own directory using the<br />
command:<br />
source "attr.dxc";<br />
Script File Errors and Debugging<br />
Usually the system does not echo commands in script files before they are<br />
executed. If there is an error in the script file, a message similar to the following<br />
is displayed:<br />
>>>> set allow-binds = 1;<br />
-----------------------^ (line 12 in ‘test.dxc’)<br />
Syntax Error: Expected ‘true’ or ‘false’<br />
Tip: To obtain a full log of every command executed in a script file, set the<br />
first lines of the script file to:<br />
echo-on;<br />
set trace-file = "script.log";<br />
After running the script file, you can examine the log file to locate any failed<br />
command and the reason for the failure.<br />
DXserver Overview 2–13
DXconsole<br />
DXconsole<br />
The management console, DXconsole, lets you enter commands interactively. It<br />
lets you monitor users, modify administrative controls, and perform actions.<br />
DXconsole also includes a powerful co-resident directory client (DUA)<br />
command-line interface, which you can use to enter user queries for diagnostic<br />
or prototyping tasks.<br />
For more information about the DUA, see the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer<br />
<strong>Guide</strong>.<br />
DXconsole Security<br />
For security reasons, DXconsole is only accessible from the local computer.<br />
The management console only accepts one telnet session. To prevent anyone else<br />
from starting up DXconsole, make sure you keep DXconsole always running.<br />
To prevent attacks from remote telnet sessions, define a console port in the DSA<br />
knowledge. This scheme uses the local host security. An administrator must have<br />
an account on the local computer to communicate with the DSA through this<br />
port.<br />
You can use the console remotely when you set the remote-console-port flag. You<br />
can attach a password, and SSL may be required. See Configuring DXconsole for<br />
more information.<br />
Opening DXconsole<br />
Open DXconsole<br />
To open DXconsole, use the telnet command to connect to the local host with<br />
the console-port number:<br />
% telnet localhost 19390;<br />
Trying 127.0.0.1...<br />
Connected to localhost.<br />
Escape character is ‘^]’.<br />
Welcome to the DSA Management Console<br />
dsa><br />
Open Remotely<br />
To open DXconsole remotely, use the telnet command to connect to the remote<br />
machine with the remote-console-port:<br />
% telnet eagle 19392<br />
Note: You should enable local echo on the local telnet client.<br />
2–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXconsole<br />
Closing DXconsole<br />
Close DXconsole<br />
The usual way to close DXconsole is to log out. This closes the telnet session<br />
from the DSA:<br />
dsa> logout;<br />
Close Locally<br />
You can close DXconsole locally from the local telnet session:<br />
<br />
telnet> quit<br />
The telnet session closes automatically when the DSA shuts down.<br />
DXserver Overview 2–15
DXconsole<br />
Configuring DXconsole<br />
DXconsole can be enabled either locally or remotely.<br />
The remote DXconsole provides the DSA administrator with a means of<br />
managing the DSA. The access protocol is telnet. To remotely manage a DSA<br />
using DXconsole, either log on to the machine running the DSA and open<br />
DXconsole using the console port, or use a remote telnet connection that uses the<br />
remote console port.<br />
Window<br />
telnet<br />
DSA<br />
By default, DXconsole is only accessible from localhost for security reasons.<br />
To enable DXconsole, you must define the console port in the knowledge file of<br />
the DSA. For more information, see the section Defining DSAs in the chapter<br />
“General Administration.”<br />
For a list of all ports in a default installation of <strong>eTrust</strong> <strong>Directory</strong>, see the section<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter DXserver Overview.<br />
2–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXconsole<br />
The DXconsole Command Options<br />
To configure DXconsole, include the following options in the DSA knowledge<br />
file:<br />
Option Parameter Description<br />
console-port Port number Allows DXconsole to accept connections from the local computer.<br />
When this is not specified, the DSA does not have a local console.<br />
remote-console-port Port number Allows DXconsole to accept a connection from a remote<br />
computer on this port. When this is not specified, there is no<br />
remote console for the DSA.<br />
console-password Password The password required for connections from a remote computer.<br />
This password is transmitted in clear text.<br />
remote-console-ssl Boolean Forces DXconsole to encrypt sessions when it runs remotely.<br />
Configuring DXconsole to Run Locally<br />
To enable DXconsole locally, use the following command:<br />
set dsa dsaname =<br />
{<br />
...<br />
console-port = port_number<br />
...<br />
};<br />
DXconsole: Local<br />
Configuration<br />
In the following sample configuration, the line console-port = 19390 defines the<br />
port that DXconsole will use to accept connections from the same machine only:<br />
set dsa DEMOCORP =<br />
{<br />
prefix = <br />
dsa-name = <br />
dsa-password = "secret"<br />
address = tcp "hostname.ca.com" port 19389<br />
disp-psap = DISP<br />
cmip-psap = CMIP<br />
snmp-port = 19389<br />
console-port = 19390<br />
ssld-port = 1112<br />
auth-levels = anonymous, clear-password, ssl-auth<br />
trust-flags = allow-check-password, trust-conveyed-originator<br />
};<br />
DXserver Overview 2–17
DXconsole<br />
Configuring DXconsole to Run Remotely<br />
You can connect to DXconsole from a remote computer, using a password for<br />
authentication. This is configured by adding the "remote-console-port = 19395"<br />
and "console-password = "password"" lines to the DSA knowledge file.<br />
Although this method allows remote access and some security, the password<br />
that is sent to DXconsole from the client is transmitted in clear text. This poses a<br />
moderate security risk on unsecured networks.<br />
To provide security, you can specify a console password. When this is set, the<br />
user is prompted for a password before a connection is made.<br />
Important! If you do not want the password to be displayed when it is entered, you must<br />
turn local echo OFF on the telnet session.<br />
To enable DXconsole remotely, use the following commands:<br />
set dsa dsaname =<br />
{<br />
...<br />
remote-console-port = port_number<br />
console-password = password_string<br />
...<br />
};<br />
DXconsole: Remote<br />
Configuration<br />
set dsa DEMOCORP =<br />
{ prefix = <br />
dsa-name = <br />
dsa-password = "secret"<br />
address = tcp "hostname.ca.com" port 19389<br />
disp-psap = DISP<br />
cmip-psap = CMIP<br />
snmp-port = 19389<br />
console-port = 19390<br />
remote-console-port = 19395<br />
console-password = "password"<br />
ssld-port = 1112<br />
auth-levels = anonymous, clear-password, ssl-auth<br />
trust-flags = allow-check-password, trust-conveyed-originator<br />
};<br />
2–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXconsole<br />
Configuring DXconsole to Run Securely and Remotely<br />
You can force the remote console connection to run over TLS by adding the<br />
"remote-console-ssl = true" line to the DSA knowledge file. This ensures that<br />
console commands and passwords are not transmitted in-the-clear over public<br />
networks.<br />
Only one console session can be active at any one time, even if both the consoleport<br />
and remote-console-port flags are set.<br />
To force DXconsole to use SSL/TLS when it is running remotely, add the<br />
following settings:<br />
set dsa dsaname =<br />
{<br />
...<br />
remote-console-port = port_number<br />
remote-console-ssl = true<br />
console-password = password_string<br />
...<br />
}<br />
DXconsole: Secure<br />
Remote<br />
Configuration<br />
In the following sample configuration, the console is running remotely, and<br />
SSL-encrypted:<br />
set dsa DEMOCORP =<br />
{ prefix = <br />
dsa-name = <br />
dsa-password = "secret"<br />
address = tcp "hostname.ca.com" port 19389<br />
disp-psap = DISP<br />
cmip-psap = CMIP<br />
snmp-port = 19389<br />
console-port = 19390<br />
remote-console-port = 19395<br />
remote-console-ssl = true<br />
console-password = "password"<br />
ssld-port = 1112<br />
auth-levels = anonymous, clear-password, ssl-auth<br />
trust-flags = allow-check-password, trust-conveyed-originator<br />
};<br />
DXserver Overview 2–19
DXconsole<br />
Testing the Secure Remote DXconsole Using TLSclient<br />
The TLSclient utility establishes an encrypted tunnel between the remote console<br />
client and the DSA. The steps to configure the DSA and TLSclient are as follows:<br />
1. Create the TLSclient configuration file on the client machine<br />
2. Configure the DSA for SSL connections to DXconsole on the server machine<br />
3. Start TLSclient on the client<br />
4. Start the DSA on the server<br />
5. Test the connection<br />
Create the TLSclient<br />
Configuration File<br />
To configure TLSclient, you will need to create the following file on the client<br />
machine:<br />
■<br />
■<br />
Windows: %DXHOME%\config\tlsclient\tlsclient.cfg<br />
UNIX: $DXHOME/config/tlsclient/tlsclient.cfg<br />
This implies that <strong>eTrust</strong> <strong>Directory</strong> is also installed on the client machine,<br />
although this may not be required. The only requirement should be that the<br />
environment variable DXHOME is set and the trusted root certificate is available.<br />
The format for tlsclient.cfg is:<br />
inPort outPort remoteAddress<br />
Where inPort is the port on the client machine that will be used for tunneling,<br />
outPort is the DXconsole remote-console-port on the server and remoteAddress<br />
is the hostname of the server running the DXconsole you wish to connect to.<br />
Here is an example for the sample DemoCorp DSA running on the server<br />
machine:<br />
19390 19395 hostname.ca.com<br />
Start TLSclient<br />
TLSclient can be installed to the system services using the command:<br />
tlsclient install -ca <br />
Here is an example for the DemoCorp DSA:<br />
tlsclient install democorp -ca config/ssld/trusted.pem<br />
You can then start the TLSclient instance with:<br />
tlsclient start <br />
For the DemoCorp DSA example, this would be:<br />
tlsclient start Democorp<br />
2–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXconsole<br />
Starting DXserver<br />
Testing the<br />
connection<br />
To start DXserver, do the following:<br />
1. Ensure that the DSA is stopped using: dxserver stop dsaname<br />
2. Start the DSA using: dxserver start dsaname<br />
To test this connection, do the following:<br />
1. Open the DXconsole client, or your favourite Telnet program, on the client<br />
machine<br />
2. Connect to the inPort (defined in tlsclient.cfg) on the local machine (19390 in<br />
the DemoCorp sample)<br />
3. Enter the DXconsole password when prompted<br />
You now have a fully-functioning SSL-encrypted connection to DXconsole on the<br />
server machine.<br />
To verify this, start TLSclient with the debug option, or set "trace all;" on the<br />
DSA, or use a packet-snooping application.<br />
Help Command<br />
The help command lists the outer-level commands for the DSA administration<br />
modules, X.500 services, and management scripts.<br />
When you enter the help command at the console, the response is similar to:<br />
Enter one of the following keywords:<br />
(modules)<br />
trace, log, stack, assoc, oper, schema, dsp, disp,<br />
dib, access<br />
(services) bind-req, unbind-req, abort-req, abandon-req,<br />
read-req, compare-req, list-req, search-req,<br />
add-entry-req, rem-entry-req, mod-entry-req, mod-dn-req<br />
(scripts) open-log, close-log, flush-log, source, !,<br />
echo, echo-on, echo-off, wait, if-reply, goto<br />
When you are not sure of the syntax, try a nonsense word for the missing part, or<br />
leave the command incomplete and let the resulting error message tell you what<br />
is expected:<br />
>>>> oper get fred;<br />
-----------------^<br />
Syntax Error: Expecting “config” or “stats”.<br />
DXserver Overview 2–21
DXconsole<br />
Command Shortcuts<br />
If you frequently use a command, or a set of commands, then store the<br />
commands in a file and execute that file. For example, a script file called List can<br />
contain the following command:<br />
list-req entry = ;<br />
You can execute it from DXconsole using the command:<br />
dsa> !list;<br />
2–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Databases<br />
Databases<br />
<strong>eTrust</strong> <strong>Directory</strong> consists of two major components. These are the DSA process<br />
and its underlying database. The DSA process is the X.500/LDAP directory<br />
object and protocol processing system and the database is used to store and<br />
retrieve the dismantled directory objects (entries) in the specially designed<br />
database tables.<br />
You can use the DSA process as a router engine, or configure it to be responsible<br />
for a portion (or all) of the DIT. When a DSA process is not acting just as a<br />
directory protocol router (for distribution or alternate, load balancing DSAs), it<br />
should be considered as a process that is responsible for a DIT Namespace.<br />
Set Database Name<br />
When starting, the DSA process needs to know the name of the database it<br />
should access. This value is usually set in a database initialization file using the<br />
command:<br />
set database-name = databaseName;<br />
where databaseName is the name of an RDBMS database.<br />
See The <strong>Directory</strong> Information Base in the chapter “General Administration” for<br />
more information about setting database names.<br />
Multiple DSA Processes to One DIT/DIB<br />
More than one DSA can access the same X.500 DIT/DIB database (for example,<br />
to provide load sharing and increased user counts). There is no possibility of<br />
database inconsistency because the database management system enforces full<br />
locking controls.<br />
When multiple DSAs on the same machine access the same database, you must<br />
configure each DSA with unique listening addresses within their knowledge<br />
files. For more information, see the section Defining DSAs in the chapter<br />
“General Administration”.<br />
DXserver Overview 2–23
Databases<br />
Multiple <strong>Directory</strong> Databases on One Machine<br />
A single machine can host many discrete directory images. This is useful for<br />
testing on separately managed production and testing databases or for<br />
partitioning your directory into separate databases.<br />
Hot Swap<br />
Change Database<br />
Name While DSA<br />
Active<br />
You can change the database name while the DSA is active without<br />
disconnecting or disrupting directory clients, using the following command:<br />
set database-name = newdb;<br />
where newdb is the name of another RDBMS database, which must already<br />
exist.<br />
You can switch to a newly reorganized database, a hot standby copy, or a<br />
restored copy by using the hot swap of a database.<br />
2–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong><br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong><br />
This section lists the port numbers used in a default <strong>eTrust</strong> <strong>Directory</strong> installation.<br />
If one of these port numbers is also used by another application on the same<br />
computer, you may need to change the port number used by <strong>eTrust</strong> <strong>Directory</strong>.<br />
Most of the port numbers listed here are configurable.<br />
Ports Used by <strong>eTrust</strong> <strong>Directory</strong> Components<br />
The following table lists the port numbers used by the <strong>eTrust</strong> <strong>Directory</strong><br />
components in a default installation.<br />
Component<br />
DXwebserver<br />
(Tomcat)<br />
Protocol Port<br />
Number<br />
Description of Port<br />
TCP 8080 The port on which Tomcat<br />
listens for requests.<br />
If you change this, the<br />
DSML, SAML, and SPML<br />
samples won’t work.<br />
SSLD TCP 1112<br />
iTechPoz<br />
data DSA<br />
UDDIV3 data<br />
DSA<br />
TCP 8005 The port on which Tomcat<br />
listens for the shutdown<br />
command<br />
TCP 8009 The Coyote/JK2 1.3<br />
connector port<br />
TCP 8443 The port to which SSL<br />
requests are redirected if<br />
they come in on a non-SSL<br />
port<br />
1113<br />
The listen ports which<br />
DXserver uses when<br />
connecting to SSLD<br />
Accepts<br />
SSL<br />
Requests<br />
No<br />
Yes<br />
Yes<br />
UDP 509 SNMP port No<br />
TCP 509 DSA listen address port Yes<br />
TCP 10510 Local console port (Telnet) Yes<br />
UDP 31389 SNMP port No<br />
TCP 31389 DSA listen address port Yes<br />
TCP 31390 Local console port (Telnet) Yes<br />
Configuration<br />
See the following site for<br />
descriptions of these ports,<br />
and instructions for<br />
changing them:<br />
http://www.onjava.com/<br />
pub/a/onjava/2002/07/3<br />
1/tomcat.html<br />
See the SSL section in the<br />
chapter “Security”<br />
DXHOME/config/<br />
knowledge/iTechPoz.dxc<br />
This DSA is only to be used<br />
by eIAM.<br />
DXHOME/config/<br />
knowledge/uddiv3.dxc<br />
This DSA is only to be used<br />
by the UDDI Server.<br />
DXserver Overview 2–25
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong><br />
Ports Used by Sample Tools and Sample DSAs<br />
The following table lists the port numbers used by a sample tool and the sample<br />
DSAs installed during a default <strong>eTrust</strong> <strong>Directory</strong> installation.<br />
Any extra DSAs that you add will take up additional ports.<br />
For information about how to set the port number of a DSA, see the section<br />
Setting DSA Port Numbers in the chapter “General Administration.”<br />
Sample<br />
DXtrap<br />
sample tool<br />
Democorp<br />
sample DSA<br />
Router<br />
sample DSA<br />
UNSPSC<br />
sample DSA<br />
Protocol Port<br />
Number<br />
Description of Port<br />
UDP 162 The port on which DXtrap<br />
receives SNMP traps<br />
UDP 19389 SNMP port No<br />
TCP 19389 DSA listen address port Yes<br />
TCP 19390 Local console port (Telnet) Yes<br />
UDP 19289 SNMP port No<br />
TCP 19289 DSA listen address port Yes<br />
TCP 19290 Local console port (Telnet) Yes<br />
UDP 19489 SNMP port No<br />
TCP 19489 DSA listen address port Yes<br />
TCP 19490 Local console port (Telnet) Yes<br />
Accepts<br />
SSL<br />
Requests<br />
Configuration<br />
See the section The<br />
DXtrap Tool in the<br />
chapter “Samples”<br />
DXHOME/config/<br />
knowledge/democorp.dx<br />
c<br />
DXHOME/config/<br />
knowledge/router.dxc<br />
DXHOME/config/<br />
knowledge/unspsc.dxc<br />
2–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
3<br />
General Administration<br />
This chapter describes the commands you use to set up and maintain the general<br />
behavior of DXserver.<br />
Defining DSAs with the set dsa Command<br />
The set dsa command defines the basic properties of each DSA or LDAP server in<br />
the system. These DSAs include the local DSA itself, any remote DSAs (either on<br />
the same system or on other systems), and other X.500 or LDAP servers.<br />
Information about other directories, how to connect to them, their role (for<br />
example, Replicas) and the entry namespace they manage is referred to as<br />
knowledge. The total “knowledge” of the system is used to form a backbone of<br />
directory servers to which each DSA belongs (a directory system).<br />
The DSA is defined in a configuration file (.dxc) in the knowledge directory<br />
(along with other DSA definitions). A DXserver determines its own entry<br />
(identity) by looking for its own name among all the set dsa definitions.<br />
Important! A DSA must use its own name (case insensitive) from the initialization file;<br />
for example, the initialization file for the DSA illustrated below is serverName.dxi.<br />
General Administration 3–1
Defining DSAs with the set dsa Command<br />
The set dsa Command Syntax<br />
The set dsa command has the following format:<br />
set dsa serverName =<br />
{<br />
prefix<br />
= <br />
native-prefix = <br />
dsa-name<br />
= <br />
dsa-password = "string"<br />
ldap-dsa-name = <br />
ldap-dsa-password = "string"<br />
address = tcp hostname port portNumber [ ,tcp host2 port port2 ]<br />
tsap<br />
= tsel<br />
ssap<br />
= ssel<br />
osi-psap<br />
= psel<br />
disp-psap<br />
= dispsap<br />
cmip-psap<br />
= cmipsap<br />
snmp-port<br />
= portNumber<br />
console-port = portNumber<br />
remote-console-port = portNumber<br />
remote-console-ssl = boolean<br />
console-password = "string"<br />
ssld-port<br />
= portNumber<br />
auth-levels<br />
= authLevelList<br />
dsp-idle-time = number<br />
dsa-flags<br />
= dsaFlagList<br />
trust-flags<br />
= trustFlaglist<br />
link-flags<br />
= linkFlagList<br />
};<br />
Important! You must declare the parameters in the order shown. Only prefix, dsa-name,<br />
and address are mandatory.<br />
3–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Defining DSAs with the set dsa Command<br />
The set dsa Command Parameters<br />
The parameters of the dsa set command are:<br />
Parameter<br />
serverName<br />
prefix<br />
native-prefix<br />
dsa-name<br />
dsa-password<br />
ldap-dsa-name<br />
ldap-dsa-password<br />
address<br />
tsap<br />
ssap<br />
osi-psap<br />
disp-psap<br />
cmip-psap<br />
snmp-port<br />
console-port<br />
remote-console-port<br />
remote-console-ssl<br />
console-password<br />
ssld-port<br />
auth-levels<br />
dsp-idle-time<br />
dsa-flags<br />
trust-flags<br />
link-flags<br />
Value<br />
Name of the DXserver—must be less than or equal to 31 characters.<br />
Distinguished name of the local root entry, for example, .<br />
(Optional) Distinguished name for an LDAP server, other DSA, or agent that<br />
should be specified when using prefix mapping.<br />
Distinguished name that identifies the DSA.<br />
(Optional) String used in DSP authentication.<br />
(Optional) Distinguished name used when binding to an LDAP server.<br />
(Optional) String used in LDAP authentication.<br />
DXserver Listen address: TCP address and listen port number<br />
(Optional) Transport SAP (not recommended).<br />
(Optional) Session SAP (not recommended).<br />
(Optional) Presentation SAP (service access point) (not recommended).<br />
(Optional) DISP presentation SAP; when absent, DISP is disabled.<br />
(Optional) CMIP presentation SAP; when absent, CMIP is disabled.<br />
(Optional) SNMP port; when absent, SNMP is disabled.<br />
(Optional) Management console port address. When this and the remote console<br />
port address are absent, the management console is disabled.<br />
(Optional) Remote console port address.<br />
(Optional) Encrypts console sessions where the console may be attached to from a<br />
remote host<br />
(Optional) String used in console authentication.<br />
(Optional) SSL port; used for SSL authentication.<br />
(Optional) List of authorization levels supported by this DSA. See the chapter<br />
“Security” for more information.<br />
(Optional) Maximum time in seconds a DSP connection can be idle before it is<br />
disconnected. The default is 600 (10 minutes).<br />
(Optional) Comma-separated list of DSA flags; see DSA Knowledge Flags in this<br />
chapter for more information.<br />
(Optional) Comma-separated list of trust flags; see DSA Knowledge Flags in this<br />
chapter for more information.<br />
(Optional) Comma-separated list of link flags; see DSA Knowledge Flags in this<br />
chapter for more information.<br />
General Administration 3–3
Defining DSAs with the set dsa Command<br />
Setting DSA Port Numbers<br />
When you are running <strong>eTrust</strong> <strong>Directory</strong> on Windows , you usually use a port<br />
number between 1700 and 64K (65536). When you are running <strong>eTrust</strong> <strong>Directory</strong><br />
on a UNIX platform, your system administrator will allocate available port<br />
numbers. On most systems, the port numbers also go up to 64K (65536).<br />
Port numbers are used differently from one DSA to another. For example,<br />
DXserver listens for connections on ports defined in its knowledge file, but<br />
communicates to other DSAs on ports defined in their knowledge files. Some<br />
parameters, for example, console-port, are only meaningful to the DXserver. No<br />
other servers use these parameters.<br />
For a list of all port numbers used in a default installation, see the section Port<br />
Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter “DXserver Overview”.<br />
Example DSA<br />
Configuration<br />
The following is an example of a DSA configuration:<br />
set dsa DemoCorp =<br />
{<br />
prefix<br />
= <br />
dsa-name<br />
= <br />
dsa-password = "secret"<br />
address = tcp Eagle port 19389<br />
snmp-port = 19389<br />
console-port = 19390<br />
ssld-port = 1112<br />
auth-levels<br />
= anonymous, clear-password, ssl-auth<br />
trust-flags<br />
= allow-check-password<br />
};<br />
Viewing Communications Settings<br />
You can view the listen addresses of the DXserver using the following command<br />
at the DXconsole:<br />
get stack;<br />
An example output from this command is:<br />
dap-psap = ""<br />
dsp-psap = ""<br />
disp-psap<br />
= "DISP"<br />
cmip-psap<br />
= "CMIP"<br />
address = 207.2.6.99 port 19389<br />
snmp-port = 19389<br />
ssld-port = 1112<br />
console-port = 19390<br />
snmp-description = <strong>CA</strong> <strong>eTrust</strong> DXserver<br />
snmp-contact<br />
= supportconnect@ca.com<br />
snmp-name = democorp<br />
snmp-location = http://www.ca.com<br />
3–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alarms, Traces, and Logs<br />
Alarms, Traces, and Logs<br />
Output from the DSA can result from:<br />
■<br />
■<br />
■<br />
■<br />
Responses to X.500 requests as entered from DXconsole<br />
Echoing of input commands from the console or a script file<br />
Trace information<br />
Alarm information<br />
The output from the DSA appears on DXconsole when it is open. It can also be<br />
captured in a log file.<br />
Alarms<br />
Alarms report serious problems. Some triggers of alarms are:<br />
■<br />
■<br />
■<br />
A configuration problem—For example, a DSA fails to start because it has<br />
the same listen address as one already running.<br />
A usage problem, such as sending a DAP request to an LDAP port.<br />
A system problem, such as running out of memory or disk space.<br />
Unlike tracing and logging, alarm messages cannot be suppressed:<br />
■<br />
■<br />
■<br />
Alarm messages are always written to the alarm-log (which cannot be<br />
closed).<br />
When a console is open, alarm messages are sent to it.<br />
When an snmp-log is open, an SNMP trap is raised for every alarm.<br />
Traces<br />
Tracing provides debugging information and analyzes service requests.<br />
Tracing does not control what is logged to the summary, query, or stats logs.<br />
In the DSA, the trace command controls the amount of tracing that is sent to the<br />
DXconsole and trace-log file (if open).<br />
General Administration 3–5
Alarms, Traces, and Logs<br />
The Trace Command<br />
DXserver supports various forms of tracing. The trace options can be turned on<br />
using the command:<br />
set trace = option, option;<br />
Multiple trace options can be specified.<br />
Trace options in the set trace command are not cumulative and override options<br />
set in previous set trace commands. In the following example, the final trace<br />
option is summary:<br />
set trace = time, error;<br />
set trace = summary;<br />
The time and error options are turned off by the second set trace command. The<br />
none option turns all tracing options off.<br />
Tip: Full tracing degrades performance, so you should use it only during<br />
testing.<br />
The following trace options are supported:<br />
Trace Option<br />
alert<br />
cert<br />
connect<br />
diag<br />
disp<br />
dsa<br />
error<br />
ldap<br />
Meaning<br />
Displays authentication errors.<br />
Displays certificate operations.<br />
Displays connections.<br />
Traces local DXserver operations that were refused.<br />
Traces warnings during DISP recovery. See the chapter Replication for more information.<br />
This option is similar to the x500 trace, but it also includes tracing of the module flow<br />
inside the DSA.<br />
Reports events that may impact on the ability of DXserver to perform a requested<br />
operation. These events are usually more serious than those reported under warn. This is<br />
the default trace level.<br />
This traces detailed LDAP operations. The output can become quite large when searches<br />
return a large number of entries.<br />
none Turns off all tracing .<br />
query<br />
stack<br />
Displays a one-line summary containing the request and a one-line summary of the<br />
result.<br />
Displays detailed protocol tracing. The output can become quite large.<br />
3–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alarms, Traces, and Logs<br />
Trace Option<br />
stats<br />
summary<br />
time<br />
update<br />
warn<br />
x500<br />
Meaning<br />
Displays statistical information for each minute the DSA is not idle.<br />
Displays a one-line summary containing the service request and result.<br />
Displays the start time, end time, and elapsed time of an operation with a brief summary<br />
of the operation.<br />
Displays update operations—add, delete, modify, and rename.<br />
Displays a message when an X.500 service is not successful. For example, an object class<br />
violation diagnostic might indicate that a mandatory attribute such as surname is<br />
missing.<br />
Warn messages usually represent a user error, rather than a problem with DXserver. This<br />
is no longer the default trace level: see error.<br />
Displays the full detail of the service request, confirmation, or error. This traces DAP,<br />
DSP, and LDAP operations. The output can become quite large when searches return a<br />
large number of entries<br />
We recommend that the error trace option is included in the set trace command<br />
during normal operation.<br />
Tracing Protocol<br />
Low-level protocol can be traced. The protocol trace is written to the trace log, if<br />
open. This tracing is only for debugging purposes. To enable protocol tracing,<br />
use this command:<br />
set trace = stack;<br />
Tracing Statistics<br />
The stats trace option enables you to retrieve the following minute-by-minute<br />
statistical information about a DSA:<br />
Label<br />
Assocs<br />
NilCredit<br />
NoTicks<br />
Queue<br />
Active<br />
Ops<br />
Description<br />
Displays the number of current associations.<br />
Displays the number of times flow control was applied (to any association).<br />
Displays the number of times per second processing did not occur because the DSA was<br />
too busy. When the number is more than 10, the DSA is very busy. The largest value is 60.<br />
Displays the number of current outstanding operations.<br />
Displays the percentage of the time during the last minute that there was activity.<br />
Activity covers local operations and chained operations. If Active is 0 it is safe to shut<br />
down the DSA.<br />
Displays the number of operations processed in the last minute.<br />
General Administration 3–7
Alarms, Traces, and Logs<br />
Logs<br />
The logs contain the output from a DSA.<br />
Controlling Logging<br />
The following commands control output:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
trace options;<br />
set trace = options;<br />
set logType = filename;<br />
close logType;<br />
flush logType;<br />
echo string;<br />
echo-on;<br />
echo-off;<br />
These commands can be used in two ways. You can define these commands in<br />
the configuration file (.dxc) in the logging directory, and you can also enter them<br />
manually on DXconsole.<br />
Log Types<br />
DXserver supports the independent log types listed in the following table.<br />
Log Type Records Description<br />
alarm-log Alarms ■ The alarm log is always open when a DSA is running. It cannot be<br />
closed with the close command.<br />
■<br />
It has a default value of serverName_alarm.log.<br />
■<br />
All alarms are written to the alarm log, regardless of the tracing<br />
level set or whether a DXconsole is open.<br />
alert-log<br />
All<br />
authorization<br />
errors<br />
■<br />
The alert log is only written if it has been opened with the set alertlog<br />
command. Writing to the alert log is not affected by the trace<br />
setting.<br />
■<br />
When an alert log is open, the system records all authorization<br />
errors. It can be used to show attempts at unauthorized access to<br />
the DXserver.<br />
■<br />
It is time and date stamped, and a new one is written daily.<br />
3–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alarms, Traces, and Logs<br />
Log Type Records Description<br />
cert-log<br />
Specific<br />
certificate<br />
operations<br />
■<br />
The cert log is only written if it has been opened with the set certlog<br />
command. Writing to the certificate log is not affected by the<br />
trace setting.<br />
■<br />
When a certificate log is open, the system records all add or modify<br />
operations that include a userCertificate, caCertificate, or<br />
certificateRevocationList attribute. In addition, any read or search,<br />
or any search filter that returns one of these attributes, is recorded.<br />
■<br />
It is time and date stamped, and a new one is written daily.<br />
connect-log<br />
diag-log<br />
All released<br />
connections<br />
Refused<br />
DXserver<br />
operations<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
The connect log is only written if it has been opened with the set<br />
connect-log command. Writing to the connect log is not affected by<br />
the trace setting.<br />
When a connect log is open, the system writes a line for each<br />
connection made when the connection is released.<br />
It is time and date stamped, and a new one is written daily.<br />
This log (or trace log if diag tracing enabled) will contain the reason<br />
why local DXserver operations have been refused.<br />
There are a number of situations where this may occur depending<br />
on a DSAs configuration and data. An example would be if search<br />
was performed with an invalid DN. The operation, affected entry<br />
and diagnostic message will appear.<br />
To enable this log, use the following commands:<br />
set trace +diag;<br />
set diag-log = "logs/$s_diag.log";<br />
query-log Search activity ■ The query log is only written if it has been opened with the set querylog<br />
command. Writing to the query log is not affected by the trace<br />
setting.<br />
■<br />
■<br />
When a query log is open, the system writes a one-line summary of<br />
the operation requested, which includes a time and date stamp.<br />
It is time and date stamped, and a new one is written daily.<br />
stats-log<br />
Summary of<br />
operational<br />
statistics<br />
■<br />
The stats log is only written if it has been opened with the set statslog<br />
command. Writing to the stats log is not affected by the trace<br />
setting.<br />
■<br />
When a statistics log is open, a one-line entry is added to the<br />
statistics log file for every minute that the DSA is active. When the<br />
DSA is not active, no information is written to the stats log; this<br />
prevents the stats log from growing during inactivity.<br />
■<br />
It is time and date stamped, and a new one is written daily.<br />
General Administration 3–9
Alarms, Traces, and Logs<br />
Log Type Records Description<br />
summary-log Summary of<br />
daily activity<br />
trace-log<br />
update-log<br />
warn-log<br />
Diagnostic<br />
tracing<br />
All add, delete,<br />
modify, and<br />
rename<br />
operations<br />
Errors and<br />
warnings<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
The summary log is only written if it has been opened with the set<br />
summary-log command. Writing to the summary log is not<br />
affected by the trace setting.<br />
When a summary log is open, the system writes the summary<br />
tracing for all operations to the summary log regardless of the<br />
tracing level set or whether DXconsole is open.<br />
It is time and date stamped, and a new one is written daily.<br />
When a trace log is open, tracing for all operations is written to the<br />
trace log.<br />
The level of tracing written to a trace log is dependent on the level<br />
of tracing set on the DSA.<br />
The update log is only written if it has been opened with the set<br />
update-log command. Writing to the update log is not affected by<br />
the trace setting.<br />
When an update log is open, the system records all add, modify,<br />
rename, and delete operations.<br />
It is time and date stamped, and a new one is written daily.<br />
When a warn log is open, all errors and warnings are written to the<br />
warn log.<br />
Warnings are only listed if the tracing level is set to 'warn'.<br />
Errors are only listed if the tracing level is set to 'error'.<br />
Each warning or error written to the log is time- and date-stamped,<br />
and a new log is written daily.<br />
3–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alarms, Traces, and Logs<br />
Log File Commands<br />
Open a Log File<br />
To open a log file, use the command:<br />
set logType = "filename";<br />
If a log file does not exist when opened, it is created. If it already exists, the DSA<br />
appends the output.<br />
If the log file name contains the string $S then the system substitutes the name<br />
of the DSA. For example, when the name of the DXserver is DemoCorp, the<br />
following command opens a log file named ../logs/DemoCorp.log:<br />
set trace-log = "logs/$S.log";<br />
Flush a Log File<br />
To force all buffered output to a particular log file, use the flush command. This<br />
feature is provided so you can examine a current log file off-line while the<br />
normal log file is still open. To flush a log file, use the command:<br />
flush logType;<br />
Note: Alarm logs are always flushed.<br />
Close a Log File<br />
Inspect Names of Log<br />
Files<br />
The close command stops output to the log file by closing it. When the DSA<br />
shuts down, it automatically closes any open log file. To close a log file, use the<br />
command:<br />
close logType;<br />
To inspect the names of each of the enabled log files (including the snmp-log<br />
file), use the following command:<br />
get log;<br />
The following is an example of the output:<br />
alarm-log<br />
= logs/democorp_alarm.log<br />
summary-log<br />
= logs/democorp_20010122.log<br />
stats-log<br />
= logs/democorp_stats_20010122.log<br />
trace-log<br />
= logs/democorp_trace.log<br />
query-log<br />
= logs/democorp_query_20010122.log<br />
update-log<br />
= logs/democorp_update_20010122.log<br />
alert-log =<br />
cert-log<br />
= logs/democorp_cert_20010122.log<br />
connect-log<br />
= logs/democorp_connect_20010122.log<br />
snmp-log = udp eagle port 9999<br />
General Administration 3–11
Alarms, Traces, and Logs<br />
History Files<br />
Most of the log files, once opened, start afresh each day.<br />
For example, the following command produces a log file in the logs directory of<br />
the form serverName_yyyymmdd.log for each day there is activity on the DSA.:<br />
set summary-log = "logs/$S.log";<br />
You can use these history files to inspect auditing, accounting, billing, and<br />
statistical information.<br />
Echoing<br />
Echoing is the process of displaying the commands in a script file before<br />
executing them..<br />
There are three echo commands:<br />
■<br />
■<br />
■<br />
echo-off;<br />
echo-on;<br />
echo "string";<br />
The output of echoed commands goes to DXconsole (if connected) and the tracelog<br />
file (if open).<br />
To prevent the display of commands in a script file during startup, echo is off by<br />
default. (See the chapter “DXserver Overview”) To view each command before it<br />
is executed, use the echo-on command.<br />
Messages on the console can be displayed using the echo command, for example:<br />
echo "Initializing ...";<br />
Turning echo-on in a script might slow the execution of the script slightly.<br />
3–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Associations<br />
Associations<br />
An association is a connection to a DSA. The number of DSA associations can be<br />
managed using the assoc module commands.<br />
The association commands have the following forms:<br />
■<br />
■<br />
■<br />
set parameter = value;<br />
get parameter;<br />
assoc action;<br />
The assoc Command Options<br />
The following are the parameters of the assoc set command:<br />
Keyword Parameter Description<br />
allow-binds Boolean When FALSE, new associations are rejected. Use this to<br />
perform a graceful shutdown.<br />
auth-trap Boolean Turns on raising an authentication trap whenever an<br />
authentication failure occurs.<br />
min-auth<br />
none,<br />
clear-password, or<br />
ssl-auth<br />
The minimum authentication level required on a bind.<br />
credits Integer The maximum number of concurrent operations the DSA<br />
processes for each user association.<br />
force-encrypt-anon Boolean Forces SSL encryption on anonymous binds.<br />
When this setting is on, if a user attempts to create an<br />
anonymous bind without SSL, the DSA will disallow the<br />
bind and return an "Inappropriate authentication" error.<br />
force-encrypt-auth Boolean Forces SSL encryption on authenticated binds.<br />
When this setting is on, if a user attempts to create an<br />
authenticated bind without SSL, the DSA will disallow the<br />
bind and return an "Inappropriate authentication" error.<br />
hold-ldap-connections Boolean When TRUE, prevents a DSA from clearing the underlying<br />
TCP/IP connection after a bind refusal.<br />
max-bind-time Integer or none The maximum time, in seconds, that any particular<br />
association can last (a value of 0 or none means<br />
unlimited).<br />
General Administration 3–13
Associations<br />
Keyword Parameter Description<br />
max-pdu-size Integer The largest size (in bytes) that a protocol data unit may be<br />
to be accepted by DXserver. The default value is 0,<br />
meaning unlimited.<br />
This value may be retrieved with the 'get assoc;'<br />
command, if the value has been set.<br />
max-users Integer or none The maximum number of current associations (number of<br />
users bound to the DSA).<br />
op-error-trap Boolean Turns on raising an operation error trap whenever an<br />
operation error occurs.<br />
password-age Integer The number of days a password is valid. By default, this<br />
feature is disabled (0).<br />
password-history Integer The maximum number of entries to retain in the history.<br />
By default, this feature is disabled (0).<br />
password-last-use Integer The number of days a password remains valid when it is<br />
not used. When the value is exceeded, the password<br />
expires. By default, this feature is disabled (0).<br />
password-length Integer The minimum length of a password. The default is 6<br />
characters.<br />
Integer<br />
The number of seconds after which a suspended password<br />
reactivates. By default, this feature is disabled (0).<br />
password-min-age Integer The number of days that transpire between changing a<br />
password (lockout period). By default, this feature is<br />
disabled (0).<br />
Integer<br />
The minimum number of nonalphanumeric characters a<br />
password must contain. The default is 0.<br />
password-numeric Integer The minimum number of numeric characters a password<br />
must contain. The default is 0.<br />
password-policy Boolean Enables or disables password management. See Password<br />
Management in the chapter “Security.”<br />
password-retries Integer The number of consecutive failed logon attempts before a<br />
password is suspended. The default is 3.<br />
role-subtree DN The DN of the subtree that stores the roles. Together with<br />
use-roles, it is used to set role-based access controls. For<br />
information about roles, see Role-based Access Controls in<br />
the chapter “Security.”<br />
password-maxsuspension<br />
password-non-alphanum<br />
ssl-auth-bypass-entrycheck<br />
Boolean<br />
Turns off automatic checking for the existence of an entry<br />
named by the subject held in the certificate.<br />
3–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Associations<br />
Keyword Parameter Description<br />
trap-on-update Boolean Turns on raising an SNMP trap whenever an update<br />
occurs.<br />
trust-sasl-proxy DN The distinguished name of the trusted proxy.<br />
use-roles Boolean Enables or disables role-based access control.<br />
user-idle-time Integer The maximum idle time in seconds. When a user is idle for<br />
user-idle-time seconds, that user is disconnected. This<br />
reduces the number of users connected and lets new users<br />
connect to the DSA.<br />
The following are the parameters of the assoc get command:<br />
Parameter<br />
assoc<br />
users<br />
Description<br />
Shows the current association configuration values of the<br />
DSA.<br />
Provides information about currently bound users.<br />
The following is the action of the assoc command:<br />
Value<br />
abort<br />
Description<br />
Abort one or all associations.<br />
Viewing Association Configuration<br />
To inspect the current association configuration, use the command:<br />
get assoc;<br />
This command shows the current association configuration values of the DSA.<br />
Details of the sample of output from this command are below:<br />
max-users = 255<br />
max-bind-time = 0<br />
user-idle-time = 3600<br />
allow-binds<br />
= TRUE<br />
min-auth<br />
= none<br />
credits = 5<br />
trap-on-update = 0<br />
auth-trap = 0<br />
op-error-trap = 0<br />
ssl-auth-bypass-entry-check = FALSE<br />
use-roles<br />
= FALSE<br />
hold-ldap-connections<br />
= FALSE<br />
password-policy<br />
= FALSE<br />
General Administration 3–15
Associations<br />
Viewing Associations<br />
The assoc module maintains information about all associations. This includes<br />
connection information, connect times, idle times, and so on. The command get<br />
users returns a list of currently bound users. A sample of output from this<br />
command follows:<br />
Association 0: connected for 240 seconds, idle for 5 seconds<br />
Association 0: bound using *UNKNOWN* from TCP 0.0.0.0 as ANONYMOUS<br />
Association 1: connected for 111 seconds, idle for 24 seconds<br />
Association 1: bound using DAP from TCP 172.24.131.145 as PASSWORD AUTH user:<br />
<br />
<br />
<br />
Tracing Associations<br />
The association trace facility controls the X.500/LDAP operation tracing of<br />
individual users through the DXconsole. Users are assigned association numbers<br />
in the order in which they bind to the DSA. The first user to bind to the DSA<br />
receives association number 0, the second user receives association number 1,<br />
and so on.<br />
Control Association<br />
Tracing<br />
To control the association tracing, use the command:<br />
trace enable assoc = association_number<br />
For example, to trace a specific association, first open a DXconsole session using<br />
telnet. Set the tracing to error only:<br />
set trace = error<br />
Determine the association number of the user that requires tracing with the get<br />
user command (see Viewing Associations in this chapter) and supply that<br />
number to the trace enable command.<br />
Disable Association<br />
Tracing<br />
To disable the association tracing, use the command:<br />
trace disable assoc = association_number<br />
Stopping a DSA<br />
To shut down the DSA with DXconsole, use the command:<br />
dsa> shutdown;<br />
3–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Associations<br />
Association Times<br />
User connections can be unconditionally aborted by setting a maximum bind<br />
time. Any user bound to the directory for longer than the maximum bind time<br />
automatically has their association aborted. To set the maximum bind time, use<br />
the command:<br />
set max-bind-time = 3600;<br />
The value is the maximum number of seconds a user can be bound to the DSA<br />
(the example shows 3,600 seconds, or one hour). 0 = no limit.<br />
Controlling Binds<br />
Two assoc module commands control the bind operation. The first is allowbinds.<br />
When set to false, the system rejects all binds. The second, min-auth, sets<br />
the minimum authentication level required on a bind. When set to clearpassword,<br />
a user name and password must be provided with the bind request.<br />
The system checks this user name and password against an existing entry in the<br />
directory database before allowing the bind. For example:<br />
Allow Binds<br />
Disable New Binds<br />
set allow-binds = true;<br />
set min-auth = clear-password;<br />
To shut down the DSA gracefully, the administrator can disable new users<br />
binding to the DSA and then wait until each association unbinds or times out.<br />
To disable new binds, use the command:<br />
set allow-binds = false;<br />
Any new user that attempts to bind to the DSA receives a bind-refuse with the<br />
following error:<br />
Bind-Error: Service Error: <strong>Directory</strong> unavailable<br />
Monitor Active Users<br />
Before allowing or disabling binds, you may want to see who is currently<br />
bound to the DSA. To monitor active users, use the command:<br />
get users;<br />
The command displays the number of users, their connection time, connection<br />
address, and user name.<br />
See the chapter “Security” for more information about authentication and binds.<br />
General Administration 3–17
Associations<br />
Aborting Associations<br />
As described previously, to obtain information about currently connected users,<br />
use the command:<br />
get users;<br />
You can abort all or some associations by using this information and one of the<br />
following commands (assuming 131072 is a valid association).<br />
abort all-users;<br />
abort user 131072;<br />
Concurrent Associations<br />
You can configure the maximum number of users that can be bound to the DSA.<br />
For example, to set this value to 100, use the command:<br />
set max-users = 100;<br />
Note: The operating system sets an upper limit of allowed associations per DSA,<br />
which relates to the maximum number of file descriptors per process. The maxusers<br />
value can be set to 0 to prevent any users from binding to the DSA.<br />
Set Maximum Idle<br />
Time<br />
To increase availability of the directory, you should set the maximum idle time<br />
parameter. The idle time for a user is the time elapsed since the DSA performed<br />
the last operation on that user’s association. Any connected user idle for longer<br />
than the maximum idle time automatically has the association aborted. The<br />
maximum idle time is set with the command:<br />
set user-idle-time = 600;<br />
The value is the number of seconds a user connection can be idle before risking<br />
a disconnection (the previous example shows 600 seconds, or 10 minutes).<br />
The system rejects an association when the number of current associations is at<br />
the specified max-users limit, and no user has exceeded his or her maximum<br />
bind time or maximum idle time.<br />
3–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Associations<br />
Association Queues<br />
The maximum number of DSA operations in progress at the same time on a peruser<br />
basis can be set using the credit limit, for example:<br />
set credits = 5<br />
To determine the maximum number of concurrent operations you can perform,<br />
multiply the number of credits by the maximum number of users. When the<br />
credit value is exceeded, the DSA delays the receipt of any new requests from the<br />
DUA.<br />
There is a difference between this value and the max-local-ops value (see Local<br />
Operations in this chapter). The credits parameter provides a mechanism to<br />
govern how many client requests are outstanding at any given time for each<br />
association and to delay new requests. Conversely, the max-local-ops value<br />
rejects new operations above its limit.<br />
General Administration 3–19
Local Operations<br />
Local Operations<br />
The oper Commands<br />
You can manage local operations using the oper module commands. The<br />
operation commands have the following form:<br />
■ set parameter = value;<br />
■<br />
■<br />
get parameter;<br />
oper action;<br />
The commands are defined in the configuration file (.dxc) in the limits directory.<br />
The following are the parameters of the operation set command:<br />
Keyword Parameter Description<br />
access-controls Boolean TRUE enables access controls; FALSE disables access controls.<br />
add-oc-parents Boolean When set to TRUE, it causes DXserver to add superior object<br />
classes even if the client did not specify these while adding an<br />
entry. It complements the prune-oc-parents and return-oc-parents<br />
flags and is added for Netscape compatibility.<br />
dynamic-access-control Boolean<br />
Used to enable or disable dynamic access controls. For more<br />
information, see the chapter “Security.”<br />
ignore-name-bindings Boolean When set to TRUE, it lets the DXserver operate without name<br />
bindings. This can be useful when the schema is imported<br />
from a directory that does not support name bindings. For<br />
more information, see the chapter “Schema Definition.”<br />
max-local-ops Integer The maximum number of concurrent operations the DSA<br />
processes for all users.<br />
max-op-size<br />
max-op-time<br />
Integer or the<br />
keyword none<br />
Integer or the<br />
keyword none<br />
The maximum number of entries that a search or list can<br />
return (a value of 0 or the keyword none means unlimited).<br />
This value overrides a user-requested size limit service control<br />
when the max-op-size is less than the one requested by the<br />
user.<br />
The maximum time (s) that any particular operation can last (a<br />
value of 0 or the keyword none means unlimited). This value<br />
overrides a user-requested time limit service control when the<br />
max-op-time is less than the one requested by the user.<br />
op-attrs Boolean When set to TRUE, operational attributes are added<br />
automatically to each entry by the DSA; when set to FALSE,<br />
operational attributes are treated like regular attributes.<br />
prune-oc-parents Boolean For more information, see the chapter “Schema Definition.”<br />
3–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Local Operations<br />
Keyword Parameter Description<br />
return-oc-parents Boolean For more information, see the chapter “Schema Definition.”<br />
role-subtree DN The distinguished name of the subtree used to store roles.<br />
For more information, see the chapter “Security.”<br />
trust-sasl-proxy DN The distinguished name of the trusted proxy.<br />
For more information, see the chapter “Security.”<br />
use-roles Boolean Used to enable and disable role-based access controls.<br />
For more information, see the chapter “Security.”<br />
The following DSA flag identifies a DSA as a read-only (no updates permitted)<br />
DSA. You can set this flag in the set dsa command in the knowledge directory.<br />
dsa-flags = read-only<br />
The following are the parameters of the operation get command:<br />
Parameter<br />
oper<br />
stats<br />
Description<br />
Shows the current operation configuration values of the<br />
DSA.<br />
Returns a list of operation statistics.<br />
The following are the actions of the oper command:<br />
Value<br />
abandon<br />
reset<br />
Description<br />
Abandons one or all operations on a particular association.<br />
Resets the statistics counters.<br />
General Administration 3–21
Local Operations<br />
Viewing Operation Configuration<br />
The following command shows the current operation configuration values of the DSA:<br />
get oper;<br />
Here is an example of the output of this command:<br />
max-local-ops = 200<br />
max-op-time = 120<br />
max-op-size = 200<br />
access-controls = FALSE<br />
op-attrs<br />
= TRUE<br />
read-only<br />
= FALSE<br />
prune-oc-parents = FALSE<br />
return-oc-parents = FALSE<br />
add-oc-parents<br />
= FALSE<br />
dynamic-access-control = FALSE<br />
modify-on-add<br />
= FALSE<br />
unique-attrs<br />
= attr1, attr2<br />
ignore-name-bindings = FALSE<br />
Viewing Operation Statistics<br />
List Operation<br />
Statistics<br />
The oper module maintains statistics about all operations, including events,<br />
services, errors, timeouts. The following command returns a list of operation<br />
statistics:<br />
get stats;<br />
An example of the output of a get stats command is given below<br />
anonymous binds = 43<br />
in ops = 789<br />
read ops = 350<br />
add entry ops = 1<br />
modify entry ops = 3<br />
modify-dn ops = 1<br />
list ops = 371<br />
search ops = 6<br />
whole tree search ops = 6<br />
errors = 2<br />
name errors = 1<br />
found local entries = 187<br />
no such object = 1<br />
DSA statistics can be read using SNMP or CMIP. The Management Information<br />
Base (MIB) being read defines the names displayed from those actions. For<br />
example, noSuchObject displays as “no such object.”<br />
Reset Counters<br />
The statistics are stored in counters. To reset these counters, use this command:<br />
reset stats;<br />
3–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Local Operations<br />
Concurrent Operations<br />
To restrict the maximum number of DSA operations in progress at the same time,<br />
use the following command:<br />
set max-local-ops = 100;<br />
Administration Limits<br />
To restrict the maximum time that the list and search services can run and the<br />
maximum number of entries these operations can return, use the following<br />
command:<br />
set max-op-time = 20;<br />
set max-op-size = 100;<br />
If an operation exceeds either of these limits, the error “Administration limit<br />
exceeded” is returned.<br />
Operational Attributes<br />
To control the automatic creation and updating of operational attributes (for<br />
example, last modified time) on entries in the DSA, use the following command:<br />
set op-attrs = true;<br />
If it is set to true, the DSA will automatically control the creation and updating of<br />
operational attributes.<br />
The op-attrs parameter should normally be set on each DSA.<br />
Note: If the multi-write-disp-recovery flag is set, the op-attrs parameter must be true.<br />
If the op-attrs parameter is set to false, then:<br />
■<br />
■<br />
The DSA will not create or update operational attributes<br />
All no-user-modification schema settings will be overridden. This means that<br />
an administrator will be able to update any operational attributes manually.<br />
Access Controls<br />
To control the level of security available on the DSA, use this command:<br />
set access-controls = true;<br />
When access controls are enabled and no rules are defined, no entries are visible<br />
and the directory cannot be viewed or updated. However, it is still possible to<br />
load the directory using the bulk load tools. For more information about access<br />
controls, see the chapter “Access Controls.”<br />
General Administration 3–23
Local Operations<br />
Read Only<br />
To reject all updates, set the read-only DSA flag in the configuration file (.dxc) in<br />
the knowledge directory, using the set dsa command:<br />
dsa-flags = read-only<br />
This guarantees update security and over-ride any access controls. It is very<br />
useful for public DSAs. In conjunction with a public DSA, an administrator can<br />
start up a local DSA that connects to the same database to perform updates.<br />
Abandoning Operations<br />
To obtain information about the current users, use the command:<br />
get users;<br />
You can abandon any outstanding operations using this information and one of<br />
the following commands (assuming 131072 is a valid association and 2 is a valid<br />
operation):<br />
abandon all on association 131072;<br />
abandon operation 2 on association 131072;<br />
When an operation is abandoned, the targeted service returns the following<br />
error:<br />
Service error: operation abandoned<br />
The abandoned operation itself returns an abandon confirm. If the operation<br />
cannot be abandoned, it returns an abandon-refused message with the<br />
appropriate error.<br />
A DSA can truncate processing an operation when it exceeds the global<br />
configuration values, for example:<br />
set max-op-time = 60;<br />
set max-op-size = 100;<br />
Tip: Services that exceed global limits are not abandoned; rather they return<br />
an error or partial result.<br />
The result returned by an abandoned operation depends on how far the<br />
operation progressed before being abandoned. The display shows either the<br />
following error message:<br />
Service error: administration limit exceeded<br />
or partial results (with the partial outcome qualifier set to the appropriate<br />
problem). An update operation cannot be abandoned.<br />
3–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The <strong>Directory</strong> Information Base<br />
The <strong>Directory</strong> Information Base<br />
To manage the DIB, use the commands:<br />
■<br />
■<br />
set parameter = value;<br />
get parameter;<br />
The following are the parameters of the DIB set command:<br />
Keyword<br />
Parameter Description<br />
alias-integrity Boolean Enables or disables alias integrity checking.<br />
See the section Alias Integrity.<br />
database-name String The database that is connected to the server.<br />
dbconnection<br />
eis-count-attr Attribute An attribute name.<br />
A compound value, which consists of database-name, databaseuser,<br />
and user-password.<br />
index-reverse Attributes List of attributes to be reverse-indexed.<br />
See the section Indexing Options.<br />
index-wide Attributes List of attributes to be wide-indexed.<br />
See the section Indexing Options.<br />
not-searchable Attributes List of attributes to be marked as not searchable.<br />
See the section Indexing Options.<br />
password-storage<br />
shutdown-on-sql-error Boolean<br />
The method used to store user passwords. See the section<br />
Password Storage for the list of password storage methods.<br />
Sets the DSA to shut down whenever an untrapped database error<br />
occurs. See the section Manage Connections to the Database<br />
Two flags in the knowledge directory affect operations on the database. These<br />
are the limit-list and limit-search flags.<br />
set dsa DemoCorp = {<br />
...<br />
DSA flags = limit-list, limit-search, ...<br />
...};<br />
The following is the parameter of the DIB get command:<br />
Keyword<br />
dib<br />
Value<br />
Shows the DSA configuration values of the directory information processor.<br />
See the appendix “DXserver Command Language” for information about<br />
grouping commands accurately.<br />
General Administration 3–25
The <strong>Directory</strong> Information Base<br />
Viewing DIB Configuration<br />
To monitor the database management settings, use the DIB module’s get<br />
commands at DXconsole.<br />
To view the DIB configuration variables and their values, use the command:<br />
get dib;<br />
Example output of this command is shown below:<br />
alias-integrity = TRUE<br />
database-name<br />
= demo<br />
database-user<br />
= fred<br />
database-password = *****<br />
eis-count-attr<br />
= dxEntryCount<br />
limit-search<br />
= FALSE<br />
limit-list<br />
= FALSE<br />
password-storage = sha-1<br />
Database Name<br />
The DSA must know the name of the database it accesses. This value is usually<br />
set in the initialization file (.dxi) through the database configuration file (.dxc),<br />
for example:<br />
set database-name = demo;<br />
where demo is the name of an Advantage Ingres database.<br />
In certain situations, because of the access controls required to access Advantage<br />
Ingres databases, it may be necessary to supply a user name and password.<br />
Database applications, in this case the <strong>eTrust</strong> <strong>Directory</strong> DXserver process, must<br />
supply these credentials to Advantage Ingres when accessing the database. If this<br />
situation arises, use the alternate form of the database configuration command as<br />
shown below:<br />
set dbconnection = { db-name = demo, db-user = ingres, db-password = secret };<br />
where demo is the name of the database, ingres is the user name and secret is the<br />
password.<br />
Tip: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
See Databases in the chapter “DXserver Overview” for more information about<br />
databases.<br />
3–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The <strong>Directory</strong> Information Base<br />
Manage Connections to the Database<br />
<strong>eTrust</strong> <strong>Directory</strong> manages problems with the DSA connection to the database in<br />
two ways:<br />
■<br />
■<br />
If a DSA cannot connect to a database, it raises an alarm and shuts down.<br />
You can set each DSA to shut down when a database error occurs<br />
DSA Shuts Down If Database Connection Lost<br />
If a DSA cannot connect to a database, it raises an alarm and shuts down. For a<br />
description of the alarms, see the section DXserver Alarm Messages in the<br />
appendix “Messages and Logs”.<br />
If a DSA shuts down due to an Ingres error, you should check the Ingres logs to<br />
find out what the problem was. For more information about Ingres logs, see the<br />
section Advantage Ingres Logs in the appendix “Messages and Logs”.<br />
Shut Down DSA If a Database Error Occurs<br />
You can set each DSA to shut down if the database produces an error. By default,<br />
this option is off.<br />
If you are concerned that a DSA may<br />
It is possible that a database could To set a DSA to shut down if the database<br />
produces an error, use the following command:<br />
set shutdown-on-sql-error = true;<br />
Alias Integrity<br />
When an entry that has one or more aliases pointing to it is removed, the aliases<br />
are also removed. This occurs regardless of the setting of the alias-integrity flag.<br />
When alias integrity is turned on, invalid aliases (where no referenced entry<br />
exists) cannot be added.<br />
To disable the alias integrity feature, use the command:<br />
set alias-integrity = false;<br />
See Aliases in the appendix “DXconsole DUA” for more information about<br />
aliases.<br />
General Administration 3–27
The <strong>Directory</strong> Information Base<br />
Counting Entries<br />
It is often useful to know how many entries in the directory satisfy a specific set<br />
of search criteria. However, performing such a search and counting the entries<br />
returned is not feasible in an automated system or in a system where the search<br />
returns large numbers of entries.<br />
Searches can return the number of entries that satisfy the search rather than the<br />
entries themselves using the eis-count-attr parameter. This parameter can be set<br />
to an unused attribute. We recommend that you use the attribute dxEntryCount<br />
in the database settings file database/default.dxc:<br />
set eis-count-attr = dxEntryCount;<br />
To enable a search to return the number of entries satisfying a search filter<br />
simply set the attributes to be returned by the search to the eis-count-attr<br />
attribute:<br />
search-req<br />
base-object = <br />
whole-subtree<br />
filter = { attr = surname substrings [ initial "C" ] }<br />
attrs = dxEntryCount;<br />
The resulting search returns a single entry with a dxEntryCount attribute. This<br />
attribute is set to the number of entries found that satisfy the search filter. For<br />
example:<br />
SEARCH-CONFIRM<br />
...<br />
Entry:<br />
<br />
<br />
Content:<br />
(dxEntryCount 98)<br />
This search result indicates that there are 98 entries with a surname beginning<br />
with "C" in the DemoCorp directory.<br />
Rejecting All list Commands<br />
There can be instances where a DIT has a very flat structure and there are many<br />
thousands of entries under one node. In this case, the list operation is not useful.<br />
The DSA can be set to reject all list requests by setting the limit-list DSA flag in<br />
the knowledge directory, using the set dsa command:<br />
dsa-flags = limit-list<br />
For information about using the limit-list flag to set up query streaming, see<br />
Query Streaming in the chapter “Distribution and DSP.”<br />
3–28 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The <strong>Directory</strong> Information Base<br />
Rejecting All Unfiltered Searches<br />
There may be instances where a DSA is set up to handle large numbers of simple<br />
lookup searches, and a high throughput is very important. Large complex<br />
searches can put unwanted pressure on the performance of the DSA.<br />
It is possible to limit the types of searches processed by setting the limit-search<br />
DSA flag in the knowledge directory, using the set dsa command:<br />
dsa-flags = limit-search<br />
This flag causes searches with no filter or with a filter containing an attribute<br />
present, substrings any, or a range of values (>=,
The <strong>Directory</strong> Information Base<br />
Indexing Options<br />
Indexing helps with the search process.<br />
Indexing options can appear anywhere in the database configuration after the<br />
schema definitions. If they appear after the database definition, then warning<br />
messages for items already indexed in the database will be produced. This<br />
database configuration file must come after the schema configuration file in the<br />
server initialization file.<br />
You can use the tool dxindexdb to set up the index. For more information, see<br />
Managing Indexes: DXindexdb in the chapter ‘Using DXtools’.<br />
Important! If you have indexed the database with DXtools (for example, dxindexdb),<br />
ensure that the attributes indexed here match those in the database.<br />
Indexing Commands<br />
Use the following commands to set the options:<br />
set not-searchable = attribute-1[, attribute-2…]<br />
set index-wide = attribute-1[, attribute-2…]<br />
set index-reverse = attribute-1[, attribute-2…]<br />
clear indexes<br />
where attribute-n is an attribute name that is either an LDAP or alternate name,<br />
but not an OID.<br />
The following table describes the index settings:<br />
Keyword<br />
Parameter Description<br />
index-reverse Attributes Lists attributes which will be indexed in reverse order. This is useful for<br />
attributes which begin with the same prefix.<br />
For example, you could reverse-index a list of the physical addresses of<br />
network cards (44-45-53-54-42-00, 44-45-53-54-42-01, and so on).<br />
index-wide Attributes Lists attributes which will be given a wide index. Use wide indexing for<br />
attributes whose values you expect to be longer than 106 characters.<br />
not-searchable Attributes Lists attributes which are to be marked as not searchable. This is useful for<br />
increasing the speed of operations (updates, searches etc).<br />
Search operations containing these attributes will return the message<br />
“Unwilling to perform.” The list of attributes must match those set in the<br />
database configuration file.<br />
Important! If a DSA has either DISP replication or multiwrite recovery set (see<br />
the chapter “Replication”), do not set the createTimestamp, modifyTimestamp, or<br />
deleteTimestamp attributes as not searchable.<br />
3–30 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The <strong>Directory</strong> Information Base<br />
Creating Additional Wide Indexes<br />
To create additional wide indexes for some attributes without changing any wide<br />
indexes that have already been set up, use the add command at the bottom of<br />
each schema for which the wide index is required:<br />
add index-wide = attribute-1[, attribute-2…]<br />
One set index-xxxx command initializes all xxxx indexes, so if you specify two<br />
commands for the same special index, only the attributes of the second<br />
command will be indexed.<br />
For information about using these options, see the <strong>eTrust</strong> <strong>Directory</strong> User <strong>Guide</strong>.<br />
Warning Message: “Attribute (attrname) exceeds searchable size limit (size)”<br />
You may see the following warning message from DXserver:<br />
Attribute [attrname] exceeds searchable size limit [size] where:<br />
■<br />
■<br />
attrname is an attribute, and<br />
size is the size limit that has been exceeded.<br />
This message means that you stored a value in the attribute that exceeds the<br />
normkey. That value cannot be successfully searched for after the limit.<br />
The limit for the search table is 106 bytes, and for the wide index is 1900 bytes.<br />
If you need accurate search results for this attribute you need to create a wide<br />
index for it.<br />
If users rarely or never perform a search on this attribute, then you should turn<br />
the indexing for this attribute off.<br />
General Administration 3–31
DXcache<br />
DXcache<br />
DXcache uses in-memory techniques to make lookups on indexed attributes even<br />
faster.<br />
In a system with DXcache running, some or all attributes are preloaded into<br />
memory. When a search request involving one of these preloaded attributes is<br />
sent to the directory, the request is directed to the cache.<br />
Example: Using<br />
DXcache to speed<br />
up lookups of<br />
customer details<br />
You are setting up a directory of customer details for the call center of a phone<br />
company. The call center staff usually look up customer details using the<br />
customer’s account number, and they usually want to see the customer’s name<br />
and account balance. To speed up these lookups, you should index the account<br />
number attribute, and cache the attributes for the account number, the customer<br />
name, and the account balance.<br />
How DXcache Works<br />
When DXserver starts up, it looks in the DXI configuration file to work out which<br />
attributes should be indexed or cached. It caches and indexes those attributes.<br />
When a search request is sent to the directory, it might be directed to the cache,<br />
or it might go to the database:<br />
■<br />
■<br />
If a search is a simple lookup of an indexed attribute in the cache, requesting<br />
attributes that are in the cache, it is directed to the cache.<br />
If a search uses attributes that are not cached, it is sent to the database. This<br />
means that DXserver’s proven superior performance for complex searches is<br />
maintained.<br />
The following table shows what kinds of search DXcache can handle in different<br />
situations:<br />
Attributes in Search<br />
Filter<br />
Attributes to be<br />
Returned after a Search<br />
Search<br />
Indexed Cached The search will be<br />
performed in the cache.<br />
Cached Cached The search will be<br />
performed in the cache.<br />
No filter Cached The search will be<br />
performed in the cache.<br />
Some of these attributes are not cached<br />
The search will be<br />
performed in the directory.<br />
3–32 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXcache<br />
Design the DXcache System<br />
If you plan to use DXcache, you need to decide which attributes your users are<br />
likely to search on, and which attributes they are likely to want to return. Then,<br />
set up the following:<br />
■<br />
■<br />
Index the attributes that users are likely to enter in the search filter.<br />
Cache the indexed attributes, and the attributes that users are likely to<br />
request.<br />
You can load all attributes into the cache, to make all searches faster. This would<br />
make the cache much larger than if you only cached some attributes.<br />
DXcache also supports base-object searches, in which the search is restricted to<br />
objects below the object specified as the base object.. For base-object searches, the<br />
filter is not required, but all the other DXcache conditions must be met.<br />
Note: Multiwrite–DISP recovery cannot be used in conjunction with the cache<br />
where more than one DSA is attached to the same database.<br />
Note: The DSA start time depends on the number and size of the attributes that<br />
are to be loaded into the cache.<br />
Enable and Configure DXcache<br />
To enable caching, add the following command to the DXI initialization file:<br />
set lookup-cache = true;<br />
This command must appear after the cache and database definitions in the<br />
initialization file. DXserver loads the cache as soon as it reads the set lookup-cache<br />
command.<br />
To configure DXcache, you need to add further commands to the initialization<br />
file. These commands include::<br />
set cache-attrs<br />
set cached-only-attrs<br />
set cache-index<br />
set cache-load-all<br />
set cache-reverse<br />
set max-cache-size<br />
= {attribute1 [, attribute2 …] | all-attributes};<br />
= {attribute1 [, attribute2 …] | all-attributes};<br />
= attribute1 [, attribute2 …];<br />
= boolean;<br />
= {attribute1 [, attribute2 …] | all-attributes};<br />
= number;<br />
General Administration 3–33
DXcache<br />
DXcache Settings<br />
The following table describes the DXcache settings:<br />
DXcache Setting<br />
cache-attrs<br />
cached-only-attrs<br />
cache-index<br />
cache-load-all<br />
cache-reverse<br />
lookup-cache<br />
max-cache-size<br />
Description<br />
Defines the attributes that are returned.<br />
Use the value all-attributes to ensure that all attributes are cached; however, when<br />
a large number of attributes are used, this requires a large amount of memory.<br />
Specifies the attributes that will be stored in the cache only.<br />
Defines which attributes will be indexed.<br />
The cache responds to a search filter that uses one of these attributes. You can<br />
define as many as you like, separated by commas. Memory requirements are<br />
affected.<br />
Forces DXcache to load all entries in the database into the cache.<br />
DXcache can only handle searches where the filter does not reference an indexed<br />
attribute if it knows that all the entries have been loaded into the cache.<br />
Sets the cache to reverse-index the attributes.<br />
Enables or disables DXcache.<br />
Sets the maximum amount of memory (in MB) that the cache is permitted to use.<br />
This setting depends on how much memory your computer has. We recommend<br />
that you set this to 50% to 70% of your machine’s total memory, depending on<br />
other programs’ memory requirements on the same computer.<br />
Note: The cache uses the minimum amount of memory required to store the<br />
indexes and results. An alarm is raised and the cache is disabled when the cache<br />
requires more memory than defined with max-cache-size.<br />
Index the Attributes To Be Used in the Search Filters<br />
The following command indexes the attributes that appear in the search filters:<br />
set cache-index = attribute [, attribute …];<br />
The cache holds all entries that contain one or more of these attributes. Entries<br />
that contain none of the attributes in this list are not loaded into the cache. The<br />
choice of indexed attributes directly affects the number of entries in the cache.<br />
3–34 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXcache<br />
Index the Attributes To Be Returned by Search Requests<br />
The following command specifies the attributes that will be returned by the<br />
search request:<br />
set cache-attrs = {attribute1 [, attribute2 …] | all-attributes};<br />
The indexed attributes are already cached so you only need to specify any<br />
additional attributes.<br />
Search requests that do not specifically request particular attributes to be returned<br />
are actually implicitly requesting the return of all attributes. To cater for this type<br />
of request, you can use the following command to cache all attributes:<br />
set cache-attrs = all-attributes;<br />
If you cache all attributes, DXcache will require more memory than if you cached<br />
only some attributes.<br />
Set the Maximum Cache Size<br />
To set the cache size, use the following command:<br />
set max-cache-size = number;<br />
You must specify the maximum memory that the cache may use. The cache<br />
always uses the minimum amount possible.<br />
The cache is designed to be memory-resident, so make sure that the maximum<br />
cache size is less than the RAM available. For example, if the cache size is 2 GB<br />
but there is only 500 MB of RAM, the cache has not been configured correctly.<br />
One million entries, including their attributes, occupy about 2GB of memory.<br />
DXserver and other 32-bit Windows applications each have a virtual address<br />
space limitation of 2GB, regardless of the amount of memory in the system.<br />
UNIX-like operating systems have a limit of 4 GB.<br />
Do not set the cache size equal to the memory available. You should leave some<br />
RAM for the operation system. For example, if your operating system uses<br />
250 MB on a 1 GB computer, do not set the max-cache-size to more that 750 MB.<br />
General Administration 3–35
DXcache<br />
Set DXcache to Process All Search Requests<br />
The cache does not help with some types of search request. For example, the<br />
following requests will be directed to the database, not to the cache:<br />
■<br />
■<br />
■<br />
commonname=*smith*<br />
Search requests where the filter does not specify an indexed attribute.<br />
One-level searches without filters (or with the filter (objectclass=*)<br />
To set the cache to process all search requests, add the following commands:<br />
set cache-load-all = true;<br />
set cache-attrs = all-attributes;<br />
The first command ensures that all entries are loaded into the cache, while the<br />
second ensures that all attributes in each entry are loaded. Each of them increases<br />
the amount of memory used by the cache, so make sure that you only use them if<br />
required.<br />
Generally, NOTs can only be processed if all entries are in the cache.<br />
Reverse-Index Cached Attributes<br />
If the users use searches of the form (telephonenumber=*1234), you may index<br />
some attributes so they index the values after reversing the order of the bytes.<br />
Use the following command to reverse-index a cached attribute:<br />
set cache-reverse = attribute<br />
For example, 123-4567 will be indexed as if it were 7654-321.<br />
Example DXcache Configuration<br />
You are running DXserver on a 2GB system, and you want to use a 1.5 GB cache.<br />
You know that users often search on the attributes commonName and<br />
organizationalUnitName, and they often want to return the attributes commonName<br />
and description.<br />
To configure DXcache for this situation, add the following commands to the end<br />
of the servername.dxi file.<br />
set database-name = database;<br />
:<br />
set lookup-cache = true;<br />
set cache-attrs = description;<br />
set cache-index = commonName, organizationalUnitName;<br />
set max-cache-size = 1500;<br />
3–36 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXcache<br />
View the DXcache Configuration<br />
To view the cache configuration variables and their values, use the command:<br />
get cache;<br />
This command displays whether the cache is enabled and provides some<br />
statistical information about the cache configuration. Example output of this<br />
command is shown below:<br />
Cache enabled<br />
max-cache-size = 1000 (MB)<br />
entry hash size 2550, maxp 10<br />
cache-attrs = postalCode cosineUserid<br />
cache-index =<br />
surname(0/0)<br />
commonName(0/0)<br />
Memory used by cache: 1008316/1183947<br />
Keep DXcache Synchronized with the Database<br />
Updates received by a DSA running DXserver are applied first to the database<br />
and then to the DXcache.<br />
All updates successfully applied to the database are applied to the cache.<br />
Therefore, if no other DXserver is updating the database, the cache will remain<br />
synchronized.<br />
If the database is updated by other instances of DXservers, you should configure<br />
the DXservers to keep their caches synchronized. To achieve this, set the<br />
following:<br />
■<br />
■<br />
All DXservers that update the database must belong to a multiwrite group<br />
(see the chapter Replication for more information about multiwrite groups.)<br />
All DXservers that update the database must have the DSA flag multi-writenotify<br />
set in their knowledge file.<br />
The effect of this is that multiwrite updates are sent to the cache but they will<br />
update only the cache contents—they are not reapplied to the database. Thus, the<br />
cache remains synchronized with the database.<br />
General Administration 3–37
DXcache<br />
Use <strong>eTrust</strong> <strong>Directory</strong> in Cache-Only Mode<br />
You can run <strong>eTrust</strong> <strong>Directory</strong> in cache-only (memory-resident) mode. In this<br />
mode, <strong>eTrust</strong> <strong>Directory</strong> uses DXcache as its repository, rather than a database.<br />
Traditional directories were designed with the following assumptions:<br />
■<br />
■<br />
Persistent data storage<br />
Data is read much more often than it is written to<br />
However, with the advent of web applications and web services, there is a<br />
growing need for a directory service with the following characteristics:<br />
■<br />
■<br />
Transient data storage<br />
Data is read about the same number of times it is written to<br />
Configure Cache-Only Mode<br />
To create a cache-only DXserver, simply remove all references to database and<br />
database settings, and add the following to your configuration:<br />
set cache-only = true;<br />
Of course none of the database DXtools can be used with a cache-only DXserver.<br />
You must use the DXmodify or ldapmodify tools to load the cache and the<br />
DXsearch or ldapsearch tools to dump its contents.<br />
How <strong>eTrust</strong> <strong>Directory</strong> Works in Cache-Only Mode<br />
A cache-only DXserver reads and writes data extremely quickly. It can service<br />
thousands of updates per second, rather than the tens or hundreds of updates<br />
per second for traditional directories.<br />
This update speed is achieved because the data in the repository is never written<br />
to disk. There is no write-behind strategy of any kind. A cache-only DXserver<br />
does not even require Ingres or any other database to be running.<br />
If a cache-only DXserver is shut down or is stopped by a software or hardware<br />
problem, all data is lost and cannot be recovered. Thus it is ideally suited for<br />
storing short-lived data that needs to be updated frequently.<br />
3–38 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXcache<br />
Example of a Cache-Only <strong>Directory</strong><br />
You could use a cache-only directory to store web session objects.<br />
These objects are only required for a short time and may be updated repeatedly,<br />
and have no long-term value. There may be thousands of these objects in use at<br />
peak times and so an application still requires the scalability and availability<br />
offered by traditional directories. However, storing such objects in a traditional<br />
directory is prohibitively expensive because of the cost of updates which must<br />
eventually be written to disk.<br />
In this situation, a cache-only DXserver could be used to manage only the session<br />
objects, leaving a traditional directory to manage the persistent data.<br />
General Administration 3–39
Virtual Attributes<br />
Virtual Attributes<br />
This section describes two different kinds of virtual attributes:<br />
Dynamic groups<br />
These can reduce the time you spend updating the membership of groups.<br />
Class of Service templates<br />
These can reduce the size of the directory, reduce the time you spend doing<br />
bulk updates, and help keep information consistent.<br />
Dynamic Groups<br />
<strong>eTrust</strong> <strong>Directory</strong> supports static, dynamic, and hybrid groups.<br />
Static groups are useful for directories when the members of groups do not<br />
change often.<br />
Dynamic groups are useful when you know that you will often need to change<br />
the membership of a group, because there is no overhead involved in<br />
maintaining the group data.<br />
Hybrid groups allow you to use the features of both static and dynamic groups.<br />
How Static Groups Work<br />
Users and other entries can be grouped in the directory using a static group<br />
entry. A static group entry contains a list of member DNs. The static group entry<br />
usually has an object class of “groupOfNames” and an attribute “member” that<br />
has one value for each of the members in the group.<br />
If a user is removed from the directory, then the user must also be removed from<br />
any static groups that they belonged to. This must be done manually by<br />
removing the user’s member DN from each group that the user was a member<br />
of.<br />
How Dynamic Groups Work<br />
A dynamic group does not store each member DN in its directory entry. Instead,<br />
it stores an LDAP search request that is executed when a base-object search is<br />
performed on the dynamic group entry. This LDAP search finds all the members<br />
that satisfy the search filter and return the DNs of those members.<br />
If a user is removed from the directory, then their user entry will not be found by<br />
the LDAP search, so the user will have been automatically removed from the<br />
dynamic group.<br />
3–40 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Virtual Attributes<br />
How Hybrid Groups Work<br />
It is possible to create a hybrid group. This is a group entry that contains both an<br />
LDAP search attribute and a list of one or member DNs.<br />
To create a hybrid group, make sure that the “member-attr” in the dynamic<br />
group definition is the same as the attribute used to store the static members.<br />
This means that the static and dynamic members will be combined when a baseobject<br />
search is performed on the entry.<br />
Enabling Dynamic Groups<br />
To turn on dynamic groups, add the following to the DSA configuration file.<br />
clear dynamic-group;<br />
set dynamic-group GROUP = {<br />
object class = groupOfURLs<br />
url-attr = memberURL<br />
member-attr = member<br />
};<br />
You can also use other object classes and attributes than those shown above.<br />
However, the “url-attr” must have a string syntax and must be a MUST or MAY<br />
container attribute of the object class. The “member-attr” must have a<br />
distinguishedName syntax, because it is used to return the DNs of the members.<br />
Creating a Dynamic Group<br />
To create a dynamic group, add an entry to the directory that has an object class<br />
as defined in the dynamic group configuration and an attribute as defined by the<br />
“url-attr” in the dynamic group configuration.<br />
The value of the “url-attr” in the dynamic group entry is an LDAP search which<br />
has the following form:<br />
ldap:///Base DN of Search??Scope?Filter<br />
The Scope value is optional. It has three possible values:<br />
■<br />
■<br />
■<br />
sub—searches the entire subtree<br />
base—searches the base DN only. This is the default, but it is the least useful<br />
option.<br />
one—searches the top level of the subtree only<br />
The Filter value is also optional. The value is any LDAP search filter string. The<br />
default value is OC present.<br />
For example, to search for all people in the Finance department in either the<br />
Payroll or Accounts groups:<br />
ldap:///ou-finance,o=democorp,c=au??sub?<br />
(|(organizationalUnitName=payroll)(organizationalUnitName=accounts))<br />
General Administration 3–41
Virtual Attributes<br />
Viewing Dynamic Groups<br />
The dynamic group configuration in use in a DSA can be viewed using the<br />
console command:<br />
get dynamic-groups;<br />
This will produce a listing of each dynamic-group in use, with the group label at<br />
the top. A sample configuration follows:<br />
************** GROUP **************<br />
Group object class : groupOfURLs<br />
Group Search URL : memberURL<br />
Member to Append : member<br />
3–42 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Virtual Attributes<br />
Class of Service Templates<br />
When directory information needs to be shared across multiple entries, the<br />
shared information can be stored in a Class of Service (CoS) template.<br />
Then, when a search returns an entry that contains a Class of Service attribute,<br />
the attributes and values from the associated template are included in the entry.<br />
This means that the information in CoS templates is only stored once, which is<br />
good for three reasons:<br />
■<br />
■<br />
■<br />
<strong>Directory</strong> size is reduced<br />
Simple bulk updates are faster<br />
Information is consistent<br />
The shared information is usually a level of service, such as a standard or<br />
premium subscription to an internet service provider.<br />
How Class of Service Templates Work<br />
The virtual attributes and values are stored in templates, which are kept in a<br />
DXserver configuration file.<br />
When a search returns an entry that contains the CoS attribute, the attributes and<br />
values from the associated template are presented.<br />
A template can have multiple attributes and values. All attributes in a template<br />
will be added to the entry.<br />
If an entry already has an value for an attribute in a template, the attribute in the<br />
template can either over-write the value, or the value can be left untouched. This<br />
is controlled by the disposition of the template attribute. The two possible<br />
dispositions are:<br />
■<br />
■<br />
default—The value from the template replaces the existing value<br />
override—If the entry already contains this attribute, the existing value will<br />
persist. Use this when a customer requires special treatment.<br />
The attributes that are stored in CoS templates are not searchable.<br />
General Administration 3–43
Virtual Attributes<br />
Example: The Excellent ISP Company<br />
The company Excellent ISP is an internet service provider. The customers of<br />
Excellent ISP can subscribe for one of two classes of service:<br />
Standard<br />
Premium<br />
Mail Storage 20 MB 30 MB<br />
Web Space 20 MB 30 MB<br />
Hours per Month 15 hr Unlimited<br />
Cost per Month $19.95 $29.95<br />
Cost of Extra Hours $1.00/hr $0.00/hr<br />
The Excellent ISP customer directory includes the subscription information in<br />
each customer entry.<br />
Entries Without Class<br />
of Service Virtual<br />
Attributes<br />
Before CoS is introduced, this information is stored in each entry. If there are<br />
one million users, then these attributes appear one million times. If Excellent<br />
ISP increases its fees, then a large global update is required.<br />
Here is an example entry for an Excellent ISP customer who has the standard<br />
class of service:<br />
dn: cn=John Smith, o=Excellent ISP, c=US<br />
oc: inetOrgPerson<br />
oc: excellentISPuser<br />
cn: John Smith<br />
sn: Smith<br />
excellentISPmailQuotaMB: 20<br />
excellentISPwebSpaceMB: 20<br />
excellentISPaccessHours: 15<br />
excellentISPprice: 19.95<br />
excellentISPextraHoursPrice: 1.00<br />
excellentISPpackage: Standard<br />
Here is an example entry for an Excellent ISP customer who has the premium<br />
class of service:<br />
dn: cn=Mary Chen, o=Excellent ISP, c=US<br />
oc: inetOrgPerson<br />
oc: excellentISPuser<br />
cn: Mary Chen<br />
sn: Chen<br />
excellentISPmailQuotaMB: 30<br />
excellentISPwebSpaceMB: 30<br />
excellentISPaccessHours: Unlimited<br />
excellentISPprice: 29.95<br />
excellentISPextraHoursPrice: 0<br />
excellentISPpackage: Premium<br />
3–44 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Virtual Attributes<br />
Entries With Class of<br />
Service Virtual<br />
Attributes<br />
To save space and time, the shared information in these entries can be moved<br />
into a template. The shared information in the entries is then replaced with a<br />
new attribute, whose value indicates which CoS template to use.<br />
The attributes from the CoS template will be added to the entry on a search.<br />
dn: cn=John Smith, o=Excellent ISP, c=US<br />
oc: inetOrgPerson<br />
oc: excellentISPuser<br />
cn: John Smith<br />
sn: Smith<br />
excellentISPpackage: Standard<br />
dn: cn=Mary Chen, o=Excellent ISP, c=US<br />
oc: inetOrgPerson<br />
oc: excellentISPuser<br />
cn: Mary Chen<br />
sn: Chen<br />
excellentISPpackage: Premium<br />
Class of Service<br />
Templates<br />
The Excellent ISP company would need to use two templates. The standardlevel<br />
template would appear as follows:<br />
set class-of-service standard = {<br />
object class = excellentISPuser<br />
cos-attr = excellentISPpackage<br />
cos-value = "Standard"<br />
attribute-values = {<br />
(type = excellentISPmailQuotaMB<br />
value = "20"<br />
disposition = default),<br />
(type = excellentISPwebSpaceMB<br />
value = "20"<br />
disposition = default),<br />
(type = excellentISPaccessHours<br />
value = "15"<br />
disposition = override),<br />
(type = excellentISPprice<br />
value = "19.95"<br />
disposition = default),<br />
(type = excellentISPextraHoursPrice<br />
value = "1.00"<br />
disposition = default)<br />
}<br />
};<br />
General Administration 3–45
Virtual Attributes<br />
The premium-level template would appear as follows:<br />
set class-of-service premium = {<br />
object class = excellentISPuser<br />
cos-attr = excellentISPpackage<br />
cos-value = "Premium"<br />
attribute-values = {<br />
(type = excellentISPmailQuotaMB<br />
value = "30"<br />
disposition = default),<br />
(type = excellentISPwebSpaceMB<br />
value = "30"<br />
disposition = default),<br />
(type = excellentISPaccessHours<br />
value = "Unlimited"<br />
disposition = override),<br />
(type = excellentISPprice<br />
value = "29.95"<br />
disposition = default),<br />
(type = excellentISPextraHoursPrice<br />
value = "0.00"<br />
disposition = default)<br />
}<br />
};<br />
Configuring Class of Service Virtual Attributes<br />
When the shared attribute values change, they can be updated in the<br />
configuration files. Therefore, make sure that configuration files are stored in a<br />
source code control system to allow for rollbacks.<br />
Distribution of CoS entries is achievable, but requires the DSA configuration to<br />
be manually copied to all nodes.<br />
Configure the DSA<br />
Add the following line to the local DSA configuration to clear any currently<br />
cached CoS information.<br />
clear class-of-service;<br />
This allows CoS attribute modifications to be made which can be included while<br />
the DSA is still running using the command dxserver init.<br />
Make sure that the template configuration file is sourced after the schema is<br />
sourced. The template uses attributes that are defined in the schema<br />
configuration.<br />
Add CoS Attributes to<br />
Entries<br />
To use CoS templates with an entry, add the cos-attr attribute to the entry.<br />
3–46 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Virtual Attributes<br />
Create Class of<br />
Service Templates<br />
Templates can be stored in any directory. However, if there are many<br />
templates, you should store them in separate files in the<br />
DXHOME/config/settings directory.<br />
The Class of Service templates use the following syntax:<br />
::= set class-of-service = { };<br />
::= <br />
::= object-class = cos-attr = cos-value =<br />
attribute-values = { }<br />
::= | , <br />
::= ( type = value = disposition =<br />
)<br />
::= value | value, <br />
::= default | override<br />
Note: The cos-attr used in a Class of Service template must be a single-valued<br />
attribute.<br />
Viewing Class of Service Templates<br />
The templates in use in a DSA can be viewed using the console command:<br />
get class-of-service;<br />
This will produce a listing of each class of service template in use, with the<br />
template label at the top. For example, the template for the standard class of<br />
service at the company Excellent ISP discussed in the example above would<br />
appear like this:<br />
************** standard **************<br />
class-of-service =<br />
target object class : excellentISPUser<br />
target attribute : excellentISPPackage<br />
target value : "Standard"<br />
attribute list =<br />
attribute : excellentISPmailQuotaMB<br />
value/s : "20"<br />
disposition : default<br />
attribute : excellentISPwebSpaceMB<br />
value/s : "20"<br />
disposition : default<br />
attribute : excellentISPaccessHours<br />
value/s : "15"<br />
disposition : override<br />
attribute : excellentISPprice<br />
value/s : "19.95"<br />
disposition : default<br />
attribute : excellentISPextraHoursPrice<br />
value/s : "1.00"<br />
disposition : default<br />
General Administration 3–47
Knowledge Flags<br />
Knowledge Flags<br />
This section describes how to use knowledge flags to define the configuration,<br />
security, and interoperability of DSAs. This section also includes tables that list<br />
all of the possible knowledge flags.<br />
For information about how knowledge files work, see Knowledge Files in the<br />
chapter DXserver Overview.<br />
The Three Kinds of Knowledge Flags<br />
The DXserver uses three sets of flags to define the configuration, security, and<br />
interoperability of DSAs:<br />
DSA Flags<br />
DSA flags define which operations that can be performed on the local DSA.<br />
These flags can be used by the local DSA to determine which operations it<br />
can process. They can also be used by remote DSAs to determine which<br />
operation the local DSA will process..<br />
Trust Flags<br />
Trust flags define how a DSA works with a remote DSA. Trust flags only<br />
affect how a remote DSA works.<br />
Link Flags<br />
Link flags define any special conditions for linking to the remote DSA,<br />
including the protocol, encryption level, and any interoperability<br />
requirements for specific applications.<br />
Example: Flags in a Knowledge File<br />
The following example knowledge file includes all three types of flags:<br />
set dsa democorp =<br />
{<br />
...<br />
dsa-flags = multi-write, shadow, load-share, no-routing-ac, limit-search,<br />
limit-list<br />
trust-flags = allow-check-password, trust-conveyed-originator, allowupgrading,<br />
allow-downgrading, no-server-credentials<br />
link-flags = dsp-ldap, ssl-encryption-remote, ms-ad<br />
};<br />
The DSA flags will be used by the Democorp DSA when a client or another<br />
DSA attempts to run an operation on it. Also, other (remote) DSAs can use the<br />
DSA flags to check which operations can be sent to the Democorp DSA.<br />
The trust flags will be used by remote DSAs to check how much they should<br />
trust the Democorp DSA.<br />
The link flags will be used by remote DSAs to define how they should link to the<br />
Democorp DSA.<br />
3–48 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Knowledge Flags<br />
Example: How the limit-search DSA Flag Works<br />
DSA flags are used by a DSA to define how it responds to operations that other<br />
DSAs or clients attempt to perform on it.<br />
The following example shows how the limit-search DSA flag works:<br />
1. The UNSPSC receives an unfiltered search request from a client.<br />
The UNSPSC DSA cannot fulfill the search request, but it knows that the<br />
Company A DSA can.<br />
2. The UNSPSC DSA checks the Company A knowledge file to see whether<br />
there are any conditions for searching the Company A DSA.<br />
The flag limit-search indicates that the Company A DSA will reject any<br />
unfiltered or complex searches.<br />
3. The UNSPSC DSA returns a Search Refused response to the client.<br />
set dsa<br />
companya = {<br />
dsa-flags =<br />
limit-search<br />
Client<br />
Application<br />
(JXplorer)<br />
1. Search request<br />
o=”Company A”<br />
3. Search response<br />
2. Check Company A<br />
DSA flags<br />
UNSPSC DSA<br />
};<br />
companya.dxc<br />
Company A<br />
DSA<br />
Using DSA flags to define how a DSA responds to requests<br />
For information about particular DSA flags, see List of all DSA Flags in this<br />
chapter.<br />
General Administration 3–49
Knowledge Flags<br />
Example: How the allow-check-password Trust Flag Works<br />
Remote DSAs use trust flags to define how much they should trust a DSA.<br />
By default, security is tight. The trust flags provide a mechanism to selectively<br />
relax security between DSAs.<br />
The following example shows how a DSA uses the trust flag allow-checkpassword:<br />
1. The UNSPSC DSA receives a bind request from a user whose credentials are<br />
stored in the Democorp DSA. The UNSPSC DSA cannot check the user’s<br />
credentials, but it knows that the Democorp DSA can.<br />
2. The UNSPSC DSA checks the Democorp knowledge file to see whether it can<br />
trust the Democorp DSA to authenticate a user. The flag allow-check-password<br />
indicates that this is permissible.<br />
3. The UNSPSC DSA requests the Democorp DSA to authenticate the user.<br />
4. The Democorp DSA responds with the user’s authentication.<br />
5. The UNSPSC DSA returns the bind confirmation to the client.<br />
set dsa<br />
democorp = {<br />
trust-flags =<br />
allow-checkpassword<br />
dn=<br />
Knowledge Flags<br />
Example: How the dsp-ldap Link Flag Works<br />
Remote DSAs use link flags to define any special conditions for a link to another<br />
DSA.<br />
The following example shows how the dsp-ldap flag works.<br />
1. The UNSPSC DSA receives a request to search the remote DSA named<br />
Company A, which happens to be an LDAP server.<br />
2. The UNSPSC DSA checks the Company A knowledge file to see whether<br />
there are any special conditions for linking to that DSA. The flag dsp-ldap<br />
indicates that the Company A DSA requires that any links use LDAP.<br />
3. The UNSPSC DSA uses DXlink to make an LDAP search request of the<br />
Company A DSA.<br />
4. The Company A DSA responds with the search result (also using LDAP).<br />
5. The UNSPSC DSA returns the search result to the client.<br />
set dsa<br />
companya = {<br />
link-flags =<br />
dsp-ldap<br />
2. Check Company A<br />
link flags<br />
};<br />
companya.dxc<br />
Client<br />
Application<br />
(JXplorer)<br />
1. Search request<br />
o=”Company A”<br />
5. Search response<br />
UNSPSC DSA<br />
3. Search request (LDAP)<br />
4. Search response (LDAP)<br />
Company A<br />
LDAP server<br />
Using Link Flags to Define the Nature of a Link Between DSAs<br />
For information about particular link flags, see List of all Link Flags in this<br />
chapter.<br />
General Administration 3–51
Knowledge Flags<br />
List of all DSA Flags<br />
The following table lists and describes all of the available DSA flags:<br />
DSA Flag<br />
limit-list<br />
limit-search<br />
load-share<br />
ms-ad<br />
multi-write<br />
multi-write-async<br />
Description<br />
Disables the list operation on the DSA.<br />
For more information, see Query Streaming in the chapter Distribution and<br />
DSP, and Limit List in this chapter.<br />
Restricts complex searches or searches with no filter on the DSA.<br />
For more information, see Query Streaming in the chapter Distribution and<br />
DSP, and Limit Search in this chapter.<br />
Marks a DSA as part of a load share group. The DSA should have other peer<br />
DSAs with the same prefix, which are also marked as load-share. A router DSA<br />
shares operations over each DSA in the load share group.<br />
See the section Load Sharing DSAs in the chapter Distribution and DSP.<br />
Active <strong>Directory</strong> - The DSA is treated as a Microsoft Active <strong>Directory</strong> server. Set<br />
this flag if you observe any problems with linking to Active <strong>Directory</strong>.<br />
See also Connecting to Active <strong>Directory</strong> in Chapter 11 of the User <strong>Guide</strong>.<br />
Marks a DSA as part of a multiwrite group. The DSA should have other peer<br />
DSAs, with the same prefix, which are also marked as multiwrite. Updates are<br />
automatically propagated to all peer DSAs marked as multiwrite.<br />
See the chapter Replication for more information.<br />
Makes the DSA update asynchronously, even though it is in a multiwrite group.<br />
See Asynchronous Multiwrite Behavior in the Replication chapter.<br />
multi-write-disp-queue Allows multiwrite queues while DISP is in progress. Multiwrite DISP recovery<br />
cannot be used where more than one DSA is attached to the same database.<br />
See Multiwrite Recovery With DISP in the Replication chapter.<br />
multi-write-notify<br />
no-routing-ac<br />
read-only<br />
relay<br />
shadow<br />
Sends multiwrite updates to DXcache.<br />
Permits forwarding of a request to another DSA regardless of access control<br />
constraints.<br />
See Access-Controlled Routing in the chapter Security for more information.<br />
Disables update operations on the DSA.<br />
See also Query Streaming in the chapter Distribution and DSP.<br />
Permits a router DSA to exist without consuming a level of the DIT.<br />
See Configuring a Relay DSA in the chapter Distribution and DSP.<br />
Permits a DSA to be updated by DISP or multiwrite, but prevents any other<br />
updates (for example, through DAP or LDAP) from occurring.<br />
See the chapter Replication.<br />
3–52 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Knowledge Flags<br />
List of all Trust Flags<br />
The following table lists and describes all of the available trust flags:<br />
Trust Flag<br />
allow-check-password<br />
Description<br />
Permits a DSA, while processing a bind request from a user who is not local, to<br />
pass a name and password-compare request to this DSA. The result of the<br />
compare request is then used to authenticate the user.<br />
See Distributed User Authentication in the chapter Security for more<br />
information.<br />
trust-conveyed-originator Signifies that a DSA treats the originator and authentication level passed in DSP<br />
chaining arguments as if that user and authentication level were authenticated<br />
locally.<br />
allow-upgrading<br />
allow-downgrading<br />
no-server-credentials<br />
See Distributed User Authentication in the chapter Security for more<br />
information.<br />
Lets the DSA pass an anonymous user request across an authenticated DSP link.<br />
See Authentication in the chapter Security for more information.<br />
Lets the DSA pass an authenticated user request across an anonymous DSP link.<br />
See Authentication in the chapter Security for more information.<br />
Removes the requirement for mutual authentication and permits a link to be set<br />
up if the remote DSA does not send credentials in the bind response.<br />
See User Credentials on the DXlink Binds in the chapter LDAP and DXlink for<br />
more information.<br />
General Administration 3–53
Knowledge Flags<br />
List of all Link Flags<br />
The following table lists and describes all of the available link flags:<br />
Link Flag<br />
dsp-ldap<br />
dsp-ldap-proxy<br />
dsp-ldapv2<br />
ms-ad<br />
ms-exchange<br />
ssl-encryption<br />
ssl-encryption-remote<br />
unavailable<br />
Description<br />
The DSA is treated as an LDAP server that supports LDAP 3.0. Other DSAs will<br />
send requests to the DSA using DXlink.<br />
When dsp-ldap is configured, there will be no COMPARE operation on the<br />
userPassword attribute, following a bind over DXlink. If the same user connects<br />
more than once, that user will use the same link, and dxserver will check that<br />
the user and the password are the same.<br />
See Integrating Other LDAP Servers in the chapter LDAP and DXlink for more<br />
information.<br />
Causes the last DSA in the chain to use the authorization of the originating user<br />
to perform operations on the LDAP server.<br />
See Automatically Authorizing LDAP Operations in the chapter LDAP and<br />
DXlink for more information.<br />
The DSA is treated as an LDAP server that supports LDAP 2.0. Other DSAs will<br />
send requests to the DSA using DXlink.<br />
See Integrating Other LDAP Servers in the chapter LDAP and DXlink for more<br />
information.<br />
The DSA is treated as an Active <strong>Directory</strong> service. If you observe any problems<br />
with linking to Active <strong>Directory</strong>, set this flag. See Connecting to Active<br />
<strong>Directory</strong> in the chapter “Connecting to Other Applications and LDAP” in the<br />
User <strong>Guide</strong> for more information.<br />
The DSA is treated as a Microsoft Exchange server to overcome limitations in<br />
Exchange’s version of LDAP.<br />
See Integrating Other LDAP Servers in the chapter LDAP and DXlink for more<br />
information.<br />
Any DSA DSA-to to-DSA communication to the DSA with this link flag will be<br />
made using SSL encryption.<br />
See DSA-to-DSA Encryption (DSP and DISP) in the chapter Security for more<br />
information.<br />
It is similar to ssl-encryption, but SSL encryption is not used if the target<br />
DXserver is on the same host.<br />
Marks a DSA as unavailable. A DSA will not forward requests to a DSA marked<br />
as unavailable.<br />
3–54 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
4<br />
Schema Definition<br />
The directory schema is a set of configurable rules that a DSA enforces on the<br />
data created within the directory. These rules define:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
The names of the various types of attributes that can exist in an entry<br />
The syntax (or data type) of each of these attributes<br />
Which attributes in each object class (a defined group of attributes) are<br />
mandatory and which are optional<br />
How each directory entry is named (for example, a person is named by his or<br />
her common-name attribute)<br />
Where the directory entry can be created in the DIT (for example, an<br />
OrganizationalUnit entry can only exist under an Organization entry)<br />
<strong>eTrust</strong> <strong>Directory</strong> provides a full directory schema definition starter kit, including:<br />
■ OSI (X.500, X.400, X.435 [EDI] )<br />
■<br />
■<br />
■<br />
Internet (LDAP, Inet, Cosine, Quipu, Thorn)<br />
Industry (JNDI, DADF, Mosaic, UNSPSC)<br />
Organizations (DMS, Umich, Entrust, RSA, Netscape)<br />
This chapter includes information about schema files, attribute definitions,<br />
schema prefixes, object class definitions, and name bindings. Name bindings are<br />
an implementation of the X.500 DIT Structure Rules.<br />
The schema of a running directory is available to LDAP clients via the LDAP<br />
Version 3 mechanism of schema publishing. See Schema Publishing in the<br />
chapter LDAP and DXlink for more information.<br />
Schema Definition 4–1
Configuring Schema<br />
Configuring Schema<br />
DXserver checks and validates schema rules on every update operation to<br />
maintain directory integrity.<br />
All aspects of X.500 schema are fully configurable, down to the attribute syntaxes<br />
(basic directory information types) compiled in the entry.<br />
You should create the schema within configuration files (that is, in the<br />
DXHOME/config/schema directory) rather than dynamically using the console<br />
interface, as the latter will only remain in effect while that DSA is running.<br />
Important! The DXtools require a separate schema file, schema.txt. If you add or change<br />
the schema definition for DXserver, you must also update schema.txt for the tools. For<br />
information about how to update schema.txt, see SCHEMA Tools in the chapter "Using<br />
DXtools."<br />
Grouping Schema<br />
You usually define schema in a single definition file. All schema definition files<br />
reside in the schema configuration directory. When building your directory<br />
schema, you typically need definitions from several schema definition files. You<br />
can group these schema definition files together in a single file using the source<br />
command. The following is an example schema.dxg file:<br />
# Schema definition file – schema.dxg<br />
source “x500.dxc”;<br />
source “cosine.dxc”;<br />
source “mhs.dxc”;<br />
source “quipu.dxc”;<br />
The DXserver initialization (for instance, democorp.dxi) file sources this schema<br />
definition.<br />
# DSA initialization file – democorp.dxi<br />
...<br />
# SCHEMA<br />
source “../schema/schema.dxg”;<br />
...<br />
4–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring Schema<br />
Managing Schema<br />
There are a number of parameters to the schema module set commands that let<br />
you change the schema configuration. You can view them by the schema module<br />
get command. The following tables summarize these commands and the<br />
following sections explain them in more detail.<br />
You can manage and monitor schema configuration using the commands:<br />
■<br />
■<br />
set parameter = value;<br />
get schema for parameter;<br />
Schema Commands<br />
The following are the parameters for the set schema command:<br />
Parameter<br />
oid-prefix<br />
attribute<br />
attr-set<br />
object-class<br />
name binding<br />
Value<br />
Defines an object identifier (OID) prefix. An OID prefix consists of a name used<br />
to represent the portion of the object identifier common to multiple schema<br />
definition statements.<br />
Defines an attribute. An attribute consists of an attribute name, alternate name,<br />
syntax, single-valued flag, and a description.<br />
Defines an attribute set. An attribute set consists of an attribute set name and a<br />
list of previously defined attributes or attribute sets.<br />
Defines an object class. An object class consists of an object class name, an<br />
alternate name, a subclass definition, an object class kind, a must-contain list of<br />
previously defined attributes or attribute sets, a may-contain list of previously<br />
defined attributes or attribute sets, and a description.<br />
Defines a name binding between two previously defined object classes. A name<br />
binding consists of a name for the name binding, an object and its allowable<br />
parent, and an attribute that names the object.<br />
The following is the parameter of the get schema command:<br />
Parameter<br />
for<br />
Value<br />
Item; a name or an object identifier of any schema definition (an attribute, object<br />
class, name binding, prefix, or attribute set).<br />
Schema Definition 4–3
Configuring Schema<br />
Viewing Schema<br />
Example: Viewing<br />
Schema Definition<br />
To retrieve the definition of commonName, use the command:<br />
get schema for commonName; or<br />
get schema for (2.5.4.3);<br />
An example output of this command is:<br />
Attribute (2.5.4.3)<br />
name = commonName<br />
ldap-names = cn<br />
syntax = caseIgnoreString<br />
You can use the name, ldap-names, or object identifier with this command.<br />
Schema Prefixes<br />
All attribute, attribute set, object class, and name binding definitions have a<br />
unique object identifier (for example, 2.5.4.6) that uniquely identifies that object.<br />
When defining a schema, you can find many definitions on the same branch of<br />
the schema definition tree. You can define a schema prefix that replaces the<br />
branch of the tree in all subsequent definitions.<br />
Example: Schema<br />
Prefix Definition<br />
set oid-prefix x500attr = (2.5.4);<br />
set oid-prefix x500oc = (2.5.6);<br />
set oid-prefix x500aset = (2.5.7);<br />
set oid-prefix x500nbind = (2.5.15);<br />
set attribute x500attr:3 = {<br />
name = commonName<br />
ldap-names = cn<br />
syntax = caseIgnoreString };<br />
Given the previous definition, the prefix x500attr can replace any occurrence of<br />
the 2.5.4 portion of an object identifier. Thus, an attribute with the object<br />
identifier of 2.5.4.6 can also be represented as x500attr:6.<br />
Without schema prefixes, the previous definition would read:<br />
set attribute (2.5.4.3) = {<br />
name = commonName<br />
ldap-names = cn<br />
syntax = caseIgnoreString ;<br />
Schema prefixes improve readability and reduce the chance of errors in the<br />
definition, especially when the object identifiers are long. For example, the object<br />
identifiers of each of the Quipu attributes are of the form<br />
0.9.2342.19200300.99.1.x, making a prefix desirable.<br />
4–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Attributes<br />
Attributes<br />
An attribute is the foundation of directory information. It consists of a type, for<br />
example, commonName, and one or more values, for example, Rick, Richard.<br />
You define an attribute in the configuration file with information about its object<br />
identifier (OID), name, LDAP names, syntax, whether it is single-valued,<br />
whether its value can be modified, and a description.<br />
You can define more than one LDAP name for each attribute. The LDAP name<br />
defaults to the attribute name, so typically you only need to define the LDAP<br />
name when it is different from the attribute name.<br />
There is no limit to the number of attributes or rules that you can define for a<br />
DSA or on the size of the attributes you can store in the DSA.<br />
Example: Attribute<br />
Definition<br />
Example: Read-Only<br />
Attribute Definition<br />
set attribute x500attr:3 = {<br />
name<br />
= commonName<br />
ldap-names = cn<br />
syntax<br />
= caseIgnoreString<br />
description = "Common Name attribute"<br />
};<br />
schema set attribute (2.5.18.1) = {<br />
name = createTimestamp<br />
syntax = generalizedTime<br />
no-user-modification<br />
};<br />
Schema Definition 4–5
Attributes<br />
Attribute Syntaxes<br />
Attribute syntaxes define the format of basic information types. All attribute<br />
syntaxes defined in X.520 are supported:<br />
■ audio<br />
■ generalizedTime ■ octetString<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
binary<br />
boolean<br />
caseExactString<br />
caseExactStringIA5<br />
caseIgnoreIA5String<br />
caseIgnoreList<br />
caseIgnoreString<br />
distinguishedName<br />
facsimileNumber<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
fax<br />
guide<br />
integer<br />
jpeg<br />
mhsORAddress<br />
mhsORName<br />
numericString<br />
objectIdentifier<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
postalAddress<br />
preferredDelivery<br />
presentationAddress<br />
printableString<br />
telephoneNumber<br />
teletexTerminalId<br />
telexNumber<br />
UTCTime<br />
As more applications become directory-enabled, you can define new attribute<br />
syntaxes.<br />
To support these new syntaxes, particularly with their search matching rules,<br />
you may need special syntax coding and decoding functions. Generally this<br />
requires a software update to the DSA and DUA processes. However, to more<br />
readily support new attribute syntaxes on demand in operational systems, the<br />
DXserver has a feature for using unknown syntaxes.<br />
The undefined attribute syntax lets the DXserver DSA accept any unknown<br />
attribute syntaxes and store them in the directory. Intelligent matching rules are<br />
applied so you can search for them.<br />
Tip: See the configuration files (.dxc) in the schema directory for the latest<br />
supported syntaxes.<br />
To ensure DIT data integrity over configuration changes, the DSA stores the<br />
names of its current attributes and attribute syntaxes securely within the<br />
directory. The list names the ones that have been used to create directory entries.<br />
This list is not the same as that of all possible attribute names and syntaxes.<br />
When you attempt to change the syntax of an attribute after an instance of that<br />
attribute exists, the following message occurs:<br />
** ALARM **: Database attribute attribute has different syntax than schema<br />
4–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Attributes<br />
Attribute Checking<br />
When you load attributes (by using set attribute), they inherit certain rules from<br />
their syntax (for example, caseIgnoreString). When attempting to add attributes<br />
with values that do not comply with these rules, they are considered invalid.<br />
When the DSA encounters an invalid attribute (for example, on updates), it<br />
returns an error containing the attribute and the associated problem.<br />
Tip: In the search service, the system ignores invalid attributes after the base<br />
object is found.<br />
The DSA always returns attributes exactly as you stored them. For example, a<br />
commonName stored as JohN citiZen matches John Citizen and JOHN CITIZEN<br />
but the value JohN citiZen is always returned. Similarly, when you received the<br />
original string as an IA5 string, you store it as an IA5 string even though it<br />
contains only printable characters.<br />
The DSA permits attributes of any size, so you do not have to define any<br />
attribute bound limits.<br />
Syntax Aliases for Unsupported Attribute Syntax<br />
Syntax aliasing is useful if you add a new schema object definition that uses an<br />
attribute syntax that is not supported by <strong>eTrust</strong> <strong>Directory</strong>. The command for<br />
setting up a syntax alias is:<br />
[ schema ] set syntax alias = { name = alias-for = };<br />
For example,<br />
set syntax-alias (1.3.6.1.4.1.1466.115.121.1.18) = {<br />
name = dlSubmitPermissions<br />
alias-for = caseIgnoreString<br />
};<br />
Schema Definition 4–7
Attributes<br />
Attribute Sets<br />
Attribute sets let you easily group attribute definitions under a label so you can<br />
use them later in object class and other definitions.<br />
Define attribute sets in the configuration file using the set attr-set command. The<br />
attribute set is given an object identifier and a definition. The definition consists<br />
of a name and a list of attributes or attribute sets that are contained in the<br />
attribute set being defined.<br />
Example: Attribute Set<br />
Definition<br />
set attr-set x500aset:3 = {<br />
name = organizationalAttributeSet<br />
description,<br />
localeAttributeSet,<br />
postalAttributeSet,<br />
telecommunicationAttributeSet,<br />
businessCategory,<br />
seeAlso,<br />
search<strong>Guide</strong>,<br />
userPassword<br />
};<br />
Attribute sets are a convenient way of grouping large numbers of attributes<br />
together for use in object class definitions. Attribute sets can contain other<br />
previously defined attribute sets.<br />
Attribute Names<br />
A schema defines the basic information types and rules in a directory, so a<br />
schema is a central part of most directory services.<br />
When defining a schema, you must supply a name. You can also supply a<br />
number of LDAP names in the definition. Use either the schema name or one of<br />
the LDAP names as a keyword in other management console commands.<br />
For example, when you define an attribute using the following command, you<br />
can use organizationName or the shorter LDAP name, o, in other commands that<br />
need to reference the attribute:<br />
set attribute (2.5.4.10) = {<br />
name = organizationName<br />
ldap-names = o<br />
syntax = caseIgnoreString<br />
};<br />
LDAP names are most convenient when defining Distinguished Names (DN).<br />
The following DN:<br />
<br />
is equivalent to:<br />
<br />
<br />
<br />
<br />
4–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Attributes<br />
Unique Attributes<br />
Some applications that use <strong>eTrust</strong> <strong>Directory</strong> as a repository may require that the<br />
value of some attributes are unique across the repository. Information such as<br />
user name, user ID, or key may need to be unique for correct operation of a<br />
service. For example, an e-mail service will not operate effectively if a user<br />
chooses an ID that is already in existence.<br />
The benefits of this change will be to push uniqueness checking from the<br />
application to the directory. This removes the potential for attributes existing<br />
with duplicate values.<br />
Distribution and Replication<br />
Unique attributes cannot be used in a distributed environment, because there is<br />
no way of ensuring that attribute values across multiple DSAs are not being<br />
updated concurrently.<br />
This means that the attribute value check will only apply to the local DSA. Make<br />
sure that the DSA design does not assume that the attribute value check will be<br />
performed across multiple DSAs.<br />
In a replicated environment, unique attributes can be used in a single master<br />
scenario only. This is also because of the issue of concurrent updates.<br />
Unique Attribute Flag<br />
Set the unique attributes using the DSA set command:<br />
set unique-attrs = attr1, attr2, …;<br />
To see a list of all of the unique attributes in a DSA, use the DSA console to issue<br />
a get oper command.<br />
Implementing Unique Attributes<br />
Before you implement unique attributes:<br />
■<br />
■<br />
Choose the attributes carefully.<br />
Make sure you understand how client applications handle problems when<br />
trying to add or modify attribute values that already exist.<br />
During operation, take care to not inadvertently switch off this feature if it is still<br />
required.<br />
Schema Definition 4–9
Attributes<br />
How Unique Attributes Work<br />
When a client application tries to update an attribute that is set to be unique,<br />
<strong>eTrust</strong> <strong>Directory</strong> checks that the attribute value is not already in existence. If the<br />
value does already exist, an error message is sent back to the client application. If<br />
the value does not yet exist, the client request is confirmed.<br />
Limitation: Access Controls Bypassed<br />
If these attributes have access controls imposed, the triggered search will bypass<br />
these to ensure uniqueness. This means that a user may be able to write a client<br />
application to determine these values. If the unique attributes contain sensitive<br />
information, then this may be an issue.<br />
Limitation: Uniqueness Cannot Be Restricted to a Sub-Tree<br />
If attribute value uniqueness is required, but only need to be unique for a<br />
particular sub-tree, then separate DSAs will be required.<br />
Limitation: Uniqueness Not Enforced In Pre-Existing Data<br />
We recommend that this feature be enabled on empty directories or new<br />
attributes. This will ensure uniqueness.<br />
There is no DSA mechanism for finding duplicates. If this feature is being<br />
enabled on a running system, the administrator should perform checks for<br />
duplicate attribute values.<br />
Uniqueness will not be enforced on back-end loads. This has a similar impact as<br />
turning on this feature with an existing set of data.<br />
The following example shell script shows how to find duplicates. This script is<br />
restricted to values to length 106.<br />
#!/bin/sh<br />
if [ $# -ne 2 ]; then<br />
echo "Usage: sql.sh database attribute"<br />
exit 1<br />
fi<br />
DATABASE=$1<br />
ATTRIBUTE=$2<br />
OUTPUT=`sql $DATABASE
Attributes<br />
# Process output to get Aid<br />
AID=`echo "$OUTPUT" | grep -v aid | awk -F'|' '{ print $2 }'`<br />
sql $DATABASE &1<br />
CREATE VIEW findDuplicates(aid, norm, count) AS<br />
SELECT aid, norm, count(norm)<br />
\q<br />
EOF<br />
FROM search<br />
WHERE aid = $AID<br />
GROUP BY aid, norm;\g<br />
sql $DATABASE
Attributes<br />
Changing the Schema Definition for Attributes in Use<br />
Important! Never change database tables manually unless <strong>CA</strong> Technical Serves direct<br />
you to do this.<br />
If an attribute, object class or name binding has never been used in the directory,<br />
then you can change or remove the schema definition by modifying the schema<br />
configuration file.<br />
If the attribute has been used before, but is no longer in use, then you should<br />
dump the database to LDIF and then reload it before you modify the schema.<br />
If an attribute has at any time been used within the directory, you can only<br />
change its schema definition using these instructions.<br />
Important! You cannot simply delete all the entries that have the attributes to be<br />
changed, change schema, and import back the data.<br />
Important! A single schema file may be used by many different DSAs, which may use<br />
many different databases. If you change a schema file, check that it will work correctly<br />
with all of the DSAs that use that file.<br />
Remember to regenerate the schema.txt file for the DAP tools after changing the<br />
DXserver schema configuration.<br />
Changing LDAP Attribute Names<br />
If an attribute is in use, but you wish to change its name for clients connecting to<br />
the directory via LDAP, then simply alter the "ldap-names" part of the schema<br />
definition.<br />
Changing Schema Definitions for Attributes in Use<br />
If an attribute has at any time been used within the directory, you cannot simply<br />
delete all the entries that have the attributes you want to change, change the<br />
schema, and import back the data. This will not work.<br />
Instead, you must reload the database with DXloaddb to remove the old schema<br />
definitions from the database.<br />
To change the schema definition for attributes in use, do the following to every<br />
databases and DXservers that uses the schema definition to be changed:<br />
1. Stop all related DSAs.<br />
2. Back up the system (data and configuration).<br />
4–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Attributes<br />
3. Dump the database to to an LDIF file:<br />
dxdumpdb olddbname<br />
4. Sort the LDIF file. To do this, use the following command:<br />
ldifsort old.ldif old_sorted.ldif<br />
5. Change the schema definitions .<br />
6. Load the database from the sorted LDIF file with DXloaddb<br />
7. Start all the DXservers<br />
8. Verify the changes<br />
This can be done without taking the <strong>eTrust</strong> <strong>Directory</strong> service offline by using the<br />
database hot-swap feature:<br />
1. Turn off DXcache.<br />
2. Mark the DSA as read-only. To do this, add the following DSA flag to the<br />
configuration file:<br />
dsa-flags = read-only<br />
3. Dump the database to to an LDIF file:<br />
dxdumpdb olddbname<br />
4. Sort the LDIF file to ensure that it will load successfully. To do this, use the<br />
following command:<br />
ldifsort old.ldif old_sorted.ldif<br />
5. Change the attribute syntax in the schema configuration<br />
dxnewdb newdbname<br />
6. Change the database name in the DSA configuration<br />
dxloaddb newdbname<br />
7. Initialize the DSA.<br />
dxserver init dsa-name<br />
If you do not change the DSA configuration before running DXloaddb, then<br />
DXloaddb will use the schema.txt file which does not have the changed attribute<br />
definitions.<br />
Schema Definition 4–13
Object Classes<br />
Object Classes<br />
Object classes specify which attributes (and attribute sets) you can have in an<br />
entry.<br />
You define an object class by specifying its object identifier, a name, an alternate<br />
name, a subclass, an object class kind, a list of must-contain and a list of maycontain<br />
attributes or attribute sets, and a description.<br />
Example: Object Class<br />
Definition<br />
set object-class x500oc:5 = {<br />
name = organizationalUnit<br />
subclass-of top<br />
kind = structural<br />
must-contain<br />
organizationalUnitName<br />
may-contain<br />
organizationalAttributeSet<br />
description = "X.500 Organizational Unit Object Class"<br />
};<br />
The organizationalAttributeSet referred to in this example was defined in<br />
Schema Example 3—Attribute Definition.<br />
Object Class Kind<br />
Within the X.500/LDAP standards, there are three kinds of object classes:<br />
■<br />
■<br />
■<br />
Abstract classes (for example, the object class top)<br />
Structural classes (for example, the object class inetOrgPerson)<br />
Auxiliary classes<br />
The kind keyword defines the type of object class. The kind keyword is optional,<br />
but if it is missing, DXserver derives the object class kind using the following<br />
rule: when the object class inherits top, it is assumed to be structural; otherwise, it<br />
is auxiliary.<br />
Abstract Classes<br />
The abstract object class determines the structure of an LDAP directory. The<br />
object class top, for example, is the root object class from which all structural<br />
object classes are derived. It contains one mandatory attribute, objectClass, and<br />
because all entries inherit its attributes, it ensures that an object class defines<br />
these entries. An abstract object class cannot stand alone in an entry. The entry<br />
must also contain a structural object class.<br />
4–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Object Classes<br />
Structural Classes<br />
Most of the object classes in a directory are structural, because they define what<br />
an entry is. They also impose rules on the entries that are stored beneath them.<br />
For example, the object class organization (o) may require that all objects stored<br />
beneath it belong to the object class organizationalUnit (ou). Other examples of<br />
structural object classes are groupOfNames, inetOrgPerson, and person.<br />
Auxiliary Classes<br />
The LDAP rules require each entry to belong to only one structural object class,<br />
but an entry can also belong to one or more auxiliary object classes. An auxiliary<br />
object class adds attributes to entries already defined by a structural object class.<br />
An auxiliary object class cannot stand on its own in an entry. The entry must<br />
contain a structural object class. Unlike structural object classes, auxiliary object<br />
classes place no restrictions on storing an entry.<br />
Object Class Checking<br />
When adding an entry, the DSA automatically includes all the attributes from<br />
any superclasses of the new entry's object class. For example, when an entry is<br />
created with the object class inetOrgPerson, it includes attributes from the<br />
inherited object classes (organizationalPerson, Person, top).<br />
Important! DXserver supports multiple inheritance of object class. This means that an<br />
object class can inherit attributes from more than one parent object class.<br />
Schema Definition 4–15
Object Classes<br />
Object Class Storage<br />
By definition, the object class attribute used by every object or entry in the<br />
directory can have multiple values of object identifiers. This enables object<br />
classes to indicate their refinement (for example, through the use of object class<br />
refinement or the addition of auxiliary object classes).<br />
Configuring how the OC Attribute is Stored<br />
You can configure how the object class attribute (single value or multiple values)<br />
is stored within the directory.<br />
By default, the DSA adds the object classes to the entry exactly as specified in the<br />
LDAP or DAP add request (for example, the object class attribute may have<br />
multiple OIDs). However, directory performance improves slightly when the<br />
object class attribute only contains a single value (the OID of the refined OC).<br />
However, this should not be the main influence over the object class design of<br />
attributes.<br />
Where entries contain a single inherited object class and explicitly list all its<br />
superiors (their OC OIDs), the superiors can be removed, leaving the lowestlevel<br />
object class in the hierarchy as a single OID value. Similarly, when entries<br />
are returned, the object class attribute can be automatically modified by the DSA<br />
to contain all the superior object classes.<br />
This OC refinement information can be returned (as OC OIDs) because the<br />
directory maintains the object class structure rules that have been configured (in<br />
its internal schema management control system).<br />
For example, suppose that the directory contained entries corresponding to<br />
people. Each entry can explicitly contain the following object classes within the<br />
database:<br />
■<br />
■<br />
■<br />
■<br />
inetOrgPerson<br />
organizationalPerson<br />
Person<br />
top<br />
4–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Object Classes<br />
Pruning and Replacing Object Classes<br />
It is more space-efficient to configure the DSA to prune all object classes, except<br />
the lowest (inetOrgPerson), when creating the entry and to replace all the<br />
superior object classes (organizationalPerson, Person, and top) when returning<br />
the entry as a result of a client search.<br />
The following configuration settings control the pruning and replacing of object<br />
classes:<br />
Setting<br />
Parameter Description<br />
set prune-oc-parents Boolean Removes redundant superior object classes<br />
when new entries are created.<br />
set return-oc-parents Boolean Replaces the superior object classes to<br />
entries retrieved when searching.<br />
set add-oc-parents Boolean Causes parent objectclasses to be added<br />
when entries are added. e.g. Consider<br />
adding a democorp entry with the classes:<br />
inetOrgPerson<br />
This control adds the parent (top-personorganizationalPerson)<br />
classes. This makes<br />
the directory entry hold the following<br />
classes:<br />
■<br />
■<br />
■<br />
■<br />
top<br />
person<br />
organizationalPerson<br />
inetOrgPerson<br />
Important! When these settings are configured, searching entries using an object class<br />
filter (for example, oc=Person) does not return any entries, because the specified object<br />
class of Person is not present in the data; it is only added to search results that contain<br />
the inetOrgPerson object class.<br />
Schema Definition 4–17
Name Bindings<br />
Name Bindings<br />
Name bindings define where entries appear in the DIT. DXserver requires a<br />
separate name binding for each allowable parent-object and child-object<br />
relationship in the directory.<br />
Example: Name<br />
Binding Definitions<br />
set name-binding x500nbind:2 = {<br />
name = org-top<br />
organization allowable-parent top<br />
named-by organizationName<br />
};<br />
set name-binding x500nbind:3 = {<br />
name = org-country<br />
organization allowable-parent country<br />
named-by organizationName<br />
};<br />
In this example, a new definition (arbitrarily named org-country) states that you<br />
can place an organization object under a country object and that you must name<br />
it by the organizationName attribute. The definition org-top states that you can<br />
also place an organization object under a top object (that is, the root of the DIT)<br />
named by the organizationName attribute.<br />
Multiple attributes can name an object, in which case you separate the attributes<br />
by commas. Additional naming attributes are optional when the keyword<br />
optional precedes them.<br />
Example: Advanced<br />
Name Binding<br />
Definition<br />
set name-binding x500nbind:22 = {<br />
name = orgUnit-orgPerson<br />
organization allowable-parent organizationalUnit<br />
named-by commonName optional surname<br />
};<br />
Name Binding Checks<br />
The DSA checks name binding rules whenever you add or rename an entry. To<br />
enforce both the parent-child relationships in the directory, and the naming<br />
attributes used by a particular entry, name bindings are necessary. The system<br />
reports any name binding errors as:<br />
Update Error: Naming Violation.<br />
When you enable warnings (set trace = warn,…;), the system sends a message<br />
describing the reason for the name binding failure to the console.<br />
There is one exception regarding name binding checks. When an object is added<br />
under the naming context (or prefix) of a DXserver, then no name bindings need<br />
exist. This facilitates the changing of the directory’s naming context without the<br />
need to change associated name binding definitions. In this situation, DXserver<br />
will give the following message:<br />
Relaxed name bindings under root.<br />
4–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Name Bindings<br />
Name Bindings and Structural Object Classes<br />
When an entry has more than one object class, the DSA looks through its list of<br />
name bindings to ensure that one exists between one of the structural object<br />
classes of the parent and one of the structural object classes of the entry<br />
containing the appropriate naming attribute. It then uses this structural object<br />
class to find a name binding and ignores all other auxiliary object classes.<br />
The DSA permits modification of the structural object class only when a name<br />
binding satisfies the parent-object relationship and the object is a leaf entry.<br />
Name Bindings and Aliases<br />
Name bindings for aliases are automatic, and you do not configure them<br />
manually. The DSA lets you create an alias entry in place of any valid object<br />
provided that you name it using the same attribute that an equivalent name<br />
binding rule permits.<br />
For example, when there is an org-orgUnit name binding, the DSA lets you place<br />
an alias under an organization object when you name it using an<br />
organizationalUnitName attribute.<br />
Thus, you do not need to define an object-alias name binding for every part of<br />
the DIT where you can place an alias.<br />
Considerations for Schemas that Do Not Support Name Binding<br />
When a schema is imported from a directory that does not support name<br />
bindings or structure rules, it is possible for <strong>eTrust</strong> <strong>Directory</strong> to operate without<br />
name bindings. To enable this functionality, add the following command to the<br />
settings file:<br />
set ignore-name-bindings = true;<br />
You can retrieve the state of this flag by using the get oper; command.<br />
Schema Definition 4–19
Defining Local Schema<br />
Defining Local Schema<br />
The X.500 standards enable the definition of local attributes, attribute sets, object<br />
classes, and name bindings in the schema in much the same way as previously<br />
described in Name Bindings and Aliases in this chapter.<br />
Before defining local schema, you should check the existing published schema to<br />
determine whether the required attribute, object class, and name binding<br />
definitions already exist.<br />
When you need to define additional schema, create an object identifier arc<br />
(1.3.6.1.4.1.3327.1 in the following example) and add the new schema under this<br />
arc. Use the set commands described previously to define the schema, and then<br />
include the newly created configuration file (.dxc) in the schema group<br />
configuration file (.dxg), used by the DSA.<br />
The following example describes a single object class that can contain three<br />
attributes. Computer Associates created the object class so that you could add the<br />
additional attributes to an organizationalPerson object.<br />
All the names in the schema definition below have the prefix ca. The use of an<br />
object identifier prefix in the name helps simplify attribute references by<br />
replacing the common portion of a complicated object identifier with a simple<br />
character string and helps identify related attributes.<br />
Example: Local<br />
Attribute, Attribute<br />
Set, Object Class, and<br />
Name Binding<br />
Definitions<br />
set oid-prefix caAttr = (1.3.6.1.4.1.3327.1.4);<br />
set oid-prefix caOclass = (1.3.6.1.4.1.3327.1.6);<br />
set oid-prefix caAset = (1.3.6.1.4.1.3327.1.7);<br />
set oid-prefix caNbind = (1.3.6.1.4.1.3327.1.14);<br />
set attribute caAttr:0 = {<br />
name = caNearestPrinter<br />
syntax = caseIgnoreString<br />
description = "Local Printer Attribute" };<br />
set attribute caAttr:1 = {<br />
name = caMobilePhone<br />
syntax = caseIgnoreString<br />
description = "Mobile Phone Attribute" };<br />
set attribute caAttr:3 = {<br />
name = caAlternateContact<br />
syntax = caseIgnoreString<br />
description = "Local Contact Attribute" };<br />
set attr-set caAset:0 = {<br />
name = caAttributeSet<br />
caNearestPrinter,<br />
caMobilePhone,<br />
caAlternateContact };<br />
set object-class caOclass:0 = {<br />
name = caOrgPerson<br />
subclass-of organizationalPerson<br />
kind = structural<br />
may-contain caAttributeSet<br />
description = "<strong>CA</strong> Organizational Person Object Class" };<br />
set name-binding caNbind:0 = {<br />
name = caOrgPerson-org<br />
caOrgPerson allowable-parent organization<br />
named-by commonName };<br />
4–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
5<br />
Distribution and DSP<br />
In a distributed environment, a number of different <strong>Directory</strong> System Agents<br />
(DSAs) manage a different part of the <strong>Directory</strong> Information Tree (DIT).<br />
There needs to be a DSA-to-DSA protocol, such as the X.500 <strong>Directory</strong> Systems<br />
Protocol (DSP), that lets the DSAs cooperate to resolve queries on any area of the<br />
DIT.<br />
DXserver fully supports the X.500 directory systems protocol, including:<br />
■<br />
■<br />
■<br />
Chaining—Performing queries through other DSAs<br />
Multi-chaining—Performing distributed searches across many DSAs<br />
Referrals—Informing clients where to find information<br />
DXserver greatly simplifies the configuration of arbitrarily distributed DSAs by<br />
providing the following unique features:<br />
■<br />
■<br />
Prefix-based knowledge—Each DSA is identified by a name and its base<br />
prefix. All superior, subordinate, and peer references are automatically<br />
inferred.<br />
Shared configuration—You define all the knowledge files once, which are<br />
then used by any DSA.<br />
The benefits of these features are:<br />
■<br />
■<br />
■<br />
Shortest-path routing—Each DSA has knowledge of other DSAs so requests<br />
are chained directly to the DSA that processes the request.<br />
Integrated security—See the chapter “Security” for more information about<br />
DSA to DSA security.<br />
High speed switching—Knowledge information is cached in each DXserver.<br />
Distribution and DSP 5–1
Managing DSP<br />
Managing DSP<br />
You can manage DSP configuration using the DSP module commands at the<br />
DXconsole. The DSP module commands let an administrator set and clear DSP<br />
configuration management variables.<br />
You can manage DSP configuration using the commands:<br />
■<br />
■<br />
■<br />
■<br />
set parameter = value;<br />
get parameter;<br />
clear dsas;<br />
unbind parameter;<br />
DSP Command Options<br />
A number of parameters of the DSP module commands let you change the DSP<br />
configuration. The following tables summarize these parameters, and the<br />
subsequent sections explain them in more detail.<br />
The following are the parameters of the dsp set command:<br />
Parameter<br />
always-chain-down<br />
dsa<br />
max-dsp-ops<br />
multi-chaining<br />
multi-write-disp-recovery<br />
multi-write-queue<br />
Value<br />
Value is TRUE or FALSE; when set to TRUE, the DSA overrides chainingprohibited<br />
controls when you need to chain the request to a subordinate<br />
DSA.<br />
The configuration details of a remote directory server.<br />
The maximum number of concurrent remote operations supported by the<br />
server.<br />
Value is TRUE or FALSE; when set to TRUE, the DSA can multi-chain<br />
searches to other DSAs.<br />
Value is TRUE or FALSE; when set to TRUE, the DSA disables offline<br />
multiwrite queuing. DSAs that cannot be contacted are dropped<br />
immediately from the multiwrite set, and DISP is used to resynchronize the<br />
DSAs when they come back online. Multiwrite DISP recovery cannot be used<br />
where more than one DSA is attached to the same database. For more<br />
information, see Multiwrite Replication the chapter “Replication.”<br />
The maximum number of multiwrite operations that are queued when a<br />
peer DSA cannot be reached. For more information, see the chapter<br />
“Replication.”<br />
5–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing DSP<br />
The following are the parameters of the dsp get command:<br />
Parameter<br />
dsp<br />
online-dsas<br />
dsas<br />
Value<br />
Shows the current DSP configuration values of the DSA.<br />
Provides information about current outgoing connections<br />
to other DSAs.<br />
Provides information about all known DSAs.<br />
The following are the additional commands of the DSP module:<br />
Command<br />
clear dsas<br />
unbind<br />
Meaning<br />
Removes all remote-DSA definitions from the DSA.<br />
Unbind one, or all, outgoing connections to other DSAs.<br />
Knowledge References<br />
The information in a set dsa definition is called a knowledge reference. A<br />
knowledge reference provides the address of another DSA and an entry point,<br />
represented by the DSA’s prefix, into the part of the directory tree that the DSA<br />
controls. A DXserver is identified by its name and prefix. References appear as<br />
entries to a DUA (see List Service in the appendix “DXconsole DUA” for more<br />
information).<br />
Access controls can hide the presence of a subordinate DSA, making that subtree<br />
invisible to a list service or any other service. (See Access-Controlled Routing in<br />
the chapter “Security” for more information).<br />
The DSA dynamically determines the type of reference (superior, subordinate, or<br />
cross-reference). When the reference is a cross-reference, the ancestors of the<br />
cross-reference are visible to the list service.<br />
Distribution and DSP 5–3
Managing DSP<br />
Remote Operations<br />
Each DSA has a context prefix that defines the base of the DIT controlled by that<br />
DSA.<br />
When the DSA receives an incoming operation, it services the request locally<br />
when it is in the DSA’s own DIT. When the operation is not local, it chains the<br />
operation to a remote DSA unless:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
One (user) service control—chainingProhibited or localScope—is set. You<br />
can override this service control. (See Proxy DSAs in this chapter for more<br />
information.)<br />
Access controls hide the existence of the remote DSA. (See Access-Controlled<br />
Routing in the chapter “Security” for more information.)<br />
The remote DSA is unavailable.<br />
You cannot establish a link of the appropriate authentication level to the<br />
remote DSA. (See Other Security Features in the chapter “Security” for more<br />
information.)<br />
There is no DSA knowledge configured for the area of the operation.<br />
Depending on the circumstance, the remote operation returns a:<br />
■<br />
■<br />
■<br />
■<br />
Result<br />
Referral<br />
Service error<br />
Security error<br />
See the X.500 standards for a complete specification of how distributed DSAs<br />
cooperate to resolve a query.<br />
Limiting Remote Operations<br />
In a multi-DSA environment a DSA may have to forward requests to other DSAs<br />
to process. You can limit the maximum number of concurrent remote operations<br />
that a DSA manages by setting max-dsp-ops in the configuration file (.dxc) in the<br />
limits directory.<br />
Example: Limiting the<br />
Number of Remote<br />
Operations to 100<br />
set max-dsp-ops = 100;<br />
5–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing DSP<br />
Remote Connections<br />
The DSA dynamically binds to and unbinds from remote DSAs. A DSA<br />
maintains at most one connection per security level (set by the auth-levels list in<br />
the DSA definition) to a remote DSA. When a DSA has an established DSP<br />
connection of the correct security level to a remote DSA, it uses this connection.<br />
A second connection of the same security level is not set up.<br />
The DSA definition supports trust flags that enable a DSA to upgrade or<br />
downgrade a link between DSAs. For example, when a link between two DSAs<br />
supports only anonymous connections, a credentialed user can access the link<br />
when the receiving DSA supports the allow-downgrading trust flag. Conversely,<br />
when the only allowed DSP link is a clear-password link, an anonymous user can<br />
access the link only when there is support for the allow-upgrading trust flag (see<br />
DSA Knowledge Flags in the chapter “General Administration” for more<br />
information).<br />
A DSP connection to a remote DSA unbinds after the dsp-idle-time is exceeded.<br />
Remove Remote DSA<br />
Knowledge<br />
You can remove all knowledge of remote DSAs using the command:<br />
clear dsas;<br />
Unbinding Remote Connections<br />
Display Outgoing<br />
Connections<br />
Unbind All or Some<br />
Connections<br />
Unbind Outgoing<br />
Connections That<br />
Exceed Global<br />
Values<br />
When a DSA communicates with a remote DSA using DSP, it sets up a<br />
connection (bind) to the remote DSA. You cannot abort this connection using<br />
the abort user command described previously because it is an outgoing<br />
connection. You can obtain information about outgoing connections with the<br />
command:<br />
get online-dsas;<br />
You can unbind all or some connections using this information and one of the<br />
following commands (assuming 3 is a valid connection identifier):<br />
unbind all;<br />
unbind dsa 3;<br />
A DSA can automatically unbind outgoing connections when they exceed<br />
global values set in the remote-DSA definition, for example:<br />
set dsa “Eagle” = {<br />
...<br />
dsp-idle-time = 60<br />
...<br />
};<br />
Distribution and DSP 5–5
Managing DSP<br />
Incoming DSP Credentials<br />
When a local DSA receives a bind with credentials from a remote DSA, it checks<br />
the credentials against a matching (remote) DSA configuration. When you do not<br />
configure a relevant remote DSA, the system rejects the incoming bind.<br />
See DSA-to-DSA Encryption (DSP and DISP) in the chapter “Security” for more<br />
information.<br />
Outgoing DSP Credentials<br />
If a remote DSA requires authentication, the local DSA must send credentials<br />
when binding to the remote DSA. To be able to do this, the local DSA must have<br />
credentials (user name and password) defined in its own set dsa definition (see<br />
Configuring a DSA in this chapter for more information).<br />
Distributed Searches (Multi-Chaining)<br />
Searches can span multiple DSAs. A subtree search searches all entries below<br />
and including the base-object of the search. Some entries can reside on a different<br />
DSA from the base-object. When you enable multi-chaining, the DSA searches for<br />
immediate subordinate DSAs after you find the base-object and then forwards<br />
the search to these DSAs. Results from all subordinate DSAs and the local DSA<br />
(the DSA containing the base-object) are collated before being returned.<br />
Limiting Multi-Chaining<br />
In a multi-DSA environment the DIT is controlled by multiple DSAs. A search<br />
area can span part of the DIT that is controlled by more than one DSA. In this<br />
case the DSA containing the base object of the search will multi-chain the request<br />
to the other relevant DSAs. You can disable multi-chaining in two ways:<br />
■<br />
■<br />
The originator of the request can disable multi-chaining by specifying localscope<br />
in the common arguments of the search.<br />
The DSA administrator can disable multi-chaining by using the command:<br />
set multi-chaining = false;<br />
The DSA prevents multi-chaining to any DSA having a presence hidden by<br />
access controls. (See Access-Controlled Routing in the chapter “Security” for<br />
more information.)<br />
5–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing DSP<br />
Viewing DSP Configuration<br />
You can monitor DSP connections using the dsp module get command at the<br />
DXconsole. You can view the DSP configuration values and details of current<br />
outgoing connections.<br />
View DSP<br />
Configuration<br />
To view the DSP configuration, use the command:<br />
get dsp;<br />
This is a sample of the output from this command:<br />
max-dsp-ops = 100<br />
local-prefix<br />
= <br />
local-dsa<br />
= “DemoCorp”<br />
multi-chaining = FALSE<br />
always-chain-down = TRUE<br />
multi-write-queue = 200 (current 0)<br />
View Online<br />
Connections<br />
To view the DSP connections that are currently active, use the command:<br />
get online-dsas;<br />
This is a sample of the output from this command:<br />
dsa> get online-dsas;<br />
Remote: DSA 2 (DEMOCORP)<br />
Association: state 3, idle for 2 seconds, 0 operations waiting<br />
0 operations abandoned<br />
prefix:<br />
<br />
<br />
dsaName:<br />
<br />
<br />
<br />
dsaPassword: ?<br />
hostname: EAGLE<br />
OSI PSAP:<br />
address: 208.12.151.204:19389<br />
address: 127.0.0.1:19389<br />
dispPsap: DISP<br />
cmipPsap: CMIP<br />
snmpPort: 19389<br />
consolePort: 19390<br />
ssldPort: 1112<br />
DEMOCORP:next_distinct: (none) (precedence 3)<br />
:next_similar: (none)<br />
:children: (none)<br />
refType: cross<br />
auth-levels: anonymous clear-password ssl-auth<br />
dsa-flags:<br />
trust-flags: allow-check-password<br />
link-flags:<br />
maxIdleTime: 60<br />
credit: 5<br />
precedence: 3<br />
Display Each DSA for<br />
Which the Current<br />
DSA Has Knowledge<br />
Use the following command to display information about each DSA for which<br />
the current DSA has knowledge, including itself:<br />
get dsas;<br />
Distribution and DSP 5–7
Configuring a DSA<br />
Configuring a DSA<br />
You can configure all DSAs, including the local one, using the set dsa command<br />
(see Defining DSAs in the chapter General Administration for more information).<br />
You can dynamically issue the set dsa command from the DXconsole, but it is<br />
recommended that you include it in a DSA definition file (.dxc) in the knowledge<br />
directory. You then source this file from another configuration file, either a .dxg<br />
file in the knowledge directory or a .dxi file in the servers directory.<br />
Configuring a Subordinate DSA<br />
The following example defines a DSA called DemoResearch, which is<br />
subordinate to the pre-configured DemoCorp DSA in the standard version.<br />
Example<br />
set dsa “DemoResearch” = {<br />
prefix = <br />
dsa-name = <br />
dsa-password = “demo”<br />
address = tcp Eagle port 389<br />
disp-psap = DISP<br />
cmip-psap = CMIP<br />
snmp-port = 1950<br />
console-port = 1952<br />
auth-levels = anonymous, clear-password<br />
dsp-idle-time = 10000<br />
credits = 5<br />
};<br />
The DSA definition contains a prefix that defines the area of the DIT that is<br />
covered by this DSA:<br />
prefix = <br />
The DSA administers the prefix and the entries below, except for any areas of the<br />
DIT below the prefix that are covered by another DSA.<br />
Every object within the directory has a unique distinguished name (DN), which<br />
directs it to an entry in the directory. The complete directory tree is called the<br />
<strong>Directory</strong> Information Tree (DIT) and can comprise a number of independent<br />
X.500 DSAs or LDAP servers that, between them, hold all the various branches of<br />
the directory tree.<br />
The naming context (which is also a DN) of an X.500 or LDAP server defines the<br />
branch that server owns.<br />
The X.500 and LDAP communities differ in the way they write their DNs. Within<br />
X.500, DNs are written from the top of the tree down (for example, c=US,<br />
o=Computer Associates, and so forth). Within the LDAP community, DNs are<br />
written from the leaf entry up (for example, cn=John Smith, ou=Sales, and so forth).<br />
5–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring a DSA<br />
Proxy DSAs<br />
There are a number of situations where a group of DSAs must appear to the<br />
outside world as a single DSA.<br />
External<br />
DUA or DSA<br />
Proxy DSA<br />
Internal<br />
DSA 1<br />
Internal<br />
DSA 2<br />
Internal<br />
DSA 3<br />
Internal<br />
DSA 4<br />
For example, an organization can make a single DSA visible through an Internet<br />
firewall, but internally let that DSA send DSP requests to other internal DSAs<br />
that control subtrees subordinate to the visible DSA. This configuration fails<br />
when the external DUA sets the local-scope or chaining-prohibited service<br />
controls. In this case, the visible DSA returns a referral, but the DUA cannot<br />
connect to the referred DSA because there is no access to this DSA through the<br />
firewall.<br />
The solution to this problem is overriding the local-scope and chainingprohibited<br />
service controls using the command:<br />
set always-chain-down = true;<br />
When you enable this feature in the visible DSA, requests are chained to the<br />
relevant DSA regardless of the request’s service controls. Also, subtree searches<br />
are always multi-chained to subordinate DSAs.<br />
A proxy DSA is also useful if an X.500 guard wants to hide the address of DSAs<br />
inside the enclave that it is guarding.<br />
Distribution and DSP 5–9
Configuring Another DXserver<br />
Configuring Another DXserver<br />
To configure the knowledge of a remote DSA, use the set dsa command (see<br />
Defining DSAs in the chapter “General Administration” for more information).<br />
Local DSA<br />
Remote DSA<br />
A DXserver is identified by its name and prefix. The relationship between two<br />
DXservers is represented by the corresponding relationship between the prefixes.<br />
See A Domain of DXservers in this chapter for more information.<br />
Configuring Alternative Network Addresses<br />
You can configure knowledge of more than one network address for a DSA. This<br />
is used where you want to distribute the directory over more than one physical<br />
or logical network. This facilitates increased network availability by using<br />
additional networks between DSAs.<br />
To configure knowledge of more than one network address for a DSA, use the set<br />
dsa command:<br />
set dsa “DualNetwork” = {<br />
…<br />
address = tcp “dnet1” port 389, tcp “dnet2” port 1900<br />
…<br />
};<br />
NET 1<br />
DSA Dual<br />
Network<br />
NET 2<br />
Handling Firewall Address Translation<br />
If your firewall translates remote addresses, your DSA may not recognize the<br />
remote DSA because of the changed address. You must configure alternative<br />
network addresses in the knowledge file of the remote DSA by specifying the<br />
address of the remote DSA followed by the address of the firewall.<br />
5–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring Another DXserver<br />
Configuring a Third-party DSA<br />
To configure the knowledge of third-party DSAs, use the set dsa command.<br />
Example: Setting a<br />
Remote DSA<br />
Reference<br />
set dsa “DemoUni” = {<br />
prefix<br />
= <br />
dsa-name = <br />
address = tcp “demouni.edu” port 389<br />
};<br />
auth-levels = anonymous<br />
dsp-idle-time = 10000<br />
Note: This DSA does not support DISP, CMIP, or SNMP and has only<br />
anonymous access.<br />
DXlink<br />
A third-party DSA can be an LDAP server. DXserver has a feature, DXlink,<br />
which treats a remote LDAP server as another DSA. To activate DXlink, set the<br />
dsp-ldap link flag in the set dsa command in the knowledge directory of the<br />
LDAP server:<br />
link-flags = dsp-ldap<br />
Note: When you are using LDAP Version 3, use the dsp-ldap link flag. When you<br />
are using LDAP version 2, use dsp-ldapv2.<br />
For more information about DXlink, see Integrating Other LDAP Servers in the<br />
chapter “LDAP and DXlink.”<br />
Distribution and DSP 5–11
Configuring Another DXserver<br />
Configuring Multiple Local DSAs<br />
To support large databases, parallel processing, or independent subtrees (for<br />
example, for performance or security reasons), you can run a number of<br />
DXserver DSAs on the same machine. You configure each DSA with its own<br />
definition and connect the DSAs together using DSP.<br />
Example: Setting Two<br />
DSA References on<br />
the Same Machine<br />
# Knowledge configuration file: localTwo.dxc<br />
set dsa “LocalTwo” =<br />
{<br />
prefix<br />
...<br />
address = tcp "Eagle" port 1910<br />
...<br />
= <br />
};<br />
# Knowledge configuration file: localThree.dxc<br />
set dsa “LocalThree” =<br />
{<br />
};<br />
prefix<br />
...<br />
address = tcp "Eagle" port 1920<br />
...<br />
= <br />
In this example, you can see that two local subtree DSAs are accessible:<br />
AU/DemoCorp/Sales and AU/DemoCorp/Support. They each listen on<br />
separate ports—1910 and 1920—although they have the same TCP/IP address.<br />
If the underlying RDBMS supports load sharing across multiple CPUs, each<br />
DSA process inherits this capability.<br />
5–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring a Domain of DXservers<br />
Configuring a Domain of DXservers<br />
A typical directory installation will include a number of DSAs, which together<br />
control the DIT. These DSAs will usually control different portions of the DIT<br />
and they need to cooperate in order to process client requests. This section shows<br />
how a group of DSAs share DXserver knowledge.<br />
A Domain of DXservers<br />
The following diagram shows how to configure five DSAs to control a DIT. Each<br />
DSA has control over a portion of the DIT, represented by its prefix, and a<br />
relationship with the other DSAs in the domain. For instance DSA1 is the<br />
superior DSA of DSA2 and DSA3, while DSA4 and DSA5 are subordinates of<br />
DSA3.<br />
DSA 1<br />
DSA 2<br />
DSA 3<br />
DSA 4 DSA 5<br />
A request received by one DSA that requires an operation on an entry that is not<br />
contained in that DSA’s area of control, is chained (forwarded) to the relevant<br />
DSA. A request may be chained through a number of DSAs before finding the<br />
DSA capable of processing the request. When a domain of DSAs has shared<br />
knowledge, a DSA receiving a request is able to forward that request directly to<br />
any other DSA within the domain.<br />
A search request can require a subtree search spread over more than one DSA. In<br />
this case, the DSA containing the base object of the search performs the search<br />
locally and multi-chains the search to any DSAs that control part of the subtree to<br />
be searched. These DSAs will then return the search results back to the<br />
originating DSA, which will collate them and return the result back to the client.<br />
Distribution and DSP 5–13
Configuring a Domain of DXservers<br />
Sharing DXserver Configuration<br />
You should include each DSA definition in its own configuration file (.dxc) in the<br />
knowledge directory. You can group together a number of DSA definitions into a<br />
domain by creating a group file (.dxg) in the knowledge directory that sources<br />
each required configuration (.dxc) file. You can then include the group file in a<br />
server initialization file (.dxi) in the server’s directory.<br />
If you change a reference or add a new DSA to the network, you can generate a<br />
new configuration file and send a copy to each DSA that uses the reference.<br />
DSA A<br />
DsaA.dxi<br />
dom.dxg<br />
(Copy)<br />
.dxc<br />
(Copies)<br />
DsaA.dxc<br />
dom.dxg<br />
DsaB.dxc<br />
DSA B<br />
DsaB.dxi<br />
dom.dxg<br />
(Copy)<br />
.dxc<br />
(Copies)<br />
Each DXserver recognizes its own set dsa definition so that it can determine<br />
whether or not an operation is local.<br />
Configuring a First-level DSA<br />
When the local prefix contains only one Relative Distinguished Name (RDN) in<br />
its DN, the DSA is a first-level DSA. Usually there is no actual root-level DSA, so<br />
each first-level DSA must handle lists and searches from the root. This means<br />
that a first-level DSA multi-chains a search from root to other first-level DSAs.<br />
5–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring a Domain of DXservers<br />
Configuring a Router DSA<br />
It is possible to start a DSA without connecting to a database. In this<br />
configuration, the DSA (known as a router DSA) simply forwards requests to<br />
other DSAs. To do this, comment out or remove the line in the DSA initialization<br />
file that sets the database name, as follows:<br />
...<br />
# DATABASE<br />
# source “../database/dbname.dxc”;<br />
...<br />
A DSA without a database is used to pass on requests to one of a number of<br />
DSAs known to the router DSA. The router DSA determines which DSA can best<br />
process the client’s request. See Alternative DSAs in this chapter for more<br />
information.<br />
A router DSA consumes a level of the DIT. In the following example of a router<br />
DSA’s knowledge file, c=au is the level of the DIT consumed by the router DSA.<br />
set dsa ROUTER =<br />
{<br />
prefix<br />
= <br />
dsa-name<br />
= <br />
dsa-password = “secret”<br />
address = tcp “hostname” port 19289<br />
disp-psap<br />
= DISP<br />
cmip-psap<br />
= CMIP<br />
snmp-port = 19289<br />
console-port = 19290<br />
ssld-port = 1112<br />
auth-levels<br />
= anonymous, clear-password, ssl-auth<br />
dsp-idle-time = 60<br />
};<br />
Transparent Routing<br />
A router DSA can be used to link clients to a number of external LDAP servers,<br />
using DXlink. In this case, the LDAP clients and the LDAP server may have<br />
schema that are not known by the router DSA.<br />
This means that the router DSA may receive requests and responses that contain<br />
unknown schema. Normally, the router cannot process such queries. However, if<br />
transparent routing is enabled, the router can pass LDAP requests and responses<br />
without requiring the controlling schema.<br />
Transparent routing only works with LDAP clients.<br />
To enable transparent routing, use the following command:<br />
set transparent-routing = true;<br />
By default, transparent routing is set to FALSE.<br />
Distribution and DSP 5–15
Configuring a Domain of DXservers<br />
Configuring a Relay DSA<br />
You can configure a DSA as a relay DSA so that it forwards requests. A relay<br />
DSA does not occupy a level of the DIT. This is useful for router DSAs (such as<br />
load balancers) or proxy DSAs (such as firewalls), because you can effectively<br />
insert them without affecting the DIT. A relay DSA always forwards requests;<br />
therefore it cannot have a local database.<br />
A relay DSA only adds to the DSP trace information if the incoming request was<br />
from a DUA.<br />
To create a DSA as a relay DSA, add relay to its DSA flags:<br />
set dsa DemoCorp = {<br />
...<br />
dsa-flags = relay, ...<br />
...<br />
};<br />
Caching Entries from Subordinate DSAs<br />
Unlike DAP, LDAP does not have a LIST operation. So, when LDAP clients want<br />
to browse a directory, they invoke one-level searches that return object class<br />
only. These one-level searches become a problem when there are many<br />
subordinate DSAs because a one-level search must be broadcast to each of the<br />
DSAs (whereas a LIST simply returns the names of the DSAs). To stop the<br />
flooding effect that this creates, especially at first-level DSAs, the DXserver caches<br />
the replies to one-level-search queries and makes them available to subsequent<br />
similar requests. Only one-level searches returning object class are cached—these<br />
are the searches commonly used to browse the directory.<br />
5–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alternative DSAs<br />
Alternative DSAs<br />
If you define more than one DSA with the same prefix (naming context) and<br />
data, these DSAs can be used to improve the performance and availability of the<br />
directory service.<br />
This section describes three ways that groups of DSAs with the same prefix and<br />
the same data can be used:<br />
■<br />
■<br />
■<br />
Failover—To improve the availability of the service, when one DSA fails,<br />
another automatically takes over its request load.<br />
Load sharing—To improve performance, read requests are divided between<br />
two or more DSAs.<br />
Query streaming—To improve performance, requests of different types are<br />
routed to different DSAs.<br />
Distribution and DSP 5–17
Alternative DSAs<br />
DSA Failover<br />
The purpose of failover is to improve the availability of the directory service.<br />
In the following example, the router DSA usually sends requests to DSA 1. If<br />
DSA 1 fails, the router DSA automatically sends all requests to DSA 2. This<br />
change is invisible to the clients. In this system, DSA 2 is simply a backup: it is<br />
only used if DSA 1 fails.<br />
Router DSA<br />
DSA 1<br />
DSA 2<br />
Database<br />
Replication<br />
Database<br />
Computer A<br />
Computer B<br />
Failing Over to a Backup DSA<br />
In the following example, the San Diego and Tokyo offices each use local replica<br />
DSAs, to improve performance. During normal operation, each local router DSA<br />
sends requests to the local data DSA. If either of the local data DSAs fails, the<br />
routers automatically fail over to the remote data DSA.<br />
San Diego<br />
Router DSA<br />
Tokyo<br />
Router DSA<br />
DSA 1<br />
DSA 2<br />
Database<br />
Replication<br />
Database<br />
Computer A<br />
(San Diego)<br />
Computer B<br />
(Tokyo)<br />
Failing Over to a Remote DSA<br />
5–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alternative DSAs<br />
Set the DSA Precedence For Failover<br />
When more than one data DSA fails, the router DSA fails over to other DSAs in<br />
their order of occurrence in the configuration files.<br />
You can override this order with the following commands:<br />
set precedence = dsaname1 [, dsaname2, dsaname3… ] ;<br />
set write-precedence = dsaname1 [, dsaname2, dsaname3… ] ;<br />
The command set precedence defines the order of the DSAs that the router DSA<br />
fails over to.<br />
The command set write-precedence defines the order in which DSAs are chosen to<br />
perform updates. You can use it to direct the write requests from a failover<br />
computer to a preferred master. If the set write-precedence command is not<br />
present, updates follow the normal precedence, which is defined by the order of<br />
the DSAs in the configuration file, or the set precedence command.<br />
The DSAs in these lists have precedence over those that are not listed, and DSAs<br />
earlier in the lists have precedence over those later in the lists.<br />
When these commands occur in a configuration file, source them after the<br />
knowledge.<br />
To maximize performance, in general you should give faster DSAs precedence<br />
over slower DSAs, and local DSAs precedence over remote DSAs.<br />
Example: Using<br />
precedence for<br />
geographically<br />
separated DSAs<br />
The DSAs EAST, WEST, NORTH and SOUTH contain the same information. The<br />
following command ensures that DSAs in the east fail over to EAST before<br />
WEST:<br />
set precedence = EAST, WEST;<br />
The DSAs NORTH and SOUTH are not listed, so if both EAST and WEST are<br />
unavailable, DSAs will fail over to them in the order that they are listed in the<br />
configuration file.<br />
Example: Using write<br />
precedence<br />
set write-precedence = home-dsa,work-dsa;<br />
Distribution and DSP 5–19
Alternative DSAs<br />
DSA Load-Sharing<br />
Load-sharing is a way to use a router DSA and multiple data DSAs to improve<br />
performance.<br />
In a system with load-sharing, the router uses a least-busy algorithm to send<br />
read requests to the DSA with the least load at the time.<br />
In the example load-sharing configuration shown below, DSA2 has the smallest<br />
queue of outstanding queries, so the router DSA will send the next query to that<br />
DSA.<br />
Queries<br />
Router DSA<br />
Queue:<br />
20 queries<br />
Queue:<br />
0 queries<br />
Queue:<br />
10 queries<br />
DSA 1 DSA 2 DSA 3<br />
Database<br />
Example Load-Sharing Configuration<br />
When the router DSA is checking the DSAs, it only considers requests that it has<br />
sent, and it does not assess the load that might be caused by the request about to<br />
be sent, or the effect of requests that are being sent from other DSAs.<br />
You can examine the statistics logs of the data DSAs to understand how often the<br />
load is such that all three are busy. If all three are often busy, you might need<br />
more data DSAs.<br />
5–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alternative DSAs<br />
Load-Sharing Groups<br />
In a load-sharing system, DSAs work to balance the number of read requests.<br />
You can use load-sharing groups to constrain load-sharing to a sub-set of the DSAs<br />
that have the same prefix.<br />
The following example shows a router DSAs and three data DSAs with the same<br />
prefix. Two of these data DSAs are in a load-sharing group, and the router shares<br />
the load of read requests between these two DSAs. The third DSA is ignored<br />
because it is not in the load-sharing group.<br />
Read<br />
Requests<br />
Router DSA<br />
Load-sharing<br />
group<br />
DSA 1 DSA 2<br />
DSA 3<br />
Database<br />
Computer A<br />
Using a Load-Sharing Group to Limit Load-sharing to Particular DSAs<br />
Distribution and DSP 5–21
Alternative DSAs<br />
In the following example, the San Diego and Tokyo offices each use local loadsharing<br />
groups of DSAs, to improve performance. During normal operation,<br />
each local router DSA sends requests to the local group. If all of the DSAs in one<br />
local load-sharing group fail, the router can fail over to the remote load-sharing<br />
group.<br />
During normal operation, the router shares the load of read requests between the<br />
DSAs in the first load-sharing group. If all of the DSAs in this group are<br />
unavailable, the router will fail over to the second load-sharing group.<br />
Read<br />
Requests<br />
Read<br />
Requests<br />
San Diego<br />
Router DSA<br />
Tokyo<br />
Router DSA<br />
DSA 1 DSA 2<br />
DSA 3 DSA 4<br />
Database<br />
Computer A (San Diego)<br />
Load-sharing<br />
groups<br />
Replication<br />
Database<br />
Computer B (Tokyo)<br />
Example System with Two Load-Sharing Groups<br />
5–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alternative DSAs<br />
Set the DSA Precedence For Failover with Load-Sharing Groups<br />
You can use precedence rules to affect how failover works with load-sharing<br />
groups. For information about setting precedence, see the section Set the DSA<br />
Precedence For Failover in this chapter.<br />
If you use the set precedence command to list DSAs that are also in load-sharing<br />
groups, then a load-sharing group has the precedence of the highest DSA in that<br />
group.<br />
For example, consider the following command:<br />
set precedence DSA1, DSA2, DSA3, DSA4;<br />
A load-sharing group that includes DSA1 and DSA4 has precedence over a<br />
group that includes DSA2 and DSA3.<br />
Also, a load-sharing group that includes DSA4 has precedence over a group that<br />
includes no listed DSAs.<br />
Set Up a Load-Sharing System<br />
To set DSAs to share the load for a particular context prefix, do the following:<br />
1. Decide how many DSAs you will use to share the load of read requests.<br />
2. Set up these DSAs with the same prefix and the same data.<br />
3. Set each DSA to share the same knowledge information.<br />
4. Add the load-share DSA flag to the shared knowledge:<br />
set dsa dsaname = {<br />
...<br />
dsa-flags = load-share, ...<br />
... };<br />
5. In the router DSA’s group knowledge file (.dxg), list the load-sharing DSAs<br />
consecutively.<br />
6. (Optional) To create a load-sharing group, add the load-share-group item to<br />
the knowledge for the DSAs in the group:<br />
set dsa dsaname = {<br />
...<br />
load-share-group = group-name<br />
dsa-flags = load-share, ...<br />
... };<br />
Distribution and DSP 5–23
Alternative DSAs<br />
DSA Query Streaming<br />
Query streaming is a way to send particular types of queries to different DSAs.<br />
This allows you to dedicate DSAs to particular types of operations, which can<br />
improve performance consistency.<br />
You can use query streaming with load sharing, to direct queries to different<br />
load-sharing groups.<br />
How Query Streaming Works<br />
Query streaming is somewhat like checkout lanes in a supermarket. In a<br />
supermarket, the express lanes are reserved for small sales, to allow people with<br />
only a few items to be served quickly.<br />
In a supermarket without an express lane, people with only a few items can be<br />
stuck behind people with many items.<br />
Similarly, you can dedicate some DSAs to small, fast queries (for example,<br />
authentications) so that they are not held up by complex queries (for example,<br />
reports).<br />
In the following example, the Router DSA sends queries in the following manner:<br />
■ Simple searches only go to DSA 1 and DSA 2<br />
■ Complex searches only go to DSA 3<br />
■ Update requests only go to DSA 4<br />
Queries<br />
Router DSA<br />
Simple<br />
queries<br />
Simple<br />
queries<br />
Complex<br />
queries<br />
Update<br />
requests<br />
DSA 1 DSA 2 DSA 3<br />
DSA 4<br />
load-share<br />
limit-search<br />
read-only<br />
load-share<br />
limit-search<br />
read-only<br />
read-only<br />
Example of a Distributed System Set Up to Allow Query Streaming<br />
5–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Alternative DSAs<br />
Set Up Query Streaming<br />
To set up query streaming, follow these steps:<br />
1. Decide how many data DSAs your distributed system will include.<br />
2. Decide what queries each data DSA will accept.<br />
3. For each data DSA, set one or more of the following flags in the DSA<br />
knowledge file:<br />
The read-only flag<br />
A router will not forward update requests to a DSA that has the flag<br />
read-only set in its knowledge file. This routes update requests to any<br />
DSAs without the flag read-only.<br />
The limit-list flag<br />
A router DSA will not forward any list requests to a DSA that has the<br />
flag limit-list set in its knowledge file.<br />
The limit-search flag<br />
A router DSA will not forward any complex searches to a DSA that has<br />
the flag limit-search set in its knowledge file.<br />
For more information about the limit-search flag, see the section Example:<br />
How the limit-search DSA Flag Works in the chapter “General<br />
Administration.”<br />
What Is a Simple Search?<br />
This section describes simple and complex searches. If a DSA includes the limitsearch<br />
flag in its knowledge file, no complex searches will be sent to that DSA.<br />
The following searches are simple:<br />
■<br />
Exact match searches—For example, cn=john smith<br />
■ Initial substring searches—For example, cn=john s*<br />
■<br />
■<br />
Searches that include exact-match and initial-substring searches combined<br />
with simple ANDs or ORs,—For example, (&(cn=john smith)(cn=john s*))<br />
All base-object searches (reads), regardless of the filter<br />
The following searches are complex:<br />
(objectclass=*)<br />
(!(cn~=john smith))<br />
(&(objectclass=*)(cn~=john smith))<br />
(|(cn=jon*)(cn=john*))<br />
These complex searches could only be sent to a DSA that does not have the limitsearch<br />
flag set.<br />
Distribution and DSP 5–25
Chapter<br />
6 Security<br />
This chapter describes the following areas of <strong>eTrust</strong> <strong>Directory</strong> security:<br />
■<br />
■<br />
■<br />
■<br />
Secure Socket Layer (SSL) encryption<br />
Authentication<br />
Password management<br />
Access controls<br />
Security 6–1
Secure Socket Layer (SSL) Encryption<br />
Secure Socket Layer (SSL) Encryption<br />
This section describes how to use SSL to protect link connections to or from<br />
DXserver.<br />
About the SSL Protocol<br />
SSL is a protocol for providing link-level security. SSL has virtually become the<br />
industry standard for encryption, integrity, and authentication. For more<br />
information about SSL, see http://home.netscape.com/eng/ssl3/index.html.<br />
SSL and Certificates<br />
SSL uses X.509 certificates. When you use SSL, you must properly manage these<br />
certificates through a certification authority or appropriate software.<br />
JXplorer lets you manage certificates, private keys, and keystores. See the chapter<br />
“Using JXplorer” for more information about managing certificates and enabling<br />
SSL authentication.<br />
<strong>eTrust</strong> <strong>Directory</strong> and SSL<br />
DXserver supports SSL as both an encryption method and an authentication<br />
method. We refer to this as SSL encryption and SSL authentication.<br />
Note: SSL authentication always uses SSL encryption.<br />
6–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Secure Socket Layer (SSL) Encryption<br />
SSL Encryption and Authentication Using SSLD<br />
You can protect any link connection to or from DXserver with SSL encryption.<br />
<strong>eTrust</strong> <strong>Directory</strong> implements SSL encryption and authentication as a companion<br />
process to the DSA. This process is called SSLD. SSLD is based on OpenSSL.<br />
For security, SSLD must run on the same computer as the DXserver.<br />
SSLD is multithreaded, which means that one SSLD process can serve multiple<br />
DXservers simultaneously. There is no need to run multiple SSLD processes on<br />
the same computer.<br />
The SSLD server supports:<br />
■ SSL (both version 2 and 3)<br />
■<br />
Transport Layer Security (TLS)<br />
How the SSLD Works with Certificates<br />
SSLD uses the following types of certificates, which are stored in its<br />
configuration directory:<br />
■<br />
■<br />
Trusted root certificates (“trusted.pem”) that contain one or more<br />
certificates of trusted Certification Authorities.<br />
Personality certificates that identify the one or more DXservers that are<br />
communicating with the SSL server. There is one per DSA (dsaName.pem),<br />
and each one contains a private key.<br />
The following diagram displays this:<br />
<strong>Directory</strong><br />
Client<br />
DSA<br />
DB<br />
SSLD<br />
Personality<br />
Certs<br />
HSM<br />
Trusted<br />
Certs<br />
Security 6–3
Secure Socket Layer (SSL) Encryption<br />
How DXserver Works with SSL Binds<br />
Unlike other directory implementations, the <strong>eTrust</strong> <strong>Directory</strong> DSA handles DAP,<br />
LDAP, DSP and DISP protocols through a single port in SSL-encrypted and<br />
unencrypted forms. When SSL encryption or decryption is required, the DSA<br />
passes the packets to the SSLD to perform the SSL operation.<br />
When a client binds to a DXserver using SSL, the following happens:<br />
1. If the DXserver is not already connected, it connects to the SSLD, assuming it<br />
is running.<br />
Note: If the SSLD is not running or is not configured properly, possibly with<br />
a different port, the DSA refuses the client connection (fails the bind request).<br />
2. DXserver passes all SSL handshaking to the SSLD to establish the SSL<br />
connection with the client.<br />
3. DXserver uses SSLD to decrypt requests and encrypt responses.<br />
The following diagram displays this:<br />
<strong>Directory</strong><br />
Client<br />
DSA<br />
DB<br />
2<br />
1<br />
3<br />
SSLD<br />
6–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Secure Socket Layer (SSL) Encryption<br />
DXserver Personality Certificates<br />
When a DSA connects to SSLD it passes the DSA server name as its SSLD<br />
personality. The server name is the name specified by the set dsa dsaName<br />
command in the DSA configuration file in the knowledge directory. For example,<br />
for the Democorp DSA, the SSLD personality name is democorp.<br />
This personality determines the certificate file that the SSLD uses to support<br />
authentication of the DSA.<br />
The personality name passed to the SSL server is mapped to a file name of the<br />
form personality.pem (the personality string is converted to lowercase). This file<br />
contains a certificate and private key in PEM format (the private key is what<br />
gives the DSA its identity) unless a HSM is in use, in which case it is a hardware<br />
reference. For information about DXserver HSM support, contact Computer<br />
Associates at http://supportconnect.ca.com.<br />
Generating Personality Certificates<br />
You must not simply rename the personality files that come with <strong>eTrust</strong><br />
<strong>Directory</strong> (for example, from democorp.pem to mydsaname.pem) and edit the<br />
subject lines. This text is just comments for the real certificate—changing the text<br />
does not alter the certificate. You must generate a new certificate.<br />
To generate personality certificates, use separate certificate authority software.<br />
The popular certification authority software OpenSSL is available from<br />
http://www.openssl.org/. You can either build the package from the source<br />
code (which requires a compiler) or locate a binary (precompiled) package for<br />
your operating system.<br />
When you are generating a personality certificate, ensure the following:<br />
■<br />
■<br />
Make sure that the DSA name in the subject field of the certificate matches<br />
the DSA name in the DSA knowledge. For example, for the Democorp DSA,<br />
this is .<br />
Add the root certificates of the certificate authorities that you use to generate<br />
your DXserver personality certificates to the end of the trusted.pem file.<br />
Security 6–5
Secure Socket Layer (SSL) Encryption<br />
Setting Up SSL For DXserver<br />
This section describes what you have to do to set up SSL for DXserver. You will<br />
need a root certificate, a DSA personality certificates and an SSLD instance to<br />
service DSA requests.<br />
Configuring DXserver for SSL Operation<br />
DXserver needs to know which port the SSLD is using for connections. This is<br />
configured in the DSA configuration file (.dxc) in the knowledge directory.<br />
For example:<br />
set dsa Democorp =<br />
{ ...<br />
ssld-port = port_number<br />
...<br />
};<br />
If the SSLD port number is not specified, it defaults to port 1112.<br />
For a list of all ports in a default installation of <strong>eTrust</strong> <strong>Directory</strong>, see the section<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter DXserver Overview.<br />
Configuring the SSLD<br />
To configure SSLD, you need a root certificate, DSA personality certificates and a<br />
SSLD instance to service DSA requests.<br />
The format of the SSLD command is as follows:<br />
ssld action [arguments]<br />
The following table lists the SSLD actions available:<br />
Action<br />
install<br />
start<br />
Description<br />
Saves the startup arguments and options and sets the SSLD to start<br />
automatically at system startup.<br />
ssld install ssld-server-name -certfiles path -ca file [options]<br />
Starts the SSLD:<br />
ssld start ssld-server-name [-certfiles path -ca file [options]]<br />
If you have already installed the SSLD, you can omit the arguments and options.<br />
To start all previously installed SSLDs, use the command:<br />
ssld start all<br />
6–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Secure Socket Layer (SSL) Encryption<br />
Action<br />
stop<br />
Description<br />
Stops the specified SSLD:<br />
ssld stop ssld-server-name<br />
To stop all SSLDs, use the command:<br />
remove<br />
status<br />
-ciphers<br />
ssld stop all<br />
Removes the specified SSLD from the list of automatically restarting SSLDs so<br />
that it does not restart at the next system startup.<br />
ssld remove ssld-server-name<br />
To remove all SSLDs, use the command:<br />
ssld remove all<br />
Displays the status of all configured SSLDs:<br />
ssld status<br />
Prints a list of all ciphers that can be used for SSL/TLS connections:<br />
ssld -ciphers<br />
The following table describes the parameters of these commands.<br />
Parameter<br />
-certfiles path<br />
Meaning<br />
The directory that contains certificate and private-key files in PEM format.<br />
This parameter is required by the install action. It is also required by the start<br />
action if the SSLD server has not already been installed.<br />
-ca file<br />
A file that contains trusted certification authority certificates in PEM format.<br />
This parameter is required by the install action. This parameter is also required<br />
by the start action if the SSLD server has not already been installed.<br />
The arguments of the ssld install and the ssld start commands are:<br />
Argument<br />
-hsm_pin pin<br />
-hsm_lib file<br />
-hsm_slot n<br />
-cipher string<br />
-help<br />
-port n<br />
Values<br />
The hardware security module (HSM) user PIN. If specified, the private key is<br />
used through the HSM.<br />
File containing the pks#11 library supplied by the HSM vendor.<br />
The HSM slot number.<br />
Specifies the ciphers that will be used for SSL/TLS connections.<br />
Displays command usage.<br />
The listen port, which DXserver uses when connecting to the SSL daemon. If not<br />
specified, it defaults to port 1112.<br />
-tls Instructs SSLD to use TLS instead of SSL 3.0.<br />
Security 6–7
Secure Socket Layer (SSL) Encryption<br />
Argument<br />
-nologo<br />
Values<br />
Do not show the banner.<br />
-debug n Sets a debugging level (0-9).<br />
-threads n<br />
Specifies the number of extra threads. The default is 2, which makes the SSLD<br />
multi-threaded by default.<br />
Resetting SSLD Parameters<br />
The parameters of the ssld start command are stored. This means that even if you<br />
stop and restart the SSLD, it continues to use the parameters that you set when<br />
you first started the SSLD.<br />
For example, if you run the following commands, the logging level set in the first<br />
line is not reset:<br />
ssld start xxx -debug 9<br />
ssld stop xxx<br />
ssld start xxx<br />
There are two ways to reset SSLD parameters:<br />
■<br />
■<br />
Reset the parameter directly<br />
You can stop and start the SSLD again, making sure that you explicitly re-set<br />
all parameters. For example, to re-set the logging parameter:<br />
ssld stop xxx<br />
ssld start xxx -debug 0<br />
Install the SSLD again, with the new parameters<br />
Another way to reset SSLD parameters is to remove and re-install the SSLD.<br />
The installation re-sets the parameters:<br />
ssld stop xxx<br />
ssld remove xxx<br />
ssld install xxx [arguments]<br />
ssld start xxx<br />
The parameters are stored in the following locations:<br />
■ Windows—The following registry variable :<br />
HKEY_LO<strong>CA</strong>L_MACHINE\SYSTEM\CurrentControlSet\Services\ssld_ins<br />
tancename\Parameters<br />
■<br />
UNIX and Linux—The ssld_name.args file in $DXHOME/config/ssld<br />
6–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Secure Socket Layer (SSL) Encryption<br />
SSLD Is Multi-Threaded<br />
SSLD can be configured to run more than one instance on each computer.<br />
However, we recommend that you use only one instance of SSLD per computer.<br />
You should only run one instance of SSLD on each computer because SSLD<br />
cannot determine if there is another SSLD instance on the same port when it<br />
starts up. This is due to the way Windows allocates TCP ports. This limitation<br />
means that two SSLD instances might be running on the same port, with<br />
unpredictable results, including "Assertion Error" messages and SSLD hanging<br />
and refusing to accept new requests.<br />
Instead of running multiple instances of SSLD, use the -threads parameter to set the<br />
required number of threads. We recommend that you set the number of threads to<br />
twice the number of CPUs, unless you have a large number of CPUs. If you have<br />
many CPUs, then set the number of threads to the number of CPUs plus five.<br />
In the following example, the SSLD process uses four CPUs, and is started<br />
automatically when the Democorp DSA is started. The certificate and private key<br />
files are in the directory DXHOME/config/ssld/personalities, and the trusted<br />
Certification Authority (<strong>CA</strong>) certificate is in config/ssld/trusted.pem.<br />
ssld install democorp –certfiles config/ssld/personalities –ca config/ssld/trusted.pem –threads 4<br />
SSLD Example: Specifying the Cipher for SSL/TSL Connections<br />
You can specify which cipher is to be used for SSL/TLS connections. When you<br />
start the server, use the -cipher option, as in this example:<br />
ssld start democorp –certfiles config/ssld/personalities –ca<br />
config/ssld/trusted.pem -cipher RC4-MD5<br />
To list all the available ciphers, use the -ciphers action:<br />
ssld -ciphers<br />
A list of ciphers appears, as in the following example:<br />
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH(1024) Au=RSA Enc=3DES(168) Mac=SHA1<br />
EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=3DES(168) Mac=SHA1<br />
DES-CBC3-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=3DES(168) Mac=SHA1<br />
DHE-DSS-RC4-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=RC4(128) Mac=SHA1<br />
RC4-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(128) Mac=SHA1<br />
RC4-MD5 SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(128) Mac=MD5<br />
EXP1024-DHE-DSS-RC4-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=RC4(56) Mac=SHA1 export<br />
EXP1024-RC4-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(56) Mac=SHA1 export<br />
EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=DES(56) Mac=SHA1<br />
DES-CBC-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=DES(56) Mac=SHA1<br />
EXP-EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export<br />
EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export<br />
EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export<br />
EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export<br />
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export<br />
Mac=MD5 export<br />
Security 6–9
Secure Socket Layer (SSL) Encryption<br />
For more information about ciphers, see http://www.openssl.org/.<br />
6–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Secure Socket Layer (SSL) Encryption<br />
Client Encryption<br />
DXserver automatically detects an SSL session from an LDAP client or DAP<br />
DUA. If the SSLD is running, it manages all the session establishment and<br />
encryption. If the SSLD is not running, the connection is refused.<br />
The only way to force a client to use SSL encryption is by enforcing SSL<br />
authentication.<br />
DSA-to-DSA Encryption (DSP and DISP)<br />
To enable a DXserver to use encryption when communicating with a remote<br />
DSA, set the link flags to ssl-encryption in the knowledge file of the remote DSA.<br />
For example, to enable encryption from a Democorp DSA to a UNSPSC DSA,<br />
ensure that, in the knowledge, the UNSPSC link flag is set to ssl-encryption.<br />
set dsa UNSPSC =<br />
…<br />
link-flags = ssl-encryption<br />
…<br />
DUA<br />
OP<br />
DemoCorp<br />
DSA<br />
BIND<br />
UNSPSC<br />
DSA<br />
Note: The previous DSAs share the same configuration, but the Democorp<br />
directory must look up the capabilities of the other directories to decide whether<br />
to use SSL encryption.<br />
Security 6–11
Authentication<br />
Authentication<br />
Authentication is the process of validating users. During authentication, the<br />
server asks itself, “Is the user who they say they are?”<br />
DXserver supports three levels of authentication:<br />
■<br />
■<br />
■<br />
Anonymous (no credentials)<br />
Simple (name and password)<br />
SSL (certificate-based authentication)<br />
Authentication is performed on all incoming binds from a client or server. When<br />
certificate-based authentication is used, then all communication on the<br />
association set up by the bind will use SSL encryption.<br />
Setting the Minimum Authentication Level<br />
You can set the minimum authentication level on a DXserver using the<br />
set min-auth command. This sets the minimum requirements for a successful<br />
bind to the DXserver.<br />
No Authentication<br />
Setting no authentication permits any type of authentication (including<br />
anonymous). To permit any authentication, use the following command in the<br />
initialization script or at the management console:<br />
set min-auth = none;<br />
Name and Password Authentication<br />
To force authentication of at least a name and password, set min-auth to<br />
clear-password. This ensures that a user provides a user name and clear-text<br />
password or provide a certificate (to be checked using SSL authentication) on a<br />
bind.<br />
set min-auth = clear-password;<br />
Certificate Authentication<br />
To force authentication by certificate, set the following command:<br />
set min-auth = ssl-auth;<br />
6–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
Anonymous Authentication<br />
When no credentials are provided or only simple credentials are provided<br />
without a password (for instance, just a name), then the bind is treated as<br />
anonymous. An anonymous bind is accepted only when the minimum<br />
authentication level is none.<br />
Simple Authentication<br />
When a name and password are supplied with the following conditions, the bind<br />
is treated as simple.<br />
■<br />
■<br />
■<br />
■<br />
The name corresponds to a real entry in the directory.<br />
That entry has a password attribute.<br />
The supplied password matches it.<br />
The min-auth flag does not include the value ssl-auth.<br />
For simple authentication, all users must have corresponding directory entries<br />
containing the password attribute.<br />
Authentication fails and the bind is refused when:<br />
■<br />
■<br />
■<br />
The entry named by the user cannot be found.<br />
The entry named by the user name does not contain a password attribute.<br />
The password provided does not match the password value of the attribute<br />
in the entry named by the user name.<br />
When the user does not provide a user name and password or only provides a<br />
user name, and if the minimum authentication level is set to “none,” the bind is<br />
accepted as anonymous.<br />
You can add the password attribute to an object with a remote DUA. When<br />
access controls are in force, users can add or change a password only when they<br />
have the appropriate privilege, for example:<br />
■<br />
■<br />
■<br />
■<br />
Superuser<br />
<strong>Administrator</strong> of a subtree (only for entries in the subtree and only when the<br />
administrator has privileges on the password attribute)<br />
<strong>Administrator</strong>s of their own entry<br />
Registered user with update permissions on the password attribute<br />
Security 6–13
Authentication<br />
SSL Authentication<br />
SSL authentication has two parts:<br />
1. Establish the SSL connection.<br />
2. Establish the directory connection (using a bind).<br />
Establishing the SSL Connection<br />
The SSL client provides a certificate with the SSL connection:<br />
SSL<br />
Client<br />
DemoCorp<br />
DSA<br />
The DXserver/SSLD validates the certificate by checking the validity dates and<br />
checking the issuer of the certificate against the configured trusted roots.<br />
SSLD<br />
Trusted<br />
Certs<br />
SSL<br />
Client<br />
DemoCorp<br />
DSA<br />
The SSL connection is then established.<br />
SSL<br />
Client<br />
SSL<br />
DemoCorp<br />
DSA<br />
Establishing the <strong>Directory</strong> Connection<br />
The SSL client uses the SSL bind procedure. In LDAP, this is known as<br />
SASL/EXTERNAL. (In X.500, we use the Bind External Procedure.) This tells the<br />
directory to use the certificate from the link layer.<br />
6–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
SSL<br />
Client<br />
BIND<br />
SSL<br />
DemoCorp<br />
DSA<br />
The DSA checks the entry named by the subject DN contained in the certificate.<br />
In the case of DAP or LDAP (clients), the DSA verifies that the entry exists. In the<br />
case of DSP or DISP, the DSA will check the dsa-name in its knowledge.<br />
To bypass this last check of the certificate’s subject DN, use the command:<br />
set ssl-auth-bypass-entry-check = TRUE;<br />
This establishes the directory connection.<br />
SSL<br />
Client<br />
X.500/<br />
LDAP<br />
SSL<br />
DemoCorp<br />
DSA<br />
Restricted Chaining<br />
If a DSA receives a bind request and passes a compare request to a remote DSA,<br />
then the compare request will have a chaining-prohibited control set.<br />
This prevent the remote DSA from passing the compare request to another DSA<br />
and ensures that the compare is only processed by a trusted DSA.<br />
If users are storing a hierarchy of DSAs, then it is a good idea for the DSAs to<br />
share knowledge so that compare requests can be sent straight to the DSA that<br />
contains the entry.<br />
Overriding Restricted Chaining<br />
It is possible for a DSA to override the chaining-prohibited control by setting<br />
always-chain-down to true.<br />
This can be useful when you want to configure proxy DSAs. For information<br />
about proxy DSAs, see the section Proxy DSAs in chapter 5.<br />
However, we recommend that you do not override the chaining-prohibited<br />
control, because this breaks the trust relationship between DSAs.<br />
Security 6–15
Authentication<br />
Bypassing the Entry Check<br />
Usually, during SSL authentication, the DSA verifies that the entry exists. This<br />
can be bypassed with the command:<br />
set ssl-auth-bypass-entry-check = TRUE;<br />
In this case, when authenticating the client, the DSA will not check that an entry<br />
with a distinguished name matching the subject field in the certificate of the<br />
client exists in the directory.<br />
Distributed User Authentication<br />
A user can bind to one DSA when their entry is held on another DSA. When the<br />
bind is made, the DXserver can forward a check to another DSA when certain<br />
distributed authentication parameters are set.<br />
During simple authentication, the local DSA can forward the password check to<br />
a remote DSA only when the local DSA can make an authenticated connection to<br />
the remote DSA. The remote DSA must have the correct trust-flags set in the<br />
DSA definition.<br />
For example, to enable the Democorp DSA to forward a password check on to<br />
the UNSPSC DSA, the Democorp DSA must check its knowledge of the UNSPSX<br />
DSA. If the UNSPSC knowledge file contains the trust flag allow-check-password,<br />
then the Democorp DSA can pass the password compare request to the UNSPSC<br />
DSA.<br />
set dsa UNSPSC =<br />
...<br />
trust-flags = allow-check-password<br />
...<br />
DUA<br />
bind request<br />
bind response<br />
Democorp<br />
DSA<br />
compare request<br />
compare response<br />
UNSPSC<br />
DSA<br />
If the DSA receiving the bind request passes a compare request of the password<br />
value to the remote DSA, and this returns a compare confirm with assertion true,<br />
then the DSA returns a bind-confirm to the user.<br />
6–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
DSP Simple Authentication<br />
DSP and DISP binds are subject to the min-auth setting. This means that if the<br />
local DSA has enabled authentication, an incoming DSP or DISP bind request<br />
must have valid bind credentials.<br />
Authenticated DSP binds use mutual authentication. During the bind process,<br />
each DSA supplies its own credentials to the other DSA, and each DSA also<br />
checks the credentials supplied to it by the other DSA.<br />
Credentials Used During DSA Binds<br />
An incoming bind is accepted only when there is a DSA knowledge<br />
configuration that meets all the following conditions:<br />
■<br />
■<br />
■<br />
The distinguished name of the credentials matches the remote DSA dsaname.<br />
The password in the credentials matches the remote DSA password.<br />
The address of the binding DSA matches the address of the remote DSA.<br />
We recommend that the DSAs in a DSP-meshed network share the same group<br />
knowledge configuration file so that all the combinations of names and<br />
passwords are known to each DSA.<br />
See Managing DSP in the chapter “Distribution and DSP” for more information<br />
about sending credentials with a DSP bind request.<br />
Security 6–17
Authentication<br />
How Mutual Authentication Works<br />
This section describes the mutual authentication process.<br />
1. The DSA sending the bind request includes its credentials with the bind<br />
request. It gets these credentials from its own knowledge file.<br />
2. The DSA receiving the bind request checks the credentials against its<br />
knowledge of the sending DSA.<br />
In this example, the UNSPSC DSA receives a bind request from the<br />
Democorp DSA, and checks its credentials:<br />
set dsa Democorp =<br />
...<br />
dsa-name = <br />
dsa-password = …<br />
address = …<br />
...<br />
Democorp<br />
DSA<br />
bind request<br />
UNSPSC<br />
DSA<br />
3. The DSA that received the bind requests now sends a bind response back,<br />
including its own credentials in this bind response.<br />
4. The DSA that sent the bind request checks the credentials of the other DSA<br />
against its knowledge of the other DSA.<br />
In the following example, the UNSPSC DSA receives a bind response from<br />
the Democorp DSA, and checks its credentials:<br />
set dsa UNSPSC =<br />
...<br />
dsa-name = <br />
dsa-password = …<br />
address = …<br />
...<br />
Democorp<br />
DSA<br />
bind response<br />
UNSPSC<br />
DSA<br />
5. If all the credential checks match, the bind succeeds.<br />
6–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
DSP SSL Authentication<br />
To enable SSL authentication between DSAs, the auth-levels flag of the receiving<br />
DSA must include the value ssl-auth.<br />
If you simply want DSA-to-DSA connections to be encrypted, SSL authentication<br />
is unnecessary. Instead, set the link-flags element in the DSA knowledge to sslencryption.<br />
How DSP SSL Authentication Works<br />
This section describes the DSP SSL authentication process.<br />
1. The DSA sending the bind request checks its own knowledge file to<br />
determine if it can use SSL.<br />
2. The sending DSA then checks the knowledge file of the receiving DSA to see<br />
if it can accept an SSL connection. If it cannot, the bind attempt is aborted. If<br />
it can, the DSA sends the SSL bind request.<br />
In this example, the Democorp DSA finds the ssl-auth flag in its copy of the<br />
UNSPSC knowledge file, so it sends the SSL bind request:<br />
set dsa UNSPSC =<br />
…<br />
auth-levels = ssl-auth<br />
…<br />
DemoCorp<br />
DSA<br />
BIND<br />
UNSPSC<br />
DSA<br />
DISP Authentication<br />
DISP authentication is controlled by the DISP agreement. See DISP Agreements<br />
in the chapter “Replication” for more information about DISP agreements.<br />
Depending on the setting of auth-level in the agreement, the authentication<br />
method follows the DSP simple or DSP SSL procedures outlined previously.<br />
Security 6–19
Authentication<br />
Bypassing Mutual Authentication<br />
In the case of simple authentication, DSAs always exchange name and password<br />
if configured. Not all third party DSAs or LDAP servers support the returning of<br />
credentials on bind confirm. You can set a trust flag in the knowledge file of the<br />
third-party DSA to bypass the return credentials check:<br />
set dsa UNSPSC =<br />
…<br />
trust-flags = no-server-credentials<br />
…<br />
DemoCorp<br />
DSA<br />
BIND<br />
RESPONSE<br />
UNSPSC<br />
3 rd PARTY<br />
DSA<br />
In the case of SSL authentication, certificates are always exchanged and the<br />
subject DN is always checked against the DSA name in the knowledge<br />
configuration file. You cannot bypass mutual authentication when using SSL<br />
authentication.<br />
6–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
Conveying User Authentication<br />
In a networked system of DSAs, a user can bind to a DSA, and then request<br />
information that is held on another DSA.<br />
You can use the trust-conveyed-originator flag to allow the first DSA to convey the<br />
user’s authentication to the second DSA.<br />
How User Authentication Is Conveyed Between DSAs<br />
1. A user binds to a DSA. The bind request includes the user’s DN, and the<br />
user’s credentials.<br />
2. The DSA authenticates the user.<br />
3. The user makes another request which the current DSA cannot fulfill.<br />
4. The DSA passes the request to another DSA that will be able to fulfill the<br />
request. The request includes the user’s DN and authentication<br />
5. The receiving DSA must decided whether to trust the user’s authentication.<br />
To do this, it looks at the knowledge file of the first DSA for the trustconveyed-originator<br />
flag.<br />
6. If the receiving DSA finds the trust-conveyed-originator flag, it accepts the<br />
request. Even though the user was authenticated on Democorp, it will be<br />
treated as if it had been authenticated on UNSPSC.<br />
7. The receiving DSA uses the DN of the originating user to determine what<br />
access controls to apply to the request.<br />
In this example, the UNSPSC DSA trusts the user authentication of the request<br />
that has been passed to it by the Democorp DSA:<br />
set dsa DemoCorp =<br />
…<br />
trust-flags = trust-conveyed-originator<br />
…<br />
DUA<br />
OP<br />
DemoCorp<br />
DSA<br />
OP<br />
UNSPSC<br />
DSA<br />
Security 6–21
Authentication<br />
DSP Link Authentication<br />
Traffic on any link is generally carried at the same security level. That is:<br />
■<br />
■<br />
■<br />
High security—SSL authentication is carried on an SSL bind<br />
Medium security—simple authentication is carried on a simple bind<br />
Low security—anonymous authentication is carried on an anonymous bind<br />
SSL authentication<br />
DSA<br />
Simple authentication<br />
DSA<br />
No authentication<br />
Possible Problems with Link Authentication<br />
This can present problems if a user makes a successful simple bind to a directory,<br />
but is refused any distributed operations because all distributed links have a<br />
minimum authentication level of ssl-auth.<br />
Similarly, a user might make a successful SSL authenticated bind to a directory,<br />
only to be refused distributed operations because the distributed directories<br />
cannot support SSL authentication.<br />
In either case, the error reported is “No compatible link type.”<br />
Possible Solutions to the “No compatible link type” Error<br />
One solution is to change the “auth-levels” so that a compatible DSP link can be<br />
established.<br />
Another solution is to either upgrade or downgrade the trust levels on the link<br />
between distributed DSAs. A user who makes a successful simple bind can be<br />
upgraded to allow distributed operations over an SSL link; a user who makes a<br />
successful SSL bind can be downgraded to allow distributed operations over an<br />
anonymous or simple link.<br />
This should not be undertaken lightly. The only reasonable use is to permit<br />
unauthenticated DSA links within the one organization (or on the one host), or to<br />
grant access to a public server. You can use downgrading and upgrading on<br />
inter-office links, but the use of encryption should suffice.<br />
6–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Authentication<br />
Examples: Upgrading and Downgrading the Link Type<br />
The following example demonstrates the upgrade of anonymous bind user on a<br />
simple link between a Democorp DSA and a UNSPSC DSA:<br />
set dsa UNSPSC =<br />
…<br />
trust-flags = allow-upgrading<br />
…<br />
DUA<br />
anon<br />
DemoCorp<br />
DSA<br />
simple<br />
UNSPSC<br />
DSA<br />
The following example demonstrates the downgrade of an SSL bind user on a<br />
simple link between a Democorp DSA and a UNSPSC DSA:<br />
set dsa UNSPSC =<br />
…<br />
trust-flags = allow-downgrading<br />
…<br />
SSL<br />
DUA<br />
DemoCorp<br />
DSA<br />
simple<br />
UNSPSC<br />
DSA<br />
Impersonation Protection<br />
DSA authentication is completely separate from DUA authentication. This means<br />
that a DUA cannot gain access using the credentials of a DSA, and a DSA cannot<br />
gain access using the credentials of a DUA.<br />
DSA authentication checks network addresses and credentials. This makes it<br />
difficult for one DSA to impersonate another DSA.<br />
Security 6–23
Managing Passwords<br />
Managing Passwords<br />
A policy is a set of rules that defines behavior.<br />
In <strong>eTrust</strong> <strong>Directory</strong>, you can define a policy for passwords. This password policy<br />
controls the password that users enter to bind to a DSA.<br />
There are two kinds of password rules:<br />
■<br />
■<br />
Password quality checking rules<br />
Password management rules<br />
Password quality checking rules define the quality of a new password. The<br />
rules are applied when a user changes their own password. The rules include:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Setting the length of the password:<br />
Setting the minimum number of particular types or characters:<br />
Limiting repetition within the password:<br />
Preventing the user from including their own user name in the password<br />
Preventing the user from re-using a recent password<br />
Password management rules define how to deal with passwords during<br />
operation, including:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Life span of passwords<br />
Suspending user accounts manually<br />
Locking user accounts after incorrect login attempts<br />
Resetting passwords<br />
Grace logins after the password has expired<br />
How Password Rules Are Applied<br />
Password rules (except vetting checks) are only applied when operations are<br />
being performed by the user that owns the password. For example, if an<br />
administrator updates the password then no history check will occur. This<br />
effectively resets the password.<br />
Each DSA can have a single set of password rules. You cannot apply different<br />
password policies to users stored within the same DSA.<br />
You can apply different policies to different groups of users by splitting the users<br />
up by sub-tree and having each sub-tree serviced by a separate DSA. Each DSA<br />
can then have its own set of password policies.<br />
6–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing Passwords<br />
Password Protection<br />
You cannot read passwords directly. An attempt to read a password attribute<br />
results in the return of the encrypted value. See Password Storage in the chapter<br />
“General Administration” for more information about encryption algorithms.<br />
Passwords are always single-valued. This means that an administrator cannot<br />
add a secret value and use this as an unpublished entry point into the DSA.<br />
Passwords are encrypted before they are stored in the database. This prevents<br />
the possibility of interrogating the database directly for the value of any<br />
passwords.<br />
Password logins are secure only if each person can change only their own<br />
password. Make sure that you set access controls so that each user can update<br />
only their own password. Also make sure that administrators are allowed to<br />
update any user password.<br />
Password Command Options<br />
The following table briefly describes each of the password settings. The default<br />
for most values is 0, which means that the option is off:<br />
Keyword Parameter Description<br />
password-age Number of days | 0<br />
(Default: 0)<br />
password-allow-ignoreexpired<br />
password-allow-locking<br />
True | False<br />
(Default: False)<br />
True | False<br />
(Default: False)<br />
password-alpha Num. chars | 0<br />
(Default: 0)<br />
The number of days for which a password will<br />
remain valid<br />
See the section Setting the Life Span of Passwords.<br />
The password-allow-ignore-expired option bypasses<br />
the expiration check of the password.<br />
This only takes effect for entries that include the<br />
attribute dxPwdIgnoreExpire.<br />
See the section Setting Passwords to Never Expire.<br />
Allows a user’s account to be locked.<br />
This only takes effect for entries that include the<br />
attribute dxPwdLocked.<br />
See the section Locking an Account after Incorrect<br />
Login Attempts.<br />
The minimum number of alphabetic characters in the<br />
password<br />
See the section Checking Password Quality .<br />
Security 6–25
Managing Passwords<br />
Keyword Parameter Description<br />
password-alpha-num Num. chars | 0<br />
(Default: 0)<br />
password-force-change<br />
True | False<br />
(Default: False)<br />
password-grace-logins Number of logins | 0<br />
(Default: )<br />
password-history Number of entries | 0<br />
(Default: 0)<br />
password-last-use Number of days | 0<br />
(Default: 0)<br />
password-lowercase Num. chars | 0<br />
(Default: 0)<br />
The minimum number of alphanumeric characters in<br />
the password<br />
See the section Checking Password Quality .<br />
Forces users to change their passwords after their<br />
passwords have been reset<br />
See the section Forcing Password Changes after<br />
Reset.<br />
The maximum number of times that the user can<br />
log in with their password after it has expired<br />
See the section Setting the Number of Grace Logins.<br />
The maximum number of entries to retain in the<br />
history. This prevents the user from re-using these<br />
passwords.<br />
See the section Preventing Users from Re-using<br />
Passwords.<br />
The number of days a password remains valid if it<br />
is not used. If the value is exceeded, the password<br />
expires.<br />
See the section Setting the Maximum Life Span of<br />
Passwords.<br />
The minimum number of lowercase characters in the<br />
password<br />
See the section Checking Password Quality .<br />
password-max-length Num. chars | 0 The maximum length of the password<br />
See the section Checking Password Quality .<br />
password-max-repetition Num. chars | 0<br />
(Default: 0)<br />
password-max-substringrepetition<br />
Number of reps | 0<br />
(Default: 0)<br />
password-max-suspension Number of secs | 0<br />
(Default: 0)<br />
The maximum number of single characters that can<br />
be repeated in a password<br />
See the section Checking Password Quality .<br />
The password-max-substring-repetition option sets<br />
the maximum repetitions of a substring within a<br />
password<br />
See the section Checking Password Quality .<br />
The number of seconds after which a locked<br />
password reactivates<br />
See the section Locking an Account after Incorrect<br />
Login Attempts.<br />
6–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing Passwords<br />
Keyword Parameter Description<br />
password-min-age Number of days | 0<br />
(Default: 0)<br />
password-min-length Num. chars | 0<br />
(Default: 6)<br />
Integer ≥2 | 0<br />
(Default: 0)<br />
password-non-alpha Num. chars | 0<br />
(Default: 0)<br />
password-non-alpha-num Num. chars | 0<br />
(Default: 0)<br />
password-numeric Num. chars | 0<br />
(Default: 0)<br />
password-policy<br />
True | False<br />
(Default: False)<br />
password-retries Integer | 0<br />
(Default: 0)<br />
password-uppercase Num. chars | 0<br />
(Default: 0)<br />
password-min-lengthrepeated-substring<br />
password-usernamesubstring<br />
True | False<br />
(Default: False)<br />
The number of days since a password was changed<br />
until it can be changed again<br />
See the section Setting the Minimum Life Span of<br />
Passwords.<br />
The minimum length of a password<br />
See the section Checking Password Quality .<br />
The password-min-length-repeated-substring option<br />
sets the minimum length of substrings that will be<br />
checked.<br />
This only takes effect for entries that include the<br />
attribute maxSubstrRep.<br />
See the section Checking Password Quality .<br />
The minimum number of non-alphabetic<br />
characters in the password<br />
See the section Checking Password Quality .<br />
The minimum number of non-alphanumeric<br />
characters in the password<br />
See the section Checking Password Quality .<br />
The minimum number of numeric characters in the<br />
password<br />
See the section Checking Password Quality .<br />
Enable password management<br />
The number of consecutive failed logon attempts<br />
before a password is locked<br />
See the section Locking an Account after Incorrect<br />
Login Attempts.<br />
The minimum number of uppercase characters in the<br />
password<br />
See the section Checking Password Quality .<br />
The password-username-substring option sets<br />
whether the password can contain the user’s RDN<br />
When this is set to true, the password must not<br />
contain the user’s last RDN.<br />
See the section Checking Password Quality .<br />
Security 6–27
Managing Passwords<br />
Enabling or Disabling Password Management<br />
Even if you have other password options set, they will only take effect if you set<br />
the password-policy option to true.<br />
To enable or disable password management, set the following option:<br />
set password-policy = true | false;<br />
Checking Password Quality<br />
You can set up rules to make sure that users only choose strong passwords.<br />
If you have set rules about password quality, these rules are applied when a user<br />
attempts to change their own password. If the new password does not pass the<br />
tests, the user will have to try again with a new password.<br />
When an administrator changes a password for a user, the password policy rules<br />
are not applied. The rules will be applied the next time that the user changes<br />
their own password.<br />
Set the length of the password:<br />
set password-min-length = number-of-characters | 0;<br />
set password-max-length = number-of-characters | 0;<br />
Set the minimum number of particular types of characters:<br />
set password-alpha = number-of-characters | 0;<br />
set password-alpha-num = number-of-characters | 0;<br />
set password-lowercase = number-of-characters | 0;<br />
set password-non-alpha = number-of-characters | 0;<br />
set password-non-alpha-num = number-of-characters | 0;<br />
set password-numeric = number-of-characters | 0;<br />
Limit repetition within the password:<br />
set password-max-repetition = number-of-characters | 0;<br />
set password-max-substring-repetition = number-of-characters | 0;<br />
set password-min-length-repeated-substring = number-of-characters | 0;<br />
Note: The password-min-length-repeated-substring option only affects those users<br />
whose entries include the attribute maxSubstrRep.<br />
Prevent the user from including their own user name in the password:<br />
set password-username-substring = true | false;<br />
6–28 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing Passwords<br />
Setting the Life Span of Passwords<br />
Use the following commands to control password expirations.<br />
Setting the Maximum Life Span of Passwords<br />
Set the number of days for which a password will remain valid:<br />
set password-age = number-of-days | 0;<br />
Set the number of days a password remains valid if it is not used. If the value is<br />
exceeded, the password expires:<br />
set password-last-use = number-of-days | 0;<br />
Example: Making<br />
passwords valid<br />
indefinitely<br />
You want passwords to be valid indefinitely except when they are not used for<br />
30 days. Set the parameters as follows:<br />
set password-policy = TRUE;<br />
set password-last-use = 30;<br />
You do not need to use the set password-age option because you are using its<br />
default value of 0 (off).<br />
Setting the Minimum Life Span of Passwords<br />
You can also set the minimum life span of a password. This is the number of<br />
days since a password was changed until it can be changed again.<br />
You can use this to prevent people from changing their password many times to<br />
fill up the password history. To do this, use the following command:<br />
set password-min-age = number-of-days | 0;<br />
Setting Passwords to Never Expire<br />
Accounts can be made to never expire. This is useful for accounts shared by<br />
many users. To set a user’s password to never expire:<br />
1. Set the password-allow-ignore-expired option to true:<br />
set password-allow-ignore-expired = true;<br />
2. Add the attribute dxPwdIgnoreExpire to the user’s entry.<br />
To check which user passwords are set to never expire:<br />
■<br />
Search for all user accounts with the attribute dxPwdIgnoreExpire.<br />
You can only find out if entries have this attribute by searching for it<br />
explicitly.<br />
Security 6–29
Managing Passwords<br />
Setting the Number of Grace Logins<br />
In a grace login system, passwords expire but users can use an expired password<br />
for limited number of times. This gives them the opportunity to change the<br />
password.<br />
If the number of grace logins is exceeded, the account will behave as if it were<br />
expired.<br />
The number of grace logins remaining will be sent back to the binding client in<br />
the presence of the password policy request control.<br />
To set the number of grace logins, use the following command:<br />
set password-grace-logins = number-of-grace-logins | 0;<br />
Resetting a Password<br />
Whenever an administrator updates a user password, the password policy<br />
attributes for that entry are reset. These attributes include:<br />
■<br />
■<br />
■<br />
Any password history<br />
The time of the last use of the password<br />
The time the password was created<br />
For example, if password-age is set to 30 days and a user has not logged in for<br />
more than 30 days, the administrator can update that user's password to enable<br />
that user to log in again.<br />
Forcing Password Changes after Reset<br />
You can force users to change their passwords after their passwords have been<br />
reset. To do this, use the following command:<br />
set password-force-change = true;<br />
When a user logs in with their new password, the only operation the user can<br />
perform is to change their password. After the user has changed their password,<br />
their normal operations are restored.<br />
This password control can only be used with LDAP clients that are aware of<br />
LDAP password policy controls (for example, LDUA and the PAM-LDAP client).<br />
6–30 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Managing Passwords<br />
Locking an Account after Incorrect Login Attempts<br />
You can set accounts to be locked if someone has made too many unsuccessful<br />
attempts to log in. To set accounts to be locked after a certain number of<br />
attempts to log in, use the following command:<br />
set password-retries = number-of-attempts;<br />
To allow users to attempt to log on again after a certain amount of time has<br />
passed, use the following command:<br />
set password-max-suspension = time-in-seconds | 0;<br />
Example:<br />
Limiting the number<br />
of logon attempts<br />
You want to allow users attempt to log on only two times before their account<br />
is locked, and you want to allow them to try to log on again after six hours. To<br />
do this, use the following commands:<br />
set password-policy = TRUE;<br />
set password-retries = 2;<br />
set password-max-suspension = 21600;<br />
Suspending an Account Manually<br />
You can suspend a user’s account manually by locking their password. You can<br />
later remove the suspension, and the user can continue to use that password.<br />
Note: This only works with LDAP clients that are aware of LDAP password<br />
policy controls (for example, LDUA and the PAM-LDAP client).<br />
To suspend a user’s account, you need to do the following:<br />
1. Set access controls as required (see the other sections in this chapter).<br />
2. Enable password locking. To do this, use the following command:<br />
set password-allow-locking = true;<br />
3. Lock the user’s password. To do this, add the attribute dxPwdLocked to the<br />
user’s entry.<br />
To unlock the account:<br />
■<br />
Remove the attribute dxPwdLocked from the user’s entry.<br />
Do not set the value to 0. If this attribute is present, the account will still be<br />
locked.<br />
To check which user accounts are locked:<br />
■<br />
Search for all user accounts with the attribute dxPwdLocked.<br />
The only way to find out if entries have this attribute if you search for it<br />
explicitly.<br />
Security 6–31
Managing Passwords<br />
Preventing Users from Re-using Passwords<br />
Set the maximum number of entries to retain in the history. By default, this<br />
feature is disabled (0). If you do not want to check a changed password against<br />
old passwords, set the value to 0:<br />
set password-history = maximum-number | 0;<br />
Some Password Controls Require an LDAP Client<br />
Some password controls can only be used with LDAP clients that are aware of<br />
LDAP password policy controls (for example, LDUA and the PAM-LDAP client).<br />
This section of the <strong>eTrust</strong> <strong>Directory</strong> password policy follows the proposed<br />
standard described in section 5 of this draft document:<br />
http://www.ietf.org/internet-drafts/draft-behera-ldap-password-policy-07.txt.<br />
Note: This document may be renamed in the future.<br />
PasswordPolicyResponseValue ::= SEQUENCE {<br />
warning [0] CHOICE {<br />
timeBeforeExpiration [0] INTEGER (0 .. maxInt),<br />
graceLoginsRemaining [1] INTEGER (0 .. maxInt) } OPTIONAL,<br />
error [1] ENUMERATED {<br />
passwordExpired (0),<br />
accountLocked (1),<br />
changeAfterReset (2),<br />
passwordModNotAllowed (3),<br />
mustSupplyOldPassword<br />
(4),
Managing Passwords<br />
Example Password Policy<br />
This section describes a sample password policy, and then lists the commands to<br />
create that policy.<br />
For this policy, you want to set up the following rules:<br />
■<br />
■<br />
■<br />
■<br />
Passwords can be reused. You do not want to keep a history of old<br />
passwords.<br />
A password must be at least eight characters in length with at least one<br />
numeral.<br />
If a user’s password is ever reset, you want the user to change the password<br />
immediately after their first login.<br />
If a password is not used for sixty days, you want the account to be locked.<br />
To set up this policy, set the following password rules:<br />
set password-policy = true;<br />
set password-min-length = 8;<br />
set password-numeric = 1;<br />
set password-force-change = true;<br />
set password-min-age = 60;<br />
Security 6–33
Access Control Overview<br />
Access Control Overview<br />
Access controls protect data from unauthorized access or modification.<br />
Access controls work by asking this question before performing an operation:<br />
Is this client permitted to perform this operation, on this data, in this subtree, at<br />
this time?<br />
where:<br />
- A client is a user, a role, a group of users, or a subtree of users.<br />
- An operation is one of the usual directory services, such as compare, list,<br />
search, read, add, remove, modify, or modify-dn.<br />
- The data (protected item) is an entry, attribute, or attribute value.<br />
- A subtree is a particular area of the DIT.<br />
- The time is a particular minute of the day or a particular day of the week.<br />
When the answer to this question is yes, the operation can proceed. When the<br />
answer is no, the operation is refused.<br />
Access Control Policies<br />
A number of access controls are usually in place. The net effect is known as an<br />
access control policy. By definition, only one access control policy is in place at any<br />
given time.<br />
An access control policy can change periodically, for example, there can be one<br />
for business hours and another for after hours. You can set the DXserver access<br />
controls to activate at certain times, so a single policy could contain different<br />
rules for different times of the day or week.<br />
To define your access control policy, you define a set of rules access control.<br />
During operation, DXserver maps these rules onto 1993 X.500 access controls.<br />
6–34 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Access Control Overview<br />
Access Control Rules<br />
DXserver manages access controls by letting you define rules. There are two<br />
types of rules:<br />
Static rules—These apply to individuals and groups of individuals, and are<br />
stored as text files in the DXserver configuration files, or run as commands<br />
on DXconsole.<br />
Dynamic rules—These are stored in an attribute in the directory, and can be set<br />
by anyone who has the power to delegate the permissions being created.<br />
In addition, <strong>eTrust</strong> <strong>Directory</strong> lets you define users groups and roles, which can<br />
help you apply access controls to many users at once.<br />
Important! The 1993 X.500 access controls are not exposed directly; rather they are<br />
defined by rules. This is because the 1993 X.500 Access Controls are difficult to<br />
understand (defining such things as userFirst, itemFirst, precedence, protectedItems, and<br />
so on) and because the definitions of DXserver rules are mathematically proven not to<br />
have security loopholes.<br />
Designing Your Access Control Scheme<br />
We recommend that you use these principles while you are developing your<br />
access control scheme:<br />
■<br />
■<br />
■<br />
■<br />
Plan your access control scheme before you start implementing it<br />
Use domains to limit the range of your access controls<br />
Grant access rather than denying access<br />
Keep access control schemes simple<br />
Plan Your Access Control Scheme<br />
Before you start setting access controls, plan your access control scheme. To do<br />
this, write your scheme out carefully. Here is an example of a set of access<br />
control rules written in plain language:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
The DSA manager has all privileges.<br />
Authenticated users can update their own entries.<br />
PABX operators can update all telephone numbers.<br />
Public (anonymous) users can view only name, e-mail addresses, and<br />
telephone numbers of staff, but they can view anything in the public subtree.<br />
Passwords must be invisible to everyone except DSA administrators.<br />
Security 6–35
Access Control Overview<br />
Use Domains to Limit the Range of Access Controls<br />
A static access control policy can apply to a single DSA, or a group of DSAs that<br />
share the same (or have copies of) group configuration files.<br />
Sharing the same access control configuration across many (or all) DSAs makes<br />
administration easier, and enables access-controlled routing.<br />
Grant Access Rather than Denying Access<br />
In general, you should grant rather than deny access to data.<br />
If you grant access to all data and then deny access to portions of the data,<br />
sensitive data that you have protected can become visible inadvertently.<br />
For example, when items within a subtree are protected and the root of the<br />
subtree (or a parent) is renamed, the protection no longer exists. Any new<br />
attributes are also automatically visible, unless specific denials are implemented.<br />
Keep Access Control Schemes Simple<br />
You should design your access control scheme to be as simple as possible. This<br />
might involve re-designing your DSAs.<br />
This is important because overly complex access control scheme can lead to the<br />
following problems:<br />
Security breaches—If you define many different groups with different subtrees,<br />
you must maintain careful control of valid users and subtrees. If you lose<br />
track of valid users and subtrees, this will eventually cause a security<br />
problem.<br />
Performance—Complex access control schemes can result in performance<br />
degradation. This is because the DSA may need to evaluate every control for<br />
every piece of information returned, depending on the circumstance and<br />
privileges of the user in question.<br />
6–36 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Access Control Overview<br />
Working with Access Controls<br />
Enabling Access Controls<br />
1. Enable access controls:<br />
set access-controls = true;<br />
2. Set static or dynamic access control rules.<br />
Clearing Access Controls<br />
To reset all access controls, use the following command:<br />
clear access;<br />
Displaying Access Controls<br />
To display the 1993 X.500 access control details, use the following command:<br />
get access;<br />
For full details of access controls, see the 1993 X.500 standard<br />
Security 6–37
Static Access Controls<br />
Static Access Controls<br />
Static access controls are applied to individuals or groups of individuals.<br />
Overview of Static Access Control Rules<br />
This section describes static access controls and how they work<br />
Static Rule Components<br />
A static access control rule can include the following information:<br />
■ The rule type<br />
■ Which user, groups, or roles it applies to<br />
■ Which area of the directory it applies to<br />
■ What attributes it applies to<br />
■ What additional permissions it gives<br />
■ What authentication level it requires<br />
■ When it applies<br />
Because all rules are cumulative, you can define very complex access control<br />
polices.<br />
Hierarchy of Rules<br />
The static access control rules have a hierarchy of power. Here are the rules listed<br />
from superior to inferior:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Superuser<br />
Administrative user<br />
Protected item<br />
Registered user<br />
Public user<br />
A superior rule always overrides an inferior user rule. For example, a superuser<br />
rule always overrides any administrative user rule.<br />
6–38 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
Rule Inheritance<br />
Rules are inherited:<br />
Grants are inherited above<br />
If a grant is defined for a given level, then all levels above inherit that grant.<br />
For example, if all registered users are granted read/write permission to<br />
their password, then superusers and administrative users are granted the<br />
same permission automatically.<br />
Denies are inherited below<br />
If a deny is defined for a given level, then all levels below inherit the deny.<br />
For example, if a registered user is denied access to home address, then all<br />
public users are denied the same.<br />
Running Static Access Control Commands<br />
You can run access control commands from DXconsole, or you can include them<br />
in a DXserver configuration file (.dxc) in the access directory.<br />
If you issue these commands using DXconsole, the commands are not stored in<br />
the configuration files. This means that they are only valid for the run-time of the<br />
DSA.<br />
If you include static access control rules in the DXserver configuration file, they<br />
are activated when DXserver is initialized. This occurs when DXserver starts up,<br />
and when an administrator reinitializes the system.<br />
Generally, you group these files together by using a group configuration file<br />
(.dxg), which constitutes an access control policy. You can share policies among a<br />
number of DSAs.<br />
Security 6–39
Static Access Controls<br />
Setting Up Static Access Controls<br />
This section shows the command for setting access control rules, and describes<br />
the options you can use with these rules.<br />
The command for setting static access control rules has the following format:<br />
set rule-type tag = {<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
subtree = DN<br />
attrs = attr1 [, attr2 ...]<br />
perms = perm1 [, perm2 ...]<br />
auth-level = simple | ssl-auth<br />
validity = start hhmm end hhmm on daystring<br />
};<br />
where:<br />
rule-type<br />
Defines the action of the set command. These actions include:<br />
super-user<br />
Grants unlimited access to particular users.<br />
admin-user<br />
Grants read and update privileges to particular users.<br />
reg-user<br />
Grants read privileges to particular users.<br />
public-user<br />
Grants read privileges to all users<br />
protected-items<br />
Protects a subtree, entry, or attribute.<br />
tag<br />
A human-readable name for the access control rule.<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
Defines the users that this rule applies to, with the following possible values:<br />
own-entry<br />
A user’s own entry<br />
user = DN<br />
A user’s distinguished name<br />
role = DN<br />
A role’s distinguished name<br />
user-subtree = <br />
The distinguished name of a user-subtree<br />
group = string<br />
The name of a predefined group of users<br />
subtree<br />
Defines the part of the directory to which the rule applies, with the following<br />
possible values:<br />
6–40 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
entry = <br />
The distinguished name of an individual entry<br />
subtree = <br />
The distinguished name of a user-subtree<br />
attrs<br />
Defines the attributes to which you want to limit access.<br />
You can give the name of an attribute set in place of the attribute name. See<br />
Attribute Sets in the chapter “Schema Definition” for more information.<br />
perms<br />
Applies permissions to a particular rule type, with these possible values:<br />
read<br />
Permits the user to read the defined attributes or entries. The other<br />
permission levels all include read access.<br />
add<br />
Permits the user to add new defined attributes or entries<br />
remove<br />
Permits the user to delete the defined attributes or entries<br />
modify<br />
Permits the user to modify the defined attributes or entries<br />
modify-dn<br />
Permits the user to modify the DN the defined attributes or entries<br />
rename<br />
Permits the user to rename the defined attributes or entries<br />
all<br />
Permits the user to carry out all operations on the defined attributes or<br />
entries<br />
auth-level<br />
Defines the authentication level at which the user must bind. The following<br />
table lists the available values:<br />
simple<br />
(Default) The user must bind using simple authentication<br />
ssl-auth<br />
The user must bind using SSL authentication<br />
validity<br />
Defines the times when the rule applies. The following table lists the<br />
available values:<br />
start<br />
Is the time at which this rule becomes valid<br />
end<br />
Is the time at which this rule is no longer valid<br />
on<br />
Is a string that defines the days on which this rule is valid. Each day of<br />
the week is represented by a number, starting with 1 for Monday. For<br />
example, 45 represents Thursday and Friday. The default is any time.<br />
Security 6–41
Static Access Controls<br />
Defining Superusers<br />
Superusers have unrestricted read and update access to all parts of the DSA. Add<br />
users to the list of superusers either as single users, groups of users, roles, or all<br />
users in a specified subtree.<br />
The command has the format:<br />
set super-user tag = {<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
[auth-level = simple | ssl-auth ]<br />
[validity = start hhmm end hhmm on daystring ]<br />
};<br />
where:<br />
tag<br />
(Optional) Is the name you define for this rule<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
Identifies the user, group, or subtree of users that is to have superuser access<br />
auth-level<br />
(Optional) The authentication level at which the listed users must bind<br />
validity<br />
(Optional) Is the days and times on which this rule is valid<br />
Example: Adding<br />
Superusers<br />
Example: Being a<br />
Superuser of One’s<br />
Own Entry<br />
The following command defines a single user with superuser privileges across<br />
the domain of the Democorp DSA:<br />
set super-user “dsa-manager” = {<br />
user = <br />
};<br />
The following command gives all users in the domain of this DSA superuser<br />
privileges on their own entry from 0800 hours to 1800 hours on Monday to Friday:<br />
set super-user “self” = { own-entry<br />
validity = ( start 0800 end 1800 on 12345 ) };<br />
When you include this command in an access.dxc file that multiple DSAs<br />
source, all users in the domains of those DSAs will have superuser privileges on<br />
their own entries.<br />
This is the only type of superuser rule that does not grant the user access to all<br />
parts of the DSA,<br />
6–42 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
Defining Administrative Users<br />
Within a specified subtree, you can assign administrator authority to users.<br />
Administrative users have read and update privileges over a specified<br />
administrative scope. This scope is a subtree, entry, or designated attributes in an<br />
entry or subtree. The administrative user can view and update protected items<br />
within the administrative scope.<br />
Add users to the list of administrative users either as single users, groups of<br />
users, roles, or all users in a specified subtree.<br />
Note: Administrative user definitions are effective only when you enable access<br />
controls. An administrator with access to only selected attributes within a subtree<br />
cannot add or remove entries.<br />
The command has the format:<br />
set admin-user tag = {<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
subtree = DN<br />
[ attrs = attr1 [, attr2 …] ]<br />
[ perms = perm1 [, perm2 ...] ]<br />
[ auth-level = simple | ssl-auth ]<br />
[ validity = start hhmm end hhmm on daystring ]<br />
};<br />
where:<br />
tag<br />
(Optional) Is the name you define for this rule<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
Identifies the user, group, or subtree of users that are to be administrative<br />
users<br />
subtree<br />
Contains a list of the distinguished names of one or more subtrees that the<br />
listed users can administer<br />
attrs<br />
(Optional) Restricts update permissions to only those attributes listed. Users<br />
cannot delete any entry if attributes are listed here.<br />
perms<br />
(Optional) Contains the level of permission that this rule grants to the listed<br />
users over the listed subtree<br />
auth-level<br />
(Optional) The authentication level at which the listed users must bind<br />
validity<br />
(Optional) Is the days and times on which this rule is valid<br />
Security 6–43
Static Access Controls<br />
Example: Adding<br />
Administrative Users<br />
Example: Allowing<br />
Update Privileges on<br />
a Role<br />
Example: Allowing<br />
Update Privileges on<br />
a Single Attribute<br />
Example: Allowing<br />
Users Update<br />
Privileges on Specific<br />
Attributes in Their<br />
Own Entry<br />
In the following example, there is one specified subtree: AU/DemoCorp. This<br />
subtree has administrators defined by the group admin-user-group.<br />
set admin-user “administrators” = {<br />
group = “admin-user-group”<br />
subtree = <br />
};<br />
In the following example, all users in the role project-leader-group have read and<br />
update privileges on the entry AU/DemoCorp/R&D/Technology SIG if they<br />
bind to the DSA using SSL authentication.<br />
set admin-user “project-leaders” = {<br />
role = <br />
entry = <br />
auth-level = ssl-auth<br />
};<br />
In the following example, all users in the group pabx-mgmt-group have update<br />
privileges on the attribute workPhone in the subtree AU/Democorp/R&D.<br />
set admin-user “work-phone” = {<br />
group = “pabx-mgmt-group”<br />
subtree = <br />
attrs = workPhone<br />
};<br />
In the following example, all users in the subtree AU/Democorp/R&D have<br />
update privileges on the attributes workPhone and description in their own entry.<br />
set admin-user “my-own-work-details” = {<br />
own-entry<br />
subtree = <br />
attrs = workPhone, description<br />
};<br />
6–44 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
Defining Registered Users<br />
In a specified subtree, you can assign users the authority of a registered user.<br />
Registered users have read privileges over a specified scope: a subtree, entry, or<br />
the designated attributes in an entry or subtree. Protected items in the scope are<br />
invisible.<br />
Note: Registered user definitions are effective only when you enable access<br />
controls.<br />
The command has the format:<br />
set reg-user tag = {<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
subtree = DN<br />
[ attrs = attr1 [, attr2 …] ]<br />
[ perms = perm1 [, perm2 ...] ]<br />
[ auth-level = simple | ssl-auth ]<br />
[ validity = start hhmm end hhmm on daystring ]<br />
};<br />
where:<br />
tag<br />
(Optional) Is the name you define for this rule<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
Contains a list of the distinguished names of the users, groups of users, roles,<br />
or all users in a specified subtree that are to be registered users<br />
subtree<br />
Contains a list of the distinguished names of one or more subtrees that the<br />
listed users can read<br />
attrs<br />
(Optional) Contains a list of attributes for which the listed users have the<br />
permissions listed in the perms parameter.<br />
perms<br />
(Optional) Contains the level of permission that this rule grants to the listed<br />
users over the listed attributes<br />
auth-level<br />
(Optional) The authentication level at which the listed users must bind<br />
validity<br />
(Optional) Is the days and times on which this rule is valid<br />
Example: Adding<br />
Registered Users<br />
In the following example, all the users in the subtree AU/DemoCorp/R&D can<br />
read the subtree AU/DemoCorp.<br />
set reg-user “R&D-Users”= {<br />
user-subtree = <br />
subtree = <br />
};<br />
Security 6–45
Static Access Controls<br />
Example: Allowing<br />
Read Privileges on an<br />
Entry<br />
Example: Allowing<br />
Read and Modify<br />
Privileges on a<br />
Number of Attributes<br />
Example: Allowing<br />
Users Read Privileges<br />
on Particular<br />
Attributes in Their<br />
Own Entry<br />
In the following example, all users in the group staff have read privileges on the<br />
entry AU/DemoCorp.<br />
set reg-user “democorp-staff” = {<br />
group = “staff”<br />
entry = <br />
};<br />
In this example, all DemoCorp users can browse all entries in the subtree<br />
DemoCorp; however, when they read or search for an entry in the subtree, only<br />
those attributes that you declare are visible. The users also have modify<br />
privileges on the listed attributes for all entries in the subtree.<br />
set reg-user “self-view” = {<br />
user-subtree = <br />
subtree = <br />
attrs = telephoneNumber, commonName, surname, title, mhsORAddresses, dcEmail<br />
perms = modify<br />
};<br />
The following example lets any user in the subtree AU/DemoCorp view only<br />
the selected attributes in their entry.<br />
set reg-user = {<br />
own-entry<br />
subtree = <br />
attrs = telephoneNumber, commonName, surname, title, mhsORAddresses, odEmail<br />
};<br />
This differs from the previous example where all users in the subtree<br />
DemoCorp can view all entries in that subtree.<br />
6–46 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
Defining Public Users<br />
You can make specific subtrees available to public (anonymous) users.<br />
Public users have read-only access to all entries and attributes within the<br />
specified public range. This range is a subtree, entry, or the designated attributes<br />
in an entry or subtree.<br />
Any permission granted to public users is also automatically granted to<br />
authenticated users. Protected items within the specified public range are<br />
invisible to public users.<br />
Note: Public user definitions are effective only when you enable access controls.<br />
Public ranges are made available to public users with the following command:<br />
set public-user tag = {<br />
subtree = DN<br />
[ attrs = attr1 [, attr2 …] ]<br />
[ perms = perm1 [, perm2 ...] ]<br />
[ validity = start hhmm end hhmm on daystring ]<br />
};<br />
where:<br />
tag<br />
(Optional) Is the name you define for this rule<br />
subtree<br />
Contains a list of the distinguished names of one or more subtrees that all<br />
users can read<br />
attrs<br />
(Optional) Contains a list of attributes for which all users have the<br />
permissions listed in the perms parameter.<br />
perms<br />
(Optional) Contains the level of permission that this rule grants to all users<br />
over the listed attributes<br />
validity<br />
(Optional) Is the days and times on which this rule is valid<br />
Example: Adding a<br />
Public Subtree<br />
In the following example, all users can view the name, telephone number, and<br />
X.400 mail addresses in the subtree AU/DemoCorp/Phone List. The access<br />
control rule is tagged with the name public-attr.<br />
set public-user “public-attr” = {<br />
subtree = <br />
attrs = telephoneNumber, commonName, surname, mhsORAddresses<br />
};<br />
Security 6–47
Static Access Controls<br />
Protecting Items<br />
You can protect specific subtrees, entries, or particular attributes in a subtree or<br />
entry. For a protected item:<br />
■<br />
■<br />
■<br />
Superusers have read and update privileges<br />
Administrative users have read and update privileges if the subtree is in the<br />
user’s administrative area<br />
Other users do not see the items<br />
Some limitations on this command:<br />
■<br />
■<br />
■<br />
This command does not protect naming attributes.<br />
If you rename a protected subtree or entry, or any of its parents, the<br />
permissions rule no longer protects the item.<br />
Protected item definitions are effective only when you enable access controls.<br />
The command that protects items has the following format:<br />
set protected-items tag = {<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
subtree = DN<br />
[ attrs = attr1 [, attr2 …] ]<br />
[ perms = perm1 [, perm2 ...] ]<br />
[ validity = start hhmm end hhmm on daystring ]<br />
};<br />
where:<br />
tag<br />
(Optional) Is the name you define for this rule<br />
own-entry | user = DN | role = DN | user-subtree = DN | group = string<br />
Contains a list of the distinguished names of the users, groups of users, roles,<br />
or all users in a specified subtree that are to be registered users<br />
subtree<br />
Contains a list of the distinguished names of one or more subtrees that the<br />
listed users can read<br />
attrs<br />
(Optional) Contains a list of attributes for which the listed users have the<br />
permissions listed in the perms parameter<br />
perms<br />
(Optional) Contains the level of permission that this rule denies to the listed<br />
users over the listed attributes.<br />
Unlike the other access control commands, any permissions listed in the set<br />
protected-items command are denied.<br />
validity<br />
Is the days and times on which this rule is valid<br />
6–48 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Static Access Controls<br />
Protecting Entries and Subtrees<br />
There is a subtle difference between protecting entries and protecting subtrees.<br />
When you protect an entry, neither a registered, nor public user can read it. It<br />
can, however, appear in a list result if the user can access the parent. This occurs<br />
because the protected entry may have subordinates that are visible to the user.<br />
If the same entry has protection as a subtree, a registered or public user cannot<br />
read it, and it does not appear in a list result as a subordinate entry.<br />
Protecting Passwords<br />
Protecting a password makes the password attribute invisible to unauthorized<br />
users. Because authentication requires the name of an entry, and that entry must<br />
contain a password, hiding the password makes login entries indistinguishable<br />
from other entries.<br />
Examples of set protected-items Commands<br />
Example: Protecting<br />
a Subtree<br />
Example: Protecting<br />
an Entry<br />
Example: Protecting<br />
Attributes<br />
Protecting a subtree from registered users also makes it invisible to public<br />
users, as described in the section Hierarchy of Rules.<br />
set protected-items “hide-finance-from-employees” = {<br />
group = “employees”<br />
subtree = <br />
};<br />
You could use the following rule to hide the existence of some management<br />
information about a DSA definition stored within the directory:<br />
set protected-items “hide-schema-from-employees” = {<br />
group = “employees”<br />
entry = <br />
};<br />
In this example, all entries in the subtree AU/DemoCorp have protection for<br />
their homePhone and password attributes (if they have these attributes).<br />
However, these attributes are visible to superusers and administrative users in<br />
their scope.<br />
set protected-items “hide-passwords-and-home-phone” = {<br />
subtree = <br />
attrs = homePhone, userPassword<br />
};<br />
Security 6–49
Static Access Controls<br />
Example: Giving a<br />
User Permission to<br />
Modify All Attributes<br />
in Their Own Entry<br />
Except "Role"<br />
In this example, the reg-user rule gives the user permission to modify all<br />
attributes in their own entry, and the protected-items rule denies the user<br />
modification rights to the role attribute in the user’s own entry if it has a higher<br />
precedence than the reg-user rule.<br />
set reg-user = {<br />
own-entry<br />
subtree = <br />
perms = modify<br />
};<br />
set protected-items = {<br />
own-entry<br />
subtree = <br />
attrs = role<br />
perms = modify<br />
};<br />
Without the "perms = modify" in the protected-items rule the user would be<br />
denied all access to the role attribute (including read access).<br />
Example: Allowing<br />
users to view a whole<br />
entry and modify<br />
some attributes<br />
A common task with access controls is to provide update access to most<br />
attributes within an entry but to prevent the update of a small number of<br />
attributes. This problem is more complex if the list of attributes that can be<br />
updated can grow - for example, as more attributes are added to the entry.<br />
■<br />
■<br />
■<br />
Providing "reg-user" access to the entry will give read-only access.<br />
Providing "admin-user" access will give update access.<br />
Setting "protected-items" on some attributes will prevent updates, but not<br />
by users with "admin-user" rights. It will also prevent reads by users with<br />
"public-user" or "reg-user" rights.<br />
A solution to this problem is to use the optional permissions in the access<br />
control rules. The following access rule will allow all users in the subtree to<br />
modify all attributes in their own entry.<br />
set reg-user = {<br />
own-entry<br />
subtree = <br />
perms = modify<br />
};<br />
To prevent update access to some of these attributes, use:<br />
set protected-items = {<br />
own-entry<br />
subtree = <br />
attrs = attr1, attr2, ...<br />
perms = modify<br />
};<br />
This prevents the user modifying the attributes listed, but it does not prevent<br />
read access. This is because the only permission denied is modify.<br />
6–50 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Dynamic Access Controls<br />
Dynamic Access Controls<br />
Dynamic access controls enable run-time management of access controls. This is<br />
useful for automated provisioning systems in ISP environments, and where the<br />
directory is used as an authorization engine.<br />
Dynamic access controls specify a subject (an identity or a role), a permission,<br />
and a list of attributes that are the target of the control. They also contain a tag<br />
that is transparent to DXserver. Adding a rule to the dxDynamicAccess attribute<br />
in an entry creates the access control rule. The subtree in which dynamic access<br />
controls are active is the local naming context; therefore, only attributes stored<br />
locally are affected by access control decisions.<br />
dxDynamicAccess is an operational attribute; it is not controlled by schema. Any<br />
user can add, delete, or modify a rule, provided they have write access over the<br />
subtree defined by the entry containing the dxDynamicAccess attribute, and the<br />
privilege in the attribute is in the user’s power.<br />
Important: In the configuration files, make sure that the database is defined (using "set<br />
database=") before the directory reads the "set dynamic-accesscontrol=true"<br />
directive.<br />
This is because the "set dynamic-access-control=true" directive causes the directory to<br />
perform a search on the database, so it needs to know the database name.<br />
Note: Dynamic access controls are limited to local DSAs, which means that they<br />
cannot be used in a distributed environment. This even applies to a router DSA<br />
on the local computer.<br />
Dynamic rules apply downwards from the entry in the DIT where the<br />
dxDynamicAccess attribute is stored.<br />
Enabling and Disabling Dynamic Access Controls<br />
To enable dynamic access controls:<br />
1. Enable access controls:<br />
set access-controls = true;<br />
2. Enable dynamic access controls:<br />
set dynamic-access-control = true;<br />
To disable dynamic access controls, enter the following command:<br />
set dynamic-access-control = false;<br />
Security 6–51
Dynamic Access Controls<br />
Dynamic Access Control Rules<br />
The rules governing dynamic access controls take the following form:<br />
{all| roles | user } {read | write | deny} …<br />
where tag is an identifier used for documentation purposes, dn is a distinguished<br />
name, and attr is an attribute.<br />
When creating rules, remember that a rule specified for a particular user prevails<br />
over one specified for a role, and that both prevail over all. Also, when creating<br />
the rule, the user or role need not exist.<br />
Example: Letting all<br />
read one attribute<br />
Example: Letting all<br />
read all attributes<br />
Example: Denying<br />
permission for roles to<br />
read an attribute<br />
Example: Letting one<br />
user write to an<br />
attribute<br />
The following command gives everyone permission to read the commonName<br />
attribute. The tag Joe is to help you with maintenance and problem analysis;<br />
DXserver does not interpret it.<br />
Joe all read commonName<br />
The following command gives everyone permission to read all attributes:<br />
Joe all read all<br />
The following command denies the roles of CEO and AdminFinance within<br />
Democorp access to the ssoHelicopter attribute:<br />
Joe role cn=ceo,o=Democorp deny ssoHelicopter<br />
The following command lets a user with the common name Craig write to the<br />
ssoHelicopter attribute:<br />
Joe user cn=Craig,o=Democorp write ssoHelicopter<br />
6–52 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Groups, Roles, and Proxies<br />
Groups, Roles, and Proxies<br />
This section describes how groups, roles, and proxies work.<br />
Defining Groups of Users<br />
You can define groups of users to make it easier to manage those users. Define<br />
groups such that you can use it in other access control commands.<br />
Note: Group definitions are effective only when you enable access controls.<br />
The command has the format:<br />
set group tag = {<br />
users = DN1 [, DN2 …]<br />
name = GroupName<br />
};<br />
where:<br />
users<br />
Is a list of the distinguished names of one or more users in the new group<br />
name<br />
Is the name you give to the group.<br />
Example: Forming a<br />
Group<br />
The following command defines a group containing two users. The group is<br />
named admin-user-group, suggesting that the users have administrative user<br />
privileges.<br />
set group = {<br />
name = "admin-user-group"<br />
users = ,<br />
<br />
};<br />
Security 6–53
Groups, Roles, and Proxies<br />
Role-Based Access Controls<br />
When access control rules are applied to a role, they are known as role-based<br />
access controls.<br />
A role is a directory entry that can be associated with user entries. These<br />
associated user entries are member entries.<br />
A role may contain any number of members. This can be useful in a large<br />
distributed directory environment where people change their roles frequently,<br />
and when the directory is to be used as an authorization engine.<br />
Both static and dynamic rules support roles.<br />
Roles are maintained in a subtree of the directory information tree (DIT), using<br />
the object class groupOfNames. You can control access to the role subtree using<br />
access controls.<br />
How Role-Based Access Controls Work<br />
When a user binds to DXserver, the user’s credentials are verified. A search is<br />
initiated for the user’s distinguished name in the member attribute of any entry<br />
with the object class groupOfNames. The name(s) returned by this search are<br />
stored as the roles pertaining to the connection, and then used in access control<br />
decisions.<br />
Note: Role-based access controls are limited to local DSAs, which means that<br />
they cannot be used in a distributed environment. This even applies to a router<br />
DSA on the local computer.<br />
Enabling and Disabling Role-Based Access Controls<br />
To add a user entry to a role, enter the distinguished name of the user entry to<br />
the role entry, as an attribute value of the member attribute type.<br />
To activate role-based access controls, enter the following commands:<br />
set role-subtree = ;<br />
set use-roles = true;<br />
where dn is the distinguished name of the subtree used to store the roles.<br />
To disable role-based access controls, enter the following command:<br />
set use-roles = false;<br />
6–54 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Groups, Roles, and Proxies<br />
Example: Activating<br />
role-based access<br />
control<br />
In the following example, when a user binds to DXserver, DXserver searches<br />
the member attribute of the entries with oc in the groupofNames in the subtree<br />
c=au, o=Democorp, ou=Roles for that user’s distinguished name. The entries<br />
which contain that member identify the roles of the member.<br />
To activate role-based access controls:<br />
set role-subtree = ;<br />
set use-roles = true;<br />
Example: Add a new<br />
role with two users<br />
This example shows how to add the new role AdminFinance with the two<br />
members, Noelene Correa and Linda Deacon.<br />
add-entry-req<br />
entry = <br />
<br />
<br />
<br />
contents = {<br />
(objectClass groupOfNames )<br />
(member ,<br />
)<br />
Security 6–55
Groups, Roles, and Proxies<br />
Secure Proxies<br />
The secure proxy feature lets an authorized user (or process) impersonate a user<br />
or role for whom it has responsibility, and bind to DXserver to elicit access<br />
control decisions (for example, when the directory is used as an authorization<br />
engine, such as a web server).<br />
The proxy must bind to DXserver using certificate-based authentication. Those<br />
users permitted to proxy (impersonate someone else) are identified to DXserver<br />
as a list of distinguished names held in the trust-sasl-proxy list.<br />
When using a proxy, the impersonating user can never obtain more power than<br />
they already have. In other words, in assuming the identity of another user, they<br />
may not obtain all the privileges of that user.<br />
Once bound to DXserver, the proxy may change identity by changing the value<br />
of dxProxyUser in the entry cn=roles to the distinguished name of the new<br />
identity. This has the effect of evaluating the roles for the new identity. An<br />
exception is, where the proxy also changes the value of dxProxyRole in cn=roles.<br />
In this case, roles are taken directly from the attribute value, not by accessing role<br />
entries in the directory.<br />
The entry cn=roles is a magic entry, and does not appear in the DIT.<br />
To permit the proxy to impersonate users not in the directory (external users),<br />
the proxy replaces the value of the dxProxyUser attribute in the magic entry with<br />
the distinguished name of the new identity, and at the same time replaces the<br />
value of the dxProxyRole attribute with the roles of the new identity. In this<br />
instance, the roles provided in the replace operation are used directly, provided<br />
set ssl-auth-bypass-entry-check = true;<br />
Activate Secure Proxy<br />
To activate proxy access, enter the following command:<br />
set trust-sasl-proxy = , …<br />
where dn is the distinguished name of a trusted proxy. The proxy must bind<br />
using SASL/EXTERNAL over SSL.<br />
6–56 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Groups, Roles, and Proxies<br />
Access Controls and Aliases<br />
When a user binds with a user name and password, the system checks the<br />
password supplied with the bind against the password in the database for the<br />
specified user. When the user name is an alias, the system checks the password<br />
against the password in the entry to which the alias points, but the user name<br />
associated with the bind is the alias name. This means that a user can bind with<br />
more than one user name, and each user name can have different access controls<br />
associated with it.<br />
Security 6–57
Access-Controlled Routing<br />
Access-Controlled Routing<br />
This section describes how access controls work in a distributed environment. If<br />
the DSA determines that it needs to chain or multicast an operation to a remote<br />
DSA but the area controlled by that DSA is completely invisible because of static<br />
access controls, the DSA refuses to route the request to the remote DSA.<br />
By default, a DSA prevents the forwarding of a request to another DSA<br />
according to its static access controls.<br />
To permit the forwarding of a request regardless of access control constraints, set<br />
the no-routing-ac DSA flag in the configuration file (.dxc) in the knowledge<br />
directory. This lets a DSA pass a request to another DSA even when the user’s<br />
access controls on the local DSA do not permit access to the particular entry or<br />
subtree in the request.<br />
For example, to let a DemoCorp DSA pass a request to a UNSPSC DSA<br />
regardless of the user's local static access control constraints, you must set the<br />
DSA flags in UNSPSC’s knowledge configuration:<br />
set dsa UNSPSC=<br />
…<br />
dsa-flags=no-routing-ac<br />
…<br />
DemoCorp<br />
DSA<br />
UNSPSC<br />
DSA<br />
6–58 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
7 Replication<br />
This chapter describes the replication schemes you can use with <strong>eTrust</strong> <strong>Directory</strong>.<br />
In a replicated directory, information stored in one part of the directory is also<br />
stored elsewhere as one or more copies.<br />
Replication is deployed for one or both of the following reasons:<br />
■<br />
■<br />
Improved availability—Replication can make a system more robust by<br />
enabling the directory on one server to fail over to an alternative server.<br />
Applications can continue working as there are alternate DSAs/servers in<br />
the network which can serve the same parts of the namespace.<br />
Improved performance—Replication can place frequently accessed<br />
information closer to where is it needed, which improves response times.<br />
Replication involves copying data, and whenever data is copied, you must<br />
ensure that the copies are synchronized. Developing and maintaining replicated<br />
systems can be expensive, and you should weigh these costs against the benefits<br />
of performance and recovery in the event of failure.<br />
Replication 7–1
Replication Concepts<br />
Replication Concepts<br />
This section describes some important concepts about replication. These concepts<br />
are used in explanations of the three different types of replication that you use<br />
with <strong>eTrust</strong> <strong>Directory</strong>.<br />
Compare Distribution and Replication<br />
Distribution differs from replication.<br />
In a distributed directory, each piece of data is stored on only one server. The<br />
directory information tree (DIT) it split and each section is stored a different<br />
server.<br />
In a replicated directory, each piece of data is held on more than one server. The<br />
entire DIT is stored in more than one place.<br />
You can use both replication and distribution in the same system. The DIT is split<br />
and stored in many different servers, and at least some of those sections of the<br />
DIT are also copied and stored in more than one place.<br />
Compare Multimaster and Master–Slave Replication<br />
In a system with multimaster replication, all DSAs are masters. Data is copied<br />
between all DSAs. The master DSAs are also called peer DSAs.<br />
In a system with master–slave replication, data is always copied in one direction,<br />
from a master DSA to one or more slave DSAs.<br />
Read and Update<br />
Requests<br />
Read and Update<br />
Requests<br />
Read and Update<br />
Requests<br />
Master DSA<br />
Updates<br />
Master DSA<br />
Master DSA<br />
Updates Updates<br />
Update Update Update<br />
Master DSA<br />
Slave DSA Slave DSA Slave DSA<br />
Read and Update<br />
Requests<br />
Multimaster Replication<br />
Master-Slave Replication<br />
7–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Replication Concepts<br />
Compare Real-Time and Write-Behind Replication<br />
In a system with real-time replication, data is replicated to other servers as soon as<br />
an update request is received from a client.. The update confirmation is not sent<br />
to the client until each of the slave or peer DSAs has sent an update confirmation<br />
message.<br />
In a system with write-behind replication, data is replicated periodically,<br />
independent of the client update. The update confirmation is sent as soon as the<br />
operation completes locally. Write-behind replication can in these two ways:<br />
■<br />
■<br />
On-demand write-behind replication—The updates are transferred<br />
immediately after they occur<br />
Scheduled write-behind replication—The updates are transferred according<br />
to a periodic schedule.<br />
Latency is the time for which the shadow servers are out-of-date with respect to a<br />
master server. For many applications, such as an authentication service, any<br />
latency is unacceptable. To overcome the problem of latency, use a real-time<br />
replication system rather than write-behind replication.<br />
Compare Replay-Based and State-Based Replication<br />
In a replay-based system, every update applied to a master is subsequently<br />
applied to the slaves.<br />
This system is simple and can operate in real time, but it is not robust when<br />
something goes wrong with the replay or when conflicting updates occurred in a<br />
system with many masters.<br />
In a state-based system, a difference is calculated between the current state of the<br />
master system and some previous state of the slave system. The calculated<br />
difference between these two states is then sent across to the slave. If conflict<br />
resolution is built in, then this mechanism can also reconcile a system with many<br />
masters.<br />
A state-based system deals very efficiently with repeated updates. For example,<br />
even if an entry were modified 100 times since the last update, only one update is<br />
transferred. In a replay-based system, 100 updates would be sent. However,<br />
state-based systems are generally not designed to operate in real-time.<br />
Replication 7–3
Replication Concepts<br />
The following table summarizes the two schemes:<br />
Replication Type Advantages Disadvantages Example<br />
Replay-based<br />
Simple<br />
Can be real-time<br />
Poor recoverability<br />
Multiwrite<br />
State-based<br />
Efficient<br />
High recoverability<br />
Cannot be real-time<br />
DISP<br />
Three Types of Replication Used with <strong>eTrust</strong> <strong>Directory</strong><br />
<strong>eTrust</strong> <strong>Directory</strong> supports three standards-based mechanisms of replication:<br />
Replication<br />
Scheme<br />
Multiwrite<br />
DISP<br />
DXtools<br />
Characteristics<br />
Multimaster<br />
Real-time<br />
Simple configuration<br />
High performance<br />
Replay-based<br />
Master–slave<br />
Write-behind<br />
High flexibility<br />
State-based<br />
Batch mode<br />
High traceability<br />
Most Suitable Deployment<br />
Where network links, computers, and<br />
power supplies are reliable<br />
Where interoperability is required with<br />
another vendor’s X.500 directory<br />
Where synchronization is required between<br />
two directories or with a legacy system<br />
Keep System Clocks Synchronized<br />
For any replication system, synchronize the operating system clocks regularly. If<br />
the system clocks are not set at the same time, replication will not work as you<br />
expect, because conflict resolution is time-based—the most recent update wins.<br />
7–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Multiwrite Replication<br />
Multiwrite replication is a good choice for a system that includes applications<br />
that require real-time replication.<br />
Multiwrite replication uses the fast, efficient <strong>Directory</strong> System Protocol (DSP) to<br />
chain updates between servers in real time.<br />
To use multiwrite replication successfully, your network links, computers, and<br />
power supplies should be reliable. Treat system crashes and unreliable networks<br />
as disaster recovery scenarios that involve reconciliation between databases<br />
using DXtools.<br />
You can configure DSAs into multiwrite groups. When an update is applied to a<br />
DSA in a group, it passes these updates on to the other DSAs in the group.<br />
How Multiwrite Replication Works<br />
Multiwrite replication uses DSP chaining to apply updates to all replication peers<br />
in real-time. When a client makes an update request, that update is applied<br />
immediately to the local DSA, and then to all other DSAs. The client receives the<br />
confirmation response only after all DSAs have successfully applied the update.<br />
The following diagram shows these steps:<br />
1. Write to self—A client sends an update request to DSA1, and this DSA<br />
applies the update to itself.<br />
2. Write to peers—If the local update succeeds, DSA1 sends the request to its<br />
peer DSAs. If these updates succeed, the peers send confirmations to DSA1.<br />
3. Send response to client—When DSA1 has received confirmation from each<br />
peer, it sends the confirmation response to the client.<br />
2<br />
2<br />
1<br />
Client<br />
3<br />
Update Request<br />
Update Confirmation<br />
DSA 1<br />
Database<br />
1<br />
2<br />
2<br />
DSA 2<br />
Database<br />
2<br />
DSA 3<br />
1 1 2 2 2 2<br />
Database<br />
3<br />
The Three Phases of Multiwrite Replication<br />
When a multiwrite update fails, the system must be recovered. See the sections<br />
Replication 7–5
Multiwrite Replication<br />
Recovering a Multiwrite System Using Queues and Recovering a Multiwrite<br />
System Using DISP.<br />
Multiwrite Can Work Asynchronously<br />
Multiwrite is usually synchronous: an update operation is not confirmed until all<br />
the multiwrite peers have applied it. This provides for load-sharing and failover.<br />
However, this synchronous behavior may not be desirable if peer DSAs are<br />
connected by slow links, or if latency is not an issue.<br />
If a DSA is set to multiwrite asynchronously, when other DSAs multiwrite to this<br />
DSA, they will not wait for a confirmation before they to hold the confirmation<br />
on account of this DSA. The confirmation is returned once all the multiwrite<br />
peers not marked multi-write-async have applied the update.<br />
To set a DSA to multiwrite asynchronously, add the DSA flag multi-write-async to<br />
the DSA’s knowledge.<br />
7–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
How Multiwrite Groups Work<br />
In a system that includes at least one slow network link between DSAs, delays<br />
caused by this slow link can slow down the whole multiwrite system. Multiwrite<br />
groups let you avoid delays due to a slow network link.<br />
How A Slow Network Link Causes Delays<br />
A single slow link can delay a multiwrite system because the DSA making the<br />
update must wait for confirmation from all DSAs before sending confirmation<br />
back to the client. This can cause a bottleneck if many updates are made each<br />
second.<br />
The following diagram shows a multiwrite system in which three of the DSAs<br />
are connected by slow network links. In this system, DSA 1 must wait until it has<br />
received confirmation from these three DSAs before it can send the update<br />
confirmation back to the client. From the client’s point of view, each update takes<br />
much longer than it should.<br />
DSA 2<br />
DSA 3<br />
2<br />
2<br />
Client<br />
1<br />
3<br />
DSA 1 2<br />
DSA 4<br />
2<br />
2<br />
Update Request<br />
Update Confirmation<br />
Slow Network Link<br />
DSA 5<br />
DSA 6<br />
A Multiwrite System with Slow Network Links<br />
Replication 7–7
Multiwrite Replication<br />
How Multiwrite Groups Avoid Bottlenecks<br />
To avoid delays due to slow network connections, you can put the DSAs on each<br />
side of a slow link into separate groups.<br />
Each group has one hub DSA. This is the DSA that will accept multiwrite<br />
requests from DSAs in other groups.<br />
The following diagram shows these steps:<br />
1. Write to self—A client sends an update request to DSA1, and this DSA<br />
applies the update to itself.<br />
2. Write to peers in group—If the local update succeeds, DSA1 sends the<br />
request to its peer DSAs in the same multiwrite group. If these updates<br />
succeed, the peers send confirmations to DSA1.<br />
3. Send response to client—When DSA1 has received confirmation from each<br />
peer in its multiwrite group, it sends the confirmation response to the client.<br />
4. Write to hub DSAs in other multiwrite groups—DSA1 sends the request to<br />
the hub DSAs in each of the other multiwrite groups.<br />
5. Hub DSAs write to peers—Each hub DSA sends the request to the other<br />
DSAs in its group. When each hub DSA has received confirmation from each<br />
peer in its multiwrite group, it sends the confirmation response to the first<br />
DSA. The client confirmation will not be affected by the slow links, because<br />
the updates over these links are asynchronous.<br />
7–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Multiwrite<br />
Group C<br />
5<br />
DSA 9<br />
Multiwrite<br />
Group A<br />
DSA 8<br />
(Hub)<br />
5<br />
DSA 10<br />
DSA 2 DSA 3<br />
4<br />
5<br />
DSA 11<br />
2 2<br />
DSA 1<br />
1<br />
3<br />
4<br />
5<br />
DSA 5<br />
Client<br />
DSA 4<br />
(Hub)<br />
5<br />
DSA 6<br />
Multiwrite<br />
Group B<br />
5<br />
DSA 7<br />
Multiwrite Hub Failover<br />
If an update sent to a hub fails because the hub DSA cannot be reached, then the<br />
DSA tries the next hub in the list.<br />
If all hubs fail, then the update will be queued against the first hub DSA. This<br />
DSA takes care of queuing for the offline DSAs.<br />
Replication 7–9
Multiwrite Replication<br />
Set Up a Multiwrite System<br />
You can set up a multiwrite replication system in many different configurations,<br />
including master–slave, primary-backup, multimaster, or multiwrite groups.<br />
You can also use other DSA flags to support load balancing and query streaming.<br />
Multiwrite replication is simple to implement. Because multiwrite replication is built<br />
into DXserver, you do not need to use a separate product or additional licensing.<br />
Enable Multiwrite Replication<br />
To enable multiwrite replication, do the following:<br />
1. Decide which DSAs will be included in the multiwrite system.<br />
2. Configure these DSAs with the same context prefix.<br />
3. Connect each DSA to a database holding synchronized information.<br />
4. Set each DSA to share the same knowledge information.<br />
5. Add the DSA flag multi-write to the shared knowledge, as follows:<br />
set dsa dsaname = {<br />
...<br />
dsa-flags = multi-write, ...<br />
... };<br />
Note: Place DSA flags after dsp-idle-time and before any trust and link flags.<br />
Set Up a Multiwrite Group<br />
To set up multiwrite groups, do the following:<br />
1. Decide which DSAs will be included in the multiwrite system.<br />
2. Decide how many multiwrite groups you need, and which DSAs will be<br />
grouped together.<br />
3. For each groups of DSAs, choose a hub DSA.<br />
4. Configure all DSAs with the same context prefix.<br />
5. Connect each DSA to a database holding synchronized information.<br />
6. Set each DSA to share the same knowledge information.<br />
7. Add the multi-write DSA flag to the shared knowledge:<br />
set dsa dsaname = {<br />
...<br />
dsa-flags = multi-write, ...<br />
... };<br />
8. In the knowledge for each DSA, define the multiwrite group:<br />
set multi-write-group = group-name<br />
7–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Define the Hub DSA for a Multiwrite Group<br />
To set a DSA as the hub for a multiwrite group, list it first in the list of DSA<br />
knowledge files.<br />
Set the Retry Interval<br />
To define the frequency at which DXserver will attempt to bind to a multiwrite<br />
peer which cannot be contacted:<br />
set multi-write-retry-time = ;<br />
If you don’t set this time, the default value of 60 seconds will be used.<br />
Replication 7–11
Multiwrite Replication<br />
Recovering a Multiwrite System Using Queues<br />
With multiwrite replication, you can choose between two methods of recovery:<br />
queues or DISP. This section describes how queues work.<br />
How Multiwrite Queues Work<br />
Multiwrite DSAs are usually online. If one of the DSAs in the group goes offline,<br />
the update is queued in memory until the DSA becomes available again.<br />
After queuing, a confirmation is sent to the directory client. In effect, multiwrite<br />
converts into a write-behind scheme until the offline DSA becomes available.<br />
Increase the Queue Size<br />
The queue pool has a default size of 200 updates for each peer. To change the<br />
queue pool size, use the following command:<br />
set multi-write-queue = n;<br />
where n is the size of the update queue.<br />
You can gauge the required size from, for example, the size of the updates in<br />
your LDIF file.<br />
View the Size of a Multiwrite Queue<br />
To see the current size of the multiwrite queue, use the following command:<br />
get dsp;<br />
Here is a sample of the output from this command:<br />
max-dsp-ops = 100<br />
local-prefix =<br />
<br />
<br />
<br />
<br />
local-dsa<br />
= dsa-1<br />
multi-chaining<br />
= TRUE<br />
always-chain-down = FALSE<br />
multi-write-disp-recovery = FALSE<br />
multi-write-queue = 200<br />
...<br />
7–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Multiwrite Queue Alarms<br />
While a peer DSA is offline, new updates are queued and, periodically, an<br />
attempt is made to connect to the offline DSA.<br />
When the peer DSA comes back online, the queued requests are sent in the order<br />
that they are processed locally. Consequently, multiwrite copes well with a DSA<br />
that is offline for a short period of time.<br />
However, if the peer DSA remains offline for an extended period, the multiwrite<br />
queues build up. Alarms are raised at 60%, 70%, 80%, 90%, and 100% of queue<br />
capacity, and written to the alarm log.<br />
If the queue becomes full, DXserver ignores the unavailable DSA. It discards all<br />
the queued requests for the peer and drops the peer from the multiwrite set. You<br />
must then resynchronize the databases and restart the DSAs.<br />
If multiwrite has occurred, the get dsp command returns one of the following<br />
statuses:<br />
Status<br />
Failed<br />
Recovering<br />
OK<br />
Description<br />
Indicates that the multiwrite peer is not responding to an update.<br />
Updates for that server are held in the multiwrite queue until the<br />
server responds. The queue is retained until the multiwrite queue<br />
size is exceeded.<br />
Indicates that the multiwrite peer has become available and still<br />
has old updates in its queue.<br />
Is the normal multiwrite server status.<br />
Replication 7–13
Multiwrite Replication<br />
Recovering a Multiwrite System Using DISP<br />
With multiwrite replication, you can choose between two methods of recovery:<br />
queues or DISP. This section describes how DISP recovery works with multiwrite<br />
replication.<br />
Enabling DISP recovery generally avoids manual resynchronization of the<br />
databases.<br />
DISP recovery works in concert with multiwrite by handling all the recovery. In<br />
effect, fast multiwrite is used during uptime and DISP is only used for recovery<br />
after a downtime.<br />
DISP recovery has the following features:<br />
Database tables<br />
All information is derived from database tables instead of in-memory<br />
queues. This means that recovery can survive restarts of a master (whereas<br />
you can lose the in-memory queues).<br />
State-based<br />
Resynchronization uses efficient state-based deltas. This is usually superior<br />
to replay-based recovery.<br />
Reconciliation<br />
The DISP processing supports automatic conflict resolution using a last write<br />
wins rule. Managing conflicts is often a problem for replay-based systems<br />
because the order of updates from different masters can be critical.<br />
Important! If you configure multiwrite DISP recovery, you should specify the ssl-auth<br />
authentication level only if you have set up SSL certificates for the DSAs in the<br />
multiwrite group. This is because DISP recovery uses the highest available<br />
authentication level.<br />
Note: Multiwrite–DISP recovery cannot be used where more than one DSA is<br />
attached to the same database.<br />
7–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Enable Multiwrite-DISP<br />
To turn on multiwrite with DISP recovery, use the following command:<br />
set multi-write-disp-recovery = TRUE;<br />
The effect of turning on this flag is to disable offline multiwrite queuing, so that<br />
when a DSA cannot be contacted, it is immediately dropped from the multiwrite<br />
set. However, DISP periodically probes the unavailable DSA.<br />
When the unavailable DSA comes online, the following occurs:<br />
1. The multiwrite queue is enabled.<br />
2. DISP performs the resynchronization (by sending a delta for the period in<br />
which the DSA was offline). While this is occurring, any updates are queued.<br />
3. When the DISP update completes, the multiwrite queue is replayed to the<br />
new DSA.<br />
4. Multiwrite operation resumes.<br />
Note: There are no explicit DISP agreements—all resynchronization and<br />
reconciliation is automatic.<br />
Queueing Multiwrite-DISP<br />
If the following configuration flag is set to true, a multiwrite master will only<br />
start DISP recovery after it has been down or its multiwrite queues had reached<br />
their limits:<br />
multi-write-disp-queue = <br />
In all other cases it replays its queue content to any peer that was unavailable for<br />
a while.<br />
Consistency During Recovery<br />
The following setting guarantees consistency during recovery:<br />
disable-non-peer-binds = <br />
If a DSA goes offline in a multiwrite DISP scenario, and this is set to true, only<br />
binds from multiwrite peers are allowed. This stops the recovering DSA from<br />
receiving non-peer (client, relay, router, or chained) requests that may provide<br />
inconsistent results.<br />
When the DSA has been synchronized (get dsp; or snmp shows multiwrite<br />
queues ok) then this setting can be set back to false. The DSA will accept binds<br />
after a few minutes.<br />
Replication 7–15
Multiwrite Replication<br />
Granularity of DISP Reconciliation<br />
When DISP resynchronization starts it propagates all changes to the DSA since<br />
the last successful multiwrite update.<br />
In a multimaster system, it is possible that some of the changes can clash.<br />
Resolution of these conflicts is automatic and is done on a last write wins rule,<br />
with the smallest element being an X.500 object.<br />
For example, when DSA1 updates an object’s surname attribute at time T, and<br />
DSA2 updates an object’s phoneNumber attribute at time T+1, then the final<br />
object after resynchronization is the object contained in DSA2, and does not have<br />
the changes to the surname.<br />
Add a Database Replica<br />
To add a database replica:<br />
1. Follow the instruction in Manually Synchronizing Replicas Using Database<br />
Tools in this chapter. This creates another database containing the same data<br />
as the source.<br />
2. Create a new peer DSA that will use the new populated database.<br />
3. Change the DSA flags in the knowledge file to contain the multi-write flag for<br />
both the source and target DSAs.<br />
4. Use the following command for all multiwrite DSAs running multiwrite<br />
DISP recovery, that is, where multi-write-disp-recovery = TRUE<br />
For example, on the Source DSA use the command:<br />
dxdisp -clear targetDSA sourceDB<br />
This clears the time of the last DISP update to the target DSA from the source<br />
DSAs internal database tables. When the source DSA starts, it sets this time<br />
to the source DSAs startup time and then only sends DISP updates<br />
containing changes since that time.<br />
5. Start the source and target DSAs.<br />
7–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Remove a Database Replica<br />
To remove a replica:<br />
1. Shut down all the peers within the replication set.<br />
2. Edit the initialization file or the knowledge group file (if applicable) to delete<br />
the knowledge of the DSA being removed.<br />
3. Clear the time of the last DISP update from each of the remaining DSAs in<br />
the replication set for the DSA being removed using tool DXdisp tool.<br />
For example, if Apple, Banana, and Pear are DSAs in a replication set and<br />
you remove the Pear DSA, issue the following commands:<br />
On the system running the Apple DSA:<br />
dxdisp –clear Pear AppleDB<br />
On the system running the Banana DSA:<br />
dxdisp –clear Pear BananaDB<br />
Multiwrite Replication to an LDAP <strong>Directory</strong><br />
You can use multiwrite replication to replicate updates applied to <strong>eTrust</strong><br />
<strong>Directory</strong> to an LDAP server.<br />
To forward all updates on an <strong>eTrust</strong> <strong>Directory</strong> server to an LDAP server, include<br />
the following line in the knowledge of the LDAP server:<br />
dsa-flags = multi-write<br />
Multiwrite and DXcache<br />
If you are using DXcache to increase search performance to a shared database,<br />
you can still send multiwrite updates to only update DXcache by including<br />
the DSA flag multi-write-notify in the knowledge:<br />
dsa-flags = multi-write-notify<br />
In this mode, the cache is updated but the database is not. Configure at least one<br />
DXserver connected to the database so that the database remains updated and<br />
synchronized.<br />
See the chapter “General Administration” for more information about DXcache.<br />
Replication 7–17
Multiwrite Replication<br />
Re-synchronize Databases Manually<br />
Regardless of the amount of automatic recovery in place, it is always necessary to<br />
have procedures in place that use tools to resynchronize databases.<br />
If a DSA is offline for a long period of time, then a large number of updates may<br />
be required to synchronize that DSA with the master. When this is the case, it can<br />
be quicker to reload the data from a snapshot of the master database. If you do<br />
this, you must also inform the master and other peers that a manual<br />
resynchronization has taken place.<br />
To take a snapshot of the master and reloading it on the slave, use the<br />
DXdumpdb and DXloaddb tools<br />
To inform a peer that a particular DSA has been manually resynchronized, use<br />
the following command:<br />
dxdisp -clear dsaname dbname<br />
where<br />
■<br />
■<br />
dsaname is the name of the slave DSA<br />
dbname is the name of the database associated with the peer DSA<br />
To manually resynchronize master and slave DSAs:<br />
1. Shut down the master DSA.<br />
2. Dump the master database using the DXdumpdb tool.<br />
3. Inform the master (and any other peer DSA) that a manual resynchronization<br />
has occurred using the DXdisp tool.<br />
4. Restart the master DSA.<br />
5. Copy the LDIF file to the slave machine.<br />
6. Reload the slave database using the DXloaddb tool.<br />
7. Start the slave DSA.<br />
7–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Multiwrite Replication<br />
Example: Multiwrite Replication<br />
The system shown in this diagram has the following properties:<br />
■<br />
■<br />
■<br />
■<br />
All read operations (read, list, search, compare) are load-shared between the<br />
two machines (according to the order that the DSAs are defined). Making use<br />
of both machines can double the system throughput.<br />
All write operations (modify, rename, add, delete) occur in real time using<br />
multiwrite. This ensures that both machines are synchronized at the time the<br />
update-confirm is sent back to the client.<br />
The primary router (R1) can automatically redirect/retry any queries sent to<br />
a data DSA (RO1, RW1, RO2, RW2) that unexpectedly shuts down. When<br />
this DSA is returned to operation, it is automatically resynchronized.<br />
The client application should fail over to the backup router (R2) in the event<br />
that Machine 1 (or R1) unexpectedly shuts down. If the client retries (to R2)<br />
any queries outstanding (on R1), then there is no possibility of the system<br />
losing transactions.<br />
This configuration can be summarized in the following table:<br />
DSA Function Prefix DSA flags<br />
R1, R2 Router DSA -<br />
RO1, RO2 Read DSA read-only, load-share<br />
RW1, RW2 Read/Write DSA multi-write<br />
This diagram shows the effective combining of distribution and replication. The<br />
prefix of the routers (R1, R2) is one level less than that of the data DSAs (RO1,<br />
RW1, RO2, RW2). A query is routed to a data DSA when the base object of the<br />
query is within the subtree of the data DSA.<br />
Replication 7–19
Multiwrite Replication<br />
You can configure the system shown this diagram to have the immediacy of the<br />
multiwrite replay system with the recoverability of the state-based system. In<br />
this case, DSP is used to chain requests in real time to peer/slave DSAs while<br />
DISP can be used to recover requests if any DSAs are restarted.<br />
7–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DISP Replication<br />
DISP Replication<br />
X.500 defines a master–slave replication scheme using DISP (<strong>Directory</strong><br />
Information Shadowing Protocol). In this scheme, any update that succeeds<br />
locally is forwarded to other DSAs according to any controlling bilateral<br />
agreement with those other DSAs.<br />
The DXserver DSA implements the 1993 <strong>Directory</strong> Information Shadowing<br />
Protocol (DISP), which lets you replicate information in OSI-conformant<br />
directories. This implementation is very flexible and supports:<br />
■<br />
■<br />
■<br />
DISP routing<br />
Shared configuration<br />
On-demand and periodic updates<br />
Configuring a DISP Responder<br />
To configure the DISP responder module, enter a listening address in the DSA<br />
definition in the configuration file (.dxc), in the knowledge directory.<br />
Example: Configuring<br />
the DISP Responder<br />
# Sample DSA Knowledge configuration file: DemoCorp.dxc<br />
set dsa “DemoCorp” =<br />
{ prefix = <br />
dsa-name = <br />
dsa-password = “demo”<br />
address = tcp eagle port 1900<br />
disp-psap<br />
= DISP<br />
...<br />
auth-levels<br />
= anonymous, clear-password<br />
dsp-idle-time = 3600<br />
};<br />
This responder remains active, awaiting incoming DISP protocol requests.<br />
DISP Agreements<br />
Agreements form the basis of all replication transfers. You direct and validate<br />
DISP updates between DSAs using agreements. A DSA can have a number of<br />
agreements relating to one or more remote DSAs.<br />
You can manage DISP agreements using the commands:<br />
■<br />
■<br />
set agreement id.ver = agreement;<br />
get agreement<br />
An agreement is a set of statements that defines a replication strategy. Define<br />
each agreement with an agreement identifier and an agreement version.<br />
Replication 7–21
DISP Replication<br />
Setting DISP Agreements<br />
You can set agreements using the set command, which the following form:<br />
set agreement id.ver =<br />
{ initiator = name mode<br />
responder = name authlevel<br />
[relay = name authlevel ]<br />
area = <br />
[filter = { searchFilter }]<br />
[attributes = { attrSelectionList }]<br />
[strategy = frequency time type]<br />
};<br />
The following are the parameters of the set agreement command:<br />
Parameter<br />
Value<br />
id.ver The agreement identification and version numbers (for example, 1.2).<br />
initiator<br />
responder<br />
relay<br />
area<br />
strategy<br />
Filter<br />
attributes<br />
The DSA initiating the DISP update:<br />
name—DSA name as defined in a set dsa definition<br />
mode—either supplier or consumer<br />
The DSA receiving the DISP update:<br />
name—DSA name as defined in a set dsa definition<br />
authlevel—anonymous, clear-password, or ssl-auth<br />
(Optional) An intermediate DSA used to relay the DISP update:<br />
name—DSA name as defined in a set dsa definition<br />
authlevel—either anonymous or clear-password<br />
The top of the subtree being replicated; the value is the distinguished name of the<br />
entry at the top of the subtree.<br />
(Optional) Enables automatic DISP update to be performed. The strategy either<br />
has the keyword value on-change or has the following three values:<br />
frequency—has one of the keyword values hourly, daily, weekly, or monthly<br />
time—either dd:hh:mm or hh:mm<br />
type—either incremental or full<br />
A search filter restricting the entries to be included in the DISP update<br />
searchFilter—an X.500 filter<br />
A list of attributes to include and/or exclude from a DISP update.<br />
attrSelectionList ::= attrSelection | attrSelection attrSelectionList<br />
attrSelection ::= { [object-class = objectClass,] IncludeExclude }<br />
IncludeExclude ::= [all-attributes] | [include = attrTypeList] | [exclude =<br />
attrTypeList]<br />
attrTypeList ::= attributeName [, attributeName]<br />
7–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DISP Replication<br />
Example: A DISP<br />
Agreement<br />
set agreement 0.0 =<br />
{ initiator = EAGLE supplier<br />
responder = BACKUP anonymous<br />
area = <br />
strategy = daily 03:00 incremental<br />
};<br />
Viewing DISP Agreements<br />
You can monitor DISP configuration using the get disp command. To view<br />
details of an agreement, use the following command:<br />
get agreement 1.0;<br />
where 1 is the agreement identifier and 0 is the agreement version. The output of<br />
this command looks similar to:<br />
Agreement 1.0<br />
initiator = EAGLE supplier<br />
responder = BACKUP<br />
area = <br />
<br />
- last update at Thu Jul 9 09:53:47 1998<br />
Shared DISP Configuration<br />
You can achieve replication between two DSAs using point-to-point DISP.<br />
DISP<br />
DB DSA<br />
DSA DB<br />
(Supplier)<br />
(Consumer)<br />
Share the DISP configuration between the DSAs. When two DSAs share an<br />
agreement that includes a strategy (see DISP Agreements in this chapter for more<br />
information), where one of the DSAs is an initiator and the other a responder, the<br />
system performs automatic DISP updates as determined by the strategy.<br />
Replication 7–23
DISP Replication<br />
Manual Initiation of DISP<br />
You can manually perform a DISP update, even when there is a strategy, using<br />
the command:<br />
disp update agreement 1.0;<br />
The strategy in the agreement defines the mode of the update. When there is no<br />
strategy, the update defaults to full.<br />
An incremental update updates all entries that changed since the last DISP<br />
update or since the DSA started.<br />
Shadow DSAs<br />
You can mark a slave DSA as a shadow. This means the DSA will act as a read<br />
only DSA and will not grant updates, except via DISP or Multiwrite. The master<br />
DSA can update the slave using DISP. Clients can query, but not update, the<br />
DSA using DAP or LDAP.<br />
set dsa ShadowDSA = {<br />
...<br />
dsa-flags = shadow, ...<br />
...<br />
};<br />
DISP Routing<br />
DXserver supports the concept of a DISP relay that lets you route DISP through<br />
one or more intermediate DSAs. This is especially useful for firewall and X.500<br />
Guard applications.<br />
DB<br />
DSA<br />
Routing<br />
DSA<br />
DSA<br />
DB<br />
To include a relay DSA in a DISP replication process, all three DSAs must have<br />
an agreement that identifies the relay. All three DSAs can share the same DISP<br />
configuration.<br />
Example: A DISP<br />
Agreement with Relay<br />
set agreement 0.0 =<br />
{ initiator = EAGLE supplier<br />
responder = BACKUP anonymous<br />
relay = DSA-RELAY anonymous<br />
area = <br />
};<br />
7–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DISP Replication<br />
Selective Shadowing<br />
The DXserver supports three methods of restricting the data that a supplier<br />
replicates to a shadow consumer. These methods are:<br />
■<br />
■<br />
■<br />
Specifying the replicated area<br />
Specifying a subtree filter for the replication area<br />
Specifying the set of attributes to be shadowed.<br />
Each of these refinements to the shadowed data are defined below.<br />
Specifying the Replicated Area<br />
This is defined by the area parameter in the DISP agreement. It specifies the top<br />
of the subtree to be replicated.<br />
Specifying a Subtree Filter<br />
This is defined by the optional filter parameter in the DISP agreement. This<br />
specifies a filter that is applied to entries in under the area context prefix. The<br />
filter parameter is defined as:<br />
filter = { } | NULL<br />
::= and { } | or { } | not { }<br />
| <br />
::= | , <br />
::= attr = <br />
::= present | value | substrings []<br />
::= = | = | ~=<br />
::= | , <br />
::= <br />
::= initial | final | any<br />
Using the subtree filter may cause problems when shadowing to other vendors<br />
directories. This is the case when a full refresh is requested, or if an entry is<br />
shadowed, but its parent entry does not exist on the shadow consumer. <strong>eTrust</strong><br />
directory overcomes these problem by the shadow consumer automatically<br />
creating glueDSEs for the missing entries. A glueDSE is a DSE (<strong>Directory</strong> Specific<br />
Entry) that has a name but no attributes including objectclass.<br />
If the subtree filter contains anything other than comparisons on object class<br />
values, for example a filter that matches all surnames of smith, then it is possible<br />
for an replicated entry to be modified on the master DSA such that the entry no<br />
longer matches the search filter. Subsequent DISP updates will not contain this<br />
entry but the shadow DSA will still contain the unmodified attribute and value.<br />
This is not a problem if the whole entry is deleted. For this reason it is not<br />
recommended to use anything other than restrictions based on object class.<br />
Replication 7–25
DISP Replication<br />
Specifying a Selection of Attributes<br />
This is defined by the optional attributes parameter in the DISP agreement. This<br />
specifies the set of attributes that are shadowed.<br />
Each element of attrSelectionList is an attrSelection element, which specifies the<br />
attributes that the shadow supplier is to select for shadowing. Specification of<br />
attributes for an object superclass also applies to any subclasses of the named<br />
class. If the class is omitted, the selection applies to all classes.<br />
When using the exclude specification, any attributes contained in an entry which<br />
are not explicitly excluded are implicitly included. Attributes are implicitly<br />
included in the case where all-attributes is specified.<br />
The attribute object class, all attributes that are described in the schema as must<br />
contain, and all operational attributes will be replicated unless they are explicitly<br />
excluded (that is, listed in an exclude list).<br />
Where entries belong to more than one of the specified classes, the specifications<br />
are cumulative. In the case of conflicting specifications include has priority over<br />
explicitly excluded attributes and exclude has priority over implicitly included<br />
attributes.<br />
It is possible for a selective DISP update to contain add entry requests that do not<br />
satisfy the schema requirements of the shadow consumer. For example, all<br />
mandatory attributes may not be present in the entry contained in the DISP<br />
update. With <strong>eTrust</strong> <strong>Directory</strong>, such an update is allowed, because it is assumed<br />
that the master DSA has verified the schema of the complete entry and allowed a<br />
partial replication to the shadow (or slave) DSA. The shadow DSA should be a<br />
read-only DSA so the fact that not all attributes are present in the entry should<br />
not be of consequence. This may cause problems when replicating to other<br />
vendors’ directories.<br />
Example: Selective<br />
Shadowing Example<br />
Agreement<br />
set agreement 2.1 =<br />
{<br />
initiator = EAGLE supplier<br />
responder = BACKUP anonymous<br />
area = <br />
filter = { attr = objectClass value = organizationalPerson }<br />
attributes = { { exclude = title, description, telephoneNumber } }<br />
strategy = on-change<br />
};<br />
7–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Manually Synchronizing Replicas Using Database Tools<br />
Manually Synchronizing Replicas Using Database Tools<br />
<strong>eTrust</strong> <strong>Directory</strong> databases should be manually synchronized when:<br />
■<br />
■<br />
The DXstatdb tool shows differing numbers of entries between databases in a<br />
replication set when the system is quiet. In this case, it usually makes sense<br />
to resynchronize all the directory databases to have the same number as the<br />
master database.<br />
There is a large mismatch between directory entries, perhaps because a<br />
multiwrite peer or DISP responder is unavailable for a long period of time<br />
while updates are applied to other systems in the replication set.<br />
How Manual Synchronization Works<br />
<strong>eTrust</strong> <strong>Directory</strong> provides a powerful set of database tools that can be used for<br />
resynchronization.<br />
This technique extracts directory information directly from the directory<br />
database into an intermediate LDIF file and then populates the target directory<br />
database directly from this file.<br />
Note: Both the source and target DSAs should be shut down during these<br />
operations.<br />
Source<br />
DB<br />
dxdumpdb<br />
LDIF<br />
File<br />
ldifsort<br />
LDIF<br />
File<br />
dxloaddb<br />
Target<br />
DB<br />
How to Manually Synchronize <strong>eTrust</strong> <strong>Directory</strong> Databases<br />
To manually resynchronize <strong>eTrust</strong> <strong>Directory</strong> databases:<br />
1. Dump the source database and use the DXdumpdb tool to produce an LDIF<br />
file.<br />
2. Use the ldifsort tool to sort the source LDIF file into DIT depth order.<br />
3. If the databases are on different systems, copy the LDIF file from the source<br />
system to the target system.<br />
4. Use the DXloaddb tool to load the target database with the LDIF data.<br />
5. Start the source and target DSAs.<br />
Replication 7–27
Chapter<br />
8<br />
LDAP and DXlink<br />
DXserver supports Lightweight <strong>Directory</strong> Access Protocol (LDAP), which<br />
enables any LDAP-conformant client access to DXserver. LDAP is fully<br />
integrated with DXserver and provides greater performance and efficiency than<br />
gateway approaches. Another advantage of integrated LDAP is that it obeys the<br />
DSA schema. This means that you only configure new schema once because both<br />
LDAP and DAP protocols share the same configuration.<br />
DXserver also supports the integration of LDAP servers into a distributed<br />
directory backbone. DXlink lets DXserver send requests to one or more LDAP<br />
servers and process the results returned from them as if they were normal X.500<br />
directory servers. This enables LDAP servers to be integrated into a fully<br />
distributed directory framework.<br />
LDAP and DXlink 8–1
LDAP Clients<br />
LDAP Clients<br />
DXserver can be accessed from LDAP clients, such as web browsers, address<br />
books, and Lightweight <strong>Directory</strong> User Agents (LDUAs).<br />
DXserver<br />
LDAP<br />
Client<br />
LDAP<br />
Server<br />
DXserver<br />
Defining the LDAP Port<br />
You define the LDAP address using the set dsa command, which contains a port<br />
number that listens for LDAP requests, as follows:<br />
set dsa “Eagle” = {<br />
...<br />
address = tcp “eagle” port 389<br />
...<br />
};<br />
This address definition is mandatory; it automatically enables LDAP as the<br />
DXserver listens for different protocols on the same port. For more information,<br />
see the section Defining DSAs in the chapter “General Administration” for more<br />
information.<br />
For a list of all ports in a default installation of <strong>eTrust</strong> <strong>Directory</strong>, see the section<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter DXserver Overview.<br />
Configuring LDAP Names<br />
You configure LDAP names along with the usual schema attribute and object<br />
class definitions:<br />
set attribute 2.5.4.3 = {<br />
name = commonName<br />
ldap-names = cn<br />
syntax = caseIgnoreString<br />
};<br />
LDAP names are integrated into the DXserver schema. See the chapter “Schema<br />
Definition” for more information.<br />
8–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
LDAP Clients<br />
Handling LDAP Strings<br />
LDAP uses only string labels for information, so DXserver resolves them to their<br />
true object and attribute identifiers by looking up their schema information. For<br />
each object and attribute label specified in the LDAP service requests, DXserver<br />
looks first for matching ldap-names, and then for a name.<br />
LDAP is a string-handling protocol only; therefore, a number of restrictions are<br />
implicit:<br />
■<br />
■<br />
■<br />
Developers of directory clients must ensure the DXserver receives an<br />
appropriately formatted LDAP message because the LDAP syntax is highly<br />
dependent on appropriate punctuation, white space, and so forth.<br />
Developers of LDAP directory clients must define locally customized<br />
attributes and objects through the DXserver schema definition process.<br />
Developers should remember that LDAP names are not necessarily unique.<br />
For example, two organizations can define the string mail, but have different<br />
syntaxes and uses for it.<br />
Transparent Routing<br />
When using DXserver to route client requests to external LDAP directories using<br />
DXlink, it may not be feasible or convenient to include all third-party schema.<br />
See the Transparent Routing section in the Distribution and DSP chapter for<br />
more information.<br />
LDAP and DXlink 8–3
Schema Publishing<br />
Schema Publishing<br />
<strong>eTrust</strong> <strong>Directory</strong> supports schema publishing through LDAP Version 3. This<br />
enables LDAP directory clients to read the directory schema dynamically from<br />
the DXserver using LDAP Version 3. For further information, see section 3.2.2<br />
Subschema Entries and Subentries of RFC 2251 LDAPv3.<br />
The following information is published through the cn=schema subschema<br />
subentry using LDAP Version 3:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Attributes<br />
Object Classes<br />
Attribute Types<br />
Syntaxes<br />
Name Forms<br />
Structure Rules<br />
This can be retrieved by performing a base object search of the cn=schema<br />
subentry with a search filter of objectClass present. The following is an extract of<br />
the LDAP trace of such a search:<br />
> SearchRequest<br />
> baseObject: cn=schema<br />
> scope: baseObject<br />
> derefAliases: derefAlways<br />
> sizeLimit: 0<br />
> timeLimit: 0<br />
> typesOnly: false<br />
> filter:<br />
> present: objectClass<br />
> attributes:<br />
><br />
><br />
> --> LDAP MESSAGE messageID 2<br />
> SearchResultEntry<br />
> objectName: cn=schema<br />
> attributes<br />
> type: objectClass<br />
> value: top<br />
> value: subschema<br />
> type: cn<br />
> value: schema<br />
> type: attributeTypes<br />
> value: (2.5.4.0 NAME 'objectClass'SYNTAX 1.3.6.1.4.1.1466.115.121.1.38)<br />
> value: (2.5.4.1 NAME 'aliasedObjectName'SYNTAX<br />
1.3.6.1.4.1.1466.115.121.1.12)<br />
. . .<br />
> value: (1.3.6.1.4.1.3327.77.4.1.9 NAME 'uNSPSCdateto' SYNTAX<br />
1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE)<br />
> type: objectClasses<br />
> value: (2.5.6.0 NAME 'top' ABSTRACT MUST (objectClass))<br />
> value: (2.5.6.1 NAME 'alias' SUP (top) STRUCTURAL MUST (aliasedObjectName))<br />
. . .<br />
> value: (1.3.6.1.4.1.3327.77.4.2.1 NAME 'uNSPSC' SUP (top) STRUCTURAL MUST<br />
(uNSPSCCode$uNSPSCTitle) MAY<br />
(uNSPSCContractManager$uNSPSCContractID$uNSPSCContractAuth$uNSPSCContractSupplie<br />
8–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Schema Publishing<br />
r$uNSPSCdateissued$uNSPSCdatefrom$uNSPSCdateto))<br />
> type: ldapSyntaxes<br />
> value: (1.3.6.1.4.1.1466.115.121.1.4 DESC 'Audio')<br />
> value: (1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary')<br />
. . .<br />
> value: (1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time')<br />
> type: nameForms<br />
> value: (1.3.6.1.4.1.3327.7.1 NAME 'country-top-NF' OC country MUST<br />
(countryName))<br />
> value: (1.3.6.1.4.1.3327.7.2 NAME 'o-top-NF' OC organization MUST<br />
(organizationName ))<br />
. . .<br />
> value: (1.3.6.1.4.1.3327.77.4.14.3 NAME 'uNSPSC-uNSPSC-NF' OC uNSPSC MUST<br />
(uNSPSCTitle) MAY (uNSPSCCode$uNSPSCContractID))<br />
> type: dITStructureRules<br />
> value: (1 NAME 'country-top-SR' FORM country-top-NF)<br />
> value: (2 NAME 'o-top-SR' FORM o-top-NF)<br />
. . .<br />
> value: (38 NAME 'uNSPSC-uNSPSC-SR' FORM uNSPSC-uNSPSC-NF SUP (36 37 38))<br />
LDAP and DXlink 8–5
Integrating Other LDAP Servers<br />
Integrating Other LDAP Servers<br />
LDAP servers do not support the DSP protocol. This means that you cannot<br />
perform a distributed search over a number of LDAP directory servers. <strong>eTrust</strong><br />
<strong>Directory</strong> has a facility called DXlink that lets LDAP servers link into an X.500<br />
backbone. The DXserver can send requests to one or more LDAP directories and<br />
process the results returned from them as if they were X.500 directory servers.<br />
DXserver<br />
LDAP<br />
DXserver<br />
DXlink<br />
To configure DXlink, configure the LDAP server as if it is a DXserver, and add<br />
the dsp-ldap link-flags to the dsa definition as follows:<br />
set dsa “LDAPserver” = {<br />
prefix = <br />
dsa-name = <br />
address = tcp Eagle port 389<br />
...<br />
link-flags = dsp-ldap<br />
}<br />
Note: When you are using LDAP Version 3, use the dsp-ldap link flag; however,<br />
when you are using LDAP version 2, use dsp-ldapv2.<br />
8–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Integrating Other LDAP Servers<br />
User Credentials on DXlink Binds<br />
LDAP servers expect connections from only LDAP users; therefore, DXlink must<br />
make the X.500 backbone look like an ordinary LDAP user.<br />
A complication arises with name and password security (simple credentials). In<br />
DSP, a single link between DSAs can support any number of users, because user<br />
information is passed with each DSP request. However, in LDAP, links cannot be<br />
shared, so DXserver must set up separate links for every LDAP user.<br />
When the DSA is acting as a direct pass-through from a user to an LDAP server<br />
and the user's name resides on the LDAP server, then the DSA sets up a separate<br />
link for that user and uses their credentials in that link:<br />
Client<br />
User=J. Bloggs<br />
password = yellow<br />
DSA<br />
User=J. Bloggs<br />
password = yellow<br />
LDAP<br />
Server<br />
Setting User Credentials for LDAP Operations<br />
However, if either of the following is true, you can set the credentials used in the<br />
DXlink connections in the LDAP server configuration file:<br />
■<br />
■<br />
The user invoking the request is authenticated using a DN that is outside the<br />
LDAP server.<br />
More than one DSA is in the path to the LDAP server.<br />
For example:<br />
set dsa LDAP1 = {<br />
...<br />
ldap-dsa-name = <br />
ldap-dsa-password = fredspassword<br />
...<br />
};<br />
The ldap-dsa-name must be a valid entry on the LDAP server because all<br />
requests from the backbone use the permissions that are granted to this entry.<br />
The DSA in the previous example expects credentials to be returned on the bind<br />
confirm sent by the LDAP server. If no credentials are returned then the bind is<br />
rejected.<br />
The knowledge reference of the LDAP server can include the trust flag no-servercredentials,<br />
which indicates to the DSA that the LDAP server will not return<br />
credentials on a bind.<br />
LDAP and DXlink 8–7
Integrating Other LDAP Servers<br />
When this flag is set, then the DSA will accept a bind confirm result returned<br />
from the LDAP server if it does not include credentials.<br />
set dsa LDAP1 = {<br />
...<br />
trust-flags = no-server-credentials<br />
...<br />
};<br />
Automatically Authorizing LDAP Operations<br />
When a directory backbone performs operations over DXLINK, some operations<br />
on the target LDAP server may require that the user be authorized for that<br />
operation.<br />
You can include the dsp-ldap-proxy link flag in the DXLINK knowledge, to cause<br />
the last DSA in the chain to use the authorization of the originating user to<br />
perform operations on the LDAP server.<br />
Important! This may compromise security, because the originating user is never<br />
authenticated by the LDAP server.<br />
Usually, the last DSA in the chain binds to the LDAP server using the credentials<br />
specified in the ldap-dsa-name and ldap-dsa-password flags.<br />
If the dsp-ldap-proxy flag is also set, then the DN of the user that made the initial<br />
bind is added to the following subsequent requests:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
search<br />
compare<br />
modify<br />
add<br />
delete<br />
modify DN<br />
If the initial bind was anonymous, no DN is added to subsequent requests.<br />
This is achieved by the DSA chaining the operation over DXLINK adding the<br />
originator DN to a LDAP proxy control on the request. The LDAP server will<br />
need to allow the DN specified ldap-dsa-name authorization to proxy all users.<br />
Note: The dsp-ldap-proxy link flag can only be used if the target LDAP server<br />
supports the LDAP Proxy Authorization control.<br />
8–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Integrating Other LDAP Servers<br />
Prefix Mapping<br />
Prefix mapping lets LDAP servers, other DSAs, or agents map into an area of the<br />
DIT. Prefix mapping is useful for collecting disjointed subtrees under a common<br />
node. Applications include transient groupings (such as task forces) or logical<br />
groupings (such as libraries where individual libraries are spread across an<br />
organization or location tree).<br />
Prefix mapping is also useful for DXlink because an LDAP server may not be<br />
able to change its prefix. Because LDAP servers have no concept of distribution,<br />
their DITs usually contain the first- or second-level nodes. This makes it hard to<br />
integrate them into a host DIT.<br />
An example is an X.500 directory system that controls the nodes c=US and c=US,<br />
o=<strong>CA</strong>I. There is also an LDAP server with the X.500 naming context:<br />
“c=US, o=<strong>CA</strong>”<br />
The LDAP server does not contain the c=US node but controls the tree beneath<br />
the c=US node that starts with the o=<strong>CA</strong> entry. It was set up to control the North<br />
American part of <strong>CA</strong> but is now required to be incorporated into the entire <strong>CA</strong><br />
directory. This context can be mapped into the host's X.500 naming context<br />
“c=US, o=<strong>CA</strong>I” as:<br />
“c=US, o=<strong>CA</strong>I, ou=<strong>CA</strong> North America”<br />
Thus, a subtree search of “c=US, o=<strong>CA</strong>I, ou=<strong>CA</strong> North America” is mapped to a<br />
subtree search of “c=US, o=<strong>CA</strong>” before being forwarded to the LDAP server. The<br />
results are mapped back into the host DIT space.<br />
C=US<br />
O=<strong>CA</strong>I<br />
O=<strong>CA</strong> North<br />
America<br />
You can enable prefix mapping by defining a native-prefix in the server<br />
definition:<br />
set dsa LDAP1 = {<br />
...<br />
prefix = <br />
native-prefix = <br />
...<br />
};<br />
LDAP and DXlink 8–9
Integrating Other LDAP Servers<br />
Working with Microsoft Exchange<br />
An example Microsoft Exchange knowledge file is shown below:<br />
set dsa EXCHANGE = {<br />
prefix = <br />
native-prefix = <br />
dsa-name = <br />
address = tcp “currawong” port 389<br />
auth-levels = anonymous<br />
dsp-idle-time = 60<br />
trust-flags = no-server-credentials, allow-downgrading, allow-upgrading<br />
link-flags = dsp-ldap, ms-exchange<br />
};<br />
The native prefix is determined by the following entries that can be found in<br />
Microsoft Exchange <strong>Administrator</strong>. See the example shown in the following<br />
dialog, where:<br />
o = the Exchange Address Book name<br />
ou = the domain name<br />
cn = the recipients container (usually named “recipients”)<br />
8–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
9<br />
Monitoring the <strong>Directory</strong><br />
We recommend that you monitor the directory to detect operational problems as<br />
early as possible.<br />
DXserver supports both Internet and OSI protocols for monitoring server<br />
operations. These protocols are:<br />
■<br />
■<br />
■<br />
The Internet Simple Network Management Protocol (SNMP)<br />
The X.700 Common Management Information Protocol (CMIP)<br />
Telnet—used by the management console<br />
General monitoring facilities, and DXadmind, the <strong>eTrust</strong> <strong>Directory</strong><br />
administration daemon, are also available.<br />
Monitoring the <strong>Directory</strong> 9–1
General Monitoring<br />
General Monitoring<br />
During normal operation of a directory:<br />
■<br />
■<br />
■<br />
Data is added to and deleted from the directory.<br />
User and other DSA connections are made and released.<br />
Log files are generated.<br />
You should review DXserver operation periodically to ensure DXserver<br />
continues to run smoothly.<br />
DXconsole<br />
You can perform special-case checking of operational parameters and server<br />
usage with management commands.<br />
To view the number and type of operations performed by the DSA:<br />
get stats;<br />
To view current DSP connections to other DSAs:<br />
get online-dsas;<br />
To view current user connections to the DSA:<br />
get users;<br />
To view the names of the currently enabled log files:<br />
get log;<br />
Log Files<br />
We recommend that you maintain log files to record a DSA’s activity. You can<br />
then postprocess these files to obtain:<br />
■<br />
■<br />
■<br />
Statistics<br />
Billing<br />
Auditing<br />
We also recommend that you periodically monitor the alarm log to check for<br />
operation errors.<br />
9–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
General Monitoring<br />
Databases<br />
The DXtools DXstatdb command prints a summary of a given database. The<br />
database itself has monitoring facilities. See the chapter “Using DXtools” for<br />
more information.<br />
Disk Space<br />
As a directory grows, it consumes more disk space. Disk space is used for:<br />
■<br />
■<br />
■<br />
<strong>Directory</strong> data<br />
Backups (database checkpoints)<br />
Log files<br />
When the directory contains a large amount of data, the database checkpoint files<br />
can become large. You can either delete old checkpoint files or move them to<br />
storage areas.<br />
Monitoring the <strong>Directory</strong> 9–3
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
DXserver has a built-in SNMP agent to monitor operations of the DSA. This<br />
management agent implements the RFC1567 <strong>Directory</strong> Monitoring Management<br />
Information Base (MIB) and includes information such as:<br />
dsaOpsTable<br />
Provides summary statistics on the directory accesses, operations, and errors<br />
dsaEntriesTable<br />
Provides summary statistics on the entries held by the DSA and on cache<br />
performance<br />
dsaIntTable<br />
Provides useful information about the interaction of the monitored DSA with<br />
peer DSAs<br />
The SNMP agent can also monitor information that is specific to <strong>eTrust</strong><br />
<strong>Directory</strong>. These monitoring options are described in<br />
/samples/snmp/dxmib.asn1. The SNMP can monitor:<br />
■<br />
■<br />
■<br />
Multiwrite replication<br />
DXserver statistics<br />
DXcache<br />
You can use any third-party SNMP manager, provided it supports the RFC1567<br />
MIB. Because this is a read-only MIB, you cannot use it for configuring the DSA.<br />
9–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
Configuring the SNMP Agent<br />
Configure the SNMP agent (via DXconsole or in the DSA configuration file (.dxc)<br />
in the knowledge directory), using the set dsa command.<br />
Example:Configuring<br />
the SNMP Agent<br />
set dsa “DEMOCORP” = {<br />
...<br />
snmp-port = 19389<br />
...<br />
};<br />
Define the UDP/IP port that listens for incoming SNMP requests by setting the<br />
snmp-port. This is the only UDP port that the DSA uses, so it can accept any<br />
value and it does not interfere with TCP port numbers.<br />
You can set the following SNMP parameters:<br />
■<br />
■<br />
■<br />
■<br />
snmp-description<br />
snmp-contact<br />
snmp-name<br />
snmp-location<br />
set snmp-description = “SNMP monitor”<br />
set snmp-contact = “supportconnect@ca.com”<br />
set snmp-name = myDXserver<br />
set snmp-location = myOffice<br />
For a list of all ports in a default installation of <strong>eTrust</strong> <strong>Directory</strong>, see the section<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter DXserver Overview.<br />
Monitoring the <strong>Directory</strong> 9–5
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
SNMP Monitor Utility<br />
<strong>eTrust</strong> <strong>Directory</strong> supplies a sample SNMP MIB walker utility called dxsnmp in<br />
the samples/snmp directory. The SNMP utility polls the server periodically and<br />
prints nonzero parameters.<br />
To start the SNMP utility, use the following command:<br />
dxsnmp -r[n] ipaddress/port<br />
The -r option is the refresh rate (in seconds). You can enter a number after the -r<br />
to indicate the number of seconds between each refresh. The default value is 5.<br />
Example: Starting the<br />
SNMP MIB Walker<br />
dxsnmp –r localhost/19389<br />
The following is a sample output:<br />
$ dxsnmp localhost/19389<br />
sysDescr : <strong>CA</strong> <strong>eTrust</strong> DXserver<br />
sysObjectID : 1.3.6.1.4.1.3327.20.0.0<br />
sysUpTime : 8323.00<br />
sysContact : supportconnect@ca.com<br />
sysName : democorp<br />
sysLocation : http://www.ca.com<br />
sysServices : 0<br />
dsaAnonymousBinds.1 : 11<br />
dsaUnauthBinds.1 : 0<br />
dsaSimpleAuthBinds.1 : 0<br />
dsaStrongAuthBinds.1 : 8<br />
dsaBindSecurityErrors.1 : 0<br />
dsaInOps.1 : 99<br />
dsaReadOps.1 : 0<br />
dsaCompareOps.1 : 0<br />
dsaAddEntryOps.1 : 0<br />
dsaRemoveEntryOps.1 : 0<br />
dsaModifyEntryOps.1 : 0<br />
dsaModifyRDNOps.1 : 0<br />
dsaListOps.1 : 0<br />
dsaSearchOps.1 : 30<br />
dsaOneLevelSearchOps.1 : 20<br />
dsaWholeTreeSearchOps.1 : 0<br />
dsaReferrals.1 : 0<br />
dsaChainings.1 : 0<br />
dsaSecurityErrors.1 : 0<br />
dsaErrors.1 : 11<br />
dsaMasterEntries.1 : 0<br />
dsaCopyEntries.1 : 0<br />
dsaCacheEntries.1 : 0<br />
dsaCacheHits.1 : 0<br />
dsaSlaveHits.1 : 0<br />
Example: Monitoring<br />
multiwrite replication<br />
This is only displayed if multiwrite replication is enabled. The following is a<br />
sample output:<br />
dxRemoteDsaName.1 : DEMOCORP2<br />
dxRemoteDsaName.2 : DEMOCORP3<br />
dxRemoteDsaName.3 : DEMOCORP4<br />
dxMWQueueLength.1 : 0<br />
dxMWQueueLength.2 : 1<br />
dxMWQueueLength.3 : 0<br />
dxMWStatus.1 : 1 (ok)<br />
dxMWStatus.2 : 2 (failed)<br />
dxMWStatus.3 : 1 (ok)<br />
dxMWPendingRemote.1 : 0<br />
dxMWPendingRemote.2 : 0<br />
9–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
dxMWPendingRemote.3 : 0<br />
dxMWConfirmedLocal.1 : 0<br />
dxMWConfirmedLocal.2 : 1<br />
dxMWConfirmedLocal.3 : 0<br />
Example: Monitoring<br />
DXserver statistics<br />
The dxStatsNoTicks and dxStatsBusy items only appear if stats logging is<br />
enabled.<br />
The following is a sample output:<br />
dxStatsAssocs : 1<br />
dxStatsNilCredit : 0<br />
dxStatsNoTicks : 1<br />
dxStatsQueue : 3<br />
dxStatsBusy : 2<br />
dxStatsOps : 11<br />
Example: Monitoring<br />
Dxcache<br />
This option always appears, but will only show information when DXcache is<br />
enabled.<br />
The dxCacheSearchHits value increments whenever a seach is resolved within<br />
the cache. The dxCacheSearchMisses value increments whenever a search has to<br />
be passed to the back end.<br />
The following is a sample output:<br />
dxCacheStatus : 3 (cache_ok)<br />
dxCacheSize : 456789<br />
dxCacheSearchHits : 15<br />
dxCacheMisses : 10<br />
Monitoring the <strong>Directory</strong> 9–7
SNMP and the <strong>Directory</strong> Monitoring MIB<br />
Configuring the SNMP Trap Destination<br />
Deliver Alarms as<br />
SNMP Traps<br />
To configure the delivery of alarms as SNMP traps, use the following console<br />
command:<br />
set snmp-log = udp host port portnumber;<br />
You can place this command in the appropriate configuration file (.dxc) within<br />
the logging directory.<br />
Disable Feature<br />
To disable the feature:<br />
close snmp-log;<br />
Tip: The trap contains three variables: sysName, sysDescr, and sysLocation.<br />
sysName contains the name of the DXserver sending the trap, sysDescr<br />
contains sufficient information to reconstruct the actual update operation,<br />
and sysLocation contains the actual alarm text.<br />
Send Traps About<br />
Any Update<br />
Operations<br />
By default, all alarms are sent to the trap destination. However, you can<br />
configure the DXserver to send traps that contain information about any update<br />
operations it receives. To do this, set an associated Boolean setting,<br />
trap-on-update, as follows:<br />
set trap-on-update = true;<br />
Typically, you set this in the DXserver settings configuration file (.dxc) in the<br />
settings directory.<br />
9–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
CMIP and X.700 Management<br />
CMIP and X.700 Management<br />
The DXserver DSA has an integral CMIP management agent for monitoring the<br />
operation of the DSA.<br />
The DSA provides limited support for ISO 9594-10 (Committee Draft April 1995)<br />
as follows:<br />
■<br />
■<br />
The MIB fully supports the DSA-managed object definitions. You can<br />
determine its structure and naming by setting scope=wholeSubTree or<br />
scope=baseObject.<br />
<strong>eTrust</strong> <strong>Directory</strong> supports all packages of the DSA-managed object. Each<br />
component of each package is read-only because the intended use is for<br />
monitoring.<br />
Configuring the CMIP Agent<br />
You configure the listening address for the CMIP agent through the management<br />
console or in the DSA initialization scripts.<br />
Example: Configuring<br />
the CMIP Agent<br />
set dsa “DEMOCORP” = {<br />
...<br />
cmip-psap = CMIP<br />
...<br />
};<br />
The cmip-psap command defines the address, which this instance of the DSA<br />
listens on for OSI management requests.<br />
If required, you can input hexadecimal values in the syntax 0x1234 in place of<br />
characters or text.<br />
CMIP Monitor Utility<br />
<strong>eTrust</strong> <strong>Directory</strong> supplies a sample CMIP monitoring utility called DXcmip in the<br />
samples/cmip directory. This very simple CMIP manager performs periodic get<br />
requests on the DSA.<br />
You can start the CMIP utility using the following command:<br />
dxcmip -r[n] ipaddress/portnumber [psel]<br />
The -r option is the refresh rate (in seconds). You can enter a number after the -r<br />
to indicate the number of seconds between each refresh. The default value is five.<br />
Monitoring the <strong>Directory</strong> 9–9
CMIP and X.700 Management<br />
Example: Starting the<br />
CMIP Monitoring<br />
Application<br />
dxcmip -r localhost/19389<br />
This example starts the CMIP monitor. It monitors operations on the server<br />
configured in SNMP Example 1—Configuring the SNMP Agent.<br />
The following is a sample output:<br />
$ dxcmip localhost/19389<br />
objectClass : 2.5.30.2.0<br />
nameBinding : 2.5.30.3.0<br />
packages : (Not decoded)<br />
commonName : DSA<br />
accessPoint : (Not decoded)<br />
masterEntries : 0<br />
copyEntries : 0<br />
loopsDetected : 0<br />
securityErrors : 0<br />
nameErrors : 1<br />
foundLocalEntries : 41<br />
referrals : 0<br />
serviceErrors : 0<br />
aliasDereferences : 0<br />
chainings : 0<br />
invalidReferences : 0<br />
unableToProceed : 0<br />
outOfScope : 0<br />
noSuchObject : 1<br />
aliasProblem : 0<br />
aliasDereferencingProblem : 0<br />
affectsMultipleDSAs : 0<br />
unavailableCriticalExtension : 0<br />
timeLimitExceeded : 0<br />
sizeLimitExceeded : 0<br />
adminLimitExceeded : 0<br />
maxSizeLimit : 0<br />
maxTimeLimit : 0<br />
prohibitChaining : False<br />
readOpsProc : 0<br />
compareOpsProc : 0<br />
abandonOpsProc : 38<br />
listOpsProc : 0<br />
searchOpsProc : 30<br />
search1levelOpsProc : 20<br />
searchSubtreeOpsProc : 0<br />
addOpsProc : 0<br />
removeOpsProc : 0<br />
modifyOpsProc : 0<br />
modifyDNOpsProc : 0<br />
readOpsProc : 0<br />
compareOpsProc : 0<br />
abandonOpsProc : 0<br />
listOpsProc : 0<br />
searchOpsProc : 0<br />
search1levelOpsProc : 0<br />
searchSubtreeOpsProc : 0<br />
addOpsProc : 0<br />
removeOpsProc : 0<br />
modifyOpsProc : 0<br />
modifyDNOpsProc : 0<br />
dSAScopeOfReferral : 0<br />
dSAScopeOfChaining : 0<br />
peerEntityAuthenticationPolicy : 0<br />
requestAuthenticationPolicy : 0<br />
resultAuthenticationPolicy : 0<br />
dSPAssociationEstablishment : 0<br />
dOPAssociationEstablishment : 0<br />
dISPAssociationEstablishment : 0<br />
maxDAPAssociations : 0<br />
maxDSPAssociations : 0<br />
9–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
CMIP and X.700 Management<br />
maxDOPAssociations : 0<br />
maxDISPAssociations : 0<br />
dAPAssociationTimeout : 0<br />
dSPAssociationTimeout : 0<br />
dOPAssociationTimeout : 0<br />
dISPAssociationTimeout : 0<br />
dSAActiveAssociations : 0<br />
pagedResultsMaxIDs : 0<br />
pagedResultsTimer : 0<br />
supportedApplicationContexts : (Not decoded)<br />
sdfasf : -0<br />
Monitoring the <strong>Directory</strong> 9–11
Chapter<br />
10<br />
Using DXtools<br />
The DXtools provide a sophisticated set of utilities that simplify the management<br />
of directory data and databases. These utilities can be divided into the following<br />
general categories:<br />
Database Tools<br />
Simplify the management of the underlying Advantage Ingres databases and<br />
the tables used by the DSAs, and provide a high performance, high volume<br />
data import and export capability.<br />
LDIF Tools<br />
Convert and manipulate data using a format appropriate for import to the<br />
directory.<br />
DAP Tools<br />
Provide an X.500 DAP interface for importing and exporting data to/from a<br />
directory.<br />
Schema Tools<br />
Simplify the extraction of schema from LDAP directories, and the conversion<br />
of schema into a format appropriate for <strong>eTrust</strong> <strong>Directory</strong> and for use by the<br />
DXtools.<br />
Note: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
Together, these tools:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Provide a fast start to any directory project, letting you easily load existing<br />
data for demonstration and prototyping.<br />
Provide the means for managing directory data on an ongoing basis.<br />
Can operate locally on the host Windows or UNIX server or execute from a<br />
Windows client workstation to a directory server over a TCP/IP network.<br />
Provide a migration path, a method, or both, for controlled exchange of data<br />
when DSP is not appropriate.<br />
Can be incorporated into your custom scripts. All tools return zero on<br />
success and non-zero when an error occurs.<br />
Using DXtools 10–1
Database Tools<br />
Database Tools<br />
The database tools provide a set of utilities that simplify the creation and<br />
management of directory databases and the DSA tables.<br />
Important! The RDBMS (Advantage Ingres) must be running for the database tools to<br />
execute successfully.<br />
The database tools are:<br />
DXnewdsa<br />
Creates a new DSA configuration, generating the initialization, database, and<br />
knowledge files, and creating the database if necessary<br />
DXnewdb<br />
Creates a new database including the tables that DXserver requires<br />
DXextenddb<br />
Adds extra Advantage Ingres locations to a database<br />
DXdestroydb<br />
Destroys an existing database<br />
DXemptydb<br />
Destroys all data in a database<br />
DXbackupdb<br />
Creates a checkpoint of a database<br />
DXrestoredb<br />
Recovers a database from the last checkpoint<br />
DXtunedb<br />
Modifies indexes and collects statistics and tunes a database<br />
DXindexdb<br />
Adds or removes wide indexes, certificate component indexes, and reverse<br />
indexes<br />
DXstatdb<br />
Displays statistics for a database<br />
DXlistdb<br />
Displays a list of databases owned by the user<br />
DXadduser<br />
Adds a new database administrator<br />
10–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
DXdeluser<br />
Deletes an existing database administrator<br />
DXloaddb<br />
Loads (or reloads) an existing database from an LDIF file<br />
DXdumpdb<br />
Extracts data from a database into an LDIF file<br />
DXgrantdb<br />
Grants a particular user access to a database<br />
DXupgradedb<br />
Migrates the database to the current version<br />
DXdisp<br />
Initializes multiwrite DISP recovery<br />
DXcertgen<br />
Reports on currently configured certificates and generates new DSA<br />
personality certificates.<br />
Using DXtools 10–3
Database Tools<br />
Creating a DSA: DXnewdsa<br />
You can create a new DSA configuration with the DXnewdsa tool using the<br />
following command:<br />
dxnewdsa dsaname dbname port [prefix]<br />
where:<br />
■<br />
■<br />
■<br />
■<br />
dsaname is the name of the DSA<br />
dbname is the name of the database<br />
port is the port number of the DSA<br />
prefix is the DSA prefix<br />
For example:<br />
dxnewdsa mydsa mydb 12345 c AU o DemoCorp ou Sales<br />
Example output:<br />
Checking if the Ingres database mydb exists...<br />
The Ingres database mydb doesn't exist. Using dxnewdb to create it...<br />
Creating database 'mydb' . . .<br />
Creating DBMS System Catalogs . . .<br />
Modifying DBMS System Catalogs . . .<br />
Creating Standard Catalog Interface . . .<br />
Creating Front-end System Catalogs . . .<br />
Creation of database 'mydb' completed successfully.<br />
New database created<br />
>> Disconnecting...<br />
>> Connecting to database 'iidbdb'...<br />
>> Connecting to database 'mydb'...<br />
>> Creating DIT table...<br />
>> Creating TREE table...<br />
>> Creating NAME table...<br />
>> Creating SEARCH table...<br />
>> Creating SUBSEARCH table...<br />
>> Creating ENTRY table...<br />
>> Creating BLOB table...<br />
>> Creating ATTR table...<br />
>> Creating SUBATTR table...<br />
>> Creating ALIAS table...<br />
>> Creating INFO table...<br />
>> Creating DISP table...<br />
>> Creating DISPMODDN table...<br />
>> Disconnecting...<br />
>> Disconnecting...<br />
Tuning system catalogs...<br />
Writing the database file...<br />
Database file written<br />
Writing the knowledge file...<br />
knowledge file written<br />
Writing the initialization file...<br />
Initialization file written<br />
Starting the DSA...<br />
The DSA started.<br />
10–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Creating a Database: DXnewdb<br />
To create a new database with the DXnewdb tool, use the following command:<br />
dxnewdb dbname<br />
where dbname is the name of the database.<br />
Extending a Database: DXextenddb<br />
You can extend a database’s storage over multiple locations with the<br />
DXextenddb utility using the following command:<br />
dxextenddb dbname fileArea locationName<br />
where:<br />
■<br />
■<br />
■<br />
dbname is the name of the database to extend<br />
fileArea is the directory under which to create the additional location (must<br />
be the absolute path name)<br />
locationName is the name of the additional location<br />
The DXextenddb utility is commonly used to increase the size of the database<br />
over the current 2 GB limit for a location.<br />
Adding Multiple<br />
Extensions<br />
To add multiple extensions, run DXextenddb multiple times. After you have<br />
added all the required extensions, run DXtunedb with either the -relocate or -<br />
full option. For example, on UNIX, you could use the following commands:<br />
su – ingres<br />
dxextenddb demo1 /local/ingres location2<br />
dxextenddb demo1 /local/ingres location3<br />
su – dsa<br />
dxtunedb -relocate demo1<br />
On Windows, you could use the following commands:<br />
dxextenddb sampledsa c:\newlocation location2<br />
dxtunedb -relocate sampledsa<br />
Important! To run DXextenddb, you must be logged in as the Advantage Ingres user<br />
(UNIX only).<br />
Using DXtools 10–5
Database Tools<br />
Destroying a Database: DXdestroydb<br />
You can destroy a database that is no longer required with the DXdestroydb<br />
utility using the following command:<br />
dxdestroydb dbname<br />
where dbname is the name of the database to be destroyed.<br />
WARNING! The DXdestroydb utility removes all directory information in the database.<br />
If you want to remove all directory information but keep the database, use DXemptydb<br />
instead.<br />
Important! This command also destroys checkpoints (backups) associated with the<br />
database.<br />
Emptying a Database: DXemptydb<br />
You can remove all the data from a database that is no longer required with the<br />
DXemptydb utility using the following command:<br />
dxemptydb dbname<br />
where dbname is the name of the database.<br />
WARNING! The DXemptydb utility removes all data from all of the tables in the<br />
database.<br />
This utility differs from DXdestroydb because DXemptydb does not destroy the<br />
database; it leaves the database tables ready to accept new data.<br />
We recommend that you first create a backup of the database using DXbackupdb<br />
before issuing the DXemptydb command.<br />
10–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Backing Up a Database: DXbackupdb<br />
The DXbackupdb utility creates a checkpoint of the specified database. You can<br />
execute the DXbackupdb utility using the following command:<br />
dxbackupdb [+journal|-journal] [-keepold] [-deleteoldest] dbname<br />
where:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
dbname is the name of the database<br />
+journal turns journaling on<br />
-journal turns journaling off<br />
-keepold keeps previous checkpoints<br />
-deleteoldest deletes the oldest checkpoint<br />
Important! The backup performs a database checkpoint. There must be sufficient disk<br />
space available to save this checkpoint. Note that journaling requires additional storage.<br />
Using the +journal and -journal options, you can enable or disable database<br />
journaling to maintain a log of all changes made since the last checkpoint. Once<br />
you turn journaling on, it stays on until you issue the dxbackupdb command and<br />
the -journal option. For example:<br />
dxbackupdb demo<br />
dxbackupdb +journal demo<br />
:<br />
dxbackupdb demo<br />
:<br />
dxbackupdb -journal demo<br />
(no journaling)<br />
(journaling is turned on)<br />
(journaling is still on)<br />
(journaling is turned off)<br />
Tip: To turn journaling off, the database must be offline before you run the<br />
dxbackupdb command with the -journal option. If you run DXloaddb or<br />
DXindexdb, you must explicitly turn journaling back on (dxbackupdb<br />
+journal) with the database offline in order to resume journaling for all<br />
tables.<br />
You can run the DXbackupdb utility when the DSA is online.<br />
Important! Backups of the database are extremely important. See the chapter<br />
“Deploying a <strong>Directory</strong>” for more information.<br />
Using DXtools 10–7
Database Tools<br />
Restoring a Database: DXrestoredb<br />
The DXrestoredb utility restores a database from a previously created<br />
checkpoint. You can execute the DXrestoredb utility using the following<br />
command:<br />
dxrestoredb [+/-journal] [-list] [-fromold checkpointNumber] dbname<br />
where:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
dbname is the name of the database to restore<br />
+journal replays the journals after the checkpoint is restored<br />
-journal restores the checkpoint without replaying the journals<br />
-list lists valid checkpoints.<br />
-fromold checkpointNumber restores from an older backup (the default is the<br />
most recent backup taken)<br />
Tip: We recommend that you perform daily backups, usually at night. When<br />
performing a restore, all DSAs that connect to the database must be shut<br />
down.<br />
10–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Tuning a Database: DXtunedb<br />
When populating or updating the directory, you can improve the performance of<br />
the directory services by running the DXtunedb utility. You can execute the<br />
DXtunedb utility with the following command:<br />
dxtunedb [-full | -relocate] dbname<br />
where dbname is the name of the database to tune.<br />
The DXtunedb utility modifies the indexes, and updates statistics used by the<br />
query optimizer.<br />
You can run the DXtunedb utility when the DSA is online, except with the -full<br />
option. However, it is better to tune when DSAs are not busy because tuning<br />
consumes CPU.<br />
Run a Full Tune<br />
The DXtunedb utility has two options: -full and -relocate. The -full option<br />
provides a more comprehensive tuning of the database. To run a full tune, use<br />
the following command:<br />
dxtunedb -full dbname<br />
where dbname is the name of the database.<br />
Tip: The DXtunedb utility with the -full option tunes all tables, indexes,<br />
system tables, and statistics. All DSAs that connect to the database must be<br />
shut down.<br />
Enable New Locations<br />
The -relocate option enables the use of the new locations created by<br />
DXextenddb. Use the following command:<br />
dxtunedb -relocate dbname<br />
where dbname is the name of the database to be relocated.<br />
Relocating a database is faster than performing a full tune, but less extensive in<br />
terms of optimization.<br />
Important! This option does not update statistics.<br />
Using DXtools 10–9
Database Tools<br />
Managing Indexes: DXindexdb<br />
The DXindexdb utility is used to add, clear or list the following indexes:<br />
■<br />
■<br />
■<br />
■<br />
Reverse indexes<br />
Certificate component indexes<br />
Certificate Revocation List (CRL) indexes<br />
Wide indexes<br />
The DXindexdb utility uses the following syntax:<br />
dxindexdb dbname [[+ | -]reverse [attrList]]<br />
| [[+ | -]cert [componentList]]<br />
| [[+ | -]crl [componentList]]<br />
| [[+ | -]wide [attrList]]<br />
where dbname is the name of the database.<br />
Applying a reverse index to an attribute stores each value of that attribute in<br />
reverse order. This aids substring searches of the type (attr=*val).<br />
Only the first 106 characters of a value are significant in a search. If this is not<br />
adequate, or you receive a warning to this effect in the log file, you can apply a<br />
wide index to those attributes. For more information about wide indexes, see<br />
Indexing Options in the chapter “General Administration.”<br />
List Indexed Attributes,<br />
Certificate/crl<br />
Components<br />
To list the currently indexed attributes, certificate/crl components and give a<br />
list of attributes and components for indexing, specify dxindexdb with only the<br />
database name:<br />
dxindexdb demo<br />
where demo is the database name.<br />
Example output:<br />
Reverse indexed attributes:<br />
telephoneNumber<br />
Component indexed attributes:<br />
certificate(cert_version cert_issuer validity)<br />
certificateList(crl_version crl_issuer)<br />
Other attributes:<br />
oc aliasedEntryName userPassword createTimestamp countryName<br />
organizationName department givenName surname commonName<br />
multiLineDescription cosineRfc822Mailbox<br />
Other components:<br />
certificate(serialNumber cert_signature subject subjectPublicKeyInfo<br />
issuerUniqueIdentifier etc...)<br />
certificateList(thisUpdate nextUpdate etc...)<br />
10–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Clear Existing Indexes<br />
Add Reverse-Index<br />
Attributes<br />
To clear all the existing reverse, wide, and certificate/CRL indexes, use any of<br />
the options with no arguments:<br />
dxindexdb demo –reverse<br />
dxindexdb demo –cert<br />
dxindexdb demo -crl<br />
To create one or more reverse-index attributes, use the -reverse option followed<br />
by a space-separated list of the attributes:<br />
dxindexdb demo -reverse attribute1 attribute2<br />
Note: This will clear any previous reverse indexes.<br />
To add one or more reverse-index attributes to an existing set, use the +reverse<br />
option followed by a space-separated list of attributes:<br />
dxindexdb demo +reverse attribute1 attribute2<br />
This will add the new reverse indexes to the previous reverse indexes.<br />
Add Certificate<br />
Component Indexes<br />
To create one or more certificate component indexes, use the -cert option<br />
followed by a space-separated list of the components:<br />
dxindexdb demo -cert component1 component2<br />
Note: This will clear any previous certificate component indexes.<br />
To add one or more certificate component indexes to an existing set, use the +cert<br />
option followed by a space-separated list of components:<br />
dxindexdb demo +cert component1 component2<br />
This will add the new certificate component indexes to the previous certificate<br />
component indexes.<br />
Add crl Component<br />
Index<br />
To create one or more CRL component indexes, use the -crl option followed by<br />
a space-separated list of the components:<br />
dxindexdb demo -crl component1 component2<br />
Note: This will clear any previous crl component indexes.<br />
To add one or more CRL component indexes to an existing set, use the +crl<br />
option followed by a space-separated list of components:<br />
dxindexdb demo +crl component1 component2<br />
This will add the new CRL component indexes to the previous CRL component indexes.<br />
Using DXtools 10–11
Database Tools<br />
Add Reverse and<br />
Component Index<br />
When both reverse and component indexing is required, a single command<br />
must be used to set up the indexes:<br />
dxindexdb demo -reverse attribute1 attribute2 -cert component1 component2<br />
If a reverse index is added using the following command, all component indexes<br />
will be removed:<br />
dxindexdb demo -reverse attribute1<br />
Add Wide Index<br />
Add Reverse and<br />
Wide Index<br />
To add a wide index to one or more attributes, use the following command:<br />
dxindexdb demo -wide attribute1 attribute2<br />
When both reverse and wide indexing is required, use the following command:<br />
dxindexdb demo -reverse attribute1 attribute2 -wide attribute1 attribute2<br />
10–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Displaying Database Statistics: DXstatdb<br />
The DXstatdb utility displays statistics of a particular database. The DXstatdb<br />
utility has the following format:<br />
dxstatdb [-cert] [-d] dbname<br />
where:<br />
■ dbname is the name of the database for which statistics will be generated<br />
■<br />
■<br />
-cert lists the statistics for the certificates stored in the database<br />
-d includes statistics for entries marked as deleted<br />
List Database Statistics<br />
You can list the statistics for the database by using the following command:<br />
dxstatdb dbname<br />
The following is a sample output:<br />
Statistics:<br />
Number of attributes types = 27<br />
Number of entries = 104472<br />
Number of node entries = 4424<br />
Number of leaf entries = 100048<br />
Number of alias entries = 0<br />
Number of level 1 entries = 12<br />
Number of level 2 entries = 58<br />
Number of level 3 entries = 341<br />
Number of level 4+ entries = 104061<br />
Number of values = 709281<br />
Number of blob (>2K) values = 0<br />
List Certificate<br />
Statistics<br />
You can list the statistics for the certificates stored in the database with this command:<br />
dxstatdb -cert dbname<br />
The following is a sample output:<br />
Certificate Statistics:<br />
Number of userCertificate = 1<br />
Number of userCertificate issuers = Not Indexed<br />
Number of expired userCertificate = Not Indexed<br />
Number of not yet valid userCertificate = Not Indexed<br />
If there are <strong>CA</strong> Certificates and CRLs in the directory, the following output appears<br />
(note that this output shows that the <strong>CA</strong> Certificate has a component index):<br />
Certificate Statistics:<br />
Number of userCertificate = 1<br />
Number of userCertificate issuers = Not Indexed<br />
Number of expired userCertificate = Not Indexed<br />
Number of not yet valid userCertificate = Not Indexed<br />
Number of cACertificate = 1<br />
Number of cACertificate issuers = 0<br />
Number of expired cACertificate = 0<br />
Number of not yet valid cACertificate = 0<br />
Number of certificateRevocationList = 1<br />
Number of certificateRevocationList issuers = Not Indexed<br />
Number of expired certificateRevocationList = Not Indexed<br />
Number of not yet valid certificateRevocationList = Not Indexed<br />
Using DXtools 10–13
Database Tools<br />
List Deleted Entries<br />
By default, the dxstatdb command ignores entries marked as deleted in the<br />
database when reporting its statistics.<br />
This is useful because two synchronized databases could give different statistics<br />
because entries marked as deleted in a DISP shadow were being counted, but not<br />
on the master.<br />
To include entries marked as deleted in the listed statistics, use the '-d' option:<br />
dxstatdb -d dbname<br />
Listing Existing Databases: DXlistdb<br />
List Databases Owned<br />
by User<br />
The DXlistdb utility lists the databases owned by the user. (The user must be a<br />
database administrator—typically, the user who has created the database.) You<br />
can execute the DXlistdb utility using the following command:<br />
dxlistdb [dbname]<br />
The output of a dxlistdb command is a list of database names, such as:<br />
backup<br />
demo<br />
live<br />
test<br />
Test Database<br />
Existence<br />
You can test for the existence of a particular database by specifying the database<br />
name as an optional parameter to the dxlistdb command:<br />
dxlistdb mydatabase<br />
If the database mydatabase does not exist then DXlistdb will return an error code.<br />
Adding a Database User: DXadduser<br />
You can create a new database administrator with the DXadduser utility using<br />
the following command (this command is generally used only during<br />
installation):<br />
dxadduser dbadmin<br />
where dbadmin is the name of the new database administrator.<br />
Note: When dbadmin contains spaces, you must use quotation marks, for<br />
example, “Fred Bloggs.”<br />
10–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Deleting a Database User: DXdeluser<br />
You can delete a database administrator with the DXdeluser utility using the<br />
following command:<br />
dxdeluser dbadmin<br />
where dbadmin is the name of the database administrator.<br />
Note: When dbadmin contains spaces, you must use quotation marks, for<br />
example, “Fred Bloggs.”<br />
Using DXtools 10–15
Database Tools<br />
Loading a Database: DXloaddb<br />
Use the DXloaddb tool to load or reload a database from a prepared LDIF file.<br />
This utility used to use schema.txt file to get schema information. It now loads<br />
schema information directly from the DSA. This means that you now have to<br />
specify the DSA name when you use the DXloaddb tool. The same change has<br />
been made to DXdumpdb.<br />
The command is:<br />
dxloaddb options ldif-file dbname<br />
The following are the options of the dxloaddb command:<br />
Option<br />
Description<br />
-p prefix The prefix of the DSA. Use a comma-separated LDAP format.<br />
Use a pair of quotes “” for a NULL DN.<br />
If a portion of prefix is more than one word, you can enclose the whole prefix in<br />
quotes or just the problem portion. For example, both of these prefixes will<br />
work:<br />
■<br />
■<br />
o=“democorp test”,c=au<br />
“o=democorp test,c=au”<br />
-O Includes standard operational attributes during the load.<br />
-P Hashes or encrypts passwords if in clear text:<br />
0: OEM hash algorithm. This option is deprecated - use SHA-1 instead.<br />
1: SHA-1 (default)<br />
2: Salted SHA-1. This produces a different hash even for the same clear text<br />
password, which is more secure.<br />
3: OEM-reversible crypt algorithm (therefore less secure)<br />
4: Traditional UNIX crypt algorithm<br />
5: MD5 password hashing<br />
-I "not-searchable<br />
"<br />
Prevents the attributes listed from loading into the search table, which reducing<br />
the size of the search table. Small table size means less disk space used, faster<br />
tuning, and faster loading. Also, update operations are faster on these attributes.<br />
Search operations containing these attributes will return empty results. The list<br />
of attributes must match those set in the database configuration file. For<br />
information about how to make attributes not searchable, see Indexing Options<br />
in the chapter “General Administration.”<br />
10–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Option<br />
Description<br />
-a attributes The estimated average number of attributes per entry. This corresponds to the<br />
average number of lines per entry in the LDIF file.<br />
-n entries The estimated number of entries.<br />
-S dsaname The DSA server with the schema definitions that the DXloaddb tool will use.<br />
database<br />
If you do not include this option, the DXloaddb tool parses the various<br />
DXserver configurations to find the one that connects to the database specified.<br />
The name of the database to load.<br />
WARNING! If you use this option, all existing directory information in the database<br />
will be lost.<br />
The following are the parameters of the dxloaddb command:<br />
Parameter<br />
ldif-file<br />
dbname<br />
Description<br />
The name of the LDIF file to use.<br />
The name of the database to load.<br />
The number of entries and the number of rows per entry are used to estimate the<br />
size of each database table in advance. This enables the database to allocate the<br />
appropriate resources before the load commences, greatly reducing load time.<br />
The correct sequence in which to create and load a database is:<br />
dxnewdb<br />
dxextenddb<br />
dxloaddb<br />
(as many times as needed)<br />
Note: There is no need to reorganize or tune the database since this is done<br />
automatically as part of the DXloaddb process. Sort the LDIF file by<br />
distinguished name, in ascending order.<br />
The following example loads the data from democorp.ldif file to database<br />
democorp:<br />
dxloaddb –p "o=democorp test,c=au" -I "not-searchable<br />
createTimestamp,userPassword" -S democorp democorp.ldif democorp<br />
In this example, “o=democorp test,c=au” is the DN prefix, and the<br />
createTimestamp and userPassword attributes are not searchable.<br />
Using DXtools 10–17
Database Tools<br />
Dumping a Database: DXdumpdb<br />
Use the DXdumpdb utility to extract the data from a database to an LDIF file.<br />
This utility used to use schema.txt file to get schema information. It now loads<br />
schema information directly from the DSA. This means that you now have to<br />
specify the DSA name when you use DXdumpdb. The same change has been<br />
made to the DXloaddb tool.<br />
The command is:<br />
dxdumpdb options dbname [attributes]<br />
The following are the options of the dxdumpdb command:<br />
Option<br />
Description<br />
-p prefix The prefix of the DSA. Use a comma-separated LDAP format.<br />
If a portion of prefix is more than one word, you can enclose the whole prefix<br />
in quotes or just the problem portion. For example, both of these prefixes will<br />
work:<br />
■<br />
■<br />
o=“democorp test”,c=au<br />
“o=democorp test,c=au”<br />
The prefix you specified doesn’t have to be the same as in the database. That is,<br />
you can change the prefix to suit your needs.<br />
-Z schema Uses the schema file specified.<br />
-f outfile Dumps the data to the specified file.<br />
-i Includes attributes.<br />
-O Includes standard operational attributes.<br />
-x Excludes attributes.<br />
-v Run in verbose mode. This switches on error/status tracing.<br />
-l Locks the database while doing the dump.<br />
-u Username used to connect to the database.<br />
-P passwd The user’s Advantage Ingres password.<br />
-E eidlist Dumps only the entries specified. Eidlist is a comma-separated entry id list, for<br />
example, “0,1,2…9”.<br />
-S dsaname The DSA server with the schema definitions that DXdumpdb will use.<br />
If you do not include this option, DXdumpdb parses the various DXserver<br />
configurations to find the one that connects to the database specified.<br />
10–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
The following are the parameters of the dxdumpdb command:<br />
Parameter<br />
dbname<br />
attributes<br />
Description<br />
The name of the database to dump.<br />
Space-separated list of attributes that you want to include or exclude in the<br />
dump (if no attribute list is given, you dump all).<br />
The following example extracts the LDIF format data from database democorp<br />
on the screen, using the o=”democorp test”,c=au DN prefix, and excludes the<br />
createTimstamp and userPassword attributes in the output.<br />
Dxdumpdb –p o=”democorp test”,c=au –x democorp -S democorp createTimestamp<br />
userPassword<br />
The following example extracts the first three entries from database democorp to<br />
the out.ldif file, using the o=”democorp test”,c=au DN prefix.<br />
Dxdumpdb –p o=Admin,c=au –f out.ldif -S democorp –E 0,1,2 democorp<br />
Granting Access to a Database: DXgrantdb<br />
Use this command to grant a nominated user access to a database with the<br />
DXgrantdb utility:<br />
dxgrantdb dbname [user]<br />
where:<br />
■<br />
■<br />
dbname is the name of the database to which you are granting access<br />
user is the name of the user to whom you are granting access<br />
Note: If you omit the user name, all database users are granted access.<br />
Revoking Access to a Database: DXrevokedb<br />
Use this command to remove the permission for the nominated user to access a<br />
database with the DXrevokedb utility:<br />
dxrevokedb dbname [user]<br />
where:<br />
■<br />
■<br />
dbname is the name of the database to which access is revoked.<br />
user is the name of the user whose access is revoked.<br />
Note: If you omit the user name, all database users will have their access<br />
revoked.<br />
Using DXtools 10–19
Database Tools<br />
Upgrading Previous Versions of a Database: DXupgradedb<br />
After upgrading <strong>eTrust</strong> <strong>Directory</strong>, existing databases may require changes to<br />
enable new features to work. For example, you may need to add new tables,<br />
upgrade existing indexes, or update existing tables.<br />
To upgrade a database, use the following command:<br />
dxupgradedb dbname<br />
where dbname is the name of the database that you want to upgrade.<br />
Note: You must run DXupgradedb before starting the server.<br />
Initializing Multiwrite–DISP Recovery: DXdisp<br />
When multi-write-disp-recovery = TRUE, and you reload a DSA, or remove a<br />
DSA from the multiwrite-DISP configuration, you must clear the last update time<br />
using the following command:<br />
dxdisp -clear dsaname dbname<br />
where:<br />
■<br />
■<br />
dsaname is the name of the newly loaded or removed DSA<br />
dbname is the name of the database<br />
To list the last update times of all multiwrite-DISP peers recorded in the<br />
database, use the following command:<br />
dxdisp -list dbname<br />
where dbname is the name of the database for which you want to list the last<br />
update times.<br />
10–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Reporting On and Generating Certificates: DXcertgen<br />
The DXcertgen tool reports on currently configured certificates and generates<br />
new DSA personality certificates and directory user certificates.<br />
The command is:<br />
dxcertgen options [report|generate]<br />
The following are the options of the dxcertgen command:<br />
Option<br />
Description<br />
-d days Number of days certificate will be valid for(default days=365)<br />
-i issuer Generate root certificate with YOUR company's name (default:<br />
"CN=Certificate Authority,O=DXCertGenPKI,C=AU")<br />
-c clientcerts Path to client certificate and private key store (default:<br />
"$DXHOME/../jxplorer/security/clientcerts")<br />
-C clientpass Password for clientcerts keystore (default: )<br />
-s cacerts Path to <strong>CA</strong> certificate and private key store (default:<br />
"$DXHOME/../jxplorer/security/cacerts")<br />
-S capass Password for cacerts key store (default: )<br />
-u users LDIF file of users to generate certificates for<br />
-p path Write user certificates to path rather than keystore<br />
-P keypass Assign this password to protect private key (default: dxcertgen)<br />
The following are the parameters of the dxcertgen command:<br />
Parameter<br />
report<br />
certs<br />
Description<br />
Report on configured certificates<br />
Generate certificates for DSAs (and 'users' if specified)<br />
Using DXtools 10–21
Database Tools<br />
Reporting Certificates<br />
The certificate report shows who the subject of the certificate is, the Certificate<br />
Authority who issued it, validity dates and whether the certificate is currently<br />
valid.<br />
Where there are multiple certificates in a file, they are numbered in the order<br />
they are found. If you have to delete a certificate, use the report to determine<br />
which one to delete.<br />
To run a report on the currently configured certificates enter the command:<br />
dxcertgen report <br />
You will see a report like this:<br />
TRUSTED ROOT CERTIFI<strong>CA</strong>TES<br />
- trusted.pem -<br />
certificate : 1<br />
version : 3<br />
serialNum : 0<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:03 2003 GMT<br />
notAfter : May 27 01:36:03 2008 GMT<br />
subject : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
status : valid<br />
PERSONALITY CERTIFI<strong>CA</strong>TES<br />
- router.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 4<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:13 2003 GMT<br />
notAfter : May 27 01:36:13 2008 GMT<br />
subject : /C=AU/CN=DXserver<br />
status : valid<br />
- democorp.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 1<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:07 2003 GMT<br />
notAfter : May 27 01:36:07 2008 GMT<br />
subject : /C=AU/O=Democorp/CN=DXserver<br />
status : valid<br />
- uddi.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 5<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:15 2003 GMT<br />
notAfter : May 27 01:36:15 2008 GMT<br />
subject : /O=<strong>CA</strong>/CN=UDDI<br />
status : valid<br />
- unspsc.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 2<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:09 2003 GMT<br />
notAfter : May 27 01:36:09 2008 GMT<br />
subject : /C=AU/O=UNSPSC/CN=DXserver<br />
status : valid<br />
10–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
- ocsp.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 4<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : Jun 6 10:39:15 2000 GMT<br />
notAfter : Jun 5 10:39:15 2005 GMT<br />
subject : /C=AU/O=OCSP/CN=DXserver<br />
status : valid<br />
- sample.pem -<br />
certificate : 1<br />
version : 1<br />
serialNum : 3<br />
issuer : /C=AU/O=MiniPKI/CN=Certificate Authority<br />
notBefore : May 29 01:36:10 2003 GMT<br />
notAfter : May 27 01:36:10 2008 GMT<br />
subject : /C=AU/O=Sample/CN=DXserver<br />
status : valid<br />
Done.<br />
Generating Certificates<br />
To secure links between DSAs using SSL encryption or SSL authentication, each<br />
DSA needs a certificate, just as if it was a directory user. These are called DSA<br />
personality certificates, and are stored under<br />
$DXHOME/config/ssld/personalities.<br />
Note: To secure the system, the private key of the root certificate used to sign all<br />
the generated certificates is not stored or written out in any way.<br />
The tool generates a root certificate first, checks that it doesn't already exist in the<br />
$DXHOME/config/ssld/trusted.pem file, then appends the new root certificate<br />
to this file. It then uses the root certificate's private key to generate a new<br />
personality certificate for each configured DSA, using the DSA-NAME from the<br />
$DXHOME/config/knowledge file as the subject of the certificate. Any previous<br />
personalities will be overwritten.<br />
Using Your Company<br />
Name as the <strong>CA</strong> Issuer<br />
The default Certificate Authority issuer is hardcoded into the tool:<br />
CN=Certificate Authority,O=DXCertGenPKI,C=AU. To use your company<br />
name instead, just use the '-i issuer' option, and specify your company name as<br />
an LDAP DN.<br />
By default, the validity period for the certificates generated is 365 days, but you<br />
can change by using the -d option.<br />
Using DXtools 10–23
Database Tools<br />
Generating<br />
Certificates for <strong>eTrust</strong><br />
<strong>Directory</strong> Users<br />
To generate user certificates and private keys, use the -u option. This should be<br />
the complete path to an LDIF file of users. The user certificates will be<br />
generated using the same root certificate's private key as the DSA personalities.<br />
To write the user certificates and private keys to the file system, enter the<br />
command:<br />
dxcertgen -i "cn=Real Company Certificate Authority,o=Real Company PKI,c=au" -d<br />
730 -u $USERS_PATH/users.ldif -p $TEMP_PATH/users certs <br />
WARNING! The private keys that are written out are not password protected or<br />
encrypted in any way - they should be moved as soon as possible.<br />
Generating<br />
Personality<br />
Certificates for DSAs<br />
To generate personality certificates for currently configured DSAs, enter the<br />
command:<br />
dxcertgen -i "cn=Real Company Certificate Authority,o=Real Company PKI,c=au" -d<br />
730 certs <br />
You will see the following output:<br />
Generating a new trusted root certificate...<br />
Generating a 1024-bit RSA public/private key pair...<br />
...................................++++++<br />
...............++++++<br />
Appending trusted root certificate to<br />
/.../products/dxserver/config/ssld/trusted.pem...<br />
Generating dxserver personalities...<br />
Generating a new personality certificate for democorp.dxc...<br />
Generating a 1024-bit RSA public/private key pair...<br />
.............++++++<br />
....................................................++++++<br />
Writing personality certificate to<br />
/.../products/dxserver/config/ssld/personalities/democorp.pem...<br />
Generating a new personality certificate for router.dxc...<br />
Generating a 1024-bit RSA public/private key pair...<br />
.++++++<br />
................................++++++<br />
Writing personality certificate to<br />
/.../products/dxserver/config/ssld/personalities/router.pem...<br />
Generating a new personality certificate for unspsc.dxc...<br />
Generating a 1024-bit RSA public/private key pair...<br />
.++++++<br />
................................++++++<br />
Writing personality certificate to<br />
/.../products/dxserver/config/ssld/personalities/unspsc.pem...<br />
Done.<br />
10–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Database Tools<br />
Wiring User<br />
Certificates and<br />
Private Keys to a<br />
Secure Location<br />
To generate user certificates and private keys and write them to a more secure<br />
location, DXcertgen is able to use the keytool facility that ships with Java and<br />
JXplorer to add the certificates and private keys to a "keystore". The keystore is<br />
password protected and each private key is password protected as well. The<br />
certificates and keys are separated out into "client" or user certificates/keys and<br />
<strong>CA</strong>/self-signed/root certificates/keys.<br />
By default the tool writes the certificates and private keys to the JXplorer<br />
keystore, but you can specify alternate keystores. To specify an alternate keystore<br />
for <strong>CA</strong> certs, use the '-s cacerts' option to enter the complete path to the <strong>CA</strong><br />
keystore. Don't forget to specify the <strong>CA</strong> certificates keystore password using '-S<br />
capass'. To specify an alternate keystore for client certificates, use the '-c<br />
clientcerts' option. Don't forget to specify the client certificates keystore<br />
password using the '-C clientpass' option.<br />
Specifying an<br />
Alternate Private Key<br />
Password<br />
To specify an alternate private key password use the '-P keypass' option.<br />
Note: JAVA_HOME must be set because the tool must run<br />
$JAVA_HOME/bin/keytool to add the certificates and private keys to the<br />
keystore.<br />
To write certificates to the JXplorer keystore, enter the command:<br />
dxcertgen -u "%DXHOME%\samples\democorp\users.ldi" certs<br />
Generating a new trusted root certificate...<br />
Generating a 1024-bit RSA public/private key pair...<br />
....................++++++<br />
Appending trusted root certificate to D:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxser<br />
ver\config\ssld\trusted.pem...<br />
Adding alias 'trusted' to keystore...<br />
Certificate was added to keystore<br />
Generating dxserver personalities...<br />
Generating a new personality certificate for router.dxc...<br />
Generating a 1024-bit RSA public/private key pair...<br />
....................................++++++<br />
Writing personality certificate to D:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxserver<br />
\config\ssld\personalities\router.pem...<br />
Generating a new personality certificate for unspsc.dxc...<br />
Generating a 1024-bit RSA public/private key pair...<br />
..................................................++++++<br />
Writing personality certificate to D:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxserver<br />
\config\ssld\personalities\unspsc.pem...<br />
Generating user certificates...<br />
Generating a new user certificate for Nadia_KITE...<br />
Generating a 1024-bit RSA public/private key pair...<br />
..++++++<br />
................................................++++++<br />
Adding alias 'Nadia_KITE' to keystore...<br />
Certificate was added to keystore<br />
Generating a new user certificate for Jodie_LAY...<br />
Generating a 1024-bit RSA public/private key pair...<br />
Using DXtools 10–25
Database Tools<br />
................................................++++++<br />
.......................++++++<br />
Adding alias 'Jodie_LAY' to keystore...<br />
Certificate was added to keystore<br />
Generating a new user certificate for Vivienne_LEVER...<br />
Generating a 1024-bit RSA public/private key pair...<br />
....++++++<br />
.......................................++++++<br />
Adding alias 'Vivienne_LEVER' to keystore...<br />
Certificate was added to keystore<br />
Generating a new user certificate for Juliet_LEVY...<br />
Generating a 1024-bit RSA public/private key pair...<br />
...................++++++<br />
.++++++<br />
Adding alias 'Juliet_LEVY' to keystore...<br />
Certificate was added to keystore<br />
Generating a new user certificate for Craig_LINK...<br />
Generating a 1024-bit RSA public/private key pair...<br />
..................++++++<br />
......++++++<br />
Adding alias 'Craig_LINK' to keystore...<br />
Certificate was added to keystore<br />
Generating a new user certificate for Gavin_LOWE...<br />
Generating a 1024-bit RSA public/private key pair...<br />
................++++++<br />
................................................++++++<br />
Adding alias 'Gavin_LOWE' to keystore...<br />
Certificate was added to keystore<br />
Done.<br />
10–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
LDIF Tools<br />
LDIF Tools<br />
The DXtools manage directory data using the LDAP Data Interchange Format<br />
(LDIF). The LDIF file format is suitable for describing directory information or<br />
modifications made to directory information. It is often used for transferring<br />
directory information between LDAP-based directory servers or describing a set<br />
of changes applied to a directory.<br />
This section describes how you can transfer comma-separated value (CSV) data<br />
files into LDIF directory files using the data conversion tools.<br />
The data conversion tools are:<br />
csv2ldif<br />
Uses the CSV data file and the LDIF template file to prepare an LDIF file for<br />
the dxmodify tool<br />
ldifsort<br />
Sorts an LDIF file or input stream on the given attribute type<br />
ldifdelta<br />
Calculates the change, or delta, between two LDIF files<br />
CSV Source Data<br />
A source data file is a comma-separated list of values. Each source data (CSV) file<br />
can contain many lines, and each line in the file should contain information<br />
about a single object or entry.<br />
DXtools Example 1<br />
CSV Data File<br />
Fred,Jones,Manager,Administration,987 6254<br />
Tom,Smith,Sales Person,Sales,987 6251<br />
Bill,Smith,Foreman,Manufacturing,987 6257<br />
Ken,Anderson,Account Manager,Sales,987 6255<br />
Wendy,Murphy,Clerk,Administration,987 6233<br />
Ann,Thompson,Receptionist,Administration,987 6222<br />
Ian,Hall,Boilermaker,Manufacturing,987 6510<br />
Linda,Bates,Accountant,Administration,987 6511<br />
Sam,Campbell,Welder,Manufacturing,987,6510<br />
Using DXtools 10–27
LDIF Tools<br />
While the default separator is a comma, the DXtools support the use of<br />
alternative and user-defined separators. See Converting CSV Data to LDIF<br />
Format: csv2ldif in this chapter for more information.<br />
You should enclose embedded commas within quotes. For example, if Tom<br />
Smith's address is contained as a single field, you can include embedded commas<br />
in the single address field as shown below:<br />
Tom,Smith,"36 High Street,Boystown,NY"<br />
To accommodate embedded quotation marks, as when applied to a property<br />
name in an address field, always use two sequential quotation marks to<br />
represent a single quotation mark in text. For example, if Tom Smith used his<br />
property name “The Grange” in his address:<br />
Tom,Smith,"""The Grange"",High Street,Boystown,NY"<br />
Template Files (LDT)<br />
The information contained in a data file is simply a list of values. To give<br />
meanings to these values, you must specify what the values in each field<br />
represent. To do this, define an LDIF template (LDT) file.<br />
The LDT files describe the objects contained in the directory. The LDT file<br />
follows the LDIF file format, which is used to add directory information to the<br />
data values. An LDIF file consists of a series of records separated by blank lines.<br />
A record consists of a sequence of lines describing a directory entry. Special<br />
substitution tokens are used to place fields from the CSV file into the LDT.<br />
Each line in the LDT file defines a rule that links a field in a CSV data file to a<br />
directory attribute or name with an object description. These rules let the tools<br />
translate CSV file information into LDIF file formats.<br />
DXtools Example 2<br />
A sample LDIF Template File<br />
# Acme template file - LDIF format<br />
dn:ou=$4, o="Acme", c=US<br />
oc:organizationalUnit<br />
dn:cn=$1 $2, ou=$4, o="Acme", c=US<br />
oc:organizationalPerson<br />
surname:$2<br />
title:$3<br />
telephonenumber:+61 3 $5<br />
10–28 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
LDIF Tools<br />
The Format of LDT files<br />
Each record in an LDT file specifies the format of entries at that level. Each<br />
record contains a DN and one or more attribute-value template lines.<br />
You can treat the $ character literally when the escape character (\) precedes it.<br />
This escape character has no significance other than escaping. Use \\ to<br />
represent the \ character.<br />
Using substitution tokens in the DN line lets you specify leaf nodes and their<br />
parents. You can therefore infer hierarchy from the original CSV data. You must<br />
explicitly code parent objects in the template file, and they must appear in<br />
increasing-depth order in the file before any definition of leaf objects.<br />
If you need a literal number following a substitution token, you can use the<br />
three-digit form of the token as in the following example (the three-digit form is<br />
shown underlined):<br />
# leaf node<br />
dn:cn=$1 $2,ou=$4, o=DemoCorp,c=AU<br />
oc:organizationalPerson<br />
Surname:$2<br />
Description: $00199 \$ $2 \$ $3<br />
Telephone:+61 $3<br />
A substitution token cannot exceed three digits (maximum is $999). When this<br />
LDT file is interpreted, the $00199 looks at the first three digits after the $ (in this<br />
example $001 is equal to $1), so the program finds the first column of the CSV to<br />
substitute, and appends "99" characters to it. If you use $199 rather than $00199,<br />
the 199 th column of the CSV is used to substitute, which is not the intention of<br />
this example.<br />
LDIF Files<br />
Using the LDIF format, you can convey directory information or a description of<br />
a set of changes made to directory entries. An LDIF file consists of a series of<br />
records with line separators. Each record consists of a sequence of lines<br />
describing either a directory entry or a set of changes to a single directory entry.<br />
These two types of records cannot be mixed in an LDIF file. An LDIF file contains<br />
either records that specify a set of directory entries or records that specify a set of<br />
changes you apply to directory entries, but not both.<br />
For further information about the LDIF format, review the Internet Engineering<br />
Task Force (IETF) draft Request For Comments (RFCs) available at<br />
http://www.ietf.org.<br />
Using DXtools 10–29
LDIF Tools<br />
Converting CSV Data to LDIF Format: csv2ldif<br />
The csv2ldif tool uses the CSV data file and the template LDT file described in the<br />
preceding two sections to prepare an LDIF file for the DXmodify tool.<br />
The format is:<br />
csv2ldif options numfields LDTfile CSVfile<br />
The following are the options of the csv2ldif command:<br />
Option<br />
Description<br />
-b badfile Output file name for CSV lines with bad format.<br />
-d Permits duplicate parent nodes to be generated.<br />
-f branching factor The number of branching factors. The default is 32.<br />
Note: This is a low-level option and should not be used unless directed by<br />
Computer Associates Technical Support.<br />
-i lines Ignores the first lines lines of the CSV file.<br />
-s sep Defines a field separator (default is a comma)<br />
The following are the parameters of the csv2ldif command:<br />
Parameter<br />
Numfields<br />
LDTfile<br />
CSVfile<br />
Description<br />
Total number of fields defined in the input CSV file.<br />
Name of the LDT file.<br />
Name of the input CSV file.<br />
DXtools Example 3<br />
csv2ldif<br />
Using the example CSV data file and the LDT file, you can execute the csv2ldif<br />
utility using the following command:<br />
csv2ldif -i 1 7 acme.ldt acme.csv > acme.ldi<br />
The file acme.ldt contains the specification and translation rules. The file<br />
acme.csv contains the raw data in comma-separated value format. The CSV file is<br />
defined as having seven fields with the first line ignored.<br />
10–30 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
LDIF Tools<br />
The output is redirected to the acme.ldi file. The following is a portion of<br />
acme.ldi:<br />
dn: o=Acme, c=US<br />
oc: organization<br />
dn: ou=Administration, o=Acme, c=US<br />
oc: organizationalUnit<br />
dn: cn=Fred Jones, ou=Administration, o=Acme, c=US<br />
oc: organizationalPerson<br />
postalAddress: 11 Main Street $ Newtown<br />
surname: Jones<br />
title: Manager<br />
telephonenumber: +1 (305) 987 6254<br />
dn: ou=Sales, o=Acme, c=US<br />
oc: organizationalUnit<br />
Sorting an LDIF File: ldifsort<br />
The ldifsort program sorts an LDIF file or input stream for the given attribute<br />
type. The default sort is DN, which sorts LDIF records based on their<br />
distinguished names. In DN sort mode, ldifsort ensures that each record is<br />
followed by its immediate subordinates.<br />
The other sort option is to sort in descending order. You can use this option, for<br />
example, when deleting the entries in an LDIF file from the directory. This sorts<br />
the LDIF file on DN in descending order, thus ordering subordinates before<br />
superior entries. The LDIF file can then be passed to DXmodify to delete these<br />
entries.<br />
Note: By default, duplicate entries are ignored or written to the bad record file<br />
(-b file). If you do not want to ignore duplicate entries, use the -U option.<br />
By default, the sort attribute is DN, but any attribute can be specified. You can<br />
use another attribute, for example, to sort employee records in an LDIF file based<br />
on their employee numbers for administration, or to sort based on telephone<br />
numbers to allocate spare lines.<br />
You must use ldifsort before ldifdelta to sort both input files to ldifdelta in the<br />
same order.<br />
ldifsort has the following command-line format:<br />
ldifsort [options] infile [outfile]<br />
Using DXtools 10–31
LDIF Tools<br />
The options of the ldifsort command are:<br />
Option<br />
Description<br />
-d Sorts in descending order. The default is to sort in ascending order.<br />
-v Runs in verbose mode (diagnostics to standard error).<br />
-U Does not ignore (filter out) duplicate entries.<br />
-a attr Sorts entries based on the attribute attr. The default sort attribute is dn.<br />
-b file Writes duplicate or bad input records to file.<br />
-m count The number of records in each bucket. The default is 200. For best results, we<br />
recommend that you set this option to the square root of the number of entries<br />
in the file<br />
(-m count = √ number of entries in file).<br />
-r block Number of buckets to allocate at a time. The default is 10,000.<br />
-s bytes Size of read buffer for each bucket. The default is 2,048 (2k).<br />
-t dir Uses the directory dir for temporary files.<br />
The parameters of the ldifsort command are:<br />
Parameter<br />
infile<br />
outfile<br />
Description<br />
The file to be sorted.<br />
The file to which output is to be written. The default is to write output to<br />
standard out.<br />
DXtools Example 4<br />
ldifsort<br />
Make the old directory the same as the reference directory:<br />
dxsearch -L -h oldhost "(oc=*)" > old.ldif<br />
dxsearch -L -h referencehost "(oc=*)" > ref.ldif<br />
ldifsort old.ldif old_sorted.ldif<br />
ldifsort ref.ldif ref_sorted.ldif<br />
ldifdelta old_sorted.ldif ref_sorted.ldif | dxmodify -h oldhost<br />
10–32 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
LDIF Tools<br />
Calculating the Change Between Two LDIF Files: ldifdelta<br />
Use this tool to calculate the change, or delta, between two LDIF files. The<br />
ldifdelta program is an offline directory synchronization tool based on the LDAP<br />
directory interchange format. You can use ldifdelta to fully or partially<br />
synchronize directories.<br />
The output file produced by ldifdelta is an LDIF file containing LDIF change<br />
records. You can apply the output file against the outdated directory with the<br />
DXmodify tool to update it with respect to the reference directory.<br />
The format is:<br />
ldifdelta [options] oldfile newfile [outfile]<br />
The following are the parameters of the ldifdelta command:<br />
Parameter<br />
oldfile<br />
newfile<br />
outfile<br />
Description<br />
The outdated file.<br />
The more recent file to compare against oldfile.<br />
The output file containing the differences between newfile<br />
and oldfile.<br />
The following are the options of the ldifdelta command:<br />
Option<br />
Description<br />
-x Ignores X.500 operational attributes.<br />
-v Verbose output.<br />
-Z schema File containing schema definitions.<br />
You must do two things before using the ldifdelta tool:<br />
1. Obtain the two required input LDIF files by using either the -L option with<br />
the DXsearch utility or the DXdump utility.<br />
2. Sort the input LDIF data files using the ldifsort tool.<br />
Using DXtools 10–33
LDIF Tools<br />
DXtools Example 5<br />
Using ldifdelta and ldifsort Together<br />
Make the old directory the same as the reference directory:<br />
dxsearch -L -h oldhost "(oc=*)" > old.ldif<br />
dxsearch -L -h referencehost "(oc=*)" > ref.ldif<br />
ldifsort old.ldif old_sorted.ldif<br />
ldifsort ref.ldif ref_sorted.ldif<br />
ldifdelta old_sorted.ldif ref_sorted.ldif | dxmodify -h oldhost<br />
The following are known limitations of the ldifdelta tool:<br />
■<br />
■<br />
Compares distinguished name in a case insensitive way, not by schema<br />
matching rules.<br />
When comparing URL values, ldifdelta compares only the file names. It does<br />
not attempt to interpret the nature or contents of the file that the URL<br />
references.<br />
10–34 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DAP Tools<br />
DAP Tools<br />
The DAP import and export tools each work with LDIF files. The import tools<br />
(DXmodify, DXrename, and DXdelete) generate updates of the directory, usually<br />
from data in an LDIF file. The export tool (DXsearch) extracts data from the<br />
directory and creates an LDIF file that contains the extracted data.<br />
DXmodify<br />
DXrename<br />
<strong>Directory</strong><br />
DXsearch<br />
LDIF<br />
DXdelete<br />
The following are the import and export tools:<br />
DXmodify<br />
Populates an empty directory; adds new entries; adds new attributes to<br />
existing entries; modifies, renames, or deletes attributes of an entry<br />
DXrename<br />
Changes the common name of a directory entry<br />
DXdelete<br />
Deletes one or more directory entries<br />
DXsearch<br />
Searches a specified directory using defined filters<br />
Note: These tools use the X.500 DAP/OSI protocol. They are similar to the public<br />
domain LDAP tools (ldapsearch, ldapmodify, ldaprename and ldapdelete) but<br />
offer more features.<br />
Using DXtools 10–35
DAP Tools<br />
Common Command Options<br />
The following command arguments are common to the import and export tools:<br />
Option<br />
Value<br />
-D binddn Distinguished name of the user performing the bind.<br />
-c Continuous operation mode.<br />
-n Shows what would be done, but does not actually do it.<br />
-Z schema File containing schema definitions.<br />
-v Runs in verbose mode.<br />
-f file Reads file rather than standard input.<br />
-w password Bind password (for simple authentication).<br />
-h daphost <strong>Directory</strong> server (default is localhost).<br />
-p dapport Port on directory server (default is 102, the OSI port).<br />
-H Usage and option information is displayed.<br />
-l timelim Time limit (in seconds) of search.<br />
You can include OSI addressing for transport, session, and presentation SAPs by<br />
fully expanding the daphost:<br />
hostname:portnumber/tsel/ssel/psel<br />
You can include binary and ASCII characters in the tsel, ssel, and psel selectors.<br />
The % is an escape character followed by two hexadecimal digits:<br />
■ / is expressed as %2F<br />
■ % is expressed as %25<br />
If you do not provide values for the binddn and password, the DXtools bind<br />
anonymously.<br />
You can combine the daphost and daport arguments into the daphost argument<br />
only and express them as a dotted IP address or hostname. For example:<br />
-h 192.168.19.202 -p 19389<br />
can be expressed as:<br />
-h hostname:1900<br />
The examples in the following command descriptions are directed to the sample<br />
DemoCorp directory supplied with DXserver. You can repeat the examples as a<br />
training exercise.<br />
10–36 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DAP Tools<br />
Searching a <strong>Directory</strong>: DXsearch<br />
The DXsearch tool searches a specified directory using defined filters. You can<br />
specify search output as LDIF or text, or you can have each returned attribute<br />
written to a file.<br />
The format is:<br />
dxsearch [options] filter [attributes]<br />
The following are the available options for dxsearch:<br />
Option<br />
Meaning<br />
-t dir Writes values to files in the given directory.<br />
-e Sorts entries by depth (shallowest first).<br />
-E Sorts entries by depth (deepest first).<br />
-A Retrieves attribute names only (no values).<br />
-N Retrieves distinguished names only (no attributes).<br />
-M Does not multicast; limits search to a single directory.<br />
-O Retrieves all operational attributes.<br />
-B Does not suppress printing of non-ASCII values.<br />
-T Times the search (no search results printed).<br />
-L Prints entries in LDIF format (-B is implied).<br />
-F sep Prints sep instead of = between attribute names and values.<br />
-b basedn Base DN for search.<br />
-s scope Either base, one, or sub (search scope).<br />
-a deref Alias dereferencing; one of the keywords never, always, search, or<br />
find.<br />
-z sizelim Size limit (in entries) for search.<br />
The following are additional arguments for dxsearch:<br />
Argument<br />
filter<br />
attributes<br />
Value<br />
RFC2254-compliant LDAP search filter.<br />
Space-separated list of attributes you retrieve (when no attribute<br />
list is given, you retrieve all).<br />
Using DXtools 10–37
DAP Tools<br />
DXtools Example 6<br />
DXsearch<br />
%dxsearch -L -h 192.168.19.202:19389 "(sn=horsfall)"<br />
dn: cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU<br />
oc: organizationalPerson<br />
oc: newPilotPerson<br />
oc: quipuObject<br />
cn: Murray HORSFALL<br />
sn: HORSFALL<br />
title: Information Technology Manager<br />
telephone: 797 8877<br />
description: Replacements<br />
mail: Murray.HORSFALL@DemoCorp.com<br />
postalAddress: 173 Toorak Pde $ Berkeley NSW<br />
postalCode: 2506<br />
If, in the previous example, you send the output to an LDIF file, you can edit the<br />
file contents and use the DXmodify tool to implement the changes.<br />
dxsearch -L -h yourhost:19389 "(sn=horsfall)" > h-modify.ldi<br />
Reporting on Certificate and CRL Indexes: DXcert<br />
The DXcert utility searches a directory for certificates and/or crls using defined<br />
filters. You can specify search output as LDIF or text, or you can have the results<br />
written to a file.<br />
DXcert lists the results, with the specified certificate/crl components returned as<br />
attributes.<br />
Note: You must run DXindexdb before generating each report or batch of reports<br />
to update the certificate/crl components indexes.<br />
The format is:<br />
dxcert options report -cert [component1 component2 ...] -crl [component1 component2 ...] filter<br />
attributes]<br />
10–38 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DAP Tools<br />
Modifying a <strong>Directory</strong>: DXmodify<br />
You can populate an empty directory, add complete new entries, add new<br />
attributes to existing entries, modify, rename, or delete attributes of an entry<br />
using the DXmodify tool. The key to DXmodify is the structure of the LDIF entry.<br />
The tool DXmodify supports entry from standard input or an LDIF file. We<br />
recommend using an LDIF file.<br />
The format is:<br />
dxmodify [options]<br />
The following are the options for dxmodify:<br />
Option<br />
Meaning<br />
-a Add mode. The default is to add entries to the directory.<br />
-r Replace mode. The default is to replace entries in the directory<br />
rather than add values.<br />
-F Forces use of all change records.<br />
-q Quiet mode, does not report successfully added or modified DNs<br />
-s period Sleeps for period (ms) after each operation<br />
-O Includes operational attributes.<br />
The structure of the LDIF file specifies the modify action to take for each listed<br />
attribute. When you do not specify a modify action, the system applies a default<br />
action as specified in the command line. The available options are adding (-a) or<br />
replacing (-r). This function is especially useful for importing large amounts of<br />
data.<br />
Note: When you do not specify a file name, the system waits for input.<br />
DXtools Example 7<br />
DXmodify<br />
You can make multiple changes, such as changing the title and postal address,<br />
adding a second telephone number, and deleting the description of an entry.<br />
First, edit the contents of the output file h-modify.ldi from DXtools Example 6:<br />
dn: cn=Murray HORSFALL,<br />
ou=Repair,ou=Operations,o=DemoCorp,c=AU<br />
changetype: modify<br />
replace: title<br />
title: Chief Information Officer<br />
-<br />
add: telephone<br />
telephone: 797 8888<br />
-<br />
delete: description<br />
Using DXtools 10–39
DAP Tools<br />
-<br />
replace: postalAddress<br />
postalAddress: 173 Toorak Rd $ South Yarra<br />
postalCode: 3066<br />
This example shows that you can replace the values of multiple attributes using<br />
one replace statement as long as the replace statement specifies the first attribute<br />
name in the series.<br />
Then we use DXmodify to apply the edited file as follows:<br />
dxmodify -h localhost:19389 -f h-modify.ldi<br />
modifying entry cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU<br />
Loading Binary Files: DXmodify<br />
You can also use the DXmodify tool to load binary files.<br />
To add a binary file, first decide on the directory schema object class and<br />
attribute to use to hold the binary data—for example, the cosineJpegPhoto<br />
attribute within the cosinePilotObject object class.<br />
Next, create entries in an LDIF file with the following syntax:<br />
attributeName:< FILE://path<br />
Dxtools Example 8<br />
DXmodify with Binary Files<br />
In this example, we will add a JPEG file with a personnel record from staff.ldif.<br />
For JPEG files, the object class is cosinePilotObject, the X.500 attribute name is<br />
cosineJpegPhoto, and the LDAP attribute name is JpegPhoto.<br />
Create an LDIF file (staff.ldif) with the following form:<br />
dn: cn=Peter Bell,ou=Infrastructure,ou=Support,o=DemoCorp,c=AU<br />
oc: organizationalPerson<br />
oc: newPilotPerson<br />
oc: cosinePilotObject<br />
cn: Peter Bell<br />
sn: BELL<br />
cosineJpegPhoto:< FILE://d:\temp\PHOTO\BELPE01.jpg<br />
title: Design Supervisor<br />
telephone: 881 9256<br />
description: Computing<br />
mail: Peter.BELL@DemoCorp.com<br />
postalAddress: 7-11 Fine Street$Penville <strong>CA</strong><br />
postalCode: 32750<br />
Run the following dxmodify command:<br />
dxmodify -a -c -h hostname:19389 -f staff.ldif<br />
10–40 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DAP Tools<br />
Renaming a <strong>Directory</strong> Entry: DXrename<br />
You can change the common name of a directory entry using the DXrename tool.<br />
You can source the rename data for a single entry from the keyboard or source<br />
multiple entries by using input from a file.<br />
The format is:<br />
dxrename [options] [dn newdn]<br />
where:<br />
■<br />
■<br />
■<br />
-r removes the old RDN<br />
dn is the distinguished name of the entry that is to be renamed<br />
newrdn is the new RDN<br />
Note: When a file name is not specified, the system will wait for input. The<br />
content format for standard input and the file consists of multiple lines, and each<br />
line is a unique distinguished name. The first line is the old distinguished name,<br />
the second line is the new distinguished name, the third line is the old<br />
distinguished name, and so on.<br />
DXtools Example 9<br />
DXrename<br />
Consider an example entry Murray Horsfall and change the rdn to insert a<br />
middle initial J. The example uses the input file option. The example file name is<br />
filename.txt, shown below:<br />
cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU<br />
cn=Murray J HORSFALL<br />
You can apply the dxrename command as follows:<br />
dxrename -r -h hostname:1900 -f filename.txt.<br />
and you can check the results of the rename with a DXsearch as shown below:<br />
dxsearch -L -h hostname:19389 "(sn=horsfall)"<br />
dn: cn=Murray J HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU<br />
oc: organizationalPerson<br />
oc: newPilotPerson<br />
oc: 0.9.2342.19200300.99.3.2<br />
cn: Murray J HORSFALL<br />
sn: HORSFALL<br />
title: Chief Information Officer<br />
telephone: 797 8877<br />
telephone: 797 8888<br />
mail: Murray.HORSFALL@DemoCorp.com<br />
postalAddress: 173 Toorak Rd $ South Yarra<br />
postalCode: 3066<br />
Using DXtools 10–41
DAP Tools<br />
Deleting a <strong>Directory</strong> Entry: DXdelete<br />
The DXdelete tool deletes one or more directory entries. You can supply the<br />
target DN identification by a direct command-line entry, or you can delete<br />
multiple entries by using input from a file.<br />
The format is:<br />
dxdelete [options] [dn]<br />
The following is an additional argument for dxdelete:<br />
Argument<br />
dn<br />
Value<br />
Distinguished name of entry to delete.<br />
Note: When a file name is not specified, the system waits for input. The content<br />
format for standard input and the file consists of multiple lines, and each line is a<br />
unique distinguished name.<br />
DXtools Example 10<br />
DXdelete<br />
To delete the entry Murray J Horsfall, enter the command as follows:<br />
dxdelete -v -h hostname:19389 "cn=Murray J HORSFALL,ou=Repair, ou=Operations,o=DemoCorp,c=AU"<br />
and test the execution with DXsearch.<br />
Bulk Loading Options<br />
Traditionally, data is imported and exported from directories using the import<br />
and export tools described earlier (see DAP Tools in this chapter for more<br />
information) or using openly available LDAP utilities (ldapmodify and<br />
ldapsearch). These utilities read and write LDIF files, encode or decode the data<br />
into DAP or LDAP, and communicate with DXserver, which then decodes the<br />
protocol and updates the underlying RDBMS database.<br />
Importing and exporting can be made more efficient by bypassing the encoding<br />
and decoding processes and loading or unloading LDIF directly to the database.<br />
The bulk tools accomplish this by converting the LDIF file into a number of data<br />
files that represent the internal database tables.<br />
The following bulk tools are provided:<br />
The DXloaddb tool<br />
Creates and loads a database from a prepared LDIF file<br />
The DXdumpdb tool<br />
Extracts data from the database to an LDIF file<br />
10–42 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Schema Tools<br />
Schema Tools<br />
The DXtools manage directory schema by making it easy to access and be<br />
converted into proprietary formats.<br />
The schema of the <strong>eTrust</strong> <strong>Directory</strong> server is in its schema directory (for example,<br />
$DXHOME/config/schema), and consists up of individual schema configuration<br />
files (.dxc) and group files (.dxg).<br />
The schema of a running directory is available to LDAP clients through the<br />
LDAP Version 3 mechanism of schema publishing. A convenient format in which<br />
to extract the schema is LDIF.<br />
After extracting the schema, you can use the schema tools to convert it into the<br />
required format.<br />
LDAP<br />
<strong>Directory</strong><br />
Schema<br />
dxschemaldif<br />
LDIF<br />
ldif2dxc<br />
<strong>eTrust</strong><br />
<strong>Directory</strong><br />
dxschematxt<br />
schema.txt<br />
Schema<br />
Schema management is required whenever the schema pertaining to a directory<br />
is changed (for example, the addition of a new object class and its associated<br />
attributes).<br />
Another common case is integration with other LDAP directories. There may be<br />
additional or different schema to incorporate in the existing directory system.<br />
To make use of new schema, it must be made available to the directory and the<br />
DXtools. This means a new or updated .dxc file, possibly an updated .dxg file,<br />
and an updated schema.txt file.<br />
The schema tools are:<br />
DXschemaldif<br />
Extracts published LDAP schema from LDAP directories in LDIF format<br />
ldif2dxc<br />
Converts LDAP schema in LDIF format into <strong>eTrust</strong> <strong>Directory</strong> server-side<br />
format (.dxc) and optionally DXtools format (schema.txt)<br />
DXschematxt<br />
Converts <strong>eTrust</strong> <strong>Directory</strong> server-side schema into a schema.txt file that<br />
DXtools uses<br />
Using DXtools 10–43
Schema Tools<br />
Extracting Schema in LDIF Format: DXschemaldif<br />
Use the DXschemaldif tool to extract schema from external LDAP directories.<br />
The tool extracts the LDAP schema in the LDIF format.<br />
The syntax is:<br />
dxschemaldif [-v] hostaddr:port<br />
To get help on the tool, enter dxschemaldif with neither option nor parameter.<br />
Typically, when using this tool, you will redirect the output from the screen to a<br />
file.<br />
DXtools Example 11<br />
DXschemaldif<br />
You want to extract the schema from a Version 3 LDAP directory and redirect<br />
the output to the new_schema.ldif file. Enter the following command:<br />
dxschemaldif -v ldapserver:389 > new_schema.ldif<br />
You can use the ldif2dxc tool to convert the LDIF schema into the <strong>eTrust</strong><br />
<strong>Directory</strong> schema format.<br />
10–44 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Schema Tools<br />
Converting Schema from LDIF to DXserver Format: ldif2dxc<br />
Use the ldif2dxc tool to convert LDAP schema in LDIF format into <strong>eTrust</strong><br />
<strong>Directory</strong> DXserver schema configuration format (.dxc). Optionally, the tool can<br />
also update an existing schema.txt file.<br />
The syntax is:<br />
ldif2dxc [options] [outfile]<br />
To get help on the tool, enter ldif2dxc with neither options nor parameter.<br />
The options of the ldif2dxc command are:<br />
Option<br />
Meaning<br />
-b badfile Write bad schema records to the specified file.<br />
-f file Read input from the specified file.<br />
-m map Get OIDs from the specified map file. For information about the file,<br />
see DXtools Example 14.<br />
-M oid_arc Generate missing OIDs from 'oid_arc'<br />
For example:<br />
■<br />
■<br />
x.y.z. generates x.y.z.0, x.y.z.1, etc<br />
x.y.z.34 generates x.y.z.34, x.y.z.35, etc<br />
For more information, see Example 16.<br />
-s Skip reserved DXserver attributes (for example, objectClass,<br />
userPassword, …)<br />
-x dxcFile Exclude schema that is defined in the specified <strong>eTrust</strong> <strong>Directory</strong><br />
schema file.<br />
-Z schema Append new schema definitions in DXtools schema file format to<br />
the specified file.<br />
Using DXtools 10–45
Schema Tools<br />
DXtools Example 12<br />
ldif2dxc<br />
You want to convert the schema in the new_schema.ldif file from DXtools<br />
Example 11. In this case, you are not interested in the entire external schema, but<br />
rather schema unique to the external source. The local directory also typically<br />
sources a single DXserver schema group file (for example, default.dxg).<br />
To convert only the schema unique to the external source, you want to instruct<br />
the tool to exclude an existing schema file. In addition, you want to instruct the<br />
tool not to redefine any internal DXserver schema definitions.<br />
Enter the following command:<br />
ldif2dxc -f new_schema.ldif -s -x default.dxg new_schema.dxc<br />
DXtools Example 13<br />
ldif2dxc with Errors<br />
While converting the schema in the new_schema.ldif file, the tool stops with an<br />
error because of schema incompatibility with <strong>eTrust</strong> <strong>Directory</strong> and does not<br />
produce any output. The problem may be caused by an unsupported syntax or<br />
matching rule, or an error in the published schema. In these cases, you can<br />
instruct the tool to write any bad schema to a bad file but continue writing the<br />
good schema to your output file. You can inspect the bad file and decide whether<br />
it is worthwhile to correct any of the errors (for example, remove an obscure<br />
matching rule for substrings), and then rerun the tool until you have what you<br />
need.<br />
To run the tool with a bad file, enter the following command:<br />
ldif2dxc -b bad.txt -f new_schema.ldif -s -x default.dxg new_schema.dxc<br />
10–46 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Schema Tools<br />
DXtools Example 14<br />
ldif2dxc with Map File<br />
Some LDAP directories publish OIDs as labels rather than dotted decimal strings<br />
(for example, xyConfig-oid). These object classes and attributes do not load into<br />
the directory. Instead, the tool assigns them temporary OIDs off the <strong>eTrust</strong><br />
<strong>Directory</strong> arc to enable you to load the new schema, but this solution may not be<br />
suitable for all directory implementations.<br />
If the dotted decimal form of these object class and attribute OIDs are available,<br />
you can create a map file, and instruct the tool to look up these label OIDs in the<br />
file and substitute the labels by the dotted decimal OIDs.<br />
The map file is a three-column comma-separated value (CSV) file with the<br />
following format, for example:<br />
-------------------------------------<br />
#<br />
# format: objectClass, attributeType, oid<br />
#<br />
# objectClasses<br />
xyConfig-oid,,1.2.3.4<br />
xyAdmin-oid,,1.2.3.5<br />
# attributeTypes<br />
,abstract-oid,1.2.4.5<br />
,aci-oid,1.2.4.6<br />
-------------------------------------<br />
You map a dotted decimal OID to either an object class or an attribute type, but<br />
not both.<br />
To run the tool with a map file, enter the following command:<br />
ldif2dxc -b bad.txt -f new_schema.ldif -m map.txt -s -x default.dxg new_schema.dxc<br />
DXtools Example 15<br />
ldif2dxc and the schema.txt File<br />
If the new schema has attributes that should be searchable, or object classes and<br />
attributes that exist as data in the directory, and you plan to use the DXtools to<br />
search, load, or dump the directory, then you must update the schema.txt<br />
DXtools file. While converting the schema in the new_schema.ldif file, you want<br />
to instruct the tool to append any new schema to the existing schema.txt file. For<br />
example, on a UNIX system, you can enter the following command:<br />
ldif2dxc -b bad.txt -f new_schema.ldif -m map.txt -s -x default.dxg -Z<br />
$DXHOME/bin/schema.txt new_schema.dxc<br />
Using DXtools 10–47
Schema Tools<br />
DXtools Example 16<br />
ldif2dxc and label OIDs<br />
If there are a large number of “label” OIDs (e.g. xyConfig-oid) in the LDIF<br />
schema file it may take a long time to add an entry for everyone in a map file. An<br />
alternative is to specify an OID arc that the tool will use in place of any label<br />
OID, incrementing it for each label OID it finds.<br />
If your arc is new, you can specify it with a trailing ‘.’, and the tool will start<br />
incrementing it from 0. If some OIDs have already been assigned against this<br />
OID arc, you can specify the next available OID, and the tool will start<br />
incrementing from that one.<br />
To replace the map file in Example 15 with a new OID arc of “1.22.333.444.”, on a<br />
UNIX system, enter:<br />
ldif2dxc -b bad.txt -f new_schema.ldif -M 1.22.333.444. -s -x default.dxg -Z<br />
$DXHOME/bin/schema.txt new_schema.dxc<br />
If the tool encountered the OID label xyConfig-oid in new_schema.ldif, it will<br />
assign it an OID of 1.22.333.444.0. If it then encountered the OID label abConfigoid,<br />
it will assign it an OID of 1.22.333.444.1, etc.<br />
If twenty OIDs from this arc were assigned, the next available OID would be<br />
1.22.333.444.20. If you were to perform another integration with schema from<br />
new_schema2.ldif, to avoid clashing with existing OIDs in the directory, on a<br />
UNIX system, enter:<br />
ldif2dxc -b bad.txt -f new_schema2.ldif -M 1.22.333.444.20 -s -x default.dxg -Z<br />
$DXHOME/bin/schema.txt new_schema2.dxc<br />
If the tool encountered the OID label cdConfig-oid in new_schema2.ldif, it will<br />
assign it an OID of 1.22.333.444.20. If it then encountered the OID label efConfigoid,<br />
it will assign it an OID of 1.22.333.444.21, etc.<br />
10–48 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Schema Tools<br />
Converting Schema from DXserver Format to DXtools Format: DXschematxt<br />
Use the DXschematxt tool to convert DXserver schema configuration files into a<br />
DXtools schema file. This is required when the existing DXtools schema file is<br />
badly out of date, or is lost or corrupted.<br />
The syntax is:<br />
dxschematxt [options] files<br />
To get help on the tool, enter dxschematxt with neither options nor parameters.<br />
The options of the dxschematxt command are:<br />
Option<br />
Meaning<br />
-f path Read schema from the specified path rather than the default schema<br />
configuration path (for example, $DXHOME/config/schema).<br />
-Z file Write to the specified file rather than the default scheme.txt file (for<br />
example, $DXHOME/bin/schema.txt).<br />
files is a list of space-separated DXserver schema configuration files that you<br />
want to convert. The list of files can include .dxc and .dxg files. The tool will read<br />
the schema configuration files listed in the group files.<br />
DXtools Example 17<br />
dxschematxt<br />
You want to rebuild the DXtools schema.txt file in $DXHOME/bin from the<br />
default schema group file. The tool backs up the current file automatically. Enter<br />
the following command to instruct the tool to read from that particular file:<br />
dxschematxt default.dxg<br />
DXtools Example 18<br />
dxschematxt to New DXtools Schema File<br />
You want to build a new DXtools schema file. For example, on a UNIX system,<br />
you can enter the following command:<br />
dxschematxt -Z $DXHOME/bin/new_schema.txt default.dxg<br />
DXtools Example 19<br />
dxschematxt from Other Path<br />
You want to build a new DXtools schema file from files in another location. For<br />
example, on a UNIX system, you can enter the following command:<br />
dxschematxt -Z $DXHOME/bin/new_schema.txt -f $DXHOME/config/new_schema default.dxg<br />
experimental.dxc<br />
Using DXtools 10–49
<strong>Directory</strong> Administration Tools<br />
<strong>Directory</strong> Administration Tools<br />
Checking DSA configuration: DXsyntax<br />
DXsyntax is a tool for checking the configuration of one or more DSAs. It is most<br />
easily run on the server hosting those DSAs, but it can be run remotely, provided<br />
the machine running it has access to the configuration directory of the server<br />
hosting the DSAs.<br />
DXsyntax has only one parameter: the DSA file name. Running DXsyntax<br />
without a parameter causes it to check the configuration of every DSA.<br />
To check a single DSA, run DXsyntax with the name of the DSA as its parameter.<br />
The name can be a filename pattern. For example, to check all DSAs whose<br />
names start with rk, run DXsyntax with a parameter of rk*.<br />
DXsyntax runs through the configuration files of each DSA in turn, reporting a<br />
detailed error message if it finds a problem. The error message specifies the line<br />
and file where the error was detected (the actual error may be earlier), and<br />
provides details on the error condition. Only one error is reported for each DSA<br />
checked, because a single error can cause a cascade of problems that is<br />
overwhelming.<br />
If no errors are found, DXsyntax exits without a message, and with a return code<br />
of 0. This is handy for use in routine test scripts. If one or more errors are found,<br />
DXsyntax exits with an error message and a non-zero return code.<br />
DXsyntax relies on the DXHOME environment variable. DXHOME must be set<br />
to the home path of DXserver. This is done automatically when <strong>eTrust</strong> <strong>Directory</strong><br />
is installed. DXsyntax expects the DSA configuration files to be located in the<br />
config folder under the path in DXHOME.<br />
10–50 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
11<br />
Using JXplorer<br />
JXplorer is a general purpose LDAP-compliant directory browser. It has a simple<br />
user interface, yet supports a wide range of powerful, configurable functions.<br />
With the JXplorer browser, you can:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Connect to any directory that supports LDAP and navigate, search, and<br />
modify the directory.<br />
Read the directory’s schema directly, rather than relying on schema<br />
configuration files.<br />
Visually cut, paste, and edit subtrees in the directory, including drag and drop<br />
on Windows platforms.<br />
Import and export LDIF files from a directory and even manipulate them<br />
offline.<br />
Configure the browser in many ways, including its appearance and logging<br />
information. For example, you can configure the look of the browser to a<br />
company standard by using company-specific icons for the directory and<br />
company graphics within the HTML templates.<br />
Display directory data within configurable HTML templates using a simple<br />
extension to the HTML language.<br />
Run in debug mode, permitting full tracing of the LDAP BER protocol.<br />
Run on a wide variety of operating system platforms, since JXplorer is<br />
written in the Java programming language.<br />
Optionally use SSL to communicate securely, and SASL for secure certificatebased<br />
authentication.<br />
<strong>eTrust</strong> <strong>Directory</strong> is a fully functional LDAP-compliant directory that lets you use<br />
all the features of JXplorer.<br />
Using JXplorer 11–1
The JXplorer Browser<br />
The JXplorer Browser<br />
To start JXplorer, click Start, Programs, Computer Associates, <strong>eTrust</strong>, <strong>eTrust</strong><br />
<strong>Directory</strong>, JXplorer.<br />
When you start JXplorer and connect to a directory, the main browser window<br />
appears:<br />
The menu bar at the top of the browser provides access to a full range of browser<br />
functions through pull-down menus.<br />
Two toolbars below the menu bar give shortcuts to commonly used functions.<br />
The first is a button bar, with shortcuts to commonly used menu functions. The<br />
second, the quick search toolbar, lets you quickly execute simple searches (such<br />
as searching a directory for an employee’s name).<br />
The status bar at the very bottom of the browser displays the status of the<br />
browser. For example, it shows whether the browser is connected or not.<br />
The main body of the browser is divided into two panes. The left pane is the<br />
directory tree, which you can navigate by using the mouse to click the entries.<br />
The right pane shows the selected entry from the directory, shown either as an<br />
HTML page or as a table of attributes and values.<br />
11–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The JXplorer Browser<br />
Menu Bar<br />
The menu bar provides the following functions:<br />
Menu Item<br />
File<br />
Connect<br />
Disconnect<br />
Print<br />
Refresh Tree<br />
Exit<br />
Function<br />
Connects to an LDAP-compliant directory.<br />
Breaks the current LDAP connection.<br />
Prints the current viewed entry.<br />
Resets the directory tree and starts reloading entries.<br />
Closes the browser.<br />
Edit<br />
New<br />
Copy DN<br />
Cut Branch<br />
Copy Branch<br />
Paste Branch<br />
Paste Alias<br />
Delete<br />
Rename<br />
Adds a new entry under the selected position.<br />
Sends the DN of the current entry to the clipboard.<br />
Cuts the currently selected entry or subtree.<br />
Copies the currently selected entry or subtree.<br />
Pastes the previously cut or copied subtree under the<br />
selected position.<br />
Pastes the previously copied Distinguished<br />
Name (DN) of an entry as an alias under the selected<br />
position.<br />
Deletes the currently selected entry or subtree.<br />
Lets you rename the currently selected entry.<br />
View<br />
Show Button Bar<br />
Show Search Bar<br />
Refresh<br />
Displays or hides the shortcut button bar.<br />
Displays or hides the quick search toolbar.<br />
Reloads the currently selected entry from the<br />
directory.<br />
Bookmark<br />
Add Bookmark<br />
Delete Bookmark<br />
Edit Bookmark<br />
Lets you add a bookmark.<br />
Lets you delete a bookmark.<br />
Lets you edit a bookmark.<br />
Using JXplorer 11–3
The JXplorer Browser<br />
Menu Item<br />
Search<br />
Function<br />
Ldif<br />
Search<br />
Delete Filter<br />
Performs an advanced search.<br />
Deletes a saved filter.<br />
Return Attribute Lists Manages the attributes that you want returned in a<br />
search.<br />
Filter<br />
Lists all saved filters.<br />
Export Full Tree<br />
Export Subtree<br />
Import File<br />
View Offline<br />
Writes the entire directory tree to an LDIF file.<br />
Writes the currently selected subtree to an LDIF file.<br />
Imports an existing LDIF file into the directory.<br />
Lets you view and edit an LDIF file in the browser.<br />
Options<br />
Confirm Tree<br />
Operations<br />
Confirm Table Editor<br />
Updates<br />
Ignore Schema<br />
Checking<br />
Resolve Aliases While<br />
Browsing<br />
Advanced Options<br />
Enables a safety mode, which prompts you to<br />
confirm modifications before they are made.<br />
Enables a confirmation dialog, which appears after<br />
you make a change to the directory.<br />
Stops the browser checking that the user’s input<br />
conforms to the directory schema.<br />
Displays the alias details such as where the alias<br />
entry points. This affects both browsing and<br />
searching.<br />
Displays the Advance Options dialog, which enables<br />
you to choose the look and feel of the browser,<br />
logging options, and LDAP levels.<br />
Tools<br />
Stop Action<br />
Cancels the current browser operation.<br />
Security<br />
Trusted Servers and<br />
<strong>CA</strong>s<br />
Client Certificates<br />
Advanced Keystore<br />
Options<br />
Displays the options for server-only authentication.<br />
Displays the options for client and server<br />
authentication.<br />
Displays the options for setting up keystores.<br />
11–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The JXplorer Browser<br />
Menu Item<br />
Help<br />
Contents<br />
Search<br />
About<br />
Function<br />
Lists the titles of help topics.<br />
Lets you search for help on a particular keyword.<br />
Lists information about the JXplorer browser,<br />
including its current version number.<br />
Button Bar<br />
The button bar provides shortcuts for normal menu functions.<br />
Button<br />
Function<br />
Connect<br />
Connects to an LDAP-compliant directory.<br />
Disconnect<br />
Breaks the current LDAP connection.<br />
Print<br />
Prints the currently selected entry.<br />
Cut Branch<br />
Cuts the currently selected entry or subtree.<br />
Copy DN<br />
Sends the DN of the current entry to the clipboard.<br />
Copy Branch<br />
Copies the currently selected entry or subtree.<br />
Paste Branch<br />
Paste Alias<br />
Delete<br />
Pastes the previously cut or copied subtree under the<br />
selected position.<br />
Pastes the previously copied DN of an entry as an<br />
alias under the selected position.<br />
Deletes the currently selected entry or subtree.<br />
New<br />
Adds a new entry under the selected position.<br />
Rename<br />
Lets you rename the selected entry.<br />
Refresh Entry Reloads the currently selected entry from the<br />
directory.<br />
Cancel<br />
Stops the current operation (such as a search or a<br />
directory update).<br />
Using JXplorer 11–5
The JXplorer Browser<br />
Quick Search Bar<br />
The quick search bar lets you execute simple searches.<br />
1. Choose or<br />
type an attribute<br />
2. Choose<br />
an operator<br />
3. Type a value<br />
to search on<br />
4. Start the search<br />
The operators are:<br />
■ Equal to =<br />
■ Not equal to !(=)<br />
■ Less than or equal to =<br />
■ Approximately equal to ~=<br />
For more information about searching, look in Chapter 13 in the User <strong>Guide</strong>.<br />
Displaying the <strong>Directory</strong> Tree<br />
The tree display pane (the left pane) displays the directory tree, and allows you<br />
to graphically browse the directory.<br />
There are usually three tree views available:<br />
Explore<br />
Displays the data in the current directory<br />
Results<br />
Shows the results of the most recent search<br />
Schema<br />
Displays the schema currently in use by the directory<br />
11–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Browsing a <strong>Directory</strong><br />
Browsing a <strong>Directory</strong><br />
With JXplorer, you can browse any LDAP-compliant directory. This section<br />
describes the browsing functions available.<br />
Starting JXplorer<br />
You can run JXplorer on either a Windows or UNIX computer.<br />
On Windows<br />
To start JXplorer on a Windows computer, click Start on the taskbar, and then<br />
choose Programs, Computer Associates, <strong>eTrust</strong>, <strong>eTrust</strong> <strong>Directory</strong>, JXplorer.<br />
On UNIX<br />
To start JXplorer on a UNIX computer, issue the following command from the<br />
JXplorer directory:<br />
./jxstart.sh<br />
Connecting to a <strong>Directory</strong><br />
When you choose File, Connect (or click the Connect button), the browser<br />
displays the following connection dialog, requesting the information that<br />
JXplorer needs to connect to a directory.<br />
The browser requires the following information to make a connection:<br />
■<br />
■<br />
■<br />
The name of the computer that hosts the directory.<br />
The port number of the server on that computer.<br />
The base distinguished name of the directory.<br />
If none is given, the browser is still able to connect, providing that the<br />
directory is one (like <strong>eTrust</strong> <strong>Directory</strong>) that makes this information available.<br />
Using JXplorer 11–7
Browsing a <strong>Directory</strong><br />
■<br />
■<br />
■<br />
The protocol that is in use, which can be Lightweight <strong>Directory</strong> Access<br />
Protocol (LDAP) or <strong>Directory</strong> Services Markup Language (DSML). For<br />
LDAP, this is usually Version 3, but can be Version 2 to support older<br />
directories.<br />
If the DSML protocol is selected, the path to the DSML service.<br />
The security level with which you want to connect (not applicable to DSML).<br />
You can connect to the directory anonymously, or with your user name and<br />
password. If you require higher security, you can establish a link to the<br />
server using SSL with either of these methods. When a client keystore is<br />
available, you can use full client-authenticated SSL, combined with SASL<br />
authentication at the directory.<br />
The browser lets you save connection details for commonly used directories as<br />
connection templates. To save the information, supply a name (or select an existing<br />
name from the drop-down list), and then click Save. You can save any number of<br />
connection templates, and you can edit or delete them at any time.<br />
You can also choose to make one of the connection templates a default template.<br />
After you specify a default template, the connection dialog opens with the details<br />
from that template already filled in.<br />
Note: For security reasons, the password field is not saved in any template.<br />
Reading Schema<br />
After the connection details are obtained, the browser attempts to contact the<br />
directory. When the directory is contacted, the browser obtains the directory’s<br />
current schema (provided that an LDAP Version 3 connection has been made).<br />
Directories that support LDAP Version 3 (such as <strong>eTrust</strong> <strong>Directory</strong>) download<br />
the schema to the browser. This lets the browser correctly create, display, and<br />
edit entries without requiring any independent browser configuration. Since the<br />
browser gets the schema from the directory, it is always up-to-date, and there is<br />
no possibility of inconsistency.<br />
Navigating the <strong>Directory</strong> Tree<br />
You can navigate the directory tree by mouse or keyboard.<br />
By Mouse<br />
By Keyboard<br />
To expand or collapse a subtree, click on the expansion icon (which usually<br />
appears as a small box containing either a + or -) to the left of the entry. Doubleclick<br />
on the text portion of a tree entry to display that entry in the viewing pane.<br />
Use the arrow keys to select entries. Press Enter to expand and collapse a<br />
subtree, or display an entry in the viewing pane.<br />
11–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Browsing a <strong>Directory</strong><br />
Displaying an Entry<br />
The entry display pane (the right pane) displays the currently selected directory<br />
entry, either in an HTML template, or in an editable table of attributes and values.<br />
When you select an entry, whether from the Explore view, the Results view, or<br />
even the Schema view, the browser queries the directory for the attribute values<br />
of the entry and displays the results in the entry display pane. The results can be<br />
displayed either in the HTML template view or in the attribute/value table view.<br />
The HTML Viewer<br />
The following is an employee record displayed in an HTML template. The<br />
template contains three tabs (Main, Address, and Other) that display the<br />
attribute information for the selected entry.<br />
Using Different HTML Templates<br />
When the browser initially reads an entry, it attempts to find an appropriate<br />
HTML template in which to display the entry, as follows:<br />
■<br />
■<br />
■<br />
■<br />
The HTML templates key on the object classes of the entry, with each HTML<br />
template specializing in displaying one object class.<br />
Each object class can have multiple HTML templates capable of displaying it.<br />
HTML templates for a given object class can also display entries whose<br />
object classes are inherited from that object class.<br />
When you select an HTML template for a particular entry, the browser<br />
remembers that template and uses it for other entries of the same object class.<br />
Using JXplorer 11–9
Browsing a <strong>Directory</strong><br />
The number of attributes and how they are displayed depend on the HTML<br />
template. When the HTML template does not have a tag for a particular attribute,<br />
that attribute is not displayed. A tag is available for displaying all attributes that<br />
have values. The tag is used to simplify the display of large numbers of<br />
attributes.<br />
This use of HTML templates enables:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Different types of entries to be displayed in ways appropriate to their type<br />
Site-specific help information to be included in the HTML<br />
HTML hyperlinks to be used to link to existing company resources<br />
Straightforward customer configuration of data display<br />
Special purpose templates for different types of users (administrator, help<br />
desk, office staff, and so forth)<br />
Use of corporate branding and logos<br />
The Table Editor<br />
The same employee record can be edited and displayed in the table editor.<br />
You can also use it to view the attributes an entry can contain, because it uses<br />
schema to show all the possible attributes that the entry might have.<br />
Attributes in bold represent mandatory attributes – these must be present for the<br />
entry to be valid. Click the Properties button to display operational attributes<br />
such as the date of the last modification.<br />
You can configure the table viewer to include custom binary editors, which may<br />
be the only way to view complex or application-specific binary data.<br />
11–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Browsing a <strong>Directory</strong><br />
Refreshing Entries<br />
For efficiency, the browser caches entries, unless you specifically request to<br />
reload them from the directory. You can force a single entry to be reloaded by<br />
selecting the Refresh option. You can refresh the DIT by selecting the Refresh<br />
Tree option.<br />
Searching<br />
In JXplorer, you can search for an entry in two ways. You can run a quick search<br />
using simple criteria, or you can run a complex search that you can save to<br />
search_filters.txt as filters. Complex searches display search results as complete<br />
directory trees, letting you browse large numbers of search results or save them<br />
as LDIF files.<br />
Running a Quick Search<br />
You can quickly execute simple, single-attribute-value searches using the quick<br />
search bar, which contains a pull down list of common attribute types. You can<br />
add attributes to this list; the browser saves changes to the list when you exit the<br />
browser.<br />
The quick search bar makes it possible to do common searches, for example,<br />
specific employee names, part numbers, and so on, without having to access the<br />
menu bar or enter a complete LDAP-format search request.<br />
Running a Complex Search<br />
You can perform more complex searches using the Search dialog.<br />
Using JXplorer 11–11
Browsing a <strong>Directory</strong><br />
The Search dialog lets you search one of the following:<br />
■<br />
■<br />
■<br />
The selected entry<br />
The next level from the selected entry, but not including the selected entry<br />
The full subtree<br />
You can use the filter constructor to create complex searches, and then save the<br />
details in a property file for use later. You can use the Information to retrieve<br />
drop-down list to select the definition that contains the list of attributes you want<br />
returned. To create these definitions, choose Return Attribute Lists from the<br />
Search menu. For more information about how to create the lists, see the online<br />
help.<br />
Aliases are similar to shortcuts and are used in some directories to link different<br />
parts of the tree. When you search aliases, JXplorer returns the real entry to<br />
which the alias points. When you do not search aliases, JXplorer does not resolve<br />
alias references and returns all alias entries as regular entries.<br />
You can choose to resolve aliases while:<br />
■<br />
■<br />
Searching, that is, to resolve aliases for subordinate entries of the base object<br />
Finding the base object, that is, to resolve aliases when locating the base<br />
object of the search<br />
Consequently, when you check both options, all aliases are resolved, and when<br />
you do not check an option, no aliases are resolved.<br />
Saving Complex Searches<br />
Since constructing complex searches can be time-consuming, JXplorer lets you<br />
save complex searches as filters for later use. With saved searches, you can:<br />
■<br />
■<br />
■<br />
Save any number of searches as filters<br />
Edit or delete them at any time<br />
Copy searches for modification, and save them under a different name<br />
11–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Browsing a <strong>Directory</strong><br />
Search Results Tree<br />
Regardless of whether the search is run using the quick search bar or a search<br />
menu option, once it is run the matching entries are displayed as a results tree in<br />
the Results view of the directory tree pane.<br />
Parents of search results appear as empty entries in the tree. You can browse and<br />
save the search result tree (including LDIF format) just like the directory tree.<br />
You can edit the results.<br />
You can set the number of entries returned from a search, and the timeout. See<br />
Search Limits in this chapter for more information.<br />
Creating Bookmarks<br />
A bookmark is an entry in the directory that you identify and name for future<br />
reference. You can use a bookmark to quickly jump to an entry.<br />
To add a bookmark, simply select the entry that you want to mark, and choose<br />
Add Bookmark from the Bookmark menu.<br />
Using JXplorer 11–13
Browsing a <strong>Directory</strong><br />
Exploring Schema<br />
In addition to viewing the data entries held in a directory, you can directly view<br />
the schema that is read from the directory. Use the Schema view of the directory<br />
tree pane.<br />
Note: Some of the following options may not be available with servers other<br />
than DXserver, because not all servers implement full schema publishing.<br />
The Schema pane lets you examine attribute definitions, class definitions, and<br />
syntax definitions.<br />
Attribute definitions include:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Names<br />
X.500 OIDs<br />
Attribute syntaxes<br />
Syntax descriptions<br />
A flag showing whether the attribute is single valued<br />
General descriptions (if available)<br />
Class definitions include:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Names<br />
Parents<br />
Kind (structural, auxiliary or abstract)<br />
A list of must-contain OIDs<br />
A translation of OIDs that must be contained in attribute names<br />
Syntax definitions include:<br />
■<br />
■<br />
The numeric OID<br />
The text description of the OID<br />
11–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Browsing a <strong>Directory</strong><br />
As with the other tree displays, you can display schema entries either in the table<br />
view or in custom HTML template pages. Unlike the other tree displays,<br />
however, you cannot edit the schema directly through the browser. For security<br />
and administration reasons, many servers do not permit their schema to be<br />
edited online and require an administrator to perform schema maintenance at<br />
the server.<br />
You can export schema to an LDIF file, but this is not the usual way to store<br />
schema information and most directories cannot use it without further<br />
processing.<br />
Using JXplorer 11–15
Editing the <strong>Directory</strong><br />
Editing the <strong>Directory</strong><br />
You can modify entries in the directory using the browser in a large number of<br />
ways, ranging from slight modification of a single attribute value to large-scale<br />
tree operations affecting many thousands of entries.<br />
JXplorer lets you use graphical cut-and-paste techniques to manipulate entire<br />
directory subtrees; you can manipulate individual entries using the table editor.<br />
You can rename entries from either the directory tree pane or the table editor,<br />
depending on what is most convenient at the time.<br />
<strong>Directory</strong> Tree Operations<br />
As you browse the directory tree, you can modify the directory using the menus,<br />
the button bar shortcuts, or the Context menu (accessed by right-clicking on the<br />
entry) for the entry in the tree itself.<br />
WARNING! This is a very powerful tool, and you can affect large areas of the directory<br />
with a single operation. To avoid accidents, you should turn on the Confirm Tree<br />
Operations flag on the Options menu.<br />
Cut, Copy, Paste, and Delete<br />
You can manipulate the directory tree using the cut, copy, paste, and delete<br />
operations. On Windows platforms, you can copy and move entries by dragging<br />
them with the mouse (“drag and drop”). These operations can be carried out on<br />
individual entries within the directory tree or on whole subtrees. Since most<br />
directories do not natively support operations on entire subtrees, the client reads<br />
and writes all subtree entries recursively, enabling operation on all types of<br />
LDAP-compliant directories.<br />
When you select (and therefore display) an entry, all cut, copy, paste, and delete<br />
operations occur relative to this selected entry. Specifically:<br />
Delete<br />
Removes the selected entry and any subentries<br />
Copy Branch<br />
Copies the selected entry and any subentries<br />
Cut Branch<br />
Prepares the selected entry and any subentries to be moved to a new location<br />
Paste Branch<br />
Either moves or copies a previously cut or copied entry (and any subentries)<br />
under the selected entry as child entries<br />
11–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Editing the <strong>Directory</strong><br />
Since some subtree operations involving large numbers of entries can take a<br />
significant time to complete, the browser displays a progress bar if it estimates<br />
that the operation is extensive:<br />
The progress bar displays the number of entries processed and estimates the<br />
proportion of the operation completed. When you want to stop the operation,<br />
you can either click Cancel in the Progress, or click the Stop button on the quick<br />
search toolbar. When you do this, any changes already made will be kept.<br />
Renaming Entries in the <strong>Directory</strong> Tree<br />
You can rename an entry within the directory tree by selecting the Rename<br />
option.<br />
When an entry is renamed, the appropriate changes to the naming attributes are<br />
also made. Naturally, when a parent is renamed, the DNs of the entries in the<br />
entire subtree under the parent also change.<br />
Copying Distinguished Names and Pasting Aliases<br />
Aliases are similar to shortcuts and are used in some directories to link different<br />
parts of the tree. To create an alias, copy the DN of an entry, and then paste it to<br />
another part of the tree using the Paste Alias option. When you copy an entry,<br />
you can choose to copy the full distinguished name of the entry.<br />
You can also use the Copy Branch and Copy DN functions to copy the name of<br />
an entry for pasting into any of JXplorer's text entry fields, or into your own<br />
documents.<br />
Using JXplorer 11–17
Editing the <strong>Directory</strong><br />
Modifying Attributes in an Entry<br />
You can modify entries in the table editor, which is a simple tabulated list of<br />
attribute names and corresponding attribute values. From the table editor, you<br />
can:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Edit existing values<br />
Add new attribute/value pairs<br />
Delete attributes and values<br />
Copy and paste attribute values<br />
Manipulate binary attributes<br />
Submit the results to the directory<br />
Add or remove naming attributes<br />
These user modifications do not affect the directory until the entry is submitted.<br />
When you have finished modifying the entry and checked your work, click the<br />
Submit button to send the changed entry to the directory. Only at this point is the<br />
data in the directory changed.<br />
Changing Attribute Values<br />
You can edit existing values where they are by selecting the appropriate cell in<br />
the table and retyping the value.<br />
Note: Binary values, attributes that contain an address, and user passwords are<br />
handled differently. See Using Binary Values, Using the Postal Address Editor,<br />
and Entering a User Password in this chapter for more information.<br />
Deleting Values and Attributes<br />
You can delete values (including binary values) using one of the following<br />
methods:<br />
■<br />
■<br />
Select the text in the cell, and then press the Delete key to leave an empty<br />
cell.<br />
Right-click on the table row, and then choose Delete Value Attribute from the<br />
Context menu.<br />
When you delete the last value of a given attribute, the attribute is also deleted;<br />
however, it is not possible to delete the last value of a mandatory attribute, and<br />
the browser does not let you submit an entry that does not include mandatory<br />
attributes, unless the Ignore Schema Checking option is active. See Mandatory<br />
Attributes in this chapter for more information about mandatory attributes.<br />
11–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Editing the <strong>Directory</strong><br />
Adding Values and Attributes<br />
When an attribute does not already have a value, but is available to a particular<br />
entry type, you can create it by finding the attribute in the list of blank-valued<br />
attributes at the bottom of the table and filling in the missing value. When an<br />
attribute already exists and has values, you can create a new value by rightclicking<br />
on the attribute name and choosing Add Another Value from the<br />
Context menu.<br />
You can add new binary values and addresses this way, but you must fill them<br />
in using the Binary Editor, and the Postal Address Editor, respectively. See Using<br />
Binary Values and Using the Postal Address Editor in this chapter for more<br />
information.<br />
Mandatory Attributes<br />
Some attribute names are represented in bold type. These are mandatory<br />
attributes, which must have at least one value for the entry. The browser does<br />
not submit an entry if it has any mandatory attributes without at least one value.<br />
Naming Attributes<br />
Some attributes are used to name an entry, by forming its Relative Distinguished<br />
Name (RDN). Each entry must have at least one naming attribute. Although<br />
attributes can have more than one attribute value, only one of these can be<br />
chosen as the naming attribute. For example, common name may have two<br />
values, Fred and Freddie, but only one can be used as the naming attribute.<br />
Important! You can set naming attributes for mandatory attributes only.<br />
To make an entry a naming attribute, select the entry in the table editor, rightclick<br />
the mouse button, and choose Make Naming Value from the Context Menu.<br />
Naming attributes are displayed in the table editor in blue. Multiple naming<br />
attributes appear in the tree display with a + symbol joining them.<br />
For example, you may want to name a person by the commonName, or cn<br />
attribute, and the surname, or sn attribute. In the case of Craig Link, Craig LINK<br />
is the value of the cn naming attribute, and LINK is the value of the sn naming<br />
attribute. Both entries appear in the table editor in blue, and in the tree display as<br />
Craig LINK + LINK. The order in which the naming attributes appear in the tree<br />
display depends on the order in which they are originally entered into the<br />
directory.<br />
Using JXplorer 11–19
Editing the <strong>Directory</strong><br />
Changing Classes<br />
The object class attribute of an entry determines the attributes that are available<br />
for an entry; therefore, you must modify them separately using the Change<br />
Classes button, located at the bottom of the table editor. This displays the same<br />
list of available object classes as is available in the New Entry panel.<br />
WARNING! You must be careful when deleting object class values because you also<br />
remove all related attributes.<br />
Using the Postal Address Editor<br />
All attributes that have an address value, for example, homePostalAddress, are<br />
entered through the Postal Address Editor dialog, which appears when you<br />
select an address field in the Table Editor. The dialog lets you enter the details, as<br />
they appear in a template with the relevant line breaks and spacing.<br />
Entering a User Password<br />
User passwords are entered via the User Password Data dialog, which appears<br />
when you select the userPassword attribute type in the table editor. The same<br />
procedure applies whether you are entering a new password, or changing an<br />
existing password. Because access to a record is controlled via the access control<br />
settings in the directory’s configuration file (.dxc), you do not have to enter the<br />
existing password before changing it.<br />
Using Binary Values<br />
LDAP is primarily a string handling protocol and many attribute values are<br />
simple text strings. However, it is often necessary to load other types of data, for<br />
example, certificates and images.<br />
JXplorer allows you to load binary files to some attributes, such as Photo and<br />
userPKCS12.<br />
The browser also supports custom binary editors (written in Java using a<br />
provided minimal API) that dynamically loads at run time. You key such binary<br />
editor extensions to a particular object class. This would allow you to write, for<br />
example, an editor for a custom certificate object class.<br />
Standard editors are provided for X.509 certificates, and a number of standard<br />
image and audio formats.<br />
11–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Editing the <strong>Directory</strong><br />
Importing Binary Files<br />
With the Binary Data dialog shown below, you can:<br />
■<br />
■<br />
Import binary files<br />
Export binary files<br />
See the online help for instructions for importing, exporting, and launching<br />
binary files.<br />
Adding a Photo<br />
JXplorer lets you import a photo into the directory, and display it in an HTML<br />
template. In table editor view, the photo is displayed using the photo editor.<br />
JXplorer lets you import photos through the jpegPhoto dialog, which appears<br />
when you select the jpegPhoto attribute type in the table editor. The display area<br />
expands to display the photo you selected; however, it does exceed the size of the<br />
window. When the photo is larger than the window, you can view the photo by<br />
using the scroll bars. All photos must be in .jpeg format. After loading, JXplorer<br />
gives you the option of saving the photo to another location, using your system’s<br />
file browser.<br />
Using JXplorer 11–21
Editing the <strong>Directory</strong><br />
Adding an Audio File<br />
JXplorer lets you import an audio file into the directory, and export it using your<br />
system’s file browser. You can also play the audio file from in JXplorer. You can<br />
import all audio formats; however, the Audio dialog plays only the following<br />
formats:<br />
■<br />
■<br />
■<br />
■<br />
.mid<br />
.au<br />
.wav<br />
.aiff<br />
Audio files are imported through the Audio dialog, which appears when you<br />
select the audio attribute type in the table editor.<br />
Adding Files that Can Be Launched<br />
JXplorer provides the odMultimedia class that contains attribute types that let<br />
you launch files of the following formats:<br />
Format<br />
.avi<br />
.doc<br />
.mid<br />
.wav<br />
.xls<br />
Attribute Type<br />
odMovieAVI<br />
odDocumentDOC<br />
odMusicMID<br />
odSoundWAV<br />
odSpreadSheetXLS<br />
A dialog appears when you click the value field of one of these attribute types in<br />
the table editor.<br />
For more information about how to add these files, see the online help.<br />
11–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Editing the <strong>Directory</strong><br />
Adding a New Entry<br />
You can add an entry by selecting the New option.<br />
The new entry is created as a child of the currently selected entry in the tree.<br />
When a new entry is created, you must specify the entry’s RDN and list its object<br />
classes.<br />
Choosing Object Classes<br />
When there are other children of the selected entry, the browser suggests object<br />
classes based on those children; otherwise, you must select them. (To turn this<br />
behavior off, clear the Suggest Classes checkbox). Since the browser is schema<br />
aware, it can fill in any required parent classes.<br />
The choice of object classes must conform to the restrictions laid down by the<br />
schema. The server may also have additional schema rules restricting where<br />
entries of a particular type are created. For example, it may not be possible to<br />
create a country entry underneath an organizationalUnit entry.<br />
Setting Initial Attribute Values<br />
When all information is entered in the new entry dialog, the entry is set up in the<br />
browser, and you can fill in the entry’s attributes in the table editor. Before the<br />
entry is actually created in the directory, you must enter the information for the<br />
attributes and submit them—especially mandatory attributes.<br />
Using JXplorer 11–23
Editing the <strong>Directory</strong><br />
Submitting an Entry to the <strong>Directory</strong><br />
Once a new entry has been filled in, or an existing entry has been modified, you<br />
must submit the result to the directory. The browser checks for consistency using<br />
schema information, and the directory checks the entry again when it is<br />
submitted.<br />
If the entry is invalid, the browser reports the directory error to you, but leaves<br />
your changes unaltered in the edit table. To discard your changes, click the Reset<br />
button.<br />
Submitted entries are:<br />
■<br />
■<br />
■<br />
Checked for gross errors by the browser.<br />
Submitted to the directory through LDAP.<br />
Checked for errors by the directory, after which either:<br />
– The user is informed if an error has occurred.<br />
– If no error has occurred, the browser display tree is updated.<br />
11–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Using LDIF Files<br />
Using LDIF Files<br />
LDIF files are a widely used format for saving directory information, similar to<br />
the use of comma-separated value files for storing a table from a relational<br />
database. LDIF is an Internet standard (RFC 2849) for storing directory entries in<br />
a text file as a distinguished name followed by a list of attribute and value pairs.<br />
More information about LDIF is available from the IETF (Internet Engineering<br />
Task Force) at their web site http://www.ietf.org/rfc/rfc2849.txt.<br />
JXplorer lets you use LDIF files to save, enter, and edit directory information,<br />
both with and without an LDAP connection to a directory.<br />
Importing and Exporting an LDIF File<br />
You can import an LDIF file into or exported it from the browser. When the<br />
browser is connected to a directory, it reads the values from the selected file and<br />
added them to the directory, or reads the values from the directory and writes<br />
them to an LDIF file.<br />
JXplorer:<br />
■<br />
■<br />
■<br />
Lets the prefix of the DNs in the LDIF file be replaced when reading or<br />
writing an entry to assist in data migration between directories<br />
Automatically handles base-64-encoded binary LDIF data<br />
Flags (with the help of the directory) when LDIF data entries are invalid<br />
In addition, JXplorer provides a status display when it estimates that a large<br />
import or export operation is taking place. The status display shows the number<br />
of entries processed and the estimated proportion processed. Click Cancel when<br />
you want to quit a long operation.<br />
Using an LDIF File Without a <strong>Directory</strong><br />
An added feature of JXplorer is that it lets you use an LDIF file directly as a<br />
miniature directory without any LDAP connection to a directory server. Using an<br />
LDIF file offline in this way can be useful for:<br />
■<br />
■<br />
■<br />
■<br />
Editing during data migration<br />
Caching data over a slow communication link<br />
Stand-alone demonstrations (on laptops, for example)<br />
Reviewing data before committing it to a production environment<br />
Using JXplorer 11–25
Using LDIF Files<br />
Viewing and Saving Offline<br />
To start offline operation, choose Ldif from the menu bar, and then select View<br />
Offline. Select an LDIF file in the same way any LDIF file is imported into the<br />
directory. Once selected, the browser loads the LDIF file, which is displayed as a<br />
directory tree.<br />
You can save the entire tree, or any subtree, at any time to any existing, or new,<br />
LDIF file. To do this, choose Ldif from the menu bar, and then select Export Full<br />
Tree or Export Subtree.<br />
Navigating and Editing Offline<br />
Because there is no communication lag, you may navigate the offline LDIF file<br />
faster than using a directory. You can also edit the LDIF file, and add and<br />
manipulate binary values. The only restriction in the use of offline LDIF files is<br />
that they cannot be searched. To search an LDIF file, you must load the file in a<br />
directory (or the raw LDIF file viewed using a text editor).<br />
Binary Values in LDIF Files<br />
Binary values in LDIF files are stored in base 64 format. This means that you can<br />
copy and paste binary values between JXplorer and LDIF files with the same ease<br />
as other string values.<br />
For more information about base 64 encoding, see IETF in RFC1521, available at:<br />
http://www.ietf.org/rfc/rfc1521.txt.<br />
11–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Using SSL and SASL<br />
Using SSL and SASL<br />
It is possible to specify that SSL should be used to communicate securely with a<br />
directory server using two variants:<br />
■<br />
■<br />
SSL with server authentication only (simple)<br />
SSL with both client and server authentication (authenticated)<br />
When client authentication is used for the SSL connection, it is possible for the<br />
server to use SASL to authenticate the client, using the client’s certificate to verify<br />
the client’s identity.<br />
Server Authenticated SSL<br />
For server authenticated SSL to work, you must initialize the client with the<br />
trusted public certificate of the directory server, or the server’s certificate<br />
authority. The default keystore for trusted certificates is the security/cacerts file,<br />
which comes initialized with the certificate authority certificate used to create the<br />
demonstration DXserver certificates. While you can change this, the default<br />
setup lets the demonstration directories be contacted immediately using SSL.<br />
You can connect to the directory using server authenticated SSL, as either an<br />
anonymous user, or with your user name and password. To do this, from the<br />
connection dialog, select either SSL + Anonymous, or SSL + User + Password.<br />
Client Authenticated SSL and SASL<br />
Client authenticated SSL requires the registration of the server’s certificate with<br />
the browser, and in addition, the registration of the browser’s certificate (or<br />
certificate authority) with the server. A demonstration client certificate<br />
marjorie.pem is provided in the security directory. Client authenticated SSL<br />
requires the use of the browser’s private key, which is held in the<br />
…//security/clientcerts file. This file is password protected, and requires the<br />
password to be entered in the connection dialog for client authenticated SSL to<br />
work.<br />
The DXserver directory is able to use SASL authentication to authenticate a user,<br />
rather than a user name and password. This implementation of SASL uses the<br />
certificates previously exchanged by SSL, and will only work when client<br />
authenticated SSL is used. This differs from server authenticated SSL where no<br />
client certificate is produced, so the directory is not able to use it to establish<br />
identity.<br />
Using JXplorer 11–27
Online Help<br />
To connect to the directory using client authenticated SSL, from the connection<br />
dialog, select SSL + SASL + Keystore Password, and enter the client certificate<br />
keystore password.<br />
The secure use of client authenticated SSL requires creating a new private key for<br />
the browser rather than using the default private key. This requires using a<br />
Public Key Infrastructure (PKI) tool, such as <strong>eTrust</strong> PKI or Open SSL, to<br />
produce a PKCS8 private key.<br />
Managing Certificates and Keystores<br />
To use SSL in either form, you must manage a variety of certificates and private<br />
keys. These are kept in two Java keystores, which are password protected data<br />
stores. The first keystore, …//security/cacerts, with the password changeit, is<br />
used for storing the public certificates of trusted certificate authorities and<br />
servers. The second keystore, …//security/clientcerts, is used for storing the<br />
certificates and private keys of the JXplorer browser, and it has the password<br />
passphrase. Manage these keystores from the Security menu in JXplorer, where<br />
you can change the default keystore passwords.<br />
To manage the certificates of trusted certificate authorities and servers, from the<br />
Security menu, choose Trusted Servers and <strong>CA</strong>s. From the dialog, you can view,<br />
add and delete certificates, and set the keystore password.<br />
To manage the certificates and private keys of the JXplorer browser, from the<br />
Security menu, choose Client Certificates. From the dialog, you can view, add,<br />
and delete certificates, and apply private keys to corresponding certificates. You<br />
can also export private keys and set the keystore password.<br />
The JXplorer browser uses the standard Java cryptography tools for its SSL<br />
support. These two files are standard Java keystores, which you can maintain<br />
using the Java keytool utility. This is a command line utility produced by Sun<br />
Microsystems. For more information, see<br />
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html.<br />
Online Help<br />
The online help system provides a number of immediately available aids to the<br />
user, including:<br />
■<br />
■<br />
■<br />
An index of help topics that explain browser usage<br />
A table of contents<br />
Links to external web resources<br />
11–28 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring JXplorer<br />
Configuring JXplorer<br />
You can customize the following JXplorer features:<br />
■<br />
■<br />
■<br />
■<br />
HTML templates<br />
Browser panels<br />
Logging and tracing<br />
<strong>Directory</strong> tree icons<br />
You can also create plugin editors for binary files.<br />
View Menu<br />
The View menu lets you access the toolbar configuration and refresh options.<br />
The button bar and quick search bar are not required for the operation of the<br />
browser and if you are short of window space you can hide either or both of<br />
these bars. To do this, from the View menu, choose Show Button Bar and/or<br />
Show Search Bar.<br />
Options Menu<br />
A number of behavioral options are available via the Options menu. These are<br />
described in the following sections.<br />
Look-and-Feel Options<br />
Java supports a number of look-and-feel options for graphical interfaces. These<br />
let the browser adopt the same appearance as other native applications on a<br />
particular operating system.<br />
You can also switch between appearances on the same operating system if you<br />
are more familiar with one particular look than another.<br />
For example, a UNIX user may be more familiar with the Motif/X Windows<br />
appearance and may prefer to use that on a Microsoft Windows platform. The<br />
possible look-and-feel options are:<br />
■<br />
■<br />
■<br />
Microsoft Windows<br />
Motif/X Windows<br />
Java<br />
Using JXplorer 11–29
Configuring JXplorer<br />
You can set these options from the Advanced Options dialog, which can be<br />
accessed via the Options menu. To select an interface, click on the L & F tab,<br />
select the look-and-feel interface you want, and then click the Apply button.<br />
For copyright reasons, the Microsoft Windows option is not available on<br />
non-Microsoft platforms.<br />
Safety Mode<br />
A single JXplorer operation can affect thousands of directory entries. To prevent<br />
accidental changes, you can choose to be reminded before you make changes to<br />
the directory. To do this, from the Options menu, choose Confirm Tree<br />
Operations. The following dialog appears prior to modifying the directory by a<br />
tree operation:<br />
To remove this behavior, deselect Confirm Tree Operations from the Options<br />
menu.<br />
Confirming Changes to the <strong>Directory</strong><br />
Some users like to receive a confirmation message when making a change to the<br />
directory. To enable the confirmation dialog, from the Options menu, choose<br />
Confirm Table Editor Updates. The following dialog box appears:<br />
To remove this behavior, from the Options menu, deselect Confirm Table Editor<br />
Updates.<br />
11–30 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring JXplorer<br />
Logging Level<br />
There are a number of logging options available, ranging from no logging at all<br />
to complete tracing of all the LDAP communications with the directory.<br />
The client can log data to a log file, to the console window, to both, or not at all.<br />
The following levels of logging information are currently available:<br />
Level Description Meaning<br />
0 Errors Only Reports errors only.<br />
1 Basic Reports errors and additional warning information.<br />
4 Tree<br />
Operations<br />
Logs internal tree operations, and other high-level<br />
process information.<br />
6 Extensive Extensively logs internal browser operations.<br />
8 All Traces all internal operations, including the<br />
translation system, and the resource loading system.<br />
9 All + BER Trace Reports all of the previous information, plus has an<br />
LDAP Basic Encoding Rules (BER) communications<br />
trace. Useful for de-bugging directory-client<br />
communications problems.<br />
Usually, clients run at level 0 or level 1. However, level 4 can be useful for<br />
auditing all transactions, and level 9 can be useful for debugging directory-client<br />
communication problems.<br />
Note: Level 9 may cause JXplorer to run slower.<br />
You can set these options from the Advanced Options dialog, which can be<br />
accessed via the Options menu. To select a logging level, click on the Log Level<br />
tab, select the logging level you want, and then click the Apply button.<br />
Using JXplorer 11–31
Configuring JXplorer<br />
Logging Method<br />
JXplorer lets you choose the method by which you view logging details. The<br />
methods available are as follows:<br />
Method<br />
None<br />
Console<br />
File<br />
Console and File<br />
Meaning<br />
No logging is performed.<br />
Logging details can be viewed via a console.<br />
Logging details are copied to a file in<br />
.../jxplorer/jxplorer.log.<br />
Logging details can be viewed via a management console;<br />
they are also copied to a file in …/jxplorer/jxplorer.log.<br />
You can set these options from the Advanced Options dialog, which can be<br />
accessed via the Options menu. To select a logging method, simply click on the<br />
Log Method tab, select the logging method you want, and then click the Apply<br />
button.<br />
Ignore Schema Checking<br />
DXserver automatically checks all entries submitted to the directory to ensure<br />
that they conform to the directory schema. However, when the network is slow,<br />
it may be wise to check the entry on JXplorer, before you send it to the server. To<br />
do this, from the Options menu, deselect Ignore Schema Checking.<br />
If you do not want JXplorer to check that an entry conforms to the directory<br />
schema when you submit it, select Ignore Schema Checking from the Options<br />
menu.<br />
Resolve Aliases While Browsing<br />
When you select an alias entry in the directory, you can choose whether to view<br />
all of the entry details or the details of the alias entry, that is, where the alias<br />
entry points.<br />
When you want to view all of the entry details, from the Options menu, choose<br />
Resolve Aliases While Browsing. To display only the details of the alias entry,<br />
deselect Resolve Aliases While Browsing from the Options menu.<br />
11–32 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring JXplorer<br />
Alias Example<br />
If you create an alias entry under Human Resources for Paul Smith in<br />
Marketing and you select Resolve Aliases While Browsing, when you select<br />
Paul’s alias entry under Human Resources you will see all of his details, just as<br />
if you had selected his entry under Marketing.<br />
However, if you deselect Resolve Aliases While Browsing, when you select<br />
Paul’s alias entry under Human Resources you will see the details of the aliased<br />
object name.<br />
Search Limits<br />
JXplorer lets you define the maximum number of entries returned from a search,<br />
and the time (in seconds) allowed to perform the search.<br />
You can set these options from the Advanced Options dialog, which can be<br />
accessed via the Options menu. To select the search limits, click on the Search<br />
Limits tab, select the LDAP limit and LDAP timeout that you want, and then<br />
click the Apply button. To revert the search limits back to the last saved version<br />
click the Reset button.<br />
Values can also be set in the server configuration (.dxc) files. When values are set<br />
in JXplorer and the server configuration files, the lower of the two values is<br />
accepted.<br />
URL Page Browser<br />
By default, linked URL pages are launched in JXplorer. However, on a Windows<br />
system, you can choose to launch them in an external web browser. To customize<br />
this behavior, choose Advanced Options from the Options menu and click the<br />
URL tab.<br />
Using JXplorer 11–33
Configuring JXplorer<br />
Creating HTML Viewing Templates<br />
You can create HTML templates and place them in a file directory hierarchy<br />
under the /templates subdirectory of the JXplorer root directory. When a shared<br />
template directory exists on the file system, you can configure JXplorer to use<br />
that directory instead by editing the dxconfig.txt configuration file in the<br />
JXplorer directory.<br />
Place templates in file directories corresponding to object class names. Within<br />
these file directories, the templates can have any name (although names that<br />
include spaces are not recommended). Templates placed directly in the<br />
/templates directory are common to all object classes. For example, the following<br />
file directory structure provides a general template, two templates for person,<br />
and a default template for organizationalUnit:<br />
<strong>Directory</strong><br />
/templates/<br />
/templates/person<br />
/templates/organizationalUnit<br />
Template Files<br />
general.html<br />
employee.html<br />
contractor.html<br />
default.html<br />
You can add any number of new HTML templates, including templates for<br />
newly defined object classes by creating (if necessary) the appropriate<br />
subdirectory under the /templates directory and placing the new HTML files in<br />
that subdirectory. After you add new files, you may need to restart the browser<br />
to recognize them.<br />
HTML Tag Extensions<br />
The HTML language is extended using a modification to the HTML <br />
tag to set placeholders where attribute values can be filled in.<br />
These extension tags:<br />
■<br />
■<br />
■<br />
Position individual attribute names and values in the page<br />
List of all attribute names and values to be set with a single tag<br />
Provide a variety of tabulated formatting options, such as HTML tables and<br />
lists<br />
See the JXplorer online help for more information.<br />
11–34 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Configuring JXplorer<br />
HTML Forms<br />
You can also use standard HTML forms; however, you must give each form<br />
element a name value that corresponds to an attribute, for example, title.<br />
JXplorer will display existing values and make updates to the directory when<br />
you click Submit.<br />
Important! JXplorer submits the changes to the directory, not to a Web server.<br />
A number of example HTML forms are in the templates sub-directory. For more<br />
information, see the JXplorer online help.<br />
Configuring Tree Icons<br />
The browser reads the icons used in the directory display tree from the /icons<br />
subdirectory of the JXplorer home directory. The icons are 16-pixel-square<br />
images in the form:<br />
object_class_name.gif<br />
You can easily replace the icons. To make sure the browser recognizes the new<br />
icons, you must restart it. For more information, see the JXplorer online help.<br />
Extending the Java Binary Editor<br />
JXplorer can be extended with user-defined binary editors inherited from the<br />
Java class com.cai.od.editor, AbstractBinaryEditor. Such an editor class must be<br />
named objectclassEditor (for example, certificateEditor) and placed in the<br />
subdirectory com/cai/od/editor. When the browser is asked to edit a binary<br />
object, it first searches in this directory for any editors that have the name of the<br />
entry’s object class and dynamically loads them if they exist. For more<br />
information, see the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer <strong>Guide</strong>.<br />
Plug-in Entry Editors<br />
JXplorer can be extended to load small Java programs, similar to Web applets,<br />
based on an entry’s object class. For more information, see the <strong>eTrust</strong> <strong>Directory</strong><br />
SDK Developer <strong>Guide</strong>.<br />
Internationalization<br />
You can localize JXplorer by using the language resource files in the languages<br />
directory. For more information, see the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer <strong>Guide</strong>.<br />
Using JXplorer 11–35
Configuring JXplorer<br />
Troubleshooting<br />
If you experience trouble while using JXplorer, you can run the console.bat<br />
utility provided in the JXplorer home directory, which displays any problems.<br />
Other LDAP and <strong>Directory</strong> Resources<br />
A number of online resources are available on the web:<br />
■<br />
■<br />
■<br />
http://supportconnect.ca.com—Computer Associates Technical Support.<br />
http://www.ietf.org/rfc/—Information about the LDAP protocol is<br />
available in a number of Internet RFC documents, especially (for LDAP V3)<br />
RFC2251 through RFC2256.<br />
http://www.java.sun.com/products/jndi/index.html—Details of the Java<br />
naming and directory interface (JNDI) are available from Sun Microsystems.<br />
11–36 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
12<br />
Using DXmanager<br />
DXmanager is a graphical web-based management portal. It lets you view and<br />
monitor all of the namespaces and DSAs within a distributed <strong>eTrust</strong> <strong>Directory</strong><br />
environment.<br />
DXmanager is a web tool that lets you monitor all of the namespaces and DSAs<br />
in a distributed <strong>eTrust</strong> <strong>Directory</strong> environment. Using DXmanager, you can<br />
monitor the following:<br />
■<br />
■<br />
■<br />
■<br />
The status of each DSA<br />
Configuration information about each DSA<br />
Statistics about each DSA<br />
Namespace diagrams for each DSA, server, or group of servers<br />
Using DXmanager 12–1
How DXmanager Works<br />
How DXmanager Works<br />
DXmanager uses the DXadmind tool to work with DXserver.<br />
The DXadmind tool is installed on each server that contains <strong>eTrust</strong> <strong>Directory</strong><br />
DSAs. This tool is a background process that enables monitoring of all DXservers<br />
that are configured on the machine that runs DXadmind.<br />
DXmanager works uses the data that each DXadmind tool extracts from the<br />
DSAs on its server.<br />
This diagram shows how DXmanager uses DXadmind to monitor DSAs within<br />
the <strong>eTrust</strong> <strong>Directory</strong> system:<br />
Computer 1<br />
Internet<br />
Browser<br />
DXmanager<br />
DXadmind<br />
DXadmind<br />
Democorp<br />
DSA<br />
UNSPSC<br />
DSA<br />
UDDI DSA<br />
Democorp<br />
DSA<br />
UNSPSC<br />
DSA<br />
UDDI DSA<br />
Computer 2<br />
Computer 3<br />
DXmanager presents data collected by DXadmind<br />
12–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
How You Can Use DXmanager<br />
How You Can Use DXmanager<br />
You can use the information presented by DXmanager to diagnose problems<br />
earlier and more accurately.<br />
Monitor DSA Status<br />
Monitor the status of each DSA—The status can be started, stopped, can't<br />
connect to server<br />
Check DSA Configuration<br />
Check on the configuration information about each DSA—Including the DSA<br />
name and prefix, and port numbers. See the ZZZ section for a full list of<br />
configuration items that DXmanager can let you monitor.<br />
Track DSA Statistics<br />
Track statistics about each DSA—Including the time the DSA has been running,<br />
the number of incoming and outgoing operations, and the number of<br />
anonymous binds. See the ZZZ section for a full list of statistics that DXmanager<br />
can let you monitor.<br />
Check Namespace Design<br />
DXmanager can display the namespace design for each host. It shows a tree in<br />
which all of the DSAs on that computer are connected.<br />
The following DXmanager page shows the namespace on a computer with the<br />
sample DSAs Router, Democorp, and UNSPSC installed:<br />
Using DXmanager 12–3
How DXmanager Presents Information<br />
How DXmanager Presents Information<br />
Using DXmanager, you can easily monitor the DSAs on a group of servers. This<br />
is useful for systems where a single directory information tree (DIT) is spread<br />
across many servers.<br />
To work with server groups, you need to define the server groups first. You can<br />
then use DXmanager to monitor the DSAs in those server groups.<br />
When you install <strong>eTrust</strong> <strong>Directory</strong>, a single server group named Default is<br />
created. This server group contains only the DSAs running on the local<br />
computer.<br />
Starting DXmanager<br />
To start DXmanager on a Windows computer:<br />
1. Click Start, All Programs, Computer Associates, <strong>eTrust</strong>, <strong>eTrust</strong> <strong>Directory</strong>,<br />
Management and Samples.<br />
2. Click the DXmanager link.<br />
To start DXmanager on a UNIX or Linux computer:<br />
1. Open a web browser..<br />
2. Go to this page:<br />
http://hostname:8080/dxmanager<br />
where hostname is the name of the computer on which DXmanager is<br />
running. Use localhost for the local computer.<br />
12–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Troubleshooting<br />
Troubleshooting<br />
This section describes how to deal with some problems that may occur while you<br />
use Dxmananger.<br />
Connectivity<br />
The main area to investigate is usually connectivity.<br />
If DXmanager cannot connect to the <strong>eTrust</strong> <strong>Directory</strong> Administration Daemon<br />
(dxadmind) on the server being scanned then no information can be returned.<br />
If this is the case, use the following steps:<br />
Use the ping command to ping the target server from the system running<br />
DXmanager's <strong>eTrust</strong> <strong>Directory</strong> WebServer.<br />
If this succeeds logon to the target server and ensure that the <strong>eTrust</strong> <strong>Directory</strong><br />
Administration Daemon (dxadmind) is running. On windows it appears in the<br />
Service Manager. On UNIX it appears as a process named dxadmind start. On<br />
either system the command dxadmind status should return:<br />
master is running<br />
DXadmind uses a configuration file in the dxserver\config folder called<br />
dxadmind.ldif. Ensure this contains the line:<br />
dxadminURL: ldap://hostname:2123/<br />
where hostname is the hostname of the target server.<br />
DXwebserver Port Numbers<br />
DXwebserver uses a set of ports. These default ports may conflict with existing<br />
ports on the machine on which DXwebserver is being installed.<br />
See the section Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in Chapter 2 for a list of<br />
the default ports used by DXwebserver and other components.<br />
If DXwebserver Does Not Start<br />
Check the logs under the DXwebserver installation directory for port conflicts.<br />
Look for this file in:<br />
■<br />
Windows: %DXHOME%\..\DXwebserver\logs<br />
■ UNIX: $DXHOME/../dxwebserver/logs<br />
Using DXmanager 12–5
Troubleshooting<br />
If there is a port number conflict, modify the DXwebserver configuration file. By<br />
default, DXwebserver is set to use the port 8080.<br />
To change the port number, you will need to modify the DXwebserver<br />
configuration file server.xml:<br />
1. Install DXwebserver as usual.<br />
2. Look for this file in the following locations:<br />
- Windows: %DXHOME%\..\DXwebserver\conf<br />
- UNIX: $DXHOME/../dxwebserver/conf<br />
3. In the server.xml file, look for the Connector section:<br />
<br />
<br />
4. Change the port number from 8080 to another port number.<br />
5. Restart DXwebserver to pick up the new port number.<br />
If the Main HTTP Connection Port Number Is Modified<br />
The main HTTP connection port number is set to 8080 by default. If this port<br />
number is modified, then some of the web applications may not work correctly,<br />
and on Windows computers, the Start menu shortcuts to Management and<br />
Samples will be affected.<br />
Note the new port number for future HTTP connections.<br />
12–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
13<br />
Using JXweb<br />
JXweb is a general purpose LDAP-compliant directory browser and editor,<br />
which provides access to a directory through the Web. It provides similar<br />
functions as those provided by JXplorer.<br />
JXweb lets you:<br />
■<br />
■<br />
■<br />
■<br />
Connect remotely to any directory that supports LDAP<br />
Browse the directory<br />
Update directory entries<br />
Manipulate the directory tree<br />
Using JXweb 13–1
Connecting to JXweb<br />
Connecting to JXweb<br />
To access JXweb, all you need is a web browser and a network connection to a<br />
computer on which JXweb is installed.<br />
If JXweb is installed on your Windows computer, you can start JXweb from the<br />
Start menu:<br />
1. Click Start on the taskbar, and then choose Programs, Computer Associates,<br />
<strong>eTrust</strong>, <strong>eTrust</strong> <strong>Directory</strong>, Management and Samples.<br />
2. On the displayed page, click JXweb.<br />
If you want to open JXweb on another computer:<br />
1. Start your web browser.<br />
2. Enter the URL http://server:port number/jxweb/index.html, where:<br />
- server is the name of the server on which JXweb is installed<br />
- port number is the number of the JXweb port. The default is 8080.<br />
For example: http://computer32:8080/jxweb/index.html<br />
The browser displays the JXweb Connect dialog:<br />
13–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Connecting to a <strong>Directory</strong><br />
Connecting to a <strong>Directory</strong><br />
From the JXweb Connect dialog, you can connect to a directory. The browser<br />
requires the following information for you to log in to a directory:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
The name of the computer that hosts the directory<br />
The port number of the directory server<br />
(Optional) The base distinguished name of the directory, for example,<br />
o=DEMOCORP,c=AU<br />
(Optional) The distinguished name of your user account, if the directory to<br />
which you want to connect has access controls enabled<br />
(Optional) A user password that you must provide if you use your user<br />
account<br />
When you are connected to a directory and want to connect to another, click<br />
Connect on the menu bar to display the JXweb Connect dialog.<br />
When you exit your browser, you disconnect from the directory.<br />
Using JXweb 13–3
The JXweb Environment<br />
The JXweb Environment<br />
When you connect to the directory, the left pane displays the <strong>Directory</strong><br />
Information Tree (DIT) of the directory to which you are connected. Click an<br />
entry to display its details in the right pane. The DN of the displayed details<br />
appears at the top of the pane. You can update the entry details (for example,<br />
Edit) and manipulate the selected branch of the DIT (for example, Copy or<br />
Move). For more information about JXweb, click Help from the JXweb menu bar.<br />
Customizing JXweb<br />
JXweb was created using Velocity tags, which render the HTML pages in JXweb.<br />
To create your own look and feel for the packaged version of JXweb, you can<br />
manipulate the HTML code and the Velocity tags.<br />
For a description of the Velocity tags used in JXweb, see the JXweb online help.<br />
For an example of how you can adjust JXweb to suit your organization, see the<br />
Democorp sample in the dxwebserver\samples directory. This is a version of<br />
JXweb that has been customized to work well for the fictional company<br />
Democorp.<br />
13–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Using JXweb in Languages Other Than English<br />
Using JXweb in Languages Other Than English<br />
<strong>eTrust</strong> <strong>Directory</strong> is language certified for the following nine languages:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Brazilian Portuguese<br />
French<br />
German<br />
Italian<br />
Japanese<br />
Korean<br />
Simplified Chinese<br />
Spanish<br />
Traditional Chinese<br />
This means that all <strong>eTrust</strong> <strong>Directory</strong> components run on operating systems in<br />
those languages.<br />
Displaying Non-English Characters in Internet Explorer<br />
By default Internet Explorer detects the language encoding automatically.<br />
However, if there are problems with displaying non-English characters:<br />
■<br />
In Internet Explorer, select View, Encoding, Auto-Select has a check mark.<br />
Displaying Non-English Characters in Mozilla Browsers<br />
Web browsers based on the Mozilla engine (including Netscape) do not autodetect<br />
the character encoding correctly.<br />
If there are problems with the characters displayed:<br />
1. In the Mozilla browser, select View, Character Coding, Auto-Detect, Off.<br />
2. Select View, Character Coding, Unicode (UTF-8).<br />
Online Help<br />
Use the online help to learn about how to use the JXweb interface, and how to<br />
customize JXweb.<br />
Using JXweb 13–5
Chapter<br />
14<br />
Using The UDDI Server<br />
Universal Description, Discovery and Integration (UDDI) is an evolving standard<br />
interface to information about services. A UDDI registry is a directory of<br />
businesses and the services they offer.<br />
In a UDDI registry, all the information is presented in a well-defined manner so<br />
that it can be used by automated components and by humans. This lets the<br />
repository be used, for example, as a means for an application to locate a<br />
replacement service, should the service it is using become unavailable.<br />
The full details of the UDDI specification can be found at the UDDI web site<br />
http://www.uddi.org/.<br />
Using The UDDI Server 14–1
About UDDI Registries<br />
About UDDI Registries<br />
A UDDI registry is a directory of all the Web services in an organization, be it a<br />
single business enterprise or a globe-spanning multinational conglomerate.<br />
The UDDI registry provides a central point for recording all the details about<br />
each Web service, enabling the developers in the organization to locate other<br />
Web services to use as building blocks to construct an application, thus saving<br />
time and effort.<br />
What a UDDI Registry Can Do<br />
Because the UDDI registry contains all the details about the interfaces,<br />
developers can more easily combine or present services developed by disparate<br />
groups, possibly in different locations.<br />
Moreover, the UDDI protocol provides for recovery—if a needed service fails<br />
and is replaced by another at a different location, all those services that depend<br />
on it can recover automatically by reloading the location and connection<br />
parameters from the UDDI registry.<br />
About the <strong>eTrust</strong> <strong>Directory</strong> UDDI Server<br />
The <strong>eTrust</strong> <strong>Directory</strong> UDDI Server provides repository services. It functions as a<br />
business directory, permitting searches based upon categorizations and<br />
relationships between businesses. It provides authentication and authorization of<br />
users for inquiry and publishing.<br />
A server provides UDDI services to requests from clients. A web-based UDDI<br />
Client enables you to publish to or search the repository.<br />
14–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>eTrust</strong> <strong>Directory</strong> UDDI Server<br />
<strong>eTrust</strong> <strong>Directory</strong> UDDI Server<br />
The <strong>eTrust</strong> <strong>Directory</strong> UDDI Server provides repository services. It can function<br />
as a business directory, enabling searches based upon categorizations and<br />
relationships between businesses. It provides authentication and authorization of<br />
users, for inquiry and publishing. It acts as a repository for UDDI information<br />
and as an engine for processing UDDI requests.<br />
The UDDI server is installed under the Tomcat servlet container. It provides<br />
UDDI services to client applications that make requests by using the Simple<br />
Object Access Protocol (SOAP).<br />
The UDDI Server is a multi-version server, responding to requests in UDDI<br />
Version 1, Version 2, and Version 3 formats. For more information about the<br />
UDDI APIs, see the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer <strong>Guide</strong>.<br />
The web-based UDDI Client enables users to:<br />
■<br />
■<br />
Publish services to the repository.<br />
Search for specific entries in the repository.<br />
Using The UDDI Server 14–3
Connecting to the UDDI Client<br />
Connecting to the UDDI Client<br />
On Windows Only 1. Open the Management and Samples page. To do this, from the start button,<br />
select Programs, Computer Associates, <strong>eTrust</strong>, <strong>eTrust</strong> <strong>Directory</strong>,<br />
Management and Samples.<br />
2. Click on the UDDI Client link.<br />
On UNIX Or Windows<br />
You can also access the UDDI Client directly from your web browser. Start your<br />
web browser and enter the following URL, where server is the name of the host<br />
on which the client is installed:<br />
http://server:8080/uddiv3-client/index.html<br />
The <strong>eTrust</strong> <strong>Directory</strong> UDDI Client Connect page appears.<br />
14–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Connecting to a UDDI Registry<br />
Connecting to a UDDI Registry<br />
The UDDI Client Connect page enables you to connect to a UDDI registry.<br />
By default, the client uses the following URLs to connect to the UDDI Server on<br />
the same computer as the UDDI Client:<br />
Inquiry URL: http://localhost:8080/uddi/services/Inquiry<br />
Publish URL: http://localhost:8080/uddi/services/Publishing<br />
When you want to connect to a server on a different host, change localhost in both<br />
of these URLs to the name of the UDDI Server computer, then click Connect.<br />
When you want to change servers at any time after you have connected, click<br />
Connect on the menu bar to return to this page.<br />
Using tModels<br />
A tModel is a data structure representing a service type (a generic representation<br />
of a registered service) in the UDDI Server. Each tModel consists of a name, an<br />
explanatory description, and a Universal Unique Identifier (UUID). It can also<br />
provide a URL that enables users to get further information.<br />
A tModel may represent a technical specification. Services that are compliant<br />
with the specification may reference the tModel. This facilitates the searching of<br />
services that are compliant with a particular specification.<br />
You can also use a tModel to provide meaning to data. For example, a tModel<br />
can give structure to the following address line: 12 Montgomery Street, where 12<br />
has the meaning of street number and Montgomery Street has the meaning of<br />
street name.<br />
Using The UDDI Server 14–5
Using the UDDI Client in Languages Other Than English<br />
Using the UDDI Client in Languages Other Than English<br />
<strong>eTrust</strong> <strong>Directory</strong> is language certified for the following nine languages:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Brazilian Portuguese<br />
French<br />
German<br />
Italian<br />
Japanese<br />
Korean<br />
Simplified Chinese<br />
Spanish<br />
Traditional Chinese<br />
This means that all <strong>eTrust</strong> <strong>Directory</strong> components run on operating systems in<br />
those languages.<br />
Displaying Non-English Characters in Internet Explorer<br />
By default Internet Explorer detects the language encoding automatically.<br />
However, if there are problems with displaying non-English characters:<br />
■<br />
In Internet Explorer, select View, Encoding, Auto-Select has a check mark.<br />
Displaying Non-English Characters in Mozilla Browsers<br />
Web browsers based on the Mozilla engine (including Netscape) do not autodetect<br />
the character encoding correctly.<br />
If there are problems with the characters displayed:<br />
1. In the Mozilla browser, select View, Character Coding, Auto-Detect, Off.<br />
2. Select View, Character Coding, Unicode (UTF-8).<br />
14–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
15<br />
Using the Sample DSAs,<br />
Applications, and Tools<br />
<strong>eTrust</strong> <strong>Directory</strong> comes with a number of samples for testing and demonstration<br />
purposes:<br />
■ Sample directories<br />
■ Sample web applications<br />
■ Sample configuration files<br />
■ Sample tools<br />
These technology previews are not covered by your usual <strong>CA</strong> Support. However,<br />
your feedback is very welcome. Please see the Readme files in each sample<br />
directory for how to let us know about your comments or questions.<br />
Using the Sample DSAs, Applications, and Tools 15–1
Implementing the Samples<br />
Implementing the Samples<br />
In a default installation, these samples are installed but not set up. You need to<br />
install each sample you want to work with.<br />
By default, the sample directories and sample tools are installed under the<br />
following directory:<br />
■<br />
Windows: %DXHOME%\samples<br />
■ UNIX: $DXHOME/samples<br />
By default, the web applications are installed under the following directory:<br />
■<br />
Windows: %DXHOME%\..\dxwebserver\samples<br />
■ UNIX: $DXHOME/../dxwebserver/samples<br />
The sample configuration files are installed into the main configuration file<br />
directories. The default location is:<br />
■<br />
Windows: %DXHOME%\..\config<br />
■ UNIX: $DXHOME/../config<br />
For more information about setting up these samples, see the appendixes<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows and Installing <strong>eTrust</strong> <strong>Directory</strong> for<br />
UNIX, and also the Readme files in each of the sample directories.<br />
15–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The Sample DSAs<br />
The Sample DSAs<br />
This section describes the sample directories, and explains how to install them<br />
manually.<br />
What the Sample DSAs Are Useful For<br />
<strong>eTrust</strong> <strong>Directory</strong> provides a number of sample directories, which contain<br />
different DSA configurations and show different methods of populating a<br />
directory.<br />
You can also use these samples to explore the <strong>eTrust</strong> <strong>Directory</strong> features before<br />
setting up your own directory.<br />
When the Sample DSAs Are Installed<br />
When you run a default installation of <strong>eTrust</strong> <strong>Directory</strong>, the three sample<br />
directories are automatically installed, configured, and started.<br />
If you run a customer installation, you can choose whether to install the sample<br />
directories.<br />
How the Sample DSAs Work Together<br />
Together, the Democorp, Router, and UNSPSC sample directories form a single<br />
logical view of all of the directory information. It does not matter which directory<br />
you connect to. You see the same data because the DSAs cooperate to resolve a<br />
query or update through X.500 distribution.<br />
Router<br />
DSA<br />
DSP<br />
DSP<br />
Democorp<br />
DSA<br />
UNSPSC<br />
DSA<br />
Using the Sample DSAs, Applications, and Tools 15–3
The Sample DSAs<br />
The Democorp DSAs<br />
Democorp is an example of a corporate staff directory.<br />
The Democorp sample models a fictitious company called DemoCorp. There are<br />
about 100 organizational units in the data, with approximately 1200 employees in<br />
total. The Democorp sample demonstrates a front-end load of the directory using<br />
the dxmodify tool.<br />
The Democorp <strong>Directory</strong> Setup Script<br />
The setup script creates a DXserver called democorp using an Advantage Ingres<br />
database called democorp. The directory is loaded using the dxmodify tool with<br />
the prefix O=DEMOCORP, C=AU. This is a demonstration of a front-end load in<br />
a directory. Front-end loads are useful for loading fewer than a few thousand<br />
entries and for loading data in already populated directories.<br />
The data is converted from comma-separated value (CSV) format to LDAP<br />
lightweight directory interchange format(LDIF) by using the csv2ldif tool. The<br />
resulting LDIF file is loaded in the directory by using the dxmodify tool. After<br />
loading, the democorp Advantage Ingres database is tuned.<br />
The setup script performs the following steps:<br />
1. Creates the Democorp Advantage Ingres database called democorp.<br />
2. Configures the Democorp initialization file, database file, knowledge file,<br />
and knowledge group file, and start the Democorp DXserver DSA.<br />
3. Converts the Democorp CSV data to LDIF.<br />
4. Loads the LDIF data in the Democorp directory.<br />
5. Tunes the democorp Advantage Ingres database.<br />
15–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
The Sample DSAs<br />
The UNSPSC DSAs<br />
The United Nations Development Program and Dun & Bradstreet merged their<br />
separate commodity classification coding schemes in 1999 to form the Universal<br />
Standard Products and Services Classification (UNSPSC).<br />
The levels let you search products more precisely because you confine the<br />
searches to logical categories, thus eliminating irrelevant hits. The levels also let<br />
managers perform expenditure analysis on categories relevant to the company’s<br />
situation.<br />
The UNSPSC directory contains more than 10,000 entries.<br />
The UNSPSC <strong>Directory</strong> Setup Script<br />
The UNSPSC sample demonstrates a back-end load of the directory using the<br />
DXloaddb tool.<br />
The setup script creates a DXserver called unspsc using Advantage Ingres. This<br />
is an example of a back-end or bulk load by using the DXloaddb tool. Bulk loads<br />
are very fast because they bypass the DSA and load the data directly in the<br />
database. They are used for initial data loads or updating the entire contents of a<br />
directory.<br />
The data is converted from CSV format to LDIF by using the csv2ldif tool. The<br />
resulting LDIF file is loaded in the directory by using the DXloaddb tool.<br />
The UNSPSC setup script performs the following steps:<br />
1. The script creates the UNSPSC Advantage Ingres database named unspsc.<br />
2. The script configures the UNSPSC initialization file, database file, knowledge<br />
file, and the knowledge group file.<br />
3. The script converts the UNSPSC CSV data to LDIF.<br />
4. The script loads more than 10,000 LDIF entries in the UNSPSC directory.<br />
5. The script starts the UNSPSC DXserver DSA.<br />
Tip: Use the bulk load tools ldifsort and DXloaddb to achieve a highperformance<br />
load of the UNSPSC data by directly loading the Advantage<br />
Ingres UNSPSC database.<br />
Using the Sample DSAs, Applications, and Tools 15–5
The Sample DSAs<br />
The Router DSAs<br />
The Router sample demonstrates a router DSA configuration, where the DSA has<br />
no database, but has knowledge of two subordinate DSAs.<br />
This sample demonstrates how a router DSA does not require a database of its<br />
own. It also acts as a single point of entry into multiple directories as<br />
demonstrated with Democorp and UNSPSC.<br />
The Router <strong>Directory</strong> Setup Script<br />
The setup script creates a DXserver called Router with no database and starts it.<br />
The setup script performs the following steps:<br />
1. Configures the Router initialization file, knowledge file, and knowledge<br />
group file.<br />
2. Starts the Router DXserver DSA.<br />
15–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Web Applications<br />
Sample Web Applications<br />
<strong>eTrust</strong> <strong>Directory</strong> comes with some sample web applications. You can open the<br />
democorp and uddi applications from the Management and Samples page.<br />
For information about the sample web applications, see the Readme files in each<br />
of the sample tools directories.<br />
For a list of all ports in a default installation of <strong>eTrust</strong> <strong>Directory</strong>, see the section<br />
Port Numbers Used by <strong>eTrust</strong> <strong>Directory</strong> in the chapter DXserver Overview.<br />
Customized Version of JXweb: democorp<br />
To demonstrate how easily JXweb can be customized, the Democorp version of<br />
JXweb has been included with <strong>eTrust</strong> <strong>Directory</strong>.<br />
What the UDDI Demonstration Shows<br />
This technology preview is an example of how you can adjust JXweb to suit your<br />
organization. This is a version of JXweb that has been customized to work well<br />
for the fictional company Democorp. It displays entry details in a “business<br />
card” format.<br />
Running the Democorp version of JXweb<br />
To run the Democorp version of JXweb:<br />
1. Open your web browser.<br />
2. Enter the following URL into the Address field:<br />
http://machinename:8080/democorp<br />
where machinename is the name of the computer on which you installed the<br />
Democorp preview. This is the computer on which DXwebserver resides.<br />
Using the Sample DSAs, Applications, and Tools 15–7
Sample Web Applications<br />
Sample DSML Server: dsml<br />
This is a sample DSML server that converts DSML to LDAP and vice versa. This<br />
allows client applications that use DSML (including web services) to<br />
communicate with <strong>eTrust</strong> <strong>Directory</strong> without using LDAP directly.<br />
How the DSML Server Works<br />
The following happens when JXplorer uses DSML to communicate with dxserver<br />
through the DSML server:<br />
1. JXplorer sends DSML requests to the DSML server.<br />
2. The DSML server translates these requests into LDAP requests and passes<br />
them onto the directory.<br />
3. The directory responds using the LDAP protocol.<br />
4. The DSML server translates the LDAP directory response into a DSML<br />
response and sends it back to JXplorer.<br />
Running the DSML Server Using JXplorer<br />
JXplorer can use DSML in order to let it connect to DSML web services. This<br />
means that you can use JXplorer to test the DSML server.<br />
To access the DSML server technology preview using JXplorer:<br />
1. The file dsml.properties points to Democorp on the current machine<br />
2. Connect using a DSML enabled LDAP client (such as JXplorer) to the web<br />
servers, using the following connection settings:<br />
Setting<br />
Value<br />
Host<br />
The name of the computer running the DSML server<br />
Port 8080<br />
Protocol DSML v2<br />
DSML Service dsml-sample/services/DSML<br />
15–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Web Applications<br />
Changing the DSML Sample Properties<br />
1. Open the following file in a text editor:<br />
- Windows: %DXHOME%\..\dxwebserver\webapps\dsmlsample\WEB-INF\dsml.poperties<br />
- UNIX: $DXHOME/../dxwebserver/webapps/dsmlsample/WEB-INF/dsml.properties<br />
Sample SAML Server: saml-sample<br />
This is a sample SAML server that converts SAML to LDAP and vice versa. This<br />
allows client applications that use SAML (including web services) to<br />
communicate with <strong>eTrust</strong> <strong>Directory</strong> without using LDAP directly.<br />
Installing the SAML Sample<br />
1. Navigate to the where you have installed <strong>eTrust</strong> <strong>Directory</strong> (Hint: echo your<br />
DXHOME environment variable if you are unsure where this is). Then<br />
navigate to dxwebserver > samples > saml.<br />
2. If you are on a Windows machine run the 'setup.bat', if on a Solaris machine<br />
run the 'setup.sh'.<br />
This setup file performs the following steps:<br />
a. Stops Tomcat<br />
b. Copies the Tomcat server files and SAML files to<br />
"%DXHOME%\..\dxwebserver\webapps\saml-sample".<br />
c. Restarts Tomcat.<br />
The install should be complete in a few moments.<br />
To Test the SAML Server<br />
For testing you can use the example 'samlping' command line program that<br />
allows for arbitrary SAML attribute requests to be sent to the server.<br />
Run 'samlping -?' for more details.<br />
To Access the SAML Server<br />
1. The file saml.properties points to Democorp on the current machine<br />
2. Connect using a SAML client to the web servers port.<br />
Using the Sample DSAs, Applications, and Tools 15–9
Sample Web Applications<br />
Sample SPML Server: spml-sample<br />
To Install the SPML Sample<br />
1. Navigate to the where you have installed <strong>eTrust</strong> <strong>Directory</strong> (Hint: echo your<br />
DXHOME environment variable if you are unsure where this is). Then<br />
navigate to dxwebserver > samples > spml.<br />
2. If you are on a Windows machine run the 'setup.bat', if on a Solaris machine<br />
run the 'setup.sh'.<br />
This setup file performs the following steps:<br />
a. Stops Tomcat<br />
b. Copies the Tomcat server files and SAML files to<br />
"%DXHOME%\..\dxwebserver\webapps\spml-sample".<br />
c. Restarts Tomcat.<br />
The install should be complete in a few moments.<br />
Note: the above setup files perform the following steps:<br />
To Access The SPML Sample<br />
1. The file spml.properties points to Democorp on the current machine<br />
2. Connect using a SPML client to the web servers port.<br />
15–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Web Applications<br />
Sample Use of UDDI: uddiv3-demo<br />
This is a demonstration of a typical application of a UDDI server. It shows a web<br />
site that compares prices on airline flights by looking up the prices on different<br />
web servers, which are registered with a UDDI server.<br />
What the UDDI Demonstration Shows<br />
The UDDI demo web site that searches for the cheapest flights between<br />
destinations. The web site queries a UDDI registry for a list which web services it<br />
should connect to.<br />
Using the UDDI Demonstration<br />
The following instructions show how to use this demonstration web site to show<br />
how you can immediately remove information from a dynamic web site by<br />
removing the name of a web services from a UDDI server.<br />
1. Open your a web browser, and go to the following page:<br />
http://localhost:8080/uddiv3-demo<br />
2. Choose an origin and destination from the dropdown lists, and click Go.<br />
If this is first time you have used the site since the last reboot, there will be a<br />
pause while all the code is loaded into the servers .<br />
3. Click the Back button to reset the appearance of the demo before the demo<br />
starts.<br />
4. Open another copy of your web browser and go to the following page:<br />
http://localhost:8080/uddiv3-client<br />
5. Click on Connect, because the defaults are correct<br />
You should now have two browser windows: one page shows the flight price<br />
search demonstration site, and the other shows the UDDI Client.<br />
6. Click Login from the column of commands on the left. The Login page<br />
opens.<br />
7. Enter the name of the airline you want to delete. To delete the Dirt Cheap<br />
Airline:<br />
a. Log in using the following details:<br />
Login name: Dirt Cheap Discount Airlines<br />
Password: secret<br />
b. Leave the info selection alone.<br />
c. Click Login. This brings you to the Registered Information display for<br />
the chosen airline.<br />
Using the Sample DSAs, Applications, and Tools 15–11
Sample Web Applications<br />
8. Click the Delete button under Business in the column of commands on the<br />
left. The Delete Business page opens.<br />
9. Click the Add button to add the business to the Selected Business Keys.<br />
These are the business to be deleted.<br />
10. Click the Delete button to delete this business from the registry.<br />
11. Return to the Demo window, and press Go again. The panel refreshes, and<br />
the Dirt Cheap airline details no longer appear.<br />
To reset the demonstration:<br />
1. Click the Refresh Demo link at the bottom of the page.<br />
2. Click Open to run the reset program - it reloads the entire demo directory<br />
back to the original state.<br />
15–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Configuration Files<br />
Sample Configuration Files<br />
The sample DSAs use sample configuration files.<br />
You can use these configuration files as templates for your own files.<br />
For information about the sample configuration files, see the Readme files in<br />
each of the sample DSA directories.<br />
Sample Tools<br />
The sample tools are some extra tools for managing <strong>eTrust</strong> <strong>Directory</strong>.<br />
A number of sample configurations and utilities are provided for testing and<br />
demonstration purposes. These reside in the ../dxserver/samples subdirectories:<br />
The DXcmip Tool<br />
An executable to request CMIP counters from the directory.<br />
The dxcmip program is a management client which retrieves management<br />
information from an Computer Associates DXserver using the CMIP protocol.<br />
The management information retrieved is defined in ISO 9594-10 (Committee<br />
Draft April 1995).<br />
Usage<br />
The dxcmip tool has the following command line format:<br />
dxcmip [-r[n]] host[:port] [psel]<br />
where:<br />
■<br />
■<br />
-r[n] refresh every n seconds. Default: 5 seconds<br />
host the hostname or IP address to contact<br />
■ port the CMIP port. Default: 19389<br />
■<br />
psel the OSI P-SELECTOR. Default: CMIP<br />
Using the Sample DSAs, Applications, and Tools 15–13
Sample Tools<br />
The dua Tool<br />
Sample text-based <strong>Directory</strong> User Agent (DUA) that runs over DAP This<br />
directory contains the DAP directory client scripting DUA. This can be used to<br />
execute scripts to add, modify or remove entries from the directory. This can also<br />
be used to perform searches.<br />
Example test scripts reside in the samples/test directory. These can be executed<br />
either by running the setup script from that directory.<br />
See the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer <strong>Guide</strong> for more details.<br />
Usage<br />
The general syntax for the dua client is:<br />
dua <br />
The script 'init' is executed if a script name is not specified.<br />
The init script in this directory performs an anonymous bind.<br />
The DemoCorp DSA should be started for this to work.<br />
If an authenticated bind is required, then the username and password lines<br />
should be uncommented and a password set on the bind username in the<br />
directory as specified in the script.<br />
The DXtoolsgui Tool<br />
Java GUI interface to the DXtools—run dxtoolsgui.bat on Windows or<br />
dxtoolsgui.sh on UNIX.<br />
The dxtoolsgui tool requires Java Runtime Environment (JRE).<br />
15–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
The ldua Tool<br />
This directory contains the LDAP directory client scripting DUA. This can be<br />
used to execute scripts to add, modify or remove entries from the directory. This<br />
can also be used to perform searches. Example test scripts reside in the<br />
samples/test directory. These can be executed either by running the setup script<br />
from that directory.<br />
See the <strong>eTrust</strong> <strong>Directory</strong> SDK Developer <strong>Guide</strong> for more details.<br />
Usage<br />
The general syntax for the ldua client is:<br />
ldua <br />
The script 'init' is executed if a script name is not specified.<br />
The init script in this directory performs an anonymous bind.<br />
The DemoCorp DSA should be started for this to work.<br />
If an authenticated bind is required, then the username and password lines<br />
should be uncommented and a password set on the bind username in the<br />
directory as specified in the script.<br />
The schema Tool<br />
A Perl schema translation tool to update schema.txt for the DXtools<br />
This directory contains a perl script (transchema.pl) which translates a custom<br />
schema file (.dxc) producing updated versions of schema.txt for the DXtools.<br />
It also creates dxtype.txt and dxobject.txt for the DXplorer client that is no longer<br />
supported but may still be the preferred client for some customers.<br />
The script cannot handle schemas that contain attributes with varying OID<br />
prefixes. Currently such schema would need to be translated manually.<br />
Inputs<br />
<br />
schema.bck<br />
dxtype.bck<br />
dxobject.bck<br />
Using the Sample DSAs, Applications, and Tools 15–15
Sample Tools<br />
Outputs<br />
schema.txt in the current directory.<br />
dxtype.txt<br />
dxobject.txt<br />
Usage<br />
transchema.pl <br />
where:<br />
■<br />
■<br />
■<br />
schema-filename is the name of a custom schema file e.g. custom.dxc<br />
attr-prefix-name is the name of the attribute prefix used in the schema<br />
class-prefix-name is the name of the object class prefix used in schema<br />
Typically the custom schema file would contain the lines:<br />
schema set oid-prefix customAttributeType = (2.16.840.1.113730.3.1);<br />
schema set oid-prefix customObjectclass = (2.16.840.1.113730.3.2);<br />
For example:<br />
transchema.pl custom.dxc customAttributeType customObjectClass<br />
This script requires Perl to run.<br />
The input files need to be copied from their home directories.<br />
On UNIX<br />
On Windows<br />
On UNIX, use the following commands to copy the input files from their home<br />
directories:<br />
cp /opt/dxserver/bin/schema.txt .<br />
cp /opt/dxserver/for_dxplorer/DXtype.txt dxtype.txt<br />
cp /opt/dxserver/for_dxplorer/DXobject.txt dxobject.txt<br />
On Windows, use the following commands to copy the input files from their<br />
home directories:<br />
copy \opt\dxserver\bin\schema.txt .<br />
copy \opt\dxserver\for_dxplorer\DXtype.txt dxtype.txt<br />
copy \opt\dxserver\for_dxplorer\DXobject.txt dxobject.txt<br />
15–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
The snmp Tool<br />
An executable to request SNMP information from the directory.<br />
The dxsnmp program is a management client which retrieves management<br />
information from an Computer Associates DXserver using the SNMP protocol.<br />
The management information retrieved is defined in RFC 1567 <strong>Directory</strong><br />
Monitoring MIB. An <strong>eTrust</strong> <strong>Directory</strong> specific information is defined in<br />
dxmib.asn1. This can be found in the current directory and provides the<br />
following:<br />
■<br />
■<br />
Multiwrite queue monitoring<br />
DSA statistics monitoring<br />
Some statistic elements require stats logging/tracing to be enabled, as these<br />
items impact performance)<br />
■<br />
DXcache Monitoring<br />
Usage<br />
The dxsnmp tool has the following command-line format:<br />
Usage: dxsnmp -r[n] host[/port] [community]<br />
where:<br />
■<br />
■<br />
-r[n] refresh every n seconds. Default: 5 seconds<br />
host the hostname or IP address to contact<br />
■ port the SNMP port. Default: 19389<br />
■<br />
community the SNMP community of interest. Default: 'public'<br />
Using the Sample DSAs, Applications, and Tools 15–17
Sample Tools<br />
The soak Tool<br />
Soak is a testing tool used to run searches against an LDAP or DAP directory.<br />
The soak program can be used to run one search or even millions. Soak is<br />
designed to keep a directory busy with searches to give an accurate time in how<br />
long it takes to the directory to compete a search. Searches can range from<br />
complex to exact matches.<br />
Soak also has a queuing system where you can set a queue of searches. This to<br />
eliminate the overhead of soak setting up the search, because if you keep a<br />
number of searches in a queue then whenever the directory has finished a search<br />
there is another one waiting. It is for this reason the soak worked better running<br />
from another box or have it’s own processor. If you run soak from another<br />
computer, then it must be a fast network and the traffic must be minimal.<br />
This program uses either LDAP or DAP to measure throughput (as<br />
searches/sec).<br />
It attempts to keep the <strong>Directory</strong> Server saturated with search requests. This is<br />
done by using asynchronous search requests.<br />
Usage<br />
The soak tool has the following command-line format:<br />
soak [options] hostaddr:port namefile searches queuesize attributes<br />
Where the options are:<br />
■ -d use the X.500 DAP protocol. Defaults to LDAP.<br />
■ -m modify mode (generates random data)<br />
- interpret names as DNs<br />
- interpret attributes as: rndAttr len rndAttr len<br />
■ -M modify mode (LDIF modify records)<br />
■ -n do not ask for any attributes to be returned.<br />
■ -s step through searches sequentially (default is rnd).<br />
■ -F interpret names as filters.<br />
■ -A retrieve attribute names only (no values)<br />
■ -r count make the first count chars of rnd value the same<br />
■<br />
■<br />
■<br />
-D base_dn bind dn<br />
-w bind_password bind password (for simple authentication)<br />
-b base_dn search base<br />
15–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
■ -S msecs sleep in milli-secs before each search (default=0)<br />
■<br />
-Z schema file containing schema definitions (DAP only)<br />
And where the variables are:<br />
■ hostaddr:port Address and port of LDAP/DAP <strong>Directory</strong> Server.<br />
■ namefile File containing names to be searched.<br />
■ searches The number of searches to perform.<br />
■ queuesize The number of outstanding searches to maintain.<br />
And where the attributes are a whitespace-separated list of attributes to retrieve<br />
(if no attribute list is given, all are retrieved)<br />
Example<br />
For example, here is a typical soak command for exact match searches used with<br />
the DemoCorp data:<br />
soak 155.35.131.155:5544 /local/travis/Performance/names/tenk.name 50000 3<br />
where<br />
■<br />
■<br />
■<br />
■<br />
■<br />
155.35.131.155 is the port number of the machine that the directory is<br />
installed on.<br />
5544 is the port number the directory is listening on.<br />
Note: The port number and IP-ADDRESS are separated with a ‘:’<br />
/local/travis/Performance/names/tenk.name is the name file the soak will<br />
use to search the directory.<br />
5000 is the number of searches to run<br />
3 is the queue size to use for the searches.<br />
The DemoCorp data has three different name file to used for each database for<br />
exact matches.<br />
■<br />
■<br />
■<br />
tenk.name<br />
onehundredk.name<br />
onemillion.name<br />
Example:<br />
soak myhost:1001 names.dat 100 5<br />
read 5 names<br />
Connecting to myhost:1001 ...<br />
1000: (cn=ann bradley)<br />
999: (cn=ann bradley)<br />
998: (cn=adrian gardner)<br />
997: (cn=adrian gardner)<br />
Using the Sample DSAs, Applications, and Tools 15–19
Sample Tools<br />
996: (cn=adrian gardner)<br />
995: (cn=ann bradley)<br />
994: (cn=adam fischer)<br />
993: (cn=adam fischer)<br />
992: (cn=adrian gardner)<br />
991: (cn=adam fischer)<br />
...<br />
7: (cn=adrian gardner)<br />
6: (cn=craig link)<br />
5: (cn=adrian gardner)<br />
4: (cn=ann bradley)<br />
3: (cn=adam fischer)<br />
2: (cn=craig link)<br />
1: (cn=craig link)<br />
Searches: 800<br />
Start time: 978082934.854<br />
Stop time: 978082940.194<br />
Elapsed time: 5.339<br />
Searches/Sec: 149.83<br />
Content of names.dat (taken from democorp example)<br />
craig link<br />
adam fischer<br />
adrian gardner<br />
ann bradley<br />
joh martinez<br />
15–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
The ssl Tool<br />
The samples/ssl directory contains tests using the DAP and LDAP script DUA.<br />
This sample includes examples of using DUA-DSA and DSA-DSA SSL<br />
authentication and encryption, using SSL encryption and SSL authentication<br />
between client and DXserver<br />
The DAP and LDAP script DUAs connect to the DemoCorp DXserver using SSL<br />
encryption or SSL authentication.<br />
This directory contains the following files:<br />
test1.dxs<br />
This script demonstrates a client-server connection using an SSL-encrypted<br />
link between the DUA and DemoCorp directory.<br />
test2.dxs<br />
This script demonstrates a mutually authenticated client–server SSL<br />
connection between the DUA and DemoCorp directory.<br />
test3.dxs<br />
This script demonstrates a mutually authenticated client–server SSL<br />
connection to the DemoCorp directory but searching the UNSPSC directory<br />
using chaining.<br />
test4.dxs<br />
This script demonstrates distributed authentication. This time the DUA<br />
connect to the UNSPSC DSA but is authenticated by the DemoCorp DSA and<br />
searches the DemoCorp directory.<br />
In tests 2-4 the DUA (via SSLD) requires use of client certificates stored in the<br />
samples/ssl/certs directory. They require the certificate of a user that exists in<br />
the DemoCorp directory, Marco Drew, in the file marco_drew.pem.<br />
These scripts can be configured and run using the setup script.<br />
Note: The DemoCorp and UNSPSC DSAs are assumed to be running. These can<br />
be configured using their sample setup scripts.<br />
The SSL Setup Script<br />
To set up the ssl tool, run the setup script. This is setup.sh on UNIX, and<br />
setup.bat on Windows NT.<br />
The script performs the following steps:<br />
1. Starts the SSLD for <strong>Directory</strong> Server requests.<br />
2. Starts the SSLD for <strong>Directory</strong> Client requests.<br />
Using the Sample DSAs, Applications, and Tools 15–21
Sample Tools<br />
3. Starts the DemoCorp DSA.<br />
4. Starts the UNSPSC DSA.<br />
5. Runs the DUA SSL encryption test (test1.dxs).<br />
6. Runs the DUA SSL authentication test (test2.dxs).<br />
7. Runs the DUA SSL authentication test (test3.dxs).<br />
8. Runs the DUA SSL distributed authentication test (test4.dxs).<br />
9. Runs the LDUA SSL encryption test (test1.dxs).<br />
10. Runs the LDUA SSL authentication test (test2.dxs).<br />
11. Runs the LDUA SSL authentication test (test3.dxs).<br />
12. Runs the LDUA SSL distributed authentication test (test4.dxs).<br />
The -q switch can be used to suppress user prompting.<br />
About the Testing DUA and SSLD<br />
The DAP and LDAP script DUAs makes use of a Client SSLD process to handle<br />
the SSL encryption and authentication.<br />
This should be started using the command:<br />
ssld start client -certfiles samples/ssl/certs -ca config/ssld/trusted.pem -port<br />
1113<br />
The command ssld stop client can be used to stop the server SSLD.<br />
This is in addition to the SSLD process used by the DSAs, this process listens for<br />
SSL requests on port 1112 and is started by the command:<br />
ssld start server -certfiles config/ssld/personalities -ca<br />
config/ssld/trusted.pem<br />
The command ssld stop server can be used to stop the server SSLD.<br />
SSL encryption is enabled in the DUA by adding 'ssl-encryption' to the bind<br />
request. The scripts explicitly use port 1113. When using SSL encryption, the<br />
DSA will use normal access controls.<br />
To enable SSL authentication as well as encryption, add 'ssl-auth' to the DUA<br />
bind request. The DSA will check its list of trusted <strong>CA</strong>s to confirm that the<br />
client's certificate is valid, then by default, the DSA will check for an entry in the<br />
directory matching the subject name of the certificate. This check can be disabled<br />
by setting 'ssl-auth-bypass-entry-check = true' in the DSA settings.<br />
When binding with ssl-auth, note that the DUA bind syntax does not allow the<br />
'user' and 'password' fields that are normally present.<br />
15–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
The test Tool<br />
A selection of <strong>Directory</strong> scripts to modify the directory using the supplied DUA<br />
or LDUA clients. Run the setup script to automatically configure the Test DSA<br />
and execute the DUA and LDUA client scripts.<br />
This directory contains sample directory client scripts. These can be executed by<br />
running the LDAP DUA (LDUA) and DAP DUA. These reside in the directories<br />
samples/ldua and samples/dua.<br />
The setup script creates a DXserver called 'test' using the Ingres database 'test'.<br />
The test DSA is loaded by the test scripts using the master script basic.tests in<br />
this directory. These scripts are executed using first the DAP DUA and then the<br />
LDAP DUA directory client.<br />
Usage<br />
setup.sh (Solaris)<br />
setup.bat (Windows NT)<br />
The -q switch can be used to suppress user prompting.<br />
The script performs the following steps:<br />
1. Create the Test Ingres database 'test'.<br />
2. Configure the Test initialization file: config/servers/test.dxi.<br />
3. Configure the Test database file: config/database/test.dxc.<br />
4. Configure the Test knowledge file: config/knowledge/test.dxc.<br />
5. Start the Test DXserver DSA. This DSA contains a null prefix.<br />
6. Execute the basic directory tests using the DAP DUA Client.<br />
7. Execute the basic directory tests using the LDAP DUA Client.<br />
The test scripts include tests of all X.500 services. The tests are performed on a<br />
single DSA with an existing database with no context prefix. The test scripts<br />
return the database to its original condition when they run successfully.<br />
All tests add a small subtree, conduct tests on this subtree and then remove the<br />
subtree.<br />
If the script executes successfully then the database will be returned to its<br />
original state.<br />
Using the Sample DSAs, Applications, and Tools 15–23
Sample Tools<br />
The response to each request is checked using the "if-reply" line, so the number<br />
of entries or attributes returned, or the returned error code can be checked. A test<br />
will fail if the wrong response is returned, such as and add-entry-refuse when an<br />
add-entry-confirm was expected, or if the wrong number of entries was returned<br />
on a list or read result.<br />
If a test fails the script will display an error message and exit. This may leave<br />
entries in the database.<br />
The scripts do not test authentication or security, so the user can bind to the DSA<br />
as an anonymous user.<br />
Test 1<br />
This script tests all the basic services apart from search.<br />
Test 2<br />
This script tests the search service.<br />
Test 3<br />
This script tests various errors.<br />
Test 4<br />
This script tests schema (MUST and MAY contains and distinguished<br />
values).<br />
Test 5<br />
This script tests the handling of large attribute values and attributes<br />
containing large numbers of values.<br />
Test 6<br />
This script tests the operation of aliases.<br />
15–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sample Tools<br />
The DXtrap Tool<br />
Information and an example program that can receive triggers from the<br />
directory.<br />
The dxtrap program is a management application which receives SNMP Traps<br />
from a Computer Associates DXserver.<br />
Four trap types may be sent by DXserver. To enable the sending of traps in<br />
DXserver, the following command should appear in the settings:<br />
set snmp-log = udp port <br />
where : is the trap address of the management application.<br />
The traps are:<br />
generic=6, specific=0<br />
These are DXserver alarms. The trap contains three variables: sysName,<br />
sysDescr and sysLocation. sysName contains the name of the DXserver and<br />
sysLocation contains the actual alarm text.<br />
DXserver always sends this trap when an alarm condition is detected if the<br />
snmp-log has been configured.<br />
generic=6, specific=1<br />
This trap is sent, depending on configuration, when the DXserver has<br />
performed an update operation. The trap contains three variables: sysName,<br />
sysDescr and sysLocation. sysName contains the name of the DXserver<br />
sending the trap plus some addressing information. sysLocation contains<br />
information relating to the actual update operation.<br />
DXserver sends this trap if the snmp-log has been configured and the<br />
following command has been executed:<br />
set trap-on-update = true;<br />
generic=6, specific=2<br />
This trap is sent, depending on configuration, when the DXserver detects an<br />
authentication failure (invalid Bind credentials). The trap contains three<br />
variables: sysName, sysDescr and sysLocation. sysName contains the name<br />
of the DXserver and sysLocation contains the reason text.<br />
DXserver sends this trap if the snmp-log has been configured and the<br />
following command has been executed:<br />
set auth-trap = true;<br />
generic=6, specific=3<br />
This trap is sent, depending on configuration, when the DXserver refuses to<br />
perform an operation. The trap contains three variables: sysName, sysDescr<br />
and sysLocation. sysName contains the name of the DXserver and<br />
sysLocation contains the reason text.<br />
DXserver sends this trap if the snmp-log has been configured and the<br />
following command has been executed:<br />
set op-error-trap = true;<br />
Using the Sample DSAs, Applications, and Tools 15–25
Sample Tools<br />
Usage<br />
The dxtrap tool has the following command line-format:<br />
dxtrap [ port ]<br />
where port is the SNMP trap port (default: 162).<br />
15–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Chapter<br />
16<br />
Deploying a <strong>Directory</strong><br />
This chapter provides some general guidelines regarding the deployment of a<br />
directory. It is broken into three major sections:<br />
■<br />
■<br />
■<br />
<strong>Directory</strong> Design<br />
Operations and Practices<br />
Troubleshooting<br />
This chapter is only intended to be an introduction to good directory design,<br />
planning, and maintenance. Good directory design and proper attention to<br />
operational details is critical to a successful directory service.<br />
Many of the areas listed are common sense but they are included so that you can<br />
use this chapter as a general checklist of items to consider when deploying a<br />
directory system.<br />
For companies with large-scale systems, or a critical need to provide continuous<br />
service, many more factors need to be considered. When you are designing a<br />
large-scale system, we recommend that you contact Computer Associates<br />
Services at http://ca.com/ for assistance.<br />
Deploying a <strong>Directory</strong> 16–1
<strong>Directory</strong> Design<br />
<strong>Directory</strong> Design<br />
Good directory design starts with understanding the information that the<br />
directory contains and the way it is used.<br />
Requirements Analysis<br />
Generally, a requirements study will determine most of the important aspects of<br />
the directory system such as:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Characteristics of the data, its size, initial load, and expected growth rate<br />
The different directory applications and types of queries they use<br />
The performance targets such as average response times and peak loads<br />
The dimensioning of the hardware, network, and other supporting IT<br />
infrastructure<br />
How the directory is integrated with other services<br />
Service Definition<br />
A separate detailed service study should establish a service profile for each<br />
directory application. This would include:<br />
■<br />
■<br />
■<br />
Type, frequency, and expected performance of searches and updates<br />
(including adds, modifies, renames, and deletes)<br />
Type of attributes specified in the search filter or returned from a search<br />
Any unusual, but potentially computationally expensive, operations such as<br />
substring and complex searches<br />
Schema Design<br />
After the sources and consumers of information are identified, you can<br />
determine the set of all possible attributes. Generally, the schema designer<br />
should try to use existing standard schema attributes where possible. Where no<br />
standard schema exists, you should create a custom attribute.<br />
You need to collect attributes into object classes. Generally, you combine related<br />
attributes to form object classes. Objects should have real world meanings (such<br />
as person, device, product), and be sensible units for directory-enabled<br />
applications to use. See the chapter “Schema Definition” for more information.<br />
16–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>Directory</strong> Design<br />
<strong>Directory</strong> Enabled Applications<br />
The schema design should take into account the way that the information will be<br />
used by directory applications. Some applications require read-only access, while<br />
others require both read and update. Some applications have very high demand<br />
for particular attributes, while other attributes are rarely used. Some attributes<br />
are shared by many applications, while other attributes are particular to only one<br />
application.<br />
It is essential to organize information so that the directory can cope with the<br />
maximum loading. You can group frequently used attributes together. It can also<br />
result in a design where objects are deliberately split or combined because some<br />
higher-level operation (for example, setting up a role) requires updates to many<br />
attributes across many objects.<br />
Namespace Design<br />
A well-designed <strong>Directory</strong> Information Tree (DIT) is a key to scalability and<br />
manageability. The namespace design needs to consider:<br />
■<br />
■<br />
■<br />
Geographic partitioning—when the directory is distributed in regions<br />
Security and management policies—when parts of the directory are<br />
accessed or managed in subtrees<br />
Common objects—to avoid duplicating information required by different<br />
DIT branches<br />
It is important that the naming structure is stable. This means choosing naming<br />
attributes that do not change often and a DIT structure that is as fixed as<br />
possible.<br />
Security<br />
Security policies must cover all aspects of security. This includes:<br />
■<br />
■<br />
■<br />
■<br />
Physical security—who has access to a site, a machine, or the directory<br />
software itself<br />
Authentication—who is permitted to access and manage information in the<br />
directory<br />
Access controls—which information is protected from unauthorized changes<br />
Sensitivity—some information may be confidential or have business value<br />
to third parties<br />
Deploying a <strong>Directory</strong> 16–3
<strong>Directory</strong> Design<br />
Dimensioning<br />
A system can run many databases and many directory servers across multiple<br />
sites. It is important that machines have enough disk memory and processors,<br />
and that the configuration of DSAs makes best use of this hardware. Even<br />
though the cost of hardware can be significant, an appropriate investment here<br />
can offset large operational costs.<br />
Performance<br />
Performance relies upon the power of the hardware and network in use and the<br />
configuration and tuning of the directory and database software. Often<br />
additional indexes or additional servers can make a big difference to<br />
performance. Items to consider include:<br />
■<br />
■<br />
■<br />
■<br />
Security—affects performance if the access control scheme is too complex or<br />
if every link employs SSL authentication. See the chapter “Security” for more<br />
information about SSL authentication.<br />
Logging—degrades performance if too much logging is enabled, particularly<br />
diagnostic logging. See the chapter “General Administration” for more<br />
information about logging.<br />
Query streaming—reserves particular DSAs for high-speed lookups and<br />
diverts known slower queries, for example substring searches to other<br />
dedicated DSAs. It can also divert slower updates to dedicated DSAs. See the<br />
chapter “Distribution and DSP” for more information about query<br />
streaming.<br />
Load sharing—lets servers share load across CPUs or across machines. See<br />
the chapter “Distribution and DSP” for more information about load sharing.<br />
Availability<br />
Availability can be improved by providing a number of strategies. This may<br />
include:<br />
■<br />
■<br />
■<br />
■<br />
Hardware—backup power supplies, RAID disks, or backup machines<br />
Network—providing multiple network interfaces and links between<br />
machines<br />
<strong>Directory</strong> servers—configuring alternative DSAs<br />
Databases—using replication to provide alternative data stores<br />
16–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
<strong>Directory</strong> Design<br />
Synchronization<br />
Often, you must synchronize data with external systems. It is important therefore<br />
to establish a list of sources and targets, and the timing and types of data that<br />
must be exchanged. Often, you must perform normalization to filter out<br />
duplicate entries, rude words, or map fields from one form to another. Planning<br />
the timing of the synchronization is important because synchronization is<br />
usually performed using a batch mode process.<br />
Scalability and Distribution<br />
Many DSAs can run on one machine for the purpose of:<br />
■<br />
■<br />
■<br />
Coping with large number of users<br />
Splitting a large DIT into smaller, more manageable pieces<br />
Achieving load balancing or query streaming<br />
In addition, directory servers can run at multiple sites over regions, countries or<br />
across the world. In this case, it is important that the separation of DSAs take<br />
advantage of geography so that servers are concentrated in areas of highest<br />
demand.<br />
Complexity<br />
Keep it simple. <strong>eTrust</strong> <strong>Directory</strong> is very flexible in terms of its features. However,<br />
complex designs can be hard to understand and maintain. Always justify why a<br />
configuration needs to be more complex.<br />
Deploying a <strong>Directory</strong> 16–5
Operations and Practices<br />
Operations and Practices<br />
Directories provide a service. Often, service level agreements gives contractual<br />
commitments on outage, response times, and escalation plans. It is critical to<br />
define and adhere to formal practices and procedures.<br />
Management<br />
All aspects of the system including personnel, applications, services,<br />
infrastructure, and day-to-day operations must be managed. There are many<br />
factors often not considered early in a directory project lifecycle including:<br />
■<br />
■<br />
■<br />
Training—especially for operations staff<br />
Support—such as hardware and software contracts<br />
Upgrades—how systems will transition with minimum down time<br />
Monitoring<br />
Monitoring determines the health of a system. Generally, it will cover the<br />
following areas:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Polling—using a protocol such as SNMP<br />
Probing—involving periodical queries to test performance<br />
Alarms—relying on systems to generate alerts when unexpected situations<br />
arise<br />
Log file analysis—scanning errors and linking into other alarm software<br />
Indirect—inferring that something is wrong because other applications are<br />
not functioning properly<br />
Capacity Planning<br />
Over time it is necessary to monitor existing platforms to show trends in growth.<br />
When additional hardware, network capacity, or licenses are required, the<br />
upgrades need to occur in a planned, orderly manner.<br />
16–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Operations and Practices<br />
Backup and Restore<br />
This is probably the most important procedure in the system. It is very important<br />
that you accurately document the backup procedure and ensure that it takes<br />
place at specified times. Backups should occur daily.<br />
You can perform database backups using the utility dxbackupdb. The<br />
dxbackupdb utility can perform on-line backups of the database even when there<br />
are DSAs updating the database.<br />
Following standard industry practices, you should regularly test your backup<br />
procedures by attempting to restore your backups onto a test system. You should<br />
also perform a restore before any system configuration changes or tuning. The<br />
restore time needs to be calculated, as it is crucial in meeting outage service level<br />
agreements.<br />
You can perform database restores using the Dxrestoredb tool.<br />
See the chapter Using JXplorer for more information about backup and restore<br />
tools.<br />
Journaling<br />
In addition to database backups, known as checkpoints, Advantage Ingres can<br />
maintain a journal of all committed transactions since the last checkpoint. To<br />
enable journaling, use the command:<br />
dxbackupdb +journal dbname<br />
Journaling should be enabled in operational environments. If journaling is<br />
enabled, backups (dxbackupdb) should be run more frequently, preferably every<br />
night. This prevents the journal logs from becoming too large and reduces<br />
recovery time if you have to roll forward the changes (dxrestoredb).<br />
Note: If dxindexdb is used, the journals must be re-enabled to let the journals<br />
track the new indexes. Perform the following sequence of commands:<br />
dxbackupdb dbname<br />
dxindexdb dbname –reverse attrName<br />
dxbackupdb +journal dbname<br />
See DB Tools in the chapter “Using DXtools” for more information.<br />
Deploying a <strong>Directory</strong> 16–7
Operations and Practices<br />
Database Tuning<br />
You should tune the directory database periodically to maintain optimum<br />
performance.<br />
You can use the dxtunedb utility in simple or full mode. In simple mode the<br />
dxtunedb utility can be run while the DSA is online as it just builds table<br />
statistics. This improves performance of the Advantage Ingres Query Optimizer.<br />
To tune while the DSA is online, use the following command:<br />
dxtunedb demo<br />
In full mode the dxtunedb utility rebalances tables to optimize storage layouts,<br />
rebuilds indexes to remove overflow pages, builds table statistics to help the<br />
query optimizer, and tunes the system tables. We recommend that you execute<br />
this utility after bulk loading or other large-scale modifications, and after a<br />
period of gradual modification.<br />
The dxtunedb utility requires at least 25 percent free disk space (for temporary<br />
tables) and takes approximately one minute per 1,000 entries to complete a full<br />
tune.<br />
To perform a full tune, shut down any DSAs connected to the database and use<br />
the following commands:<br />
dxbackupdb demo<br />
dxtunedb –full demo<br />
dxbackupdb demo<br />
Change Control<br />
There are some basic principles of change management required to ensure the<br />
ongoing consistency of the directory:<br />
■<br />
■<br />
■<br />
■<br />
Subdirectories of the config directory contain the directory configuration<br />
files. The configuration files contain the operational controls and schema<br />
definitions for one or more DSAs. You should back up this config directory<br />
in synchronization with copies of the matching Advantage Ingres database<br />
set.<br />
You should manually track modifications to the configuration files while<br />
maintaining appropriate backup copies. You may want to consider a source<br />
control system.<br />
You should test configuration changes against test and development copies<br />
of the directory database rather than the live database.<br />
You can switch test databases into production, in a live environment, using<br />
the hot swap facility.<br />
16–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Operations and Practices<br />
Upgrades<br />
Over time, you need to install new versions of software for the directory,<br />
database, or operating system to fix problems, add new functionality, or provide<br />
performance features. You should build prototype systems first on separate<br />
machines to validate the new system before going live.<br />
Important! Always check the latest release notes for details of software changes,<br />
particularly in the area of schema. The product schema files can evolve to follow changing<br />
standards. Using these latest standards can break existing applications when they have<br />
not been modified to keep pace with these changes. When it is not desirable or practical to<br />
change existing applications, then these should use the existing schema on the upgraded<br />
software.<br />
Maintenance<br />
Periodically, systems should be scheduled for maintenance to perform various<br />
housekeeping tasks, such as disk defragmentation, hardware upgrades, or<br />
software patches. The first maintenance step should be a backup sequence as<br />
follows:<br />
dxbackupdb demo<br />
dxtunedb –full demo<br />
dxbackupdb demo<br />
This ensures that the database tables and indexes are optimally laid out.<br />
Deploying a <strong>Directory</strong> 16–9
Troubleshooting<br />
Troubleshooting<br />
This section covers various areas that may cause problems in operational<br />
systems. See DB Tools in the chapter “Using DXtools” for more information<br />
about alarms, warnings, and logs.<br />
Optimizing Performance<br />
Performance problems generally arise because of unexpected demands on the<br />
system. The following is a list of possible areas to investigate:<br />
■<br />
■<br />
■<br />
■<br />
■<br />
■<br />
Resources—When a system is under peak loads, there may not be enough<br />
CPU or disk to process all the required requests. Ensure that you have done<br />
sufficient capacity planning and traffic analysis to determine the amount of<br />
hardware required to achieve the given service levels.<br />
Load-sharing DSAs—On a multi-CPU box it may be necessary to run a<br />
router DSA and multiple load-sharing DSAs to make use of all the CPUs on a<br />
given machine.<br />
Query-streaming DSAs—When there is a large variation in the types of<br />
queries, then different DSAs can be dedicated for different tasks, for<br />
example, lookup queries, updates, and complex queries. If the lookup<br />
queries are additionally handled by a load-sharing group of DSAs then the<br />
system effectively can reserve DSAs to handle small, fast lookup queries<br />
regardless of what else is going on in the system.<br />
Database tuning—This optimizes the data layout in the database tables. You<br />
should tune the database after large-scale modifications. The dxtunedb<br />
utility can perform an on-line tune or full tune (“-full”) if all the DSAs are<br />
taken off-line.<br />
Advantage Ingres tuning—You can tune the cache and a number of other<br />
Advantage Ingres parameters in mission-critical sites. Contact Computer<br />
Associates at http://supportconnect.ca.com for advice.<br />
File system tuning—On UNIX, the tunefs utility can optimize disk partitions<br />
to minimize access times. We recommend that you run tunefs when you add<br />
new hard drives, before you add data to the new device.<br />
Managing Large Numbers of Users<br />
The UNIX operating system limits the number of file descriptors per process (for<br />
example, 1024). This limits the number of users who can bind to a DSA at any<br />
one time. When the number of users is large, you can run multiple DSAs, all<br />
connecting to the same database (DIB).<br />
16–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Troubleshooting<br />
Managing Large Numbers of Entries<br />
When the DIT contains very large numbers of entries, you can split it into a<br />
number of subtrees (each having, for example, 100,000 entries). You can run a<br />
DSA for each subtree with a master top-level DSA. You can then link the DSAs<br />
with local DSP configurations.<br />
When a database needs to have a large number of entries, then the database can<br />
be split over multiple locations. Use the dxextenddb utility to create such<br />
locations. (See DB Tools in the chapter “Using DXtools” for more information.)<br />
All database tools make use of multiple locations and can handle large (> 2 GB)<br />
files.<br />
When you need to load a large number of entries initially, use the bulk load tool<br />
DXloaddb. When there are a large number of changes to be made, or a large<br />
number of entries added to an existing database, consider extracting the existing<br />
data into an LDIF file using the DXdumpdb tool. Manipulate the LDIF file<br />
(merge it with new data), and reload the data using the bulk load tool DXloaddb.<br />
Limiting Users<br />
There are many ways to control users, including the following:<br />
■<br />
■<br />
■<br />
Security—Limit access to a directory through authentication and access to<br />
particular data through access controls.<br />
Service controls—Set service controls such as time limits and size limits on<br />
operations.<br />
Flow control—Use DXserver’s “credit” facility to prevent a client flooding a<br />
DSA with requests. This works by simply not reading bytes on that client’s<br />
socket so that TCP/IP back pressures then restricts that client’s ability to<br />
send data on that connection.<br />
Deploying a <strong>Directory</strong> 16–11
Appendix<br />
A<br />
Tailoring the RDBMS<br />
This appendix describes how to change some Advantage Ingres database<br />
parameters. This is usually not necessary but is desirable in certain cases as<br />
recommended by Computer Associates Technical Support.<br />
The customizations covered in this appendix are:<br />
■<br />
■<br />
The default page size<br />
The number of cache pages<br />
You can configure each of these using the Advantage Ingres utility cbf<br />
(configuration by forms). You can run cbf in an OpenWindows or CDE<br />
(Common Desktop Environment) shell window.<br />
Keep the following navigational tips in mind:<br />
■ When using OpenWindows, you can move the cursor up or down using ↵,<br />
Ctrl+J, or Ctrl+K.<br />
■<br />
■<br />
When using CDE you can move the cursor up or down using ↵, ↑ (up<br />
arrow), or ↓ (down arrow).<br />
You can advance between fields using the Tab key.<br />
On Windows, you can configure these using cbf from the command prompt.<br />
Navigation instructions for cbf appear on the window.<br />
Note: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
Tailoring the RDBMS A–1
Changing the Default Page Size<br />
Changing the Default Page Size<br />
Under most circumstances, the best performance is obtained with a database<br />
page size of 2 KB. However, there may be circumstances in which you want to<br />
change this.<br />
To change the default page size, run cbf (configuration by forms) and enter the<br />
following:<br />
OpenWindow<br />
Keystrokes<br />
CDE Keystrokes Purpose<br />
↵ ↵ Moves to DBMS server line.<br />
ESC+conf ↵ F10 Displays the DBMS Server Parameters<br />
window.<br />
dd dd Moves to default-page-size.<br />
ESC+edit ↵ F10 Displays popup for new value.<br />
8192 ↵ 8192 ↵ Enters new value.<br />
ESC+cache ↵ Insert Displays the DBMS Caches window.<br />
↵ ↵ ↵ ↵ Moves to DMF cache 8K.<br />
ESC+edit ↵ F11 Sets cache status to ON.<br />
ESC+end ↵ F3 Exits DBMS Caches window.<br />
ESC+end ↵ F3 Exits DBMS Server Parameters window.<br />
↵ ↵ Yes, saves changes and end.<br />
ESC+quit F4 Exits cbf.<br />
A–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Increasing the Number of Cache Pages<br />
Increasing the Number of Cache Pages<br />
For systems that have a large amount of RAM, it can help to increase the number<br />
of cache pages used. On a large production database, optimum performance is<br />
obtained with a cache size of 60,000 pages of 2 KB per page, requiring 128 MB of<br />
memory for the cache.<br />
To increase the number of cache pages, run cbf , and enter the following:<br />
OpenWindow<br />
Keystrokes<br />
CDE Keystrokes Purpose<br />
↵ ↵ Moves to DBMS server line.<br />
ESC+conf ↵ F10 Displays the DBMS Server Parameters<br />
window.<br />
ESC+cache ↵ Insert Displays the DBMS Caches window.<br />
↵ ↵ Moves to the largest activated cache line.<br />
ESC+conf ↵ F10 Displays the DBMS Cache Parameters<br />
window.<br />
ESC+derived ↵ F11 Displays the Derived DBMS Cache<br />
Parameters window.<br />
ESC+edit ↵ F10 Displays popup requesting new value.<br />
60000 ↵ 60000 ↵ Enters new value.<br />
ESC+end ↵ F3 Exits Derived DBMS Cache Parameters<br />
for xk window.<br />
ESC+end ↵ F3 Exits DBMS Cache Parameters for xk<br />
Buffers window.<br />
ESC+end ↵ F3 Exits DBMS Caches window.<br />
ESC+end ↵ F3 Exits DBMS Server Parameters window.<br />
↵ ↵ Yes, saves changes and end.<br />
ESC+quit F4 Exits cbf.<br />
Tailoring the RDBMS A–3
Increasing the Number of Database Connections<br />
Increasing the Number of Database Connections<br />
<strong>eTrust</strong> <strong>Directory</strong> ships with a default configuration of 64 database connections.<br />
However, if you are upgrading from a previous version of <strong>eTrust</strong> <strong>Directory</strong>, the<br />
previous limit of 32 connections applies.<br />
If you have many data DSAs running on the same machine and you then run the<br />
DXloaddb tool, which uses many Ingres connections, you may get the following<br />
error in II_SYSTEM/ingres/files/errlog.log:<br />
E_US0001 Number of users has exceeded limit.<br />
If you see this error, then the Ingres connection limit needs to be increased.<br />
Step 1. Increase the Shared Memory Maximum (Optional)<br />
To successfully increase the Ingres connection limit, you may need to increase<br />
the shared memory maximum.<br />
You can skip this step if the shared memory maximum is already higher than the<br />
following list:<br />
Number of Database<br />
Connections<br />
RAM required<br />
32 16 MB<br />
64 100 MB<br />
128 200 MB<br />
If you need to do this step, use the following table:<br />
Platform<br />
Solaris<br />
Action<br />
Edit the value of "set shmsys:shminfo_shmmax" to the<br />
new value in /etc/system, then restart the machine.<br />
Linux Run sysctl -w kernel.shmmax="new value" and sysctl -<br />
w kernel.shmall="new value", then restart the machine.<br />
HP-UX<br />
AIX<br />
Windows<br />
Use the sam command to update the shmmax kernel<br />
parameter to the new value, rebuild the kernel, then<br />
restart the machine.<br />
No change is required because kernel parameters are<br />
dynamic.<br />
No change is required.<br />
A–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Other Customizations<br />
Step 2. Increase the Database Connection Limit<br />
If enough shared memory has been allocated, then you can increase the<br />
connection limit.<br />
1. As the ingres user, run Configuration-By-Forms (CBF):<br />
% su - ingres<br />
% setenv TERM_INGRES wxterm (csh assumed)<br />
% cbf<br />
2. In CBF:<br />
a. Press D to highlight the DBMS Server row .<br />
b. Press Esc and type Configure.<br />
c. Press c until the row connect_limit is highlighted.<br />
d. Press Esc and type Edit.<br />
e. Enter the new maximum value.<br />
f. Press Esc and type End.<br />
g. Press Enter to save the value.<br />
h. Press Esc and type Quit to end CBF.<br />
3. Restart Ingres:<br />
% ingstop; ingstart<br />
Other Customizations<br />
Several other customizations are possible, and Computer Associates Technical<br />
Support may recommend them depending on the particular site and hardware in<br />
use. These include:<br />
■<br />
■<br />
■<br />
Enabling the backup transaction log file<br />
Configuring a separate disk area for backups<br />
Configuring a separate disk area for tuning<br />
You may want to set the Advantage Ingres log folder to a different disk drive for<br />
improved performance.<br />
For more information, contact Computer Associates Technical Support at<br />
http://supportconnect.ca.com.<br />
Tailoring the RDBMS A–5
Appendix<br />
B<br />
DXserver Command Language<br />
This appendix lists the configuration commands used by DXserver.<br />
There are six command categories. Each command category includes a number<br />
of valid commands.<br />
Some commands also have additional parameters. For example, the following<br />
command is made up of the set category, the admin-user command, and the ownentry<br />
parameter:<br />
set admin-user = own-entry<br />
Command Categories<br />
Command<br />
add<br />
clear<br />
close<br />
set<br />
source<br />
trace<br />
Description<br />
Creates an additional wide index.<br />
Clears a portion of the configuration information. This command is commonly<br />
used to ensure that you load configuration details into a clear setup, rather than<br />
laying them on top of an (possibly contradictory) existing configuration.<br />
Closes a log.<br />
Defines an aspect of. There are over ninety set commands.<br />
Specifies a file to be loaded. This is used to make configurations using multiple<br />
files.<br />
Enables tracing, and defines what type of tracing is enabled.<br />
DXserver Command Language B–1
Add Command<br />
Add Command<br />
Command<br />
add index-wide<br />
Description<br />
Create additional wide indexes for some attributes without changing any wide<br />
indexes that have already been set up. For more information, see the section<br />
Creating Additional Wide Indexes in the chapter “General Administration.”<br />
Clear Commands<br />
Command<br />
clear access<br />
clear dsas<br />
clear indexes<br />
clear schema<br />
Description<br />
Clears all of the static access controls. Typically, this is done before loading access<br />
controls to ensure that conflicting controls are not loaded.<br />
Clears the knowledge of all DSAs. This may be done immediately before loading<br />
knowledge.<br />
Clears all indexing options on attributes.<br />
Clears all of the schema information. This is done before re-loading the schema,<br />
to ensure there are no conflicting definitions for attributes or object classes.<br />
Close Commands<br />
Command<br />
close summary-log<br />
close stats-log<br />
close trace-log<br />
close query-log<br />
close update-log<br />
close alert-log<br />
close cert-log<br />
close connect-log<br />
Description<br />
Closes the summary log.<br />
Closes the statistics log.<br />
Closes the trace log.<br />
Closes the query log.<br />
Closes the update log.<br />
Closes the alert log.<br />
Closes the certificate log.<br />
Closes the connection log.<br />
Note: The alarm log cannot be closed.<br />
B–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
Set Commands<br />
Command<br />
set access-controls<br />
set add-oc-parents<br />
set admin-user<br />
set agreement<br />
set alarm-log<br />
set alert-log<br />
set alias-integrity<br />
set allow-binds<br />
Description<br />
Specifies whether access controls are enabled or not<br />
Adds superior object classes even if the client did not specify these<br />
while adding an entry.<br />
Defines access controls that apply to users who are considered<br />
administrators of the directory.<br />
Specifies the details of an agreement between two DSAs for replication<br />
purposes.<br />
Specifies the name of the file to which the alarm-log is written.<br />
Specifies the name of the file to which the alert-log is written.<br />
Specifies whether the DSA manages the integrity of alias entries, for<br />
example, deleting aliases that point to deleted entries.<br />
Specifies whether the DSA is accepting new binds.<br />
set always-chain-down Specifies whether requests are chained down, overriding X.500<br />
controls.<br />
set attribute<br />
set attr-cache-reload<br />
set attr-set<br />
set auth-trap<br />
set cache-attr<br />
set cache-index<br />
set cert-log<br />
set connect-log<br />
Specifies all of the information relating to an attribute.<br />
The default is true. When set to false, a filter with an attribute type that<br />
is not in the attribute cache will not cause the cache to automatically<br />
reload from the database and is considered as not present in the<br />
directory.<br />
To see the current value, use get dip all;.<br />
Specifies a name for a list of attributes.<br />
A mechanism that can be used to hook into the authentication<br />
processing on the DSA using SNMP traps.<br />
Defines the attributes returned in a fast lookup (DXcache). The value<br />
all-attributes can be used to ensure that all attributes are cached;<br />
however, when a large number of attributes are used, this will require<br />
a large amount of memory.<br />
Sets the attributes to index in DXcache. The cache will respond to a<br />
search filter that uses one of these attributes. You can define as many<br />
as you like, separated by commas. Memory requirements are affected.<br />
Specifies the name of the file to which the cert-log is written.<br />
Specifies the name of the file to which the connect-log is written.<br />
DXserver Command Language B–3
Set Commands<br />
Command<br />
set credits<br />
set database-name<br />
set dbconnection<br />
set dsa<br />
set dynamic-access-control<br />
set eis-count-attr<br />
set group<br />
set hold-ldap-connections<br />
set index-reverse<br />
set index-wide<br />
set ignore-name-bindings<br />
set limit-list<br />
set limit-search<br />
set lookup-cache<br />
set max-bind-time<br />
set max-cache-size<br />
set max-dsp-ops<br />
set max-local-ops<br />
Description<br />
A control used to regulate the DSA—new requests are accepted until<br />
the number of credits is exhausted.<br />
Specifies the name of the Advantage Ingres database used by the<br />
directory.<br />
Specifies the elements of a database connection.<br />
Specifies the knowledge of a DSA.<br />
When TRUE, enables dynamic access controls; when FALSE, disables<br />
dynamic access controls.<br />
Specifies the name of the attribute that is used when you want a count<br />
of matches, instead of a list of matching entries.<br />
Defines a group of users. Groups are used when defining access<br />
controls.<br />
When TRUE, prevents a DSA from clearing the underlying TCP/IP<br />
connection after a bind refusal. The default value is FALSE.<br />
Lists the attributes to which to apply reverse index.<br />
Lists the attributes to which to apply wide index.<br />
Lets the DXserver operate without name bindings. This is useful when<br />
the schema is imported from a directory that does not support name<br />
bindings.<br />
Specifies whether the DSA should reject all list requests. This is useful<br />
when there are thousands of entries under one node.<br />
Specifies whether to limit the types of searches processed by the DSA.<br />
This causes searches with no filter or with a filter containing an<br />
attribute present; substring any; or a range of values to be rejected.<br />
Specifies whether DXcache is enabled or not.<br />
Specifies the maximum time a bind is held before being disconnected.<br />
Sets the maximum amount of memory (in MB) that DXcache uses. This<br />
value depends on how much memory your computer has. You should<br />
set this to around 50% to 70% of your machine’s total memory,<br />
depending on other programs’ memory requirements on the same<br />
computer.<br />
Specifies the maximum number of DSP operations that are accepted<br />
simultaneously.<br />
Specifies the maximum number of simultaneous local operations that<br />
this DSA will accept.<br />
B–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
Command<br />
set max-op-time<br />
set max-op-size<br />
set max-users<br />
set min-auth<br />
set modify-on-add<br />
set multi-casting<br />
set multi-chaining<br />
set multi-write-disp-recovery<br />
set multi-write-queue<br />
set multi-write-retry-time<br />
set name-binding<br />
set not-searchable<br />
set object-class<br />
set oid-prefix<br />
set op-error-trap<br />
set op-attrs<br />
set password-age<br />
set password-force-change<br />
set password-history<br />
set password-last-use<br />
set password-length<br />
set password-allow-locking<br />
Description<br />
Specifies the maximum amount of time a single operation takes before<br />
it is aborted.<br />
Specifies the maximum size of an operation that is accepted by this<br />
DSA.<br />
Specifies the maximum number of simultaneous users on a DSA.<br />
Specifies the minimum level of authentication that is accepted.<br />
Adds modifyTimestamp to a newly created entry. Used for SAP<br />
compatibility.<br />
See set multi-chaining.<br />
Specifies whether requests are chained to other DSAs.<br />
Enables or disables multiwrite DISP. The default value is FALSE.<br />
Specifies the maximum size of the queue of requests to be written to<br />
other DSAs.<br />
This defines the time (in seconds) at which DXserver will attempt to<br />
bind to a Multiwrite peer which cannot be contacted.<br />
The default value is 60 seconds.<br />
Specifies all of the information relating to a name binding, which<br />
specifies an acceptable parent-child relationship between two object<br />
classes.<br />
Lists attributes that are not to be searched.<br />
Specifies all of the information relating to an object class.<br />
Specifies a name for an OID, which is used as a prefix when specifying<br />
the OIDs for attributes, attr-sets, and object classes.<br />
A mechanism that can be used to hook into the handling of errors<br />
using SNMP traps.<br />
Specifies whether operational attributes are enabled.<br />
Sets the number of days a password is valid.<br />
Forces users to change their passwords after their passwords have<br />
been reset.<br />
Sets the maximum number of entries to retain in the history.<br />
Sets the number of days a password remains valid. When the value is<br />
exceeded, the password expires.<br />
Sets the minimum length of a password.<br />
Allows user accounts to be suspended by locking the password. This<br />
DXserver Command Language B–5
Set Commands<br />
Command<br />
set password-max-suspension<br />
set password-min-age<br />
set password-non-alpha-num<br />
set password-numeric<br />
set password-policy<br />
set password-retries<br />
set password-storage<br />
set precedence<br />
set protected-items<br />
set prune-oc-parents<br />
set public-user<br />
set query-log<br />
set reg-user<br />
set relaxed-not-search<br />
set return-oc-parents<br />
set role-subtree<br />
set snmp-log<br />
set ssl-auth-bypass-entry-check<br />
Description<br />
does not delete the password.<br />
Sets the number of seconds after which a suspended password<br />
reactivates.<br />
Sets the number of days since a password was changed last before it<br />
can be changed again (lockout period).<br />
Sets the minimum number of nonalphanumeric characters a password<br />
contains.<br />
Sets the minimum number of numeric characters a password contains.<br />
Specifies whether password management is enabled.<br />
Sets the number of consecutive failed logon attempts before a<br />
password is suspended.<br />
Specifies a password storage method.<br />
Specifies a precedence rule, ordering DSA knowledge.<br />
Defines static access controls, which apply to an item or items within<br />
the directory.<br />
Removes redundant superior object classes when new entries are<br />
created.<br />
Defines static access controls that apply to users who are public users<br />
of the directory. A public user is an unidentified user (anonymous<br />
user).<br />
Specifies the name of the file to which the query-log is written.<br />
Defines static access controls that apply to users who are registered<br />
users of the directory. A registered user is an identified user (as<br />
opposed to an anonymous user).<br />
Interprets NOT in the non-standard manner supported by some other<br />
directories.<br />
For example, a search for "description not equal M*" returns entries<br />
that have nothing in the description and all entries that do not start<br />
with M. When the flag is false (or not set), a search returns only entries<br />
that have the attribute populated and do not start with M.<br />
Replaces the superior object classes of entries retrieved when<br />
searching.<br />
Specifies the DN where the roles are defined.<br />
Specifies the port address and server to which SNMP traps is written.<br />
Allows a bind to skip the server authentication step if it has already<br />
B–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
Command<br />
set stats-log<br />
set summary-log<br />
set syntax-alias<br />
set super-user<br />
set trace<br />
set trace-level<br />
set trace-log<br />
set transparent-routing<br />
set trap-on-update<br />
set trust-sasl-proxy<br />
set unique-attrs<br />
set update-log<br />
set use-roles<br />
set user-idle-time<br />
set warn-log<br />
set write-precedence<br />
Description<br />
authenticated itself to the SSLD.<br />
Specifies the name of the file to which the stats-log is written.<br />
Specifies the name of the file to which the summary-log should be<br />
written.<br />
Creates a syntax alias for use when an attribute syntax is not<br />
supported by <strong>eTrust</strong> <strong>Directory</strong>.<br />
Defines static access controls that apply to users who are considered<br />
super-users of the directory.<br />
Specifies tracing options.<br />
Specifies the level of detail when tracing.<br />
Specifies the name of the file to which the trace-log is written.<br />
When set to true, enables a router DSA to route LDAP queries without<br />
knowing the related schema.<br />
A mechanism that can be used to hook into the processing of updates<br />
on the DSA using SNMP traps.<br />
Specifies the distinguished name of the trusted proxy.<br />
Specifies attributes which are to have a unique value.<br />
Specifies the name of the file to which the update-log is written.<br />
Set to true to enable role-based access controls; set to false to disable<br />
role-based access controls.<br />
Specifies the maximum time a user is idle before being disconnected.<br />
Specifies the name of a separate file for error and warning messages.<br />
Ensure that at least warn or error tracing is turned on.<br />
Specifies which DSAs are chosen to perform updates.<br />
DXserver Command Language B–7
Set Commands<br />
The set admin-user Command<br />
Use the set admin-user command to specify static access controls. See the chapter<br />
“Security” for more information.<br />
Parameter<br />
attrs<br />
auth-level<br />
entry<br />
group<br />
own-entry<br />
perms<br />
subtree<br />
user<br />
user-subtree<br />
validity<br />
Description<br />
Lists attributes to which this access control applies.<br />
Specifies the level of authentication required. May be simple, ssl-auth.<br />
Specifies an entry to which access is granted.<br />
Specifies a group of users for admin-user access.<br />
Specifies a user as admin-user for their own entry.<br />
Lists the permissions granted. May include read, add, remove, modify, rename,<br />
all.<br />
Specifies a subtree of the directory to which access is granted.<br />
Specifies a named user to be treated as an admin-user.<br />
Specifies a subtree within the user tree; users in this subtree are affected by this<br />
access control.<br />
Specifies the period during which this is valid. May include start, end, on.<br />
The set agreement Command<br />
Use the set agreement command to define a DISP connection between two DSAs.<br />
See the chapter “Replication” for more information.<br />
Parameter<br />
area<br />
initiator<br />
relay<br />
responder<br />
strategy<br />
Description<br />
Specifies the portion of the DIT covered by this agreement.<br />
Specifies the name of the initiating DSA, and whether that DSA is the supplier or<br />
consumer in the DISP connection.<br />
Specifies the name of the intermediate relay DSA. These parameters may include<br />
anonymous, clear-password, ssl-auth.<br />
Specifies the name of the responding DSA, and the parameters of the connection.<br />
These parameters may include anonymous, clear-password, ssl-auth.<br />
Specifies when the interchange of data takes place. May include on-change,<br />
minutely, hourly, daily, weekly, monthly, incremental, full.<br />
B–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
The set attribute Command<br />
Use the set attribute command to define an attribute, which is a basic building<br />
block in the schema. See the chapter “Schema Definition” for more information.<br />
Parameter<br />
description<br />
equality<br />
ldap-names<br />
name<br />
no-user-modification<br />
ordering<br />
single-valued / multi-valued<br />
substr<br />
syntax<br />
Description<br />
A description of the attribute.<br />
Indicates the type of matching to apply to the attribute.<br />
Alternative names for the attribute. Think of these as nicknames—<br />
they can be used anywhere the name can be used. Often these are<br />
shorter, and used in DNs, for example, c for country.<br />
The name of the attribute. This is its formal name, and is often<br />
descriptive.<br />
Indicates whether the user can modify the value of the attribute<br />
Indicates the ordering rules to apply to the attribute.<br />
Indicates whether the attribute has multiple values (for example, lines<br />
of an address), or is limited to a single value (for example, salary).<br />
Indicates the substring-matching rule to apply to the attribute.<br />
Indicates the type of data that may be stored in the attribute.<br />
The set dsa Command<br />
Use the set dsa command to define the knowledge of a DSA. See the chapter<br />
“General Information” for more information.<br />
Important! You must declare the parameters in a set order.<br />
Parameter<br />
prefix<br />
native-prefix<br />
dsa-name<br />
dsa-password<br />
ldap-dsa-name<br />
ldap-dsa-password<br />
Description<br />
Specifies a partial DN, which specifies the portion of the DIT served by this<br />
DSA.<br />
Specifies a partial DN, which the DSA recognizes as applicable to its entries—<br />
generally only used with LDAP servers.<br />
Specifies the name of the DSA as a DN; not to be confused with the name of the<br />
server<br />
Specifies the password other DSAs must supply to communicate with this DSA.<br />
Specifies the name of the LDAP DSA.<br />
Specifies the password of the LDAP DSA.<br />
DXserver Command Language B–9
Set Commands<br />
Parameter<br />
address<br />
tsap<br />
ssap<br />
osi-psap<br />
disp-psap<br />
cmip-psap<br />
snmp-port<br />
console-port<br />
remote-console-port<br />
remote-console-ssl<br />
console-password<br />
ssld-port<br />
auth-levels<br />
dsp-idle-time<br />
dsa-flags<br />
trust-flags<br />
link-flags<br />
Description<br />
Specifies one or more addresses (TCP/IP address + port number) the DSA.<br />
Specifies Transport SAP.<br />
Specifies Session SAP.<br />
Specifies Presentation SAP.<br />
Specifies DISP Presentation SAP; if absent, DISP is disabled.<br />
Specifies CMIP Presentation SAP; if absent, CMIP is disabled.<br />
Specifies the SNMP port.<br />
Allows DXconsole to accept connections from the local computer. When this is<br />
not specified, the DSA does not have a local console.<br />
Allows DXconsole to accept a connection from a remote computer on this port.<br />
When this is not specified, there is no remote console for the DSA.<br />
Forces DXconsole encryptDXconsole sessions when it runs remotely.<br />
The password required for connections from a remote computer. This password<br />
is transmitted in clear text.<br />
Specifies the port number that should be used for SSLD.<br />
Specifies the levels of authentication that will be accepted by this DSA. May<br />
include anonymous, clear-password, and ssl-auth.<br />
Specifies the maximum time (in seconds) that a DSP connection can be idle<br />
before it is disconnected.<br />
Specifies the flags that control the operation of the DSA. The flags include<br />
multiwrite, shadow, read-only, relay, load-share, no-routing-ac, limit-search, limit-list,<br />
and multi-write-notify.<br />
Specifies flags relating to trust that control the operation of the DSA. The flags<br />
include allow-check-password, trust-conveyed-originator, allow-upgrading, allowdowngrading,<br />
and no-server-credentials.<br />
Specifies flags that control connecting to the DSA. The flags include dsp-ldap,<br />
dsp-ldapv2, ms-exchange, ms-ad, ssl-encryption, and unavailable. For a complete list,<br />
see Link Flags in the chapter “General Administration.”<br />
B–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
The set name-binding Command<br />
Use the set name-binding command to define a name binding. This defines the<br />
hierarchy of the directory. See the chapter “Schema Definition” for more<br />
information.<br />
Parameter<br />
allowable-parent<br />
name<br />
named-by<br />
optional<br />
Description<br />
Specifies the parent and child object classes.<br />
The name of the name binding. This is often descriptive; it can be constructed by<br />
concatenating the names of the object classes being connected.<br />
Lists the attributes that name an object of the child object class. Often only one<br />
attribute is listed.<br />
Lists attributes that may optionally be appended to the list specified in namedby.<br />
The set object-class Command<br />
Use the set object-class command to define an object class, which is a fundamental<br />
part of the schema, and essential to the directory. See the chapter “Schema<br />
Definition” for more information.<br />
Parameter<br />
description<br />
kind<br />
ldap-names<br />
may-contain<br />
must-contain<br />
name<br />
subclass-of<br />
Description<br />
A description of the object class.<br />
Specifies the kind of object class—may be structural, auxiliary, or abstract.<br />
Alternative names for the object class. Think of these as nicknames—they can be<br />
used anywhere the name can be used. Often these are shorter.<br />
Lists the attributes that may be supplied in an instance of this object class.<br />
Lists the attributes that must be supplied for every instance of this object class.<br />
The name of the object class. This is its formal name, and is often descriptive.<br />
Specifies the object class, or object classes, from which this object class inherits.<br />
DXserver Command Language B–11
Set Commands<br />
The set protected-items Command<br />
Use the set protected-items command to specify static access controls. Generally,<br />
you use protected-items controls to protect specified attributes in a specified<br />
portion of the DIT. See the chapter “Security” for more information.<br />
Parameter<br />
attrs<br />
entry<br />
group<br />
own-entry<br />
perms<br />
subtree<br />
user<br />
user-subtree<br />
validity<br />
Description<br />
Lists attributes to which this access control applies.<br />
Specifies an entry to which this access control applies.<br />
Specifies that this control applies to a particular group of users.<br />
Specifies that this control applies to a user accessing their own entry.<br />
Gives registered users access to modify 'role' attribute in their own entries.<br />
Specifies a subtree of the directory to which this access control applies.<br />
Specifies that this control applies to a particular user.<br />
Specifies a subtree within the user tree; users in this subtree are affected by this<br />
access control.<br />
Specifies the period during which this is valid. May include start, end, on.<br />
The set public-user Command<br />
Use the set public-user command to specify static access controls. See the chapter<br />
“Security” for more information.<br />
Parameter<br />
attrs<br />
entry<br />
perms<br />
subtree<br />
validity<br />
Description<br />
Lists attributes to which this access control applies.<br />
Specifies an entry to which access is granted.<br />
Lists the permissions granted. May include read, add, remove, modify, rename,<br />
all.<br />
Specifies a subtree of the directory to which access is granted.<br />
Specifies the period during which this is valid. May include start, end, on.<br />
B–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Set Commands<br />
The set reg-user Command<br />
Use the set reg-user command to specify static access controls. See the chapter<br />
“Security” for more information.<br />
Parameter<br />
attrs<br />
entry<br />
group<br />
own-entry<br />
perms<br />
subtree<br />
user<br />
user-subtree<br />
validity<br />
Description<br />
Lists attributes to which this access control applies.<br />
Specifies an entry to which access is granted.<br />
Specifies a group of users to be treated as a reg-user.<br />
Specifies that a user may be treated as a reg-user for their own entry.<br />
Lists the permissions granted. May include read, add, remove, modify, rename,<br />
all.<br />
Specifies a subtree of the directory to which access is granted.<br />
Specifies a user to be treated as a reg-user.<br />
Specifies a subtree within the user tree; users in this subtree are affected by this<br />
access control.<br />
Specifies the period during which this is valid. May include start, end, on.<br />
The set super-user Command<br />
Use the set super-user command to specify static access controls. See the chapter<br />
“Security” for more information.<br />
Parameter<br />
auth-level<br />
group<br />
own-entry<br />
user<br />
user-subtree<br />
validity<br />
Description<br />
Specifies the level of authentication required. May be simple, ssl-auth.<br />
Specifies a group of users to be treated as a super-user.<br />
Specifies that a user may be treated as a super-user for their own entry.<br />
Specifies a user to be treated as a super-user.<br />
Specifies a subtree within the user tree; users in this subtree are affected by this<br />
access control.<br />
Specifies the period during which this is valid. May include start, end, on.<br />
DXserver Command Language B–13
Source Commands<br />
Source Commands<br />
A source command is a means of including shared commands. It says, “Include<br />
the contents of this file here.” You can nest source commands, and source a file<br />
that contains further source commands. An example is shown below:<br />
source “file2.dxg”<br />
set access-controls<br />
= true;<br />
source “file3.dxc”<br />
set group =<br />
source “file4.dxc”<br />
set super-user =<br />
set reg-user =<br />
B–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Trace Commands<br />
Trace Commands<br />
You can specify trace commands in two ways:<br />
■<br />
■<br />
You can enter them as arguments to a trace command. For example:<br />
trace all;<br />
You can enter them as parameters to a set trace command. For example:<br />
set trace = all;<br />
Command<br />
trace alert<br />
trace all<br />
trace dsa<br />
trace cert<br />
trace connect<br />
trace error<br />
trace ldap<br />
trace limit<br />
trace none<br />
trace query<br />
trace stack<br />
trace stats<br />
trace summary<br />
trace time<br />
trace update<br />
trace warn<br />
trace x500<br />
Description<br />
Displays authentication errors.<br />
Traces everything.<br />
Similar to the x500 trace, but also includes tracing of the module flow inside the<br />
DSA.<br />
Displays certificate operations.<br />
Displays connections.<br />
Displays error messages of very high severity. Compare with TRACE WARN.<br />
Traces detailed LDAP operations.<br />
Traces any violation of size or time limits.<br />
Traces nothing.<br />
Displays a one-line summary containing the server request and result.<br />
Displays detailed protocol tracing.<br />
Displays statistical information for each minute the DSA is not idle.<br />
Displays summary information.<br />
Displays the start time, end time, and elapsed time of an operation with a brief<br />
summary of the operation.<br />
Displays update operations—add, delete, modify, and rename.<br />
Displays error messages of moderately high severity. Compare with TRACE<br />
ERROR.<br />
Displays the full details of the service request, confirmation, or error. This traces<br />
DAP, DSP, and LDAP operations.<br />
DXserver Command Language B–15
Appendix<br />
C<br />
Messages and Logs<br />
This appendix describes the error and diagnostic logs that <strong>eTrust</strong> <strong>Directory</strong><br />
provides to assist you in diagnosing problems. It also explains some common<br />
alarms and warning messages.<br />
For further information, contact Computer Associates at<br />
http://supportconnect.ca.com.<br />
UNIX System Error Log<br />
Both UNIX and DXserver log errors to the system error log. By default, the<br />
system also displays all errors in the console window.<br />
The system error log file is located in …/var/adm/messages.<br />
A useful command for showing the most recent messages is:<br />
%$ dmesg<br />
Windows Event Log<br />
Both Windows and DXserver log errors in the Windows event log. You can view<br />
the event logs in the Windows Event Viewer.<br />
To display the Event Viewer, click Start on the taskbar, and then choose<br />
Programs, Administrative Tools (Common), Event Viewer.<br />
DXserver logs errors in the Application Log. You can view the Application Log<br />
by selecting Event Viewer Log, Application.<br />
Messages and Logs C–1
DXserver Logs<br />
DXserver Logs<br />
DXserver logs all errors, alarms, and warnings to server-specific log files. Each<br />
server has both an alarm log and is usually configured with a trace log. The<br />
server alarm log provides more detail than the system error log, while the trace<br />
log provides additional diagnostic information.<br />
Note: If an error is encountered while starting DXserver, the server cannot start,<br />
and diagnostics are logged to these server-specific logs rather than to the system<br />
error log.<br />
When a DXserver fails to start or is not behaving as expected, consult the server<br />
logs.<br />
On UNIX, the server log files are:<br />
$DXHOME/logs/servername_alarm.log<br />
$DXHOME/logs/servername_trace.log<br />
On Windows, the server log files are:<br />
%DXHOME%\logs\servername_alarm.log<br />
%DXHOME%\logs\servername_trace.log<br />
In all cases, substitute the name of your server for servername.<br />
C–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Advantage Ingres Logs<br />
Advantage Ingres Logs<br />
The Advantage Ingres RDBMS server reports all database-related errors to a<br />
single log file. This file may contain more detailed diagnostics about databaserelated<br />
problems than the DXserver alarm log.<br />
Note: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
On UNIX, the Advantage Ingres error log file is:<br />
$II_SYSTEM/ingres/files/errlog.log<br />
On Windows, the Advantage Ingres error log file is:<br />
%II_SYSTEM%\ingres\files\errlog.log<br />
DSA Does Not Start and Alarm Log Reports "Database is inconsistent"<br />
The alarm log reports something like this:<br />
20040305.084328 DIB001: Unable to connect to database 'democorp' as ' '<br />
SQL error (-39100): E_US0026 Database is inconsistent. Please contact the system<br />
manager.<br />
Reason:<br />
A database "goes inconsistent" when Ingres does not know what state the<br />
database is in. This is often caused by a hardware failure or hard shutdown. The<br />
recommended method of recovery is to restore from backup.<br />
The Ingres error log may give some indication as to why the database is<br />
inconsistent. Things to look for include an absence of shutdown messages,<br />
references to hardware problems (could not write to disk, etc), or anything OS<br />
related.<br />
Action:<br />
For non-critical databases, the following ingres command can be used:<br />
verifydb -mrun -sdbname "democorp" -oforce_consistent<br />
This will give you several warnings. The force_consistent command is used to<br />
permit entry into a database that is inconsistent. This does not fix the problem<br />
with the database; it merely allows you to force the database to act as if it were in<br />
a consistent state. This can be very dangerous if used against a production<br />
database. Hidden data damage may render one or more tables in the database<br />
unrecoverable at some time in the future.<br />
Messages and Logs C–3
Advantage Ingres Logs<br />
I get "failed to connect" errors<br />
E_LQ0001 Failed to connect to DBMS session.<br />
E_LC0001 CGA protocol service (G<strong>CA</strong>_REQUEST) failure.<br />
Internal service status E)GC0139 -- No DBMS servers (for the specified<br />
database) are running in the target installation.<br />
Reason:<br />
This usually means that Ingres is not started.<br />
Action:<br />
The easiest way to resolve this is to stop and restart Ingres. The process differs<br />
slightly for Windows and UNIX/Linux platforms.<br />
To stop and restart Ingres on a Windows computer:<br />
1. From the Services menu, look for the status of Ingres Intelligent Database.<br />
2. If it is "starting" then either be patient, or manually kill the processes (see<br />
below). Stop the Service.<br />
3. After Ingres had stopped, check Task Manager for the following processes:<br />
- iigcc (comms server, optional)<br />
- iigcn (name server)<br />
- iidbms (one or more DBMS servers)<br />
- dmfrcp (recovery server)<br />
- dmfacp (archiver)<br />
4. Try one or more of the following:<br />
- Manually kill any processes remaining.<br />
- Reboot the computer.<br />
- Stop Ingres again.<br />
5. Start Ingres again.<br />
6. Check that all the processes listed above are running. If one or more<br />
processes failed to start, then send the ingres errlog.log to <strong>CA</strong> Technical<br />
Services.<br />
To stop and restart Ingres on a UNIX or Linux computer:<br />
1. Enter the following command to stop Ingres:<br />
ingstop<br />
2. After the ingstop command completes, check ps -ef' for the following<br />
processes:<br />
- iigcc (comms server, optional)<br />
C–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Advantage Ingres Logs<br />
- iigcn (name server)<br />
- iidbms (one or more DBMS servers)<br />
- dmfrcp (recovery server)<br />
- dmfacp (archiver)<br />
3. Try one or more of the following:<br />
- Manually kill any processes remaining.<br />
- Reboot the computer.<br />
- Stop Ingres again.<br />
4. Enter the following command to start Ingres:<br />
ingstart<br />
5. Check that all the processes listed above are running. If one or more<br />
processes failed to start, then send the ingres errlog.log to <strong>CA</strong> Technical<br />
Services.<br />
6. To test a connection, type 'sql iidbdb' at the command prompt. If you get an<br />
asterisk prompt, then the connection succeeded. Type '\q' to quit. If the<br />
connection failed, then screendump the output, and pass it to your favourite<br />
Ingres whiz, along with the errlog.log.<br />
DSA Does Not Start and Alarm Log Reports “No DBMS Servers”<br />
If your alarm log has the following text, your IngresDBMS server is not setup<br />
correctly.<br />
Unable to connect to database 'democorp' as \'\' SQL error (-38100): E_LQ0001<br />
Failed to connect to DBMS session. E_LC0001 G<strong>CA</strong> protocol service (G<strong>CA</strong>_REQUEST)<br />
failure. Internal service status E_GC0139 -- No DBMS servers (for the specified<br />
database) are running in the target installation..<br />
Reason:<br />
One of the causes of the above error is that the IngresDBMS server startup count<br />
it set to 0 instead of 1.<br />
Action:<br />
If this error message has occurred on a production computer, you will need to<br />
contact <strong>eTrust</strong> <strong>Directory</strong> support for help.<br />
If this error message has occurred on a test computer and you previously had<br />
enterprise <strong>eTrust</strong> <strong>Directory</strong>, and you just installed embedded <strong>eTrust</strong> <strong>Directory</strong>,<br />
run the test again with a valid <strong>eTrust</strong> <strong>Directory</strong> license before you run the<br />
embedded install.<br />
For more help, please contact <strong>CA</strong> Technical Services.<br />
Messages and Logs C–5
Advantage Ingres Logs<br />
Ingres Error Log Reports “Unknown ipcclean” (Windows Only)<br />
Reason:<br />
If you have the cygwin toolkit installed, an option inside this package includes a<br />
file called ipcclean. If cygwin\bin is in your path, then when you install, Ingres<br />
will try to use this ipcclean tool instead of the one installed by Ingres. This will<br />
cause the post-installation setup to fail.<br />
Action:<br />
1. Uninstall <strong>eTrust</strong> <strong>Directory</strong>.<br />
2. Check your computer is clean by using CleanReg.exe.<br />
3. Rename cygwin ipcclean to ipcclean.old and re-run the install.<br />
4. Do one of the following steps:<br />
- Move Ingres\bin to the beginning of the %PATH% environment<br />
variable.<br />
- Rename the cygwin tool to ipccleanCygwin and leave the path as is.<br />
C–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Alarm Messages<br />
DXserver Alarm Messages<br />
Database dbname has more entries (n) than license allows (m)<br />
Reason:<br />
The number of entries in the DXserver database has been exceeded. (This is only<br />
relevant to legacy licenses, not those issued by Computer Associates.)<br />
Action:<br />
Either reduce the number of entries in the database or purchase a larger license.<br />
Database attribute attribute-name has different syntax than schema<br />
Reason:<br />
The syntax of the attribute-name definition in the DSA schema has been<br />
changed; however, directory entries have been created with the old syntax.<br />
Action:<br />
You must roll back the syntax in the schema. When you need a new syntax,<br />
dump the database using DXtools, and then create a new one with the new<br />
syntax.<br />
Database attribute attribute-name not defined in schema<br />
Reason:<br />
The attribute attribute-name presented in the LDAP (or DAP) call has not been<br />
defined in the schema.<br />
Action:<br />
Check the attribute-name definition. It is possible that the LDAP client has<br />
misspelled the attribute. Alternatively, the LDAP client may be using an attribute<br />
name not defined in the schema. If the latter is true, define the attribute<br />
appropriately.<br />
Messages and Logs C–7
DXserver Alarm Messages<br />
Error in initialization files<br />
Reason:<br />
One or more of the DXserver initialization files (.dxi) in the servers subdirectory<br />
are not configured correctly.<br />
Action:<br />
Check the configuration of the initialization files.<br />
Out of memory<br />
Reason:<br />
The DSA has run out of memory when processing the result of a large search.<br />
Action:<br />
Reduce the number of results returned by single searches by breaking them into<br />
a number of separate, smaller searches, each returning part of the result. Also,<br />
consider increasing the amount of virtual memory.<br />
Prefix too large<br />
Reason:<br />
The DSA prefix is greater than 255 characters.<br />
Action:<br />
Shorten the DSA prefix.<br />
Rejected console request<br />
Reason:<br />
More than one telnet session has attempted to connect to the DXserver console.<br />
Action:<br />
Remember that <strong>eTrust</strong> <strong>Directory</strong> supports only one console connection at a time.<br />
C–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Alarm Messages<br />
DIB001: Unable to connect to database 'production'<br />
Reason:<br />
This message may be because the ingres user has a password, which means that<br />
<strong>eTrust</strong> <strong>Directory</strong> cannot connect to the database.<br />
Action:<br />
There are two things that can be done about this:<br />
■ Use accessdb to remove the user’s password<br />
■ If the user must have a password, then follow these steps:<br />
a. Remove the following command:<br />
set database-name = "production";<br />
b. Replace it with this command:<br />
set dbconnection = {db-name=production, db-user=dba, dbpassword=mypassword};<br />
DIB001: Unable to attr load cache<br />
Reason:<br />
This can happen when the user that the dxserver is trying to connect to the<br />
database as is not the owner of the database.<br />
Action:<br />
To resolve the problem you must give the user grants on the database. This can<br />
be done with the DXgrantdb tool, which is provided with <strong>eTrust</strong> <strong>Directory</strong>. To<br />
do this, run the following command:<br />
dxgrantdb database [user]<br />
where:<br />
■<br />
■<br />
database is the name of the database where access is granted.<br />
user is the name of the user whose access is granted. If user is omitted, all<br />
database users will be granted access.<br />
After running this you will be able to operate a directory on the database.<br />
Or, you can configure the dxserver to connect as a specific user by editing the<br />
server configuration. To edit the server configuration:<br />
1. Remove the following command:<br />
set database-name = "production";<br />
2. Replace it with this command:<br />
set dbconnection = {db-name=production, db-user=dba, db-password=mypassword};<br />
Messages and Logs C–9
DXserver Alarm Messages<br />
DIB003<br />
This error code refers to a problem with allocating a new internal entry identifier.<br />
Reason:<br />
If this is seen, then you probably have added the maximum number of possible<br />
entries to the directory.<br />
Action:<br />
You may have to use distribution.<br />
DIB004: attr aid not in cache<br />
The DIB004 error code refers to a problem with the attribute cache.<br />
Reason:<br />
During a read, search, or update operation, an attribute ID was found internally<br />
that does not exist in the attribute cache. This may be the case if the attribute was<br />
added for the first time by another DSA using the same database.<br />
Depending on where this was encountered and current configuration setting the<br />
attribute cache is usually reloaded and the operation redone.<br />
DIB004: attr aid too big for cache - unable to resize<br />
DIB004: subattr aid too big for cache - unable to resize<br />
DIB004: too many attributes (number of attrs) to register<br />
The DIB004 error code refers to a problem with the attribute cache.<br />
Reason:<br />
These messages are indicative of a problem resizing the attribtue cache. This is<br />
usually due to running out of memory. These errors are usually found in<br />
conjunction with out-of-memory errors.<br />
C–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Alarm Messages<br />
DIB008<br />
This error code refers to a problem with normalising an attribute value.<br />
Reason:<br />
This may be the case if the attribute value is not valid for the defined attribute<br />
syntax. The associated error message gives futher information about the type of<br />
attribute being processed.<br />
DIB009<br />
This error code refers to a problem with buffer or storage sizes.<br />
Reason:<br />
This may be the case if the RDN (either normalised or raw) of an entry is too big.<br />
MW-DISP: Invalid update strategy<br />
Reason:<br />
Standard MW-DISP (NOT cache-only) can only receive an incremental-refresh<br />
DISP update. This message indicates it has received something other than an<br />
incremental-refresh.<br />
This could happen if you have a mix of cache-only and standard DSAs<br />
configured to replicate to each other. This is not supported.<br />
MW-DISP: Invalid update strategy for cache-only<br />
Reason:<br />
Cache-only MW-DISP can only receive a total-refresh DISP update because it has<br />
no database to apply an incremental update to. This message indicates it has<br />
received something other than a total-refresh.<br />
This could happen if you have a mix of cache-only and standard DSAs<br />
configured to replicate to each other. This is not supported.<br />
Messages and Logs C–11
DXserver Alarm Messages<br />
Unable to connect to database - Shutting down<br />
Reason:<br />
This alarm is shown if during recovery from a database error, or switching<br />
databases the DSA is unable to connect to the configured database.<br />
Action:<br />
If this alarm is raised, the DSA will automatically shut down.<br />
For more information about thi, see the section Manage Connections to the<br />
Database.<br />
Shutting down due to SQL error<br />
Reason:<br />
This alarm is shown if shutdown-on-sql-error is set to TRUE in the configuration<br />
of a DSA and an SQL error is encountered.<br />
Action:<br />
If this alarm is raised, the DSA will automatically shutdown.<br />
For more information about thi, see the section Manage Connections to the<br />
Database.<br />
Error in initialization file<br />
Action:<br />
To find out which command caused this error, look in the trace log.<br />
For example, see the following section of a router_trace.log:<br />
20040902.123320 ERROR : Syntax Error: Line 14 in C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong><br />
<strong>Directory</strong>\dxserver\config\settings\default.dxc near 'set'<br />
Expected a ';'<br />
> Setting max-users to (255)<br />
* 20040902.123320 Error in initialization files<br />
C–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Warning Messages<br />
DXserver Warning Messages<br />
To prevent excessive tracing and logging of repetitive warning message,<br />
configure the affected DSA with "set trace = error". This will prevent warnings<br />
from being logged, but will still capture real errors.<br />
Cannot register address<br />
Reason:<br />
The DSA has been configured with incorrect protocol stack information.<br />
Action:<br />
Check the set DSA command within the appropriate knowledge file. Check the<br />
details in the address setting.<br />
DIP not connected to a database<br />
Reason:<br />
The DSA has been requested to add or update an entry within its naming context<br />
and found that it has not been configured with a database.<br />
Action:<br />
Check the set database-name command in the appropriate configuration file (.dxc)<br />
in the database subdirectory.<br />
Database dbname entries (n) is close to license maximum (m)<br />
Reason:<br />
The directory exceeds 90 percent of the licensed maximum. (This is only relevant<br />
to legacy licenses, not those issued by Computer Associates.)<br />
Action:<br />
Consider reducing the number of directory entries or purchasing a larger license.<br />
Messages and Logs C–13
DXserver Warning Messages<br />
Licence expires in n days<br />
Reason:<br />
These warnings begin 20 days before the license is due to expire. (This is only<br />
relevant to legacy licenses, not those issued by Computer Associates.)<br />
Action:<br />
Consider purchasing a new license.<br />
No stack nor console<br />
Reason:<br />
The DSA has been configured without any protocol stack information.<br />
Action:<br />
Check the set dsa command within the appropriate knowledge file. Typically, this<br />
message occurs when there is a mismatch between the name of the DSA (from<br />
the initialization file (.dxi) in the servers subdirectory) and the name of the DSA<br />
used in the set dsa command in the DXserver knowledge file.<br />
Undefined syntax not ASN.1<br />
The DXserver syntax binary refers only to datatypes that have an ASN.1<br />
representation. To represent arbitrary binary data, octetString is a more suitable<br />
choice.<br />
Attribute (attrName) exceeds searchable size limit (106) - Refer to Managing Indexes in the<br />
Admin <strong>Guide</strong><br />
Reason:<br />
This message means that an attribute value has been added that is too big to<br />
search reliably. Some search requests may produce incorrect results. The length<br />
of an attribute value that will generate this message can vary, but the normalised<br />
value can only by 106 bytes long before this message is reported. Note that due<br />
to the different normalisation techniques that can be applied it may be possible<br />
to add data that is much bigger than 106 bytes without causing a problem. For<br />
example a 1MB jpeg photo will not cause this problem despite it's size, while a<br />
110 character sentence probably will.<br />
The search overflow message points out that some values are greater than the<br />
106 byte normalised limit and their normalised form has been truncated.<br />
C–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXserver Warning Messages<br />
Searches that have the same first 106 normalised values will match all entries<br />
even if they varied past this point.<br />
Searches for values ending with a particular value will give curious results on<br />
this data as it will be matching on the truncated value.<br />
Note This is a limitation for searching only, data this is returned will not be<br />
truncated.<br />
Action:<br />
To overcome this problem, examine the use of the data. This could fall into one of<br />
many categories:<br />
■<br />
■<br />
■<br />
■<br />
Never searched or compared.<br />
In this case the warning could be ignored, or even better to save space and<br />
speed up operations mark the attribute as not searchable<br />
Searched only by a begins with filter item.<br />
If the filter items are less than the 106 byte searchable limit then the warning<br />
can be ignored.<br />
Searched only by an ends in filter item.<br />
Consider adding a reverse index for the item.<br />
Other searches.<br />
Consider adding a wide index for this attribute. This does decrease<br />
performance, but it also increases the searchable limit to 1900 bytes. If this is<br />
still too small then a subsearch overflow message will be reported.<br />
rs_rsp: Credit limit reached<br />
Reason:<br />
This message means that a DAP or DSP client has exceeded the number of<br />
credits configured for that connection, and flow-control has been invoked. This is<br />
not an error, merely and informative message.<br />
In the case where all clients are using LDAP, then this message means that a DSP<br />
backbone link from another DSA has exceeded the value of "max-dsp-credits".<br />
DIP: time limit exceeded<br />
This message only applies to search operations and means that the search has<br />
taken longer than the configured op time limit, or the requested time limit in the<br />
search controls.<br />
Messages and Logs C–15
Alias Errors<br />
WARNING: ssld_ssl_request failed – certificate error?<br />
Reason:<br />
This message means that there was an error with a certificate. This error will<br />
appear with “-debug 0” is set. Setting debug level to 5 or 9 should help to find<br />
the actual problem.<br />
This could be due to:<br />
■<br />
■<br />
■<br />
■<br />
Invalid or expired DSA personality<br />
Invalid or expired root certificate<br />
Invalid client certificate<br />
An error with the client application<br />
This warning may also occur when an LDAP client disconnects an SSL<br />
connection. When an SSL connection is set up between a client and server the<br />
two ssl daemons perform a handshake process to determine the encryption<br />
cypher that will be used. When a server receives an unbind request then the<br />
SSLD daemons perform another handshake operation to close the ssl session.<br />
However, some LDAP clients perform a "close connection" rather than an<br />
unbind. If this occurs then the server SSLD cannot send its close SSL session<br />
request to the client as the connection between the client and the server has<br />
already been closed. In this case the above warning will be produced.<br />
This warning can occur even if the connection is only using SSL encryption (no<br />
certificates involved). The certificate error is only an indication of the possible<br />
error.<br />
Alias Errors<br />
Aliases are a powerful mechanism for alternate naming. However, when you do<br />
not use them properly, the result can be inconsistent DITs and degraded<br />
performance.<br />
Managing aliases properly is an application design issue. When you disable alias<br />
integrity, the DSA does not prevent the creation of aliases to nonexistent objects.<br />
It detects and reports invalid aliases only when it encounters them.<br />
You should enable alias integrity. This prevents the creation of dangling aliases—<br />
that is, aliases that point to no object entry.<br />
See The <strong>Directory</strong> Information Base in the chapter “General Administration” for<br />
more information about DIB commands.<br />
C–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Service Errors<br />
Service Errors<br />
In rare circumstances, the DSA may find an inconsistency that is outside the<br />
X.500 standard (for example, corrupt database tables). In this case, an X.500 error<br />
is returned with a message sent to the console, as shown below:<br />
Service Error: <strong>Directory</strong> unwilling to perform<br />
If such a situation arises, contact Computer Associates Technical Support at<br />
http://supportconnect.ca.com.<br />
Advantage Ingres Errors<br />
DXserver relies heavily on Advantage Ingres for database integrity and<br />
processing. Usually, appropriate Advantage Ingres error codes will accompany<br />
any database problems.<br />
An example of the syntax of the Advantage Ingres errors reported by DXserver is<br />
as follows:<br />
DSA: DIB-001: Can't logon to database 'temp'<br />
E_US0010 Database does not exist<br />
The first line is a general error message produced by DXserver. The second line is<br />
the Advantage Ingres error. (See the appropriate Advantage Ingres<br />
documentation for details.)<br />
If an Advantage Ingres error occurs, then more detail can be obtained from the<br />
Advantage Ingres error log.<br />
In an extreme case, a database can be corrupted. You can usually correct this by<br />
restoring a backup and, if journaling was enabled, rolling forward all changes<br />
that occurred after the backup. If this is not possible or the situation still exists,<br />
you can use a number of other Advantage Ingres tools with the help of <strong>CA</strong><br />
Technical Support.<br />
Some possible errors with their solutions are:<br />
E_LQ0001 Failed to connect to DBMS session<br />
Action:<br />
Determine whether Advantage Ingres is running (for example, use the UNIX<br />
command ps).<br />
Messages and Logs C–17
Advantage Ingres Errors<br />
E_US000C You are not a valid Ingres user<br />
Action:<br />
As the UNIX user ingres (the Advantage Ingres superuser account) run accessdb,<br />
and authorize UNIX user dsa to use the database.<br />
E_US0DAE SELECT on table dit: no GRANT permission<br />
Action:<br />
Run the DSA from the UNIX user account dsa.<br />
E_US0028 Could not open the iidbdb database<br />
Action:<br />
Check that you installed Advantage Ingres by running the Advantage Ingres<br />
command ingbuild.<br />
C–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Appendix<br />
D<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for<br />
Windows<br />
This appendix explains how to install <strong>eTrust</strong> <strong>Directory</strong> for Windows systems.<br />
Note: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–1
Installation Overview<br />
Installation Overview<br />
The <strong>eTrust</strong> <strong>Directory</strong> setup programs automate the installation processes. These<br />
programs check which <strong>eTrust</strong> <strong>Directory</strong> components are installed and up-todate,<br />
and either install or upgrade those components that are missing or old.<br />
To install <strong>eTrust</strong> <strong>Directory</strong>, perform the following activities:<br />
1. Check the system and disk requirements.<br />
2. Install or upgrade the directory components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
3. (Optional) Install or upgrade the web components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
4. (Optional) Run the sample scripts to install the three sample directories, the<br />
technology previews, and the sample tools.<br />
<strong>eTrust</strong> <strong>Directory</strong> Components<br />
The <strong>eTrust</strong> <strong>Directory</strong> installation is split into the following two sections, which<br />
you can install separately or on the same computer:<br />
■<br />
<strong>Directory</strong>—The main <strong>eTrust</strong> <strong>Directory</strong> installation, which includes the<br />
following modules:<br />
- DXserver—The <strong>eTrust</strong> <strong>Directory</strong> server, DXtools, and DXconsole<br />
- Ingres—A <strong>CA</strong> open-source database, which is required by DXserver if<br />
the data repository is used<br />
- JXplorer—An LDAP client that lets you browse and update a directory<br />
- Documentation—PDF product manuals<br />
- Samples—Sample DSAs and sample tools for working with DXserver<br />
■<br />
Web Components—Optional web-based modules, including the following<br />
modules:<br />
- DXmanager—A web-based tool for monitoring and administration<br />
- JXweb—A web-based LDAP client that lets you browse a directory<br />
- UDDI Server—A UDDI repository that functions as a business directory.<br />
The UDDI Server requires DXserver.<br />
- UDDI Client—A web-based browser for the UDDI Server<br />
- Samples—Sample web applications, including a DSML server, a SAML<br />
server, and a UDDI demonstration.<br />
D–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Installation Overview<br />
Default Installation Locations<br />
By default, the <strong>eTrust</strong> <strong>Directory</strong> components are installed into the directories<br />
listed in the following table. You can change these locations in a custom<br />
installation.<br />
Component<br />
DXserver<br />
Advantage Ingres<br />
JXplorer<br />
DXwebserver<br />
Documentation<br />
DXconsole<br />
Sample Directories and<br />
Sample Tools<br />
Sample Web<br />
Applications<br />
Default <strong>Directory</strong><br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxserver<br />
C:\Program Files\<strong>CA</strong>\Advantage Ingres [ET]\ingres<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\jxplorer<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxwebserver<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\documentation<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\ttermpro<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\samples<br />
C:\Program Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxwebserver\samples<br />
The %DXHOME% Location<br />
Throughout this guide, %DXHOME% refers to the location in which DXserver is<br />
installed on your computer. This location is set in the DXHOME environment<br />
variable.<br />
For example, in a default installation, %DXHOME% is C:\Program<br />
Files\<strong>CA</strong>\<strong>eTrust</strong> <strong>Directory</strong>\dxserver.<br />
Installation Logging<br />
All installations are logged.<br />
If the DXHOME environment variable is defined, the installation log file is<br />
created in %DXHOME%. If DXHOME is not defined, the installation log is<br />
created in %TEMP%.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–3
Installation Overview<br />
Upgrade <strong>eTrust</strong> <strong>Directory</strong><br />
If you have the enterprise version of <strong>eTrust</strong> <strong>Directory</strong>, you can upgrade this by<br />
following the installation instructions in this chapter.<br />
If you are using a version of <strong>eTrust</strong> <strong>Directory</strong> that is embedded in another<br />
product, you must use the upgrade package from the embedding product.<br />
Each embedding product that installs <strong>eTrust</strong> <strong>Directory</strong> has a specific process for<br />
upgrading <strong>eTrust</strong> <strong>Directory</strong> and if this is not followed, the products will not<br />
work as intended.<br />
For example, if you use <strong>eTrust</strong> SSO and the embedded version of <strong>eTrust</strong><br />
<strong>Directory</strong> that comes with it, you must use an <strong>eTrust</strong> SSO package to upgrade<br />
both products.<br />
Upgrade Advantage Ingres<br />
For a new installation, <strong>eTrust</strong> <strong>Directory</strong> embeds the single-byte version of<br />
Advantage Ingres II 2.6 SP2, with the installation code ET. The installation<br />
performs a standard tuning of the database parameters. You can customize these<br />
parameters.<br />
For an upgrade to an existing configuration, check the Readme to find out how<br />
<strong>eTrust</strong> <strong>Directory</strong> works with the various versions of Advantage Ingres.<br />
If you currently use Advantage Ingres 2.0 or 2.5, check with Computer<br />
Associates’ Technical Support to find out whether the applications that use your<br />
existing version of Advantage Ingres also support Advantage Ingres 2.6.<br />
<strong>eTrust</strong> <strong>Directory</strong> ships with a default configuration of 64 database connections.<br />
However, if you are upgrading from a previous version of <strong>eTrust</strong> <strong>Directory</strong>, the<br />
previous limit of 32 connections applies.<br />
If you plan to have many data DSAs running on the same machine, read the<br />
section Increasing the Number of Database Connections in the appendix<br />
“Tailoring the RDBMS”.<br />
D–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Installation Overview<br />
Embedded <strong>eTrust</strong> Identity and Access Management<br />
The <strong>eTrust</strong> <strong>Directory</strong> Web Components installation includes an embedded<br />
version of <strong>eTrust</strong> Identity and Access Management. This is a security module<br />
that DXmanager uses to make sure that your directory system is protected.<br />
If you install DXmanager, you will have to enter details about how the<br />
embedded <strong>eTrust</strong> Identity and Access Management module will work.<br />
The installation gives you four options for installing the module:<br />
■<br />
■<br />
■<br />
■<br />
Install new local eIAM Server—Installs a new eIAM Server on the same<br />
computer as DXmanager. You will have to supply a password for the user<br />
EiamAdmin.<br />
Install new local eIAM Server with an external user store—You will be<br />
prompted to close the installation program, and go back to the Product<br />
Explorer, where you should install eIAM from the Supporting Products<br />
section.<br />
You might choose this option if you want to reference another user store, or<br />
if you want to install the eIAM server on another computer.<br />
Reference existing local eIAM Server—Lets you reference an existing<br />
installed eIAM Server on the local computer. You will have to supply a<br />
password for the user EiamAdmin.<br />
Reference existing remote eIAM Server—Lets you reference an existing<br />
eIAM server on a remote computer. You will have to supply a password for<br />
the user EiamAdmin.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–5
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
This section describes how to install <strong>eTrust</strong> <strong>Directory</strong> and the <strong>eTrust</strong> <strong>Directory</strong><br />
Web Components using the Product Explorer.<br />
Step 1. Check System and Disk Requirements<br />
This section lists the checks you should make before you install <strong>eTrust</strong> <strong>Directory</strong>.<br />
Check the System Requirements<br />
Check the Readme for system requirements.<br />
The disk space required for directory information is approximately 20 times the<br />
raw data size. This provides space for backups, journals, indexing, tuning,<br />
import, and preprocessing.<br />
Back Up Data<br />
If you are upgrading from an earlier version, back up your schema files.<br />
Design the Disk Configuration<br />
To improve recovery and performance, you should store the database<br />
information on a separate physical disk from the product files. Be sure that the<br />
drives you choose are actually on separate physical disks. Do not use a single<br />
physical disk partitioned into multiple drives.<br />
In the following example of the layout of a typical installation, the C and D<br />
drives are on separate physical disks:<br />
The C drive<br />
<strong>eTrust</strong> <strong>Directory</strong> product files<br />
Advantage Ingres product files<br />
Advantage Ingres transaction log<br />
The D drive<br />
<strong>Directory</strong> information (database files)<br />
Advantage Ingres checkpoints (database backups)<br />
Advantage Ingres journals<br />
Advantage Ingres work area<br />
In Windows Explorer, partitions local to the computer have Local Disk in the<br />
Type column. You can configure and view logical and physical drives using the<br />
Windows Disk <strong>Administrator</strong>.<br />
For more information about disk configurations such as mirrored disks and RAID,<br />
contact Computer Associates Technical Support at http://supportconnect.ca.com.<br />
D–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
Step 2. Install <strong>eTrust</strong> <strong>Directory</strong><br />
To install <strong>eTrust</strong> <strong>Directory</strong>:<br />
1. Stop all applications that may have current open connections to an<br />
Advantage Ingres database.<br />
2. Log in as a user with administrator privileges.<br />
3. Insert the <strong>eTrust</strong> <strong>Directory</strong> CD. The Product Explorer starts automatically.<br />
If the Product Explorer does not start automatically, double-click on<br />
PE_i386.exe in the top-level directory of the CD.<br />
4. If you plan to use JXplorer, install JRE from the Supporting Products list.<br />
5. Navigate to <strong>Directory</strong> for Windows and click Install.<br />
6. To install <strong>eTrust</strong> <strong>Directory</strong> now, select the option Install <strong>eTrust</strong> <strong>Directory</strong>.<br />
To create a response file that can be used to install <strong>eTrust</strong> <strong>Directory</strong> silently<br />
on many computers, select the option Build response file for unattended<br />
installation. For information about response files, see the section Install<br />
Silently Using Response File.<br />
7. Follow the instructions on the installation screens until you come to the<br />
Setup Type screen.<br />
To install DXserver, Ingres, JXplorer and the documentation in their default<br />
locations, select Complete and click Next, then skip to step 9.<br />
To choose which components to install, choose Custom Setup and click Next.<br />
8. Select options for the components you are installing.<br />
If you are an advanced user, you can click the Options button to configure<br />
some aspects of Advantage Ingres. For more information, see the section<br />
Upgrade Advantage Ingres.<br />
9. When you have selected the components and selected the appropriate<br />
options, the Setup wizard displays a message telling you that it is ready to<br />
install the selected files.<br />
Use the Back button to review your selections before finalizing the<br />
installation.<br />
10. When the installation is complete, the Advantage Ingres Intelligent Database<br />
service starts automatically, and the sample scripts run if you selected this<br />
option. The samples are run in a default installation, but not in a default<br />
upgrade from a previous <strong>eTrust</strong> <strong>Directory</strong> version.<br />
You do not have to reboot the computer after installation.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–7
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
Step 3. (Optional) Install <strong>eTrust</strong> <strong>Directory</strong> Web Components<br />
You can install the web components of <strong>eTrust</strong> <strong>Directory</strong> on a different computer<br />
from the main directory components.<br />
To install <strong>eTrust</strong> <strong>Directory</strong> Web Components:<br />
1. Log in as a user with administrator privileges.<br />
2. Insert the <strong>eTrust</strong> <strong>Directory</strong> CD. The Product Explorer starts automatically.<br />
If the Product Explorer does not start automatically, double-click on<br />
PE_i386.exe in the top-level directory of the CD.<br />
3. If Java Runtime Environment is not already installed, install it from the<br />
Supporting Products list.<br />
4. If you plan to use the UDDI Server, make sure that the directory component<br />
is already installed.<br />
5. Navigate to the section <strong>eTrust</strong> <strong>Directory</strong> Web Components, and click on the<br />
Windows option.<br />
6. To install the web components now, click the select the option Install <strong>eTrust</strong><br />
<strong>Directory</strong> Web Components Now.<br />
To create a response file that can be used to install <strong>eTrust</strong> <strong>Directory</strong> Web<br />
Components silently on many computers, select the option Build response<br />
file for unattended installation. For information about creating and using<br />
response files, see the section Install Silently Using Response File.<br />
7. Continue to follow the instructions on the installation screens.<br />
8. Select options for the components you are installing.<br />
9. When you have selected the components and selected the appropriate<br />
options, the Setup wizard displays a message telling you that it is ready to<br />
install the selected files.<br />
Use the Back button to review your selections before finalizing the installation.<br />
D–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
Step 4. (Optional) Install the Samples and Technology Previews<br />
<strong>eTrust</strong> <strong>Directory</strong> comes with sample directories, technology previews, and tools.<br />
Install the Sample Directories<br />
You can only set up the sample directories if you have installed the directory<br />
components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
In a default installation of the directory components, these samples are installed<br />
but not set up. You need to install each sample you want to work with.<br />
The schema used by the Democorp sample has changed since <strong>eTrust</strong> <strong>Directory</strong><br />
3.6 SP2. You should reinstall the samples by running the setup script in the<br />
Router, Democorp, and UNSPSC directories.<br />
Important! If you run these scripts, any existing data in the Democorp and UNSPSC<br />
databases will be lost.<br />
To set up the sample directories:<br />
1. Log in as the DXserver administrator.<br />
2. Open Windows Explorer, and navigate to the %DXHOME%\samples\democorp<br />
directory.<br />
3. Run setup.bat.<br />
4. Navigate to the %DXHOME%\samples\unspsc directory.<br />
5. Run setup.bat.<br />
6. Navigate to the %DXHOME%\samples\router directory.<br />
7. Run setup.bat.<br />
Install the Sample Tools<br />
<strong>eTrust</strong> <strong>Directory</strong> includes ten sample tools that you can use to work with your<br />
DSAs.<br />
You can only set up the sample tools if you have installed the directory<br />
components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
In a default installation of the directory components, these samples are installed<br />
but not set up. You need to install each sample you want to work with.<br />
■<br />
To install each of these sample tools, run the scripts in the directories under<br />
the directory %DXHOME%\samples.<br />
For more information, see the chapter “Samples”, and the Readme in each of the<br />
samples sub-directories.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–9
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Product Explorer<br />
Install the Technology Previews<br />
You can only set up the technology previews if you have installed the web<br />
components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
In a default installation of the web components, these previews are installed but<br />
not set up. You need to install each preview you want to work with.<br />
These technology previews are not covered by your usual <strong>CA</strong> Support. However,<br />
your feedback is very welcome. Please see the Readme files in each sample<br />
directory for how to let us know about your comments or questions.<br />
For more information, see the chapter “Samples”.<br />
To install the Democorp version of JXweb:<br />
1. Navigate to \dxwebserver\samples\democorp.<br />
2. Run setup.bat.<br />
To install the UDDI demonstration:<br />
1. Navigate to \dxwebserver\samples\uddi\uddiv3-demo .<br />
2. Run setup.bat.<br />
To install the DSML server technology preview:<br />
1. Navigate to \dxwebserver\samples\dsml.<br />
2. Run setup.bat.<br />
D–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
You can install <strong>eTrust</strong> <strong>Directory</strong> and <strong>eTrust</strong> <strong>Directory</strong> Web Components using<br />
the commands dxsetup and dxwebsetup.<br />
The dxsetup Command<br />
You can use the dxsetup command to install the main directory components.<br />
dxsetup [-write_responses filepath/filename] [ADDLO<strong>CA</strong>L=value] [option-value]<br />
where:<br />
■<br />
■<br />
-write_responses creates a response file<br />
the values and arguments are any of the following:<br />
ADDLO<strong>CA</strong>L Value Description<br />
ALL<br />
Installs all components<br />
<strong>CA</strong>_LICENSE Installs the <strong>CA</strong> license. Must be added with DXserver and Advantage Ingres<br />
DXServer<br />
Installs DXserver, must also use <strong>CA</strong>_LICENSE<br />
ETRDocumentation Installs the <strong>eTrust</strong> <strong>Directory</strong> documentation<br />
IngresDBMS,IngresNet Installs Ingres 2.6 with the installation code ET<br />
JXplorer Installs JXplorer (requires JRE 1.4.2)<br />
TeraTerm<br />
Installs DXconsole, which traces DXserver<br />
Option Value Description<br />
ETRDIR_DXSERVER_SAMPLES 1 DXserver samples will be set up during installation.<br />
ETRDIR_SHORTCUTS 1 All start menu shortcut are installed (default).<br />
ETRDIR_SILENT_INSTALL 1 No prompts are displayed, and an installation log is<br />
created in ..\%DXHOME%.<br />
ETRDIRBASEPATH path The location for the whole installation.<br />
ETRDIR_DOCO_DESTINATION path The <strong>eTrust</strong> <strong>Directory</strong> documentation location.<br />
ETRDIR_DXSERVER_DESTINATION path The DXserver location.<br />
ETRDIR_JXPLORER_DESTINATION path The JXplorer location.<br />
ETRDIR_TERATERM_DESTINATION path The DXconsole location.<br />
ETRDIR_BASIC_UI_INSTALL 1 A small progress bar appears during installation.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–11
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
Option Value Description<br />
INGRES_DESTINATION path The location for the whole Ingres installation.<br />
INGRES_CKPDIR path The Ingres check point location.<br />
INGRES_DATADIR path The Ingres data location.<br />
INGRES_DMPDIR path The Ingres dump location.<br />
INGRES_JNLDIR path The Ingres journal location.<br />
INGRES_PRIMLOGDIR path The Ingres primary log file location.<br />
INGRES_WORKDIR path The Ingres work location.<br />
INGRES_LOGFILESIZE<br />
size (MB) The size of the Ingres log file. Default: 64 MB.<br />
The dxwebsetup Command<br />
You can use the dxwebsetup command to install the web components of <strong>eTrust</strong><br />
<strong>Directory</strong>.<br />
dxwebsetup [-write_responses filepath/filename] [ADDLO<strong>CA</strong>L=value] [option-value]<br />
where:<br />
■<br />
■<br />
-write_responses creates a response file<br />
the values and arguments are any of the following:<br />
ADDLO<strong>CA</strong>L Value<br />
Description<br />
ALL<br />
Installs all components<br />
DXmanager<br />
Installs DXmanager, a DXserver management tool (requires DXwebserver)<br />
DXwebservers Installs the Tomcat web server (requires JRE 1.4.2).<br />
JXweb<br />
Installs JXweb (requires DXwebserver)<br />
Uddi<br />
Installs the UDDI Server (requires DXServer, IngresDBMS and DXwebserver)<br />
UddiClient<br />
Installs the UDDI Client (requires DXwebserver)<br />
Option Value Description<br />
ETRDIR_DXWEBSERVER_DESTINATION path The DXwebserver location.<br />
ETRDIR_SILENT_INSTALL 1 No prompts are displayed, and an installation log<br />
is created in ..\%DXHOME%.<br />
ETRDIR_BASIC_UI_INSTALL 1 A small progress bar appears during installation.<br />
D–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
Limit on Number of Characters in the Commands<br />
The Windows command line may limit the number of characters in a single<br />
command. This could be a problem if you want to set the installation<br />
destinations for many <strong>eTrust</strong> <strong>Directory</strong> components.<br />
To avoid using a very long command, use the ETRDIRBASEPATH argument to<br />
set the location for the entire installation, instead of setting the location of each<br />
component separately.<br />
Example Commands<br />
The following sections show some example commands.<br />
Install All<br />
Components Except<br />
Samples<br />
To install <strong>eTrust</strong> <strong>Directory</strong> with all components except the samples, run the<br />
following command:<br />
dxsetup ADDLO<strong>CA</strong>L=ALL ETRDIR_DXSERVER_SAMPLES=0<br />
Install DXmanager<br />
only<br />
To install only DXmanager, you must also install DXwebserver. To install them<br />
to to the default location, run the following command:<br />
dxwebsetup ADDLO<strong>CA</strong>L=DXwebServers,DXmanager<br />
Install DXserver,<br />
Ingres, and <strong>CA</strong><br />
Licensing only<br />
To install DXserver, Advantage Ingres 2.6 [ET] and <strong>CA</strong> licensing to the default<br />
location, run the following command:<br />
dxsetup ADDLO<strong>CA</strong>L=DXServer,IngresDBMS,IngresNet,<strong>CA</strong>_LICENSE<br />
ETRDIR_DXSERVER_SAMPLES=1<br />
Install JXplorer only<br />
To install only JXplorer to the specified installation directory, run the following<br />
command:<br />
dxsetup ADDLO<strong>CA</strong>L=JXplorer ETRDIR_JXPLORER_DESTINATION=f:\Mynewdirectory\jxplorer<br />
File Path that Includes<br />
Spaces<br />
If a file path includes spaces, surround the path with quotes. For example:<br />
dxsetup ADDLO<strong>CA</strong>L=JXplorer ETRDIR_JXPLORER_DESTINATION=”f:\My directory\jxplorer”<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–13
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
You can install <strong>eTrust</strong> <strong>Directory</strong> silently (or unattended). This means that no user<br />
input is required during the installation process, and no feedback from the<br />
installation process appears on the screen.<br />
To install <strong>eTrust</strong> <strong>Directory</strong> silently, you need to provide the information that<br />
would normally be supplied by the user during installation in one of the<br />
following two ways:<br />
■<br />
■<br />
As options with the dxsetup command<br />
In a response file<br />
If you plan to silently install JXplorer or any of the web components, Make sure<br />
that the correct version of the Java Runtime Environment has been installed.<br />
Install Silently Using Commands<br />
To silently install the main directory components of <strong>eTrust</strong> <strong>Directory</strong>, use the<br />
following command:<br />
dxsetup ETRDIR_SILENT_INSTALL=1 [ADDLO<strong>CA</strong>L=values]<br />
To silently install the web components of <strong>eTrust</strong> <strong>Directory</strong>, use the following<br />
command:<br />
dxwebsetup ETRDIR_SILENT_INSTALL=1 [ADDLO<strong>CA</strong>L=values]<br />
See the section Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands for descriptions of the<br />
command options.<br />
Example: Silently<br />
Install Using the<br />
dxsetup Command<br />
Example: Silently<br />
Install UDDI Server<br />
Only<br />
To silently install <strong>eTrust</strong> <strong>Directory</strong> with all components except the samples, run<br />
the following command from …\CD ROM drive\dxserver\windows:<br />
dxsetup ETRDIR_SILENT_INSTALL=1 ADDLO<strong>CA</strong>L=ALL ETRDIR_DXSERVER_SAMPLES=0<br />
To silently install UDDI Server only, run the following command from …\CD<br />
ROM drive\dxserver\windows:<br />
dxwebsetup ETRDIR_SILENT_INSTALL=1 ADDLO<strong>CA</strong>L=Uddi,DXwebservers<br />
D–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Install Silently Using Response Files<br />
The response file is a text file that supplies the arguments to be used during the<br />
installation process. This input would usually be supplied by the user as they<br />
install <strong>eTrust</strong> <strong>Directory</strong> or <strong>eTrust</strong> <strong>Directory</strong> Web Components.<br />
A response file must contain data that you cannot create using a text editor. To<br />
create a new response file, you must use the Product Explorer on the CD<br />
Create a Response File<br />
To create a response file, follow these steps:<br />
1. On a computer that does not have <strong>eTrust</strong> <strong>Directory</strong> installed on it, log in as a<br />
user with administrator privileges.<br />
2. Insert the <strong>eTrust</strong> <strong>Directory</strong> CD. The Product Explorer starts automatically.<br />
If the Product Explorer does not start automatically, double-click on<br />
PE_i386.exe in the top-level directory of the CD.<br />
3. To create a response file for the directory components, navigate to <strong>Directory</strong><br />
for Windows and click Install.<br />
To create a response file for the web components, navigate to Web<br />
Components for Windows and click Install.<br />
4. Select the option Build response file for unattended installation, then click Next.<br />
5. If you accept the terms of the license agreement, scroll to the bottom of the<br />
license agreement, then click I Agree.<br />
6. In the Response File Installation Options page, set the following options:<br />
- The location of the response file.<br />
- The name of the response file. This file can have any extension.<br />
- The level of feedback to be given during installation.<br />
The option Small progress bar makes a bar appear during installations<br />
that are controlled by this response file.<br />
The option No dialogs makes the installation truly silent.<br />
6. Continue the installation as you would for a direct installation.<br />
7. When you have selected the components and selected the appropriate<br />
options, the Setup wizard displays a message that it is ready to create the<br />
response file.<br />
Use the Back button to review your selections before creating the response file.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–15
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Install Using Response Files<br />
To use a response file to install the main directory components, use the following<br />
command:<br />
dxsetup -responsefile filepath\filename<br />
To use a response file to install web components, use the following command:<br />
dxwebsetup -responsefile filepath\filename<br />
where:<br />
■<br />
■<br />
-responsefile sets the installation to use a response file<br />
filepath/filename is the path to the response file you created<br />
D–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
<strong>eTrust</strong> <strong>Directory</strong> can be installed as an embedded product so that other <strong>CA</strong><br />
products can use its features in their product.<br />
The information that the user would usually supply during the installation<br />
process are supplied as options with the dxsetup command.<br />
How Installation Codes Work<br />
Only one product can use a particular installation code. They must also never<br />
change this installation code. Each installation code is recorded, so as not to<br />
affect any other instances of <strong>eTrust</strong> <strong>Directory</strong>. They must also use this installation<br />
code to uninstall <strong>eTrust</strong> <strong>Directory</strong>.<br />
This means that other <strong>CA</strong> products can install <strong>eTrust</strong> <strong>Directory</strong> using their own unique<br />
installation code. Then, if <strong>eTrust</strong> <strong>Directory</strong> needs to be removed, the customer can<br />
remove it without removing anything that the embedding product requires.<br />
As with silent installation, you can put the embedded and installation code<br />
commands on the one command line.<br />
To find out which installation codes are supported, contact <strong>CA</strong> Support.<br />
Install <strong>eTrust</strong> <strong>Directory</strong> as an Embedded Module<br />
To install the main directory components as an embedded module, use the<br />
following command:<br />
dxsetup ETRDIR_DXSERVER_EMBEDDED=1 <strong>CA</strong>LLER_ID=callerID [ADDLO<strong>CA</strong>L=values [arguments]<br />
]<br />
where:<br />
■<br />
■<br />
ETRDIR_DXSERVER_EMBEDDED=1 specifies that this is an embedded<br />
installation<br />
<strong>CA</strong>LLER_ID callerID uniquely identifies the embedding customer.<br />
To install the web components as an embedded module, use the following<br />
command:<br />
dxwebsetup ETRDIR_DXWEBSERVER_EMBEDDED=1 <strong>CA</strong>LLER_ID=callerID [ADDLO<strong>CA</strong>L=values<br />
[arguments] ]<br />
where:<br />
■<br />
■<br />
ETRDIR_DXSERVER_EMBEDDED=1 specifies that this is an embedded<br />
installation<br />
<strong>CA</strong>LLER_ID callerID uniquely identifies the embedding customer.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–17
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
Uninstall <strong>eTrust</strong> <strong>Directory</strong> After an Embedded Installation<br />
The installation code must be used to uninstall <strong>eTrust</strong> <strong>Directory</strong>.<br />
The uninstallation process determines if no more products require <strong>eTrust</strong><br />
<strong>Directory</strong> and remove the product accordingly. If other products are using <strong>eTrust</strong><br />
<strong>Directory</strong> then the uninstall will remove only the reference counter for that caller,<br />
and not the <strong>eTrust</strong> <strong>Directory</strong> components used by the other callers.<br />
Example: Install and<br />
Uninstall the <strong>Directory</strong><br />
Components within<br />
<strong>eTrust</strong> Web Access<br />
Control<br />
The following command installs embedded <strong>eTrust</strong> <strong>Directory</strong> silently as part of<br />
the product <strong>eTrust</strong> Web Access Control:<br />
dxsetup ADDLO<strong>CA</strong>L=ALL ETRDIR_DXSERVER_EMBEDDED=1 ETRDIR_SILENT_INSTALL=1<br />
<strong>CA</strong>LLER_ID=ETWAC<br />
To silently uninstall embedded <strong>eTrust</strong> <strong>Directory</strong> as ETWAC:<br />
dxsetup REMOVE=ALL ETRDIR_DXSERVER_EMBEDDED=1 ETRDIR_SILENT_INSTALL=1<br />
<strong>CA</strong>LLER_ID=ETWAC<br />
D–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Troubleshooting<br />
Troubleshooting<br />
Error 267 or Error 1606<br />
Reason:<br />
These errors occur when there are some inconsistencies with the Windows<br />
Installer DLL.<br />
This usually occurs because a reboot was not performed when Windows Installer<br />
was upgraded. This problem can also occur when you are upgrading from <strong>eTrust</strong><br />
<strong>Directory</strong> 3.6.<br />
Action:<br />
To prevent this problem from occurring or to fix this error if it has already<br />
happened, use the <strong>eTrust</strong> <strong>Directory</strong> Cleanup tool, which is located under<br />
Unsupported on the <strong>eTrust</strong> <strong>Directory</strong> installation CD. To run this tool, use the<br />
following command:<br />
CleanReg.exe -fixup267<br />
Error 1605 Could not retrieve Version String<br />
Reason:<br />
This error appears when the registry has rogue entries under the Windows<br />
Installer areas. These are usually from an aborted uninstall, or a failed uninstall.<br />
Action:<br />
Use the <strong>eTrust</strong> <strong>Directory</strong> Cleanup tool, which is located under Unsupported on<br />
the <strong>eTrust</strong> <strong>Directory</strong> installation CD. To run this tool, use this command:<br />
CleanReg.exe -all<br />
Error 1639 Invalid Command Line Argument<br />
Reason:<br />
This error can occur when you install <strong>eTrust</strong> <strong>Directory</strong> using commands.<br />
Action:<br />
If you receive this error, check the following:<br />
■ All arguments must be in the form of =. i.e ETRDIR_SILENT_INSTALL=1<br />
■ All characters A-Z from the PROPERTY must be uppercase.<br />
■ All paths specified in the VALUE must have quotes if they contain spaces.<br />
For example, FOLDER="c:\Program Files\<strong>CA</strong>"<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–19
Troubleshooting<br />
Can’t Connect to <strong>eTrust</strong> <strong>Directory</strong> from Remote Computer (Windows XP SP2)<br />
After you install Windows XP SP2, you may not be able to connect to <strong>eTrust</strong><br />
<strong>Directory</strong> from another computer.<br />
Reason:<br />
This is because the firewall is on by default. If you disable the firewall then you<br />
do not need to configure anything (all ports are open).<br />
Action:<br />
If the Windows XP firewall is on, follow these steps to enable a program by using<br />
this firewall:<br />
1. Open Control Panel.<br />
2. Click Windows Firewall.<br />
3. In the Windows Firewall dialog box, click the Exceptions tab, and then click<br />
Add Program.<br />
4. In the Add a Program dialog box, click Browse to locate dxserver.exe. (This<br />
will open all the ports that <strong>eTrust</strong> <strong>Directory</strong> uses)<br />
5. After you select the program, click OK.<br />
6. On the Exceptions tab, make sure that the checkbox next to dxserver.exe is<br />
selected, and then click OK.<br />
If you later decide that you do not want the program to be an exception, clear<br />
this check box.<br />
If you cannot identify the ports that are used by the program, you can open a<br />
port manually. To manually open a port, follow these steps:<br />
1. Open Control Panel<br />
2. Click Windows Firewall.<br />
3. On the Exceptions tab, click Add Port.<br />
4. In the Add a Port dialog box, type the number of the port that you want to<br />
open in the Port Number box. For example, type 2123 for DXadmind, and<br />
then click TCP.<br />
5. Type a name for the port, and then click OK. For example, type DXadmind.<br />
6. On the Exceptions tab, notice that the new service is listed. To enable the<br />
port, click to select the check box next to the service, and then click OK<br />
To only allow connections to a specific DSA and block all the DSAs on the<br />
computer:<br />
1. Do not add dxserver.exe to the exception list.<br />
2. Add the port number for that specific DSA. For example, add port number<br />
19389 for access to the Democorp DSA only.<br />
D–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Troubleshooting<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for Windows D–21
Appendix<br />
E<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX<br />
This appendix explains how to install <strong>eTrust</strong> <strong>Directory</strong> for UNIX and Linux<br />
systems.<br />
Note: Throughout this guide, references to Advantage Ingres include both<br />
Ingres II and OpenIngres, unless one or the other is explicitly specified.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–1
Installation Overview<br />
Installation Overview<br />
The <strong>eTrust</strong> <strong>Directory</strong> setup programs automate the installation processes. These<br />
programs check which <strong>eTrust</strong> <strong>Directory</strong> components are installed and up-todate,<br />
and either install or upgrade those components that are missing or old.<br />
To install <strong>eTrust</strong> <strong>Directory</strong>, perform the following activities:<br />
1. Check the system and disk requirements.<br />
2. Install or upgrade the directory components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
3. (Optional) Install or upgrade the web components of <strong>eTrust</strong> <strong>Directory</strong>.<br />
4. (Optional) Run the sample scripts to install the three sample directories, the<br />
technology previews, and the sample tools.<br />
<strong>eTrust</strong> <strong>Directory</strong> Components<br />
The <strong>eTrust</strong> <strong>Directory</strong> installation is split into the following two sections, which<br />
you can install separately or on the same computer:<br />
■<br />
The dxsetup program—The main <strong>eTrust</strong> <strong>Directory</strong> installation, which<br />
includes the following modules:<br />
- DXserver—The <strong>eTrust</strong> <strong>Directory</strong> server, DXtools, and DXconsole<br />
- Ingres—A <strong>CA</strong> open-source database, which is required by DXserver if<br />
the data repository is used<br />
- JXplorer—An LDAP client that lets you browse and update a directory<br />
- Documentation—PDF product manuals<br />
- Samples—Sample DSAs and sample tools for working with DXserver<br />
■<br />
The dxwebsetup program—Web-based modules, which can be installed on<br />
a different computer to the main directory installation. This includes the<br />
following modules:<br />
- DXmanager—A web-based tool for monitoring and administration<br />
- JXweb—A web-based LDAP client that lets you browse a directory<br />
- UDDI Server—A UDDI repository that functions as a business directory.<br />
- UDDI Client—A web-based browser for the UDDI Server<br />
- Samples—Sample web applications, including a DSML server, a SAML<br />
server, and a UDDI demonstration.<br />
E–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Installation Overview<br />
Default Installation Locations<br />
This table lists the locations into which the <strong>eTrust</strong> <strong>Directory</strong> components are<br />
installed in a default installation.<br />
Component<br />
DXserver<br />
Advantage Ingres<br />
JXplorer<br />
DXwebserver<br />
JRE<br />
Documentation<br />
Sample Directories and<br />
Sample Tools<br />
Sample Web<br />
Applications<br />
Default <strong>Directory</strong><br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxserver<br />
/opt/<strong>CA</strong>/AdvantageIngresET/ingres<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jxplorer<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxwebserver<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jre<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/documentation<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxserver/samples<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxwebserver/samples<br />
The $DXHOME Location<br />
Throughout this guide, $DXHOME refers to the location in which DXserver is<br />
installed on your computer. This location is set in the $DXHOME environment<br />
variable.<br />
For example, in a default installation, $DXHOME is<br />
/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxserver.<br />
Installation Logging<br />
All installations are logged.<br />
If DXHOME is defined, the installation log file is created in $DXHOME/.. . If<br />
DXHOME is not defined, the installation log is created in /tmp.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–3
Installation Overview<br />
Upgrade <strong>eTrust</strong> <strong>Directory</strong><br />
If you have the enterprise version of <strong>eTrust</strong> <strong>Directory</strong>, you can upgrade this by<br />
following the installation instructions in this chapter.<br />
If you are using a version of <strong>eTrust</strong> <strong>Directory</strong> that is embedded in another<br />
product, you must use the upgrade package from the embedding product.<br />
Each embedding product that installs <strong>eTrust</strong> <strong>Directory</strong> has a specific process for<br />
upgrading <strong>eTrust</strong> <strong>Directory</strong> and if this is not followed, the products will not<br />
work as intended.<br />
For example, if you use <strong>eTrust</strong> SSO and the embedded version of <strong>eTrust</strong><br />
<strong>Directory</strong> that comes with it, you must use an <strong>eTrust</strong> SSO package to upgrade<br />
both products.<br />
Upgrade Advantage Ingres<br />
For a new installation, <strong>eTrust</strong> <strong>Directory</strong> embeds the single-byte version of<br />
Advantage Ingres II 2.6 SP2, with the installation code ET. The Advantage Ingres<br />
RDBMS installation performs a standard tuning of the database parameters. You<br />
can customize these parameters.<br />
For an upgrade to an existing configuration, check the Readme to find out how<br />
<strong>eTrust</strong> <strong>Directory</strong> works with the various versions of Advantage Ingres.<br />
If you are currently running Advantage Ingres 2.0 or 2.5, check with Computer<br />
Associates’ Technical Support to find out whether the applications that use your<br />
existing version of Advantage Ingres also support Advantage Ingres 2.6.<br />
You may want to set the Advantage Ingres log folder to a different disk drive for<br />
improved performance.<br />
<strong>eTrust</strong> <strong>Directory</strong> ships with a default configuration of 64 database connections.<br />
However, if you are upgrading from a previous version of <strong>eTrust</strong> <strong>Directory</strong>, the<br />
previous limit of 32 connections applies.<br />
If you plan to have many data DSAs running on the same computer, read the<br />
section Increasing the Number of Database Connections in the appendix<br />
“Tailoring the RDBMS”.<br />
E–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Installation Overview<br />
User Accounts<br />
<strong>eTrust</strong> <strong>Directory</strong> requires two user accounts to be set up:<br />
■<br />
■<br />
dsa—An <strong>eTrust</strong> <strong>Directory</strong> administrator<br />
ingres—An Ingres administrator<br />
You can create these accounts manually before you install <strong>eTrust</strong> <strong>Directory</strong>, or<br />
you can let the installation program create them.<br />
If these accounts do not exist, the installation program will create them.<br />
■<br />
■<br />
During a normal interactive installation, you will be prompted to create<br />
passwords for these accounts.<br />
After a silent installation, the accounts will be created without passwords.<br />
You must manually assign passwords after the installation is complete.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–5
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
This section describes how to install <strong>eTrust</strong> <strong>Directory</strong> using the installation<br />
programs dxsetup and dxwebsetup.<br />
Step 1. Check System and Disk Requirements<br />
This section lists the checks you should make before you start installing <strong>eTrust</strong><br />
<strong>Directory</strong>.<br />
Check System Requirements<br />
Check the Readme for system requirements.<br />
The disk space required for directory information is approximately 20 times the<br />
raw data size. This provides space for backups, journals, indexing, tuning,<br />
import, and preprocessing.<br />
Back Up Data<br />
If you are upgrading from an earlier version of <strong>eTrust</strong> <strong>Directory</strong>, make sure you<br />
have adequate backups, including any changes to your schema files.<br />
Verify CD-ROM Accessibility<br />
Check that the CD-ROM is available.<br />
You can install <strong>eTrust</strong> <strong>Directory</strong> and Advantage Ingres from either a local CD-<br />
ROM drive, or a remote CD-ROM drive on the same network.<br />
Set Up User Permissions<br />
If you are installing <strong>eTrust</strong> <strong>Directory</strong> from a local disk, you must ensure that the<br />
parent directories have read and execute permissions for all users. This gives<br />
newly added users (including dsa and ingres, which are created during the <strong>eTrust</strong><br />
<strong>Directory</strong> installation) permissions to access the tar files.<br />
Note: You should never run DXserver as root.<br />
E–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Check the Kernel Settings (Solaris and HP only)<br />
Check the kernel settings and, if required, modify them. This is not required on<br />
computers running Linux or AIX.<br />
Check the Kernel Settings on Solaris<br />
<strong>eTrust</strong> <strong>Directory</strong> on Solaris requires the following kernel settings:<br />
Kernel Setting Value Description<br />
seminfo_semmap 1 Max number of semaphore map entries<br />
seminfo_semmni 100 Number of semaphore identifiers<br />
seminfo_semmns 1000 Max number of semaphores<br />
seminfo_semmnu 30 Number of semaphore undo structures<br />
seminfo_semms1 50<br />
seminfo_semopm 10 Max number of operations<br />
seminfo_semume 10 Semaphore undo entries per process<br />
seminfo_semusz 96 Size of undo structures<br />
seminfo_semvmx 32767 Semaphore maximum value<br />
seminfo_semaem 16384 Max value adjust on exit<br />
shminfo_shmmax<br />
100000000 Max shared mem segment<br />
shminfo_shmmin 1 Min shared memory segment<br />
shminfo_shmmni 100 Number of shared memory identifiers<br />
shminfo_shmseg 10 Shared memory segments per process<br />
To check that the …/etc/system file has the required settings, use the following<br />
command:<br />
./dxsetup.sh –check_kernel<br />
This command returns the value 1 if kernel changes are required, and 0 if no<br />
changes are required.<br />
To update the kernel settings, use the following command:<br />
./dxsetup.sh -reboot_kernel y|n<br />
where:<br />
■<br />
■<br />
y reboots the computer after the kernel parameters are modified<br />
n leaves the computer running after the kernel parameters are modified<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–7
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Check the Kernel Settings on HP<br />
<strong>eTrust</strong> <strong>Directory</strong> on HP requires the following kernel settings:<br />
Kernel Setting Value Description<br />
sema 1 Enable sys V semaphores<br />
semmap 1 Max number of semaphore map entries<br />
semmni 100 Number of semaphore identifiers<br />
semmns 1000 Max number of semaphores<br />
semmmnu 30 Number of semaphore undo structures<br />
semume 10 Semaphore undo entries per process<br />
semvmx 32767 Semaphore maximum value<br />
semaem 16384 Max value adjust on exit<br />
shmem 1 Enable sys V shared memory<br />
shmmax<br />
100000000 Max shared mem segment<br />
schmmni 100 Number of shared memory identifiers<br />
schmseg 10 Shared memory segments per process<br />
To update the kernel, use SAM:<br />
1. Run SAM as root.<br />
2. Set each parameter to the larger of the current or suggested values.<br />
3. Rebuild the kernel.<br />
4. Restart the computer.<br />
E–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Design the Disk Configuration<br />
To improve recovery and performance, you should store the database<br />
information on a separate physical disk from the Advantage Ingres installation.<br />
In the following example of the layout of a typical installation, the /local<br />
partition is on a separate physical disk:<br />
/opt/<strong>CA</strong><br />
DXserver product files<br />
Advantage Ingres product files<br />
Advantage Ingres transaction log<br />
/local/<strong>CA</strong><br />
<strong>Directory</strong> information (database files)<br />
Advantage Ingres checkpoints (database backups)<br />
Advantage Ingres journals<br />
Advantage Ingres work area<br />
For information about disk configurations such as mirrored disks and RAID,<br />
contact Computer Associates Technical Support at http://supportconnect.ca.com.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–9
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 2. Install <strong>eTrust</strong> <strong>Directory</strong><br />
The two <strong>eTrust</strong> <strong>Directory</strong> installation programs, dxsetup and dxwebsetup, are<br />
located on the <strong>eTrust</strong> <strong>Directory</strong> CD-ROM.<br />
These programs will ask a series of questions as the installation proceeds. In<br />
general, you should use the defaults.<br />
Step 2a. Run dxsetup<br />
1. Log in as root.<br />
2. If there is an existing Advantage Ingres installation on the system, stop<br />
Advantage Ingres.<br />
3. Run the dxsetup installation program in one of the following ways:<br />
- Run dxsetup from the CD or from the location to which you copied the<br />
CD contents. For example:<br />
cd /dxserver/unix/install<br />
./dxsetup.sh<br />
- Run dxsetup and include a parameter that specifies the location of the<br />
installation files. For example:<br />
./dxsetup.sh –r /dxserver/unix/install<br />
4. The Welcome dialog appears. It asks if you want to perform an express or<br />
custom setup.<br />
If you choose express setup, dxsetup installs <strong>eTrust</strong> <strong>Directory</strong> automatically,<br />
with the default values shown in the table in the section Default Installation<br />
Locations.<br />
If you choose custom setup, dxsetup asks you for information during the<br />
installation process.<br />
E–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 2b. Configure the System Kernel<br />
Solaris<br />
The dxsetup program checks the kernel configuration. This check ensures that<br />
the settings in the …/etc/system file are at least as good as the settings listed in<br />
the section Check the Kernel Settings.<br />
This is done differently for the different platforms.<br />
The kernel is updated as part of the installation process:L<br />
■<br />
■<br />
■<br />
■<br />
If the settings in the …/etc/system file are already correct, no action is taken.<br />
If any of the settings do not exist, they are created.<br />
If any of the settings already exist, their values are increased if necessary.<br />
If any of these values are changed, the dxsetup program asks if you want to<br />
restart the system. If you select n, dxsetup will exit.<br />
See the section Check the Kernel Settings (Solaris and HP only) for how to check<br />
the kernel settings manually.<br />
HP-UX<br />
Make sure that the kernel is already updated. See the section Check the Kernel<br />
Settings (Solaris and HP only) for instructions.<br />
Linux<br />
Not applicable.<br />
AIX<br />
The kernel is updated automatically. No action is required.<br />
Step 2c. Accept the License Agreement<br />
Before the installation begins, you must view and agree to the license<br />
agreements.<br />
1. The license agreement appears.<br />
2. When you have finished viewing the license, the dxsetup program asks:<br />
Do you agree to the above license? (y/n) [ ]<br />
- If you select n, the installation process stops.<br />
- If you select y, the installation process continues.<br />
- If you select the default (blank), the question is repeated until you select<br />
either y or n.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–11
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 2d. Set Up DXserver<br />
1. The dxsetup program asks if you want to install the DXserver software:<br />
Do you want to install the DXserver software? (y/n/i/q) [y]<br />
2. If you select n, dxsetup quits.<br />
If you select y, and dxsetup finds an existing DXserver installation, it asks if<br />
you want to perform an upgrade. If you select y, the existing <strong>eTrust</strong><br />
<strong>Directory</strong> installation is backed up.<br />
If you select y, and you are installing <strong>eTrust</strong> <strong>Directory</strong> for the first time, you<br />
are prompted for the shell and password for the dsa user.<br />
Enter the login shell for the dsa account [/bin/csh]<br />
The dsa account requires a password<br />
New password:<br />
4. The dxsetup program requests an installation directory for DXserver:<br />
Please specify the DXserver installation directory<br />
[/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxserver]<br />
Press Enter to accept the default directory, or enter the full pathname for a<br />
different directory.<br />
6. The following confirmation message appears:<br />
The directory /opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxserver will be created.<br />
Do you wish to change the directory? (y/n) [n]<br />
7. Enter n to accept the directory.<br />
Step 2e. Set Up the Documentation<br />
1. The dxsetup program asks if you want to install the documentation:<br />
Do you want to install the <strong>eTrust</strong> <strong>Directory</strong> documentation? (y/n/i/q) [y]<br />
2. The dxsetup program then requests an installation directory for the<br />
documentation:<br />
Please specify the Documentation installation directory<br />
[/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/documentation]<br />
Press Enter to accept the default directory, or enter the full pathname for a<br />
different directory.<br />
3. The following confirmation message appears:<br />
The directory /opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/documentation will be created.<br />
Do you wish to change the directory? (y/n) [n]<br />
4. Enter n to accept the directory.<br />
E–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 2f. Set Up Advantage Ingres<br />
1. The dxsetup program asks if you want to install the Advantage Ingres<br />
software:<br />
Do you want to install the Advantage Ingres software (y/n/i/q) [y]<br />
2. If you select y, and you are installing Advantage Ingres for the first time, you<br />
are prompted for the shell and password for the Advantage Ingres user.<br />
Enter the login shell for the ingres account [/bin/csh]<br />
The ingres account requires a password<br />
New password:<br />
If you select n, dxsetup bypasses the Advantage Ingres installation section.<br />
Ensure that you have adequate backups before performing an upgrade.<br />
3. The dxsetup program requests an installation directory for the Advantage<br />
Ingres software:<br />
Please specify the Advantage Ingres installation directory<br />
[/opt/<strong>CA</strong>/AdvantageIngresET/ingres]<br />
4. Press Enter to specify the default directory<br />
(/opt/<strong>CA</strong>/AdvantageIngresET/ingres), or provide the full pathname for an<br />
alternate directory.<br />
5. When you press Enter, the confirmation message will appear.<br />
The directory /opt/<strong>CA</strong>/AdvantageIngresET/ingres will be created.<br />
Do you wish to change the directory? (y/n) [n]<br />
6. The installation program asks you if you want to specify separate locations<br />
for data, work, checkpoint, dumps, and journals.<br />
If you select Yes, you are asked to specify a separate location for each<br />
component.<br />
If you select No, the installation program asks you to specify the location of<br />
the Advantage Ingres database directory:<br />
Please specify the Advantage Ingres database directory<br />
[/local/<strong>CA</strong>/AdvantageIngresET]<br />
7. Press Enter to accept the default directory (/local/<strong>CA</strong>/AdvantageIngresET),<br />
or provide the full pathname for an alternate directory.<br />
The directory /local/<strong>CA</strong>/AdvantageIngresET will be created.<br />
Do you wish to change the directory? (y/n) [n]<br />
8. Enter n to accept the directory.<br />
An ingres directory is added automatically to the path of the database<br />
directory you select. For example, if you select /local2/IngresET, the<br />
Advantage Ingres database directory is /local2/IngresET/ingres.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–13
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
9. You will then be prompted with a list of the time zones in that region.<br />
This setting must be assigned one of the following values:<br />
AFRI<strong>CA</strong><br />
ASIA<br />
AUSTRALIA<br />
MIDDLE-EAST<br />
NORTH-AMERI<strong>CA</strong><br />
NORTH-ATLANTIC<br />
SOUTH-AMERI<strong>CA</strong><br />
SOUTH-PACIFIC<br />
SOUTH-ASIA<br />
GMT-OFFSET<br />
Please enter one of the named regions:<br />
10. You will then be asked to select from one of the time zones in the region.<br />
11. When you enter one of the values, a confirmation message will appear.<br />
The Time Zone you have selected is: timezone<br />
Is this Time Zone correct? (y/n) [y]<br />
Enter y to confirm your choice.<br />
If dxsetup cannot upgrade a database, you will need to do this manually, using<br />
the DXupgradedb tool.<br />
To check for problems upgrading a database, look in the Ingres installation log files.<br />
By default, these files are in the folder /opt/<strong>CA</strong>/AdvantageIngresET/ingres/files.<br />
Step 2g. Set up DXadmind<br />
1. The dxsetup program asks for the details of DXadmind trusted hosts.<br />
Please enter the Hostnames/IP Addresses of DXadmind Trusted Hosts.<br />
Step 2h. Set Up JXplorer<br />
1. The dxsetup program asks if you want to install JXplorer:<br />
Do you want to install the JXplorer browser software? (y/n/i/q) [y]<br />
2. The dxsetup program requests an installation directory for JXplorer:<br />
Please specify the JXplorer installation directory<br />
[/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jxplorer]<br />
3. Press Enter to choose the default directory, or provide the full pathname for<br />
an alternate directory.<br />
The directory /opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jxplorer will be created.<br />
Do you want to change the directory ? (y/n) [n]<br />
4. Enter n to accept the directory.<br />
The dxsetup program installs the JXplorer files into the selected directory.<br />
E–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 2i. Set Up Java Runtime Environment (JRE)<br />
If you chose to install JXplorer, dxsetup checks to see if the Java Runtime<br />
Environment (JRE) is already installed.<br />
If JRE is installed:<br />
■<br />
■<br />
If the installed version is up-to-date, dxsetup skips to the next section:<br />
The existing java version 1.4.2_04 is newer/identical to the version supplied<br />
with this package. JRE will not be upgraded.<br />
If the installed version is not up-to-date, dxsetup upgrades JRE.<br />
If JRE is not installed, the dxsetup program installs it:<br />
1. The dxsetup program requests an installation directory for the JRE:<br />
Please specify the JRE installation directory. [/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jre]<br />
2. Press Enter to choose the default directory, or enter a different directory.<br />
The directory [/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jre will be created.<br />
Do you want to change the directory? (y/n) [n]<br />
3. Enter n to accept the directory.<br />
Step 2j. Set Up the Sample Directories<br />
1. If you have installed Advantage Ingres, the dxsetup program asks if you<br />
want to install the sample directories Democorp, UNSPSC, and Router:<br />
Do you wish to start the sample directories (y/n) [y]<br />
2. If you select y, the samples will be installed and set up.<br />
If you select n, the sample files will be installed, but they will not be set up.<br />
Note: If you do not install Advantage Ingres, you cannot run the sample<br />
scripts, and the system displays an error message.<br />
The installation program installs <strong>eTrust</strong> <strong>Directory</strong>, using the settings you entered.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–15
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 3: (Optional) Install the Web Components<br />
Step 3a. Run dxwebsetup<br />
1. The dxwebsetup program asks if you want to install DXwebserver:<br />
Do you want to install the DXwebserver software? (y/n/i/q) [y]<br />
2. The dxwebsetup program requests an installation directory for<br />
DXwebserver:<br />
Please specify the DXwebserver installation directory<br />
[/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxwebserver]<br />
3. Press Enter to choose the default directory, or enter a different directory.<br />
The directory /opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/dxwebserver will be created.<br />
Do you want to change the directory ? (y/n) [n]<br />
4. Enter n to accept the directory.<br />
Step 3b. Accept the License Agreement<br />
Before the installation begins, you must view and agree to the license agreement.<br />
1. The license agreement appears.<br />
2. When you have finished viewing the license, the dxsetup program asks:<br />
Do you agree to the above license? (y/n) [ ]<br />
- If you select n, the installation process stops.<br />
- If you select y, the installation process continues.<br />
- If you select the default (blank), the question is repeated until you select<br />
either y or n.<br />
Step 3c. Set Up Java Runtime Environment (JRE)<br />
If the Java Runtime Environment (JRE) is already installed, the dxwebsetup<br />
program checks the version:<br />
■ If the installed version is up-to-date, dxwebsetup skips to the next section:<br />
■<br />
The existing java version 1.4.2_04 is newer/identical to the version supplied<br />
with this package. JRE will not be upgraded.<br />
If the installed version is not up-to-date, dxwebsetup upgrades JRE.<br />
If JRE is not installed, the dxwebsetup program installs it:<br />
1. The dxwebsetup program requests an installation directory for the JRE:<br />
Please specify the JRE installation directory. [/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jre]<br />
2. Press Enter to choose the default directory, or enter a different directory.<br />
The directory [/opt/<strong>CA</strong>/<strong>eTrust</strong><strong>Directory</strong>/jre will be created.<br />
Do you want to change the directory? (y/n) [n]<br />
3. Enter n to accept the directory.<br />
The installation program installs the web components using the settings you entered.<br />
E–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Step 4: (Optional) Install the Technology Previews and Sample Tools<br />
This section describes how to set up the extras that come with <strong>eTrust</strong> <strong>Directory</strong>.<br />
Install the Sample Directories<br />
If you installed the samples but did not set them up, you can do this manually.<br />
You need to install each sample you want to work with.<br />
The schema used by the Democorp sample has changed since <strong>eTrust</strong> <strong>Directory</strong><br />
3.6 SP2. You should reinstall the samples by running the setup script in the<br />
Router, Democorp, and UNSPSC directories.<br />
Important! If you run these scripts, any existing data in the Democorp and UNSPSC<br />
databases will be lost.<br />
To set up the sample directories:<br />
1. Navigate to $DXHOME/samples/democorp.<br />
2. Run setup.sh.<br />
3. Navigate to $DXHOME/samples/unspsc.<br />
4. Run setup.bat.<br />
5. Navigate to $DXHOME/samples/router.<br />
6. Run setup.bat.<br />
Install the Sample Tools<br />
<strong>eTrust</strong> <strong>Directory</strong> includes sample tools that you can use to work with your DSAs.<br />
In an express installation, these samples are installed but not set up. You need to<br />
install each sample you want to work with.<br />
■<br />
To install each of these sample tools, run the scripts in the directories under<br />
the directory $DXHOME/samples.<br />
For more information, see the chapter “Samples”.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–17
Install <strong>eTrust</strong> <strong>Directory</strong> Using the Installation Program<br />
Install the Technology Previews<br />
<strong>eTrust</strong> <strong>Directory</strong> comes with three technology previews that are examples of how<br />
you can extend <strong>eTrust</strong> <strong>Directory</strong>, or are previews of upcoming features. For more<br />
information, see the chapter “Samples”.<br />
To install the Democorp version of JXweb:<br />
1. Navigate to dxwebserver/samples/democorp.<br />
2. Run setup.sh.<br />
To install the UDDI demonstration:<br />
1. Navigate to dxwebserver/samples/uddi/uddiv3-demo.<br />
2. Run setup.sh.<br />
To install the DSML server technology preview:<br />
1. Navigate to dxwebserver/samples/dsml.<br />
2. Run setup.sh.<br />
E–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
You can install <strong>eTrust</strong> <strong>Directory</strong> and the <strong>eTrust</strong> <strong>Directory</strong> web components using<br />
the commands dxsetup and dxwebsetup.<br />
The dxsetup Command<br />
You can use the dxsetup command to install the main directory components:<br />
./dxsetup.sh [options]<br />
where the options are any of the following, in any order:<br />
Option<br />
Action<br />
-nojxplorer<br />
-nodocs<br />
-noingres<br />
-nosamples<br />
Install <strong>eTrust</strong> <strong>Directory</strong> without installing JXplorer<br />
Install <strong>eTrust</strong> <strong>Directory</strong> without installing the user documentation<br />
Install <strong>eTrust</strong> <strong>Directory</strong> without installing Advantage Ingres. Only use this<br />
option if DXserver will act as a router or a relay DSA. The DXserver directory<br />
samples will not run, as these require a database.<br />
Install <strong>eTrust</strong> <strong>Directory</strong> without installing the sample DSAs<br />
-r source_directory Run dxsetup from a remote location<br />
-dxuser username<br />
-silent<br />
-embedded<br />
-caller_id caller_id<br />
-list_callers<br />
-write_responses<br />
/filepath/filename<br />
-responsefile<br />
/filepath/filename<br />
-check_kernel<br />
-reboot_kernel y|n<br />
Allows a username other than the 'dsa' default<br />
Installs <strong>eTrust</strong> <strong>Directory</strong> silently. This is ideantical to the -default option, which is<br />
still valid.<br />
Installs <strong>eTrust</strong> <strong>Directory</strong> as a component embedded in another product<br />
The installation code of the embedding product.<br />
List all embedded installations of <strong>eTrust</strong> <strong>Directory</strong>. This does not install <strong>eTrust</strong><br />
<strong>Directory</strong>.<br />
Create a response file that can be used to install <strong>eTrust</strong> <strong>Directory</strong> silently.<br />
This does not install <strong>eTrust</strong> <strong>Directory</strong>.<br />
Install <strong>eTrust</strong> <strong>Directory</strong> using the options listed in the response file.<br />
This does not install <strong>eTrust</strong> <strong>Directory</strong>.<br />
(Solaris only) Checks if the kernel needs to be updated: returns 1 if kernel<br />
changes are required, and returns 0 if no changes are required.<br />
This does not install <strong>eTrust</strong> <strong>Directory</strong>.<br />
(Solaris only) Modifies kernel parameters to allow installation, and then either<br />
reboots the computer or leaves it running. If you enter y, the computer reboots<br />
after the kernel parameters are modified. If you enter n, the computer is left<br />
running. This does not install <strong>eTrust</strong> <strong>Directory</strong>.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–19
Install <strong>eTrust</strong> <strong>Directory</strong> Using Commands<br />
The dxwebsetup Command<br />
Use the dxwebsetup command to install the web components of <strong>eTrust</strong> <strong>Directory</strong>:<br />
./dxwebsetup.sh [options]<br />
where the options are any of the following, in any order:<br />
Option<br />
Action<br />
-r source_directory Run dxwebsetup from a remote location<br />
-silent<br />
Installs the web components silently (no prompts are given to the user).<br />
-embedded<br />
Install <strong>eTrust</strong> <strong>Directory</strong> as a component embedded in another product<br />
-caller_id caller_id The installation code of the embedding product.<br />
E–20 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
You can install <strong>eTrust</strong> <strong>Directory</strong> silently (or unattended). This means that you<br />
need to provide the information that would normally be supplied by the user<br />
during installation in one of the following two ways:<br />
■<br />
■<br />
In the command used to launch the installation<br />
In a response file<br />
Install Using Commands<br />
During a silent installation, feedback is still printed to the screen. To suppress<br />
this feedback, send the output to /dev/null:<br />
./dxsetup.sh -silent >/dev/null<br />
Install the Main <strong>eTrust</strong> <strong>Directory</strong> Components<br />
1. Change to the /dxserver/unix/install directory.<br />
2. Run the following command:<br />
./dxsetup.sh -silent [options]<br />
where options are the options listed in the table in the section The dxsetup<br />
Command<br />
3. If the users dsa and ingres did not exist before, this installation created them<br />
without passwords.<br />
Run the passwd utility to assign passwords to the dsa and ingres users.<br />
Example: Silently<br />
Install DXserver Using<br />
a COmmand<br />
The following command installs only DXserver and DXtools, in the default<br />
locations (the samples are not installed because Ingres is not installed):<br />
./dxsetup.sh –silent –nojxplorer –nodxwebserver –nodocs –noingres<br />
Install the <strong>eTrust</strong> <strong>Directory</strong> Web Components<br />
1. Change to the /dxserver/unix/install directory.<br />
2. Run the following command:<br />
./dxwebsetup.sh> -silent [options]<br />
where options are the options listed in the table in the section The dxsetup<br />
Command<br />
3. If the user dsa did not exist before, this installation created it without a<br />
password.<br />
Run the passwd utility to assign a password to the dsa user.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–21
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Install Using Response Files<br />
A response file is a text file that supplies the arguments to be used during the<br />
installation process. This input would usually be supplied by the user as they<br />
install <strong>eTrust</strong> <strong>Directory</strong>.<br />
When you create a response file, the license agreement appears, and if you agree<br />
to the terms, a response file is created, using the options that you specify.<br />
The <strong>eTrust</strong> <strong>Directory</strong> installation CD includes response filea that install the<br />
components to the default locations shown in the table in the section Default<br />
Installation Locations. You can edit these response files, or you can generate new<br />
ones.<br />
If you run an installation from a response file that has errors or omissions, error<br />
messages are written to the screen, and the installation quits.<br />
Install the Main <strong>eTrust</strong> <strong>Directory</strong> Components<br />
To use a response file to install the main directory components, use the following<br />
command:<br />
./dxsetup.sh -responsefile /filepath/filename<br />
where filepath/filename is the path to the response file<br />
Install the <strong>eTrust</strong> <strong>Directory</strong> Web Components<br />
To use a response file to install web components, use the following command:<br />
./dxwebsetup -responsefile /filepath\filename<br />
where filepath/filename is the path to the response file<br />
Edit a Response File<br />
The installation CD includes one response file for each of the two installation<br />
modules:<br />
■<br />
■<br />
The dxsetup response file: /dxserver/responsefile.txt<br />
The dxwebsetup response file: /dxwebserver/responsefile.txt<br />
To edit a response file:<br />
1. Copy the response file from the CD onto a computer.<br />
2. Edit the response file using a text editor.<br />
E–22 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Install <strong>eTrust</strong> <strong>Directory</strong> Silently<br />
Create a New Response File for the Main <strong>eTrust</strong> <strong>Directory</strong> Components<br />
The default location for the response file is /tmp/etrdir8.rsp.<br />
1. To create a response file for the main directory components:<br />
./dxsetup.sh -write_responses [/filepath/filename] [options]<br />
where:<br />
- /filepath/filename is the path to the new response file<br />
- options are the installation options listed in the section The dxsetup<br />
Command<br />
2. The installation program asks you for information as in a normal installation.<br />
Create a New Response File for the Main <strong>eTrust</strong> <strong>Directory</strong> Components<br />
The default location for the response file is /tmp/etrdir8.rsp.<br />
1. To create a response file for the web components:<br />
./dxwebsetup.sh -write_responses [/filepath/filename] [options]<br />
where:<br />
- /filepath/filename is the path to the new response file<br />
- options are the installation options listed in the section The dxsetup<br />
Command<br />
2. The installation program asks you for information as in a normal installation.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–23
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
<strong>eTrust</strong> <strong>Directory</strong> can be installed as an embedded product so that other <strong>CA</strong><br />
products can use its features in their product.<br />
The information that the user would usually supply during the installation<br />
process is supplied as options with the installation commands.<br />
How Installation Codes Work<br />
Only one product can use a particular installation code. Each product will always<br />
use the same installation code. Each installation code is recorded, so as not to<br />
affect any other instances of <strong>eTrust</strong> <strong>Directory</strong>. They must also use this installation<br />
code to uninstall <strong>eTrust</strong> <strong>Directory</strong>.<br />
This means that other <strong>CA</strong> products can install <strong>eTrust</strong> <strong>Directory</strong> using their own<br />
unique installation code. Then, if <strong>eTrust</strong> <strong>Directory</strong> needs to be removed, the<br />
customer can remove it without removing anything that the embedding <strong>CA</strong><br />
product requires.<br />
All install commands can be used with the embedded and installation code<br />
commands on the one command line.<br />
To find out which installation codes are supported, contact <strong>CA</strong> Support.<br />
Install the Main <strong>eTrust</strong> <strong>Directory</strong> Components as an Embedded Module<br />
To install the main directory components as an embedded module, use the<br />
following command:<br />
./dxsetup.sh –embedded -caller_id unique_id<br />
where -caller_id unique_id uniquely identifies the embedding customer.<br />
Install the Web Components as an Embedded Module<br />
To install the web components as an embedded module, use the following<br />
command:<br />
./dxwebsetup.sh –embedded -caller_id unique_id<br />
where -caller_id unique_id uniquely identifies the embedding customer.<br />
E–24 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Embed <strong>eTrust</strong> <strong>Directory</strong> in Another <strong>CA</strong> Product<br />
Uninstall <strong>eTrust</strong> <strong>Directory</strong> after an Embedded Installation<br />
The installation code must be used to uninstall an embedded version of <strong>eTrust</strong><br />
<strong>Directory</strong>.<br />
The uninstallation process determines if no more products require <strong>eTrust</strong><br />
<strong>Directory</strong> and remove the product accordingly. If other products are using <strong>eTrust</strong><br />
<strong>Directory</strong> then the uninstall will remove only the reference counter for that caller,<br />
and not the <strong>eTrust</strong> <strong>Directory</strong> components used by the other callers.<br />
Example: Installing<br />
and Uninstalling <strong>eTrust</strong><br />
<strong>Directory</strong> within <strong>eTrust</strong><br />
Web Access Control<br />
The following command installs <strong>eTrust</strong> <strong>Directory</strong> silently with the installation<br />
code ETWAC, which signifies that it is embedded within <strong>eTrust</strong> Web Access<br />
Control:<br />
./dxsetup.sh -default -embedded –caller_id ETWAC<br />
To uninstall <strong>eTrust</strong> <strong>Directory</strong> that was installed with the installation code<br />
ETWAC:<br />
./dxuninst.sh -embedded –caller_id ETWAC<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–25
Troubleshooting<br />
Troubleshooting<br />
This section describes how to deal with problems that might occur during or<br />
after installing or upgrading <strong>eTrust</strong> <strong>Directory</strong>.<br />
Diagnosing Startup Problems with <strong>eTrust</strong> <strong>Directory</strong> or Ingres<br />
On Solaris, <strong>eTrust</strong> <strong>Directory</strong> is started and stopped at system boot and shutdown<br />
via the /etc/init.d/dxserver script. This starts and stops Ingres, SSL daemons,<br />
the DXadmin daemon, and any DXserver processes marked for autostart.<br />
This file writes a log called dxserver-rc.log usually in the DXserver logs<br />
directory, $DXHOME/logs (if DXHOME is not defined for some reason then<br />
look for this file in the /tmp directory). This log shows each of the processes<br />
being started or stopped.<br />
Prior to <strong>eTrust</strong> <strong>Directory</strong> 3.6, this file was called rc.log in the DXserver logs<br />
directory. There should always be a dxserver-rc.log file in /tmp.<br />
DXadmind Times Out after Upgrading<br />
Reason:<br />
This problem occurs because DXadmind is already started.<br />
In a standard upgrade for DXserver, DXadmind is stopped and restarted once<br />
the upgrade is complete. However if the installation for DXserver is cancelled<br />
part-way, DXadmind may not have stopped and then when it tries to re-start, it<br />
times out.<br />
Action:<br />
To check the status of DXadmind, type the following command:<br />
dxadmind status<br />
To fix the problem, run the following commands:<br />
1. Log in a the user DXserver <strong>Administrator</strong> (the default user is DSA).<br />
2. Stop DXadmind:<br />
dxadmind stop all<br />
3. Re-start DXadmind:<br />
dxadmind start all<br />
E–26 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Troubleshooting<br />
If DXadmind times out again, do the following steps:<br />
1. Type the following command:<br />
ps -ef | grep dxadmind<br />
The response includes a line similar to the following:<br />
dsa 6204 1 0 21:23:34 ? 0:00 dxadmind start<br />
2. In the sample above, the number 6204 is the process number. You have to kill<br />
that process by typing kill process number<br />
Important! Ensure this number is typed correctly!<br />
3. Re-start DXadmind by typing the following command:<br />
dxadmind start all<br />
Note: To run the kill command, you can be logged in as root or dsa. However,<br />
you need to be logged in as dsa to run the command dxadmind start.<br />
Installing <strong>eTrust</strong> <strong>Directory</strong> for UNIX E–27
Appendix<br />
F<br />
Licenses for Third-Party Products<br />
<strong>eTrust</strong> <strong>Directory</strong> uses some third-party code. This appendix includes the license<br />
agreements for that code.<br />
See the Release Notes for a list of the components and version numbers.<br />
Apache<br />
This product includes software developed by the Apache Software Foundation<br />
(http://www.apache.org/). The Apache software is distributed in accordance<br />
with the following license agreement.<br />
The Apache Software License, Version 1.1<br />
Apache Ant 1.5.3<br />
Copyright (C) 2000-2003 The Apache Software Foundation. All rights reserved.<br />
Apache Axis 1.1<br />
Copyright (c) 2002 The Apache Software Foundation. All rights reserved.<br />
Apache Cactus 1.5<br />
Copyright (c) 2001-2003 The Apache Software Foundation. All rights reserved.<br />
Apache Jakarta-Oro 2.0<br />
Copyright (c) 2000-2002 The Apache Software Foundation. All rights reserved.<br />
Apache Log4j 1.2.8<br />
Copyright (c) 1999 The Apache Software Foundation. All rights reserved.<br />
Apache Tomcat 4.1.29<br />
Copyright (c) 1999, 2000 The Apache Software Foundation. All rights reserved.<br />
Apache Xalan C++ 1.6<br />
Copyright (c) 1999 The Apache Software Foundation. All rights reserved.<br />
Apache Xalan Java 2.5.2<br />
Copyright (c) 1999-2003 The Apache Software Foundation. All rights reserved.<br />
Licenses for Third-Party Products F–1
Apache<br />
Apache Xerces C++ 2.3<br />
Copyright (c) 1999-2001 The Apache Software Foundation. All rights reserved.<br />
Apache Xerces Java 2.6<br />
Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.<br />
Redistribution and use in source and binary forms, with or without modification,<br />
are permitted provided that the following conditions are met:<br />
1. Redistributions of source code must retain the above copyright notice, this list<br />
of conditions and the following disclaimer.<br />
2. Redistributions in binary form must reproduce the above copyright notice, this<br />
list of conditions and the following disclaimer in the documentation and/or<br />
other materials provided with the distribution.<br />
3. The end-user documentation included with the redistribution, if any, must<br />
include the following acknowledgment: "This product includes software<br />
developed by the Apache Software Foundation (http://www.apache.org/)."<br />
Alternately, this acknowledgment may appear in the software itself, if and<br />
wherever such third-party acknowledgments normally appear.<br />
4. The names "Ant", "Axis", "Cactus", "The Jakarta Project", "Jakarta-Oro", "log4j",<br />
"Tomcat", "Xalan", "Xerces", "Apache" and "Apache Software Foundation" must<br />
not be used to endorse or promote products derived from this software without<br />
prior written permission. For written permission, please contact<br />
apache@apache.org.<br />
5. Products derived from this software may not be called "Apache" or "Jakarta-<br />
Oro", nor may "Apache" or "Jakarta-Oro" appear in their name, without prior<br />
written permission of the Apache Software Foundation.<br />
THIS SOFTWARE IS PROVIDED "AS IS'' AND ANY EXPRESSED OR IMPLIED<br />
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED<br />
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR<br />
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE<br />
SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY<br />
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR<br />
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,<br />
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,<br />
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER <strong>CA</strong>USED<br />
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT<br />
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)<br />
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF<br />
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.<br />
F–2 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Morten’s JavaScript Tree Menu v2.3.2<br />
Apache Ant, Axis, Cactus, Jakarta-Oro, Log4J and Tomcat consist of voluntary<br />
contributions made by many individuals on behalf of the Apache Software<br />
Foundation. For more information on the Apache Software Foundation, please<br />
see .<br />
Portions of Apache Jakarta-Oro are based upon software originally written by<br />
Daniel F. Savarese. We appreciate his contributions.<br />
Apache Xalan C++ and Xalan Java consist of voluntary contributions made by<br />
many individuals on behalf of the Apache Software Foundation and were<br />
originally based on software copyright (c) 1999, Lotus Development Corporation,<br />
http://www.lotus.com. For more information on the Apache Software<br />
Foundation, please see .<br />
Apache Xerces C++ and Xerces Java consist of voluntary contributions made by<br />
many individuals on behalf of the Apache Software Foundation and were<br />
originally based on software copyright (c) 1999, International Business Machines,<br />
Inc., http://www.ibm.com. For more information on the Apache Software<br />
Foundation, please see .<br />
Morten’s JavaScript Tree Menu v2.3.2<br />
This product includes software developed by Morten Wang & contributors. The<br />
software is distributed in accordance with the following copyright and<br />
permission notices.<br />
Copyright (c) 2001-2002, Morten Wang & contributors All rights reserved.<br />
Redistribution and use in source and binary forms, with or without modification,<br />
are permitted provided that the following conditions are met:<br />
* Redistributions of source code must retain the above copyright notice, this list<br />
of conditions and the following disclaimer.<br />
* Redistributions in binary form must reproduce the above copyright notice, this<br />
list of conditions and the following disclaimer in the documentation and/or<br />
other materials provided with the distribution.<br />
* Neither the name "Morten's JavaScript Tree Menu" nor the names of its<br />
contributors may be used to endorse or promote products derived from this<br />
software without specific prior written permission.<br />
Licenses for Third-Party Products F–3
OpenLDAP<br />
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND<br />
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,<br />
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF<br />
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE<br />
DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE<br />
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,<br />
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT<br />
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS<br />
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER<br />
<strong>CA</strong>USED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,<br />
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)<br />
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF<br />
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.<br />
OpenLDAP<br />
Portions of this product include software developed by the OpenLDAP<br />
Foundation. The OpenLDAP software is distributed in accordance with the<br />
following license agreement.<br />
The OpenLDAP Public License<br />
Version 2.8, 17 August 2003<br />
Redistribution and use of this software and associated documentation<br />
("Software"), with or without modification, are permitted provided that the<br />
following conditions are met:<br />
1. Redistributions in source form must retain copyright statements and notices,<br />
2. Redistributions in binary form must reproduce applicable copyright<br />
statements and notices, this list of conditions, and the following disclaimer in the<br />
documentation and/or other materials provided with the distribution, and<br />
3. Redistributions must contain a verbatim copy of this document.<br />
The OpenLDAP Foundation may revise this license from time to time.<br />
Each revision is distinguished by a version number. You may use this Software<br />
under terms of this license revision or under the terms of any subsequent<br />
revision of the license.<br />
F–4 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
OpenLDAP<br />
THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND<br />
ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED<br />
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED<br />
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR<br />
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENLDAP<br />
FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) OR OWNER(S)<br />
OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,<br />
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES<br />
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE<br />
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS<br />
INTERRUPTION) HOWEVER <strong>CA</strong>USED AND ON ANY THEORY OF<br />
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT<br />
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT<br />
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY<br />
OF SUCH DAMAGE.<br />
The names of the authors and copyright holders must not be used in advertising<br />
or otherwise to promote the sale, use or other dealing in this Software without<br />
specific, written prior permission. Title to copyright in this Software shall at all<br />
times remain with copyright holders.<br />
OpenLDAP is a registered trademark of the OpenLDAP Foundation.<br />
Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, California,<br />
USA. All Rights Reserved. Permission to copy and distribute verbatim copies of<br />
this document is granted.<br />
The OpenLDAP Copyright Notice<br />
Copyright 1998-2004 The OpenLDAP Foundation<br />
All rights reserved.<br />
Redistribution and use in source and binary forms, with or without modification,<br />
are permitted only as authorized by the OpenLDAP Public License.<br />
A copy of this license is available in the file LICENSE in the top-level directory of<br />
the distribution or, alternatively, at<br />
.<br />
OpenLDAP is a registered trademark of the OpenLDAP Foundation.<br />
Individual files and/or contributed packages may be copyright by other parties<br />
and subject to additional restrictions.<br />
Licenses for Third-Party Products F–5
OpenSSL<br />
This work is derived from the University of Michigan LDAP v3.3 distribution.<br />
Information concerning this software is available at<br />
.<br />
This work also contains materials derived from public sources.<br />
Additional information about OpenLDAP can be obtained at<br />
.<br />
Portions Copyright 1998-2004 Kurt D. Zeilenga.<br />
Portions Copyright 1998-2004 Net Boolean Incorporated.<br />
Portions Copyright 2001-2004 IBM Corporation.<br />
All rights reserved.<br />
Redistribution and use in source and binary forms, with or without modification,<br />
are permitted only as authorized by the OpenLDAP Public License.<br />
Portions Copyright 1999-2003 Howard Y.H. Chu.<br />
Portions Copyright 1999-2003 Symas Corporation.<br />
Portions Copyright 1998-2003 Hallvard B. Furuseth.<br />
All rights reserved.<br />
Redistribution and use in source and binary forms, with or without modification,<br />
are permitted provided that this notice is preserved. The names of the copyright<br />
holders may not be used to endorse or promote products derived from this<br />
software without their specific prior written permission. This software is<br />
provided ``as is'' without express or implied warranty.<br />
Portions Copyright (c) 1992-1996 Regents of the University of Michigan.<br />
All rights reserved.<br />
Redistribution and use in source and binary forms are permitted provided that<br />
this notice is preserved and that due credit is given to the University of Michigan<br />
at Ann Arbor. The name of the University may not be used to endorse or<br />
promote products derived from this software without specific prior written<br />
permission. This software is provided ``as is'' without express or implied<br />
warranty.<br />
OpenSSL<br />
Terms and Conditions for the Use of The OpenSSL Toolkit<br />
F–6 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
OpenSSL<br />
Licensee agrees that the following terms (in addition to the applicable provisions<br />
above) shall apply with respect to any open source provided by The OpenSSL<br />
Project and Eric Young contained within the Product. Notwithstanding anything<br />
contained in the <strong>CA</strong> End User License Agreement, solely with respect to such<br />
open source, these terms are not superseded by any written agreement between<br />
<strong>CA</strong> and Licensee:<br />
Copyright (c) 1998-2000 The OpenSSL Project. All rights reserved.<br />
This product includes software developed by the OpenSSL Project for use in the<br />
OpenSSL Toolkit (http://www.openssl.org/).<br />
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ”AS IS” AND<br />
ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT<br />
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND<br />
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT<br />
SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR<br />
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR<br />
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,<br />
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,<br />
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER <strong>CA</strong>USED<br />
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT<br />
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)<br />
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF<br />
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.<br />
This product includes cryptographic software written by Eric Young<br />
(eay@cryptsoft.com). This product includes software written by Tim Hudson<br />
(tjh@cryptsoft.com).<br />
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved.<br />
The following conditions apply to all code found in this distribution, be it the<br />
RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation<br />
included with this distribution is covered by the same copyright terms except<br />
that the holder is Tim Hudson (tjh@cryptsoft.com).<br />
This product includes software written by Tim Hudson (tjh@cryptsoft.com).<br />
Licenses for Third-Party Products F–7
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ”AS IS” AND ANY<br />
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,<br />
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A<br />
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE<br />
AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,<br />
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES<br />
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE<br />
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS<br />
INTERRUPTION) HOWEVER <strong>CA</strong>USED AND ON ANY THEORY OF<br />
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT<br />
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT<br />
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY<br />
OF SUCH DAMAGE.<br />
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED<br />
SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT")<br />
<strong>CA</strong>REFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY<br />
OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS<br />
OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE<br />
ELECTRONI<strong>CA</strong>LLY, INDI<strong>CA</strong>TE YOUR ACCEPTANCE OF THESE TERMS BY<br />
SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT.<br />
IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN THE<br />
UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR,<br />
IF THE SOFTWARE IS ACCESSED ELECTRONI<strong>CA</strong>LLY, SELECT THE<br />
"DECLINE" BUTTON AT THE END OF THIS AGREEMENT.<br />
1. LICENSE TO USE. Sun grants you a non-exclusive and non-transferable<br />
license for the internal use only of the accompanying software and<br />
documentation and any error corrections provided by Sun (collectively<br />
"Software"), by the number of users and the class of computer hardware for<br />
which the corresponding fee has been paid.<br />
2. RESTRICTIONS. Software is confidential and copyrighted. Title to Software<br />
and all associated intellectual property rights is retained by Sun and/or its<br />
licensors. Except as specifically authorized in any Supplemental License<br />
Terms, you may not make copies of Software, other than a single copy of<br />
Software for archival purposes. Unless enforcement is prohibited by<br />
applicable law, you may not modify, decompile, or reverse engineer<br />
Software. Licensee acknowledges that Licensed Software is not designed or<br />
intended for use in the design, construction, operation or maintenance of any<br />
nuclear facility. Sun Microsystems, Inc. disclaims any express or implied<br />
warranty of fitness for such uses. No right, title or interest in or to any<br />
trademark, service mark, logo or trade name of Sun or its licensors is granted<br />
under this Agreement.<br />
F–8 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
3. LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90)<br />
days from the date of purchase, as evidenced by a copy of the receipt, the<br />
media on which Software is furnished (if any) will be free of defects in<br />
materials and workmanship under normal use. Except for the foregoing,<br />
Software is provided "AS IS". Your exclusive remedy and Sun's entire<br />
liability under this limited warranty will be at Sun's option to replace<br />
Software media or refund the fee paid for Software.<br />
4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS<br />
AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS,<br />
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED<br />
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR<br />
PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO<br />
THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY<br />
INVALID.<br />
5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY<br />
LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY<br />
LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT,<br />
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER<br />
<strong>CA</strong>USED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT<br />
OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE,<br />
EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH<br />
DAMAGES. In no event will Sun's liability to you, whether in contract, tort<br />
(including negligence), or otherwise, exceed the amount paid by you for<br />
Software under this Agreement. The foregoing limitations will apply even if<br />
the above stated warranty fails of its essential purpose.<br />
6. Termination. This Agreement is effective until terminated. You may<br />
terminate this Agreement at any time by destroying all copies of Software.<br />
This Agreement will terminate immediately without notice from Sun if you<br />
fail to comply with any provision of this Agreement. Upon Termination, you<br />
must destroy all copies of Software.<br />
7. Export Regulations. All Software and technical data delivered under this<br />
Agreement are subject to US export control laws and may be subject to<br />
export or import regulations in other countries. You agree to comply strictly<br />
with all such laws and regulations and acknowledge that you have the<br />
responsibility to obtain such licenses to export, re-export, or import as may<br />
be required after delivery to you.<br />
8. U.S. Government Restricted Rights. If Software is being acquired by or on<br />
behalf of the U.S. Government or by a U.S. Government prime contractor or<br />
subcontractor (at any tier), then the Government's rights in Software and<br />
accompanying documentation will be only as set forth in this Agreement;<br />
this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for<br />
Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and<br />
12.212 (for non-DOD acquisitions).<br />
Licenses for Third-Party Products F–9
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
9. Governing Law. Any action related to this Agreement will be governed by<br />
California law and controlling U.S. federal law. No choice of law rules of any<br />
jurisdiction will apply.<br />
10. Severability. If any provision of this Agreement is held to be unenforceable,<br />
this Agreement will remain in effect with the provision omitted, unless<br />
omission would frustrate the intent of the parties, in which case this<br />
Agreement will immediately terminate.<br />
11. Integration. This Agreement is the entire agreement between you and Sun<br />
relating to its subject matter. It supersedes all prior or contemporaneous oral<br />
or written communications, proposals, representations and warranties and<br />
prevails over any conflicting or additional terms of any quote, order,<br />
acknowledgment, or other communication between the parties relating to its<br />
subject matter during the term of this Agreement. No modification of this<br />
Agreement will be binding, unless in writing and signed by an authorized<br />
representative of each party.<br />
JAVATM WEB SERVICES DEVELOPER PACK, VERSION 1.1<br />
SUPPLEMENTAL LICENSE TERMS<br />
These supplemental license terms ("Supplemental Terms") add to or modify the<br />
terms of the Binary Code License Agreement (collectively, the "Agreement").<br />
Capitalized terms not defined in these Supplemental Terms shall have the same<br />
meanings ascribed to them in the Agreement. These Supplemental Terms shall<br />
supersede any inconsistent or conflicting terms in the Agreement, or in any<br />
license contained within the Software.<br />
1. Software Internal Use and Development License Grant. Subject to the terms<br />
and conditions of this Agreement, including, but not limited to Section 4<br />
(Java Technology Restrictions) of these Supplemental Terms, Sun grants you<br />
a non-exclusive, non-transferable, limited license to reproduce internally and<br />
use internally the binary form of the Software complete and unmodified for<br />
the purposes of designing, developing, testing, and running your Java<br />
applets and applications intended to run on the Java platform ("Programs"),<br />
except for certain files identified in the Software "Release Notes" file which<br />
may only be used for the purposes of designing, developing, and testing<br />
Programs.<br />
F–10 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
2. License to Distribute Software. Subject to the terms and conditions of this<br />
Agreement, including but not limited to Section 4 (Java Technology<br />
Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive,<br />
non-transferable, limited license to reproduce and distribute the Software in<br />
binary code form only, provided that you (i) distribute the Software<br />
complete and unmodified and only bundled as part of your Programs, (ii) do<br />
not distribute additional software intended to replace any portion of the<br />
Software, (iii) do not remove or alter any proprietary legends or notices<br />
contained in the Software, (iv) only distribute the Software subject to a<br />
license agreement that protects Sun's interests consistent with the terms<br />
contained in this Agreement, (v) agree to defend and indemnify Sun and its<br />
licensors from and against any damages, costs, liabilities, settlement amounts<br />
and/or expenses (including attorneys' fees) incurred in connection with any<br />
claim, lawsuit or action by any third party that arises or results from the use<br />
or distribution of any and all Programs and/or Software, and (vi) include the<br />
following statement as part of product documentation (whether hard copy or<br />
electronic), as a part of a copyright page or proprietary rights notice page, in<br />
an "About" box or in any other form reasonably designed to make the<br />
statement visible to users of the Software: "This product includes code<br />
licensed from RSA Data Security".<br />
3. License to Distribute Redistributables. Subject to the terms and conditions of<br />
this Agreement, including but not limited to Section 4 (Java Technology<br />
Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive,<br />
non-transferable, limited license to reproduce and distribute those<br />
components specifically identified as redistributable in the Software "Release<br />
Notes" file ("Redistributables") provided that: (i) you distribute the<br />
Redistributables complete and unmodified (unless otherwise specified in the<br />
applicable Release Notes file), and only bundled as part of your Programs,<br />
(ii) you do not distribute additional software intended to supersede any<br />
portion of the Redistributables, (iii) you do not remove or alter any<br />
proprietary legends or notices contained in or on the Redistributables, (iv)<br />
you only distribute the Redistributables pursuant to a license agreement that<br />
protects Sun's interests consistent with the terms contained in the<br />
Agreement, (v) you agree to defend and indemnify Sun and its licensors<br />
from and against any damages, costs, liabilities, settlement amounts and/or<br />
expenses (including attorneys' fees) incurred in connection with any claim,<br />
lawsuit or action by any third party that arises or results from the use or<br />
distribution of any and all Programs and/or Software, and (vi) if you<br />
distribute the Java Secure Socket Extension package, include the following<br />
statement as part of product documentation (whether hard copy or<br />
electronic), as a part of a copyright page or proprietary rights notice page, in<br />
an "About" box or in any other form reasonably designed to make the<br />
statement visible to users of the Software: "This product includes code<br />
licensed from RSA Data Security".<br />
Licenses for Third-Party Products F–11
Sun Microsystems, Inc. Java Web Services Developer Pack<br />
4. Java Technology Restrictions. You may not modify the Java Platform<br />
Interface ("JPI", identified as classes contained within the "java" package or<br />
any subpackages of the "java" package), by creating additional classes within<br />
the JPI or otherwise causing the addition to or modification of the classes in<br />
the JPI. In the event that you create an additional class and associated API(s)<br />
which (i) extends the functionality of the Java platform, and (ii) is exposed to<br />
third party software developers for the purpose of developing additional<br />
software which invokes such additional API, you must promptly publish<br />
broadly an accurate specification for such API for free use by all developers.<br />
You may not create, or authorize your licensees to create, additional classes,<br />
interfaces, or subpackages that are in any way identified as "java", "javax",<br />
"sun" or similar convention as specified by Sun in any naming convention<br />
designation.<br />
5. Java Runtime Availability. Refer to the appropriate version of the Java<br />
Runtime Environment binary code license (currently located at<br />
http://www.java.sun.com/jdk/index.html) for the availability of runtime<br />
code which may be distributed with Java applets and applications.<br />
6. Trademarks and Logos. You acknowledge and agree as between you and<br />
Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET<br />
trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANETrelated<br />
trademarks, service marks, logos and other brand designations ("Sun<br />
Marks"), and you agree to comply with the Sun Trademark and Logo Usage<br />
Requirements currently located at<br />
http://www.sun.com/policies/trademarks. Any use you make of the Sun<br />
Marks inures to Sun's benefit.<br />
7. Source Code. Software may contain source code that is provided solely for<br />
reference purposes pursuant to the terms of this Agreement. Source code<br />
may not be redistributed unless expressly provided for in this Agreement.<br />
8. Third Party Licenses. Additional copyright notices and license terms<br />
applicable to portions of the software are set forth in the<br />
THIRDPARTYLICENSEREADME file.<br />
9. Termination for Infringement. Either party may terminate this Agreement<br />
immediately should any Software become, or in either party's opinion be<br />
likely to become, the subject of a claim of infringement of any intellectual<br />
property right.<br />
F–12 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Tom Sawyer Layout Assistant<br />
This software is provided "AS IS," without a warranty of any kind. ALL<br />
EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND<br />
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF<br />
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-<br />
INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC.<br />
("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES<br />
SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR<br />
DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL<br />
SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR<br />
DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,<br />
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER <strong>CA</strong>USED AND<br />
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE<br />
OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN<br />
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.<br />
For inquiries please contact: Sun Microsystems, Inc. 4150 Network Circle, Santa<br />
Clara, California 95054.<br />
Tom Sawyer Layout Assistant<br />
END-USER LICENSE AGREEMENT FOR Tom Sawyer Software's Layout<br />
Assistant® SOFTWARE<br />
IMPORTANT—READ <strong>CA</strong>REFULLY. This Layout Assistant End-User License<br />
Agreement ("EULA") is a legal AGREEMENT between You, the Licensee (either<br />
as a registered individual user or as the registered user/representative on behalf<br />
of a single entity), and Tom Sawyer Software Corporation for the Layout<br />
Assistant software product identified above, which product includes computer<br />
software and the associated documentation ("SOFTWARE PRODUCT"). Unless<br />
You have a different license agreement signed by Tom Sawyer Software<br />
Corporation, your installing, copying, or otherwise using the SOFTWARE<br />
PRODUCT indicates You agree to be bound by all the terms of this EULA. If You<br />
do not agree to the terms of this EULA, then You MUST NOT copy, install, or use<br />
the SOFTWARE PRODUCT.<br />
SOFTWARE PRODUCT LICENSE<br />
The SOFTWARE PRODUCT is protected by copyright laws and international<br />
copyright treaties, as well as other intellectual property laws and treaties. The<br />
SOFTWARE PRODUCT is licensed, not sold.<br />
1) Grant of License<br />
This EULA grants You (the Licensee) the following rights:<br />
Applications Software<br />
Licenses for Third-Party Products F–13
Tom Sawyer Layout Assistant<br />
Tom Sawyer Software grants You the non-exclusive, non-sublicensable, limited<br />
license to use one copy of the SOFTWARE PRODUCT on a single computer,<br />
subject to the terms and conditions of this EULA. Any individual license for the<br />
SOFTWARE PRODUCT may not be shared or used concurrently or otherwise on<br />
different computers or by different users in a given organization.<br />
In return for our license grant, You hereby irrevocably grant to Tom Sawyer<br />
Software the non-exclusive, worldwide, fully-paid right to publicly disclose the<br />
fact that You are using the SOFTWARE PRODUCT, including but not limited to<br />
the reproduction and distribution of the software 'screen shots' and/or 'box<br />
shots' from your applications for Tom Sawyer Software's advertising and other<br />
promotional purposes.<br />
Storage/Network Use<br />
You may also store or install a copy of the SOFTWARE PRODUCT on a storage<br />
device, such as a network server, used only to install or run the SOFTWARE<br />
PRODUCT on your other computers over an internal network; however, you<br />
must acquire and dedicate a distinct license for each developer using the<br />
SOFTWARE PRODUCT from the storage device. Any given license for the<br />
SOFTWARE PRODUCT may not be shared or used concurrently or otherwise on<br />
different computers or by different developers in a given organization.<br />
License Pack<br />
If You have acquired this EULA in a Tom Sawyer Software Layout Assistant<br />
License Pack, You may install the number of additional copies of the<br />
SOFTWARE PRODUCT identified above on this EULA, and You may use each<br />
copy in the manner specified above.<br />
2) Description of Other Rights and Limitations<br />
F–14 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Tom Sawyer Layout Assistant<br />
You acknowledge that the SOFTWARE PRODUCT in source code form remains<br />
a confidential trade secret of Tom Sawyer Software, and therefore You agree not<br />
to reverse-engineer, decompile, or disassemble the SOFTWARE PRODUCT, or<br />
make any attempt to discover the source code to the SOFTWARE PRODUCT,<br />
except and only to the extent that such activity is expressly permitted by<br />
applicable law notwithstanding this limitation. Except as expressly permitted in<br />
this EULA, the SOFTWARE PRODUCT may not be used, copied, translated,<br />
redistributed, retransmitted, published, sold, rented, leased, marketed,<br />
sublicensed, pledged, assigned, disposed of, encumbered, transferred, altered,<br />
modified, or enhanced, whether in whole or in part, nor may You create<br />
derivative works from or based on the SOFTWARE PRODUCT. You may not<br />
remove any proprietary notices, marks, or labels from the SOFTWARE<br />
PRODUCT.<br />
The SOFTWARE PRODUCT is licensed as a single product and its components<br />
may not be separated for use on more than one computer.<br />
Termination<br />
Without prejudice to any of Tom Sawyer Software’s other rights, Tom Sawyer<br />
Software may terminate this EULA if You fail to comply with the terms and<br />
conditions of this EULA. In such event, You must destroy any and all copies of<br />
the SOFTWARE PRODUCT and all of its component parts; to this end You grant<br />
to Tom Sawyer Software the right to, with or without notice, monitor your<br />
Internet accessible activities for the purpose of verifying SOFTWARE PRODUCT<br />
performance and/or your compliance with the terms hereof, including, but not<br />
limited to the remote monitoring and verification of your implementation, use<br />
and duplication of the SOFTWARE PRODUCT.<br />
3) Upgrades<br />
You must currently be properly licensed to use the SOFTWARE PRODUCT in<br />
order to be eligible to purchase an upgrade. A SOFTWARE PRODUCT identified<br />
by Tom Sawyer Software as an upgrade replaces and/or supplements the<br />
product that formed the basis for your eligibility for such upgrade. You may use<br />
the resulting upgraded product only in accordance with the terms of this EULA.<br />
4) Copyright and Trademarks<br />
Licenses for Third-Party Products F–15
Tom Sawyer Layout Assistant<br />
All title, trademarks, and copyrights in and pertaining to the SOFTWARE<br />
PRODUCT (including but not limited to any images, photographs, animation,<br />
video, audio, music, text, and applets incorporated into the SOFTWARE<br />
PRODUCT) are owned by Tom Sawyer Software Corporation. The SOFTWARE<br />
PRODUCT is protected by copyright and trademark laws and international<br />
treaty provisions. The SOFTWARE PRODUCT is licensed, not sold. There is no<br />
transfer to You of any title or ownership of the SOFTWARE PRODUCT and the<br />
license granted under this EULA should not be construed as a sale of any right in<br />
the SOFTWARE PRODUCT. You must treat the SOFTWARE PRODUCT like any<br />
other copyrighted materials for archival purposes.<br />
You may not remove, modify or alter any Tom Sawyer Software copyright or<br />
trademark notice from any part of the SOFTWARE PRODUCT, including but not<br />
limited to any such notices contained in the electronic media or documentation,<br />
in the Layout Assistant Setup Wizard dialogue or 'about' boxes, in any of the<br />
runtime resources, and/or in any web-presence or web-enabled notices, code, or<br />
other embodiments originally contained in or dynamically or otherwise created<br />
by the SOFTWARE PRODUCT.<br />
5) Dual-Media Software<br />
You may receive the SOFTWARE PRODUCT in more than one medium.<br />
Regardless of the type or size of the medium You receive, You may use only that<br />
one medium that is appropriate for your single computer. You may not use or<br />
install the other medium on another computer, including but not limited to<br />
portable computers under the exclusive control of the registered developer. You<br />
may not loan, rent, lease, or otherwise transfer the other medium to another user.<br />
6) U.S. Government Restricted Rights<br />
The SOFTWARE PRODUCT and documentation are provided with<br />
RESTRICTED RIGHTS. Use, duplication, or disclosure by the U.S. Government is<br />
subject to restrictions as set forth in subparagraph C(1)(ii) of the subparagraphs<br />
(c) (1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR<br />
52.227-19, as applicable. Manufacturer is: Tom Sawyer Software Corporation,<br />
1625 Clay Street, Sixth Floor, Oakland, <strong>CA</strong> 94612, USA (or by FAX +1 510 208<br />
4371, e-mail to info@tomsawyer.com).<br />
7) Miscellaneous<br />
F–16 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Tom Sawyer Layout Assistant<br />
If You acquired or use this SOFTWARE PRODUCT in the United States, this<br />
EULA is governed by the laws of the State of California. If this SOFTWARE<br />
PRODUCT was acquired and is used exclusively outside of the United States, the<br />
local law may also apply. Should You have any questions concerning this EULA,<br />
or if You desire to contact Tom Sawyer Software for any reason, please write:<br />
Tom Sawyer Software Corporation, 1625 Clay Street, Sixth Floor, Oakland, <strong>CA</strong><br />
94612, USA (or by FAX +1 510 208 4371, e-mail to info@tomsawyer.com).<br />
8) Limited Warranty<br />
Limited Warranty Tom Sawyer Software warrants that for a period of thirty (30)<br />
days from the date of your original purchase ("warranty period") as evidenced<br />
by your receipt or other proof of purchase, the SOFTWARE PRODUCT, unless<br />
modified or otherwise altered by You, will perform substantially in accordance<br />
with the accompanying written materials.<br />
Tom Sawyer Software does not warrant that the SOFTWARE PRODUCT will<br />
meet your requirements or use of the SOFTWARE PRODUCT will be<br />
uninterrupted or error-free. Tom Sawyer Software is not responsible for<br />
problems caused by changes in the operating characteristics of computer<br />
hardware or computer operating systems which are made after the release of the<br />
SOFTWARE PRODUCT, nor for problems in the interactions of the SOFTWARE<br />
PRODUCT with non-Tom Sawyer Software products.<br />
Some jurisdictions do not allow limitations on duration of an implied warranty,<br />
so the above limitation may not apply to You. To the extent implied warranties<br />
may not be entirely disclaimed but implied warranty limitations are allowed by<br />
applicable law, implied warranties on the SOFTWARE PRODUCT, if any, are<br />
limited to thirty (30) days.<br />
THE ABOVE WARRANTIES ARE EXCLUSIVE. TO THE MAXIMUM EXTENT<br />
PERMITTED BY APPLI<strong>CA</strong>BLE LAW, TOM SAWYER SOFTWARE DISCLAIMS<br />
ALL OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESS OR<br />
IMPLIED, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES OF<br />
MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE, TITLE, AND<br />
NON-INFRINGEMENT, AND THOSE ARISING OUT OF USAGE OF TRADE<br />
OR COURSE OF DEALING, CONCERNING THE SOFTWARE PRODUCT. NO<br />
ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY TOM SAWYER<br />
SOFTWARE OR ITS EMPLOYEES SHALL INCREASE THE SCOPE OF THE<br />
ABOVE WARRANTIES OR CREATE ANY OTHER WARRANTIES.<br />
Customer Remedies<br />
Licenses for Third-Party Products F–17
Tom Sawyer Layout Assistant<br />
Tom Sawyer Software's entire liability, and your exclusive remedy, shall be, at<br />
Tom Sawyer Software's option, either (a) repair or replacement of the<br />
SOFTWARE PRODUCT that does not meet Tom Sawyer Software's Limited<br />
Warranty, or (b) return of the price paid, if any, and termination of this EULA.<br />
This remedy is subject to delivery to Tom Sawyer Software of a Tom Sawyer<br />
Software-approved "Affidavit of Destruction" together with proof of purchase<br />
within the Warranty Period. This Limited Warranty is void if failure of the<br />
SOFTWARE PRODUCT has resulted from accident, abuse or misapplication.<br />
Any replacement SOFTWARE PRODUCT will be warranted for the remainder of<br />
the original warranty period or fifteen (15) days, whichever is longer.<br />
9) Limitation of liability for damages<br />
REGARDLESS OF WHETHER ANY REMEDY SET FORTH HEREIN FAILS IN<br />
ITS ESSENTIAL PURPOSE, TO THE MAXIMUM EXTENT PERMITTED BY THE<br />
APPLI<strong>CA</strong>BLE LAW, IN NO EVENT SHALL TOM SAWYER SOFTWARE BE<br />
LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT<br />
LIMITATION, CONSEQUENTIAL, INCIDENTAL, INDIRECT, SPECIAL,<br />
ECONOMIC, PUNITIVE, OR SIMILAR DAMAGES, OR DAMAGES FOR LOSS<br />
OF BUSINESS PROFITS, LOSS OF GOODWILL, BUSINESS INTERRUPTION,<br />
COMPUTER FAILURE OR MALFUNCTION, LOSS OF BUSINESS<br />
INFORMATION, OR ANY AND ALL OTHER COMMERCIAL OR PECUNIARY<br />
DAMAGES OR LOSSES) ARISING OUT OF THE USE OF OR INABILITY TO<br />
USE THE SOFTWARE PRODUCT, HOWEVER <strong>CA</strong>USED AND ON ANY LEGAL<br />
THEORY OF LIABILITY (WHETHER IN TORT, CONTRACT, OR OTHERWISE),<br />
EVEN IF TOM SAWYER SOFTWARE HAS BEEN ADVISED OF THE<br />
POSSIBILITY OF SUCH DAMAGES, OR ANY CLAIM BY ANY OTHER PARTY.<br />
YOU ACKNOWLEDGE THAT THE LICENSE FEE REFLECTS THIS<br />
ALLO<strong>CA</strong>TION OF RISK.<br />
In any event, if any statute implies warranties or conditions not stated in this<br />
EULA, Tom Sawyer Software's entire liability under any provision of this EULA<br />
shall be limited to the greater of the amount actually paid by You to license the<br />
SOFTWARE PRODUCT or Five United States Dollars (US$5.00). Because some<br />
jurisdictions do not allow the exclusion or limitation of liability for consequential<br />
or incidental damages, the above limitation may not apply to You.<br />
F–18 <strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
Index<br />
.<br />
.dxc file type, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33<br />
.dxg file type, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33<br />
.dxi file type, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14<br />
.dxs file type, 2-4<br />
A<br />
abandon<br />
all operations, 3-24<br />
operation, 3-24<br />
abort associations, 3-18<br />
abstract object classes, 4-14<br />
access control permissions, 6-49<br />
access controls, 3-23<br />
aliases, 6-56<br />
dynamic, 6-50<br />
policy, 6-33, 6-34<br />
role-based, 6-53<br />
roles, 6-53<br />
routing, 6-57<br />
rule hierarchies, 6-37<br />
rules, 6-37<br />
secure proxy, 6-55<br />
static, 6-37<br />
access subdirectory, 2-2<br />
accounts<br />
suspending, 6-30<br />
add<br />
database user, 10-14<br />
administrative user<br />
defining, 6-42<br />
privileges, 6-47<br />
administrator, 6-12<br />
defining, 6-42<br />
Advantage Ingres errors, C-17<br />
agreement, 7-20<br />
get, 7-20<br />
set, 7-20<br />
alarm-log file, 3-8<br />
alarms, 3-5<br />
multiwrite queues, 7-12<br />
alert-log file, 3-8<br />
alias<br />
access controls, 6-56<br />
dangling aliases, C-16<br />
entry, 4-19<br />
errors, C-16<br />
integrity, 3-27, C-16<br />
invalid, 3-27<br />
name binding, 4-19<br />
allow-check-password trust flag, 3-53<br />
allow-downgrading trust flag, 3-53<br />
allow-upgrading trust flag, 3-53<br />
alt-name, 8-3<br />
anonymous bind, 6-11<br />
Apache Tomcat license agreement, F-1<br />
API (application program interface)<br />
UDDI, 14-3<br />
application program interface. See API<br />
arguments<br />
DXtools, 10-36<br />
assoc<br />
commands, 3-13<br />
configuration, 3-15<br />
Index–1
associations<br />
aborting, 3-18<br />
configuration, 5-7<br />
limiting, 3-18<br />
maximum times, 3-17<br />
queues, 3-19<br />
rejection, 3-18<br />
tracing, 3-16<br />
users, 3-16<br />
viewing, 3-16<br />
asynchronous<br />
multiwrite, 7-6<br />
attributes<br />
changing schema, 4-12<br />
checking, 4-7<br />
indexing, 3-30<br />
inherited rules, 4-7<br />
invalid, 4-7<br />
locally customized, 8-3<br />
multiple, 4-18<br />
read-only, 4-5, B-9<br />
sets, 4-8<br />
single-valued, 4-5<br />
syntax, 4-2, 4-6<br />
auditing<br />
monitoring, 9-2<br />
authentication<br />
conveying, 6-19, 6-20<br />
DISP, 6-16, 6-18<br />
distributed user, 6-15<br />
DSP, 5-6, 6-16, 6-18<br />
DSP link, 6-21<br />
setting levels, 6-11<br />
SSL, 6-13<br />
strong, 6-21<br />
user, 6-13<br />
auxiliary object classes, 4-15<br />
B<br />
backup a database, 10-7<br />
base-object searches, 3-33<br />
billing<br />
monitoring, 9-2<br />
bin directory, 2-2<br />
bind<br />
anonymous, 6-11<br />
control, 3-17<br />
DSP requests, 6-16<br />
maximum time, 3-17<br />
names, 4-18<br />
with credentials, 5-6<br />
bookmarks, 11-13<br />
bulk loading, 16-8<br />
C<br />
cache-only mode, 3-38<br />
configuring, 3-38<br />
example, 3-39<br />
caches, 3-32<br />
cache-only mode, 3-38<br />
configuring, 3-33<br />
enabling, 3-33<br />
example configuration, 3-36<br />
indexing, 3-34, 3-35<br />
load all attributes, 3-36<br />
maximum size, 3-35<br />
reverse-indexing, 3-36<br />
settings, 3-34<br />
synchronizing with database, 3-37<br />
viewing configuration, 3-37<br />
caching subordinate entries, 5-16<br />
certificates, 6-5<br />
generating, 10-21<br />
generation, 6-5<br />
reporting, 10-21<br />
certification<br />
language, 13-5, 14-6<br />
cert-log file, 3-9<br />
change control, 16-8<br />
changes in LDIF files, 10-33<br />
changing schema, 4-12<br />
characters<br />
non-English, 13-5, 14-6<br />
ciphers, 6-9<br />
clear<br />
dsas, 5-5<br />
indexes, 3-30<br />
Index–2<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
CLI, 2-14<br />
client encryption, 6-10<br />
close logtype, 3-11<br />
closing the management console, 2-15<br />
CMIP (Common Management Information Protocol),<br />
1-2, 3-22, 9-1<br />
agent, 9-8<br />
monitoring utility, 9-9<br />
X.700 management, 9-8<br />
cmip-psap, 9-8<br />
collective attributes, 3-40<br />
command-line<br />
interface, 2-14<br />
options, 2-9<br />
commands<br />
assoc, 3-13<br />
controlling output, 3-8<br />
DSP, 5-2<br />
DXserver, 2-11<br />
grouping by function, 2-11<br />
help, 2-20<br />
logs, 3-11<br />
oper, 3-20<br />
shortcuts, 2-21<br />
syntax, 2-12<br />
trace, 3-5, 3-6<br />
commands, access control<br />
set access-controls, 3-23<br />
set protected-items, 6-36<br />
set super-user, 6-41<br />
ssld, 6-6<br />
commands, associations<br />
abort, 3-18<br />
get assoc, 3-15<br />
get users, 3-16, 3-17, 3-18, 3-24, 9-2<br />
set allow-binds, 3-17<br />
set authentication, 3-17<br />
set credits, 3-19<br />
set max-bind-time, 3-17<br />
set max-users, 3-18<br />
set min-auth, 6-11<br />
set user-idle time, 3-18<br />
commands, CMIP<br />
cmip-psap, 9-8<br />
dxcmip, 9-9<br />
commands, DAP tools<br />
common argument, 10-36<br />
DXdelete, 10-42<br />
DXmodify, 10-39<br />
DXrename, 10-41<br />
DXsearch, 10-37<br />
commands, DB tools<br />
DXadduser, 10-14<br />
DXbackupdb, 10-7<br />
DXdeluser, 10-15<br />
DXdestroydb, 10-6<br />
DXdumpdb, 10-18<br />
DXemptydb, 10-6<br />
DXextenddb, 10-5<br />
DXgrantdb, 10-19<br />
DXindexdb, 10-10<br />
DXlistdb, 10-14<br />
DXloaddb, 10-16<br />
DXnewdb, 10-5<br />
DXnewdsa, 10-4<br />
DXrestoredb, 10-8<br />
DXstatdb, 10-13<br />
DXtunedb, 10-9<br />
DXupgradedb, 10-20<br />
commands, DIB<br />
clear indexes, 3-30<br />
get dib, 3-26<br />
set alias-integrity, 3-27<br />
set database-name, 2-23, 3-26<br />
set eis-count-attr, 3-28<br />
set index wide, 3-30<br />
set index-reverse, 3-30<br />
set not-searchable, 3-30<br />
commands, DISP<br />
disp update, 7-23<br />
get agreement, 7-20<br />
set agreement, 7-20, 7-21<br />
commands, DSAs<br />
set always-chain-down, 5-9<br />
set dsa, 3-1, 5-8, 5-10, 5-11, 5-12, 6-6, 7-23, 8-9<br />
set precedence, 5-19<br />
shutdown, 3-16<br />
commands, DSP<br />
clear dsas, 5-3, 5-5<br />
get dsp, 5-7<br />
get online dsas, 5-7<br />
get online-dsas, 5-5, 9-2<br />
set multi-casting, 5-6<br />
unbind, 5-3<br />
commands, LDIF tools<br />
csv2ldif, 10-30<br />
ldifdelta, 10-33<br />
Index–3
commands, local operations<br />
get oper, 3-22<br />
get stats, 3-22, 9-2<br />
reset stats, 3-22<br />
set max op-size, 3-23<br />
set max-local-ops, 3-23<br />
set max-op-size, 3-24<br />
set max-op-time, 3-24, 3-27<br />
commands, logs<br />
close logtype, 3-11<br />
echo, 3-12<br />
echo-off, 3-12<br />
echo-on, 3-12<br />
flush logtype, 3-11<br />
get log, 3-11<br />
set logtype, 3-11<br />
set summary-log, 3-12<br />
commands, multiwrite<br />
set multi-write-queue, 7-11<br />
commands, schema, 4-3<br />
get schema, 4-4<br />
set attribute, 4-4, 4-5, 4-8<br />
set attr-set, 4-8<br />
set name-binding, 4-18<br />
set object-class, 4-14<br />
set oid-prefix, 4-4<br />
commands, SCHEMA tools<br />
DXschemaldif, 10-44<br />
DXschematxt, 10-49<br />
ldif2dxc, 10-45<br />
commands, SNMP<br />
snmp-port, 9-5<br />
commands, traces<br />
set trace, 3-6, 3-16<br />
trace disable assoc, 3-16<br />
trace enable assoc, 3-16<br />
comments in script files, 2-13<br />
Common Management Information Protocol. See<br />
CMIP<br />
communication settings, view, 3-4<br />
complex queries, 5-24<br />
config directory, 2-2<br />
configuration<br />
DIB, 3-26<br />
DSP, 5-2<br />
file errors, 2-13<br />
file type, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33<br />
operations, 3-22<br />
server, 2-2<br />
configuration files, 1-3<br />
grouping, 2-6<br />
grouping commands, 2-11<br />
configuring<br />
another DXserver, 5-8<br />
DSP relay, 5-15<br />
first level DSA, 5-14<br />
management console, 2-16<br />
multiple local DSAs, 5-12, 5-14<br />
third-party DSAs, 5-4, 5-6, 5-10, 5-11<br />
connect times, 3-16<br />
connection<br />
address, 3-17<br />
information, 3-16<br />
remote, 5-4, 5-5, 5-16<br />
time, 3-17<br />
UDDI server, to, 14-5<br />
connect-log file, 3-9<br />
control<br />
binds, 3-17<br />
operations, 3-23, 3-24<br />
controlling<br />
operations, 3-23<br />
output, 3-8<br />
CPUs, multiple, 5-12<br />
creating a database, 10-5<br />
credentials, definition, 6-11<br />
credits, 3-19<br />
crypt password format, 3-29<br />
CSV data, 10-27<br />
csv2ldif, 10-27, 10-30<br />
D<br />
dangling alias, C-16<br />
DAP (<strong>Directory</strong> Access Protocol), 1-2<br />
database<br />
add user, 10-14<br />
backup, 10-7<br />
backups, 16-7<br />
Index–4<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
creation, 10-5<br />
data removal, 10-6<br />
delete user, 10-15<br />
destruction, 10-6<br />
hot swap, 2-23<br />
initializing, 2-22<br />
integrity, 4-2, C-17<br />
listing, 10-14<br />
massive, 5-12<br />
monitoring, 9-3<br />
multiple directory, 2-23<br />
name, 3-26<br />
restore, 10-8<br />
statistics, 10-13<br />
tailoring, A-1<br />
tuning, 10-9<br />
database subdirectory, 2-3<br />
debugging, 2-13<br />
default port numbers, 2-24<br />
defining<br />
local data types, 4-20, 8-4<br />
local schema, 4-20, 8-4<br />
users, 6-12<br />
delete<br />
database user, 10-15<br />
directory entries, 10-42<br />
Democorp sample DSA<br />
port number, 2-25<br />
destroying a database, 10-6<br />
DIB (<strong>Directory</strong> Information Base), 1-3, 3-25<br />
manage, 3-25<br />
directory<br />
delete entries, 10-42<br />
Information Shadowing Protocol (DISP), 7-20<br />
knowledge, 3-1<br />
modify, 10-39<br />
rename, 10-41<br />
samples, 1-4, 1-5, 15-13<br />
search, 10-37<br />
<strong>Directory</strong> Access Protocol. See DAP<br />
directory browser<br />
JXplorer, 11-1<br />
JXweb, 13-1<br />
directory entries, counting, 3-28<br />
<strong>Directory</strong> Information Base. See DIB<br />
<strong>Directory</strong> Information Shadowing Protocol. See DISP<br />
<strong>Directory</strong> System Protocol. See DSP<br />
<strong>Directory</strong> User Agent (DUA), 1-4<br />
disk space<br />
monitoring, 9-3<br />
DISP (<strong>Directory</strong> Information Shadowing Protocol), 1-2<br />
authentication, 6-16<br />
responder, 7-20<br />
update, 7-23<br />
display database statistics, 10-13<br />
distinguished name, 5-8<br />
relative, 5-14<br />
DIT (<strong>Directory</strong> Information Tree), 5-4<br />
definition, 5-8<br />
prefix, 5-4<br />
relay DSA, 5-16<br />
DSA<br />
caching entries, 5-16<br />
defining, 3-1<br />
first level, 5-14<br />
load-sharing, 5-20, 5-24<br />
local, 5-8, 5-10<br />
multiple local, 5-12, 5-14<br />
proxy, 5-9<br />
relay, 5-16<br />
shadow, 7-23<br />
stopping, 3-16<br />
third-party, 5-4, 5-6, 5-10, 5-11<br />
trust flags, 3-48<br />
DSA flags, 3-25, 3-52, 5-16, 7-23<br />
limit-list, 3-28<br />
limit-search, 3-29<br />
DSA processes, multiple, 2-22<br />
dsa, ssld-port, 6-6<br />
dsaEntriesTable, 9-4<br />
dsaIntTable, 9-4<br />
dsaOpsTable, 9-4<br />
dsp<br />
clear dsas, 5-2, 5-3<br />
get, 5-2<br />
set, 5-2<br />
unbind, 5-2<br />
unbind, 5-3<br />
DSP<br />
authentication, 6-18<br />
DSP (<strong>Directory</strong> System Protocol), 1-2<br />
Index–5
authentication, 5-6, 6-16, 6-18<br />
bind request, 6-16<br />
commands, 5-2<br />
configuration, 5-2, 5-7<br />
credentials, 5-6<br />
incoming credentials, 5-6<br />
monitoring connections, 5-7<br />
multiprocessing, 5-12<br />
outgoing connections, 5-5<br />
outgoing credentials, 5-6<br />
relay, 5-15<br />
dsp-ldap link flag, 3-54<br />
dsp-ldap-proxy link flag, 3-54<br />
dsp-ldapv2 link flag, 3-54<br />
DUA, 1-4<br />
dump, 10-1<br />
DXadduser, 10-14<br />
DXadmind<br />
port number, 2-24<br />
DXbackup, 16-7<br />
DXbackupdb, 10-7<br />
DXcache, 3-32<br />
cache-only mode, 3-38<br />
configuring, 3-33<br />
enabling, 3-33<br />
example configuration, 3-36<br />
indexing, 3-34, 3-35<br />
load all attributes, 3-36<br />
maximum size, 3-35<br />
reverse-indexing, 3-36<br />
settings, 3-34<br />
synchronizing, 3-37<br />
viewing configuration, 3-37<br />
DXcertgen, 10-21<br />
dxcmip, 9-9<br />
DXconsole, 2-14, 9-2<br />
DXdelete, 10-42<br />
DXdeluser, 10-15<br />
DXdestroydb, 10-6<br />
DXdisp, 10-20<br />
DXdumpdb, 10-18<br />
DXemptydb, 10-6<br />
DXextenddb, 10-5<br />
DXgrantdb, 10-19<br />
DXI configuration file, 3-32<br />
DXindexdb, 10-10<br />
DXlistdb, 10-14<br />
DXloaddb, 10-16<br />
DXmodify, 10-39<br />
DXnewdb, 10-5<br />
DXnewdsa, 10-4<br />
DXrename, 10-41<br />
DXrestoredb, 10-8<br />
DXschemaldif tool, 10-44<br />
DXschematxt tool, 10-49<br />
DXsearch, 10-37<br />
DXserver, 1-2<br />
alarms, C-7<br />
commands, 2-11<br />
configuring SSL, 6-6<br />
logs, C-2<br />
version, 2-10<br />
warning messages, C-13<br />
dxsnmp, 9-6<br />
DXstatdb, 9-3, 10-13<br />
DXsyntax tool, 10-50<br />
DXtools, 1-3, 7-26<br />
csv2ldif, 10-30<br />
DXadduser, 10-14<br />
DXbackupdb, 10-7<br />
DXcertgen, 10-21<br />
DXdelete, 10-42<br />
DXdeluser, 10-15<br />
DXdestroydb, 10-6<br />
DXdisp, 10-20<br />
DXdumpdb, 10-18<br />
DXemptydb, 10-6<br />
DXextenddb, 10-5<br />
DXgrantdb, 10-19<br />
DXindexdb, 10-10<br />
DXlistdb, 10-14<br />
DXloaddb, 10-16<br />
DXmodify, 10-39<br />
DXnewdb, 10-5<br />
DXnewdsa, 10-4<br />
Index–6<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
DXrename, 10-41<br />
DXrestoredb, 10-8<br />
DXschemaldif, 10-44<br />
DXschematxt, 10-49<br />
DXsearch, 10-37<br />
DXstatdb, 10-13<br />
DXtunedb, 10-9<br />
DXupgradedb, 10-20<br />
ldif2dxc, 10-45<br />
ldifdelta, 10-33<br />
DXtunedb, 10-9, 16-8<br />
DXupgradedb, 10-20<br />
DXweb server, 1-5<br />
DXwebserver<br />
port number, 2-24<br />
dynamic access controls, 6-50<br />
dynamic groups, 3-40<br />
E<br />
echo command, 3-12<br />
embedded installation<br />
on Windows, D-17<br />
emptying a database, 10-6<br />
encryption<br />
client, 6-10<br />
DSA to DSA, 6-10<br />
error logs, C-1<br />
error messages<br />
search overflow, 3-31<br />
errors<br />
configuration file, 2-13<br />
ldif2dxc tool, 10-46<br />
script file, 2-13<br />
statistics, 3-22<br />
event logs, C-1<br />
events, 3-22<br />
export, 10-1<br />
F<br />
failover<br />
multiwrite, 7-9<br />
file descriptors, 3-18, 16-10<br />
file extensions<br />
dxc, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33<br />
dxg, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33<br />
dxi, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14<br />
dxs, 2-4<br />
files<br />
configuration, 1-3<br />
launch, 11-22<br />
types, 2-4<br />
firewall, 5-9<br />
alternative network addresses, 5-10<br />
flush logtype, 3-11<br />
forward requests, 5-15<br />
G<br />
generating certificates, 10-21<br />
get<br />
assoc, 3-15<br />
dib, 3-25, 3-26<br />
dsp, 5-3, 5-7<br />
log, 3-11<br />
online-dsas, 5-5, 5-7, 9-2<br />
oper, 3-22<br />
operations, 3-21<br />
schema, 4-3, 4-4<br />
stats, 3-22, 9-2<br />
users, 3-16, 3-17, 3-18, 3-24, 9-2<br />
group<br />
configuration files, 2-6<br />
file type, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33<br />
group membership, 3-40<br />
groups<br />
dynamic, 3-40<br />
hybrid, 3-41<br />
static, 3-40<br />
guard, 5-9, 7-23<br />
Index–7
H<br />
help command, 2-20<br />
history files, 3-12<br />
hot swap, 2-23<br />
hybrid<br />
groups, 3-41<br />
I<br />
IA5 string, 4-7<br />
idle times, 3-16<br />
maximum, 3-18<br />
IETF, 4-1<br />
impersonation protection, 6-22<br />
import, 10-1<br />
import data, 3-23<br />
increased user counts, 2-22<br />
indexing<br />
commands, 3-30<br />
for caches, 3-35<br />
options, 3-30<br />
reverse, 3-36<br />
wide indexes, 3-31<br />
initialization<br />
file, 2-5<br />
file type, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14<br />
server, 2-9<br />
initializing multiwrite–DISP recovery, 10-20<br />
initiator, 7-21<br />
install directory, 2-3<br />
Installation<br />
logging on Windows, D-3, E-3<br />
installation code, D-17, E-24<br />
installing <strong>eTrust</strong> <strong>Directory</strong><br />
for Windows, D-1, E-1<br />
installing silently<br />
on Windows, D-14<br />
installing the sample tools<br />
on Windows, D-9, E-17<br />
invalid<br />
aliases, 3-27<br />
attribute, 4-7<br />
ISO 9594-10, 9-8<br />
J<br />
JXplorer, 11-1<br />
add audio file, 11-22<br />
add entry, 11-23<br />
add photo, 11-21<br />
binary values, 11-20<br />
browse, 11-7<br />
button bar, 11-5<br />
connect, 11-7<br />
display enries, 11-9<br />
edit the directory, 11-16<br />
file launch, 11-22<br />
LDIF files, 11-25<br />
managing certificates, 11-28<br />
menu bar, 11-3<br />
modify attributes, 11-18<br />
navigate, 11-8<br />
quick search bar, 11-6<br />
refresh entries, 11-11<br />
search, 11-11<br />
SSL and SASL, 11-27<br />
submit entry, 11-24<br />
templates, 11-9<br />
JXweb<br />
connect to a directory, 13-3<br />
display directory information, 13-4<br />
K<br />
knowledge, 3-1, 6-5<br />
directory, 2-3, 3-1<br />
references, 5-3<br />
knowledge flags, 3-48<br />
L<br />
language certification, 13-5, 14-6<br />
LDAP (Lightweight <strong>Directory</strong> Access Protocol), 1-2<br />
Index–8<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
managing, 8-3<br />
names, 4-5, 4-8<br />
servers, 8-9<br />
LDAP attributes<br />
changing, 4-12<br />
LDAP port number, 8-2<br />
ldap-dsa-name, 8-7<br />
ldap-dsa-password, 8-7<br />
LDIF<br />
format, 10-29<br />
tools, 10-27<br />
LDIF file<br />
calculating changes, 10-33<br />
sort, 10-31<br />
template file, 10-28<br />
ldif2dxc tool, 10-45<br />
error handling, 10-46<br />
OID maps, 10-47<br />
schema.txt file update, 10-47<br />
ldifdelta, 10-33<br />
ldifsort, 10-31<br />
LDT file, 10-28<br />
LDUA, 1-4<br />
license agreement<br />
Apache Tomcat, F-1<br />
OpenLDAP, F-4<br />
OpenSSL, F-6<br />
SUN Java Web Services, F-8<br />
Lightweight <strong>Directory</strong> Access Protocol. See LDAP<br />
limiting associations, 3-18<br />
limiting searches to simple only, 3-29<br />
limit-list DSA flag, 3-52<br />
limits subdirectory, 2-3<br />
limit-search DSA flag, 3-52<br />
link flags, 3-54<br />
list<br />
existing databases, 10-14<br />
listen address for LDAP requests, 8-2<br />
listen address for SNMP requests, 9-5<br />
listening address, 2-22, 3-4, 7-20, 8-2<br />
load sharing, 2-22, 5-12<br />
DSA, 5-20, 5-24<br />
load-share DSA flag, 3-52<br />
local<br />
attributes, 4-20, 8-4<br />
data type definition, 4-20, 8-4<br />
DSAs, 5-8, 5-10<br />
schema, 4-20, 8-4<br />
local operations, 3-20<br />
locking a password, 6-30<br />
log files<br />
alarm-log, 3-8<br />
alert-log, 3-8<br />
cert-log, 3-9<br />
closing, 3-11<br />
commands, 3-11<br />
connect-log, 3-9<br />
flush, 3-11<br />
monitoring, 9-2<br />
opening, 3-11<br />
query-log, 3-9<br />
stats-log, 3-9<br />
summary, 3-12<br />
summary-log, 3-10<br />
trace-log, 3-10<br />
types, 3-8<br />
update-log, 3-10<br />
viewing, 3-11<br />
Logging<br />
installation on Windows, D-3, E-3<br />
logging subdirectory, 2-3<br />
login entries, 6-48<br />
logs directory, 2-3<br />
M<br />
management console, 2-14, 2-16<br />
closing, 2-15<br />
configuration, 2-16<br />
opening, 2-14<br />
Management Information Base. See MIB<br />
managing<br />
large numbers of entries, 16-11<br />
large numbers of users, 16-10<br />
LDAP, 8-3<br />
Index–9
telnet configuration, 2-16<br />
mapping, prefixes, 8-9<br />
matching rules, 4-6<br />
may-contain, 4-14<br />
md5 password format, 3-29<br />
members of groups, 3-40<br />
memory<br />
maximum size of cache, 3-35<br />
merge, 10-1<br />
MIB (Management Information Base), 3-22, 9-4<br />
MIB walker, 9-6<br />
migration path, 10-1<br />
modify<br />
directory, 10-39<br />
monitoring<br />
active users, 3-17<br />
CMIP, 9-9<br />
databases, 9-3<br />
disk space, 9-3<br />
DSP, 5-7<br />
dxconsole, 9-2<br />
log files, 9-2<br />
ms-ad DSA flag, 3-52<br />
ms-ad link-flag, 3-54<br />
ms-exchange link-flag, 3-54<br />
multicasting, 5-6, 5-13<br />
multiple<br />
DSA processes, 2-22<br />
multiwrite<br />
asynchronous, 7-6<br />
enabling, 7-9<br />
retry interval, 7-10<br />
multi-write DSA flag, 3-52<br />
multiwrite failover, 7-9<br />
multiwrite groups, 7-7<br />
setting up, 5-23, 7-9<br />
multiwrite queues<br />
alarms, 7-12<br />
size, 7-11<br />
multiwrite replication, 7-5<br />
multiwrite status, 7-12<br />
multi-write-async DSA flag, 3-52<br />
multiwrite–DISP recovery, 10-20<br />
multi-write-disp-queue DSA flag, 3-52<br />
multi-write-notify DSA flag, 3-52<br />
must-contain, 4-14<br />
N<br />
name, 8-3<br />
name binding, 4-18<br />
aliases, 4-19<br />
checks, 4-18<br />
considerations, 4-19<br />
rules, 4-18<br />
structural object classes, 4-19<br />
native-prefix, 8-9<br />
no compatible link type, 6-21<br />
non-English characters, 13-5, 14-6<br />
no-routing-ac DSA flag, 3-52<br />
North American <strong>Directory</strong> Forum, 4-1<br />
no-server-credentials trust flag, 3-53<br />
nsap, 3-3<br />
O<br />
object class, 4-14<br />
checking, 4-15, 4-16<br />
kinds, 4-14<br />
abstract, 4-14<br />
auxiliary, 4-15<br />
structural, 4-15<br />
pruning, 4-17<br />
replacing, 4-17<br />
object identifier (OID), 4-4<br />
oem-encrypt password format, 3-29<br />
oem-hash password format, 3-29<br />
OID prefix, 4-4<br />
one-level searches, 5-16<br />
Index–10<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
opening the managment console, 2-14<br />
OpenLDAP license agreement, F-4<br />
OpenSSL license agreement, F-6<br />
oper commands, 3-20<br />
operations, 3-22<br />
abandon, 3-24<br />
configuration, 3-22<br />
control, 3-23, 3-24<br />
controlling, 3-23<br />
remote, 5-17<br />
statistics, 3-22<br />
output, controlling, 3-8<br />
P<br />
parallel processing, 5-12<br />
parameters<br />
get assoc command, 3-15<br />
get dib command, 3-25<br />
get dsp command, 5-3<br />
get operations command, 3-21<br />
get schema command, 4-3<br />
oper command, 3-21<br />
resetting SSLD, 6-8<br />
set assoc command, 3-13, 7-21<br />
set dib command, 3-25<br />
set dsa command, 3-3<br />
set dsp command, 5-2<br />
set operations command, 3-20<br />
set schema command, 4-3<br />
password, 3-23<br />
attribute, 6-12<br />
expiry, 6-28<br />
protection, 6-24, 6-48<br />
reset, 6-24<br />
passwords<br />
locking, 6-30<br />
storage formats, 3-29<br />
performance, 5-12, 10-9<br />
degradation, 6-35<br />
tuning, 16-8<br />
permissions, 6-37, 6-49<br />
personality, 6-5<br />
certificate generation, 6-5<br />
pid directory, 2-3<br />
port numbers, 2-24<br />
LDAP, 8-2<br />
setting with set dsa command, 3-4<br />
preferredDelivery, 4-6<br />
prefix<br />
mapping, 8-9<br />
schema, 4-4, 4-5<br />
presentationAddress, 4-6<br />
printable character, 4-7<br />
privileges, 6-47<br />
protected item, 6-42, 6-44<br />
defining, 6-47<br />
protocol tracing, 3-7<br />
prototyping, 10-1<br />
proxy<br />
DSAs, 5-9<br />
secure, 6-55<br />
public users, defining, 6-46<br />
Q<br />
query streaming, 5-24<br />
query-log file, 3-9<br />
R<br />
RAM<br />
maximum size of cache, 3-35<br />
RDBMS<br />
tools, 1-5<br />
read<br />
privileges, 6-44<br />
unrestricted, 6-41<br />
read-only access, 6-46<br />
read-only attributes, 4-5, B-9<br />
read-only DSA flag, 3-52<br />
recovery<br />
multiwrite–DISP, 10-20<br />
Index–11
eferences, 5-3<br />
referrals, 5-9<br />
registered users, 6-44<br />
relative distinguished name, 5-14<br />
relay, 7-21<br />
DSA, 5-16<br />
DSP, 5-15<br />
relay DSA flag, 3-52<br />
reload, 10-1<br />
remote connections, 5-4, 5-5, 5-16<br />
remote operations, 5-17<br />
rename a directory, 10-41<br />
replication<br />
clock synchronization, 7-4<br />
directory, 2-3<br />
multiwrite, 7-5<br />
using DXtools, 7-26<br />
repository, UDDI, 14-1<br />
reset stats, 3-22<br />
resetting SSLD parameters, 6-8<br />
resetting statistics, 3-22<br />
responder, 7-21<br />
restore a database, 10-8<br />
retry interval for multiwrite, 7-10<br />
return attribute lists, 11-12<br />
reverse-indexing, 3-36<br />
RFC1567, 9-4<br />
roles, access controls, 6-53<br />
Router sample DSA<br />
port number, 2-25<br />
rules, 6-34<br />
components, 6-37<br />
S<br />
samples directory, 1-4, 1-5, 2-3, 15-13<br />
schema<br />
commands, 4-3<br />
defining local, 4-20<br />
definition, 4-1<br />
directory, 2-3<br />
local, 4-20, 8-4<br />
management, 4-3<br />
prefixes, 4-4, 4-5<br />
published, 4-20<br />
validation, 4-2<br />
viewing, 4-4<br />
SCHEMA tools, 10-43<br />
DXschemaldif, 10-44<br />
DXschematxt, 10-49<br />
ldif2dxc, 10-45<br />
script file<br />
description, 2-13<br />
errors, 2-13<br />
type, 2-4<br />
search<br />
a directory, 10-37<br />
complex, 11-11<br />
indexes, 3-30<br />
quick, 11-11<br />
return attribute lists, 11-12<br />
templates, 11-12<br />
search overflow error message, 3-31<br />
searches<br />
limiting to simple only, 3-29<br />
simple, 5-25<br />
searching<br />
base-object, 3-33<br />
secure proxy, 6-55<br />
Secure Socket Layer, 6-2<br />
security, 5-12<br />
security level, 3-23, 3-24, 3-28<br />
server<br />
configuration, 2-2<br />
DXweb, 1-5<br />
initialization, 2-9<br />
UDDI, 14-3<br />
servers subdirectory, 2-3<br />
service<br />
errors, C-17<br />
service error<br />
administration limit exceeded, 3-24<br />
operation abandoned, 3-24<br />
Index–12<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
set<br />
schema, 4-3<br />
set commands<br />
assoc, 3-13, 7-21<br />
dib, 3-25<br />
dsp, 5-2<br />
operations, 3-20<br />
set commands, access control<br />
access-controls, 3-23<br />
protected-items, 6-36<br />
super-user, 6-41<br />
set commands, associations<br />
allow-binds, 3-17<br />
authentication, 3-17<br />
credits, 3-19<br />
max-bind-time, 3-17<br />
max-users, 3-18<br />
min-auth, 6-11<br />
user-idle-time, 3-18<br />
set commands, DIB<br />
alias-integrity, 3-27<br />
database-name, 2-22, 2-23, 3-26<br />
eis-count-attr, 3-28<br />
index-reverse, 3-30<br />
index-wide, 3-30<br />
not-searchable, 3-30<br />
set commands, DISP<br />
agreement, 7-21<br />
set commands, DSAs<br />
always-chain-down, 5-9<br />
dsa, 3-1, 5-8, 5-10, 5-11, 5-12, 6-6, 7-23, 8-9<br />
precedence, 5-19<br />
set commands, DSP<br />
multi-casting, 5-6<br />
set commands, local operations<br />
max-local-ops, 3-23<br />
max-op-size, 3-23, 3-24<br />
max-op-time, 3-24, 3-27<br />
set commands, logs<br />
logtype, 3-11<br />
summary-log, 3-12<br />
set commands, mutliwrite<br />
multi-write-queue, 7-11<br />
set commands, schema<br />
attribute, 4-5<br />
attribute, 4-4, 4-8<br />
attr-set, 4-8<br />
name-binding, 4-18<br />
object-class, 4-14<br />
oid-prefix, 4-4<br />
set commands, traces<br />
trace, 3-6<br />
settings subdirectory, 2-3<br />
sha-1 password format, 3-29<br />
shadow DSA flag, 3-52<br />
shadow DSAs, 7-23<br />
shortcuts for commands, 2-21<br />
shutdown command, 3-16<br />
silent installation<br />
on Windows, D-14<br />
Simple Network Management Protocol. See SNMP<br />
simple queries, 5-24<br />
simple searches, 5-25<br />
single-valued attributes, 4-5<br />
SNMP (Simple Network Management Protocol), 1-2,<br />
3-22, 9-1<br />
MIB walker, 9-6<br />
SNMP monitoring<br />
port number, 2-25<br />
SNMP port number, 9-5<br />
snmp-port, 9-5<br />
sort an LDIF file, 10-31<br />
ssha-1 password format, 3-29<br />
SSL<br />
authentication, 6-13<br />
configuring DXserver, 6-6<br />
connections, 6-4<br />
daemon, 6-3<br />
enabling, 6-2<br />
SSL/TLS connections<br />
ciphers, 6-9<br />
SSLD, 6-3<br />
configuring, 6-6<br />
port number, 2-24<br />
SSLD example<br />
ciphers for SSL/TLS connections, 6-9<br />
four threads, 6-9<br />
SSLD parameters<br />
Index–13
esetting, 6-8<br />
ssl-encryption link-flag, 3-54<br />
ssl-encryption-remote link-flag, 3-54<br />
static access controls, 6-37<br />
static groups, 3-40<br />
statistics<br />
monitoring, 9-2<br />
resetting, 3-22<br />
traced, 3-7<br />
viewing, 3-22<br />
stats-log file, 3-9<br />
statuses<br />
multiwrite, 7-12<br />
stopping DSAs, 3-16<br />
strategy, 7-21, 7-22<br />
string labels, 8-3<br />
strong authentication, 6-21<br />
structural object classes, 4-15<br />
summary-log file, 3-10<br />
SUN Java Web Services license agreement, F-8<br />
superuser<br />
password, 6-12<br />
privileges, 6-47<br />
suspend a user’s account, 6-30<br />
synchronization, replication, 7-4<br />
syntax<br />
attribute, 4-2, 4-6<br />
commands, 2-12<br />
undefined, 4-6<br />
T<br />
telephoneNumber, 4-6<br />
teletexTerminalId, 4-6<br />
telexNumber, 4-6<br />
telnet, 9-1<br />
template file, 10-28<br />
timeouts, 3-22<br />
tModels, 14-5<br />
Tomcat port number, 2-24<br />
tools<br />
csv2ldif, 10-30<br />
DXadduser, 10-14<br />
DXbackupdb, 10-7<br />
DXcertgen, 10-21<br />
DXdelete, 10-42<br />
DXdeluser, 10-15<br />
DXdestroydb, 10-6<br />
DXdisp, 10-20<br />
DXdumpdb, 10-18<br />
DXemptydb, 10-6<br />
DXextenddb, 10-5<br />
DXgrantdb, 10-19<br />
DXindexdb, 10-10<br />
DXlistdb, 10-14<br />
DXloaddb, 10-16<br />
DXmodify, 10-39<br />
DXnewdb, 10-5<br />
DXnewdsa, 10-4<br />
DXrename, 10-41<br />
DXrestoredb, 10-8<br />
DXschemaldif, 10-44<br />
DXschematxt, 10-49<br />
DXsearch, 10-37<br />
DXstatdb, 10-13<br />
DXtunedb, 10-9<br />
DXupgradedb, 10-20<br />
ldif2dxc, 10-45<br />
ldifdelta, 10-33<br />
RDBMS, 1-5<br />
trace<br />
command, 3-5, 3-6<br />
protocol, 3-7<br />
statistics, 3-7<br />
trace-log file, 3-10<br />
tracing, 3-5<br />
associations, 3-16<br />
transparent routing, 5-15<br />
trust flags, 3-53<br />
trust subdirectory, 2-3<br />
trust-conveyed-originator trust flag, 3-53<br />
tuning a database, 10-9<br />
Index–14<br />
<strong>eTrust</strong> <strong>Directory</strong> <strong>Administrator</strong> <strong>Guide</strong>
U<br />
UDDI (Universal Description, Discovery and<br />
Integration), 14-1<br />
API, 14-3<br />
UDDI Client, 14-4<br />
UDDI registries, 14-1<br />
tModels, 14-5<br />
UDDI Server, 14-3<br />
UDDI servers, 14-3<br />
connecting to, 14-5<br />
unavailable link-flag, 3-54<br />
unbind, outgoing connections, 5-5<br />
undefined syntax, 4-6<br />
Universal Description, Discovery and Integration. See<br />
UDDI<br />
unrestricted read, 6-41<br />
UNSPSC sample DSA<br />
port number, 2-25<br />
update access, 6-41<br />
update error, naming violation, 4-18<br />
update requests, 5-24<br />
update-log file, 3-10<br />
upgrading Advantage Ingres, D-4, E-4<br />
URL pages, launching of, 11-33<br />
user accounts<br />
suspending, 6-30<br />
users<br />
administrative, 6-12, 6-42<br />
associations, 3-16<br />
authentication, 6-13<br />
conveying authentication, 6-19, 6-20<br />
current, 3-24<br />
defining, 6-12<br />
defining superusers, 6-41<br />
distributed, 6-15<br />
limit in associations, 3-18<br />
managing large numbers, 16-10<br />
maximum number to bind, 3-18<br />
V<br />
monitoring, 3-17<br />
name, 3-17<br />
number of, 3-17<br />
public, 6-46<br />
registered, 6-44<br />
superusers, 6-12, 6-41<br />
version, 2-10<br />
viewing<br />
assoc configuration, 3-15<br />
associations, 3-16<br />
communication settings, 3-4<br />
DIB configuration, 3-26<br />
DSP configuration, 5-7<br />
operation configuration, 3-22<br />
operation statistics, 3-22<br />
schema, 4-4<br />
virtual attributes, 3-40<br />
W<br />
wide indexes, 3-31<br />
X<br />
X.435, 4-1<br />
X.500<br />
guard, 5-9, 7-23<br />
information types, 4-2<br />
object class kinds, 4-14<br />
schema, 4-2<br />
tracing, 3-16<br />
X.509 certificates, 6-2<br />
X.520<br />
attribute syntax, 4-6<br />
attributes, 4-5<br />
X.521, object classes, 4-14<br />
Index–15