eTrust Directory Administrator Guide

Transcription

eTrust Directory

Administrator Guide
r8, Service Pack 1
G00505-4E
This documentation and related computer software program (hereinafter referred to as the “Documentation”) is for
the end user’s informational purposes only and is subject to change or withdrawal by Computer Associates
International, Inc. (“CA”) at any time.
This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without
the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright
laws of the United States and international treaties.
Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for
their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only
authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the
license for the software are permitted to have access to such copies.
This right to print copies is limited to the period during which the license for the product remains in full force and
effect. Should the license terminate for any reason, it shall be the user’s responsibility to return to CA the reproduced
copies or to certify to CA that same have been destroyed.
To the extent permitted by applicable law, CA provides this documentation “as is” without warranty of any kind,
including without limitation, any implied warranties of merchantability, fitness for a particular purpose or
noninfringement. In no event will CA be liable to the end user or any third party for any loss or damage, direct or
indirect, from the use of this documentation, including without limitation, lost profits, business interruption,
goodwill, or lost data, even if CA is expressly advised of such loss or damage.
The use of any product referenced in this documentation and this documentation is governed by the end user’s
applicable license agreement.
The manufacturer of this documentation is Computer Associates International, Inc.
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
DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.
 2005 Computer Associates International, Inc.
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Contents
Chapter 1: Introduction
eTrust Directory Modules .....................................................................
DXserver .................................................................................
The Relational Database Management System (RDBMS) ......................................
Configuration Files ........................................................................
DXtools ..................................................................................
Samples ..................................................................................
RDBMS Tools .............................................................................
DXwebserver .............................................................................
eTrust Directory Glossary .....................................................................
1-2
1-2
1-3
1-3
1-3
1-4
1-5
1-5
1-6
Chapter 2: DXserver Overview
What is DXserver? ............................................................................ 2-1
DXserver Configuration Files .................................................................. 2-2
DXserver File Directories .................................................................. 2-2
Sample Configuration Files ................................................................ 2-4
Configuration File Types .................................................................. 2-4
The Initialization File ...................................................................... 2-5
Configuration Grouping Files .............................................................. 2-6
Knowledge Files .......................................................................... 2-7
DXserver Commands ......................................................................... 2-9
The dxserver Command - Install, Start, or Stop the DXserver .................................. 2-9
DXserver Script Language .................................................................... 2-11
Configuration Files ....................................................................... 2-11
Command Syntax ........................................................................ 2-12
Script Files .............................................................................. 2-13
Script File Errors and Debugging .......................................................... 2-13
DXconsole .................................................................................. 2-14
DXconsole Security....................................................................... 2-14
Opening DXconsole ...................................................................... 2-14
Contents
iii
Closing DXconsole........................................................................ 2-15
Configuring DXconsole ................................................................... 2-16
Help Command .......................................................................... 2-21
Command Shortcuts ...................................................................... 2-22
Databases ................................................................................... 2-23
Multiple DSA Processes to One DIT/DIB ................................................... 2-23
Multiple Directory Databases on One Machine .............................................. 2-24
Hot Swap ................................................................................ 2-24
Port Numbers Used by eTrust Directory ........................................................ 2-25
Ports Used by eTrust Directory Components ................................................ 2-25
Ports Used by Sample Tools and Sample DSAs .............................................. 2-26
Chapter 3: General Administration
Defining DSAs with the set dsa Command ....................................................... 3-1
The set dsa Command Syntax ............................................................... 3-2
The set dsa Command Parameters .......................................................... 3-3
Setting DSA Port Numbers ................................................................. 3-4
Viewing Communications Settings .......................................................... 3-4
Alarms, Traces, and Logs ...................................................................... 3-5
Alarms ................................................................................... 3-5
Traces .................................................................................... 3-5
Logs...................................................................................... 3-8
Associations ................................................................................. 3-13
The assoc Command Options .............................................................. 3-13
Viewing Association Configuration ........................................................ 3-15
Viewing Associations ..................................................................... 3-16
Tracing Associations ...................................................................... 3-16
Stopping a DSA .......................................................................... 3-16
Association Times ........................................................................ 3-17
Controlling Binds ......................................................................... 3-17
Aborting Associations .................................................................... 3-18
Concurrent Associations .................................................................. 3-18
Association Queues ....................................................................... 3-19
Local Operations ............................................................................. 3-20
The oper Commands...................................................................... 3-20
Viewing Operation Configuration .......................................................... 3-22
Viewing Operation Statistics ............................................................... 3-22
Concurrent Operations .................................................................... 3-23
Administration Limits .................................................................... 3-23
Operational Attributes .................................................................... 3-23
iv
Access Controls ..........................................................................
Read Only ...............................................................................
Abandoning Operations ..................................................................
The Directory Information Base ...............................................................
Viewing DIB Configuration ...............................................................
Database Name ..........................................................................
Manage Connections to the Database ......................................................
Alias Integrity ...........................................................................
Counting Entries .........................................................................
Rejecting All list Commands ..............................................................
Rejecting All Unfiltered Searches ..........................................................
Password Storage ........................................................................
Indexing Options ........................................................................
DXcache ....................................................................................
How DXcache Works .....................................................................
Design the DXcache System ...............................................................
Enable and Configure DXcache ............................................................
View the DXcache Configuration ..........................................................
Keep DXcache Synchronized with the Database .............................................
Use eTrust Directory in Cache-Only Mode..................................................
Virtual Attributes ............................................................................
Dynamic Groups .........................................................................
Class of Service Templates ................................................................
Knowledge Flags ............................................................................
The Three Kinds of Knowledge Flags ......................................................
List of all DSA Flags ......................................................................
List of all Trust Flags .....................................................................
List of all Link Flags ......................................................................
3-23
3-24
3-24
3-25
3-26
3-26
3-27
3-27
3-28
3-28
3-29
3-29
3-30
3-32
3-32
3-33
3-33
3-37
3-37
3-38
3-40
3-40
3-43
3-48
3-48
3-52
3-53
3-54
Chapter 4: Schema Definition
Configuring Schema ..........................................................................
Grouping Schema .........................................................................
Managing Schema ........................................................................
Schema Commands .......................................................................
Viewing Schema ..........................................................................
Schema Prefixes...........................................................................
Attributes ....................................................................................
Attribute Syntaxes ........................................................................
Attribute Checking ........................................................................
Syntax Aliases for Unsupported Attribute Syntax ............................................
Contents
4-2
4-2
4-3
4-3
4-4
4-4
4-5
4-6
4-7
4-7
v
Attribute Sets ............................................................................. 4-8
Attribute Names .......................................................................... 4-8
Unique Attributes ......................................................................... 4-9
Changing the Schema Definition for Attributes in Use........................................ 4-12
Object Classes ................................................................................ 4-14
Object Class Kind ......................................................................... 4-14
Object Class Checking .................................................................... 4-15
Object Class Storage ...................................................................... 4-16
Name Bindings .............................................................................. 4-18
Name Binding Checks .................................................................... 4-18
Name Bindings and Structural Object Classes ............................................... 4-19
Name Bindings and Aliases ............................................................... 4-19
Considerations for Schemas that Do Not Support Name Binding .............................. 4-19
Defining Local Schema........................................................................ 4-20
Chapter 5: Distribution and DSP
Managing DSP ................................................................................ 5-2
DSP Command Options .................................................................... 5-2
Knowledge References ..................................................................... 5-3
Remote Operations ........................................................................ 5-4
Limiting Remote Operations ................................................................ 5-4
Remote Connections ....................................................................... 5-5
Unbinding Remote Connections ............................................................ 5-5
Incoming DSP Credentials .................................................................. 5-6
Outgoing DSP Credentials.................................................................. 5-6
Distributed Searches (Multi-Chaining) ....................................................... 5-6
Limiting Multi-Chaining ................................................................... 5-6
Viewing DSP Configuration ................................................................ 5-7
Configuring a DSA ............................................................................ 5-8
Configuring a Subordinate DSA ............................................................ 5-8
Proxy DSAs ............................................................................... 5-9
Configuring Another DXserver ................................................................ 5-10
Configuring Alternative Network Addresses ................................................ 5-10
Configuring a Third-party DSA ............................................................ 5-11
DXlink .................................................................................. 5-11
Configuring Multiple Local DSAs .......................................................... 5-12
Configuring a Domain of DXservers ........................................................... 5-13
A Domain of DXservers ................................................................... 5-13
Sharing DXserver Configuration ........................................................... 5-14
Configuring a First-level DSA.............................................................. 5-14
vi
Configuring a Router DSA ................................................................
Transparent Routing .....................................................................
Configuring a Relay DSA .................................................................
Caching Entries from Subordinate DSAs ...................................................
Alternative DSAs ............................................................................
DSA Failover ............................................................................
DSA Load-Sharing .......................................................................
DSA Query Streaming ....................................................................
5-15
5-15
5-16
5-16
5-17
5-18
5-20
5-24
Chapter 6: Security
Secure Socket Layer (SSL) Encryption ........................................................... 6-2
About the SSL Protocol .................................................................... 6-2
SSL Encryption and Authentication Using SSLD ............................................. 6-3
DXserver Personality Certificates ........................................................... 6-5
Setting Up SSL For DXserver ............................................................... 6-6
Client Encryption ........................................................................ 6-11
DSA-to-DSA Encryption (DSP and DISP) ................................................... 6-11
Authentication .............................................................................. 6-12
Setting the Minimum Authentication Level ................................................. 6-12
Anonymous Authentication ............................................................... 6-13
Simple Authentication .................................................................... 6-13
SSL Authentication ....................................................................... 6-14
Distributed User Authentication ........................................................... 6-16
DSP Simple Authentication ............................................................... 6-17
DSP SSL Authentication .................................................................. 6-19
DISP Authentication ..................................................................... 6-19
Bypassing Mutual Authentication ......................................................... 6-20
Conveying User Authentication ........................................................... 6-21
DSP Link Authentication ................................................................. 6-22
Impersonation Protection ................................................................. 6-23
Managing Passwords ........................................................................ 6-24
How Password Rules Are Applied......................................................... 6-24
Password Protection ..................................................................... 6-25
Password Command Options ............................................................. 6-25
Enabling or Disabling Password Management .............................................. 6-28
Checking Password Quality ............................................................... 6-28
Setting the Life Span of Passwords ......................................................... 6-29
Resetting a Password ..................................................................... 6-30
Locking an Account after Incorrect Login Attempts ......................................... 6-31
Suspending an Account Manually ......................................................... 6-31
Contents
vii
Preventing Users from Re-using Passwords ................................................. 6-32
Some Password Controls Require an LDAP Client ........................................... 6-32
Example Password Policy ................................................................. 6-33
Access Control Overview ..................................................................... 6-34
Access Control Policies .................................................................... 6-34
Access Control Rules...................................................................... 6-35
Designing Your Access Control Scheme .................................................... 6-35
Working with Access Controls ............................................................. 6-37
Static Access Controls......................................................................... 6-38
Overview of Static Access Control Rules .................................................... 6-38
Setting Up Static Access Controls .......................................................... 6-40
Defining Superusers ...................................................................... 6-42
Defining Administrative Users ............................................................. 6-43
Defining Registered Users ................................................................. 6-45
Defining Public Users ..................................................................... 6-47
Protecting Items .......................................................................... 6-48
Dynamic Access Controls ..................................................................... 6-51
Enabling and Disabling Dynamic Access Controls ........................................... 6-51
Dynamic Access Control Rules ............................................................. 6-52
Groups, Roles, and Proxies .................................................................... 6-53
Defining Groups of Users ................................................................. 6-53
Role-Based Access Controls ............................................................... 6-54
Secure Proxies ............................................................................ 6-56
Access Controls and Aliases ............................................................... 6-57
Access-Controlled Routing .................................................................... 6-58
Chapter 7: Replication
Replication Concepts .......................................................................... 7-2
Compare Distribution and Replication ....................................................... 7-2
Compare Multimaster and Master–Slave Replication .......................................... 7-2
Compare Real-Time and Write-Behind Replication ........................................... 7-3
Compare Replay-Based and State-Based Replication .......................................... 7-3
Three Types of Replication Used with eTrust Directory ....................................... 7-4
Keep System Clocks Synchronized .......................................................... 7-4
Multiwrite Replication ......................................................................... 7-5
How Multiwrite Replication Works ......................................................... 7-5
Multiwrite Can Work Asynchronously ...................................................... 7-6
How Multiwrite Groups Work .............................................................. 7-7
Set Up a Multiwrite System ................................................................ 7-10
Recovering a Multiwrite System Using Queues .............................................. 7-12
viii
Recovering a Multiwrite System Using DISP ................................................
Multiwrite Replication to an LDAP Directory ...............................................
Multiwrite and DXcache ..................................................................
Re-synchronize Databases Manually .......................................................
Example: Multiwrite Replication ..........................................................
DISP Replication .............................................................................
Configuring a DISP Responder ............................................................
DISP Agreements ........................................................................
Setting DISP Agreements .................................................................
Viewing DISP Agreements ................................................................
Shared DISP Configuration ...............................................................
Manual Initiation of DISP .................................................................
Shadow DSAs ...........................................................................
DISP Routing ............................................................................
Selective Shadowing .....................................................................
Manually Synchronizing Replicas Using Database Tools .........................................
How Manual Synchronization Works ......................................................
How to Manually Synchronize eTrust Directory Databases ...................................
7-14
7-17
7-17
7-18
7-19
7-21
7-21
7-21
7-22
7-23
7-23
7-24
7-24
7-24
7-25
7-27
7-27
7-27
Chapter 8: LDAP and DXlink
LDAP Clients................................................................................. 8-2
Defining the LDAP Port ................................................................... 8-2
Configuring LDAP Names ................................................................. 8-2
Handling LDAP Strings ................................................................... 8-3
Transparent Routing ...................................................................... 8-3
Schema Publishing ............................................................................ 8-4
Integrating Other LDAP Servers................................................................ 8-6
User Credentials on DXlink Binds .......................................................... 8-7
Prefix Mapping ........................................................................... 8-9
Working with Microsoft Exchange ......................................................... 8-10
Chapter 9: Monitoring the Directory
General Monitoring ...........................................................................
DXconsole ................................................................................
Log Files .................................................................................
Databases ................................................................................
Disk Space ...............................................................................
9-2
9-2
9-2
9-3
9-3
Contents
ix
SNMP and the Directory Monitoring MIB ....................................................... 9-4
Configuring the SNMP Agent .............................................................. 9-5
SNMP Monitor Utility ..................................................................... 9-6
Configuring the SNMP Trap Destination..................................................... 9-8
CMIP and X.700 Management .................................................................. 9-9
Configuring the CMIP Agent ............................................................... 9-9
CMIP Monitor Utility ...................................................................... 9-9
Chapter 10: Using DXtools
Database Tools ............................................................................... 10-2
Creating a DSA: DXnewdsa ............................................................... 10-4
Creating a Database: DXnewdb ............................................................ 10-5
Extending a Database: DXextenddb ........................................................ 10-5
Destroying a Database: DXdestroydb ....................................................... 10-6
Emptying a Database: DXemptydb ......................................................... 10-6
Backing Up a Database: DXbackupdb ...................................................... 10-7
Restoring a Database: DXrestoredb ......................................................... 10-8
Tuning a Database: DXtunedb ............................................................. 10-9
Managing Indexes: DXindexdb ........................................................... 10-10
Displaying Database Statistics: DXstatdb................................................... 10-13
Listing Existing Databases: DXlistdb ...................................................... 10-14
Adding a Database User: DXadduser ...................................................... 10-14
Deleting a Database User: DXdeluser ...................................................... 10-15
Loading a Database: DXloaddb ........................................................... 10-16
Dumping a Database: DXdumpdb ........................................................ 10-18
Granting Access to a Database: DXgrantdb ................................................. 10-19
Revoking Access to a Database: DXrevokedb ............................................... 10-19
Upgrading Previous Versions of a Database: DXupgradedb ................................. 10-20
Initializing Multiwrite–DISP Recovery: DXdisp............................................. 10-20
Reporting On and Generating Certificates: DXcertgen ....................................... 10-21
LDIF Tools ................................................................................. 10-27
CSV Source Data ........................................................................ 10-27
Template Files (LDT) .................................................................... 10-28
LDIF Files .............................................................................. 10-29
Converting CSV Data to LDIF Format: csv2ldif ............................................. 10-30
Sorting an LDIF File: ldifsort .............................................................. 10-31
Calculating the Change Between Two LDIF Files: ldifdelta .................................. 10-33
DAP Tools .................................................................................. 10-35
Common Command Options ............................................................. 10-36
Searching a Directory: DXsearch .......................................................... 10-37
x
Reporting on Certificate and CRL Indexes: DXcert .........................................
Modifying a Directory: DXmodify ........................................................
Loading Binary Files: DXmodify ..........................................................
Renaming a Directory Entry: DXrename ...................................................
Deleting a Directory Entry: DXdelete......................................................
Bulk Loading Options ...................................................................
Schema Tools...............................................................................
Extracting Schema in LDIF Format: DXschemaldif .........................................
Converting Schema from LDIF to DXserver Format: ldif2dxc ................................
Converting Schema from DXserver Format to DXtools Format: DXschematxt .................
Directory Administration Tools ..............................................................
Checking DSA configuration: DXsyntax ...................................................
10-38
10-39
10-40
10-41
10-42
10-42
10-43
10-44
10-45
10-49
10-50
10-50
Chapter 11: Using JXplorer
The JXplorer Browser ........................................................................ 11-2
Menu Bar ............................................................................... 11-3
Button Bar ............................................................................... 11-5
Quick Search Bar ......................................................................... 11-6
Displaying the Directory Tree ............................................................. 11-6
Browsing a Directory ......................................................................... 11-7
Starting JXplorer ......................................................................... 11-7
Connecting to a Directory ................................................................. 11-7
Reading Schema ......................................................................... 11-8
Navigating the Directory Tree ............................................................. 11-8
Displaying an Entry ...................................................................... 11-9
Refreshing Entries....................................................................... 11-11
Searching .............................................................................. 11-11
Exploring Schema ....................................................................... 11-14
Editing the Directory ........................................................................ 11-16
Directory Tree Operations ............................................................... 11-16
Modifying Attributes in an Entry ......................................................... 11-18
Using Binary Values ..................................................................... 11-20
Adding a New Entry .................................................................... 11-23
Submitting an Entry to the Directory ...................................................... 11-24
Using LDIF Files ............................................................................ 11-25
Importing and Exporting an LDIF File .................................................... 11-25
Using an LDIF File Without a Directory ................................................... 11-25
Binary Values in LDIF Files .............................................................. 11-26
Using SSL and SASL ........................................................................ 11-27
Server Authenticated SSL ................................................................ 11-27
Contents
xi
Client Authenticated SSL and SASL ....................................................... 11-27
Managing Certificates and Keystores ...................................................... 11-28
Online Help ................................................................................ 11-28
Configuring JXplorer ........................................................................ 11-29
View Menu ............................................................................. 11-29
Options Menu ........................................................................... 11-29
Creating HTML Viewing Templates ....................................................... 11-34
Configuring Tree Icons ................................................................... 11-35
Extending the Java Binary Editor .......................................................... 11-35
Internationalization ...................................................................... 11-35
Troubleshooting ......................................................................... 11-36
Other LDAP and Directory Resources ..................................................... 11-36
Chapter 12: Using DXmanager
How DXmanager Works ...................................................................... 12-2
How You Can Use DXmanager ................................................................ 12-3
Monitor DSA Status ...................................................................... 12-3
Check DSA Configuration ................................................................. 12-3
Track DSA Statistics ...................................................................... 12-3
Check Namespace Design ................................................................. 12-3
How DXmanager Presents Information ......................................................... 12-4
Starting DXmanager .......................................................................... 12-4
Troubleshooting ............................................................................. 12-5
Connectivity ............................................................................. 12-5
DXwebserver Port Numbers ............................................................... 12-5
Chapter 13: Using JXweb
Connecting to JXweb ......................................................................... 13-2
Connecting to a Directory ..................................................................... 13-3
The JXweb Environment ...................................................................... 13-4
Customizing JXweb .......................................................................... 13-4
Using JXweb in Languages Other Than English ................................................. 13-5
Displaying Non-English Characters in Internet Explorer...................................... 13-5
Displaying Non-English Characters in Mozilla Browsers ..................................... 13-5
Online Help ................................................................................. 13-5
xii
Chapter 14: Using The UDDI Server
About UDDI Registries .......................................................................
What a UDDI Registry Can Do ............................................................
About the eTrust Directory UDDI Server ...................................................
eTrust Directory UDDI Server.................................................................
Connecting to the UDDI Client ................................................................
Connecting to a UDDI Registry ...............................................................
Using tModels ...............................................................................
Using the UDDI Client in Languages Other Than English ........................................
Displaying Non-English Characters in Internet Explorer .....................................
Displaying Non-English Characters in Mozilla Browsers .....................................
14-2
14-2
14-2
14-3
14-4
14-5
14-5
14-6
14-6
14-6
Chapter 15: Using the Sample DSAs, Applications, and Tools
Implementing the Samples ................................................................... 15-2
The Sample DSAs ............................................................................ 15-3
What the Sample DSAs Are Useful For ..................................................... 15-3
When the Sample DSAs Are Installed ...................................................... 15-3
How the Sample DSAs Work Together ..................................................... 15-3
The Democorp DSAs ..................................................................... 15-4
The UNSPSC DSAs ...................................................................... 15-5
The Router DSAs ........................................................................ 15-6
Sample Web Applications .................................................................... 15-7
Customized Version of JXweb: democorp .................................................. 15-7
Sample DSML Server: dsml ............................................................... 15-8
Sample SAML Server: saml-sample ........................................................ 15-9
Sample SPML Server: spml-sample ....................................................... 15-10
Sample Use of UDDI: uddiv3-demo ....................................................... 15-11
Sample Configuration Files .................................................................. 15-13
Sample Tools ............................................................................... 15-13
The DXcmip Tool ....................................................................... 15-13
The dua Tool ........................................................................... 15-14
The DXtoolsgui Tool .................................................................... 15-14
The ldua Tool ........................................................................... 15-15
The schema Tool ........................................................................ 15-15
The snmp Tool .......................................................................... 15-17
The soak Tool ........................................................................... 15-18
The ssl Tool ............................................................................ 15-21
The test Tool............................................................................ 15-23
The DXtrap Tool ........................................................................ 15-25
Contents
xiii
Chapter 16: Deploying a Directory
Directory Design ............................................................................. 16-2
Requirements Analysis .................................................................... 16-2
Service Definition......................................................................... 16-2
Schema Design ........................................................................... 16-2
Directory Enabled Applications ............................................................ 16-3
Namespace Design ....................................................................... 16-3
Security ................................................................................. 16-3
Dimensioning ............................................................................ 16-4
Performance ............................................................................. 16-4
Availability .............................................................................. 16-4
Synchronization .......................................................................... 16-5
Scalability and Distribution ................................................................ 16-5
Complexity .............................................................................. 16-5
Operations and Practices ...................................................................... 16-6
Management ............................................................................. 16-6
Monitoring .............................................................................. 16-6
Capacity Planning ........................................................................ 16-6
Backup and Restore ....................................................................... 16-7
Journaling ............................................................................... 16-7
Database Tuning ......................................................................... 16-8
Change Control .......................................................................... 16-8
Upgrades ................................................................................ 16-9
Maintenance ............................................................................. 16-9
Troubleshooting ............................................................................ 16-10
Optimizing Performance ................................................................. 16-10
Managing Large Numbers of Users........................................................ 16-10
Managing Large Numbers of Entries ...................................................... 16-11
Limiting Users .......................................................................... 16-11
Appendix A: Tailoring the RDBMS
Changing the Default Page Size ................................................................
Increasing the Number of Cache Pages .........................................................
Increasing the Number of Database Connections ................................................
Step 1. Increase the Shared Memory Maximum (Optional) ....................................
Step 2. Increase the Database Connection Limit ..............................................
Other Customizations ........................................................................
xiv
A-2
A-3
A-4
A-4
A-5
A-5
Appendix B: DXserver Command Language
Command Categories ......................................................................... B-1
Add Command ............................................................................... B-2
Clear Commands ............................................................................. B-2
Close Commands ............................................................................. B-2
Set Commands ............................................................................... B-3
The set admin-user Command ............................................................. B-8
The set agreement Command .............................................................. B-8
The set attribute Command ................................................................ B-9
The set dsa Command ..................................................................... B-9
The set name-binding Command .......................................................... B-11
The set object-class Command ............................................................. B-11
The set protected-items Command ......................................................... B-12
The set public-user Command ............................................................. B-12
The set reg-user Command ............................................................... B-13
The set super-user Command ............................................................. B-13
Source Commands ........................................................................... B-14
Trace Commands ............................................................................ B-15
Appendix C: Messages and Logs
UNIX System Error Log ....................................................................... C-1
Windows Event Log .......................................................................... C-1
DXserver Logs ................................................................................ C-2
Advantage Ingres Logs ........................................................................ C-3
DXserver Alarm Messages ..................................................................... C-7
DXserver Warning Messages.................................................................. C-13
Alias Errors ................................................................................. C-16
Service Errors ............................................................................... C-17
Advantage Ingres Errors ..................................................................... C-17
Appendix D: Installing eTrust Directory for Windows
Installation Overview ......................................................................... D-2
eTrust Directory Components .............................................................. D-2
Default Installation Locations .............................................................. D-3
The %DXHOME% Location ................................................................ D-3
Installation Logging ....................................................................... D-3
Upgrade eTrust Directory .................................................................. D-4
Upgrade Advantage Ingres ................................................................ D-4
Contents
xv
Embedded eTrust Identity and Access Management ......................................... D-5
Install eTrust Directory Using the Product Explorer.............................................. D-6
Step 1. Check System and Disk Requirements ............................................... D-6
Step 2. Install eTrust Directory ............................................................. D-7
Step 3. (Optional) Install eTrust Directory Web Components .................................. D-8
Step 4. (Optional) Install the Samples and Technology Previews............................... D-9
Install eTrust Directory Using Commands ..................................................... D-11
Install eTrust Directory Silently ............................................................... D-14
Install Silently Using Commands .......................................................... D-14
Install Silently Using Response Files ....................................................... D-15
Embed eTrust Directory in Another CA Product ............................................... D-17
How Installation Codes Work ............................................................ D-17
Install eTrust Directory as an Embedded Module ........................................... D-17
Uninstall eTrust Directory After an Embedded Installation .................................. D-18
Troubleshooting ............................................................................ D-19
Appendix E: Installing eTrust Directory for UNIX
Installation Overview .......................................................................... E-2
eTrust Directory Components .............................................................. E-2
Default Installation Locations ............................................................... E-3
The $DXHOME Location ................................................................... E-3
Installation Logging ....................................................................... E-3
Upgrade eTrust Directory .................................................................. E-4
Upgrade Advantage Ingres ................................................................. E-4
User Accounts............................................................................. E-5
Install eTrust Directory Using the Installation Program ........................................... E-6
Step 1. Check System and Disk Requirements ................................................ E-6
Step 2. Install eTrust Directory ............................................................. E-10
Step 3: (Optional) Install the Web Components .............................................. E-16
Step 4: (Optional) Install the Technology Previews and Sample Tools .......................... E-17
Install eTrust Directory Using Commands ...................................................... E-19
The dxsetup Command ................................................................... E-19
The dxwebsetup Command ............................................................... E-20
Install eTrust Directory Silently ................................................................ E-21
Install Using Commands .................................................................. E-21
Install Using Response Files ............................................................... E-22
Embed eTrust Directory in Another CA Product ................................................ E-24
How Installation Codes Work ............................................................. E-24
Install the Main eTrust Directory Components as an Embedded Module ....................... E-24
Install the Web Components as an Embedded Module ....................................... E-24
xvi
Uninstall eTrust Directory after an Embedded Installation ................................... E-25
Troubleshooting ............................................................................. E-26
Appendix F: Licenses for Third-Party Products
Apache ...................................................................................... F-1
Morten’s JavaScript Tree Menu v2.3.2 ........................................................... F-3
OpenLDAP .................................................................................. F-4
The OpenLDAP Public License ............................................................. F-4
The OpenLDAP Copyright Notice .......................................................... F-5
OpenSSL ..................................................................................... F-6
Sun Microsystems, Inc. Java Web Services Developer Pack ........................................ F-8
Tom Sawyer Layout Assistant................................................................. F-13
Contents
xvii
Chapter
1
Introduction
The eTrust™ Directory consists of a suite of products that lets you build an
industrial-strength directory service for directory-enabled applications. The
product suite includes a high performance, state-of-the-art Directory server,
graphical Directory browsers, and a set of tools for importing, exporting, and
synchronizing data with other information systems.
eTrust Directory advanced features are:
■
■
■
Lightweight Directory Access Protocol (LDAP) support for access and the
X.500 distributed directory model for distribution, which lets you build highcapacity global directory systems
Its underlying information repository (on each server) that uses a relational
database to apply a patented meta-data design, thus ensuring reliability and
data integrity
Its unique ability to connect and integrate smaller scale LDAP Servers to
create a unified directory backbone service with legacy directory servers
The system is highly scalable and robust, and meets the needs of large corporate
organizations, Internet Service Providers (ISPs), carriers, the military, and the
smaller office automation directory applications.
Introduction
1–1
eTrust Directory Modules
The following diagram shows the relationships between the major components
of eTrust Directory:
JXplorer
SPML
ne
t
DXconsole
te
l
Web Services
Examples
SAML
SSL SNMP
TLS CMIP
AP
LD
DSML
LDAP DSP
DAP DISP
UDDI Server
DXserver
LDAP
UDDI
SQL
DXmanager
HTTP
JXweb
UDDI Client
LDAP
DXwebserver
DA
P
Config
. Files
DXadmind
SSLD
Ingres
Database
SQL
DXtools
DXserver
The DXserver process uses highly efficient techniques for managing directory
information and processing the directory protocols. The eTrust Directory
supports the following protocols:
Protocol
Description
LDAP
Lightweight Directory Access Protocol
DAP (X.511)
Directory Access Protocol
DSP (X.518)
Directory System Protocol
DISP (X.525)
Directory Information Shadowing Protocol
CMIP (X.700)
Common Management Information Protocol
SNMP
Simple Network Management Protocol
The DSA fully supports all mandatory requirements of the approved protocols.
See the appendix Supported Standards in the eTrust Directory Getting Started
guide for a list of all standards supported by eTrust Directory.
1–2
The Relational Database Management System (RDBMS)
The RDBMS stores and maintains the Directory Information Base (DIB) within
specially designed tables. Each DIT or DIB image stores its own set of tables in
the RDBMS’s portion of the file system.
The RDBMS contributes to the performance, reliability, and management of the
DXserver system with the following features:
■
Caching
■
Query optimization
■
Multiprocessing and locking
■
Check-pointing and recovery
■
International character sets and collating sequences
■
Database table and indexing management
■
Housekeeping and tuning utilities
Unlike other X.500 and LDAP implementations, particularly in-memory
implementations, the DXserver does not load directory information and other
indexes into memory on startup, unless DXcache is configured. See the chapter
“General Administration” for more information about DXcache.
Configuration Files
When a DSA starts up, it initializes with commands stored in configuration files.
The configuration files are organized into logical groups corresponding to their
function (for example, logging, schema, knowledge).
DXtools
The DXtools provide general data management facilities, including:
■
Managing databases
■
Tuning and backing up directory data
■
Importing and exporting directory data
■
Bulk loading databases from a prepared LDIF file
■
Bulk extracting a database to an LDIF file for comparison
■
LDIF sorting and comparison
For descriptions of these tools, see the chapter "Using DXtools".
Introduction
1–3
Samples
A number of sample configurations and utilities are provided for testing and
demonstration purposes. These reside in the ../dxserver/samples subdirectories:
Subdirectory
Purpose
cmip
An executable to request CMIP counters from the directory.
democorp
DemoCorp example, run the setup script to automatically
configure the DemoCorp DSA.
dua
Sample text-based Directory User Agent (DUA) that runs
over DAP
dxtoolsgui
Java GUI interface to the DXtools—run dxtoolsgui.bat on
Windows or dxtoolsgui.sh on UNIX.
Note: This requires Java Runtime Environment (JRE).
ldua
Sample text-based DUA that runs over LDAP
router
An example router DSA that does not use a database and has the
prefix c = AU, and is aware of the DemoCorp and UNSPSC DSAs.
schema
A Perl schema translation tool to update schema.txt for the
DXtools
snmp
An executable to request SNMP information from the directory.
soak
An executable to measure the throughput (in searches per
second) of a DSA.
ssl
Examples of using DUA-DSA and DSA-DSA SSL
authentication and encryption.
test
A selection of Directory scripts to modify the directory
using the supplied DUA or LDUA clients. Run the setup
script to automatically configure the Test DSA and execute
the DUA and LDUA client scripts.
trap
Information and an example program that can receive
triggers from the directory.
unspsc
United Nations Standard Product and Services Classification
(UNSPSC) Code System. Run the setup script to automatically
configure the UNSPSC DSA and populate it with UNSPSC data.
For more information see .../dxserver/samples/README.TXT, and the
README.TXT files within each sample sub-directory.
1–4
RDBMS Tools
The RDBMS tools provide support for the RDBMS. See the Advantage Ingres
product documentation set for further details.
DXwebserver
The DXwebserver enables access to the DXserver process through web-based
GUIs, including:
DXmanager
A graphical, web-based eTrust Directory administration tool
JXweb
A graphical web-based LDAP directory browser and editor
UDDI Client
A graphical web-based browser for a UDDI Server
You can also create your own web-based GUIs to suit your organization.
Three technology previews are also provided for testing and demonstration
purposes. These reside in the ../dxwebserver/samples subdirectories:
democorp
This is a version of JXweb that has been customized to work well with the
fictional company Democorp.
dsml
This is a sample DSML server that converts DSML to LDAP and vice versa.
This allows client applications that use DSML (including web services) to
communicate with eTrust Directory without using LDAP directly.
uddi
This is a demonstration of a typical application of a UDDI server. It shows a
web site that compares prices on airline flights by looking up the prices on
different web servers, which are registered with a UDDI server.
Each sample includes a Readme that describes how to install the sample.
Introduction
1–5
eTrust Directory Glossary
This section defines some terms that are commonly used in this guide.
Attribute
Entries are comprised of attributes. Each attribute consists of a type and a
value.
For example, in a staff directory, each entry would include attributes that
defines the person’s name, phone number, office location, etc.
Distinguished name (DN)
A name that uniquely identifies an entry. The DN includes the name of the
entry, plus the names of all superior entries and domains. Thus, the DN
identifies the entry, and its location within the directory information tree
(DIT).
Directory system agent (DSA)
A hierarchy of parent-child entries, built from the data stored in the
directory. One unified directory might actually consist of many linked DSAs.
Directory system protocol (DSP)
A server-to-server protocol used by X.500 for distributed operations. This is
the protocol used for chaining. LDAP does not have a DSP equivalent.
Entry
The basic unit of information storage in a directory. All information in a
directory is stored in the form of entries. Also sometimes named objects.
For example, in a directory listing all staff members at a company, each staff
member would have an entry.
Latency
The delay caused by the round-trip time taken between sending a network
packet and receiving a response.
Multiwrite
A mechanism for replicating updates to a number of DSAs to ensure they are
synchronized. When DXserver receives an update, this will be written to
itself and then its peers. If a peer DSA cannot be reached, the updates will be
queued and replayed when the DSA becomes available.
Multiwrite groups
Tiered replication will be implemented using multi-write groups. DSAs on
either side of a slow link (e.g. different continents) can be grouped.
Replication will occur in the group and sent to elected hubs from another
group asynchronously.
Namespace
A namespace is a set of names in which all names are unique. Each name
contains enough information to identify where the named entry appears in
the structure of all entries.
1–6
Replicating hub
In a tiered replication scheme, a hub given responsibility for cascading
updates to its peers. The DSA that originated the update offloads replicating
responsibility to the hub.
Schema
A formal definition of the contents and structure of the directory data. This
governs where each entry can be placed within the directory structure, how
entries are to be named, and what attributes each entry can contain.
Tiered replication
During normal replication of an update, an entity will cycle through and
update all mates. In a tiered model the update will be passed on to a mate
outside the group, which will write to its mates.
Introduction
1–7
Chapter
2
DXserver Overview
This chapter describes how the eTrust Directory server component works.
What is DXserver?
The eTrust Directory server component is named DXserver.
DXserver can be operated as a directory in a standalone mode similar to other
LDAP servers. DXserver can also be configured to operate in a distributed
environment as a full featured X.500 Directory System Agent (DSA) supporting
all the powerful X.500 features such as chaining, parallel searching, distributed
management and advanced security.
DXserver supports many communications protocols and management facilities,
including:
■
User access protocols (DAP, LDAP)
■
System (inter server) protocols (DSP, DISP)
■
Management protocols (SNMP, CMIP)
■
Input commands (from script files or management console)
■
Logging Services (alarms, traces, management responses)
DXserver Overview
2–1
DXserver Configuration Files
DXserver stores configuration information in a structured directory tree. The
easy-to-use, hierarchical tree defines the conventions and the strategy for
managing the directory system that can extend to multiple servers, multiple
machines, and multiple platforms.
The configuration files should be managed from a central station. The directories
are shared across all servers to ensure consistency in system operation. This
architecture also lets you manage version of the configuration files, because you
can store these files in a document or source control system.
DXserver File Directories
After installation, DXserver uses the following directories:
DXserver
|__ bin
|__ config
|
|__ access
|
|__ autostart (UNIX only)
|
|__ database
|
|__ knowledge
|
|__ limits
|
|__ logging
|
|__ replication
|
|__ schema
|
|__ servers
|
|__ settings
|
|__ ssld
|__ logs
|__ samples
|__ pid
|__ install
(UNIX only)
|__ uninstall (UNIX only)
bin
This directory holds all binary executables and batch files for the product.
config
This directory holds the current configuration files, and some Readme files
for your reference. DXserver always starts with the configuration
information stored in this directory. We recommend that you give read-only
permissions to files in these directories to prevent accidental overwriting.
Each subdirectory contains the configuration file(s) that deal with a
component of the DXserver configuration.
access
Access control rules.
autostart
(UNIX only) DXserver uses the autostart directory to track the servers
that must start at the same time as the operating system.
2–2
database
Database name information.
knowledge
Access-point information for all DSAs.
limits
Administrative limits, such as size limits and time limits.
logging
Trace levels and log file names.
replication
Replication agreements.
schema
Schema definitions.
servers
Startup information for each server. An initialization file must exist for
each defined DSA.
settings
Operational settings and controls.
ssld
Trusted CA and server certificates.
logs
This directory is the default log output directory for DXserver, which
generates all log files at this location unless you specify another directory.
samples
This directory contains demonstration utilities and test script files. Each
sample has its own subdirectory and associated README file.
pid
This directory is for DXserver use only, and contains information about
currently running processes. The pid directory does not contain any files
after an installation, but when the services are run, files are created in that
directory.
install
(UNIX only) This directory is for DXserver use only, and contains installation
files and environment information.
uninstall
(UNIX only) This directory contains uninstallation scripts..
DXserver Overview
2–3
Sample Configuration Files
DXserver contains a working example DSA configuration. You can use the
example server without modification as described in the appendixes “Installing
DXserver for Windows” and “Installing DXserver for UNIX.” The example
contains three DXserver configurations—Router, DemoCorp and UNSPSC.
Configuration File Types
You can identify file types within the directory configuration structure by their
file name extensions. It is important to use the correct file name extensions when
creating new files.
Use the following file types in a DXserver configuration set:
2–4
Extension
File type
Description
.dxc
Configuration
Contains one or more commands that set
configuration parameters.
.dxg
Group
Groups a selection of one or more .dxc
files (in the current directory) using the
DXserver source command.
.dxi
Initialization
DXserver initialization file. A .dxi file
contains commands to source other (.dxg
and .dxc) files.
.dxs
Script
Contains commands supported by the
DXcli. You usually use script files for
testing.
The Initialization File
Each server’s initialization file sources (refers to and reads) selected files from the
config subdirectories.
Important points to notice are:
■
■
The initialization file is a template in which the DSA sources a single file
from each of the config subdirectories appropriately.
You can organize the contents of the config directories as required—from
one file to many files—typically creating a specific file in each of the config
directories for each new DSA definition.
Here is the DemoCorp initialization file:
# Computer Associates DXserver/config/servers
#
# DXserver initialization file.
#
# logging and tracing
close summary-log;
close trace-log;
source "../logging/default.dxc";
# schema
clear schema;
source "../schema/default.dxg";
# access controls
clear access;
# source "../access/";
# knowledge
clear dsas;
source "../knowledge/sample.dxg";
# operational settings
source "../settings/default.dxc";
# service limits
source "../limits/default.dxc";
# database
source "../database/democorp.dxc";
# replication agreements (rarely used)
# source "../replication/";
DXserver Overview
2–5
Configuration Grouping Files
Each component directory can consist of one or more configuration (.dxc) files.
For complex configurations typically involving multiple DSAs, you might need a
number of configuration files, grouped in a convenient manner using grouping
(.dxg) files:
Group 1
commands A
Group 2
commands B
commands C
As an example, suppose the DSAs TestCorp1, TestCorp2, and TestCorp3 all
require the schema files x500.dxc, cosine.dxc, and inetop.dxc. Rather than
“sourcing” each of these files from each of the DSA initialization files, it is more
convenient to create a TestCorp.dxg file containing the following lines:
source “x500.dxc”;
source “cosine.dxc”;
source “inetop.dxc”;
Each DSA initialization file would then contain the following line:
source “../schema/TestCorp.dxg”;
The advantage of this approach is that, if these DSAs require additional schema,
only a single file—TestCorp.dxg—needs editing.
Reasons for grouping files are:
■
■
To present a view that abstracts any internal organization within the
component
To manage ordering of the configuration files—especially important in
schema where definitions in one file depend on definitions in another file
Typically the schema and knowledge files are grouped.
2–6
Knowledge Files
This section describes what knowledge files are, and how to use them.
Knowledge files are text files that include commands that affect how DSAs work.
Each DSA has a single knowledge file, which is named dsaname.dxc, where
dsaname is the case-insensitive name of the DSA. These knowledge files are kept
in the config/knowledge directory.
Each DSA must source its own knowledge file, which includes what operations
from remote DSAs are to be permitted or denied.
Each DSA can also source the knowledge files for other, remote DSAs. These files
define how the local DSA works with the remote DSA.
For information about knowledge flags, see Knowledge Flags in the chapter
General Administration.
Using Knowledge Files in a Single-Server Environment
If your directory includes more than one DSA, you need to consider how you
work with your knowledge files.
If all of the DSAs happen to be one the same computer, they can all source the
same copy of the knowledge files.
Router DSA
Server A
router.dxc
unspsc.dxc
democorp
.dxc
Democorp
DSA
UNSPSC DSA
Three DSAs on one server, sharing the same knowledge files
DXserver Overview
2–7
Using Knowledge Files in a Distributed Environment
However, it is more likely that the DSAs in a distributed system are on different
computers. To make sure that operations are not slowed down by network
limitations, each DSA should use its own local copy of the knowledge files.
We recommend that you make any changes to only one of these sets of
knowledge files, and then copy the changed files to the other locations.
This will help you keep the knowledge files synchronized.
For example, in the system shown here, you could use the knowledge files on
Server A as the master copies. Whenever you need to change a knowledge file,
you would make the change on Server A. You could then copy the changed files
to the other two servers.
Server A
router.dxc
Router DSA
unspsc.dxc
democorp
.dxc
router.dxc
Democorp
DSA
router.dxc
unspsc.dxc
democorp
.dxc
Server B
Server C
unspsc.dxc
UNSPSC DSA
democorp
.dxc
Three DSAs on separate servers, using local copies of the same knowledge files
2–8
DXserver Commands
DXserver Commands
When a server starts up, it reads an initialization file (.dxi) from the servers
subdirectory. The initialization file name is derived from the DSA name. For
example, democorp.dxi defines a DSA named DemoCorp. Thus, the following
command causes DXserver to search the servers subdirectory for a file called
democorp.dxi:
dxserver start democorp
When found, it is read and the commands are executed (usually instructions to
read other files in the other subdirectories of the config tree).
See the appendixes “Installing eTrust Directory for Windows” and “Installing
eTrust Directory for UNIX” for information about starting and stopping a
DXserver process.
The dxserver Command - Install, Start, or Stop the DXserver
You can run the DXserver from the command line using the following command:
dxserver options
Important! You must start the RDBMS before starting DXserver. If an error occurs
while reading the configuration files, DXserver cannot start. You can find information
about this error in both the operating system error log and the DXserver alarm and trace
log files in the dxserver/logs directory.
The options of the dxserver command are:
Option
Meaning
init serverName
Signals serverName to reread its configuration files (if
running). For example:
dxserver init democorp
init all
Signals all DSAs to reread its configuration files
install serverName
Adds serverName to the list of servers to start at system
startup. For example:
dxserver install democorp
Note: On Windows, the dxserver start command implicitly
installs eTrust Directory
remove serverName
Removes serverName from the auto-startup list, for example:
dxserver remove democorp
start serverName
Starts the DXserver serverName. For example:
dxserver start democorp
DXserver Overview
2–9
DXserver Commands
Option
Meaning
start all
Starts all DSAs.
status serverName
Reports the running status of serverName. For example:
dxserver status democorp
If you omit the serverName, the status of all servers is
reported.
stop serverName
Stops the DXserver serverName. For example:
dxserver stop democorp
2–10
stop all
Stops all DSAs
version
Displays version information
DXserver Script Language
You can use the DXserver commands to control every aspect of DXserver
operation. The DSA supports an extensive set of configuration and management
commands that you can use in configuration files or enter interactively through
the management console.
The complete command language is defined in the appendix “DXserver
Command Language.”
You can organize commands into script files. Script files have the following
general uses:
■
Configuration—A group of DSAs can share the same configuration
information.
■
Prototyping—X.500 operations you can automate.
■
Testing—The command language supports conditional statements.
■
Shortcuts—Storage of often used commands.
Configuration Files
In order to describe the large number of DXserver commands, you can separate
commands into individual files according to their function. These separate files
should then reside in the appropriate config subdirectory.
A description of each set of related commands is in subsequent chapters:
■
General administrative commands—see the chapter “General
Administration”
■
Schema commands—see the chapter “Schema Definition”)
■
DSA and distribution commands—see the chapter “Distribution and DSP”
■
Security commands—see the chapter “Security”
■
Replication commands—see the chapter “Replication”
■
X.500 commands—see the appendix “DXconsole DUA”
DXserver Overview
2–11
Command Syntax
Typically, commands have one of the following formats:
set item = value;
get item;
action parameters;
■
■
■
Some commands are hyphenated (for example, add-entry-req). You can spread
each command over many lines. You must terminate each command with a
semicolon.
You do not need to quote simple (one-word) strings. You must quote more
complex (many-word) strings. Within a quoted string, you can use a backslash
(\) as an escape mechanism for the following cases:
Case
Example
String
Quote
my “favorite” car
"my \"favorite\" car"
Backslash
c:\myfile
"c:\\myfile"
Hex number
touché
"Touch\xC2e"
There is often a need to specify attribute values in character sets other than
ASCII. For example, you can perform the following modification:
mod-entry-req entry=<c au><o democorp> add-attr { description "a description" };
But how is this done in other languages?
LDAPv3 has standardized on UTF-8 for internationalization. An example, using
UTF-8, is now:
mod-entry-req entry=<c au><o democorp> add-attr { description utf8 "touch\xC3\xA9" };
The Latin-1 character e-acute (E9) in UTF-8 (C3A9) has been encoded. The
following example would search for all entries with common names beginning
with e-acute.
search-req base-object=<> whole-subtree filter = { attr = commonName substrings [
initial utf8 "\xC3\xA9" };
Commands can continue over multiple lines. If you enter an incomplete
command at the management console, a continuation prompt, as shown below,
displays until you enter a semicolon:
--->
Tip: You can interrupt the execution of a script file from the management
console using the telnet commands Ctrl-c or Ctrl-x. (See DXconsole in this
chapter.)
2–12
Script Files
Script files store frequently used or complex commands (such as schema
initialization commands). You can then execute these files from the management
console or from inside other command files using the command:
source "script-file";
or the short form of the command:
! "script-file";
Tip: A configuration file (.dxi, .dxc, or .dxg) is a special form of script file.
Within a script file, the # sign introduces a comment. DXserver treats the # and
all text after it, to the end of the line, as a comment.
A script file can source other script files. The source command is relative to the
file that invokes it. For example, when you source the file schema.dxg using the
command:
source "../schema/schema.dxg";
then the schema.dxg script can source a file in its own directory using the
command:
source "attr.dxc";
Script File Errors and Debugging
Usually the system does not echo commands in script files before they are
executed. If there is an error in the script file, a message similar to the following
is displayed:
>>>> set allow-binds = 1;
-----------------------^ (line 12 in ‘test.dxc’)
Syntax Error: Expected ‘true’ or ‘false’
Tip: To obtain a full log of every command executed in a script file, set the
first lines of the script file to:
echo-on;
set trace-file = "script.log";
After running the script file, you can examine the log file to locate any failed
command and the reason for the failure.
DXserver Overview
2–13
DXconsole
DXconsole
The management console, DXconsole, lets you enter commands interactively. It
lets you monitor users, modify administrative controls, and perform actions.
DXconsole also includes a powerful co-resident directory client (DUA)
command-line interface, which you can use to enter user queries for diagnostic
or prototyping tasks.
For more information about the DUA, see the eTrust Directory SDK Developer
Guide.
DXconsole Security
For security reasons, DXconsole is only accessible from the local computer.
The management console only accepts one telnet session. To prevent anyone else
from starting up DXconsole, make sure you keep DXconsole always running.
To prevent attacks from remote telnet sessions, define a console port in the DSA
knowledge. This scheme uses the local host security. An administrator must have
an account on the local computer to communicate with the DSA through this
port.
You can use the console remotely when you set the remote-console-port flag. You
can attach a password, and SSL may be required. See Configuring DXconsole for
more information.
Opening DXconsole
Open DXconsole
To open DXconsole, use the telnet command to connect to the local host with
the console-port number:
% telnet localhost 19390;
Trying 127.0.0.1...
Connected to localhost.
Escape character is ‘^]’.
Welcome to the DSA Management Console
dsa>
Open Remotely
To open DXconsole remotely, use the telnet command to connect to the remote
machine with the remote-console-port:
% telnet eagle 19392
Note: You should enable local echo on the local telnet client.
2–14
DXconsole
Closing DXconsole
Close DXconsole
The usual way to close DXconsole is to log out. This closes the telnet session
from the DSA:
dsa> logout;
Close Locally
You can close DXconsole locally from the local telnet session:
<control-]>
telnet> quit
The telnet session closes automatically when the DSA shuts down.
DXserver Overview
2–15
DXconsole
Configuring DXconsole
DXconsole can be enabled either locally or remotely.
The remote DXconsole provides the DSA administrator with a means of
managing the DSA. The access protocol is telnet. To remotely manage a DSA
using DXconsole, either log on to the machine running the DSA and open
DXconsole using the console port, or use a remote telnet connection that uses the
remote console port.
telnet
Window
DSA
By default, DXconsole is only accessible from localhost for security reasons.
To enable DXconsole, you must define the console port in the knowledge file of
the DSA. For more information, see the section Defining DSAs in the chapter
“General Administration.”
For a list of all ports in a default installation of eTrust Directory, see the section
Port Numbers Used by eTrust Directory in the chapter DXserver Overview.
2–16
DXconsole
The DXconsole Command Options
To configure DXconsole, include the following options in the DSA knowledge
file:
Option
Parameter
Description
console-port
Port number
Allows DXconsole to accept connections from the local computer.
When this is not specified, the DSA does not have a local console.
remote-console-port
Port number
Allows DXconsole to accept a connection from a remote
computer on this port. When this is not specified, there is no
remote console for the DSA.
console-password
Password
The password required for connections from a remote computer.
This password is transmitted in clear text.
remote-console-ssl
Boolean
Forces DXconsole to encrypt sessions when it runs remotely.
Configuring DXconsole to Run Locally
To enable DXconsole locally, use the following command:
set dsa dsaname =
{
...
console-port = port_number
...
};
DXconsole: Local
Configuration
In the following sample configuration, the line console-port = 19390 defines the
port that DXconsole will use to accept connections from the same machine only:
set dsa DEMOCORP =
{
prefix
dsa-name
dsa-password
address
disp-psap
cmip-psap
snmp-port
console-port
ssld-port
auth-levels
trust-flags
};
=
=
=
=
=
=
=
=
=
=
=
<c AU><o DEMOCORP>
<c AU><o DEMOCORP><cn DXserver>
"secret"
tcp "hostname.ca.com" port 19389
DISP
CMIP
19389
19390
1112
anonymous, clear-password, ssl-auth
allow-check-password, trust-conveyed-originator
DXserver Overview
2–17
DXconsole
Configuring DXconsole to Run Remotely
You can connect to DXconsole from a remote computer, using a password for
authentication. This is configured by adding the "remote-console-port = 19395"
and "console-password = "password"" lines to the DSA knowledge file.
Although this method allows remote access and some security, the password
that is sent to DXconsole from the client is transmitted in clear text. This poses a
moderate security risk on unsecured networks.
To provide security, you can specify a console password. When this is set, the
user is prompted for a password before a connection is made.
Important! If you do not want the password to be displayed when it is entered, you must
turn local echo OFF on the telnet session.
To enable DXconsole remotely, use the following commands:
set dsa dsaname =
{
...
remote-console-port = port_number
console-password = password_string
...
};
DXconsole: Remote
Configuration
2–18
set dsa DEMOCORP =
{
prefix
= <c AU><o DEMOCORP>
dsa-name
= <c AU><o DEMOCORP><cn DXserver>
dsa-password = "secret"
address
= tcp "hostname.ca.com" port 19389
disp-psap
= DISP
cmip-psap
= CMIP
snmp-port
= 19389
console-port = 19390
remote-console-port = 19395
console-password = "password"
ssld-port
= 1112
auth-levels
= anonymous, clear-password, ssl-auth
trust-flags
= allow-check-password, trust-conveyed-originator
};
DXconsole
Configuring DXconsole to Run Securely and Remotely
You can force the remote console connection to run over TLS by adding the
"remote-console-ssl = true" line to the DSA knowledge file. This ensures that
console commands and passwords are not transmitted in-the-clear over public
networks.
Only one console session can be active at any one time, even if both the consoleport and remote-console-port flags are set.
To force DXconsole to use SSL/TLS when it is running remotely, add the
following settings:
set dsa dsaname =
{
...
remote-console-port = port_number
remote-console-ssl = true
console-password = password_string
...
}
DXconsole: Secure
Remote
Configuration
In the following sample configuration, the console is running remotely, and
SSL-encrypted:
set dsa DEMOCORP =
{
prefix
= <c AU><o DEMOCORP>
dsa-name
= <c AU><o DEMOCORP><cn DXserver>
dsa-password = "secret"
address
= tcp "hostname.ca.com" port 19389
disp-psap
= DISP
cmip-psap
= CMIP
snmp-port
= 19389
console-port = 19390
remote-console-port = 19395
remote-console-ssl = true
console-password = "password"
ssld-port
= 1112
auth-levels
trust-flags
= allow-check-password, trust-conveyed-originator
};
DXserver Overview
2–19
DXconsole
Testing the Secure Remote DXconsole Using TLSclient
The TLSclient utility establishes an encrypted tunnel between the remote console
client and the DSA. The steps to configure the DSA and TLSclient are as follows:
Create the TLSclient
Configuration File
1.
Create the TLSclient configuration file on the client machine
2.
Configure the DSA for SSL connections to DXconsole on the server machine
3.
Start TLSclient on the client
4.
Start the DSA on the server
5.
Test the connection
To configure TLSclient, you will need to create the following file on the client
machine:
■
Windows: %DXHOME%\config\tlsclient\tlsclient.cfg
■
UNIX: $DXHOME/config/tlsclient/tlsclient.cfg
This implies that eTrust Directory is also installed on the client machine,
although this may not be required. The only requirement should be that the
environment variable DXHOME is set and the trusted root certificate is available.
The format for tlsclient.cfg is:
inPort outPort remoteAddress
Where inPort is the port on the client machine that will be used for tunneling,
outPort is the DXconsole remote-console-port on the server and remoteAddress
is the hostname of the server running the DXconsole you wish to connect to.
Here is an example for the sample DemoCorp DSA running on the server
machine:
19390 19395 hostname.ca.com
Start TLSclient
TLSclient can be installed to the system services using the command:
tlsclient install <tlsclient-server-name> -ca <file>
Here is an example for the DemoCorp DSA:
tlsclient install democorp -ca config/ssld/trusted.pem
You can then start the TLSclient instance with:
tlsclient start <tlsclient-server-name>
For the DemoCorp DSA example, this would be:
tlsclient start Democorp
2–20
DXconsole
Starting DXserver
Testing the
connection
To start DXserver, do the following:
1.
Ensure that the DSA is stopped using: dxserver stop dsaname
2.
Start the DSA using: dxserver start dsaname
To test this connection, do the following:
1.
Open the DXconsole client, or your favourite Telnet program, on the client
machine
2.
Connect to the inPort (defined in tlsclient.cfg) on the local machine (19390 in
the DemoCorp sample)
3.
Enter the DXconsole password when prompted
You now have a fully-functioning SSL-encrypted connection to DXconsole on the
server machine.
To verify this, start TLSclient with the debug option, or set "trace all;" on the
DSA, or use a packet-snooping application.
Help Command
The help command lists the outer-level commands for the DSA administration
modules, X.500 services, and management scripts.
When you enter the help command at the console, the response is similar to:
Enter one of the following keywords:
(modules)
trace, log, stack, assoc, oper, schema, dsp, disp,
dib, access
(services) bind-req, unbind-req, abort-req, abandon-req,
read-req, compare-req, list-req, search-req,
add-entry-req, rem-entry-req, mod-entry-req, mod-dn-req
(scripts)
open-log, close-log, flush-log, source, !,
echo, echo-on, echo-off, wait, if-reply, goto
When you are not sure of the syntax, try a nonsense word for the missing part, or
leave the command incomplete and let the resulting error message tell you what
is expected:
>>>> oper get fred;
-----------------^
Syntax Error: Expecting “config” or “stats”.
DXserver Overview
2–21
DXconsole
Command Shortcuts
If you frequently use a command, or a set of commands, then store the
commands in a file and execute that file. For example, a script file called List can
contain the following command:
list-req entry = <c AU><o DemoCorp>;
You can execute it from DXconsole using the command:
dsa> !list;
2–22
Databases
Databases
eTrust Directory consists of two major components. These are the DSA process
and its underlying database. The DSA process is the X.500/LDAP directory
object and protocol processing system and the database is used to store and
retrieve the dismantled directory objects (entries) in the specially designed
database tables.
You can use the DSA process as a router engine, or configure it to be responsible
for a portion (or all) of the DIT. When a DSA process is not acting just as a
directory protocol router (for distribution or alternate, load balancing DSAs), it
should be considered as a process that is responsible for a DIT Namespace.
Set Database Name
When starting, the DSA process needs to know the name of the database it
should access. This value is usually set in a database initialization file using the
command:
set database-name = databaseName;
where databaseName is the name of an RDBMS database.
See The Directory Information Base in the chapter “General Administration” for
more information about setting database names.
Multiple DSA Processes to One DIT/DIB
More than one DSA can access the same X.500 DIT/DIB database (for example,
to provide load sharing and increased user counts). There is no possibility of
database inconsistency because the database management system enforces full
locking controls.
When multiple DSAs on the same machine access the same database, you must
configure each DSA with unique listening addresses within their knowledge
files. For more information, see the section Defining DSAs in the chapter
“General Administration”.
DXserver Overview
2–23
Databases
Multiple Directory Databases on One Machine
A single machine can host many discrete directory images. This is useful for
testing on separately managed production and testing databases or for
partitioning your directory into separate databases.
Hot Swap
Change Database
Name While DSA
Active
You can change the database name while the DSA is active without
disconnecting or disrupting directory clients, using the following command:
set database-name = newdb;
where newdb is the name of another RDBMS database, which must already
exist.
You can switch to a newly reorganized database, a hot standby copy, or a
restored copy by using the hot swap of a database.
2–24
Port Numbers Used by eTrust Directory
This section lists the port numbers used in a default eTrust Directory installation.
If one of these port numbers is also used by another application on the same
computer, you may need to change the port number used by eTrust Directory.
Most of the port numbers listed here are configurable.
Ports Used by eTrust Directory Components
The following table lists the port numbers used by the eTrust Directory
components in a default installation.
Component
Protocol Port
Description of Port
Number
DXwebserver TCP
(Tomcat)
8080
Accepts
SSL
Requests
The port on which Tomcat No
listens for requests.
If you change this, the
DSML, SAML, and SPML
samples won’t work.
SSLD
TCP
8005
The port on which Tomcat Yes
listens for the shutdown
command
TCP
8009
The Coyote/JK2 1.3
connector port
TCP
8443
Yes
The port to which SSL
requests are redirected if
they come in on a non-SSL
port
TCP
1112
The listen ports which
DXserver uses when
connecting to SSLD
1113
iTechPoz
data DSA
Configuration
See the following site for
descriptions of these ports,
and instructions for
changing them:
http://www.onjava.com/
pub/a/onjava/2002/07/3
1/tomcat.html
See the SSL section in the
chapter “Security”
UDP
509
SNMP port
No
DXHOME/config/
knowledge/iTechPoz.dxc
TCP
509
DSA listen address port
Yes
TCP
10510
Local console port (Telnet) Yes
This DSA is only to be used
by eIAM.
UDDIV3 data UDP
DSA
TCP
31389
SNMP port
No
31389
Yes
DXHOME/config/
knowledge/uddiv3.dxc
TCP
31390
Local console port (Telnet) Yes
This DSA is only to be used
by the UDDI Server.
DXserver Overview
2–25
Ports Used by Sample Tools and Sample DSAs
The following table lists the port numbers used by a sample tool and the sample
DSAs installed during a default eTrust Directory installation.
Any extra DSAs that you add will take up additional ports.
For information about how to set the port number of a DSA, see the section
Setting DSA Port Numbers in the chapter “General Administration.”
Sample
Protocol Port
Description of Port
Number
DXtrap
sample tool
UDP
162
The port on which DXtrap
receives SNMP traps
Democorp
sample DSA
UDP
19389
SNMP port
No
TCP
19389
Yes
TCP
19390
Local console port (Telnet)
Yes
UDP
19289
SNMP port
No
TCP
19289
Yes
TCP
19290
Yes
UDP
19489
SNMP port
No
TCP
19489
Yes
TCP
19490
Yes
Router
sample DSA
UNSPSC
sample DSA
2–26
Accepts
SSL
Requests
Configuration
See the section The
DXtrap Tool in the
chapter “Samples”
DXHOME/config/
knowledge/democorp.dx
c
DXHOME/config/
knowledge/router.dxc
DXHOME/config/
knowledge/unspsc.dxc
Chapter
3
General Administration
This chapter describes the commands you use to set up and maintain the general
behavior of DXserver.
Defining DSAs with the set dsa Command
The set dsa command defines the basic properties of each DSA or LDAP server in
the system. These DSAs include the local DSA itself, any remote DSAs (either on
the same system or on other systems), and other X.500 or LDAP servers.
Information about other directories, how to connect to them, their role (for
example, Replicas) and the entry namespace they manage is referred to as
knowledge. The total “knowledge” of the system is used to form a backbone of
directory servers to which each DSA belongs (a directory system).
The DSA is defined in a configuration file (.dxc) in the knowledge directory
(along with other DSA definitions). A DXserver determines its own entry
(identity) by looking for its own name among all the set dsa definitions.
Important! A DSA must use its own name (case insensitive) from the initialization file;
for example, the initialization file for the DSA illustrated below is serverName.dxi.
3–1
The set dsa Command Syntax
The set dsa command has the following format:
set dsa serverName =
{
prefix
native-prefix
dsa-name
dsa-password
ldap-dsa-name
ldap-dsa-password
};
=
=
=
=
=
=
<DN>
<DN>
<DN>
"string"
<DN>
"string"
address
= tcp hostname port portNumber [ ,tcp host2 port port2 ]
tsap
ssap
osi-psap
= tsel
= ssel
= psel
disp-psap
cmip-psap
snmp-port
console-port
remote-console-port
remote-console-ssl
console-password
ssld-port
=
=
=
=
=
=
=
=
auth-levels
dsp-idle-time
= authLevelList
= number
dsa-flags
trust-flags
link-flags
= dsaFlagList
= trustFlaglist
= linkFlagList
dispsap
cmipsap
portNumber
portNumber
portNumber
boolean
"string"
portNumber
Important! You must declare the parameters in the order shown. Only prefix, dsa-name,
and address are mandatory.
3–2
The set dsa Command Parameters
The parameters of the dsa set command are:
Parameter
Value
serverName
Name of the DXserver—must be less than or equal to 31 characters.
prefix
Distinguished name of the local root entry, for example, <c AU><o Democorp>.
native-prefix
(Optional) Distinguished name for an LDAP server, other DSA, or agent that
should be specified when using prefix mapping.
dsa-name
Distinguished name that identifies the DSA.
dsa-password
(Optional) String used in DSP authentication.
ldap-dsa-name
(Optional) Distinguished name used when binding to an LDAP server.
ldap-dsa-password
(Optional) String used in LDAP authentication.
address
DXserver Listen address: TCP address and listen port number
tsap
(Optional) Transport SAP (not recommended).
ssap
(Optional) Session SAP (not recommended).
osi-psap
(Optional) Presentation SAP (service access point) (not recommended).
disp-psap
(Optional) DISP presentation SAP; when absent, DISP is disabled.
cmip-psap
(Optional) CMIP presentation SAP; when absent, CMIP is disabled.
snmp-port
(Optional) SNMP port; when absent, SNMP is disabled.
console-port
(Optional) Management console port address. When this and the remote console
port address are absent, the management console is disabled.
remote-console-port
(Optional) Remote console port address.
remote-console-ssl
(Optional) Encrypts console sessions where the console may be attached to from a
remote host
console-password
(Optional) String used in console authentication.
ssld-port
(Optional) SSL port; used for SSL authentication.
auth-levels
(Optional) List of authorization levels supported by this DSA. See the chapter
“Security” for more information.
dsp-idle-time
(Optional) Maximum time in seconds a DSP connection can be idle before it is
disconnected. The default is 600 (10 minutes).
dsa-flags
(Optional) Comma-separated list of DSA flags; see DSA Knowledge Flags in this
chapter for more information.
trust-flags
(Optional) Comma-separated list of trust flags; see DSA Knowledge Flags in this
link-flags
(Optional) Comma-separated list of link flags; see DSA Knowledge Flags in this
3–3
Setting DSA Port Numbers
When you are running eTrust Directory on Windows , you usually use a port
number between 1700 and 64K (65536). When you are running eTrust Directory
on a UNIX platform, your system administrator will allocate available port
numbers. On most systems, the port numbers also go up to 64K (65536).
Port numbers are used differently from one DSA to another. For example,
DXserver listens for connections on ports defined in its knowledge file, but
communicates to other DSAs on ports defined in their knowledge files. Some
parameters, for example, console-port, are only meaningful to the DXserver. No
other servers use these parameters.
For a list of all port numbers used in a default installation, see the section Port
Numbers Used by eTrust Directory in the chapter “DXserver Overview”.
Example DSA
Configuration
The following is an example of a DSA configuration:
set dsa DemoCorp =
{
prefix
dsa-name
dsa-password
};
= <c AU><o DemoCorp>
= <c AU><o DemoCorp><cn DXserver>
= "secret"
address
= tcp Eagle port 19389
snmp-port
console-port
ssld-port
= 19389
= 19390
= 1112
auth-levels
trust-flags
= allow-check-password
Viewing Communications Settings
You can view the listen addresses of the DXserver using the following command
at the DXconsole:
get stack;
An example output from this command is:
dap-psap
= ""
dsp-psap
= ""
disp-psap
= "DISP"
cmip-psap
= "CMIP"
address
= 207.2.6.99 port 19389
snmp-port
= 19389
ssld-port
= 1112
console-port
= 19390
snmp-description
= CA eTrust DXserver
snmp-contact
= supportconnect@ca.com
snmp-name
= democorp
snmp-location = http://www.ca.com
3–4
Alarms, Traces, and Logs
Output from the DSA can result from:
■
Responses to X.500 requests as entered from DXconsole
■
Echoing of input commands from the console or a script file
■
Trace information
■
Alarm information
The output from the DSA appears on DXconsole when it is open. It can also be
captured in a log file.
Alarms
Alarms report serious problems. Some triggers of alarms are:
■
A configuration problem—For example, a DSA fails to start because it has
the same listen address as one already running.
■
A usage problem, such as sending a DAP request to an LDAP port.
■
A system problem, such as running out of memory or disk space.
Unlike tracing and logging, alarm messages cannot be suppressed:
■
Alarm messages are always written to the alarm-log (which cannot be
closed).
■
When a console is open, alarm messages are sent to it.
■
When an snmp-log is open, an SNMP trap is raised for every alarm.
Traces
Tracing provides debugging information and analyzes service requests.
Tracing does not control what is logged to the summary, query, or stats logs.
In the DSA, the trace command controls the amount of tracing that is sent to the
DXconsole and trace-log file (if open).
3–5
The Trace Command
DXserver supports various forms of tracing. The trace options can be turned on
using the command:
set trace = option, option;
Multiple trace options can be specified.
Trace options in the set trace command are not cumulative and override options
set in previous set trace commands. In the following example, the final trace
option is summary:
set trace = time, error;
set trace = summary;
The time and error options are turned off by the second set trace command. The
none option turns all tracing options off.
Tip: Full tracing degrades performance, so you should use it only during
testing.
The following trace options are supported:
Trace Option
Meaning
alert
Displays authentication errors.
cert
Displays certificate operations.
connect
Displays connections.
diag
Traces local DXserver operations that were refused.
disp
Traces warnings during DISP recovery. See the chapter Replication for more information.
dsa
This option is similar to the x500 trace, but it also includes tracing of the module flow
inside the DSA.
error
Reports events that may impact on the ability of DXserver to perform a requested
operation. These events are usually more serious than those reported under warn. This is
the default trace level.
ldap
This traces detailed LDAP operations. The output can become quite large when searches
return a large number of entries.
none
Turns off all tracing .
query
Displays a one-line summary containing the request and a one-line summary of the
result.
stack
Displays detailed protocol tracing. The output can become quite large.
3–6
Trace Option
Meaning
stats
Displays statistical information for each minute the DSA is not idle.
summary
Displays a one-line summary containing the service request and result.
time
Displays the start time, end time, and elapsed time of an operation with a brief summary
of the operation.
update
Displays update operations—add, delete, modify, and rename.
warn
Displays a message when an X.500 service is not successful. For example, an object class
violation diagnostic might indicate that a mandatory attribute such as surname is
missing.
Warn messages usually represent a user error, rather than a problem with DXserver. This
is no longer the default trace level: see error.
x500
Displays the full detail of the service request, confirmation, or error. This traces DAP,
DSP, and LDAP operations. The output can become quite large when searches return a
large number of entries
We recommend that the error trace option is included in the set trace command
during normal operation.
Tracing Protocol
Low-level protocol can be traced. The protocol trace is written to the trace log, if
open. This tracing is only for debugging purposes. To enable protocol tracing,
use this command:
set trace = stack;
Tracing Statistics
The stats trace option enables you to retrieve the following minute-by-minute
statistical information about a DSA:
Label
Description
Assocs
Displays the number of current associations.
NilCredit
Displays the number of times flow control was applied (to any association).
NoTicks
Displays the number of times per second processing did not occur because the DSA was
too busy. When the number is more than 10, the DSA is very busy. The largest value is 60.
Queue
Displays the number of current outstanding operations.
Active
Displays the percentage of the time during the last minute that there was activity.
Activity covers local operations and chained operations. If Active is 0 it is safe to shut
down the DSA.
Ops
Displays the number of operations processed in the last minute.
3–7
Logs
The logs contain the output from a DSA.
Controlling Logging
The following commands control output:
■
trace options;
■
set trace = options;
■
set logType = filename;
■
close logType;
■
flush logType;
■
echo string;
■
echo-on;
■
echo-off;
These commands can be used in two ways. You can define these commands in
the configuration file (.dxc) in the logging directory, and you can also enter them
manually on DXconsole.
Log Types
DXserver supports the independent log types listed in the following table.
Log Type
Records
Description
alarm-log
Alarms
■
■
■
alert-log
All
authorization
errors
■
■
■
3–8
The alarm log is always open when a DSA is running. It cannot be
closed with the close command.
It has a default value of serverName_alarm.log.
All alarms are written to the alarm log, regardless of the tracing
level set or whether a DXconsole is open.
The alert log is only written if it has been opened with the set alertlog command. Writing to the alert log is not affected by the trace
setting.
When an alert log is open, the system records all authorization
errors. It can be used to show attempts at unauthorized access to
the DXserver.
It is time and date stamped, and a new one is written daily.
Log Type
Records
cert-log
Specific
certificate
operations
Description
■
■
■
connect-log
All released
connections
■
■
■
diag-log
Refused
DXserver
operations
■
■
■
The cert log is only written if it has been opened with the set certlog command. Writing to the certificate log is not affected by the
trace setting.
When a certificate log is open, the system records all add or modify
operations that include a userCertificate, caCertificate, or
certificateRevocationList attribute. In addition, any read or search,
or any search filter that returns one of these attributes, is recorded.
The connect log is only written if it has been opened with the set
connect-log command. Writing to the connect log is not affected by
the trace setting.
When a connect log is open, the system writes a line for each
connection made when the connection is released.
This log (or trace log if diag tracing enabled) will contain the reason
why local DXserver operations have been refused.
There are a number of situations where this may occur depending
on a DSAs configuration and data. An example would be if search
was performed with an invalid DN. The operation, affected entry
and diagnostic message will appear.
To enable this log, use the following commands:
set trace +diag;
set diag-log = "logs/$s_diag.log";
query-log
Search activity
■
■
■
stats-log
Summary of
operational
statistics
■
■
■
The query log is only written if it has been opened with the set querylog command. Writing to the query log is not affected by the trace
setting.
When a query log is open, the system writes a one-line summary of
the operation requested, which includes a time and date stamp.
The stats log is only written if it has been opened with the set statslog command. Writing to the stats log is not affected by the trace
setting.
When a statistics log is open, a one-line entry is added to the
statistics log file for every minute that the DSA is active. When the
DSA is not active, no information is written to the stats log; this
prevents the stats log from growing during inactivity.
3–9
Log Type
Records
summary-log Summary of
daily activity
Description
■
■
■
trace-log
Diagnostic
tracing
■
■
update-log
All add, delete,
modify, and
rename
operations
■
■
■
warn-log
Errors and
warnings
■
When a summary log is open, the system writes the summary
tracing for all operations to the summary log regardless of the
tracing level set or whether DXconsole is open.
When a trace log is open, tracing for all operations is written to the
trace log.
The level of tracing written to a trace log is dependent on the level
of tracing set on the DSA.
The update log is only written if it has been opened with the set
update-log command. Writing to the update log is not affected by
the trace setting.
When an update log is open, the system records all add, modify,
rename, and delete operations.
When a warn log is open, all errors and warnings are written to the
warn log.
■
Warnings are only listed if the tracing level is set to 'warn'.
■
Errors are only listed if the tracing level is set to 'error'.
■
3–10
The summary log is only written if it has been opened with the set
summary-log command. Writing to the summary log is not
affected by the trace setting.
Each warning or error written to the log is time- and date-stamped,
and a new log is written daily.
Log File Commands
Open a Log File
To open a log file, use the command:
set logType = "filename";
If a log file does not exist when opened, it is created. If it already exists, the DSA
appends the output.
If the log file name contains the string $S then the system substitutes the name
of the DSA. For example, when the name of the DXserver is DemoCorp, the
following command opens a log file named ../logs/DemoCorp.log:
set trace-log = "logs/$S.log";
Flush a Log File
To force all buffered output to a particular log file, use the flush command. This
feature is provided so you can examine a current log file off-line while the
normal log file is still open. To flush a log file, use the command:
flush logType;
Note: Alarm logs are always flushed.
Close a Log File
The close command stops output to the log file by closing it. When the DSA
shuts down, it automatically closes any open log file. To close a log file, use the
command:
close logType;
Inspect Names of Log
Files
To inspect the names of each of the enabled log files (including the snmp-log
file), use the following command:
get log;
The following is an example of the output:
alarm-log
summary-log
stats-log
trace-log
query-log
update-log
alert-log
cert-log
connect-log
snmp-log
=
=
=
=
=
=
=
=
=
=
logs/democorp_alarm.log
logs/democorp_20010122.log
logs/democorp_stats_20010122.log
logs/democorp_trace.log
logs/democorp_query_20010122.log
logs/democorp_update_20010122.log
logs/democorp_cert_20010122.log
logs/democorp_connect_20010122.log
udp eagle port 9999
3–11
History Files
Most of the log files, once opened, start afresh each day.
For example, the following command produces a log file in the logs directory of
the form serverName_yyyymmdd.log for each day there is activity on the DSA.:
set summary-log = "logs/$S.log";
You can use these history files to inspect auditing, accounting, billing, and
statistical information.
Echoing
Echoing is the process of displaying the commands in a script file before
executing them..
There are three echo commands:
■
echo-off;
■
echo-on;
■
echo "string";
The output of echoed commands goes to DXconsole (if connected) and the tracelog file (if open).
To prevent the display of commands in a script file during startup, echo is off by
default. (See the chapter “DXserver Overview”) To view each command before it
is executed, use the echo-on command.
Messages on the console can be displayed using the echo command, for example:
echo "Initializing ...";
Turning echo-on in a script might slow the execution of the script slightly.
3–12
Associations
Associations
An association is a connection to a DSA. The number of DSA associations can be
managed using the assoc module commands.
The association commands have the following forms:
■
set parameter = value;
■
get parameter;
■
assoc action;
The assoc Command Options
The following are the parameters of the assoc set command:
Keyword
Parameter
Description
allow-binds
Boolean
When FALSE, new associations are rejected. Use this to
perform a graceful shutdown.
auth-trap
Boolean
Turns on raising an authentication trap whenever an
authentication failure occurs.
min-auth
none,
clear-password, or
ssl-auth
The minimum authentication level required on a bind.
credits
Integer
The maximum number of concurrent operations the DSA
processes for each user association.
force-encrypt-anon
Boolean
Forces SSL encryption on anonymous binds.
When this setting is on, if a user attempts to create an
anonymous bind without SSL, the DSA will disallow the
bind and return an "Inappropriate authentication" error.
force-encrypt-auth
Boolean
Forces SSL encryption on authenticated binds.
When this setting is on, if a user attempts to create an
authenticated bind without SSL, the DSA will disallow the
bind and return an "Inappropriate authentication" error.
hold-ldap-connections
Boolean
When TRUE, prevents a DSA from clearing the underlying
TCP/IP connection after a bind refusal.
max-bind-time
Integer or none
The maximum time, in seconds, that any particular
association can last (a value of 0 or none means
unlimited).
3–13
Associations
Keyword
Parameter
Description
max-pdu-size
Integer
The largest size (in bytes) that a protocol data unit may be
to be accepted by DXserver. The default value is 0,
meaning unlimited.
This value may be retrieved with the 'get assoc;'
command, if the value has been set.
max-users
Integer or none
The maximum number of current associations (number of
users bound to the DSA).
op-error-trap
Boolean
Turns on raising an operation error trap whenever an
operation error occurs.
password-age
Integer
The number of days a password is valid. By default, this
feature is disabled (0).
password-history
Integer
The maximum number of entries to retain in the history.
By default, this feature is disabled (0).
password-last-use
Integer
The number of days a password remains valid when it is
not used. When the value is exceeded, the password
expires. By default, this feature is disabled (0).
password-length
Integer
The minimum length of a password. The default is 6
characters.
password-maxsuspension
Integer
The number of seconds after which a suspended password
reactivates. By default, this feature is disabled (0).
password-min-age
Integer
The number of days that transpire between changing a
password (lockout period). By default, this feature is
disabled (0).
password-non-alphanum
Integer
The minimum number of nonalphanumeric characters a
password must contain. The default is 0.
password-numeric
Integer
The minimum number of numeric characters a password
must contain. The default is 0.
password-policy
Boolean
Enables or disables password management. See Password
Management in the chapter “Security.”
password-retries
Integer
The number of consecutive failed logon attempts before a
password is suspended. The default is 3.
role-subtree
DN
The DN of the subtree that stores the roles. Together with
use-roles, it is used to set role-based access controls. For
information about roles, see Role-based Access Controls in
the chapter “Security.”
ssl-auth-bypass-entrycheck
Boolean
Turns off automatic checking for the existence of an entry
named by the subject held in the certificate.
3–14
Associations
Keyword
Parameter
Description
trap-on-update
Boolean
Turns on raising an SNMP trap whenever an update
occurs.
trust-sasl-proxy
DN
The distinguished name of the trusted proxy.
use-roles
Boolean
Enables or disables role-based access control.
user-idle-time
Integer
The maximum idle time in seconds. When a user is idle for
user-idle-time seconds, that user is disconnected. This
reduces the number of users connected and lets new users
connect to the DSA.
The following are the parameters of the assoc get command:
Parameter
Description
assoc
Shows the current association configuration values of the
DSA.
users
Provides information about currently bound users.
The following is the action of the assoc command:
Value
Description
abort
Abort one or all associations.
Viewing Association Configuration
To inspect the current association configuration, use the command:
get assoc;
This command shows the current association configuration values of the DSA.
Details of the sample of output from this command are below:
max-users
max-bind-time
user-idle-time
allow-binds
min-auth
credits
trap-on-update
auth-trap
op-error-trap
ssl-auth-bypass-entry-check
use-roles
hold-ldap-connections
password-policy
=
=
=
=
=
=
=
=
=
=
=
=
=
255
0
3600
TRUE
none
5
0
0
0
FALSE
FALSE
FALSE
FALSE
3–15
Associations
Viewing Associations
The assoc module maintains information about all associations. This includes
connection information, connect times, idle times, and so on. The command get
users returns a list of currently bound users. A sample of output from this
command follows:
Association 0: connected for 240 seconds, idle for 5 seconds
Association 0: bound using *UNKNOWN* from TCP 0.0.0.0 as ANONYMOUS
Association 1: connected for 111 seconds, idle for 24 seconds
Association 1: bound using DAP from TCP 172.24.131.145 as PASSWORD AUTH user:
<countryName "US">
<organizationName "CA">
<commonName "Berndt Stark">
Tracing Associations
The association trace facility controls the X.500/LDAP operation tracing of
individual users through the DXconsole. Users are assigned association numbers
in the order in which they bind to the DSA. The first user to bind to the DSA
receives association number 0, the second user receives association number 1,
and so on.
Control Association
Tracing
To control the association tracing, use the command:
trace enable assoc = association_number
For example, to trace a specific association, first open a DXconsole session using
telnet. Set the tracing to error only:
set trace = error
Determine the association number of the user that requires tracing with the get
user command (see Viewing Associations in this chapter) and supply that
number to the trace enable command.
Disable Association
Tracing
To disable the association tracing, use the command:
trace disable assoc = association_number
Stopping a DSA
To shut down the DSA with DXconsole, use the command:
dsa> shutdown;
3–16
Associations
Association Times
User connections can be unconditionally aborted by setting a maximum bind
time. Any user bound to the directory for longer than the maximum bind time
automatically has their association aborted. To set the maximum bind time, use
the command:
set max-bind-time = 3600;
The value is the maximum number of seconds a user can be bound to the DSA
(the example shows 3,600 seconds, or one hour). 0 = no limit.
Controlling Binds
Two assoc module commands control the bind operation. The first is allowbinds. When set to false, the system rejects all binds. The second, min-auth, sets
the minimum authentication level required on a bind. When set to clearpassword, a user name and password must be provided with the bind request.
The system checks this user name and password against an existing entry in the
directory database before allowing the bind. For example:
Allow Binds
Disable New Binds
set allow-binds = true;
set min-auth = clear-password;
To shut down the DSA gracefully, the administrator can disable new users
binding to the DSA and then wait until each association unbinds or times out.
To disable new binds, use the command:
set allow-binds = false;
Any new user that attempts to bind to the DSA receives a bind-refuse with the
following error:
Bind-Error: Service Error: Directory unavailable
Monitor Active Users
Before allowing or disabling binds, you may want to see who is currently
bound to the DSA. To monitor active users, use the command:
get users;
The command displays the number of users, their connection time, connection
address, and user name.
See the chapter “Security” for more information about authentication and binds.
3–17
Associations
Aborting Associations
As described previously, to obtain information about currently connected users,
use the command:
get users;
You can abort all or some associations by using this information and one of the
following commands (assuming 131072 is a valid association).
abort all-users;
abort user 131072;
Concurrent Associations
You can configure the maximum number of users that can be bound to the DSA.
For example, to set this value to 100, use the command:
set max-users = 100;
Note: The operating system sets an upper limit of allowed associations per DSA,
which relates to the maximum number of file descriptors per process. The maxusers value can be set to 0 to prevent any users from binding to the DSA.
Set Maximum Idle
Time
To increase availability of the directory, you should set the maximum idle time
parameter. The idle time for a user is the time elapsed since the DSA performed
the last operation on that user’s association. Any connected user idle for longer
than the maximum idle time automatically has the association aborted. The
maximum idle time is set with the command:
set user-idle-time = 600;
The value is the number of seconds a user connection can be idle before risking
a disconnection (the previous example shows 600 seconds, or 10 minutes).
The system rejects an association when the number of current associations is at
the specified max-users limit, and no user has exceeded his or her maximum
bind time or maximum idle time.
3–18
Associations
Association Queues
The maximum number of DSA operations in progress at the same time on a peruser basis can be set using the credit limit, for example:
set credits = 5
To determine the maximum number of concurrent operations you can perform,
multiply the number of credits by the maximum number of users. When the
credit value is exceeded, the DSA delays the receipt of any new requests from the
DUA.
There is a difference between this value and the max-local-ops value (see Local
Operations in this chapter). The credits parameter provides a mechanism to
govern how many client requests are outstanding at any given time for each
association and to delay new requests. Conversely, the max-local-ops value
rejects new operations above its limit.
3–19
Local Operations
Local Operations
You can manage local operations using the oper module commands. The
operation commands have the following form:
■
■
get parameter;
■
oper action;
The commands are defined in the configuration file (.dxc) in the limits directory.
The oper Commands
The following are the parameters of the operation set command:
Keyword
Parameter
Description
access-controls
Boolean
TRUE enables access controls; FALSE disables access controls.
add-oc-parents
Boolean
When set to TRUE, it causes DXserver to add superior object
classes even if the client did not specify these while adding an
entry. It complements the prune-oc-parents and return-oc-parents
flags and is added for Netscape compatibility.
dynamic-access-control Boolean
Used to enable or disable dynamic access controls. For more
information, see the chapter “Security.”
ignore-name-bindings
Boolean
When set to TRUE, it lets the DXserver operate without name
bindings. This can be useful when the schema is imported
from a directory that does not support name bindings. For
more information, see the chapter “Schema Definition.”
max-local-ops
Integer
The maximum number of concurrent operations the DSA
processes for all users.
max-op-size
Integer or the
keyword none
The maximum number of entries that a search or list can
return (a value of 0 or the keyword none means unlimited).
This value overrides a user-requested size limit service control
when the max-op-size is less than the one requested by the
user.
max-op-time
Integer or the
keyword none
The maximum time (s) that any particular operation can last (a
value of 0 or the keyword none means unlimited). This value
overrides a user-requested time limit service control when the
max-op-time is less than the one requested by the user.
op-attrs
Boolean
When set to TRUE, operational attributes are added
automatically to each entry by the DSA; when set to FALSE,
operational attributes are treated like regular attributes.
prune-oc-parents
Boolean
For more information, see the chapter “Schema Definition.”
3–20
Local Operations
Keyword
Parameter
Description
return-oc-parents
Boolean
For more information, see the chapter “Schema Definition.”
role-subtree
DN
The distinguished name of the subtree used to store roles.
For more information, see the chapter “Security.”
trust-sasl-proxy
DN
The distinguished name of the trusted proxy.
use-roles
Boolean
Used to enable and disable role-based access controls.
The following DSA flag identifies a DSA as a read-only (no updates permitted)
DSA. You can set this flag in the set dsa command in the knowledge directory.
dsa-flags = read-only
The following are the parameters of the operation get command:
Parameter
Description
oper
Shows the current operation configuration values of the
DSA.
stats
Returns a list of operation statistics.
The following are the actions of the oper command:
Value
Description
abandon
Abandons one or all operations on a particular association.
reset
Resets the statistics counters.
3–21
Local Operations
Viewing Operation Configuration
The following command shows the current operation configuration values of the DSA:
get oper;
Here is an example of the output of this command:
max-local-ops
max-op-time
max-op-size
access-controls
op-attrs
read-only
prune-oc-parents
return-oc-parents
add-oc-parents
dynamic-access-control
modify-on-add
unique-attrs
ignore-name-bindings
=
=
=
=
=
=
=
=
=
=
=
=
=
200
120
200
FALSE
TRUE
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
attr1, attr2
FALSE
Viewing Operation Statistics
List Operation
Statistics
The oper module maintains statistics about all operations, including events,
services, errors, timeouts. The following command returns a list of operation
statistics:
get stats;
An example of the output of a get stats command is given below
anonymous binds = 43
in ops = 789
read ops = 350
add entry ops = 1
modify entry ops = 3
modify-dn ops = 1
list ops = 371
search ops = 6
whole tree search ops = 6
errors = 2
name errors = 1
found local entries = 187
no such object = 1
DSA statistics can be read using SNMP or CMIP. The Management Information
Base (MIB) being read defines the names displayed from those actions. For
example, noSuchObject displays as “no such object.”
Reset Counters
The statistics are stored in counters. To reset these counters, use this command:
reset stats;
3–22
Local Operations
Concurrent Operations
To restrict the maximum number of DSA operations in progress at the same time,
use the following command:
set max-local-ops = 100;
Administration Limits
To restrict the maximum time that the list and search services can run and the
maximum number of entries these operations can return, use the following
command:
set max-op-time = 20;
set max-op-size = 100;
If an operation exceeds either of these limits, the error “Administration limit
exceeded” is returned.
Operational Attributes
To control the automatic creation and updating of operational attributes (for
example, last modified time) on entries in the DSA, use the following command:
set op-attrs = true;
If it is set to true, the DSA will automatically control the creation and updating of
operational attributes.
The op-attrs parameter should normally be set on each DSA.
Note: If the multi-write-disp-recovery flag is set, the op-attrs parameter must be true.
If the op-attrs parameter is set to false, then:
■
■
The DSA will not create or update operational attributes
All no-user-modification schema settings will be overridden. This means that
an administrator will be able to update any operational attributes manually.
Access Controls
To control the level of security available on the DSA, use this command:
set access-controls = true;
When access controls are enabled and no rules are defined, no entries are visible
and the directory cannot be viewed or updated. However, it is still possible to
load the directory using the bulk load tools. For more information about access
controls, see the chapter “Access Controls.”
3–23
Local Operations
Read Only
To reject all updates, set the read-only DSA flag in the configuration file (.dxc) in
the knowledge directory, using the set dsa command:
This guarantees update security and over-ride any access controls. It is very
useful for public DSAs. In conjunction with a public DSA, an administrator can
start up a local DSA that connects to the same database to perform updates.
Abandoning Operations
To obtain information about the current users, use the command:
get users;
You can abandon any outstanding operations using this information and one of
the following commands (assuming 131072 is a valid association and 2 is a valid
operation):
abandon all on association 131072;
abandon operation 2 on association 131072;
When an operation is abandoned, the targeted service returns the following
error:
Service error: operation abandoned
The abandoned operation itself returns an abandon confirm. If the operation
cannot be abandoned, it returns an abandon-refused message with the
appropriate error.
A DSA can truncate processing an operation when it exceeds the global
configuration values, for example:
set max-op-time = 60;
set max-op-size = 100;
Tip: Services that exceed global limits are not abandoned; rather they return
an error or partial result.
The result returned by an abandoned operation depends on how far the
operation progressed before being abandoned. The display shows either the
following error message:
Service error: administration limit exceeded
or partial results (with the partial outcome qualifier set to the appropriate
problem). An update operation cannot be abandoned.
3–24
The Directory Information Base
To manage the DIB, use the commands:
■
■
get parameter;
The following are the parameters of the DIB set command:
Keyword
Parameter Description
alias-integrity
Boolean
Enables or disables alias integrity checking.
See the section Alias Integrity.
database-name
String
The database that is connected to the server.
dbconnection
A compound value, which consists of database-name, databaseuser, and user-password.
eis-count-attr
Attribute
An attribute name.
index-reverse
Attributes
List of attributes to be reverse-indexed.
See the section Indexing Options.
index-wide
Attributes
List of attributes to be wide-indexed.
not-searchable
Attributes
List of attributes to be marked as not searchable.
password-storage
The method used to store user passwords. See the section
Password Storage for the list of password storage methods.
shutdown-on-sql-error Boolean
Sets the DSA to shut down whenever an untrapped database error
occurs. See the section Manage Connections to the Database
Two flags in the knowledge directory affect operations on the database. These
are the limit-list and limit-search flags.
set dsa DemoCorp = {
...
DSA flags = limit-list, limit-search, ...
...};
The following is the parameter of the DIB get command:
Keyword
Value
dib
Shows the DSA configuration values of the directory information processor.
See the appendix “DXserver Command Language” for information about
grouping commands accurately.
3–25
Viewing DIB Configuration
To monitor the database management settings, use the DIB module’s get
commands at DXconsole.
To view the DIB configuration variables and their values, use the command:
get dib;
Example output of this command is shown below:
alias-integrity= TRUE
database-name
database-user
database-password
eis-count-attr
limit-search
limit-list
password-storage
=
=
=
=
=
=
=
demo
fred
*****
dxEntryCount
FALSE
FALSE
sha-1
Database Name
The DSA must know the name of the database it accesses. This value is usually
set in the initialization file (.dxi) through the database configuration file (.dxc),
for example:
set database-name = demo;
where demo is the name of an Advantage Ingres database.
In certain situations, because of the access controls required to access Advantage
Ingres databases, it may be necessary to supply a user name and password.
Database applications, in this case the eTrust Directory DXserver process, must
supply these credentials to Advantage Ingres when accessing the database. If this
situation arises, use the alternate form of the database configuration command as
shown below:
set dbconnection = { db-name = demo, db-user = ingres, db-password = secret };
where demo is the name of the database, ingres is the user name and secret is the
password.
Tip: Throughout this guide, references to Advantage Ingres include both
Ingres II and OpenIngres, unless one or the other is explicitly specified.
See Databases in the chapter “DXserver Overview” for more information about
databases.
3–26
Manage Connections to the Database
eTrust Directory manages problems with the DSA connection to the database in
two ways:
■
If a DSA cannot connect to a database, it raises an alarm and shuts down.
■
You can set each DSA to shut down when a database error occurs
DSA Shuts Down If Database Connection Lost
If a DSA cannot connect to a database, it raises an alarm and shuts down. For a
description of the alarms, see the section DXserver Alarm Messages in the
appendix “Messages and Logs”.
If a DSA shuts down due to an Ingres error, you should check the Ingres logs to
find out what the problem was. For more information about Ingres logs, see the
section Advantage Ingres Logs in the appendix “Messages and Logs”.
Shut Down DSA If a Database Error Occurs
You can set each DSA to shut down if the database produces an error. By default,
this option is off.
If you are concerned that a DSA may
It is possible that a database could To set a DSA to shut down if the database
produces an error, use the following command:
set shutdown-on-sql-error = true;
Alias Integrity
When an entry that has one or more aliases pointing to it is removed, the aliases
are also removed. This occurs regardless of the setting of the alias-integrity flag.
When alias integrity is turned on, invalid aliases (where no referenced entry
exists) cannot be added.
To disable the alias integrity feature, use the command:
set alias-integrity = false;
See Aliases in the appendix “DXconsole DUA” for more information about
aliases.
3–27
Counting Entries
It is often useful to know how many entries in the directory satisfy a specific set
of search criteria. However, performing such a search and counting the entries
returned is not feasible in an automated system or in a system where the search
returns large numbers of entries.
Searches can return the number of entries that satisfy the search rather than the
entries themselves using the eis-count-attr parameter. This parameter can be set
to an unused attribute. We recommend that you use the attribute dxEntryCount
in the database settings file database/default.dxc:
set eis-count-attr = dxEntryCount;
To enable a search to return the number of entries satisfying a search filter
simply set the attributes to be returned by the search to the eis-count-attr
attribute:
search-req
base-object = <c "AU"><o "Democorp">
whole-subtree
filter = { attr = surname substrings [ initial "C" ] }
attrs = dxEntryCount;
The resulting search returns a single entry with a dxEntryCount attribute. This
attribute is set to the number of entries found that satisfy the search filter. For
example:
SEARCH-CONFIRM
...
Entry:
<countryName "AU">
<organizationName "Democorp">
Content:
(dxEntryCount 98)
This search result indicates that there are 98 entries with a surname beginning
with "C" in the DemoCorp directory.
Rejecting All list Commands
There can be instances where a DIT has a very flat structure and there are many
thousands of entries under one node. In this case, the list operation is not useful.
The DSA can be set to reject all list requests by setting the limit-list DSA flag in
the knowledge directory, using the set dsa command:
dsa-flags = limit-list
For information about using the limit-list flag to set up query streaming, see
Query Streaming in the chapter “Distribution and DSP.”
3–28
Rejecting All Unfiltered Searches
There may be instances where a DSA is set up to handle large numbers of simple
lookup searches, and a high throughput is very important. Large complex
searches can put unwanted pressure on the performance of the DSA.
It is possible to limit the types of searches processed by setting the limit-search
DSA flag in the knowledge directory, using the set dsa command:
dsa-flags = limit-search
This flag causes searches with no filter or with a filter containing an attribute
present, substrings any, or a range of values (>=, <=) to be rejected. Only simple
(or exact) searches are accepted.
For example, if you want to search for all people with a surname of Smith and
enter sn=smith, your request is processed; however, if you search for all
surnames that sound like Smith, and enter sn~=smith, your request is rejected.
For information about using the limit-search flag to set up query streaming, see
Query Streaming in the chapter “Distribution and DSP.”
For more information about phonetic match searching, see Chapter 13 in the
eTrust Directory User Guide.
Password Storage
To check a password, an application requests a compare operation. The DSA will
then hash/encrypt the candidate password, and compare it with the value saved
in the directory.
The DXserver can store user passwords in a number of formats:
■
■
sha-1—This is the default
ssha-1—This format implements the SHA-1 algorithm used by Netscape,
iPlanet, and Sun.
■
oem-hash
■
oem-encrypt—This is a reversible format
■
crypt
■
md5
3–29
Indexing Options
Indexing helps with the search process.
Indexing options can appear anywhere in the database configuration after the
schema definitions. If they appear after the database definition, then warning
messages for items already indexed in the database will be produced. This
database configuration file must come after the schema configuration file in the
server initialization file.
You can use the tool dxindexdb to set up the index. For more information, see
Managing Indexes: DXindexdb in the chapter ‘Using DXtools’.
Important! If you have indexed the database with DXtools (for example, dxindexdb),
ensure that the attributes indexed here match those in the database.
Indexing Commands
Use the following commands to set the options:
set not-searchable = attribute-1[, attribute-2…]
set index-wide = attribute-1[, attribute-2…]
set index-reverse = attribute-1[, attribute-2…]
clear indexes
where attribute-n is an attribute name that is either an LDAP or alternate name,
but not an OID.
The following table describes the index settings:
Keyword
index-reverse
Attributes
Lists attributes which will be indexed in reverse order. This is useful for
attributes which begin with the same prefix.
For example, you could reverse-index a list of the physical addresses of
network cards (44-45-53-54-42-00, 44-45-53-54-42-01, and so on).
index-wide
Attributes
Lists attributes which will be given a wide index. Use wide indexing for
attributes whose values you expect to be longer than 106 characters.
not-searchable
Attributes
Lists attributes which are to be marked as not searchable. This is useful for
increasing the speed of operations (updates, searches etc).
Search operations containing these attributes will return the message
“Unwilling to perform.” The list of attributes must match those set in the
database configuration file.
Important! If a DSA has either DISP replication or multiwrite recovery set (see
the chapter “Replication”), do not set the createTimestamp, modifyTimestamp, or
deleteTimestamp attributes as not searchable.
3–30
Creating Additional Wide Indexes
To create additional wide indexes for some attributes without changing any wide
indexes that have already been set up, use the add command at the bottom of
each schema for which the wide index is required:
add index-wide = attribute-1[, attribute-2…]
One set index-xxxx command initializes all xxxx indexes, so if you specify two
commands for the same special index, only the attributes of the second
command will be indexed.
For information about using these options, see the eTrust Directory User Guide.
Warning Message: “Attribute (attrname) exceeds searchable size limit (size)”
You may see the following warning message from DXserver:
Attribute [attrname] exceeds searchable size limit [size] where:
■
attrname is an attribute, and
■
size is the size limit that has been exceeded.
This message means that you stored a value in the attribute that exceeds the
normkey. That value cannot be successfully searched for after the limit.
The limit for the search table is 106 bytes, and for the wide index is 1900 bytes.
If you need accurate search results for this attribute you need to create a wide
index for it.
If users rarely or never perform a search on this attribute, then you should turn
the indexing for this attribute off.
3–31
DXcache
DXcache
DXcache uses in-memory techniques to make lookups on indexed attributes even
faster.
In a system with DXcache running, some or all attributes are preloaded into
memory. When a search request involving one of these preloaded attributes is
sent to the directory, the request is directed to the cache.
Example: Using
DXcache to speed
up lookups of
customer details
You are setting up a directory of customer details for the call center of a phone
company. The call center staff usually look up customer details using the
customer’s account number, and they usually want to see the customer’s name
and account balance. To speed up these lookups, you should index the account
number attribute, and cache the attributes for the account number, the customer
name, and the account balance.
How DXcache Works
When DXserver starts up, it looks in the DXI configuration file to work out which
attributes should be indexed or cached. It caches and indexes those attributes.
When a search request is sent to the directory, it might be directed to the cache,
or it might go to the database:
■
■
If a search is a simple lookup of an indexed attribute in the cache, requesting
attributes that are in the cache, it is directed to the cache.
If a search uses attributes that are not cached, it is sent to the database. This
means that DXserver’s proven superior performance for complex searches is
maintained.
The following table shows what kinds of search DXcache can handle in different
situations:
Attributes in Search
Filter
Attributes to be
Returned after a Search
Search
Indexed
Cached
The search will be
performed in the cache.
Cached
Cached
The search will be
No filter
Cached
The search will be
Some of these attributes are not cached
3–32
The search will be
performed in the directory.
DXcache
Design the DXcache System
If you plan to use DXcache, you need to decide which attributes your users are
likely to search on, and which attributes they are likely to want to return. Then,
set up the following:
■
■
Index the attributes that users are likely to enter in the search filter.
Cache the indexed attributes, and the attributes that users are likely to
request.
You can load all attributes into the cache, to make all searches faster. This would
make the cache much larger than if you only cached some attributes.
DXcache also supports base-object searches, in which the search is restricted to
objects below the object specified as the base object.. For base-object searches, the
filter is not required, but all the other DXcache conditions must be met.
Note: Multiwrite–DISP recovery cannot be used in conjunction with the cache
where more than one DSA is attached to the same database.
Note: The DSA start time depends on the number and size of the attributes that
are to be loaded into the cache.
Enable and Configure DXcache
To enable caching, add the following command to the DXI initialization file:
set lookup-cache = true;
This command must appear after the cache and database definitions in the
initialization file. DXserver loads the cache as soon as it reads the set lookup-cache
command.
To configure DXcache, you need to add further commands to the initialization
file. These commands include::
set
set
set
set
set
set
cache-attrs
cached-only-attrs
cache-index
cache-load-all
cache-reverse
max-cache-size
=
=
=
=
=
=
{attribute1 [, attribute2 …] | all-attributes};
attribute1 [, attribute2 …];
boolean;
number;
3–33
DXcache
DXcache Settings
The following table describes the DXcache settings:
DXcache Setting
Description
cache-attrs
Defines the attributes that are returned.
Use the value all-attributes to ensure that all attributes are cached; however, when
a large number of attributes are used, this requires a large amount of memory.
cached-only-attrs
Specifies the attributes that will be stored in the cache only.
cache-index
Defines which attributes will be indexed.
The cache responds to a search filter that uses one of these attributes. You can
define as many as you like, separated by commas. Memory requirements are
affected.
cache-load-all
Forces DXcache to load all entries in the database into the cache.
DXcache can only handle searches where the filter does not reference an indexed
attribute if it knows that all the entries have been loaded into the cache.
cache-reverse
Sets the cache to reverse-index the attributes.
lookup-cache
Enables or disables DXcache.
max-cache-size
Sets the maximum amount of memory (in MB) that the cache is permitted to use.
This setting depends on how much memory your computer has. We recommend
that you set this to 50% to 70% of your machine’s total memory, depending on
other programs’ memory requirements on the same computer.
Note: The cache uses the minimum amount of memory required to store the
indexes and results. An alarm is raised and the cache is disabled when the cache
requires more memory than defined with max-cache-size.
Index the Attributes To Be Used in the Search Filters
The following command indexes the attributes that appear in the search filters:
set cache-index = attribute [, attribute …];
The cache holds all entries that contain one or more of these attributes. Entries
that contain none of the attributes in this list are not loaded into the cache. The
choice of indexed attributes directly affects the number of entries in the cache.
3–34
DXcache
Index the Attributes To Be Returned by Search Requests
The following command specifies the attributes that will be returned by the
search request:
set cache-attrs = {attribute1 [, attribute2 …] | all-attributes};
The indexed attributes are already cached so you only need to specify any
additional attributes.
Search requests that do not specifically request particular attributes to be returned
are actually implicitly requesting the return of all attributes. To cater for this type
of request, you can use the following command to cache all attributes:
set cache-attrs = all-attributes;
If you cache all attributes, DXcache will require more memory than if you cached
only some attributes.
Set the Maximum Cache Size
To set the cache size, use the following command:
set max-cache-size = number;
You must specify the maximum memory that the cache may use. The cache
always uses the minimum amount possible.
The cache is designed to be memory-resident, so make sure that the maximum
cache size is less than the RAM available. For example, if the cache size is 2 GB
but there is only 500 MB of RAM, the cache has not been configured correctly.
One million entries, including their attributes, occupy about 2GB of memory.
DXserver and other 32-bit Windows applications each have a virtual address
space limitation of 2GB, regardless of the amount of memory in the system.
UNIX-like operating systems have a limit of 4 GB.
Do not set the cache size equal to the memory available. You should leave some
RAM for the operation system. For example, if your operating system uses
250 MB on a 1 GB computer, do not set the max-cache-size to more that 750 MB.
3–35
DXcache
Set DXcache to Process All Search Requests
The cache does not help with some types of search request. For example, the
following requests will be directed to the database, not to the cache:
■
commonname=*smith*
■
Search requests where the filter does not specify an indexed attribute.
■
One-level searches without filters (or with the filter (objectclass=*)
To set the cache to process all search requests, add the following commands:
set cache-load-all = true;
set cache-attrs = all-attributes;
The first command ensures that all entries are loaded into the cache, while the
second ensures that all attributes in each entry are loaded. Each of them increases
the amount of memory used by the cache, so make sure that you only use them if
required.
Generally, NOTs can only be processed if all entries are in the cache.
Reverse-Index Cached Attributes
If the users use searches of the form (telephonenumber=*1234), you may index
some attributes so they index the values after reversing the order of the bytes.
Use the following command to reverse-index a cached attribute:
set cache-reverse = attribute
For example, 123-4567 will be indexed as if it were 7654-321.
Example DXcache Configuration
You are running DXserver on a 2GB system, and you want to use a 1.5 GB cache.
You know that users often search on the attributes commonName and
organizationalUnitName, and they often want to return the attributes commonName
and description.
To configure DXcache for this situation, add the following commands to the end
of the servername.dxi file.
set database-name = database;
:
set
set
set
set
3–36
lookup-cache = true;
cache-attrs = description;
cache-index = commonName, organizationalUnitName;
max-cache-size = 1500;
DXcache
View the DXcache Configuration
To view the cache configuration variables and their values, use the command:
get cache;
This command displays whether the cache is enabled and provides some
statistical information about the cache configuration. Example output of this
command is shown below:
Cache enabled
max-cache-size = 1000 (MB)
entry hash size 2550, maxp 10
cache-attrs = postalCode cosineUserid
cache-index =
surname(0/0)
commonName(0/0)
Memory used by cache: 1008316/1183947
Keep DXcache Synchronized with the Database
Updates received by a DSA running DXserver are applied first to the database
and then to the DXcache.
All updates successfully applied to the database are applied to the cache.
Therefore, if no other DXserver is updating the database, the cache will remain
synchronized.
If the database is updated by other instances of DXservers, you should configure
the DXservers to keep their caches synchronized. To achieve this, set the
following:
■
■
All DXservers that update the database must belong to a multiwrite group
(see the chapter Replication for more information about multiwrite groups.)
All DXservers that update the database must have the DSA flag multi-writenotify set in their knowledge file.
The effect of this is that multiwrite updates are sent to the cache but they will
update only the cache contents—they are not reapplied to the database. Thus, the
cache remains synchronized with the database.
3–37
DXcache
Use eTrust Directory in Cache-Only Mode
You can run eTrust Directory in cache-only (memory-resident) mode. In this
mode, eTrust Directory uses DXcache as its repository, rather than a database.
Traditional directories were designed with the following assumptions:
■
Persistent data storage
■
Data is read much more often than it is written to
However, with the advent of web applications and web services, there is a
growing need for a directory service with the following characteristics:
■
Transient data storage
■
Data is read about the same number of times it is written to
Configure Cache-Only Mode
To create a cache-only DXserver, simply remove all references to database and
database settings, and add the following to your configuration:
set cache-only = true;
Of course none of the database DXtools can be used with a cache-only DXserver.
You must use the DXmodify or ldapmodify tools to load the cache and the
DXsearch or ldapsearch tools to dump its contents.
How eTrust Directory Works in Cache-Only Mode
A cache-only DXserver reads and writes data extremely quickly. It can service
thousands of updates per second, rather than the tens or hundreds of updates
per second for traditional directories.
This update speed is achieved because the data in the repository is never written
to disk. There is no write-behind strategy of any kind. A cache-only DXserver
does not even require Ingres or any other database to be running.
If a cache-only DXserver is shut down or is stopped by a software or hardware
problem, all data is lost and cannot be recovered. Thus it is ideally suited for
storing short-lived data that needs to be updated frequently.
3–38
DXcache
Example of a Cache-Only Directory
You could use a cache-only directory to store web session objects.
These objects are only required for a short time and may be updated repeatedly,
and have no long-term value. There may be thousands of these objects in use at
peak times and so an application still requires the scalability and availability
offered by traditional directories. However, storing such objects in a traditional
directory is prohibitively expensive because of the cost of updates which must
eventually be written to disk.
In this situation, a cache-only DXserver could be used to manage only the session
objects, leaving a traditional directory to manage the persistent data.
3–39
Virtual Attributes
Virtual Attributes
This section describes two different kinds of virtual attributes:
Dynamic groups
These can reduce the time you spend updating the membership of groups.
Class of Service templates
These can reduce the size of the directory, reduce the time you spend doing
bulk updates, and help keep information consistent.
Dynamic Groups
eTrust Directory supports static, dynamic, and hybrid groups.
Static groups are useful for directories when the members of groups do not
change often.
Dynamic groups are useful when you know that you will often need to change
the membership of a group, because there is no overhead involved in
maintaining the group data.
Hybrid groups allow you to use the features of both static and dynamic groups.
How Static Groups Work
Users and other entries can be grouped in the directory using a static group
entry. A static group entry contains a list of member DNs. The static group entry
usually has an object class of “groupOfNames” and an attribute “member” that
has one value for each of the members in the group.
If a user is removed from the directory, then the user must also be removed from
any static groups that they belonged to. This must be done manually by
removing the user’s member DN from each group that the user was a member
of.
How Dynamic Groups Work
A dynamic group does not store each member DN in its directory entry. Instead,
it stores an LDAP search request that is executed when a base-object search is
performed on the dynamic group entry. This LDAP search finds all the members
that satisfy the search filter and return the DNs of those members.
If a user is removed from the directory, then their user entry will not be found by
the LDAP search, so the user will have been automatically removed from the
dynamic group.
3–40
Virtual Attributes
How Hybrid Groups Work
It is possible to create a hybrid group. This is a group entry that contains both an
LDAP search attribute and a list of one or member DNs.
To create a hybrid group, make sure that the “member-attr” in the dynamic
group definition is the same as the attribute used to store the static members.
This means that the static and dynamic members will be combined when a baseobject search is performed on the entry.
Enabling Dynamic Groups
To turn on dynamic groups, add the following to the DSA configuration file.
clear dynamic-group;
set dynamic-group GROUP = {
object class = groupOfURLs
url-attr
= memberURL
member-attr = member
};
You can also use other object classes and attributes than those shown above.
However, the “url-attr” must have a string syntax and must be a MUST or MAY
container attribute of the object class. The “member-attr” must have a
distinguishedName syntax, because it is used to return the DNs of the members.
Creating a Dynamic Group
To create a dynamic group, add an entry to the directory that has an object class
as defined in the dynamic group configuration and an attribute as defined by the
“url-attr” in the dynamic group configuration.
The value of the “url-attr” in the dynamic group entry is an LDAP search which
has the following form:
ldap:///Base DN of Search??Scope?Filter
The Scope value is optional. It has three possible values:
■
■
■
sub—searches the entire subtree
base—searches the base DN only. This is the default, but it is the least useful
option.
one—searches the top level of the subtree only
The Filter value is also optional. The value is any LDAP search filter string. The
default value is OC present.
For example, to search for all people in the Finance department in either the
Payroll or Accounts groups:
ldap:///ou-finance,o=democorp,c=au??sub?
(|(organizationalUnitName=payroll)(organizationalUnitName=accounts))
3–41
Virtual Attributes
Viewing Dynamic Groups
The dynamic group configuration in use in a DSA can be viewed using the
console command:
get dynamic-groups;
This will produce a listing of each dynamic-group in use, with the group label at
the top. A sample configuration follows:
************** GROUP **************
Group object class : groupOfURLs
Group Search URL : memberURL
Member to Append : member
3–42
Virtual Attributes
Class of Service Templates
When directory information needs to be shared across multiple entries, the
shared information can be stored in a Class of Service (CoS) template.
Then, when a search returns an entry that contains a Class of Service attribute,
the attributes and values from the associated template are included in the entry.
This means that the information in CoS templates is only stored once, which is
good for three reasons:
■
Directory size is reduced
■
Simple bulk updates are faster
■
Information is consistent
The shared information is usually a level of service, such as a standard or
premium subscription to an internet service provider.
How Class of Service Templates Work
The virtual attributes and values are stored in templates, which are kept in a
DXserver configuration file.
When a search returns an entry that contains the CoS attribute, the attributes and
values from the associated template are presented.
A template can have multiple attributes and values. All attributes in a template
will be added to the entry.
If an entry already has an value for an attribute in a template, the attribute in the
template can either over-write the value, or the value can be left untouched. This
is controlled by the disposition of the template attribute. The two possible
dispositions are:
■
■
default—The value from the template replaces the existing value
override—If the entry already contains this attribute, the existing value will
persist. Use this when a customer requires special treatment.
The attributes that are stored in CoS templates are not searchable.
3–43
Virtual Attributes
Example: The Excellent ISP Company
The company Excellent ISP is an internet service provider. The customers of
Excellent ISP can subscribe for one of two classes of service:
Standard
Premium
Mail Storage
20 MB
30 MB
Web Space
20 MB
30 MB
Hours per Month
15 hr
Unlimited
Cost per Month
$19.95
$29.95
Cost of Extra Hours
$1.00/hr
$0.00/hr
The Excellent ISP customer directory includes the subscription information in
each customer entry.
Entries Without Class
of Service Virtual
Attributes
Before CoS is introduced, this information is stored in each entry. If there are
one million users, then these attributes appear one million times. If Excellent
ISP increases its fees, then a large global update is required.
Here is an example entry for an Excellent ISP customer who has the standard
class of service:
dn: cn=John Smith, o=Excellent ISP, c=US
oc: inetOrgPerson
oc: excellentISPuser
cn: John Smith
sn: Smith
excellentISPmailQuotaMB: 20
excellentISPwebSpaceMB: 20
excellentISPaccessHours: 15
excellentISPprice: 19.95
excellentISPextraHoursPrice: 1.00
excellentISPpackage: Standard
Here is an example entry for an Excellent ISP customer who has the premium
class of service:
dn: cn=Mary Chen, o=Excellent ISP, c=US
oc: inetOrgPerson
cn: Mary Chen
sn: Chen
excellentISPmailQuotaMB: 30
excellentISPwebSpaceMB: 30
excellentISPaccessHours: Unlimited
excellentISPprice: 29.95
excellentISPextraHoursPrice: 0
excellentISPpackage: Premium
3–44
Virtual Attributes
Entries With Class of
Service Virtual
Attributes
To save space and time, the shared information in these entries can be moved
into a template. The shared information in the entries is then replaced with a
new attribute, whose value indicates which CoS template to use.
The attributes from the CoS template will be added to the entry on a search.
dn: cn=John Smith, o=Excellent ISP, c=US
oc: inetOrgPerson
cn: John Smith
sn: Smith
excellentISPpackage: Standard
dn: cn=Mary Chen, o=Excellent ISP, c=US
oc: inetOrgPerson
cn: Mary Chen
sn: Chen
excellentISPpackage: Premium
Class of Service
Templates
The Excellent ISP company would need to use two templates. The standardlevel template would appear as follows:
set class-of-service standard = {
object class = excellentISPuser
cos-attr
= excellentISPpackage
cos-value
= "Standard"
attribute-values = {
(type
= excellentISPmailQuotaMB
value
= "20"
disposition = default),
(type
= excellentISPwebSpaceMB
value
= "20"
(type
= excellentISPaccessHours
value
= "15"
disposition = override),
(type
= excellentISPprice
value
= "19.95"
(type
= excellentISPextraHoursPrice
value
= "1.00"
disposition = default)
};
}
3–45
Virtual Attributes
The premium-level template would appear as follows:
set class-of-service premium = {
object class = excellentISPuser
cos-attr
= excellentISPpackage
cos-value
= "Premium"
attribute-values = {
(type
= excellentISPmailQuotaMB
value
= "30"
(type
= excellentISPwebSpaceMB
value
= "30"
(type
= excellentISPaccessHours
value
= "Unlimited"
disposition = override),
(type
= excellentISPprice
value
= "29.95"
};
}
(type
= excellentISPextraHoursPrice
value
= "0.00"
disposition = default)
Configuring Class of Service Virtual Attributes
When the shared attribute values change, they can be updated in the
configuration files. Therefore, make sure that configuration files are stored in a
source code control system to allow for rollbacks.
Distribution of CoS entries is achievable, but requires the DSA configuration to
be manually copied to all nodes.
Configure the DSA
Add the following line to the local DSA configuration to clear any currently
cached CoS information.
clear class-of-service;
This allows CoS attribute modifications to be made which can be included while
the DSA is still running using the command dxserver init.
Make sure that the template configuration file is sourced after the schema is
sourced. The template uses attributes that are defined in the schema
configuration.
Add CoS Attributes to
Entries
3–46
To use CoS templates with an entry, add the cos-attr attribute to the entry.
Virtual Attributes
Create Class of
Service Templates
Templates can be stored in any directory. However, if there are many
templates, you should store them in separate files in the
DXHOME/config/settings directory.
The Class of Service templates use the following syntax:
<cosTemplate>
::= set class-of-service <cosLabel> = { <operCos> };
<cosLabel>
::= <string>
<operCos>
::= object-class = <attrOid> cos-attr = <attrOid> cos-value =
<value> attribute-values = { <cosTemplateList> }
<cosTemplateList> ::= <cosTemplate> | <cosTemplate>, <cosTemplateList>
<cosTemplate>
::= ( type = <attrOid> value = <cosValueList> disposition =
<cosDisposition> )
<cosValueList>
::= value | value, <cosValueList>
<cosDisposition> ::= default | override
Note: The cos-attr used in a Class of Service template must be a single-valued
attribute.
Viewing Class of Service Templates
The templates in use in a DSA can be viewed using the console command:
get class-of-service;
This will produce a listing of each class of service template in use, with the
template label at the top. For example, the template for the standard class of
service at the company Excellent ISP discussed in the example above would
appear like this:
************** standard **************
class-of-service =
target object class : excellentISPUser
target attribute
: excellentISPPackage
target value
: "Standard"
attribute list =
attribute
: excellentISPmailQuotaMB
value/s
: "20"
disposition : default
attribute
: excellentISPwebSpaceMB
value/s
: "20"
attribute
: excellentISPaccessHours
value/s
: "15"
disposition : override
attribute
: excellentISPprice
value/s
: "19.95"
attribute
: excellentISPextraHoursPrice
value/s
: "1.00"
3–47
Knowledge Flags
Knowledge Flags
This section describes how to use knowledge flags to define the configuration,
security, and interoperability of DSAs. This section also includes tables that list
all of the possible knowledge flags.
For information about how knowledge files work, see Knowledge Files in the
chapter DXserver Overview.
The Three Kinds of Knowledge Flags
The DXserver uses three sets of flags to define the configuration, security, and
interoperability of DSAs:
DSA Flags
DSA flags define which operations that can be performed on the local DSA.
These flags can be used by the local DSA to determine which operations it
can process. They can also be used by remote DSAs to determine which
operation the local DSA will process..
Trust Flags
Trust flags define how a DSA works with a remote DSA. Trust flags only
affect how a remote DSA works.
Link Flags
Link flags define any special conditions for linking to the remote DSA,
including the protocol, encryption level, and any interoperability
requirements for specific applications.
Example: Flags in a Knowledge File
The following example knowledge file includes all three types of flags:
set dsa democorp =
{
...
dsa-flags
= multi-write, shadow, load-share, no-routing-ac, limit-search,
limit-list
trust-flags
= allow-check-password, trust-conveyed-originator, allowupgrading, allow-downgrading, no-server-credentials
link-flags
= dsp-ldap, ssl-encryption-remote, ms-ad
};
The DSA flags will be used by the Democorp DSA when a client or another
DSA attempts to run an operation on it. Also, other (remote) DSAs can use the
DSA flags to check which operations can be sent to the Democorp DSA.
The trust flags will be used by remote DSAs to check how much they should
trust the Democorp DSA.
The link flags will be used by remote DSAs to define how they should link to the
Democorp DSA.
3–48
Knowledge Flags
Example: How the limit-search DSA Flag Works
DSA flags are used by a DSA to define how it responds to operations that other
DSAs or clients attempt to perform on it.
The following example shows how the limit-search DSA flag works:
1.
The UNSPSC receives an unfiltered search request from a client.
The UNSPSC DSA cannot fulfill the search request, but it knows that the
Company A DSA can.
2.
The UNSPSC DSA checks the Company A knowledge file to see whether
there are any conditions for searching the Company A DSA.
The flag limit-search indicates that the Company A DSA will reject any
unfiltered or complex searches.
3.
The UNSPSC DSA returns a Search Refused response to the client.
set dsa
companya = {
dsa-flags =
limit-search
2. Check Company A
DSA flags
};
companya.dxc
Client
Application
(JXplorer)
1. Search request
o=”Company A”
UNSPSC DSA
Company A
DSA
3. Search response
Using DSA flags to define how a DSA responds to requests
For information about particular DSA flags, see List of all DSA Flags in this
chapter.
3–49
Knowledge Flags
Example: How the allow-check-password Trust Flag Works
Remote DSAs use trust flags to define how much they should trust a DSA.
By default, security is tight. The trust flags provide a mechanism to selectively
relax security between DSAs.
The following example shows how a DSA uses the trust flag allow-checkpassword:
1.
The UNSPSC DSA receives a bind request from a user whose credentials are
stored in the Democorp DSA. The UNSPSC DSA cannot check the user’s
credentials, but it knows that the Democorp DSA can.
2.
The UNSPSC DSA checks the Democorp knowledge file to see whether it can
trust the Democorp DSA to authenticate a user. The flag allow-check-password
indicates that this is permissible.
3.
The UNSPSC DSA requests the Democorp DSA to authenticate the user.
4.
The Democorp DSA responds with the user’s authentication.
5.
The UNSPSC DSA returns the bind confirmation to the client.
set dsa
democorp = {
trust-flags =
allow-checkpassword
2. Check Democorp
trust flags
dn=<c=au><o=democorp>
<cn=”Bob Smith”
};
democorp.dxc
Client
Application
(JXplorer)
1. Bind request
3. Authentication request
UNSPSC DSA
5. Bind response
Democorp
DSA
4. Authentication response
Using Trust Flags to Trust Another DSA to Authenticate a User
For information about particular trust flags, see List of all Trust Flags in this
chapter.
3–50
Knowledge Flags
Example: How the dsp-ldap Link Flag Works
Remote DSAs use link flags to define any special conditions for a link to another
DSA.
The following example shows how the dsp-ldap flag works.
1.
The UNSPSC DSA receives a request to search the remote DSA named
Company A, which happens to be an LDAP server.
2.
The UNSPSC DSA checks the Company A knowledge file to see whether
there are any special conditions for linking to that DSA. The flag dsp-ldap
indicates that the Company A DSA requires that any links use LDAP.
3.
The UNSPSC DSA uses DXlink to make an LDAP search request of the
Company A DSA.
4.
The Company A DSA responds with the search result (also using LDAP).
5.
The UNSPSC DSA returns the search result to the client.
set dsa
companya = {
link-flags =
dsp-ldap
2. Check Company A
link flags
};
companya.dxc
Client
Application
(JXplorer)
1. Search request
o=”Company A”
3. Search request (LDAP)
UNSPSC DSA
5. Search response
Company A
LDAP server
4. Search response (LDAP)
Using Link Flags to Define the Nature of a Link Between DSAs
For information about particular link flags, see List of all Link Flags in this
chapter.
3–51
Knowledge Flags
List of all DSA Flags
The following table lists and describes all of the available DSA flags:
DSA Flag
Description
limit-list
Disables the list operation on the DSA.
For more information, see Query Streaming in the chapter Distribution and
DSP, and Limit List in this chapter.
limit-search
Restricts complex searches or searches with no filter on the DSA.
For more information, see Query Streaming in the chapter Distribution and
DSP, and Limit Search in this chapter.
load-share
Marks a DSA as part of a load share group. The DSA should have other peer
DSAs with the same prefix, which are also marked as load-share. A router DSA
shares operations over each DSA in the load share group.
See the section Load Sharing DSAs in the chapter Distribution and DSP.
ms-ad
Active Directory - The DSA is treated as a Microsoft Active Directory server. Set
this flag if you observe any problems with linking to Active Directory.
See also Connecting to Active Directory in Chapter 11 of the User Guide.
multi-write
Marks a DSA as part of a multiwrite group. The DSA should have other peer
DSAs, with the same prefix, which are also marked as multiwrite. Updates are
automatically propagated to all peer DSAs marked as multiwrite.
See the chapter Replication for more information.
multi-write-async
Makes the DSA update asynchronously, even though it is in a multiwrite group.
See Asynchronous Multiwrite Behavior in the Replication chapter.
multi-write-disp-queue Allows multiwrite queues while DISP is in progress. Multiwrite DISP recovery
cannot be used where more than one DSA is attached to the same database.
See Multiwrite Recovery With DISP in the Replication chapter.
multi-write-notify
Sends multiwrite updates to DXcache.
no-routing-ac
Permits forwarding of a request to another DSA regardless of access control
constraints.
See Access-Controlled Routing in the chapter Security for more information.
read-only
Disables update operations on the DSA.
See also Query Streaming in the chapter Distribution and DSP.
relay
Permits a router DSA to exist without consuming a level of the DIT.
See Configuring a Relay DSA in the chapter Distribution and DSP.
shadow
Permits a DSA to be updated by DISP or multiwrite, but prevents any other
updates (for example, through DAP or LDAP) from occurring.
See the chapter Replication.
3–52
Knowledge Flags
List of all Trust Flags
The following table lists and describes all of the available trust flags:
Trust Flag
Description
allow-check-password
Permits a DSA, while processing a bind request from a user who is not local, to
pass a name and password-compare request to this DSA. The result of the
compare request is then used to authenticate the user.
See Distributed User Authentication in the chapter Security for more
information.
trust-conveyed-originator Signifies that a DSA treats the originator and authentication level passed in DSP
chaining arguments as if that user and authentication level were authenticated
locally.
See Distributed User Authentication in the chapter Security for more
information.
allow-upgrading
Lets the DSA pass an anonymous user request across an authenticated DSP link.
See Authentication in the chapter Security for more information.
allow-downgrading
Lets the DSA pass an authenticated user request across an anonymous DSP link.
See Authentication in the chapter Security for more information.
no-server-credentials
Removes the requirement for mutual authentication and permits a link to be set
up if the remote DSA does not send credentials in the bind response.
See User Credentials on the DXlink Binds in the chapter LDAP and DXlink for
more information.
3–53
Knowledge Flags
List of all Link Flags
The following table lists and describes all of the available link flags:
Link Flag
Description
dsp-ldap
The DSA is treated as an LDAP server that supports LDAP 3.0. Other DSAs will
send requests to the DSA using DXlink.
When dsp-ldap is configured, there will be no COMPARE operation on the
userPassword attribute, following a bind over DXlink. If the same user connects
more than once, that user will use the same link, and dxserver will check that
the user and the password are the same.
See Integrating Other LDAP Servers in the chapter LDAP and DXlink for more
information.
dsp-ldap-proxy
Causes the last DSA in the chain to use the authorization of the originating user
to perform operations on the LDAP server.
See Automatically Authorizing LDAP Operations in the chapter LDAP and
DXlink for more information.
dsp-ldapv2
The DSA is treated as an LDAP server that supports LDAP 2.0. Other DSAs will
send requests to the DSA using DXlink.
information.
ms-ad
The DSA is treated as an Active Directory service. If you observe any problems
with linking to Active Directory, set this flag. See Connecting to Active
Directory in the chapter “Connecting to Other Applications and LDAP” in the
User Guide for more information.
ms-exchange
The DSA is treated as a Microsoft Exchange server to overcome limitations in
Exchange’s version of LDAP.
information.
ssl-encryption
Any DSA DSA-to to-DSA communication to the DSA with this link flag will be
made using SSL encryption.
See DSA-to-DSA Encryption (DSP and DISP) in the chapter Security for more
information.
ssl-encryption-remote
It is similar to ssl-encryption, but SSL encryption is not used if the target
DXserver is on the same host.
unavailable
Marks a DSA as unavailable. A DSA will not forward requests to a DSA marked
as unavailable.
3–54
Chapter
4
Schema Definition
The directory schema is a set of configurable rules that a DSA enforces on the
data created within the directory. These rules define:
■
The names of the various types of attributes that can exist in an entry
■
The syntax (or data type) of each of these attributes
■
■
■
Which attributes in each object class (a defined group of attributes) are
mandatory and which are optional
How each directory entry is named (for example, a person is named by his or
her common-name attribute)
Where the directory entry can be created in the DIT (for example, an
OrganizationalUnit entry can only exist under an Organization entry)
eTrust Directory provides a full directory schema definition starter kit, including:
■
OSI (X.500, X.400, X.435 [EDI] )
■
Internet (LDAP, Inet, Cosine, Quipu, Thorn)
■
Industry (JNDI, DADF, Mosaic, UNSPSC)
■
Organizations (DMS, Umich, Entrust, RSA, Netscape)
This chapter includes information about schema files, attribute definitions,
schema prefixes, object class definitions, and name bindings. Name bindings are
an implementation of the X.500 DIT Structure Rules.
The schema of a running directory is available to LDAP clients via the LDAP
Version 3 mechanism of schema publishing. See Schema Publishing in the
chapter LDAP and DXlink for more information.
Schema Definition
4–1
Configuring Schema
Configuring Schema
DXserver checks and validates schema rules on every update operation to
maintain directory integrity.
All aspects of X.500 schema are fully configurable, down to the attribute syntaxes
(basic directory information types) compiled in the entry.
You should create the schema within configuration files (that is, in the
DXHOME/config/schema directory) rather than dynamically using the console
interface, as the latter will only remain in effect while that DSA is running.
Important! The DXtools require a separate schema file, schema.txt. If you add or change
the schema definition for DXserver, you must also update schema.txt for the tools. For
information about how to update schema.txt, see SCHEMA Tools in the chapter "Using
DXtools."
Grouping Schema
You usually define schema in a single definition file. All schema definition files
reside in the schema configuration directory. When building your directory
schema, you typically need definitions from several schema definition files. You
can group these schema definition files together in a single file using the source
command. The following is an example schema.dxg file:
# Schema definition file – schema.dxg
source “x500.dxc”;
source “cosine.dxc”;
source “mhs.dxc”;
source “quipu.dxc”;
The DXserver initialization (for instance, democorp.dxi) file sources this schema
definition.
# DSA initialization file – democorp.dxi
...
# SCHEMA
source “../schema/schema.dxg”;
...
4–2
Configuring Schema
Managing Schema
There are a number of parameters to the schema module set commands that let
you change the schema configuration. You can view them by the schema module
get command. The following tables summarize these commands and the
following sections explain them in more detail.
You can manage and monitor schema configuration using the commands:
■
■
get schema for parameter;
Schema Commands
The following are the parameters for the set schema command:
Parameter
Value
oid-prefix
Defines an object identifier (OID) prefix. An OID prefix consists of a name used
to represent the portion of the object identifier common to multiple schema
definition statements.
attribute
Defines an attribute. An attribute consists of an attribute name, alternate name,
syntax, single-valued flag, and a description.
attr-set
Defines an attribute set. An attribute set consists of an attribute set name and a
list of previously defined attributes or attribute sets.
object-class
Defines an object class. An object class consists of an object class name, an
alternate name, a subclass definition, an object class kind, a must-contain list of
previously defined attributes or attribute sets, a may-contain list of previously
defined attributes or attribute sets, and a description.
name binding
Defines a name binding between two previously defined object classes. A name
binding consists of a name for the name binding, an object and its allowable
parent, and an attribute that names the object.
The following is the parameter of the get schema command:
Parameter
Value
for
Item; a name or an object identifier of any schema definition (an attribute, object
class, name binding, prefix, or attribute set).
Schema Definition
4–3
Configuring Schema
Viewing Schema
Example: Viewing
Schema Definition
To retrieve the definition of commonName, use the command:
get schema for commonName; or
get schema for (2.5.4.3);
An example output of this command is:
Attribute (2.5.4.3)
name = commonName
ldap-names = cn
syntax = caseIgnoreString
You can use the name, ldap-names, or object identifier with this command.
Schema Prefixes
All attribute, attribute set, object class, and name binding definitions have a
unique object identifier (for example, 2.5.4.6) that uniquely identifies that object.
When defining a schema, you can find many definitions on the same branch of
the schema definition tree. You can define a schema prefix that replaces the
branch of the tree in all subsequent definitions.
Example: Schema
Prefix Definition
set
set
set
set
oid-prefix
oid-prefix
oid-prefix
oid-prefix
x500attr =
x500oc
=
x500aset =
x500nbind =
(2.5.4);
(2.5.6);
(2.5.7);
(2.5.15);
set attribute x500attr:3 = {
name = commonName
ldap-names = cn
syntax = caseIgnoreString };
Given the previous definition, the prefix x500attr can replace any occurrence of
the 2.5.4 portion of an object identifier. Thus, an attribute with the object
identifier of 2.5.4.6 can also be represented as x500attr:6.
Without schema prefixes, the previous definition would read:
set attribute (2.5.4.3) = {
name = commonName
ldap-names = cn
syntax = caseIgnoreString ;
Schema prefixes improve readability and reduce the chance of errors in the
definition, especially when the object identifiers are long. For example, the object
identifiers of each of the Quipu attributes are of the form
0.9.2342.19200300.99.1.x, making a prefix desirable.
4–4
Attributes
Attributes
An attribute is the foundation of directory information. It consists of a type, for
example, commonName, and one or more values, for example, Rick, Richard.
You define an attribute in the configuration file with information about its object
identifier (OID), name, LDAP names, syntax, whether it is single-valued,
whether its value can be modified, and a description.
You can define more than one LDAP name for each attribute. The LDAP name
defaults to the attribute name, so typically you only need to define the LDAP
name when it is different from the attribute name.
There is no limit to the number of attributes or rules that you can define for a
DSA or on the size of the attributes you can store in the DSA.
Example: Attribute
Definition
Example: Read-Only
Attribute Definition
set attribute x500attr:3 = {
name
= commonName
ldap-names = cn
syntax
= caseIgnoreString
description = "Common Name attribute"
};
schema set attribute (2.5.18.1) = {
name = createTimestamp
syntax = generalizedTime
no-user-modification
};
Schema Definition
4–5
Attributes
Attribute Syntaxes
Attribute syntaxes define the format of basic information types. All attribute
syntaxes defined in X.520 are supported:
■
audio
■
generalizedTime
■
octetString
■
binary
■
fax
■
postalAddress
■
boolean
■
guide
■
preferredDelivery
■
caseExactString
■
integer
■
presentationAddress
■
caseExactStringIA5
■
jpeg
■
printableString
■
caseIgnoreIA5String
■
mhsORAddress
■
telephoneNumber
■
caseIgnoreList
■
mhsORName
■
teletexTerminalId
■
caseIgnoreString
■
numericString
■
telexNumber
■
distinguishedName
■
objectIdentifier
■
UTCTime
■
facsimileNumber
As more applications become directory-enabled, you can define new attribute
syntaxes.
To support these new syntaxes, particularly with their search matching rules,
you may need special syntax coding and decoding functions. Generally this
requires a software update to the DSA and DUA processes. However, to more
readily support new attribute syntaxes on demand in operational systems, the
DXserver has a feature for using unknown syntaxes.
The undefined attribute syntax lets the DXserver DSA accept any unknown
attribute syntaxes and store them in the directory. Intelligent matching rules are
applied so you can search for them.
Tip: See the configuration files (.dxc) in the schema directory for the latest
supported syntaxes.
To ensure DIT data integrity over configuration changes, the DSA stores the
names of its current attributes and attribute syntaxes securely within the
directory. The list names the ones that have been used to create directory entries.
This list is not the same as that of all possible attribute names and syntaxes.
When you attempt to change the syntax of an attribute after an instance of that
attribute exists, the following message occurs:
** ALARM **: Database attribute attribute has different syntax than schema
4–6
Attributes
Attribute Checking
When you load attributes (by using set attribute), they inherit certain rules from
their syntax (for example, caseIgnoreString). When attempting to add attributes
with values that do not comply with these rules, they are considered invalid.
When the DSA encounters an invalid attribute (for example, on updates), it
returns an error containing the attribute and the associated problem.
Tip: In the search service, the system ignores invalid attributes after the base
object is found.
The DSA always returns attributes exactly as you stored them. For example, a
commonName stored as JohN citiZen matches John Citizen and JOHN CITIZEN
but the value JohN citiZen is always returned. Similarly, when you received the
original string as an IA5 string, you store it as an IA5 string even though it
contains only printable characters.
The DSA permits attributes of any size, so you do not have to define any
attribute bound limits.
Syntax Aliases for Unsupported Attribute Syntax
Syntax aliasing is useful if you add a new schema object definition that uses an
attribute syntax that is not supported by eTrust Directory. The command for
setting up a syntax alias is:
[ schema ] set syntax alias <oid> = { name = <string> alias-for = <string> };
For example,
set syntax-alias (1.3.6.1.4.1.1466.115.121.1.18) = {
name = dlSubmitPermissions
alias-for = caseIgnoreString
};
Schema Definition
4–7
Attributes
Attribute Sets
Attribute sets let you easily group attribute definitions under a label so you can
use them later in object class and other definitions.
Define attribute sets in the configuration file using the set attr-set command. The
attribute set is given an object identifier and a definition. The definition consists
of a name and a list of attributes or attribute sets that are contained in the
attribute set being defined.
Example: Attribute Set
Definition
set attr-set x500aset:3 = {
name = organizationalAttributeSet
description,
localeAttributeSet,
postalAttributeSet,
telecommunicationAttributeSet,
businessCategory,
seeAlso,
searchGuide,
userPassword
};
Attribute sets are a convenient way of grouping large numbers of attributes
together for use in object class definitions. Attribute sets can contain other
previously defined attribute sets.
Attribute Names
A schema defines the basic information types and rules in a directory, so a
schema is a central part of most directory services.
When defining a schema, you must supply a name. You can also supply a
number of LDAP names in the definition. Use either the schema name or one of
the LDAP names as a keyword in other management console commands.
For example, when you define an attribute using the following command, you
can use organizationName or the shorter LDAP name, o, in other commands that
need to reference the attribute:
set attribute (2.5.4.10) = {
name
= organizationName
ldap-names = o
syntax
= caseIgnoreString
};
LDAP names are most convenient when defining Distinguished Names (DN).
The following DN:
<c AU><o “Computer Associates”><ou Sales><cn "Jim Smith">
is equivalent to:
<countryName "AU">
<organizationName "Computer Associates">
<organizationalUnitName "Sales">
<commonName "Jim Smith">
4–8
Attributes
Unique Attributes
Some applications that use eTrust Directory as a repository may require that the
value of some attributes are unique across the repository. Information such as
user name, user ID, or key may need to be unique for correct operation of a
service. For example, an e-mail service will not operate effectively if a user
chooses an ID that is already in existence.
The benefits of this change will be to push uniqueness checking from the
application to the directory. This removes the potential for attributes existing
with duplicate values.
Distribution and Replication
Unique attributes cannot be used in a distributed environment, because there is
no way of ensuring that attribute values across multiple DSAs are not being
updated concurrently.
This means that the attribute value check will only apply to the local DSA. Make
sure that the DSA design does not assume that the attribute value check will be
performed across multiple DSAs.
In a replicated environment, unique attributes can be used in a single master
scenario only. This is also because of the issue of concurrent updates.
Unique Attribute Flag
Set the unique attributes using the DSA set command:
set unique-attrs = attr1, attr2, …;
To see a list of all of the unique attributes in a DSA, use the DSA console to issue
a get oper command.
Implementing Unique Attributes
Before you implement unique attributes:
■
■
Choose the attributes carefully.
Make sure you understand how client applications handle problems when
trying to add or modify attribute values that already exist.
During operation, take care to not inadvertently switch off this feature if it is still
required.
Schema Definition
4–9
Attributes
How Unique Attributes Work
When a client application tries to update an attribute that is set to be unique,
eTrust Directory checks that the attribute value is not already in existence. If the
value does already exist, an error message is sent back to the client application. If
the value does not yet exist, the client request is confirmed.
Limitation: Access Controls Bypassed
If these attributes have access controls imposed, the triggered search will bypass
these to ensure uniqueness. This means that a user may be able to write a client
application to determine these values. If the unique attributes contain sensitive
information, then this may be an issue.
Limitation: Uniqueness Cannot Be Restricted to a Sub-Tree
If attribute value uniqueness is required, but only need to be unique for a
particular sub-tree, then separate DSAs will be required.
Limitation: Uniqueness Not Enforced In Pre-Existing Data
We recommend that this feature be enabled on empty directories or new
attributes. This will ensure uniqueness.
There is no DSA mechanism for finding duplicates. If this feature is being
enabled on a running system, the administrator should perform checks for
duplicate attribute values.
Uniqueness will not be enforced on back-end loads. This has a similar impact as
turning on this feature with an existing set of data.
The following example shell script shows how to find duplicates. This script is
restricted to values to length 106.
#!/bin/sh
if [ $# -ne 2 ]; then
echo "Usage: sql.sh database attribute"
exit 1
fi
DATABASE=$1
ATTRIBUTE=$2
OUTPUT=`sql $DATABASE <<EOF
SELECT aid
FROM
attr
WHERE description = '$ATTRIBUTE';\g
\q
EOF`
4–10
Attributes
# Process output to get Aid
AID=ècho "$OUTPUT" | grep -v aid | awk -F'|' '{ print $2 }'`
sql $DATABASE <<EOF >/dev/null 2>&1
CREATE VIEW findDuplicates(aid, norm, count) AS
SELECT aid, norm, count(norm)
FROM
search
WHERE aid = $AID
GROUP BY aid, norm;\g
\q
EOF
sql $DATABASE <<EOF | tr -d " " | grep $ATTRIBUTE | awk -F'|' '{ print $2 " = "
$3 ", occurrences = " $4 }'
SELECT a.description, f.norm, f.count
FROM
findDuplicates f,
attr a
WHERE f.aid = a.aid;\g
\q
EOF
sql $DATABASE <<EOF >/dev/null 2>&1
DROP findDuplicates;\g
\q
EOF
Schema Definition
4–11
Attributes
Changing the Schema Definition for Attributes in Use
Important! Never change database tables manually unless CA Technical Serves direct
you to do this.
If an attribute, object class or name binding has never been used in the directory,
then you can change or remove the schema definition by modifying the schema
configuration file.
If the attribute has been used before, but is no longer in use, then you should
dump the database to LDIF and then reload it before you modify the schema.
If an attribute has at any time been used within the directory, you can only
change its schema definition using these instructions.
Important! You cannot simply delete all the entries that have the attributes to be
changed, change schema, and import back the data.
Important! A single schema file may be used by many different DSAs, which may use
many different databases. If you change a schema file, check that it will work correctly
with all of the DSAs that use that file.
Remember to regenerate the schema.txt file for the DAP tools after changing the
DXserver schema configuration.
Changing LDAP Attribute Names
If an attribute is in use, but you wish to change its name for clients connecting to
the directory via LDAP, then simply alter the "ldap-names" part of the schema
definition.
Changing Schema Definitions for Attributes in Use
If an attribute has at any time been used within the directory, you cannot simply
delete all the entries that have the attributes you want to change, change the
schema, and import back the data. This will not work.
Instead, you must reload the database with DXloaddb to remove the old schema
definitions from the database.
To change the schema definition for attributes in use, do the following to every
databases and DXservers that uses the schema definition to be changed:
4–12
1.
Stop all related DSAs.
2.
Back up the system (data and configuration).
Attributes
3.
Dump the database to to an LDIF file:
dxdumpdb olddbname
4.
Sort the LDIF file. To do this, use the following command:
ldifsort old.ldif old_sorted.ldif
5.
Change the schema definitions .
6.
Load the database from the sorted LDIF file with DXloaddb
7.
Start all the DXservers
8.
Verify the changes
This can be done without taking the eTrust Directory service offline by using the
database hot-swap feature:
1.
Turn off DXcache.
2.
Mark the DSA as read-only. To do this, add the following DSA flag to the
configuration file:
3.
Dump the database to to an LDIF file:
dxdumpdb olddbname
4.
Sort the LDIF file to ensure that it will load successfully. To do this, use the
following command:
5.
Change the attribute syntax in the schema configuration
dxnewdb newdbname
6.
Change the database name in the DSA configuration
dxloaddb newdbname
7.
Initialize the DSA.
dxserver init dsa-name
If you do not change the DSA configuration before running DXloaddb, then
DXloaddb will use the schema.txt file which does not have the changed attribute
definitions.
Schema Definition
4–13
Object Classes
Object Classes
Object classes specify which attributes (and attribute sets) you can have in an
entry.
You define an object class by specifying its object identifier, a name, an alternate
name, a subclass, an object class kind, a list of must-contain and a list of maycontain attributes or attribute sets, and a description.
Example: Object Class
Definition
set object-class x500oc:5 = {
name = organizationalUnit
subclass-of top
kind = structural
must-contain
organizationalUnitName
may-contain
organizationalAttributeSet
description = "X.500 Organizational Unit Object Class"
};
The organizationalAttributeSet referred to in this example was defined in
Schema Example 3—Attribute Definition.
Object Class Kind
Within the X.500/LDAP standards, there are three kinds of object classes:
■
Abstract classes (for example, the object class top)
■
Structural classes (for example, the object class inetOrgPerson)
■
Auxiliary classes
The kind keyword defines the type of object class. The kind keyword is optional,
but if it is missing, DXserver derives the object class kind using the following
rule: when the object class inherits top, it is assumed to be structural; otherwise, it
is auxiliary.
Abstract Classes
The abstract object class determines the structure of an LDAP directory. The
object class top, for example, is the root object class from which all structural
object classes are derived. It contains one mandatory attribute, objectClass, and
because all entries inherit its attributes, it ensures that an object class defines
these entries. An abstract object class cannot stand alone in an entry. The entry
must also contain a structural object class.
4–14
Object Classes
Structural Classes
Most of the object classes in a directory are structural, because they define what
an entry is. They also impose rules on the entries that are stored beneath them.
For example, the object class organization (o) may require that all objects stored
beneath it belong to the object class organizationalUnit (ou). Other examples of
structural object classes are groupOfNames, inetOrgPerson, and person.
Auxiliary Classes
The LDAP rules require each entry to belong to only one structural object class,
but an entry can also belong to one or more auxiliary object classes. An auxiliary
object class adds attributes to entries already defined by a structural object class.
An auxiliary object class cannot stand on its own in an entry. The entry must
contain a structural object class. Unlike structural object classes, auxiliary object
classes place no restrictions on storing an entry.
Object Class Checking
When adding an entry, the DSA automatically includes all the attributes from
any superclasses of the new entry's object class. For example, when an entry is
created with the object class inetOrgPerson, it includes attributes from the
inherited object classes (organizationalPerson, Person, top).
Important! DXserver supports multiple inheritance of object class. This means that an
object class can inherit attributes from more than one parent object class.
Schema Definition
4–15
Object Classes
Object Class Storage
By definition, the object class attribute used by every object or entry in the
directory can have multiple values of object identifiers. This enables object
classes to indicate their refinement (for example, through the use of object class
refinement or the addition of auxiliary object classes).
Configuring how the OC Attribute is Stored
You can configure how the object class attribute (single value or multiple values)
is stored within the directory.
By default, the DSA adds the object classes to the entry exactly as specified in the
LDAP or DAP add request (for example, the object class attribute may have
multiple OIDs). However, directory performance improves slightly when the
object class attribute only contains a single value (the OID of the refined OC).
However, this should not be the main influence over the object class design of
attributes.
Where entries contain a single inherited object class and explicitly list all its
superiors (their OC OIDs), the superiors can be removed, leaving the lowestlevel object class in the hierarchy as a single OID value. Similarly, when entries
are returned, the object class attribute can be automatically modified by the DSA
to contain all the superior object classes.
This OC refinement information can be returned (as OC OIDs) because the
directory maintains the object class structure rules that have been configured (in
its internal schema management control system).
For example, suppose that the directory contained entries corresponding to
people. Each entry can explicitly contain the following object classes within the
database:
4–16
■
inetOrgPerson
■
organizationalPerson
■
Person
■
top
Object Classes
Pruning and Replacing Object Classes
It is more space-efficient to configure the DSA to prune all object classes, except
the lowest (inetOrgPerson), when creating the entry and to replace all the
superior object classes (organizationalPerson, Person, and top) when returning
the entry as a result of a client search.
The following configuration settings control the pruning and replacing of object
classes:
Setting
set prune-oc-parents
Boolean
Removes redundant superior object classes
when new entries are created.
set return-oc-parents
Boolean
Replaces the superior object classes to
entries retrieved when searching.
set add-oc-parents
Boolean
Causes parent objectclasses to be added
when entries are added. e.g. Consider
adding a democorp entry with the classes:
inetOrgPerson
This control adds the parent (top-personorganizationalPerson) classes. This makes
the directory entry hold the following
classes:
■
top
■
person
■
organizationalPerson
■
inetOrgPerson
Important! When these settings are configured, searching entries using an object class
filter (for example, oc=Person) does not return any entries, because the specified object
class of Person is not present in the data; it is only added to search results that contain
the inetOrgPerson object class.
Schema Definition
4–17
Name Bindings
Name Bindings
Name bindings define where entries appear in the DIT. DXserver requires a
separate name binding for each allowable parent-object and child-object
relationship in the directory.
Example: Name
Binding Definitions
set name-binding x500nbind:2 = {
name = org-top
organization allowable-parent top
named-by organizationName
};
name = org-country
organization allowable-parent country
named-by organizationName
};
In this example, a new definition (arbitrarily named org-country) states that you
can place an organization object under a country object and that you must name
it by the organizationName attribute. The definition org-top states that you can
also place an organization object under a top object (that is, the root of the DIT)
named by the organizationName attribute.
Multiple attributes can name an object, in which case you separate the attributes
by commas. Additional naming attributes are optional when the keyword
optional precedes them.
Example: Advanced
Name Binding
Definition
name = orgUnit-orgPerson
organization allowable-parent organizationalUnit
named-by commonName optional surname
};
Name Binding Checks
The DSA checks name binding rules whenever you add or rename an entry. To
enforce both the parent-child relationships in the directory, and the naming
attributes used by a particular entry, name bindings are necessary. The system
reports any name binding errors as:
Update Error: Naming Violation.
When you enable warnings (set trace = warn,…;), the system sends a message
describing the reason for the name binding failure to the console.
There is one exception regarding name binding checks. When an object is added
under the naming context (or prefix) of a DXserver, then no name bindings need
exist. This facilitates the changing of the directory’s naming context without the
need to change associated name binding definitions. In this situation, DXserver
will give the following message:
Relaxed name bindings under root.
4–18
Name Bindings
Name Bindings and Structural Object Classes
When an entry has more than one object class, the DSA looks through its list of
name bindings to ensure that one exists between one of the structural object
classes of the parent and one of the structural object classes of the entry
containing the appropriate naming attribute. It then uses this structural object
class to find a name binding and ignores all other auxiliary object classes.
The DSA permits modification of the structural object class only when a name
binding satisfies the parent-object relationship and the object is a leaf entry.
Name Bindings and Aliases
Name bindings for aliases are automatic, and you do not configure them
manually. The DSA lets you create an alias entry in place of any valid object
provided that you name it using the same attribute that an equivalent name
binding rule permits.
For example, when there is an org-orgUnit name binding, the DSA lets you place
an alias under an organization object when you name it using an
organizationalUnitName attribute.
Thus, you do not need to define an object-alias name binding for every part of
the DIT where you can place an alias.
Considerations for Schemas that Do Not Support Name Binding
When a schema is imported from a directory that does not support name
bindings or structure rules, it is possible for eTrust Directory to operate without
name bindings. To enable this functionality, add the following command to the
settings file:
set ignore-name-bindings = true;
You can retrieve the state of this flag by using the get oper; command.
Schema Definition
4–19
Defining Local Schema
Defining Local Schema
The X.500 standards enable the definition of local attributes, attribute sets, object
classes, and name bindings in the schema in much the same way as previously
described in Name Bindings and Aliases in this chapter.
Before defining local schema, you should check the existing published schema to
determine whether the required attribute, object class, and name binding
definitions already exist.
When you need to define additional schema, create an object identifier arc
(1.3.6.1.4.1.3327.1 in the following example) and add the new schema under this
arc. Use the set commands described previously to define the schema, and then
include the newly created configuration file (.dxc) in the schema group
configuration file (.dxg), used by the DSA.
The following example describes a single object class that can contain three
attributes. Computer Associates created the object class so that you could add the
additional attributes to an organizationalPerson object.
All the names in the schema definition below have the prefix ca. The use of an
object identifier prefix in the name helps simplify attribute references by
replacing the common portion of a complicated object identifier with a simple
character string and helps identify related attributes.
Example: Local
Attribute, Attribute
Set, Object Class, and
Name Binding
Definitions
set
set
set
set
set
set
set
set
set
set
4–20
oid-prefix caAttr
= (1.3.6.1.4.1.3327.1.4);
oid-prefix caOclass = (1.3.6.1.4.1.3327.1.6);
oid-prefix caAset
= (1.3.6.1.4.1.3327.1.7);
oid-prefix caNbind = (1.3.6.1.4.1.3327.1.14);
attribute caAttr:0 = {
name = caNearestPrinter
description = "Local Printer Attribute" };
name = caMobilePhone
description = "Mobile Phone Attribute" };
name = caAlternateContact
description = "Local Contact Attribute" };
attr-set caAset:0 = {
name = caAttributeSet
caNearestPrinter,
caMobilePhone,
caAlternateContact };
object-class caOclass:0 = {
name = caOrgPerson
subclass-of organizationalPerson
kind = structural
may-contain caAttributeSet
description = "CA Organizational Person Object Class"
name-binding caNbind:0 = {
name = caOrgPerson-org
caOrgPerson allowable-parent organization
named-by commonName };
};
Chapter
5
Distribution and DSP
In a distributed environment, a number of different Directory System Agents
(DSAs) manage a different part of the Directory Information Tree (DIT).
There needs to be a DSA-to-DSA protocol, such as the X.500 Directory Systems
Protocol (DSP), that lets the DSAs cooperate to resolve queries on any area of the
DIT.
DXserver fully supports the X.500 directory systems protocol, including:
■
Chaining—Performing queries through other DSAs
■
Multi-chaining—Performing distributed searches across many DSAs
■
Referrals—Informing clients where to find information
DXserver greatly simplifies the configuration of arbitrarily distributed DSAs by
providing the following unique features:
■
■
Prefix-based knowledge—Each DSA is identified by a name and its base
prefix. All superior, subordinate, and peer references are automatically
inferred.
Shared configuration—You define all the knowledge files once, which are
then used by any DSA.
The benefits of these features are:
■
■
■
Shortest-path routing—Each DSA has knowledge of other DSAs so requests
are chained directly to the DSA that processes the request.
Integrated security—See the chapter “Security” for more information about
DSA to DSA security.
High speed switching—Knowledge information is cached in each DXserver.
5–1
Managing DSP
Managing DSP
You can manage DSP configuration using the DSP module commands at the
DXconsole. The DSP module commands let an administrator set and clear DSP
configuration management variables.
You can manage DSP configuration using the commands:
■
■
get parameter;
■
clear dsas;
■
unbind parameter;
DSP Command Options
A number of parameters of the DSP module commands let you change the DSP
configuration. The following tables summarize these parameters, and the
subsequent sections explain them in more detail.
The following are the parameters of the dsp set command:
Parameter
Value
always-chain-down
Value is TRUE or FALSE; when set to TRUE, the DSA overrides chainingprohibited controls when you need to chain the request to a subordinate
DSA.
dsa
The configuration details of a remote directory server.
max-dsp-ops
The maximum number of concurrent remote operations supported by the
server.
multi-chaining
Value is TRUE or FALSE; when set to TRUE, the DSA can multi-chain
searches to other DSAs.
multi-write-disp-recovery
Value is TRUE or FALSE; when set to TRUE, the DSA disables offline
multiwrite queuing. DSAs that cannot be contacted are dropped
immediately from the multiwrite set, and DISP is used to resynchronize the
DSAs when they come back online. Multiwrite DISP recovery cannot be used
where more than one DSA is attached to the same database. For more
information, see Multiwrite Replication the chapter “Replication.”
multi-write-queue
The maximum number of multiwrite operations that are queued when a
peer DSA cannot be reached. For more information, see the chapter
“Replication.”
5–2
Managing DSP
The following are the parameters of the dsp get command:
Parameter
Value
dsp
Shows the current DSP configuration values of the DSA.
online-dsas
Provides information about current outgoing connections
to other DSAs.
dsas
Provides information about all known DSAs.
The following are the additional commands of the DSP module:
Command
Meaning
clear dsas
Removes all remote-DSA definitions from the DSA.
unbind
Unbind one, or all, outgoing connections to other DSAs.
Knowledge References
The information in a set dsa definition is called a knowledge reference. A
knowledge reference provides the address of another DSA and an entry point,
represented by the DSA’s prefix, into the part of the directory tree that the DSA
controls. A DXserver is identified by its name and prefix. References appear as
entries to a DUA (see List Service in the appendix “DXconsole DUA” for more
information).
Access controls can hide the presence of a subordinate DSA, making that subtree
invisible to a list service or any other service. (See Access-Controlled Routing in
the chapter “Security” for more information).
The DSA dynamically determines the type of reference (superior, subordinate, or
cross-reference). When the reference is a cross-reference, the ancestors of the
cross-reference are visible to the list service.
5–3
Managing DSP
Remote Operations
Each DSA has a context prefix that defines the base of the DIT controlled by that
DSA.
When the DSA receives an incoming operation, it services the request locally
when it is in the DSA’s own DIT. When the operation is not local, it chains the
operation to a remote DSA unless:
■
■
■
■
■
One (user) service control—chainingProhibited or localScope—is set. You
can override this service control. (See Proxy DSAs in this chapter for more
information.)
Access controls hide the existence of the remote DSA. (See Access-Controlled
Routing in the chapter “Security” for more information.)
The remote DSA is unavailable.
You cannot establish a link of the appropriate authentication level to the
remote DSA. (See Other Security Features in the chapter “Security” for more
information.)
There is no DSA knowledge configured for the area of the operation.
Depending on the circumstance, the remote operation returns a:
■
Result
■
Referral
■
Service error
■
Security error
See the X.500 standards for a complete specification of how distributed DSAs
cooperate to resolve a query.
Limiting Remote Operations
In a multi-DSA environment a DSA may have to forward requests to other DSAs
to process. You can limit the maximum number of concurrent remote operations
that a DSA manages by setting max-dsp-ops in the configuration file (.dxc) in the
limits directory.
Example: Limiting the
Number of Remote
Operations to 100
5–4
set max-dsp-ops = 100;
Managing DSP
Remote Connections
The DSA dynamically binds to and unbinds from remote DSAs. A DSA
maintains at most one connection per security level (set by the auth-levels list in
the DSA definition) to a remote DSA. When a DSA has an established DSP
connection of the correct security level to a remote DSA, it uses this connection.
A second connection of the same security level is not set up.
The DSA definition supports trust flags that enable a DSA to upgrade or
downgrade a link between DSAs. For example, when a link between two DSAs
supports only anonymous connections, a credentialed user can access the link
when the receiving DSA supports the allow-downgrading trust flag. Conversely,
when the only allowed DSP link is a clear-password link, an anonymous user can
access the link only when there is support for the allow-upgrading trust flag (see
DSA Knowledge Flags in the chapter “General Administration” for more
information).
A DSP connection to a remote DSA unbinds after the dsp-idle-time is exceeded.
Remove Remote DSA
Knowledge
You can remove all knowledge of remote DSAs using the command:
clear dsas;
Unbinding Remote Connections
Display Outgoing
Connections
When a DSA communicates with a remote DSA using DSP, it sets up a
connection (bind) to the remote DSA. You cannot abort this connection using
the abort user command described previously because it is an outgoing
connection. You can obtain information about outgoing connections with the
command:
get online-dsas;
Unbind All or Some
Connections
You can unbind all or some connections using this information and one of the
following commands (assuming 3 is a valid connection identifier):
unbind all;
unbind dsa 3;
Unbind Outgoing
Connections That
Exceed Global
Values
A DSA can automatically unbind outgoing connections when they exceed
global values set in the remote-DSA definition, for example:
set dsa “Eagle” = {
...
dsp-idle-time = 60
...
};
5–5
Managing DSP
Incoming DSP Credentials
When a local DSA receives a bind with credentials from a remote DSA, it checks
the credentials against a matching (remote) DSA configuration. When you do not
configure a relevant remote DSA, the system rejects the incoming bind.
See DSA-to-DSA Encryption (DSP and DISP) in the chapter “Security” for more
information.
Outgoing DSP Credentials
If a remote DSA requires authentication, the local DSA must send credentials
when binding to the remote DSA. To be able to do this, the local DSA must have
credentials (user name and password) defined in its own set dsa definition (see
Configuring a DSA in this chapter for more information).
Distributed Searches (Multi-Chaining)
Searches can span multiple DSAs. A subtree search searches all entries below
and including the base-object of the search. Some entries can reside on a different
DSA from the base-object. When you enable multi-chaining, the DSA searches for
immediate subordinate DSAs after you find the base-object and then forwards
the search to these DSAs. Results from all subordinate DSAs and the local DSA
(the DSA containing the base-object) are collated before being returned.
Limiting Multi-Chaining
In a multi-DSA environment the DIT is controlled by multiple DSAs. A search
area can span part of the DIT that is controlled by more than one DSA. In this
case the DSA containing the base object of the search will multi-chain the request
to the other relevant DSAs. You can disable multi-chaining in two ways:
■
■
The originator of the request can disable multi-chaining by specifying localscope in the common arguments of the search.
The DSA administrator can disable multi-chaining by using the command:
set multi-chaining = false;
The DSA prevents multi-chaining to any DSA having a presence hidden by
access controls. (See Access-Controlled Routing in the chapter “Security” for
more information.)
5–6
Managing DSP
Viewing DSP Configuration
You can monitor DSP connections using the dsp module get command at the
DXconsole. You can view the DSP configuration values and details of current
outgoing connections.
View DSP
Configuration
To view the DSP configuration, use the command:
get dsp;
This is a sample of the output from this command:
max-dsp-ops
local-prefix
local-dsa
multi-chaining
always-chain-down
multi-write-queue
View Online
Connections
=
=
=
=
=
=
100
<countryName AU><organizationName “DemoCorp”>
“DemoCorp”
FALSE
TRUE
200 (current 0)
To view the DSP connections that are currently active, use the command:
get online-dsas;
This is a sample of the output from this command:
dsa> get online-dsas;
Remote: DSA 2 (DEMOCORP)
Association: state 3, idle for 2 seconds, 0 operations waiting
0 operations abandoned
prefix:
<countryName “AU”>
<organizationName “DEMOCORP”>
dsaName:
<countryName “AU”>
<organizationName “DEMOCORP”>
<commonName “DXserver”>
dsaPassword: ?
hostname: EAGLE
OSI PSAP:
address: 208.12.151.204:19389
address: 127.0.0.1:19389
dispPsap: DISP
cmipPsap: CMIP
snmpPort: 19389
consolePort: 19390
ssldPort: 1112
DEMOCORP:next_distinct: (none) (precedence 3)
:next_similar: (none)
:children: (none)
refType: cross
auth-levels: anonymous clear-password ssl-auth
dsa-flags:
trust-flags: allow-check-password
link-flags:
maxIdleTime: 60
credit: 5
precedence: 3
Display Each DSA for
Which the Current
DSA Has Knowledge
Use the following command to display information about each DSA for which
the current DSA has knowledge, including itself:
get dsas;
5–7
Configuring a DSA
Configuring a DSA
You can configure all DSAs, including the local one, using the set dsa command
(see Defining DSAs in the chapter General Administration for more information).
You can dynamically issue the set dsa command from the DXconsole, but it is
recommended that you include it in a DSA definition file (.dxc) in the knowledge
directory. You then source this file from another configuration file, either a .dxg
file in the knowledge directory or a .dxi file in the servers directory.
Configuring a Subordinate DSA
The following example defines a DSA called DemoResearch, which is
subordinate to the pre-configured DemoCorp DSA in the standard version.
Example
set dsa “DemoResearch” = {
prefix
= <c AU><o DemoCorp><ou Research>
dsa-name = <c AU><o DemoCorp><ou Research><cn DXserver>
dsa-password
= “demo”
address = tcp Eagle port 389
disp-psap = DISP
cmip-psap = CMIP
snmp-port = 1950
console-port
= 1952
auth-levels
= anonymous, clear-password
dsp-idle-time
= 10000
credits = 5
};
The DSA definition contains a prefix that defines the area of the DIT that is
covered by this DSA:
prefix
= <c AU><o DemoCorp><ou Research>
The DSA administers the prefix and the entries below, except for any areas of the
DIT below the prefix that are covered by another DSA.
Every object within the directory has a unique distinguished name (DN), which
directs it to an entry in the directory. The complete directory tree is called the
Directory Information Tree (DIT) and can comprise a number of independent
X.500 DSAs or LDAP servers that, between them, hold all the various branches of
the directory tree.
The naming context (which is also a DN) of an X.500 or LDAP server defines the
branch that server owns.
The X.500 and LDAP communities differ in the way they write their DNs. Within
X.500, DNs are written from the top of the tree down (for example, c=US,
o=Computer Associates, and so forth). Within the LDAP community, DNs are
written from the leaf entry up (for example, cn=John Smith, ou=Sales, and so forth).
5–8
Configuring a DSA
Proxy DSAs
There are a number of situations where a group of DSAs must appear to the
outside world as a single DSA.
External
DUA or DSA
Proxy DSA
Internal
DSA 2
Internal
DSA 1
Internal
DSA 3
Internal
DSA 4
For example, an organization can make a single DSA visible through an Internet
firewall, but internally let that DSA send DSP requests to other internal DSAs
that control subtrees subordinate to the visible DSA. This configuration fails
when the external DUA sets the local-scope or chaining-prohibited service
controls. In this case, the visible DSA returns a referral, but the DUA cannot
connect to the referred DSA because there is no access to this DSA through the
firewall.
The solution to this problem is overriding the local-scope and chainingprohibited service controls using the command:
set always-chain-down = true;
When you enable this feature in the visible DSA, requests are chained to the
relevant DSA regardless of the request’s service controls. Also, subtree searches
are always multi-chained to subordinate DSAs.
A proxy DSA is also useful if an X.500 guard wants to hide the address of DSAs
inside the enclave that it is guarding.
5–9
Configuring Another DXserver
To configure the knowledge of a remote DSA, use the set dsa command (see
Defining DSAs in the chapter “General Administration” for more information).
Local DSA
Remote DSA
A DXserver is identified by its name and prefix. The relationship between two
DXservers is represented by the corresponding relationship between the prefixes.
See A Domain of DXservers in this chapter for more information.
Configuring Alternative Network Addresses
You can configure knowledge of more than one network address for a DSA. This
is used where you want to distribute the directory over more than one physical
or logical network. This facilitates increased network availability by using
additional networks between DSAs.
To configure knowledge of more than one network address for a DSA, use the set
dsa command:
set dsa “DualNetwork” = {
…
address
= tcp “dnet1” port 389, tcp “dnet2” port 1900
…
};
NET 1
DSA Dual
Network
NET 2
Handling Firewall Address Translation
If your firewall translates remote addresses, your DSA may not recognize the
remote DSA because of the changed address. You must configure alternative
network addresses in the knowledge file of the remote DSA by specifying the
address of the remote DSA followed by the address of the firewall.
5–10
Configuring a Third-party DSA
To configure the knowledge of third-party DSAs, use the set dsa command.
Example: Setting a
Remote DSA
Reference
set dsa “DemoUni” = {
prefix
= <c AU><o DemoUni>
dsa-name
= <c AU><o DemoUni><cn DSA>
};
address
= tcp “demouni.edu” port 389
auth-levels
dsp-idle-time
= anonymous
= 10000
Note: This DSA does not support DISP, CMIP, or SNMP and has only
anonymous access.
DXlink
A third-party DSA can be an LDAP server. DXserver has a feature, DXlink,
which treats a remote LDAP server as another DSA. To activate DXlink, set the
dsp-ldap link flag in the set dsa command in the knowledge directory of the
LDAP server:
link-flags = dsp-ldap
Note: When you are using LDAP Version 3, use the dsp-ldap link flag. When you
are using LDAP version 2, use dsp-ldapv2.
For more information about DXlink, see Integrating Other LDAP Servers in the
chapter “LDAP and DXlink.”
5–11
Configuring Multiple Local DSAs
To support large databases, parallel processing, or independent subtrees (for
example, for performance or security reasons), you can run a number of
DXserver DSAs on the same machine. You configure each DSA with its own
definition and connect the DSAs together using DSP.
Example: Setting Two
DSA References on
the Same Machine
# Knowledge configuration file: localTwo.dxc
set dsa “LocalTwo” =
{
prefix
= <c "AU"><o "DemoCorp"><ou "Sales">
...
address
= tcp "Eagle" port 1910
...
};
# Knowledge configuration file: localThree.dxc
set dsa “LocalThree” =
{
prefix
= <c "AU"><o "DemoCorp"><ou "Support">
...
address
= tcp "Eagle" port 1920
...
};
In this example, you can see that two local subtree DSAs are accessible:
AU/DemoCorp/Sales and AU/DemoCorp/Support. They each listen on
separate ports—1910 and 1920—although they have the same TCP/IP address.
If the underlying RDBMS supports load sharing across multiple CPUs, each
DSA process inherits this capability.
5–12
Configuring a Domain of DXservers
A typical directory installation will include a number of DSAs, which together
control the DIT. These DSAs will usually control different portions of the DIT
and they need to cooperate in order to process client requests. This section shows
how a group of DSAs share DXserver knowledge.
A Domain of DXservers
The following diagram shows how to configure five DSAs to control a DIT. Each
DSA has control over a portion of the DIT, represented by its prefix, and a
relationship with the other DSAs in the domain. For instance DSA1 is the
superior DSA of DSA2 and DSA3, while DSA4 and DSA5 are subordinates of
DSA3.
DSA 1
DSA 3
DSA 2
DSA 4
DSA 5
A request received by one DSA that requires an operation on an entry that is not
contained in that DSA’s area of control, is chained (forwarded) to the relevant
DSA. A request may be chained through a number of DSAs before finding the
DSA capable of processing the request. When a domain of DSAs has shared
knowledge, a DSA receiving a request is able to forward that request directly to
any other DSA within the domain.
A search request can require a subtree search spread over more than one DSA. In
this case, the DSA containing the base object of the search performs the search
locally and multi-chains the search to any DSAs that control part of the subtree to
be searched. These DSAs will then return the search results back to the
originating DSA, which will collate them and return the result back to the client.
5–13
Sharing DXserver Configuration
You should include each DSA definition in its own configuration file (.dxc) in the
knowledge directory. You can group together a number of DSA definitions into a
domain by creating a group file (.dxg) in the knowledge directory that sources
each required configuration (.dxc) file. You can then include the group file in a
server initialization file (.dxi) in the server’s directory.
If you change a reference or add a new DSA to the network, you can generate a
new configuration file and send a copy to each DSA that uses the reference.
DSA A
DsaA.dxi
dom.dxg
(Copy)
.dxc
(Copies)
DsaA.dxc
dom.dxg
DsaB.dxc
DSA B
DsaB.dxi
dom.dxg
(Copy)
.dxc
(Copies)
Each DXserver recognizes its own set dsa definition so that it can determine
whether or not an operation is local.
Configuring a First-level DSA
When the local prefix contains only one Relative Distinguished Name (RDN) in
its DN, the DSA is a first-level DSA. Usually there is no actual root-level DSA, so
each first-level DSA must handle lists and searches from the root. This means
that a first-level DSA multi-chains a search from root to other first-level DSAs.
5–14
Configuring a Router DSA
It is possible to start a DSA without connecting to a database. In this
configuration, the DSA (known as a router DSA) simply forwards requests to
other DSAs. To do this, comment out or remove the line in the DSA initialization
file that sets the database name, as follows:
...
# DATABASE
# source “../database/dbname.dxc”;
...
A DSA without a database is used to pass on requests to one of a number of
DSAs known to the router DSA. The router DSA determines which DSA can best
process the client’s request. See Alternative DSAs in this chapter for more
information.
A router DSA consumes a level of the DIT. In the following example of a router
DSA’s knowledge file, c=au is the level of the DIT consumed by the router DSA.
set dsa ROUTER =
{
prefix
dsa-name
dsa-password
address
disp-psap
cmip-psap
snmp-port
console-port
ssld-port
auth-levels
dsp-idle-time
};
=
=
=
=
=
=
=
=
=
=
=
<c AU>
<c AU><CN DXserver>
“secret”
tcp “hostname” port 19289
DISP
CMIP
19289
19290
1112
anonymous, clear-password, ssl-auth
60
Transparent Routing
A router DSA can be used to link clients to a number of external LDAP servers,
using DXlink. In this case, the LDAP clients and the LDAP server may have
schema that are not known by the router DSA.
This means that the router DSA may receive requests and responses that contain
unknown schema. Normally, the router cannot process such queries. However, if
transparent routing is enabled, the router can pass LDAP requests and responses
without requiring the controlling schema.
Transparent routing only works with LDAP clients.
To enable transparent routing, use the following command:
set transparent-routing = true;
By default, transparent routing is set to FALSE.
5–15
Configuring a Relay DSA
You can configure a DSA as a relay DSA so that it forwards requests. A relay
DSA does not occupy a level of the DIT. This is useful for router DSAs (such as
load balancers) or proxy DSAs (such as firewalls), because you can effectively
insert them without affecting the DIT. A relay DSA always forwards requests;
therefore it cannot have a local database.
A relay DSA only adds to the DSP trace information if the incoming request was
from a DUA.
To create a DSA as a relay DSA, add relay to its DSA flags:
set dsa DemoCorp = {
...
dsa-flags = relay, ...
...
};
Caching Entries from Subordinate DSAs
Unlike DAP, LDAP does not have a LIST operation. So, when LDAP clients want
to browse a directory, they invoke one-level searches that return object class
only. These one-level searches become a problem when there are many
subordinate DSAs because a one-level search must be broadcast to each of the
DSAs (whereas a LIST simply returns the names of the DSAs). To stop the
flooding effect that this creates, especially at first-level DSAs, the DXserver caches
the replies to one-level-search queries and makes them available to subsequent
similar requests. Only one-level searches returning object class are cached—these
are the searches commonly used to browse the directory.
5–16
Alternative DSAs
Alternative DSAs
If you define more than one DSA with the same prefix (naming context) and
data, these DSAs can be used to improve the performance and availability of the
directory service.
This section describes three ways that groups of DSAs with the same prefix and
the same data can be used:
■
■
■
Failover—To improve the availability of the service, when one DSA fails,
another automatically takes over its request load.
Load sharing—To improve performance, read requests are divided between
two or more DSAs.
Query streaming—To improve performance, requests of different types are
routed to different DSAs.
5–17
Alternative DSAs
DSA Failover
The purpose of failover is to improve the availability of the directory service.
In the following example, the router DSA usually sends requests to DSA 1. If
DSA 1 fails, the router DSA automatically sends all requests to DSA 2. This
change is invisible to the clients. In this system, DSA 2 is simply a backup: it is
only used if DSA 1 fails.
Router DSA
DSA 1
Database
DSA 2
Replication
Computer A
Database
Computer B
Failing Over to a Backup DSA
In the following example, the San Diego and Tokyo offices each use local replica
DSAs, to improve performance. During normal operation, each local router DSA
sends requests to the local data DSA. If either of the local data DSAs fails, the
routers automatically fail over to the remote data DSA.
San Diego
Router DSA
Tokyo
Router DSA
DSA 1
DSA 2
Database
Replication
Computer A
(San Diego)
Failing Over to a Remote DSA
5–18
Database
Computer B
(Tokyo)
Alternative DSAs
Set the DSA Precedence For Failover
When more than one data DSA fails, the router DSA fails over to other DSAs in
their order of occurrence in the configuration files.
You can override this order with the following commands:
set precedence
set write-precedence
= dsaname1 [, dsaname2, dsaname3… ] ;
= dsaname1 [, dsaname2, dsaname3… ] ;
The command set precedence defines the order of the DSAs that the router DSA
fails over to.
The command set write-precedence defines the order in which DSAs are chosen to
perform updates. You can use it to direct the write requests from a failover
computer to a preferred master. If the set write-precedence command is not
present, updates follow the normal precedence, which is defined by the order of
the DSAs in the configuration file, or the set precedence command.
The DSAs in these lists have precedence over those that are not listed, and DSAs
earlier in the lists have precedence over those later in the lists.
When these commands occur in a configuration file, source them after the
knowledge.
To maximize performance, in general you should give faster DSAs precedence
over slower DSAs, and local DSAs precedence over remote DSAs.
Example: Using
precedence for
geographically
separated DSAs
The DSAs EAST, WEST, NORTH and SOUTH contain the same information. The
following command ensures that DSAs in the east fail over to EAST before
WEST:
set precedence = EAST, WEST;
The DSAs NORTH and SOUTH are not listed, so if both EAST and WEST are
unavailable, DSAs will fail over to them in the order that they are listed in the
configuration file.
Example: Using write
precedence
set write-precedence = home-dsa,work-dsa;
5–19
Alternative DSAs
DSA Load-Sharing
Load-sharing is a way to use a router DSA and multiple data DSAs to improve
performance.
In a system with load-sharing, the router uses a least-busy algorithm to send
read requests to the DSA with the least load at the time.
In the example load-sharing configuration shown below, DSA2 has the smallest
queue of outstanding queries, so the router DSA will send the next query to that
DSA.
Queries
Router DSA
Queue:
Queue:
20 queries
0 queries
DSA 1
DSA 2
Queue:
10 queries
DSA 3
Database
Example Load-Sharing Configuration
When the router DSA is checking the DSAs, it only considers requests that it has
sent, and it does not assess the load that might be caused by the request about to
be sent, or the effect of requests that are being sent from other DSAs.
You can examine the statistics logs of the data DSAs to understand how often the
load is such that all three are busy. If all three are often busy, you might need
more data DSAs.
5–20
Alternative DSAs
Load-Sharing Groups
In a load-sharing system, DSAs work to balance the number of read requests.
You can use load-sharing groups to constrain load-sharing to a sub-set of the DSAs
that have the same prefix.
The following example shows a router DSAs and three data DSAs with the same
prefix. Two of these data DSAs are in a load-sharing group, and the router shares
the load of read requests between these two DSAs. The third DSA is ignored
because it is not in the load-sharing group.
Read
Requests
Load-sharing
group
Router DSA
DSA 1
DSA 2
DSA 3
Database
Computer A
Using a Load-Sharing Group to Limit Load-sharing to Particular DSAs
5–21
Alternative DSAs
In the following example, the San Diego and Tokyo offices each use local loadsharing groups of DSAs, to improve performance. During normal operation,
each local router DSA sends requests to the local group. If all of the DSAs in one
local load-sharing group fail, the router can fail over to the remote load-sharing
group.
During normal operation, the router shares the load of read requests between the
DSAs in the first load-sharing group. If all of the DSAs in this group are
unavailable, the router will fail over to the second load-sharing group.
Read
Requests
Read
Requests
San Diego
Router DSA
Tokyo
Router DSA
DSA 1
DSA 2
DSA 3
DSA 4
Load-sharing
groups
Database
Database
Replication
Computer A (San Diego)
Example System with Two Load-Sharing Groups
5–22
Computer B (Tokyo)
Alternative DSAs
Set the DSA Precedence For Failover with Load-Sharing Groups
You can use precedence rules to affect how failover works with load-sharing
groups. For information about setting precedence, see the section Set the DSA
Precedence For Failover in this chapter.
If you use the set precedence command to list DSAs that are also in load-sharing
groups, then a load-sharing group has the precedence of the highest DSA in that
group.
For example, consider the following command:
set precedence DSA1, DSA2, DSA3, DSA4;
A load-sharing group that includes DSA1 and DSA4 has precedence over a
group that includes DSA2 and DSA3.
Also, a load-sharing group that includes DSA4 has precedence over a group that
includes no listed DSAs.
Set Up a Load-Sharing System
To set DSAs to share the load for a particular context prefix, do the following:
1.
Decide how many DSAs you will use to share the load of read requests.
2.
Set up these DSAs with the same prefix and the same data.
3.
Set each DSA to share the same knowledge information.
4.
Add the load-share DSA flag to the shared knowledge:
set dsa dsaname = {
...
dsa-flags = load-share, ...
... };
5.
In the router DSA’s group knowledge file (.dxg), list the load-sharing DSAs
consecutively.
6.
(Optional) To create a load-sharing group, add the load-share-group item to
the knowledge for the DSAs in the group:
set dsa dsaname = {
...
load-share-group = group-name
dsa-flags = load-share, ...
... };
5–23
Alternative DSAs
DSA Query Streaming
Query streaming is a way to send particular types of queries to different DSAs.
This allows you to dedicate DSAs to particular types of operations, which can
improve performance consistency.
You can use query streaming with load sharing, to direct queries to different
load-sharing groups.
How Query Streaming Works
Query streaming is somewhat like checkout lanes in a supermarket. In a
supermarket, the express lanes are reserved for small sales, to allow people with
only a few items to be served quickly.
In a supermarket without an express lane, people with only a few items can be
stuck behind people with many items.
Similarly, you can dedicate some DSAs to small, fast queries (for example,
authentications) so that they are not held up by complex queries (for example,
reports).
In the following example, the Router DSA sends queries in the following manner:
■
Simple searches only go to DSA 1 and DSA 2
■
Complex searches only go to DSA 3
■
Update requests only go to DSA 4
Queries
Router DSA
Simple
queries
DSA 1
load-share
limit-search
read-only
Simple
queries
DSA 2
load-share
limit-search
read-only
Complex
queries
DSA 3
Update
requests
DSA 4
read-only
Example of a Distributed System Set Up to Allow Query Streaming
5–24
Alternative DSAs
Set Up Query Streaming
To set up query streaming, follow these steps:
1.
Decide how many data DSAs your distributed system will include.
2.
Decide what queries each data DSA will accept.
3.
For each data DSA, set one or more of the following flags in the DSA
knowledge file:
The read-only flag
A router will not forward update requests to a DSA that has the flag
read-only set in its knowledge file. This routes update requests to any
DSAs without the flag read-only.
The limit-list flag
A router DSA will not forward any list requests to a DSA that has the
flag limit-list set in its knowledge file.
The limit-search flag
A router DSA will not forward any complex searches to a DSA that has
the flag limit-search set in its knowledge file.
For more information about the limit-search flag, see the section Example:
How the limit-search DSA Flag Works in the chapter “General
Administration.”
What Is a Simple Search?
This section describes simple and complex searches. If a DSA includes the limitsearch flag in its knowledge file, no complex searches will be sent to that DSA.
The following searches are simple:
■
Exact match searches—For example, cn=john smith
■
Initial substring searches—For example, cn=john s*
■
■
Searches that include exact-match and initial-substring searches combined
with simple ANDs or ORs,—For example, (&(cn=john smith)(cn=john s*))
All base-object searches (reads), regardless of the filter
The following searches are complex:
(objectclass=*)
(!(cn~=john smith))
(&(objectclass=*)(cn~=john smith))
(|(cn=jon*)(cn=john*))
These complex searches could only be sent to a DSA that does not have the limitsearch flag set.
5–25
Chapter
6
Security
This chapter describes the following areas of eTrust Directory security:
■
Secure Socket Layer (SSL) encryption
■
Authentication
■
Password management
■
Access controls
Security
6–1
Secure Socket Layer (SSL) Encryption
This section describes how to use SSL to protect link connections to or from
DXserver.
About the SSL Protocol
SSL is a protocol for providing link-level security. SSL has virtually become the
industry standard for encryption, integrity, and authentication. For more
information about SSL, see http://home.netscape.com/eng/ssl3/index.html.
SSL and Certificates
SSL uses X.509 certificates. When you use SSL, you must properly manage these
certificates through a certification authority or appropriate software.
JXplorer lets you manage certificates, private keys, and keystores. See the chapter
“Using JXplorer” for more information about managing certificates and enabling
SSL authentication.
eTrust Directory and SSL
DXserver supports SSL as both an encryption method and an authentication
method. We refer to this as SSL encryption and SSL authentication.
Note: SSL authentication always uses SSL encryption.
6–2
SSL Encryption and Authentication Using SSLD
You can protect any link connection to or from DXserver with SSL encryption.
eTrust Directory implements SSL encryption and authentication as a companion
process to the DSA. This process is called SSLD. SSLD is based on OpenSSL.
For security, SSLD must run on the same computer as the DXserver.
SSLD is multithreaded, which means that one SSLD process can serve multiple
DXservers simultaneously. There is no need to run multiple SSLD processes on
the same computer.
The SSLD server supports:
■
SSL (both version 2 and 3)
■
Transport Layer Security (TLS)
How the SSLD Works with Certificates
SSLD uses the following types of certificates, which are stored in its
configuration directory:
■
■
Trusted root certificates (“trusted.pem”) that contain one or more
certificates of trusted Certification Authorities.
Personality certificates that identify the one or more DXservers that are
communicating with the SSL server. There is one per DSA (dsaName.pem),
and each one contains a private key.
The following diagram displays this:
Directory
Client
DB
DSA
SSLD
Personality
Certs
HSM
Trusted
Certs
Security
6–3
How DXserver Works with SSL Binds
Unlike other directory implementations, the eTrust Directory DSA handles DAP,
LDAP, DSP and DISP protocols through a single port in SSL-encrypted and
unencrypted forms. When SSL encryption or decryption is required, the DSA
passes the packets to the SSLD to perform the SSL operation.
When a client binds to a DXserver using SSL, the following happens:
1.
If the DXserver is not already connected, it connects to the SSLD, assuming it
is running.
Note: If the SSLD is not running or is not configured properly, possibly with
a different port, the DSA refuses the client connection (fails the bind request).
2.
DXserver passes all SSL handshaking to the SSLD to establish the SSL
connection with the client.
3.
DXserver uses SSLD to decrypt requests and encrypt responses.
The following diagram displays this:
Directory
Client
DB
DSA
1
2
3
SSLD
6–4
DXserver Personality Certificates
When a DSA connects to SSLD it passes the DSA server name as its SSLD
personality. The server name is the name specified by the set dsa dsaName
command in the DSA configuration file in the knowledge directory. For example,
for the Democorp DSA, the SSLD personality name is democorp.
This personality determines the certificate file that the SSLD uses to support
authentication of the DSA.
The personality name passed to the SSL server is mapped to a file name of the
form personality.pem (the personality string is converted to lowercase). This file
contains a certificate and private key in PEM format (the private key is what
gives the DSA its identity) unless a HSM is in use, in which case it is a hardware
reference. For information about DXserver HSM support, contact Computer
Associates at http://supportconnect.ca.com.
Generating Personality Certificates
You must not simply rename the personality files that come with eTrust
Directory (for example, from democorp.pem to mydsaname.pem) and edit the
subject lines. This text is just comments for the real certificate—changing the text
does not alter the certificate. You must generate a new certificate.
To generate personality certificates, use separate certificate authority software.
The popular certification authority software OpenSSL is available from
http://www.openssl.org/. You can either build the package from the source
code (which requires a compiler) or locate a binary (precompiled) package for
your operating system.
When you are generating a personality certificate, ensure the following:
■
■
Make sure that the DSA name in the subject field of the certificate matches
the DSA name in the DSA knowledge. For example, for the Democorp DSA,
this is <c AU><o Democorp><cn DXserver>.
Add the root certificates of the certificate authorities that you use to generate
your DXserver personality certificates to the end of the trusted.pem file.
Security
6–5
Setting Up SSL For DXserver
This section describes what you have to do to set up SSL for DXserver. You will
need a root certificate, a DSA personality certificates and an SSLD instance to
service DSA requests.
Configuring DXserver for SSL Operation
DXserver needs to know which port the SSLD is using for connections. This is
configured in the DSA configuration file (.dxc) in the knowledge directory.
For example:
set dsa Democorp =
{
...
ssld-port = port_number
...
};
If the SSLD port number is not specified, it defaults to port 1112.
Configuring the SSLD
To configure SSLD, you need a root certificate, DSA personality certificates and a
SSLD instance to service DSA requests.
The format of the SSLD command is as follows:
ssld action [arguments]
The following table lists the SSLD actions available:
Action
Description
install
Saves the startup arguments and options and sets the SSLD to start
automatically at system startup.
ssld install ssld-server-name -certfiles path -ca file [options]
start
Starts the SSLD:
ssld start ssld-server-name [-certfiles path -ca file [options]]
If you have already installed the SSLD, you can omit the arguments and options.
To start all previously installed SSLDs, use the command:
ssld start all
6–6
Action
Description
stop
Stops the specified SSLD:
ssld stop ssld-server-name
To stop all SSLDs, use the command:
ssld stop all
remove
Removes the specified SSLD from the list of automatically restarting SSLDs so
that it does not restart at the next system startup.
ssld remove ssld-server-name
To remove all SSLDs, use the command:
ssld remove all
status
Displays the status of all configured SSLDs:
ssld status
-ciphers
Prints a list of all ciphers that can be used for SSL/TLS connections:
ssld -ciphers
The following table describes the parameters of these commands.
Parameter
Meaning
-certfiles path
The directory that contains certificate and private-key files in PEM format.
This parameter is required by the install action. It is also required by the start
action if the SSLD server has not already been installed.
-ca file
A file that contains trusted certification authority certificates in PEM format.
This parameter is required by the install action. This parameter is also required
by the start action if the SSLD server has not already been installed.
The arguments of the ssld install and the ssld start commands are:
Argument
Values
-hsm_pin pin
The hardware security module (HSM) user PIN. If specified, the private key is
used through the HSM.
-hsm_lib file
File containing the pks#11 library supplied by the HSM vendor.
-hsm_slot n
The HSM slot number.
-cipher string
Specifies the ciphers that will be used for SSL/TLS connections.
-help
Displays command usage.
-port n
The listen port, which DXserver uses when connecting to the SSL daemon. If not
specified, it defaults to port 1112.
-tls
Instructs SSLD to use TLS instead of SSL 3.0.
Security
6–7
Argument
Values
-nologo
Do not show the banner.
-debug n
Sets a debugging level (0-9).
-threads n
Specifies the number of extra threads. The default is 2, which makes the SSLD
multi-threaded by default.
Resetting SSLD Parameters
The parameters of the ssld start command are stored. This means that even if you
stop and restart the SSLD, it continues to use the parameters that you set when
you first started the SSLD.
For example, if you run the following commands, the logging level set in the first
line is not reset:
ssld start xxx -debug 9
ssld stop xxx
ssld start xxx
There are two ways to reset SSLD parameters:
■
Reset the parameter directly
You can stop and start the SSLD again, making sure that you explicitly re-set
all parameters. For example, to re-set the logging parameter:
ssld stop xxx
ssld start xxx -debug 0
■
Install the SSLD again, with the new parameters
Another way to reset SSLD parameters is to remove and re-install the SSLD.
The installation re-sets the parameters:
ssld
ssld
ssld
ssld
stop xxx
remove xxx
install xxx [arguments]
start xxx
The parameters are stored in the following locations:
■
■
6–8
Windows—The following registry variable :
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ssld_ins
tancename\Parameters
UNIX and Linux—The ssld_name.args file in $DXHOME/config/ssld
SSLD Is Multi-Threaded
SSLD can be configured to run more than one instance on each computer.
However, we recommend that you use only one instance of SSLD per computer.
You should only run one instance of SSLD on each computer because SSLD
cannot determine if there is another SSLD instance on the same port when it
starts up. This is due to the way Windows allocates TCP ports. This limitation
means that two SSLD instances might be running on the same port, with
unpredictable results, including "Assertion Error" messages and SSLD hanging
and refusing to accept new requests.
Instead of running multiple instances of SSLD, use the -threads parameter to set the
required number of threads. We recommend that you set the number of threads to
twice the number of CPUs, unless you have a large number of CPUs. If you have
many CPUs, then set the number of threads to the number of CPUs plus five.
In the following example, the SSLD process uses four CPUs, and is started
automatically when the Democorp DSA is started. The certificate and private key
files are in the directory DXHOME/config/ssld/personalities, and the trusted
Certification Authority (CA) certificate is in config/ssld/trusted.pem.
ssld install democorp –certfiles config/ssld/personalities –ca config/ssld/trusted.pem –threads 4
SSLD Example: Specifying the Cipher for SSL/TSL Connections
You can specify which cipher is to be used for SSL/TLS connections. When you
start the server, use the -cipher option, as in this example:
ssld start democorp –certfiles config/ssld/personalities –ca
config/ssld/trusted.pem -cipher RC4-MD5
To list all the available ciphers, use the -ciphers action:
ssld -ciphers
A list of ciphers appears, as in the following example:
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH(1024) Au=RSA Enc=3DES(168) Mac=SHA1
EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=3DES(168) Mac=SHA1
DES-CBC3-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=3DES(168) Mac=SHA1
DHE-DSS-RC4-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=RC4(128) Mac=SHA1
RC4-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(128) Mac=SHA1
RC4-MD5 SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(128) Mac=MD5
EXP1024-DHE-DSS-RC4-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=RC4(56) Mac=SHA1 export
EXP1024-RC4-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=RC4(56) Mac=SHA1 export
EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(1024) Au=DSS Enc=DES(56) Mac=SHA1
DES-CBC-SHA SSLv3 Kx=RSA(1024) Au=RSA Enc=DES(56) Mac=SHA1
EXP-EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export
EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export
EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export
EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
Mac=MD5
export
Security
6–9
For more information about ciphers, see http://www.openssl.org/.
6–10
Client Encryption
DXserver automatically detects an SSL session from an LDAP client or DAP
DUA. If the SSLD is running, it manages all the session establishment and
encryption. If the SSLD is not running, the connection is refused.
The only way to force a client to use SSL encryption is by enforcing SSL
authentication.
DSA-to-DSA Encryption (DSP and DISP)
To enable a DXserver to use encryption when communicating with a remote
DSA, set the link flags to ssl-encryption in the knowledge file of the remote DSA.
For example, to enable encryption from a Democorp DSA to a UNSPSC DSA,
ensure that, in the knowledge, the UNSPSC link flag is set to ssl-encryption.
set dsa UNSPSC =
…
link-flags = ssl-encryption
…
DUA
OP
DemoCorp
DSA
BIND
UNSPSC
DSA
Note: The previous DSAs share the same configuration, but the Democorp
directory must look up the capabilities of the other directories to decide whether
to use SSL encryption.
Security
6–11
Authentication
Authentication
Authentication is the process of validating users. During authentication, the
server asks itself, “Is the user who they say they are?”
DXserver supports three levels of authentication:
■
Anonymous (no credentials)
■
Simple (name and password)
■
SSL (certificate-based authentication)
Authentication is performed on all incoming binds from a client or server. When
certificate-based authentication is used, then all communication on the
association set up by the bind will use SSL encryption.
Setting the Minimum Authentication Level
You can set the minimum authentication level on a DXserver using the
set min-auth command. This sets the minimum requirements for a successful
bind to the DXserver.
No Authentication
Setting no authentication permits any type of authentication (including
anonymous). To permit any authentication, use the following command in the
initialization script or at the management console:
set min-auth = none;
Name and Password Authentication
To force authentication of at least a name and password, set min-auth to
clear-password. This ensures that a user provides a user name and clear-text
password or provide a certificate (to be checked using SSL authentication) on a
bind.
set min-auth = clear-password;
Certificate Authentication
To force authentication by certificate, set the following command:
set min-auth = ssl-auth;
6–12
Authentication
Anonymous Authentication
When no credentials are provided or only simple credentials are provided
without a password (for instance, just a name), then the bind is treated as
anonymous. An anonymous bind is accepted only when the minimum
authentication level is none.
Simple Authentication
When a name and password are supplied with the following conditions, the bind
is treated as simple.
■
The name corresponds to a real entry in the directory.
■
That entry has a password attribute.
■
The supplied password matches it.
■
The min-auth flag does not include the value ssl-auth.
For simple authentication, all users must have corresponding directory entries
containing the password attribute.
Authentication fails and the bind is refused when:
■
The entry named by the user cannot be found.
■
The entry named by the user name does not contain a password attribute.
■
The password provided does not match the password value of the attribute
in the entry named by the user name.
When the user does not provide a user name and password or only provides a
user name, and if the minimum authentication level is set to “none,” the bind is
accepted as anonymous.
You can add the password attribute to an object with a remote DUA. When
access controls are in force, users can add or change a password only when they
have the appropriate privilege, for example:
■
■
Superuser
Administrator of a subtree (only for entries in the subtree and only when the
administrator has privileges on the password attribute)
■
Administrators of their own entry
■
Registered user with update permissions on the password attribute
Security
6–13
Authentication
SSL Authentication
SSL authentication has two parts:
1.
2.
Establish the SSL connection.
Establish the directory connection (using a bind).
Establishing the SSL Connection
The SSL client provides a certificate with the SSL connection:
SSL
Client
DemoCorp
DSA
The DXserver/SSLD validates the certificate by checking the validity dates and
checking the issuer of the certificate against the configured trusted roots.
SSLD
SSL
Client
Trusted
Certs
DemoCorp
DSA
The SSL connection is then established.
SSL
Client
SSL
DemoCorp
DSA
Establishing the Directory Connection
The SSL client uses the SSL bind procedure. In LDAP, this is known as
SASL/EXTERNAL. (In X.500, we use the Bind External Procedure.) This tells the
directory to use the certificate from the link layer.
6–14
Authentication
SSL
Client
BIND
SSL
DemoCorp
DSA
The DSA checks the entry named by the subject DN contained in the certificate.
In the case of DAP or LDAP (clients), the DSA verifies that the entry exists. In the
case of DSP or DISP, the DSA will check the dsa-name in its knowledge.
To bypass this last check of the certificate’s subject DN, use the command:
set ssl-auth-bypass-entry-check = TRUE;
This establishes the directory connection.
X.500/
LDAP
SSL
Client
SSL
DemoCorp
DSA
Restricted Chaining
If a DSA receives a bind request and passes a compare request to a remote DSA,
then the compare request will have a chaining-prohibited control set.
This prevent the remote DSA from passing the compare request to another DSA
and ensures that the compare is only processed by a trusted DSA.
If users are storing a hierarchy of DSAs, then it is a good idea for the DSAs to
share knowledge so that compare requests can be sent straight to the DSA that
contains the entry.
Overriding Restricted Chaining
It is possible for a DSA to override the chaining-prohibited control by setting
always-chain-down to true.
This can be useful when you want to configure proxy DSAs. For information
about proxy DSAs, see the section Proxy DSAs in chapter 5.
However, we recommend that you do not override the chaining-prohibited
control, because this breaks the trust relationship between DSAs.
Security
6–15
Authentication
Bypassing the Entry Check
Usually, during SSL authentication, the DSA verifies that the entry exists. This
can be bypassed with the command:
set ssl-auth-bypass-entry-check = TRUE;
In this case, when authenticating the client, the DSA will not check that an entry
with a distinguished name matching the subject field in the certificate of the
client exists in the directory.
Distributed User Authentication
A user can bind to one DSA when their entry is held on another DSA. When the
bind is made, the DXserver can forward a check to another DSA when certain
distributed authentication parameters are set.
During simple authentication, the local DSA can forward the password check to
a remote DSA only when the local DSA can make an authenticated connection to
the remote DSA. The remote DSA must have the correct trust-flags set in the
DSA definition.
For example, to enable the Democorp DSA to forward a password check on to
the UNSPSC DSA, the Democorp DSA must check its knowledge of the UNSPSX
DSA. If the UNSPSC knowledge file contains the trust flag allow-check-password,
then the Democorp DSA can pass the password compare request to the UNSPSC
DSA.
set dsa UNSPSC =
...
trust-flags = allow-check-password
...
bind request
DUA
bind response
Democorp
DSA
compare request
compare response
UNSPSC
DSA
If the DSA receiving the bind request passes a compare request of the password
value to the remote DSA, and this returns a compare confirm with assertion true,
then the DSA returns a bind-confirm to the user.
6–16
Authentication
DSP Simple Authentication
DSP and DISP binds are subject to the min-auth setting. This means that if the
local DSA has enabled authentication, an incoming DSP or DISP bind request
must have valid bind credentials.
Authenticated DSP binds use mutual authentication. During the bind process,
each DSA supplies its own credentials to the other DSA, and each DSA also
checks the credentials supplied to it by the other DSA.
Credentials Used During DSA Binds
An incoming bind is accepted only when there is a DSA knowledge
configuration that meets all the following conditions:
■
The distinguished name of the credentials matches the remote DSA dsaname.
■
The password in the credentials matches the remote DSA password.
■
The address of the binding DSA matches the address of the remote DSA.
We recommend that the DSAs in a DSP-meshed network share the same group
knowledge configuration file so that all the combinations of names and
passwords are known to each DSA.
See Managing DSP in the chapter “Distribution and DSP” for more information
about sending credentials with a DSP bind request.
Security
6–17
Authentication
How Mutual Authentication Works
This section describes the mutual authentication process.
1.
The DSA sending the bind request includes its credentials with the bind
request. It gets these credentials from its own knowledge file.
2.
The DSA receiving the bind request checks the credentials against its
knowledge of the sending DSA.
In this example, the UNSPSC DSA receives a bind request from the
Democorp DSA, and checks its credentials:
set dsa Democorp =
...
dsa-name = <c CA><o UNSPSC<>cn DXserver>
dsa-password = …
address = …
...
Democorp
DSA
bind request
UNSPSC
DSA
3.
The DSA that received the bind requests now sends a bind response back,
including its own credentials in this bind response.
4.
The DSA that sent the bind request checks the credentials of the other DSA
against its knowledge of the other DSA.
In the following example, the UNSPSC DSA receives a bind response from
the Democorp DSA, and checks its credentials:
set dsa UNSPSC =
...
dsa-name = <c CA><o UNSPSC<>cn DXserver>
dsa-password = …
address = …
...
Democorp
DSA
5.
6–18
bind response
UNSPSC
DSA
If all the credential checks match, the bind succeeds.
Authentication
DSP SSL Authentication
To enable SSL authentication between DSAs, the auth-levels flag of the receiving
DSA must include the value ssl-auth.
If you simply want DSA-to-DSA connections to be encrypted, SSL authentication
is unnecessary. Instead, set the link-flags element in the DSA knowledge to sslencryption.
How DSP SSL Authentication Works
This section describes the DSP SSL authentication process.
1.
The DSA sending the bind request checks its own knowledge file to
determine if it can use SSL.
2.
The sending DSA then checks the knowledge file of the receiving DSA to see
if it can accept an SSL connection. If it cannot, the bind attempt is aborted. If
it can, the DSA sends the SSL bind request.
In this example, the Democorp DSA finds the ssl-auth flag in its copy of the
UNSPSC knowledge file, so it sends the SSL bind request:
set dsa UNSPSC =
…
auth-levels = ssl-auth
…
DemoCorp
DSA
BIND
UNSPSC
DSA
DISP Authentication
DISP authentication is controlled by the DISP agreement. See DISP Agreements
in the chapter “Replication” for more information about DISP agreements.
Depending on the setting of auth-level in the agreement, the authentication
method follows the DSP simple or DSP SSL procedures outlined previously.
Security
6–19
Authentication
Bypassing Mutual Authentication
In the case of simple authentication, DSAs always exchange name and password
if configured. Not all third party DSAs or LDAP servers support the returning of
credentials on bind confirm. You can set a trust flag in the knowledge file of the
third-party DSA to bypass the return credentials check:
set dsa UNSPSC =
…
trust-flags = no-server-credentials
…
DemoCorp
DSA
BIND
RESPONSE
UNSPSC
rd
3 PARTY
DSA
In the case of SSL authentication, certificates are always exchanged and the
subject DN is always checked against the DSA name in the knowledge
configuration file. You cannot bypass mutual authentication when using SSL
authentication.
6–20
Authentication
Conveying User Authentication
In a networked system of DSAs, a user can bind to a DSA, and then request
information that is held on another DSA.
You can use the trust-conveyed-originator flag to allow the first DSA to convey the
user’s authentication to the second DSA.
How User Authentication Is Conveyed Between DSAs
1.
A user binds to a DSA. The bind request includes the user’s DN, and the
user’s credentials.
2.
The DSA authenticates the user.
3.
The user makes another request which the current DSA cannot fulfill.
4.
The DSA passes the request to another DSA that will be able to fulfill the
request. The request includes the user’s DN and authentication
5.
The receiving DSA must decided whether to trust the user’s authentication.
To do this, it looks at the knowledge file of the first DSA for the trustconveyed-originator flag.
6.
If the receiving DSA finds the trust-conveyed-originator flag, it accepts the
request. Even though the user was authenticated on Democorp, it will be
treated as if it had been authenticated on UNSPSC.
7.
The receiving DSA uses the DN of the originating user to determine what
access controls to apply to the request.
In this example, the UNSPSC DSA trusts the user authentication of the request
that has been passed to it by the Democorp DSA:
set dsa DemoCorp =
…
trust-flags = trust-conveyed-originator
…
DUA
OP
DemoCorp
DSA
OP
UNSPSC
DSA
Security
6–21
Authentication
DSP Link Authentication
Traffic on any link is generally carried at the same security level. That is:
■
High security—SSL authentication is carried on an SSL bind
■
Medium security—simple authentication is carried on a simple bind
■
Low security—anonymous authentication is carried on an anonymous bind
SSL authentication
DSA
Simple authentication
DSA
No authentication
Possible Problems with Link Authentication
This can present problems if a user makes a successful simple bind to a directory,
but is refused any distributed operations because all distributed links have a
minimum authentication level of ssl-auth.
Similarly, a user might make a successful SSL authenticated bind to a directory,
only to be refused distributed operations because the distributed directories
cannot support SSL authentication.
In either case, the error reported is “No compatible link type.”
Possible Solutions to the “No compatible link type” Error
One solution is to change the “auth-levels” so that a compatible DSP link can be
established.
Another solution is to either upgrade or downgrade the trust levels on the link
between distributed DSAs. A user who makes a successful simple bind can be
upgraded to allow distributed operations over an SSL link; a user who makes a
successful SSL bind can be downgraded to allow distributed operations over an
anonymous or simple link.
This should not be undertaken lightly. The only reasonable use is to permit
unauthenticated DSA links within the one organization (or on the one host), or to
grant access to a public server. You can use downgrading and upgrading on
inter-office links, but the use of encryption should suffice.
6–22
Authentication
Examples: Upgrading and Downgrading the Link Type
The following example demonstrates the upgrade of anonymous bind user on a
simple link between a Democorp DSA and a UNSPSC DSA:
set dsa UNSPSC =
…
trust-flags = allow-upgrading
…
DUA
anon
DemoCorp
DSA
simple
UNSPSC
DSA
The following example demonstrates the downgrade of an SSL bind user on a
simple link between a Democorp DSA and a UNSPSC DSA:
set dsa UNSPSC =
…
trust-flags = allow-downgrading
…
SSL
DUA
DemoCorp
DSA
simple
UNSPSC
DSA
Impersonation Protection
DSA authentication is completely separate from DUA authentication. This means
that a DUA cannot gain access using the credentials of a DSA, and a DSA cannot
gain access using the credentials of a DUA.
DSA authentication checks network addresses and credentials. This makes it
difficult for one DSA to impersonate another DSA.
Security
6–23
Managing Passwords
Managing Passwords
A policy is a set of rules that defines behavior.
In eTrust Directory, you can define a policy for passwords. This password policy
controls the password that users enter to bind to a DSA.
There are two kinds of password rules:
■
Password quality checking rules
■
Password management rules
Password quality checking rules define the quality of a new password. The
rules are applied when a user changes their own password. The rules include:
■
Setting the length of the password:
■
Setting the minimum number of particular types or characters:
■
Limiting repetition within the password:
■
Preventing the user from including their own user name in the password
■
Preventing the user from re-using a recent password
Password management rules define how to deal with passwords during
operation, including:
■
Life span of passwords
■
Suspending user accounts manually
■
Locking user accounts after incorrect login attempts
■
Resetting passwords
■
Grace logins after the password has expired
How Password Rules Are Applied
Password rules (except vetting checks) are only applied when operations are
being performed by the user that owns the password. For example, if an
administrator updates the password then no history check will occur. This
effectively resets the password.
Each DSA can have a single set of password rules. You cannot apply different
password policies to users stored within the same DSA.
You can apply different policies to different groups of users by splitting the users
up by sub-tree and having each sub-tree serviced by a separate DSA. Each DSA
can then have its own set of password policies.
6–24
Managing Passwords
Password Protection
You cannot read passwords directly. An attempt to read a password attribute
results in the return of the encrypted value. See Password Storage in the chapter
“General Administration” for more information about encryption algorithms.
Passwords are always single-valued. This means that an administrator cannot
add a secret value and use this as an unpublished entry point into the DSA.
Passwords are encrypted before they are stored in the database. This prevents
the possibility of interrogating the database directly for the value of any
passwords.
Password logins are secure only if each person can change only their own
password. Make sure that you set access controls so that each user can update
only their own password. Also make sure that administrators are allowed to
update any user password.
Password Command Options
The following table briefly describes each of the password settings. The default
for most values is 0, which means that the option is off:
Keyword
Parameter
Description
password-age
Number of days | 0
(Default: 0)
The number of days for which a password will
remain valid
See the section Setting the Life Span of Passwords.
password-allow-ignoreexpired
True | False
(Default: False)
The password-allow-ignore-expired option bypasses
the expiration check of the password.
This only takes effect for entries that include the
attribute dxPwdIgnoreExpire.
See the section Setting Passwords to Never Expire.
password-allow-locking
True | False
(Default: False)
Allows a user’s account to be locked.
attribute dxPwdLocked.
See the section Locking an Account after Incorrect
Login Attempts.
password-alpha
Num. chars | 0
(Default: 0)
The minimum number of alphabetic characters in the
password
See the section Checking Password Quality .
Security
6–25
Managing Passwords
Keyword
Parameter
Description
password-alpha-num
Num. chars | 0
(Default: 0)
The minimum number of alphanumeric characters in
the password
password-force-change
True | False
(Default: False)
Forces users to change their passwords after their
passwords have been reset
See the section Forcing Password Changes after
Reset.
password-grace-logins
Number of logins | 0
(Default: )
The maximum number of times that the user can
log in with their password after it has expired
See the section Setting the Number of Grace Logins.
password-history
Number of entries | 0
(Default: 0)
The maximum number of entries to retain in the
history. This prevents the user from re-using these
passwords.
See the section Preventing Users from Re-using
Passwords.
password-last-use
Number of days | 0
(Default: 0)
The number of days a password remains valid if it
is not used. If the value is exceeded, the password
expires.
See the section Setting the Maximum Life Span of
Passwords.
password-lowercase
Num. chars | 0
(Default: 0)
The minimum number of lowercase characters in the
password
password-max-length
Num. chars | 0
The maximum length of the password
password-max-repetition
Num. chars | 0
(Default: 0)
The maximum number of single characters that can
be repeated in a password
password-max-substringrepetition
Number of reps | 0
(Default: 0)
The password-max-substring-repetition option sets
the maximum repetitions of a substring within a
password
password-max-suspension
Number of secs | 0
(Default: 0)
The number of seconds after which a locked
password reactivates
Login Attempts.
6–26
Managing Passwords
Keyword
Parameter
Description
password-min-age
Number of days | 0
(Default: 0)
The number of days since a password was changed
until it can be changed again
See the section Setting the Minimum Life Span of
Passwords.
password-min-length
password-min-lengthrepeated-substring
Num. chars | 0
(Default: 6)
The minimum length of a password
Integer ≥2 | 0
(Default: 0)
The password-min-length-repeated-substring option
sets the minimum length of substrings that will be
checked.
attribute maxSubstrRep.
password-non-alpha
Num. chars | 0
(Default: 0)
The minimum number of non-alphabetic
characters in the password
password-non-alpha-num
Num. chars | 0
(Default: 0)
The minimum number of non-alphanumeric
characters in the password
password-numeric
Num. chars | 0
(Default: 0)
The minimum number of numeric characters in the
password
password-policy
True | False
(Default: False)
Enable password management
password-retries
Integer | 0
(Default: 0)
The number of consecutive failed logon attempts
before a password is locked
Login Attempts.
password-uppercase
Num. chars | 0
(Default: 0)
The minimum number of uppercase characters in the
password
password-usernamesubstring
True | False
(Default: False)
The password-username-substring option sets
whether the password can contain the user’s RDN
When this is set to true, the password must not
contain the user’s last RDN.
Security
6–27
Managing Passwords
Enabling or Disabling Password Management
Even if you have other password options set, they will only take effect if you set
the password-policy option to true.
To enable or disable password management, set the following option:
set password-policy = true | false;
Checking Password Quality
You can set up rules to make sure that users only choose strong passwords.
If you have set rules about password quality, these rules are applied when a user
attempts to change their own password. If the new password does not pass the
tests, the user will have to try again with a new password.
When an administrator changes a password for a user, the password policy rules
are not applied. The rules will be applied the next time that the user changes
their own password.
Set the length of the password:
set password-min-length = number-of-characters | 0;
set password-max-length = number-of-characters | 0;
Set the minimum number of particular types of characters:
set
set
set
set
set
set
password-alpha = number-of-characters | 0;
password-alpha-num = number-of-characters | 0;
password-lowercase = number-of-characters | 0;
password-non-alpha = number-of-characters | 0;
password-non-alpha-num = number-of-characters | 0;
password-numeric = number-of-characters | 0;
Limit repetition within the password:
set password-max-repetition = number-of-characters | 0;
set password-max-substring-repetition = number-of-characters | 0;
set password-min-length-repeated-substring = number-of-characters | 0;
Note: The password-min-length-repeated-substring option only affects those users
whose entries include the attribute maxSubstrRep.
Prevent the user from including their own user name in the password:
set password-username-substring = true | false;
6–28
Managing Passwords
Setting the Life Span of Passwords
Use the following commands to control password expirations.
Setting the Maximum Life Span of Passwords
Set the number of days for which a password will remain valid:
set password-age = number-of-days | 0;
Set the number of days a password remains valid if it is not used. If the value is
exceeded, the password expires:
set password-last-use = number-of-days | 0;
Example: Making
passwords valid
indefinitely
You want passwords to be valid indefinitely except when they are not used for
30 days. Set the parameters as follows:
set password-policy = TRUE;
set password-last-use = 30;
You do not need to use the set password-age option because you are using its
default value of 0 (off).
Setting the Minimum Life Span of Passwords
You can also set the minimum life span of a password. This is the number of
days since a password was changed until it can be changed again.
You can use this to prevent people from changing their password many times to
fill up the password history. To do this, use the following command:
set password-min-age = number-of-days | 0;
Setting Passwords to Never Expire
Accounts can be made to never expire. This is useful for accounts shared by
many users. To set a user’s password to never expire:
1.
Set the password-allow-ignore-expired option to true:
set password-allow-ignore-expired = true;
2.
Add the attribute dxPwdIgnoreExpire to the user’s entry.
To check which user passwords are set to never expire:
■
Search for all user accounts with the attribute dxPwdIgnoreExpire.
You can only find out if entries have this attribute by searching for it
explicitly.
Security
6–29
Managing Passwords
Setting the Number of Grace Logins
In a grace login system, passwords expire but users can use an expired password
for limited number of times. This gives them the opportunity to change the
password.
If the number of grace logins is exceeded, the account will behave as if it were
expired.
The number of grace logins remaining will be sent back to the binding client in
the presence of the password policy request control.
To set the number of grace logins, use the following command:
set password-grace-logins = number-of-grace-logins | 0;
Resetting a Password
Whenever an administrator updates a user password, the password policy
attributes for that entry are reset. These attributes include:
■
Any password history
■
The time of the last use of the password
■
The time the password was created
For example, if password-age is set to 30 days and a user has not logged in for
more than 30 days, the administrator can update that user's password to enable
that user to log in again.
Forcing Password Changes after Reset
You can force users to change their passwords after their passwords have been
reset. To do this, use the following command:
set password-force-change = true;
When a user logs in with their new password, the only operation the user can
perform is to change their password. After the user has changed their password,
their normal operations are restored.
This password control can only be used with LDAP clients that are aware of
LDAP password policy controls (for example, LDUA and the PAM-LDAP client).
6–30
Managing Passwords
Locking an Account after Incorrect Login Attempts
You can set accounts to be locked if someone has made too many unsuccessful
attempts to log in. To set accounts to be locked after a certain number of
attempts to log in, use the following command:
set password-retries = number-of-attempts;
To allow users to attempt to log on again after a certain amount of time has
passed, use the following command:
set password-max-suspension = time-in-seconds | 0;
Example:
Limiting the number
of logon attempts
You want to allow users attempt to log on only two times before their account
is locked, and you want to allow them to try to log on again after six hours. To
do this, use the following commands:
set password-policy = TRUE;
set password-retries = 2;
set password-max-suspension = 21600;
Suspending an Account Manually
You can suspend a user’s account manually by locking their password. You can
later remove the suspension, and the user can continue to use that password.
Note: This only works with LDAP clients that are aware of LDAP password
policy controls (for example, LDUA and the PAM-LDAP client).
To suspend a user’s account, you need to do the following:
1.
Set access controls as required (see the other sections in this chapter).
2.
Enable password locking. To do this, use the following command:
set password-allow-locking = true;
3.
Lock the user’s password. To do this, add the attribute dxPwdLocked to the
user’s entry.
To unlock the account:
■
Remove the attribute dxPwdLocked from the user’s entry.
Do not set the value to 0. If this attribute is present, the account will still be
locked.
To check which user accounts are locked:
■
Search for all user accounts with the attribute dxPwdLocked.
The only way to find out if entries have this attribute if you search for it
explicitly.
Security
6–31
Managing Passwords
Preventing Users from Re-using Passwords
Set the maximum number of entries to retain in the history. By default, this
feature is disabled (0). If you do not want to check a changed password against
old passwords, set the value to 0:
set password-history = maximum-number | 0;
Some Password Controls Require an LDAP Client
Some password controls can only be used with LDAP clients that are aware of
LDAP password policy controls (for example, LDUA and the PAM-LDAP client).
This section of the eTrust Directory password policy follows the proposed
standard described in section 5 of this draft document:
http://www.ietf.org/internet-drafts/draft-behera-ldap-password-policy-07.txt.
Note: This document may be renamed in the future.
PasswordPolicyResponseValue ::= SEQUENCE {
warning [0] CHOICE {
timeBeforeExpiration
[0] INTEGER (0 .. maxInt),
graceLoginsRemaining
[1] INTEGER (0 .. maxInt) } OPTIONAL,
error
[1] ENUMERATED {
passwordExpired
(0),
accountLocked
(1),
changeAfterReset
(2),
passwordModNotAllowed
(3),
mustSupplyOldPassword
(4), <== Not required (handled by bind)
insufficientPasswordQuality
(5),
passwordTooShort
(6),
passwordTooYoung
(7),
passwordInHistory
(8) } OPTIONAL }
timeBeforeExpiration and graceLoginsRemaining are provided where
appropriate. For example, password policy must be enabled in DXserver.
Account Management
The following command does not require the control but is handy for informing
the user:
set password-allow-locking = true or false;
This feature requires the control
set password-force-change = true or false;
6–32
Managing Passwords
Example Password Policy
This section describes a sample password policy, and then lists the commands to
create that policy.
For this policy, you want to set up the following rules:
■
■
■
■
Passwords can be reused. You do not want to keep a history of old
passwords.
A password must be at least eight characters in length with at least one
numeral.
If a user’s password is ever reset, you want the user to change the password
immediately after their first login.
If a password is not used for sixty days, you want the account to be locked.
To set up this policy, set the following password rules:
set
set
set
set
set
password-policy = true;
password-min-length = 8;
password-numeric = 1;
password-force-change = true;
password-min-age = 60;
Security
6–33
Access Control Overview
Access controls protect data from unauthorized access or modification.
Access controls work by asking this question before performing an operation:
Is this client permitted to perform this operation, on this data, in this subtree, at
this time?
where:
-
A client is a user, a role, a group of users, or a subtree of users.
-
An operation is one of the usual directory services, such as compare, list,
search, read, add, remove, modify, or modify-dn.
-
The data (protected item) is an entry, attribute, or attribute value.
-
A subtree is a particular area of the DIT.
-
The time is a particular minute of the day or a particular day of the week.
When the answer to this question is yes, the operation can proceed. When the
answer is no, the operation is refused.
Access Control Policies
A number of access controls are usually in place. The net effect is known as an
access control policy. By definition, only one access control policy is in place at any
given time.
An access control policy can change periodically, for example, there can be one
for business hours and another for after hours. You can set the DXserver access
controls to activate at certain times, so a single policy could contain different
rules for different times of the day or week.
To define your access control policy, you define a set of rules access control.
During operation, DXserver maps these rules onto 1993 X.500 access controls.
6–34
Access Control Rules
DXserver manages access controls by letting you define rules. There are two
types of rules:
Static rules—These apply to individuals and groups of individuals, and are
stored as text files in the DXserver configuration files, or run as commands
on DXconsole.
Dynamic rules—These are stored in an attribute in the directory, and can be set
by anyone who has the power to delegate the permissions being created.
In addition, eTrust Directory lets you define users groups and roles, which can
help you apply access controls to many users at once.
Important! The 1993 X.500 access controls are not exposed directly; rather they are
defined by rules. This is because the 1993 X.500 Access Controls are difficult to
understand (defining such things as userFirst, itemFirst, precedence, protectedItems, and
so on) and because the definitions of DXserver rules are mathematically proven not to
have security loopholes.
Designing Your Access Control Scheme
We recommend that you use these principles while you are developing your
access control scheme:
■
Plan your access control scheme before you start implementing it
■
Use domains to limit the range of your access controls
■
Grant access rather than denying access
■
Keep access control schemes simple
Plan Your Access Control Scheme
Before you start setting access controls, plan your access control scheme. To do
this, write your scheme out carefully. Here is an example of a set of access
control rules written in plain language:
■
The DSA manager has all privileges.
■
Authenticated users can update their own entries.
■
PABX operators can update all telephone numbers.
■
■
Public (anonymous) users can view only name, e-mail addresses, and
telephone numbers of staff, but they can view anything in the public subtree.
Passwords must be invisible to everyone except DSA administrators.
Security
6–35
Use Domains to Limit the Range of Access Controls
A static access control policy can apply to a single DSA, or a group of DSAs that
share the same (or have copies of) group configuration files.
Sharing the same access control configuration across many (or all) DSAs makes
administration easier, and enables access-controlled routing.
Grant Access Rather than Denying Access
In general, you should grant rather than deny access to data.
If you grant access to all data and then deny access to portions of the data,
sensitive data that you have protected can become visible inadvertently.
For example, when items within a subtree are protected and the root of the
subtree (or a parent) is renamed, the protection no longer exists. Any new
attributes are also automatically visible, unless specific denials are implemented.
Keep Access Control Schemes Simple
You should design your access control scheme to be as simple as possible. This
might involve re-designing your DSAs.
This is important because overly complex access control scheme can lead to the
following problems:
Security breaches—If you define many different groups with different subtrees,
you must maintain careful control of valid users and subtrees. If you lose
track of valid users and subtrees, this will eventually cause a security
problem.
Performance—Complex access control schemes can result in performance
degradation. This is because the DSA may need to evaluate every control for
every piece of information returned, depending on the circumstance and
privileges of the user in question.
6–36
Working with Access Controls
Enabling Access Controls
1.
Enable access controls:
2.
Set static or dynamic access control rules.
Clearing Access Controls
To reset all access controls, use the following command:
clear access;
Displaying Access Controls
To display the 1993 X.500 access control details, use the following command:
get access;
For full details of access controls, see the 1993 X.500 standard
Security
6–37
Static Access Controls
Static access controls are applied to individuals or groups of individuals.
Overview of Static Access Control Rules
This section describes static access controls and how they work
Static Rule Components
A static access control rule can include the following information:
■
The rule type
■
Which user, groups, or roles it applies to
■
Which area of the directory it applies to
■
What attributes it applies to
■
What additional permissions it gives
■
What authentication level it requires
■
When it applies
Because all rules are cumulative, you can define very complex access control
polices.
Hierarchy of Rules
The static access control rules have a hierarchy of power. Here are the rules listed
from superior to inferior:
■
Superuser
■
Administrative user
■
Protected item
■
Registered user
■
Public user
A superior rule always overrides an inferior user rule. For example, a superuser
rule always overrides any administrative user rule.
6–38
Rule Inheritance
Rules are inherited:
Grants are inherited above
If a grant is defined for a given level, then all levels above inherit that grant.
For example, if all registered users are granted read/write permission to
their password, then superusers and administrative users are granted the
same permission automatically.
Denies are inherited below
If a deny is defined for a given level, then all levels below inherit the deny.
For example, if a registered user is denied access to home address, then all
public users are denied the same.
Running Static Access Control Commands
You can run access control commands from DXconsole, or you can include them
in a DXserver configuration file (.dxc) in the access directory.
If you issue these commands using DXconsole, the commands are not stored in
the configuration files. This means that they are only valid for the run-time of the
DSA.
If you include static access control rules in the DXserver configuration file, they
are activated when DXserver is initialized. This occurs when DXserver starts up,
and when an administrator reinitializes the system.
Generally, you group these files together by using a group configuration file
(.dxg), which constitutes an access control policy. You can share policies among a
number of DSAs.
Security
6–39
Setting Up Static Access Controls
This section shows the command for setting access control rules, and describes
the options you can use with these rules.
The command for setting static access control rules has the following format:
set rule-type tag = {
own-entry | user = DN | role = DN | user-subtree = DN | group = string
DN
subtree
=
attrs
=
attr1 [, attr2 ...]
perm1 [, perm2 ...]
perms
=
auth-level =
simple | ssl-auth
validity
=
start hhmm end hhmm on daystring
};
where:
rule-type
Defines the action of the set command. These actions include:
super-user
Grants unlimited access to particular users.
admin-user
Grants read and update privileges to particular users.
reg-user
Grants read privileges to particular users.
public-user
Grants read privileges to all users
protected-items
Protects a subtree, entry, or attribute.
tag
A human-readable name for the access control rule.
Defines the users that this rule applies to, with the following possible values:
own-entry
A user’s own entry
user = DN
A user’s distinguished name
role = DN
A role’s distinguished name
user-subtree = <DN>
The distinguished name of a user-subtree
group = string
The name of a predefined group of users
subtree
Defines the part of the directory to which the rule applies, with the following
possible values:
6–40
entry = <DN>
The distinguished name of an individual entry
subtree = <DN>
The distinguished name of a user-subtree
attrs
Defines the attributes to which you want to limit access.
You can give the name of an attribute set in place of the attribute name. See
Attribute Sets in the chapter “Schema Definition” for more information.
perms
Applies permissions to a particular rule type, with these possible values:
read
Permits the user to read the defined attributes or entries. The other
permission levels all include read access.
add
Permits the user to add new defined attributes or entries
remove
Permits the user to delete the defined attributes or entries
modify
Permits the user to modify the defined attributes or entries
modify-dn
Permits the user to modify the DN the defined attributes or entries
rename
Permits the user to rename the defined attributes or entries
all
Permits the user to carry out all operations on the defined attributes or
entries
auth-level
Defines the authentication level at which the user must bind. The following
table lists the available values:
simple
(Default) The user must bind using simple authentication
ssl-auth
The user must bind using SSL authentication
validity
Defines the times when the rule applies. The following table lists the
available values:
start
Is the time at which this rule becomes valid
end
Is the time at which this rule is no longer valid
on
Is a string that defines the days on which this rule is valid. Each day of
the week is represented by a number, starting with 1 for Monday. For
example, 45 represents Thursday and Friday. The default is any time.
Security
6–41
Defining Superusers
Superusers have unrestricted read and update access to all parts of the DSA. Add
users to the list of superusers either as single users, groups of users, roles, or all
users in a specified subtree.
The command has the format:
set super-user tag = {
[auth-level =
simple | ssl-auth ]
[validity
=
start hhmm end hhmm on daystring ]
};
where:
tag
(Optional) Is the name you define for this rule
Identifies the user, group, or subtree of users that is to have superuser access
auth-level
(Optional) The authentication level at which the listed users must bind
validity
(Optional) Is the days and times on which this rule is valid
Example: Adding
Superusers
The following command defines a single user with superuser privileges across
the domain of the Democorp DSA:
set super-user “dsa-manager” = {
user = <c “AU”><o “Democorp”><commonName “DSA manager”>
};
Example: Being a
Superuser of One’s
Own Entry
The following command gives all users in the domain of this DSA superuser
privileges on their own entry from 0800 hours to 1800 hours on Monday to Friday:
set super-user “self” = { own-entry
validity = ( start 0800 end 1800 on 12345 ) };
When you include this command in an access.dxc file that multiple DSAs
source, all users in the domains of those DSAs will have superuser privileges on
their own entries.
This is the only type of superuser rule that does not grant the user access to all
parts of the DSA,
6–42
Defining Administrative Users
Within a specified subtree, you can assign administrator authority to users.
Administrative users have read and update privileges over a specified
administrative scope. This scope is a subtree, entry, or designated attributes in an
entry or subtree. The administrative user can view and update protected items
within the administrative scope.
Add users to the list of administrative users either as single users, groups of
users, roles, or all users in a specified subtree.
Note: Administrative user definitions are effective only when you enable access
controls. An administrator with access to only selected attributes within a subtree
cannot add or remove entries.
set admin-user tag = {
DN
subtree
=
[ attrs
=
attr1 [, attr2 …] ]
perm1 [, perm2 ...] ]
[ perms
=
[ auth-level =
simple | ssl-auth ]
[ validity =
};
where:
tag
Identifies the user, group, or subtree of users that are to be administrative
users
subtree
Contains a list of the distinguished names of one or more subtrees that the
listed users can administer
attrs
(Optional) Restricts update permissions to only those attributes listed. Users
cannot delete any entry if attributes are listed here.
perms
(Optional) Contains the level of permission that this rule grants to the listed
users over the listed subtree
auth-level
validity
Security
6–43
Example: Adding
Administrative Users
In the following example, there is one specified subtree: AU/DemoCorp. This
subtree has administrators defined by the group admin-user-group.
set admin-user “administrators” = {
group = “admin-user-group”
subtree = <c “AU”><o “DemoCorp”>
};
Example: Allowing
Update Privileges on
a Role
In the following example, all users in the role project-leader-group have read and
update privileges on the entry AU/DemoCorp/R&D/Technology SIG if they
bind to the DSA using SSL authentication.
set admin-user “project-leaders” = {
role = <c “AU”><o “Democorp”><ou “roles”><cn “project-leader-group”>
entry = <c “AU”><o “DemoCorp”><ou “R&D”><listName “Technology SIG”>
auth-level = ssl-auth
};
Example: Allowing
Update Privileges on
a Single Attribute
In the following example, all users in the group pabx-mgmt-group have update
privileges on the attribute workPhone in the subtree AU/Democorp/R&D.
Example: Allowing
Users Update
Privileges on Specific
Attributes in Their
Own Entry
In the following example, all users in the subtree AU/Democorp/R&D have
update privileges on the attributes workPhone and description in their own entry.
6–44
set admin-user “work-phone” = {
group = “pabx-mgmt-group”
subtree = <c “AU”><o “DemoCorp”><ou “R&D”>
attrs = workPhone
};
set admin-user “my-own-work-details” = {
own-entry
subtree = <c “AU”><o “DemoCorp”><ou “R&D”>
attrs = workPhone, description
};
Defining Registered Users
In a specified subtree, you can assign users the authority of a registered user.
Registered users have read privileges over a specified scope: a subtree, entry, or
the designated attributes in an entry or subtree. Protected items in the scope are
invisible.
Note: Registered user definitions are effective only when you enable access
controls.
set reg-user tag
= {
DN
subtree
=
[ attrs
=
perm1 [, perm2 ...] ]
[ perms
=
[ auth-level =
simple | ssl-auth ]
[ validity =
};
where:
tag
Contains a list of the distinguished names of the users, groups of users, roles,
or all users in a specified subtree that are to be registered users
subtree
listed users can read
attrs
(Optional) Contains a list of attributes for which the listed users have the
permissions listed in the perms parameter.
perms
(Optional) Contains the level of permission that this rule grants to the listed
users over the listed attributes
auth-level
validity
Example: Adding
Registered Users
In the following example, all the users in the subtree AU/DemoCorp/R&D can
read the subtree AU/DemoCorp.
set reg-user “R&D-Users”= {
user-subtree = <c “AU”><o “DemoCorp”><ou “R&D”>
};
Security
6–45
Example: Allowing
Read Privileges on an
Entry
In the following example, all users in the group staff have read privileges on the
entry AU/DemoCorp.
Example: Allowing
Read and Modify
Privileges on a
Number of Attributes
In this example, all DemoCorp users can browse all entries in the subtree
DemoCorp; however, when they read or search for an entry in the subtree, only
those attributes that you declare are visible. The users also have modify
privileges on the listed attributes for all entries in the subtree.
set reg-user “democorp-staff” = {
group = “staff”
entry = <c “AU”><o “DemoCorp”>
};
set reg-user “self-view” = {
user-subtree = <c AU><o DemoCorp>
attrs = telephoneNumber, commonName, surname, title, mhsORAddresses, dcEmail
perms = modify
};
Example: Allowing
Users Read Privileges
on Particular
Attributes in Their
Own Entry
The following example lets any user in the subtree AU/DemoCorp view only
the selected attributes in their entry.
set reg-user = {
own-entry
attrs = telephoneNumber, commonName, surname, title, mhsORAddresses, odEmail
};
This differs from the previous example where all users in the subtree
DemoCorp can view all entries in that subtree.
6–46
Defining Public Users
You can make specific subtrees available to public (anonymous) users.
Public users have read-only access to all entries and attributes within the
specified public range. This range is a subtree, entry, or the designated attributes
in an entry or subtree.
Any permission granted to public users is also automatically granted to
authenticated users. Protected items within the specified public range are
invisible to public users.
Note: Public user definitions are effective only when you enable access controls.
Public ranges are made available to public users with the following command:
set public-user
subtree
[ attrs
[ perms
[ validity
};
tag
=
=
=
=
= {
DN
perm1 [, perm2 ...] ]
where:
tag
subtree
Contains a list of the distinguished names of one or more subtrees that all
users can read
attrs
(Optional) Contains a list of attributes for which all users have the
permissions listed in the perms parameter.
perms
(Optional) Contains the level of permission that this rule grants to all users
over the listed attributes
validity
Example: Adding a
Public Subtree
In the following example, all users can view the name, telephone number, and
X.400 mail addresses in the subtree AU/DemoCorp/Phone List. The access
control rule is tagged with the name public-attr.
set public-user “public-attr” = {
subtree = <c “AU”><o “DemoCorp”><ou “Phone List”>
attrs = telephoneNumber, commonName, surname, mhsORAddresses
};
Security
6–47
Protecting Items
You can protect specific subtrees, entries, or particular attributes in a subtree or
entry. For a protected item:
■
■
■
Superusers have read and update privileges
Administrative users have read and update privileges if the subtree is in the
user’s administrative area
Other users do not see the items
Some limitations on this command:
■
■
■
This command does not protect naming attributes.
If you rename a protected subtree or entry, or any of its parents, the
permissions rule no longer protects the item.
Protected item definitions are effective only when you enable access controls.
The command that protects items has the following format:
set protected-items tag = {
DN
subtree
=
[ attrs
=
perm1 [, perm2 ...] ]
[ perms
=
[ validity =
};
where:
tag
Contains a list of the distinguished names of the users, groups of users, roles,
or all users in a specified subtree that are to be registered users
subtree
listed users can read
attrs
(Optional) Contains a list of attributes for which the listed users have the
permissions listed in the perms parameter
perms
(Optional) Contains the level of permission that this rule denies to the listed
users over the listed attributes.
Unlike the other access control commands, any permissions listed in the set
protected-items command are denied.
validity
Is the days and times on which this rule is valid
6–48
Protecting Entries and Subtrees
There is a subtle difference between protecting entries and protecting subtrees.
When you protect an entry, neither a registered, nor public user can read it. It
can, however, appear in a list result if the user can access the parent. This occurs
because the protected entry may have subordinates that are visible to the user.
If the same entry has protection as a subtree, a registered or public user cannot
read it, and it does not appear in a list result as a subordinate entry.
Protecting Passwords
Protecting a password makes the password attribute invisible to unauthorized
users. Because authentication requires the name of an entry, and that entry must
contain a password, hiding the password makes login entries indistinguishable
from other entries.
Examples of set protected-items Commands
Example: Protecting
a Subtree
Protecting a subtree from registered users also makes it invisible to public
users, as described in the section Hierarchy of Rules.
set protected-items “hide-finance-from-employees” = {
group
=
“employees”
subtree
=
<c “AU”><o “DemoCorp”><ou “Finance”>
};
Example: Protecting
an Entry
You could use the following rule to hide the existence of some management
information about a DSA definition stored within the directory:
set protected-items “hide-schema-from-employees” = {
group
=
“employees”
entry
=
<c “AU”><o “DemoCorp”><ou “Schema”>
};
Example: Protecting
Attributes
In this example, all entries in the subtree AU/DemoCorp have protection for
their homePhone and password attributes (if they have these attributes).
However, these attributes are visible to superusers and administrative users in
their scope.
set protected-items “hide-passwords-and-home-phone” = {
subtree
=
<c “AU”><o “DemoCorp”>
attrs
=
homePhone, userPassword
};
Security
6–49
Example: Giving a
User Permission to
Modify All Attributes
in Their Own Entry
Except "Role"
In this example, the reg-user rule gives the user permission to modify all
attributes in their own entry, and the protected-items rule denies the user
modification rights to the role attribute in the user’s own entry if it has a higher
precedence than the reg-user rule.
set reg-user = {
own-entry
subtree
=
perms
=
};
<o Democorp>
modify
set protected-items = {
own-entry
subtree
=
<o DemoCorp>
attrs
=
role
perms
=
modify
};
Without the "perms = modify" in the protected-items rule the user would be
denied all access to the role attribute (including read access).
Example: Allowing
users to view a whole
entry and modify
some attributes
A common task with access controls is to provide update access to most
attributes within an entry but to prevent the update of a small number of
attributes. This problem is more complex if the list of attributes that can be
updated can grow - for example, as more attributes are added to the entry.
■
Providing "reg-user" access to the entry will give read-only access.
■
Providing "admin-user" access will give update access.
■
Setting "protected-items" on some attributes will prevent updates, but not
by users with "admin-user" rights. It will also prevent reads by users with
"public-user" or "reg-user" rights.
A solution to this problem is to use the optional permissions in the access
control rules. The following access rule will allow all users in the subtree to
modify all attributes in their own entry.
set reg-user = {
own-entry
subtree = <o test>
perms = modify
};
To prevent update access to some of these attributes, use:
set protected-items = {
own-entry
subtree = <o test>
attrs = attr1, attr2, ...
perms = modify
};
This prevents the user modifying the attributes listed, but it does not prevent
read access. This is because the only permission denied is modify.
6–50
Dynamic Access Controls
Dynamic access controls enable run-time management of access controls. This is
useful for automated provisioning systems in ISP environments, and where the
directory is used as an authorization engine.
Dynamic access controls specify a subject (an identity or a role), a permission,
and a list of attributes that are the target of the control. They also contain a tag
that is transparent to DXserver. Adding a rule to the dxDynamicAccess attribute
in an entry creates the access control rule. The subtree in which dynamic access
controls are active is the local naming context; therefore, only attributes stored
locally are affected by access control decisions.
dxDynamicAccess is an operational attribute; it is not controlled by schema. Any
user can add, delete, or modify a rule, provided they have write access over the
subtree defined by the entry containing the dxDynamicAccess attribute, and the
privilege in the attribute is in the user’s power.
Important: In the configuration files, make sure that the database is defined (using "set
database=<database_name>") before the directory reads the "set dynamic-accesscontrol=true" directive.
This is because the "set dynamic-access-control=true" directive causes the directory to
perform a search on the database, so it needs to know the database name.
Note: Dynamic access controls are limited to local DSAs, which means that they
cannot be used in a distributed environment. This even applies to a router DSA
on the local computer.
Dynamic rules apply downwards from the entry in the DIT where the
dxDynamicAccess attribute is stored.
Enabling and Disabling Dynamic Access Controls
To enable dynamic access controls:
1.
Enable access controls:
2.
Enable dynamic access controls:
set dynamic-access-control = true;
To disable dynamic access controls, enter the following command:
set dynamic-access-control = false;
Security
6–51
Dynamic Access Control Rules
The rules governing dynamic access controls take the following form:
<tag> {all| roles <dn>| user <dn>} {read | write | deny} <attr>…
where tag is an identifier used for documentation purposes, dn is a distinguished
name, and attr is an attribute.
When creating rules, remember that a rule specified for a particular user prevails
over one specified for a role, and that both prevail over all. Also, when creating
the rule, the user or role need not exist.
Example: Letting all
read one attribute
The following command gives everyone permission to read the commonName
attribute. The tag Joe is to help you with maintenance and problem analysis;
DXserver does not interpret it.
Joe all read commonName
Example: Letting all
read all attributes
The following command gives everyone permission to read all attributes:
Example: Denying
permission for roles to
read an attribute
The following command denies the roles of CEO and AdminFinance within
Democorp access to the ssoHelicopter attribute:
Example: Letting one
user write to an
attribute
The following command lets a user with the common name Craig write to the
ssoHelicopter attribute:
6–52
Joe all read all
Joe role cn=ceo,o=Democorp deny ssoHelicopter
Joe user cn=Craig,o=Democorp write ssoHelicopter
Groups, Roles, and Proxies
This section describes how groups, roles, and proxies work.
Defining Groups of Users
You can define groups of users to make it easier to manage those users. Define
groups such that you can use it in other access control commands.
Note: Group definitions are effective only when you enable access controls.
set group tag
users
name
};
= {
DN1 [, DN2 …]
=
GroupName
=
where:
users
Is a list of the distinguished names of one or more users in the new group
name
Is the name you give to the group.
Example: Forming a
Group
The following command defines a group containing two users. The group is
named admin-user-group, suggesting that the users have administrative user
privileges.
set group = {
name
= "admin-user-group"
users = <c “AU”><o “DemoCorp”> <ou “Services”><ou “Networks”><cn “Anna
HAWKINS”>,
<c “AU”><o “DemoCorp”> <ou “Services”><ou “Networks”><cn Brendan
RANDALL”>
};
Security
6–53
Role-Based Access Controls
When access control rules are applied to a role, they are known as role-based
access controls.
A role is a directory entry that can be associated with user entries. These
associated user entries are member entries.
A role may contain any number of members. This can be useful in a large
distributed directory environment where people change their roles frequently,
and when the directory is to be used as an authorization engine.
Both static and dynamic rules support roles.
Roles are maintained in a subtree of the directory information tree (DIT), using
the object class groupOfNames. You can control access to the role subtree using
access controls.
How Role-Based Access Controls Work
When a user binds to DXserver, the user’s credentials are verified. A search is
initiated for the user’s distinguished name in the member attribute of any entry
with the object class groupOfNames. The name(s) returned by this search are
stored as the roles pertaining to the connection, and then used in access control
decisions.
Note: Role-based access controls are limited to local DSAs, which means that
they cannot be used in a distributed environment. This even applies to a router
DSA on the local computer.
Enabling and Disabling Role-Based Access Controls
To add a user entry to a role, enter the distinguished name of the user entry to
the role entry, as an attribute value of the member attribute type.
To activate role-based access controls, enter the following commands:
set role-subtree = <dn>;
set use-roles = true;
where dn is the distinguished name of the subtree used to store the roles.
To disable role-based access controls, enter the following command:
set use-roles = false;
6–54
Example: Activating
role-based access
control
In the following example, when a user binds to DXserver, DXserver searches
the member attribute of the entries with oc in the groupofNames in the subtree
c=au, o=Democorp, ou=Roles for that user’s distinguished name. The entries
which contain that member identify the roles of the member.
To activate role-based access controls:
set role-subtree = <c “au”> <o “Democorp”> <ou “Roles”>;
set use-roles = true;
Example: Add a new
role with two users
This example shows how to add the new role AdminFinance with the two
members, Noelene Correa and Linda Deacon.
add-entry-req
entry = <countryName "AU">
<organizationName "Democorp">
<organizationalUnitName "Roles">
<commonName "AdminFinance">
contents = {
(objectClass groupOfNames )
(member <c au><o Democorp><ou Clerical><cn "Noelene Correa">,
<c au><o Democorp><ou Finance><ou Budgets><cn "Linda Deacon"> )
Security
6–55
Secure Proxies
The secure proxy feature lets an authorized user (or process) impersonate a user
or role for whom it has responsibility, and bind to DXserver to elicit access
control decisions (for example, when the directory is used as an authorization
engine, such as a web server).
The proxy must bind to DXserver using certificate-based authentication. Those
users permitted to proxy (impersonate someone else) are identified to DXserver
as a list of distinguished names held in the trust-sasl-proxy list.
When using a proxy, the impersonating user can never obtain more power than
they already have. In other words, in assuming the identity of another user, they
may not obtain all the privileges of that user.
Once bound to DXserver, the proxy may change identity by changing the value
of dxProxyUser in the entry cn=roles to the distinguished name of the new
identity. This has the effect of evaluating the roles for the new identity. An
exception is, where the proxy also changes the value of dxProxyRole in cn=roles.
In this case, roles are taken directly from the attribute value, not by accessing role
entries in the directory.
The entry cn=roles is a magic entry, and does not appear in the DIT.
To permit the proxy to impersonate users not in the directory (external users),
the proxy replaces the value of the dxProxyUser attribute in the magic entry with
the distinguished name of the new identity, and at the same time replaces the
value of the dxProxyRole attribute with the roles of the new identity. In this
instance, the roles provided in the replace operation are used directly, provided
set ssl-auth-bypass-entry-check = true;
Activate Secure Proxy
To activate proxy access, enter the following command:
set trust-sasl-proxy = <dn>, …
where dn is the distinguished name of a trusted proxy. The proxy must bind
using SASL/EXTERNAL over SSL.
6–56
Access Controls and Aliases
When a user binds with a user name and password, the system checks the
password supplied with the bind against the password in the database for the
specified user. When the user name is an alias, the system checks the password
against the password in the entry to which the alias points, but the user name
associated with the bind is the alias name. This means that a user can bind with
more than one user name, and each user name can have different access controls
associated with it.
Security
6–57
Access-Controlled Routing
Access-Controlled Routing
This section describes how access controls work in a distributed environment. If
the DSA determines that it needs to chain or multicast an operation to a remote
DSA but the area controlled by that DSA is completely invisible because of static
access controls, the DSA refuses to route the request to the remote DSA.
By default, a DSA prevents the forwarding of a request to another DSA
according to its static access controls.
To permit the forwarding of a request regardless of access control constraints, set
the no-routing-ac DSA flag in the configuration file (.dxc) in the knowledge
directory. This lets a DSA pass a request to another DSA even when the user’s
access controls on the local DSA do not permit access to the particular entry or
subtree in the request.
For example, to let a DemoCorp DSA pass a request to a UNSPSC DSA
regardless of the user's local static access control constraints, you must set the
DSA flags in UNSPSC’s knowledge configuration:
set dsa UNSPSC=
…
dsa-flags=no-routing-ac
…
DemoCorp
DSA
6–58
UNSPSC
DSA
Chapter
7
Replication
This chapter describes the replication schemes you can use with eTrust Directory.
In a replicated directory, information stored in one part of the directory is also
stored elsewhere as one or more copies.
Replication is deployed for one or both of the following reasons:
■
■
Improved availability—Replication can make a system more robust by
enabling the directory on one server to fail over to an alternative server.
Applications can continue working as there are alternate DSAs/servers in
the network which can serve the same parts of the namespace.
Improved performance—Replication can place frequently accessed
information closer to where is it needed, which improves response times.
Replication involves copying data, and whenever data is copied, you must
ensure that the copies are synchronized. Developing and maintaining replicated
systems can be expensive, and you should weigh these costs against the benefits
of performance and recovery in the event of failure.
Replication
7–1
Replication Concepts
This section describes some important concepts about replication. These concepts
are used in explanations of the three different types of replication that you use
with eTrust Directory.
Compare Distribution and Replication
Distribution differs from replication.
In a distributed directory, each piece of data is stored on only one server. The
directory information tree (DIT) it split and each section is stored a different
server.
In a replicated directory, each piece of data is held on more than one server. The
entire DIT is stored in more than one place.
You can use both replication and distribution in the same system. The DIT is split
and stored in many different servers, and at least some of those sections of the
DIT are also copied and stored in more than one place.
Compare Multimaster and Master–Slave Replication
In a system with multimaster replication, all DSAs are masters. Data is copied
between all DSAs. The master DSAs are also called peer DSAs.
In a system with master–slave replication, data is always copied in one direction,
from a master DSA to one or more slave DSAs.
Read and Update
Requests
Read and Update
Requests
Master DSA
Updates
Read and Update
Requests
Master DSA
Updates
Updates
Master DSA
Update
Update
Update
Master DSA
Slave DSA
Slave DSA
Read and Update
Requests
Multimaster Replication
7–2
Master-Slave Replication
Slave DSA
Compare Real-Time and Write-Behind Replication
In a system with real-time replication, data is replicated to other servers as soon as
an update request is received from a client.. The update confirmation is not sent
to the client until each of the slave or peer DSAs has sent an update confirmation
message.
In a system with write-behind replication, data is replicated periodically,
independent of the client update. The update confirmation is sent as soon as the
operation completes locally. Write-behind replication can in these two ways:
■
■
On-demand write-behind replication—The updates are transferred
immediately after they occur
Scheduled write-behind replication—The updates are transferred according
to a periodic schedule.
Latency is the time for which the shadow servers are out-of-date with respect to a
master server. For many applications, such as an authentication service, any
latency is unacceptable. To overcome the problem of latency, use a real-time
replication system rather than write-behind replication.
Compare Replay-Based and State-Based Replication
In a replay-based system, every update applied to a master is subsequently
applied to the slaves.
This system is simple and can operate in real time, but it is not robust when
something goes wrong with the replay or when conflicting updates occurred in a
system with many masters.
In a state-based system, a difference is calculated between the current state of the
master system and some previous state of the slave system. The calculated
difference between these two states is then sent across to the slave. If conflict
resolution is built in, then this mechanism can also reconcile a system with many
masters.
A state-based system deals very efficiently with repeated updates. For example,
even if an entry were modified 100 times since the last update, only one update is
transferred. In a replay-based system, 100 updates would be sent. However,
state-based systems are generally not designed to operate in real-time.
Replication
7–3
The following table summarizes the two schemes:
Replication Type
Advantages
Disadvantages
Example
Replay-based
Simple
Can be real-time
Poor recoverability
Multiwrite
State-based
Efficient
High recoverability
Cannot be real-time
DISP
Three Types of Replication Used with eTrust Directory
eTrust Directory supports three standards-based mechanisms of replication:
Replication Characteristics
Scheme
Most Suitable Deployment
Multiwrite
Where network links, computers, and
Multimaster
power supplies are reliable
Real-time
Simple configuration
High performance
Replay-based
DISP
Master–slave
Write-behind
High flexibility
State-based
Where interoperability is required with
another vendor’s X.500 directory
DXtools
Batch mode
High traceability
Where synchronization is required between
two directories or with a legacy system
Keep System Clocks Synchronized
For any replication system, synchronize the operating system clocks regularly. If
the system clocks are not set at the same time, replication will not work as you
expect, because conflict resolution is time-based—the most recent update wins.
7–4
Multiwrite Replication
Multiwrite replication is a good choice for a system that includes applications
that require real-time replication.
Multiwrite replication uses the fast, efficient Directory System Protocol (DSP) to
chain updates between servers in real time.
To use multiwrite replication successfully, your network links, computers, and
power supplies should be reliable. Treat system crashes and unreliable networks
as disaster recovery scenarios that involve reconciliation between databases
using DXtools.
You can configure DSAs into multiwrite groups. When an update is applied to a
DSA in a group, it passes these updates on to the other DSAs in the group.
How Multiwrite Replication Works
Multiwrite replication uses DSP chaining to apply updates to all replication peers
in real-time. When a client makes an update request, that update is applied
immediately to the local DSA, and then to all other DSAs. The client receives the
confirmation response only after all DSAs have successfully applied the update.
The following diagram shows these steps:
1.
Write to self—A client sends an update request to DSA1, and this DSA
applies the update to itself.
2.
Write to peers—If the local update succeeds, DSA1 sends the request to its
peer DSAs. If these updates succeed, the peers send confirmations to DSA1.
3.
Send response to client—When DSA1 has received confirmation from each
peer, it sends the confirmation response to the client.
2
2
1
2
Client
DSA 1
DSA 2
3
DSA 3
2
1
1
2
2
2
2
Update Request
Update Confirmation
Database
1
Database
2
Database
3
The Three Phases of Multiwrite Replication
When a multiwrite update fails, the system must be recovered. See the sections
Replication
7–5
Recovering a Multiwrite System Using Queues and Recovering a Multiwrite
System Using DISP.
Multiwrite Can Work Asynchronously
Multiwrite is usually synchronous: an update operation is not confirmed until all
the multiwrite peers have applied it. This provides for load-sharing and failover.
However, this synchronous behavior may not be desirable if peer DSAs are
connected by slow links, or if latency is not an issue.
If a DSA is set to multiwrite asynchronously, when other DSAs multiwrite to this
DSA, they will not wait for a confirmation before they to hold the confirmation
on account of this DSA. The confirmation is returned once all the multiwrite
peers not marked multi-write-async have applied the update.
To set a DSA to multiwrite asynchronously, add the DSA flag multi-write-async to
the DSA’s knowledge.
7–6
How Multiwrite Groups Work
In a system that includes at least one slow network link between DSAs, delays
caused by this slow link can slow down the whole multiwrite system. Multiwrite
groups let you avoid delays due to a slow network link.
How A Slow Network Link Causes Delays
A single slow link can delay a multiwrite system because the DSA making the
update must wait for confirmation from all DSAs before sending confirmation
back to the client. This can cause a bottleneck if many updates are made each
second.
The following diagram shows a multiwrite system in which three of the DSAs
are connected by slow network links. In this system, DSA 1 must wait until it has
received confirmation from these three DSAs before it can send the update
confirmation back to the client. From the client’s point of view, each update takes
much longer than it should.
DSA 2
DSA 3
2
2
1
Client
DSA 1
2
DSA 4
3
2
2
Update Request
Update Confirmation
DSA 6
DSA 5
Slow Network Link
A Multiwrite System with Slow Network Links
Replication
7–7
How Multiwrite Groups Avoid Bottlenecks
To avoid delays due to slow network connections, you can put the DSAs on each
side of a slow link into separate groups.
Each group has one hub DSA. This is the DSA that will accept multiwrite
requests from DSAs in other groups.
The following diagram shows these steps:
7–8
1.
Write to self—A client sends an update request to DSA1, and this DSA
applies the update to itself.
2.
Write to peers in group—If the local update succeeds, DSA1 sends the
request to its peer DSAs in the same multiwrite group. If these updates
succeed, the peers send confirmations to DSA1.
3.
Send response to client—When DSA1 has received confirmation from each
peer in its multiwrite group, it sends the confirmation response to the client.
4.
Write to hub DSAs in other multiwrite groups—DSA1 sends the request to
the hub DSAs in each of the other multiwrite groups.
5.
Hub DSAs write to peers—Each hub DSA sends the request to the other
DSAs in its group. When each hub DSA has received confirmation from each
peer in its multiwrite group, it sends the confirmation response to the first
DSA. The client confirmation will not be affected by the slow links, because
the updates over these links are asynchronous.
Multiwrite
Group C
DSA 9
5
Multiwrite
Group A
DSA 2
DSA 8
(Hub)
DSA 3
5
5
DSA 11
4
2
DSA 10
2
DSA 1
1
3
Client
4
DSA 5
5
DSA 4
(Hub)
5
DSA 6
5
Multiwrite
Group B
DSA 7
Multiwrite Hub Failover
If an update sent to a hub fails because the hub DSA cannot be reached, then the
DSA tries the next hub in the list.
If all hubs fail, then the update will be queued against the first hub DSA. This
DSA takes care of queuing for the offline DSAs.
Replication
7–9
Set Up a Multiwrite System
You can set up a multiwrite replication system in many different configurations,
including master–slave, primary-backup, multimaster, or multiwrite groups.
You can also use other DSA flags to support load balancing and query streaming.
Multiwrite replication is simple to implement. Because multiwrite replication is built
into DXserver, you do not need to use a separate product or additional licensing.
Enable Multiwrite Replication
To enable multiwrite replication, do the following:
1.
Decide which DSAs will be included in the multiwrite system.
2.
Configure these DSAs with the same context prefix.
3.
Connect each DSA to a database holding synchronized information.
4.
5.
Add the DSA flag multi-write to the shared knowledge, as follows:
set dsa dsaname = {
...
dsa-flags = multi-write, ...
... };
Note: Place DSA flags after dsp-idle-time and before any trust and link flags.
Set Up a Multiwrite Group
To set up multiwrite groups, do the following:
1.
Decide which DSAs will be included in the multiwrite system.
2.
Decide how many multiwrite groups you need, and which DSAs will be
grouped together.
3.
For each groups of DSAs, choose a hub DSA.
4.
Configure all DSAs with the same context prefix.
5.
Connect each DSA to a database holding synchronized information.
6.
7.
Add the multi-write DSA flag to the shared knowledge:
set dsa dsaname = {
...
dsa-flags = multi-write, ...
... };
8.
In the knowledge for each DSA, define the multiwrite group:
set multi-write-group = group-name
7–10
Define the Hub DSA for a Multiwrite Group
To set a DSA as the hub for a multiwrite group, list it first in the list of DSA
knowledge files.
Set the Retry Interval
To define the frequency at which DXserver will attempt to bind to a multiwrite
peer which cannot be contacted:
set multi-write-retry-time = <seconds>;
If you don’t set this time, the default value of 60 seconds will be used.
Replication
7–11
Recovering a Multiwrite System Using Queues
With multiwrite replication, you can choose between two methods of recovery:
queues or DISP. This section describes how queues work.
How Multiwrite Queues Work
Multiwrite DSAs are usually online. If one of the DSAs in the group goes offline,
the update is queued in memory until the DSA becomes available again.
After queuing, a confirmation is sent to the directory client. In effect, multiwrite
converts into a write-behind scheme until the offline DSA becomes available.
Increase the Queue Size
The queue pool has a default size of 200 updates for each peer. To change the
queue pool size, use the following command:
set multi-write-queue = n;
where n is the size of the update queue.
You can gauge the required size from, for example, the size of the updates in
your LDIF file.
View the Size of a Multiwrite Queue
To see the current size of the multiwrite queue, use the following command:
get dsp;
Here is a sample of the output from this command:
max-dsp-ops
= 100
local-prefix
=
<countryName "AU">
<organizationName "CA">
<organizationalUnitName "Test">
<organizationalUnitName "mwrite">
local-dsa
= dsa-1
multi-chaining
= TRUE
always-chain-down
= FALSE
multi-write-disp-recovery = FALSE
multi-write-queue
= 200
...
7–12
Multiwrite Queue Alarms
While a peer DSA is offline, new updates are queued and, periodically, an
attempt is made to connect to the offline DSA.
When the peer DSA comes back online, the queued requests are sent in the order
that they are processed locally. Consequently, multiwrite copes well with a DSA
that is offline for a short period of time.
However, if the peer DSA remains offline for an extended period, the multiwrite
queues build up. Alarms are raised at 60%, 70%, 80%, 90%, and 100% of queue
capacity, and written to the alarm log.
If the queue becomes full, DXserver ignores the unavailable DSA. It discards all
the queued requests for the peer and drops the peer from the multiwrite set. You
must then resynchronize the databases and restart the DSAs.
If multiwrite has occurred, the get dsp command returns one of the following
statuses:
Status
Description
Failed
Indicates that the multiwrite peer is not responding to an update.
Updates for that server are held in the multiwrite queue until the
server responds. The queue is retained until the multiwrite queue
size is exceeded.
Recovering
Indicates that the multiwrite peer has become available and still
has old updates in its queue.
OK
Is the normal multiwrite server status.
Replication
7–13
Recovering a Multiwrite System Using DISP
With multiwrite replication, you can choose between two methods of recovery:
queues or DISP. This section describes how DISP recovery works with multiwrite
replication.
Enabling DISP recovery generally avoids manual resynchronization of the
databases.
DISP recovery works in concert with multiwrite by handling all the recovery. In
effect, fast multiwrite is used during uptime and DISP is only used for recovery
after a downtime.
DISP recovery has the following features:
Database tables
All information is derived from database tables instead of in-memory
queues. This means that recovery can survive restarts of a master (whereas
you can lose the in-memory queues).
State-based
Resynchronization uses efficient state-based deltas. This is usually superior
to replay-based recovery.
Reconciliation
The DISP processing supports automatic conflict resolution using a last write
wins rule. Managing conflicts is often a problem for replay-based systems
because the order of updates from different masters can be critical.
Important! If you configure multiwrite DISP recovery, you should specify the ssl-auth
authentication level only if you have set up SSL certificates for the DSAs in the
multiwrite group. This is because DISP recovery uses the highest available
authentication level.
Note: Multiwrite–DISP recovery cannot be used where more than one DSA is
attached to the same database.
7–14
Enable Multiwrite-DISP
To turn on multiwrite with DISP recovery, use the following command:
set multi-write-disp-recovery = TRUE;
The effect of turning on this flag is to disable offline multiwrite queuing, so that
when a DSA cannot be contacted, it is immediately dropped from the multiwrite
set. However, DISP periodically probes the unavailable DSA.
When the unavailable DSA comes online, the following occurs:
1.
The multiwrite queue is enabled.
2.
DISP performs the resynchronization (by sending a delta for the period in
which the DSA was offline). While this is occurring, any updates are queued.
3.
When the DISP update completes, the multiwrite queue is replayed to the
new DSA.
4.
Multiwrite operation resumes.
Note: There are no explicit DISP agreements—all resynchronization and
reconciliation is automatic.
Queueing Multiwrite-DISP
If the following configuration flag is set to true, a multiwrite master will only
start DISP recovery after it has been down or its multiwrite queues had reached
their limits:
multi-write-disp-queue = <boolean>
In all other cases it replays its queue content to any peer that was unavailable for
a while.
Consistency During Recovery
The following setting guarantees consistency during recovery:
disable-non-peer-binds = <boolean>
If a DSA goes offline in a multiwrite DISP scenario, and this is set to true, only
binds from multiwrite peers are allowed. This stops the recovering DSA from
receiving non-peer (client, relay, router, or chained) requests that may provide
inconsistent results.
When the DSA has been synchronized (get dsp; or snmp shows multiwrite
queues ok) then this setting can be set back to false. The DSA will accept binds
after a few minutes.
Replication
7–15
Granularity of DISP Reconciliation
When DISP resynchronization starts it propagates all changes to the DSA since
the last successful multiwrite update.
In a multimaster system, it is possible that some of the changes can clash.
Resolution of these conflicts is automatic and is done on a last write wins rule,
with the smallest element being an X.500 object.
For example, when DSA1 updates an object’s surname attribute at time T, and
DSA2 updates an object’s phoneNumber attribute at time T+1, then the final
object after resynchronization is the object contained in DSA2, and does not have
the changes to the surname.
Add a Database Replica
To add a database replica:
1.
Follow the instruction in Manually Synchronizing Replicas Using Database
Tools in this chapter. This creates another database containing the same data
as the source.
2.
Create a new peer DSA that will use the new populated database.
3.
Change the DSA flags in the knowledge file to contain the multi-write flag for
both the source and target DSAs.
4.
Use the following command for all multiwrite DSAs running multiwrite
DISP recovery, that is, where multi-write-disp-recovery = TRUE
For example, on the Source DSA use the command:
dxdisp -clear targetDSA sourceDB
This clears the time of the last DISP update to the target DSA from the source
DSAs internal database tables. When the source DSA starts, it sets this time
to the source DSAs startup time and then only sends DISP updates
containing changes since that time.
5.
7–16
Start the source and target DSAs.
Remove a Database Replica
To remove a replica:
1.
Shut down all the peers within the replication set.
2.
Edit the initialization file or the knowledge group file (if applicable) to delete
the knowledge of the DSA being removed.
3.
Clear the time of the last DISP update from each of the remaining DSAs in
the replication set for the DSA being removed using tool DXdisp tool.
For example, if Apple, Banana, and Pear are DSAs in a replication set and
you remove the Pear DSA, issue the following commands:
On the system running the Apple DSA:
dxdisp –clear Pear AppleDB
On the system running the Banana DSA:
dxdisp –clear Pear BananaDB
Multiwrite Replication to an LDAP Directory
You can use multiwrite replication to replicate updates applied to eTrust
Directory to an LDAP server.
To forward all updates on an eTrust Directory server to an LDAP server, include
the following line in the knowledge of the LDAP server:
dsa-flags = multi-write
Multiwrite and DXcache
If you are using DXcache to increase search performance to a shared database,
you can still send multiwrite updates to only update DXcache by including
the DSA flag multi-write-notify in the knowledge:
dsa-flags = multi-write-notify
In this mode, the cache is updated but the database is not. Configure at least one
DXserver connected to the database so that the database remains updated and
synchronized.
See the chapter “General Administration” for more information about DXcache.
Replication
7–17
Re-synchronize Databases Manually
Regardless of the amount of automatic recovery in place, it is always necessary to
have procedures in place that use tools to resynchronize databases.
If a DSA is offline for a long period of time, then a large number of updates may
be required to synchronize that DSA with the master. When this is the case, it can
be quicker to reload the data from a snapshot of the master database. If you do
this, you must also inform the master and other peers that a manual
resynchronization has taken place.
To take a snapshot of the master and reloading it on the slave, use the
DXdumpdb and DXloaddb tools
To inform a peer that a particular DSA has been manually resynchronized, use
the following command:
dxdisp -clear dsaname dbname
where
■
dsaname is the name of the slave DSA
■
dbname is the name of the database associated with the peer DSA
To manually resynchronize master and slave DSAs:
7–18
1.
Shut down the master DSA.
2.
Dump the master database using the DXdumpdb tool.
3.
Inform the master (and any other peer DSA) that a manual resynchronization
has occurred using the DXdisp tool.
4.
Restart the master DSA.
5.
Copy the LDIF file to the slave machine.
6.
Reload the slave database using the DXloaddb tool.
7.
Start the slave DSA.
Example: Multiwrite Replication
The system shown in this diagram has the following properties:
■
■
■
■
All read operations (read, list, search, compare) are load-shared between the
two machines (according to the order that the DSAs are defined). Making use
of both machines can double the system throughput.
All write operations (modify, rename, add, delete) occur in real time using
multiwrite. This ensures that both machines are synchronized at the time the
update-confirm is sent back to the client.
The primary router (R1) can automatically redirect/retry any queries sent to
a data DSA (RO1, RW1, RO2, RW2) that unexpectedly shuts down. When
this DSA is returned to operation, it is automatically resynchronized.
The client application should fail over to the backup router (R2) in the event
that Machine 1 (or R1) unexpectedly shuts down. If the client retries (to R2)
any queries outstanding (on R1), then there is no possibility of the system
losing transactions.
This configuration can be summarized in the following table:
DSA
Function
Prefix
DSA flags
R1, R2
Router DSA
<c US>
-
RO1, RO2
Read DSA
<c US><o CA>
read-only, load-share
RW1, RW2
Read/Write DSA
<c US><o CA>
multi-write
This diagram shows the effective combining of distribution and replication. The
prefix of the routers (R1, R2) is one level less than that of the data DSAs (RO1,
RW1, RO2, RW2). A query is routed to a data DSA when the base object of the
query is within the subtree of the data DSA.
Replication
7–19
You can configure the system shown this diagram to have the immediacy of the
multiwrite replay system with the recoverability of the state-based system. In
this case, DSP is used to chain requests in real time to peer/slave DSAs while
DISP can be used to recover requests if any DSAs are restarted.
7–20
DISP Replication
DISP Replication
X.500 defines a master–slave replication scheme using DISP (Directory
Information Shadowing Protocol). In this scheme, any update that succeeds
locally is forwarded to other DSAs according to any controlling bilateral
agreement with those other DSAs.
The DXserver DSA implements the 1993 Directory Information Shadowing
Protocol (DISP), which lets you replicate information in OSI-conformant
directories. This implementation is very flexible and supports:
■
DISP routing
■
Shared configuration
■
On-demand and periodic updates
Configuring a DISP Responder
To configure the DISP responder module, enter a listening address in the DSA
definition in the configuration file (.dxc), in the knowledge directory.
Example: Configuring
the DISP Responder
# Sample DSA Knowledge configuration file: DemoCorp.dxc
set dsa “DemoCorp” =
{
prefix
dsa-name
=
<c AU><o DemoCorp><cn “DXserver”>
dsa-password
= “demo”
address
= tcp eagle port 1900
disp-psap
= DISP
...
auth-levels
= anonymous, clear-password
dsp-idle-time
= 3600
};
This responder remains active, awaiting incoming DISP protocol requests.
DISP Agreements
Agreements form the basis of all replication transfers. You direct and validate
DISP updates between DSAs using agreements. A DSA can have a number of
agreements relating to one or more remote DSAs.
You can manage DISP agreements using the commands:
■
set agreement id.ver = agreement;
■
get agreement
An agreement is a set of statements that defines a replication strategy. Define
each agreement with an agreement identifier and an agreement version.
Replication
7–21
DISP Replication
Setting DISP Agreements
You can set agreements using the set command, which the following form:
set agreement id.ver =
{
initiator = name mode
responder = name authlevel
[relay = name authlevel ]
area = <DN>
[filter = { searchFilter }]
[attributes = { attrSelectionList }]
[strategy = frequency time type]
};
The following are the parameters of the set agreement command:
Parameter
Value
id.ver
The agreement identification and version numbers (for example, 1.2).
initiator
The DSA initiating the DISP update:
name—DSA name as defined in a set dsa definition
mode—either supplier or consumer
responder
The DSA receiving the DISP update:
authlevel—anonymous, clear-password, or ssl-auth
relay
(Optional) An intermediate DSA used to relay the DISP update:
authlevel—either anonymous or clear-password
area
The top of the subtree being replicated; the value is the distinguished name of the
entry at the top of the subtree.
strategy
(Optional) Enables automatic DISP update to be performed. The strategy either
has the keyword value on-change or has the following three values:
frequency—has one of the keyword values hourly, daily, weekly, or monthly
time—either dd:hh:mm or hh:mm
type—either incremental or full
Filter
A search filter restricting the entries to be included in the DISP update
searchFilter—an X.500 filter
attributes
A list of attributes to include and/or exclude from a DISP update.
attrSelectionList ::= attrSelection | attrSelection attrSelectionList
attrSelection ::= { [object-class = objectClass,] IncludeExclude }
IncludeExclude ::= [all-attributes] | [include = attrTypeList] | [exclude =
attrTypeList]
attrTypeList ::= attributeName [, attributeName]
7–22
DISP Replication
Example: A DISP
Agreement
set agreement 0.0 =
{
initiator = EAGLE supplier
responder = BACKUP anonymous
area
strategy = daily 03:00 incremental
};
Viewing DISP Agreements
You can monitor DISP configuration using the get disp command. To view
details of an agreement, use the following command:
get agreement 1.0;
where 1 is the agreement identifier and 0 is the agreement version. The output of
this command looks similar to:
Agreement 1.0
initiator
responder
area
= EAGLE supplier
= BACKUP
= <countryName AU>
<organizationName DemoCorp>
- last update at Thu Jul 9 09:53:47 1998
Shared DISP Configuration
You can achieve replication between two DSAs using point-to-point DISP.
DB
DSA
(Supplier)
DISP
DSA
DB
(Consumer)
Share the DISP configuration between the DSAs. When two DSAs share an
agreement that includes a strategy (see DISP Agreements in this chapter for more
information), where one of the DSAs is an initiator and the other a responder, the
system performs automatic DISP updates as determined by the strategy.
Replication
7–23
DISP Replication
Manual Initiation of DISP
You can manually perform a DISP update, even when there is a strategy, using
the command:
disp update agreement 1.0;
The strategy in the agreement defines the mode of the update. When there is no
strategy, the update defaults to full.
An incremental update updates all entries that changed since the last DISP
update or since the DSA started.
Shadow DSAs
You can mark a slave DSA as a shadow. This means the DSA will act as a read
only DSA and will not grant updates, except via DISP or Multiwrite. The master
DSA can update the slave using DISP. Clients can query, but not update, the
DSA using DAP or LDAP.
set dsa ShadowDSA = {
...
dsa-flags = shadow, ...
...
};
DISP Routing
DXserver supports the concept of a DISP relay that lets you route DISP through
one or more intermediate DSAs. This is especially useful for firewall and X.500
Guard applications.
DB
DSA
Routing
DSA
DSA
DB
To include a relay DSA in a DISP replication process, all three DSAs must have
an agreement that identifies the relay. All three DSAs can share the same DISP
configuration.
Example: A DISP
Agreement with Relay
7–24
set agreement 0.0 =
{
relay
= DSA-RELAY anonymous
area
};
DISP Replication
Selective Shadowing
The DXserver supports three methods of restricting the data that a supplier
replicates to a shadow consumer. These methods are:
■
Specifying the replicated area
■
Specifying a subtree filter for the replication area
■
Specifying the set of attributes to be shadowed.
Each of these refinements to the shadowed data are defined below.
Specifying the Replicated Area
This is defined by the area parameter in the DISP agreement. It specifies the top
of the subtree to be replicated.
Specifying a Subtree Filter
This is defined by the optional filter parameter in the DISP agreement. This
specifies a filter that is applied to entries in under the area context prefix. The
filter parameter is defined as:
filter = { <filter> } | NULL
<filter>
::= and { <filterSet> } | or { <filterSet> } | not { <filter> }
| <filterItem>
<filterSet>
::= <filter> | <filter> , <filterSet>
<filterItem>
::= attr = <attrOid> <filterExist>
<filterExist>
::= present | value <filterComp> <value> | substrings [<substrings>]
<filterComp>
::= = | <= | >= | ~=
<subStrings>
::= <subStr> | <subStr> , <subStrings>
<subStr>
::= <subStrPortion> <string>
<subStrPortion> ::= initial | final | any
Using the subtree filter may cause problems when shadowing to other vendors
directories. This is the case when a full refresh is requested, or if an entry is
shadowed, but its parent entry does not exist on the shadow consumer. eTrust
directory overcomes these problem by the shadow consumer automatically
creating glueDSEs for the missing entries. A glueDSE is a DSE (Directory Specific
Entry) that has a name but no attributes including objectclass.
If the subtree filter contains anything other than comparisons on object class
values, for example a filter that matches all surnames of smith, then it is possible
for an replicated entry to be modified on the master DSA such that the entry no
longer matches the search filter. Subsequent DISP updates will not contain this
entry but the shadow DSA will still contain the unmodified attribute and value.
This is not a problem if the whole entry is deleted. For this reason it is not
recommended to use anything other than restrictions based on object class.
Replication
7–25
DISP Replication
Specifying a Selection of Attributes
This is defined by the optional attributes parameter in the DISP agreement. This
specifies the set of attributes that are shadowed.
Each element of attrSelectionList is an attrSelection element, which specifies the
attributes that the shadow supplier is to select for shadowing. Specification of
attributes for an object superclass also applies to any subclasses of the named
class. If the class is omitted, the selection applies to all classes.
When using the exclude specification, any attributes contained in an entry which
are not explicitly excluded are implicitly included. Attributes are implicitly
included in the case where all-attributes is specified.
The attribute object class, all attributes that are described in the schema as must
contain, and all operational attributes will be replicated unless they are explicitly
excluded (that is, listed in an exclude list).
Where entries belong to more than one of the specified classes, the specifications
are cumulative. In the case of conflicting specifications include has priority over
explicitly excluded attributes and exclude has priority over implicitly included
attributes.
It is possible for a selective DISP update to contain add entry requests that do not
satisfy the schema requirements of the shadow consumer. For example, all
mandatory attributes may not be present in the entry contained in the DISP
update. With eTrust Directory, such an update is allowed, because it is assumed
that the master DSA has verified the schema of the complete entry and allowed a
partial replication to the shadow (or slave) DSA. The shadow DSA should be a
read-only DSA so the fact that not all attributes are present in the entry should
not be of consequence. This may cause problems when replicating to other
vendors’ directories.
Example: Selective
Shadowing Example
Agreement
7–26
set agreement 2.1 =
{
area = <c AU><o Democorp>
filter = { attr = objectClass value = organizationalPerson }
attributes = { { exclude = title, description, telephoneNumber } }
strategy = on-change
};
Manually Synchronizing Replicas Using Database Tools
Manually Synchronizing Replicas Using Database Tools
eTrust Directory databases should be manually synchronized when:
■
■
The DXstatdb tool shows differing numbers of entries between databases in a
replication set when the system is quiet. In this case, it usually makes sense
to resynchronize all the directory databases to have the same number as the
master database.
There is a large mismatch between directory entries, perhaps because a
multiwrite peer or DISP responder is unavailable for a long period of time
while updates are applied to other systems in the replication set.
How Manual Synchronization Works
eTrust Directory provides a powerful set of database tools that can be used for
resynchronization.
This technique extracts directory information directly from the directory
database into an intermediate LDIF file and then populates the target directory
database directly from this file.
Note: Both the source and target DSAs should be shut down during these
operations.
Source
DB
dxdumpdb
LDIF
ldifsort
File
LDIF
File
dxloaddb
Target
DB
How to Manually Synchronize eTrust Directory Databases
To manually resynchronize eTrust Directory databases:
1.
Dump the source database and use the DXdumpdb tool to produce an LDIF
file.
2.
Use the ldifsort tool to sort the source LDIF file into DIT depth order.
3.
If the databases are on different systems, copy the LDIF file from the source
system to the target system.
4.
Use the DXloaddb tool to load the target database with the LDIF data.
5.
Start the source and target DSAs.
Replication
7–27
Chapter
8
LDAP and DXlink
DXserver supports Lightweight Directory Access Protocol (LDAP), which
enables any LDAP-conformant client access to DXserver. LDAP is fully
integrated with DXserver and provides greater performance and efficiency than
gateway approaches. Another advantage of integrated LDAP is that it obeys the
DSA schema. This means that you only configure new schema once because both
LDAP and DAP protocols share the same configuration.
DXserver also supports the integration of LDAP servers into a distributed
directory backbone. DXlink lets DXserver send requests to one or more LDAP
servers and process the results returned from them as if they were normal X.500
directory servers. This enables LDAP servers to be integrated into a fully
distributed directory framework.
LDAP and DXlink
8–1
LDAP Clients
LDAP Clients
DXserver can be accessed from LDAP clients, such as web browsers, address
books, and Lightweight Directory User Agents (LDUAs).
DXserver
LDAP
LDAP
Server
Client
DXserver
Defining the LDAP Port
You define the LDAP address using the set dsa command, which contains a port
number that listens for LDAP requests, as follows:
set dsa “Eagle” = {
...
address = tcp “eagle” port 389
...
};
This address definition is mandatory; it automatically enables LDAP as the
DXserver listens for different protocols on the same port. For more information,
see the section Defining DSAs in the chapter “General Administration” for more
information.
Configuring LDAP Names
You configure LDAP names along with the usual schema attribute and object
class definitions:
set attribute 2.5.4.3 = {
name
= commonName
ldap-names = cn
syntax
= caseIgnoreString
};
LDAP names are integrated into the DXserver schema. See the chapter “Schema
Definition” for more information.
8–2
LDAP Clients
Handling LDAP Strings
LDAP uses only string labels for information, so DXserver resolves them to their
true object and attribute identifiers by looking up their schema information. For
each object and attribute label specified in the LDAP service requests, DXserver
looks first for matching ldap-names, and then for a name.
LDAP is a string-handling protocol only; therefore, a number of restrictions are
implicit:
■
■
■
Developers of directory clients must ensure the DXserver receives an
appropriately formatted LDAP message because the LDAP syntax is highly
dependent on appropriate punctuation, white space, and so forth.
Developers of LDAP directory clients must define locally customized
attributes and objects through the DXserver schema definition process.
Developers should remember that LDAP names are not necessarily unique.
For example, two organizations can define the string mail, but have different
syntaxes and uses for it.
Transparent Routing
When using DXserver to route client requests to external LDAP directories using
DXlink, it may not be feasible or convenient to include all third-party schema.
See the Transparent Routing section in the Distribution and DSP chapter for
more information.
LDAP and DXlink
8–3
Schema Publishing
Schema Publishing
eTrust Directory supports schema publishing through LDAP Version 3. This
enables LDAP directory clients to read the directory schema dynamically from
the DXserver using LDAP Version 3. For further information, see section 3.2.2
Subschema Entries and Subentries of RFC 2251 LDAPv3.
The following information is published through the cn=schema subschema
subentry using LDAP Version 3:
■
Attributes
■
Object Classes
■
Attribute Types
■
Syntaxes
■
Name Forms
■
Structure Rules
This can be retrieved by performing a base object search of the cn=schema
subentry with a search filter of objectClass present. The following is an extract of
the LDAP trace of such a search:
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
<-- LDAP MESSAGE messageID 2
SearchRequest
baseObject: cn=schema
scope: baseObject
derefAliases: derefAlways
sizeLimit: 0
timeLimit: 0
typesOnly: false
filter:
present: objectClass
attributes:
--> LDAP MESSAGE messageID 2
SearchResultEntry
objectName: cn=schema
attributes
type: objectClass
value: top
value: subschema
type: cn
value: schema
>
type: attributeTypes
>
value: (2.5.4.0 NAME 'objectClass'SYNTAX 1.3.6.1.4.1.1466.115.121.1.38)
>
value: (2.5.4.1 NAME 'aliasedObjectName'SYNTAX
1.3.6.1.4.1.1466.115.121.1.12)
. . .
>
value: (1.3.6.1.4.1.3327.77.4.1.9 NAME 'uNSPSCdateto' SYNTAX
1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE)
>
type: objectClasses
>
value: (2.5.6.0 NAME 'top' ABSTRACT MUST (objectClass))
>
value: (2.5.6.1 NAME 'alias' SUP (top) STRUCTURAL MUST (aliasedObjectName))
. . .
>
value: (1.3.6.1.4.1.3327.77.4.2.1 NAME 'uNSPSC' SUP (top) STRUCTURAL MUST
(uNSPSCCode$uNSPSCTitle) MAY
(uNSPSCContractManager$uNSPSCContractID$uNSPSCContractAuth$uNSPSCContractSupplie
8–4
Schema Publishing
r$uNSPSCdateissued$uNSPSCdatefrom$uNSPSCdateto))
>
type: ldapSyntaxes
>
value: (1.3.6.1.4.1.1466.115.121.1.4 DESC 'Audio')
>
value: (1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary')
. . .
>
value: (1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time')
>
type: nameForms
>
value: (1.3.6.1.4.1.3327.7.1 NAME 'country-top-NF' OC country MUST
(countryName))
>
value: (1.3.6.1.4.1.3327.7.2 NAME 'o-top-NF' OC organization MUST
(organizationName ))
. . .
>
value: (1.3.6.1.4.1.3327.77.4.14.3 NAME 'uNSPSC-uNSPSC-NF' OC uNSPSC MUST
(uNSPSCTitle) MAY (uNSPSCCode$uNSPSCContractID))
>
type: dITStructureRules
>
value: (1 NAME 'country-top-SR' FORM country-top-NF)
>
value: (2 NAME 'o-top-SR' FORM o-top-NF)
. . .
>
value: (38 NAME 'uNSPSC-uNSPSC-SR' FORM uNSPSC-uNSPSC-NF SUP (36 37 38))
LDAP and DXlink
8–5
Integrating Other LDAP Servers
LDAP servers do not support the DSP protocol. This means that you cannot
perform a distributed search over a number of LDAP directory servers. eTrust
Directory has a facility called DXlink that lets LDAP servers link into an X.500
backbone. The DXserver can send requests to one or more LDAP directories and
process the results returned from them as if they were X.500 directory servers.
DXserver
LDAP
DXserver
DXlink
To configure DXlink, configure the LDAP server as if it is a DXserver, and add
the dsp-ldap link-flags to the dsa definition as follows:
set dsa “LDAPserver” = {
prefix
= <c AU><o DemoCorp><ou email>
dsa-name
= <c US><o DemoCorp><ou email><cn LDAPserver>
address
= tcp Eagle port 389
...
link-flags
= dsp-ldap
}
Note: When you are using LDAP Version 3, use the dsp-ldap link flag; however,
when you are using LDAP version 2, use dsp-ldapv2.
8–6
User Credentials on DXlink Binds
LDAP servers expect connections from only LDAP users; therefore, DXlink must
make the X.500 backbone look like an ordinary LDAP user.
A complication arises with name and password security (simple credentials). In
DSP, a single link between DSAs can support any number of users, because user
information is passed with each DSP request. However, in LDAP, links cannot be
shared, so DXserver must set up separate links for every LDAP user.
When the DSA is acting as a direct pass-through from a user to an LDAP server
and the user's name resides on the LDAP server, then the DSA sets up a separate
link for that user and uses their credentials in that link:
User=J. Bloggs
password = yellow
Client
User=J. Bloggs
password = yellow
DSA
LDAP
Server
Setting User Credentials for LDAP Operations
However, if either of the following is true, you can set the credentials used in the
DXlink connections in the LDAP server configuration file:
■
■
The user invoking the request is authenticated using a DN that is outside the
LDAP server.
More than one DSA is in the path to the LDAP server.
For example:
set dsa LDAP1 = {
...
ldap-dsa-name
= <c US><o “Ace Industry”><cn “Fred Smith”>
ldap-dsa-password = fredspassword
...
};
The ldap-dsa-name must be a valid entry on the LDAP server because all
requests from the backbone use the permissions that are granted to this entry.
The DSA in the previous example expects credentials to be returned on the bind
confirm sent by the LDAP server. If no credentials are returned then the bind is
rejected.
The knowledge reference of the LDAP server can include the trust flag no-servercredentials, which indicates to the DSA that the LDAP server will not return
credentials on a bind.
LDAP and DXlink
8–7
When this flag is set, then the DSA will accept a bind confirm result returned
from the LDAP server if it does not include credentials.
set dsa LDAP1 = {
...
trust-flags = no-server-credentials
...
};
Automatically Authorizing LDAP Operations
When a directory backbone performs operations over DXLINK, some operations
on the target LDAP server may require that the user be authorized for that
operation.
You can include the dsp-ldap-proxy link flag in the DXLINK knowledge, to cause
the last DSA in the chain to use the authorization of the originating user to
perform operations on the LDAP server.
Important! This may compromise security, because the originating user is never
authenticated by the LDAP server.
Usually, the last DSA in the chain binds to the LDAP server using the credentials
specified in the ldap-dsa-name and ldap-dsa-password flags.
If the dsp-ldap-proxy flag is also set, then the DN of the user that made the initial
bind is added to the following subsequent requests:
■
search
■
compare
■
modify
■
add
■
delete
■
modify DN
If the initial bind was anonymous, no DN is added to subsequent requests.
This is achieved by the DSA chaining the operation over DXLINK adding the
originator DN to a LDAP proxy control on the request. The LDAP server will
need to allow the DN specified ldap-dsa-name authorization to proxy all users.
Note: The dsp-ldap-proxy link flag can only be used if the target LDAP server
supports the LDAP Proxy Authorization control.
8–8
Prefix Mapping
Prefix mapping lets LDAP servers, other DSAs, or agents map into an area of the
DIT. Prefix mapping is useful for collecting disjointed subtrees under a common
node. Applications include transient groupings (such as task forces) or logical
groupings (such as libraries where individual libraries are spread across an
organization or location tree).
Prefix mapping is also useful for DXlink because an LDAP server may not be
able to change its prefix. Because LDAP servers have no concept of distribution,
their DITs usually contain the first- or second-level nodes. This makes it hard to
integrate them into a host DIT.
An example is an X.500 directory system that controls the nodes c=US and c=US,
o=CAI. There is also an LDAP server with the X.500 naming context:
“c=US, o=CA”
The LDAP server does not contain the c=US node but controls the tree beneath
the c=US node that starts with the o=CA entry. It was set up to control the North
American part of CA but is now required to be incorporated into the entire CA
directory. This context can be mapped into the host's X.500 naming context
“c=US, o=CAI” as:
“c=US, o=CAI, ou=CA North America”
Thus, a subtree search of “c=US, o=CAI, ou=CA North America” is mapped to a
subtree search of “c=US, o=CA” before being forwarded to the LDAP server. The
results are mapped back into the host DIT space.
C=US
O=CAI
O=CA North
America
You can enable prefix mapping by defining a native-prefix in the server
definition:
set dsa LDAP1 = {
...
prefix
= <c US><o CAI><ou “CA North America”>
native-prefix = <c US><o “CA”>
...
};
LDAP and DXlink
8–9
Working with Microsoft Exchange
An example Microsoft Exchange knowledge file is shown below:
set dsa EXCHANGE = {
prefix
= <c AU><o Exchange>
native-prefix = <o “Computer Associates”><ou TEST><cn Recipients>
dsa-name
= <c US><o Exchange>
address
= tcp “currawong” port 389
auth-levels
= anonymous
dsp-idle-time = 60
trust-flags
= no-server-credentials, allow-downgrading, allow-upgrading
link-flags
= dsp-ldap, ms-exchange
};
The native prefix is determined by the following entries that can be found in
Microsoft Exchange Administrator. See the example shown in the following
dialog, where:
o = the Exchange Address Book name
ou = the domain name
cn = the recipients container (usually named “recipients”)
8–10
Chapter
9
Monitoring the Directory
We recommend that you monitor the directory to detect operational problems as
early as possible.
DXserver supports both Internet and OSI protocols for monitoring server
operations. These protocols are:
■
The Internet Simple Network Management Protocol (SNMP)
■
The X.700 Common Management Information Protocol (CMIP)
■
Telnet—used by the management console
General monitoring facilities, and DXadmind, the eTrust Directory
administration daemon, are also available.
9–1
General Monitoring
General Monitoring
During normal operation of a directory:
■
Data is added to and deleted from the directory.
■
User and other DSA connections are made and released.
■
Log files are generated.
You should review DXserver operation periodically to ensure DXserver
continues to run smoothly.
DXconsole
You can perform special-case checking of operational parameters and server
usage with management commands.
To view the number and type of operations performed by the DSA:
get stats;
To view current DSP connections to other DSAs:
get online-dsas;
To view current user connections to the DSA:
get users;
To view the names of the currently enabled log files:
get log;
Log Files
We recommend that you maintain log files to record a DSA’s activity. You can
then postprocess these files to obtain:
■
Statistics
■
Billing
■
Auditing
We also recommend that you periodically monitor the alarm log to check for
operation errors.
9–2
General Monitoring
Databases
The DXtools DXstatdb command prints a summary of a given database. The
database itself has monitoring facilities. See the chapter “Using DXtools” for
more information.
Disk Space
As a directory grows, it consumes more disk space. Disk space is used for:
■
Directory data
■
Backups (database checkpoints)
■
Log files
When the directory contains a large amount of data, the database checkpoint files
can become large. You can either delete old checkpoint files or move them to
storage areas.
9–3
SNMP and the Directory Monitoring MIB
DXserver has a built-in SNMP agent to monitor operations of the DSA. This
management agent implements the RFC1567 Directory Monitoring Management
Information Base (MIB) and includes information such as:
dsaOpsTable
Provides summary statistics on the directory accesses, operations, and errors
dsaEntriesTable
Provides summary statistics on the entries held by the DSA and on cache
performance
dsaIntTable
Provides useful information about the interaction of the monitored DSA with
peer DSAs
The SNMP agent can also monitor information that is specific to eTrust
Directory. These monitoring options are described in
/samples/snmp/dxmib.asn1. The SNMP can monitor:
■
Multiwrite replication
■
DXserver statistics
■
DXcache
You can use any third-party SNMP manager, provided it supports the RFC1567
MIB. Because this is a read-only MIB, you cannot use it for configuring the DSA.
9–4
Configuring the SNMP Agent
Configure the SNMP agent (via DXconsole or in the DSA configuration file (.dxc)
in the knowledge directory), using the set dsa command.
Example:Configuring
the SNMP Agent
set dsa “DEMOCORP” = {
...
snmp-port = 19389
...
};
Define the UDP/IP port that listens for incoming SNMP requests by setting the
snmp-port. This is the only UDP port that the DSA uses, so it can accept any
value and it does not interfere with TCP port numbers.
You can set the following SNMP parameters:
■
snmp-description
■
snmp-contact
■
snmp-name
■
snmp-location
set
set
set
set
snmp-description = “SNMP monitor”
snmp-contact = “supportconnect@ca.com”
snmp-name = myDXserver
snmp-location = myOffice
9–5
SNMP Monitor Utility
eTrust Directory supplies a sample SNMP MIB walker utility called dxsnmp in
the samples/snmp directory. The SNMP utility polls the server periodically and
prints nonzero parameters.
To start the SNMP utility, use the following command:
dxsnmp -r[n] ipaddress/port
The -r option is the refresh rate (in seconds). You can enter a number after the -r
to indicate the number of seconds between each refresh. The default value is 5.
Example: Starting the
SNMP MIB Walker
dxsnmp –r localhost/19389
The following is a sample output:
$ dxsnmp localhost/19389
sysDescr
sysObjectID
sysUpTime
sysContact
sysName
sysLocation
sysServices
dsaAnonymousBinds.1
dsaUnauthBinds.1
dsaSimpleAuthBinds.1
dsaStrongAuthBinds.1
dsaBindSecurityErrors.1
dsaInOps.1
dsaReadOps.1
dsaCompareOps.1
dsaAddEntryOps.1
dsaRemoveEntryOps.1
dsaModifyEntryOps.1
dsaModifyRDNOps.1
dsaListOps.1
dsaSearchOps.1
dsaOneLevelSearchOps.1
dsaWholeTreeSearchOps.1
dsaReferrals.1
dsaChainings.1
dsaSecurityErrors.1
dsaErrors.1
dsaMasterEntries.1
dsaCopyEntries.1
dsaCacheEntries.1
dsaCacheHits.1
dsaSlaveHits.1
Example: Monitoring
multiwrite replication
CA eTrust DXserver
1.3.6.1.4.1.3327.20.0.0
8323.00
supportconnect@ca.com
democorp
http://www.ca.com
0
11
0
0
8
0
99
0
0
0
0
0
0
0
30
20
0
0
0
0
11
0
0
0
0
0
This is only displayed if multiwrite replication is enabled. The following is a
sample output:
dxRemoteDsaName.1
dxRemoteDsaName.2
dxRemoteDsaName.3
dxMWQueueLength.1
dxMWQueueLength.2
dxMWQueueLength.3
dxMWStatus.1
dxMWStatus.2
dxMWStatus.3
dxMWPendingRemote.1
dxMWPendingRemote.2
9–6
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
DEMOCORP2
DEMOCORP3
DEMOCORP4
0
1
0
1 (ok)
2 (failed)
1 (ok)
0
0
dxMWPendingRemote.3
dxMWConfirmedLocal.1
Example: Monitoring
DXserver statistics
:
:
:
:
0
0
1
0
The dxStatsNoTicks and dxStatsBusy items only appear if stats logging is
enabled.
dxStatsAssocs
dxStatsNilCredit
dxStatsNoTicks
dxStatsQueue
dxStatsBusy
dxStatsOps
Example: Monitoring
Dxcache
:
:
:
:
:
:
1
0
1
3
2
11
This option always appears, but will only show information when DXcache is
enabled.
The dxCacheSearchHits value increments whenever a seach is resolved within
the cache. The dxCacheSearchMisses value increments whenever a search has to
be passed to the back end.
dxCacheStatus
dxCacheSize
dxCacheSearchHits
dxCacheMisses
:
:
:
:
3 (cache_ok)
456789
15
10
9–7
Configuring the SNMP Trap Destination
Deliver Alarms as
SNMP Traps
To configure the delivery of alarms as SNMP traps, use the following console
command:
set snmp-log = udp host port portnumber;
You can place this command in the appropriate configuration file (.dxc) within
the logging directory.
Disable Feature
To disable the feature:
close snmp-log;
Tip: The trap contains three variables: sysName, sysDescr, and sysLocation.
sysName contains the name of the DXserver sending the trap, sysDescr
contains sufficient information to reconstruct the actual update operation,
and sysLocation contains the actual alarm text.
Send Traps About
Any Update
Operations
By default, all alarms are sent to the trap destination. However, you can
configure the DXserver to send traps that contain information about any update
operations it receives. To do this, set an associated Boolean setting,
trap-on-update, as follows:
set trap-on-update = true;
Typically, you set this in the DXserver settings configuration file (.dxc) in the
settings directory.
9–8
CMIP and X.700 Management
The DXserver DSA has an integral CMIP management agent for monitoring the
operation of the DSA.
The DSA provides limited support for ISO 9594-10 (Committee Draft April 1995)
as follows:
■
■
The MIB fully supports the DSA-managed object definitions. You can
determine its structure and naming by setting scope=wholeSubTree or
scope=baseObject.
eTrust Directory supports all packages of the DSA-managed object. Each
component of each package is read-only because the intended use is for
monitoring.
Configuring the CMIP Agent
You configure the listening address for the CMIP agent through the management
console or in the DSA initialization scripts.
Example: Configuring
the CMIP Agent
set dsa “DEMOCORP” = {
...
cmip-psap = CMIP
...
};
The cmip-psap command defines the address, which this instance of the DSA
listens on for OSI management requests.
If required, you can input hexadecimal values in the syntax 0x1234 in place of
characters or text.
CMIP Monitor Utility
eTrust Directory supplies a sample CMIP monitoring utility called DXcmip in the
samples/cmip directory. This very simple CMIP manager performs periodic get
requests on the DSA.
You can start the CMIP utility using the following command:
dxcmip -r[n] ipaddress/portnumber
[psel]
The -r option is the refresh rate (in seconds). You can enter a number after the -r
to indicate the number of seconds between each refresh. The default value is five.
9–9
Example: Starting the
CMIP Monitoring
Application
dxcmip -r localhost/19389
This example starts the CMIP monitor. It monitors operations on the server
configured in SNMP Example 1—Configuring the SNMP Agent.
$ dxcmip localhost/19389
objectClass
nameBinding
packages
commonName
accessPoint
masterEntries
copyEntries
loopsDetected
securityErrors
nameErrors
foundLocalEntries
referrals
serviceErrors
aliasDereferences
chainings
invalidReferences
unableToProceed
outOfScope
noSuchObject
aliasProblem
aliasDereferencingProblem
affectsMultipleDSAs
unavailableCriticalExtension
timeLimitExceeded
sizeLimitExceeded
adminLimitExceeded
maxSizeLimit
maxTimeLimit
prohibitChaining
readOpsProc
compareOpsProc
abandonOpsProc
listOpsProc
searchOpsProc
search1levelOpsProc
searchSubtreeOpsProc
addOpsProc
removeOpsProc
modifyOpsProc
modifyDNOpsProc
readOpsProc
compareOpsProc
abandonOpsProc
listOpsProc
searchOpsProc
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
2.5.30.2.0
2.5.30.3.0
(Not decoded)
DSA
(Not decoded)
0
0
0
0
1
41
0
0
0
0
0
0
0
1
0
0
0
0
0
0
0
0
0
False
0
0
38
0
30
20
0
0
0
0
0
0
0
0
0
0
search1levelOpsProc : 0
searchSubtreeOpsProc
addOpsProc
removeOpsProc
modifyOpsProc
modifyDNOpsProc
dSAScopeOfReferral
dSAScopeOfChaining
peerEntityAuthenticationPolicy
requestAuthenticationPolicy
resultAuthenticationPolicy
dSPAssociationEstablishment
dOPAssociationEstablishment
dISPAssociationEstablishment
maxDAPAssociations
maxDSPAssociations
9–10
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
maxDOPAssociations
maxDISPAssociations
dAPAssociationTimeout
dSPAssociationTimeout
dOPAssociationTimeout
dISPAssociationTimeout
dSAActiveAssociations
pagedResultsMaxIDs
pagedResultsTimer
supportedApplicationContexts
:
:
:
:
:
:
:
:
:
0
0
0
0
0
0
0
0
(Not decoded)
sdfasf : -0
9–11
Chapter
10
Using DXtools
The DXtools provide a sophisticated set of utilities that simplify the management
of directory data and databases. These utilities can be divided into the following
general categories:
Database Tools
Simplify the management of the underlying Advantage Ingres databases and
the tables used by the DSAs, and provide a high performance, high volume
data import and export capability.
LDIF Tools
Convert and manipulate data using a format appropriate for import to the
directory.
DAP Tools
Provide an X.500 DAP interface for importing and exporting data to/from a
directory.
Schema Tools
Simplify the extraction of schema from LDAP directories, and the conversion
of schema into a format appropriate for eTrust Directory and for use by the
DXtools.
Note: Throughout this guide, references to Advantage Ingres include both
Together, these tools:
■
■
■
■
■
Provide a fast start to any directory project, letting you easily load existing
data for demonstration and prototyping.
Provide the means for managing directory data on an ongoing basis.
Can operate locally on the host Windows or UNIX server or execute from a
Windows client workstation to a directory server over a TCP/IP network.
Provide a migration path, a method, or both, for controlled exchange of data
when DSP is not appropriate.
Can be incorporated into your custom scripts. All tools return zero on
success and non-zero when an error occurs.
Using DXtools
10–1
Database Tools
Database Tools
The database tools provide a set of utilities that simplify the creation and
management of directory databases and the DSA tables.
Important! The RDBMS (Advantage Ingres) must be running for the database tools to
execute successfully.
The database tools are:
DXnewdsa
Creates a new DSA configuration, generating the initialization, database, and
knowledge files, and creating the database if necessary
DXnewdb
Creates a new database including the tables that DXserver requires
DXextenddb
Adds extra Advantage Ingres locations to a database
DXdestroydb
Destroys an existing database
DXemptydb
Destroys all data in a database
DXbackupdb
Creates a checkpoint of a database
DXrestoredb
Recovers a database from the last checkpoint
DXtunedb
Modifies indexes and collects statistics and tunes a database
DXindexdb
Adds or removes wide indexes, certificate component indexes, and reverse
indexes
DXstatdb
Displays statistics for a database
DXlistdb
Displays a list of databases owned by the user
DXadduser
Adds a new database administrator
10–2
Database Tools
DXdeluser
Deletes an existing database administrator
DXloaddb
Loads (or reloads) an existing database from an LDIF file
DXdumpdb
Extracts data from a database into an LDIF file
DXgrantdb
Grants a particular user access to a database
DXupgradedb
Migrates the database to the current version
DXdisp
Initializes multiwrite DISP recovery
DXcertgen
Reports on currently configured certificates and generates new DSA
personality certificates.
Using DXtools
10–3
Database Tools
Creating a DSA: DXnewdsa
You can create a new DSA configuration with the DXnewdsa tool using the
following command:
dxnewdsa dsaname dbname port [prefix]
where:
■
dsaname is the name of the DSA
■
dbname is the name of the database
■
port is the port number of the DSA
■
prefix is the DSA prefix
For example:
dxnewdsa mydsa mydb 12345 c AU o DemoCorp ou Sales
Example output:
Checking if the Ingres database mydb exists...
The Ingres database mydb doesn't exist. Using dxnewdb to create it...
Creating database 'mydb' . . .
Creating DBMS System Catalogs . . .
Modifying DBMS System Catalogs . . .
Creating Standard Catalog Interface . . .
Creating Front-end System Catalogs . . .
Creation of database 'mydb' completed successfully.
New database created
>> Disconnecting...
>> Connecting to database 'iidbdb'...
>> Connecting to database 'mydb'...
>> Creating DIT table...
>> Creating TREE table...
>> Creating NAME table...
>> Creating SEARCH table...
>> Creating SUBSEARCH table...
>> Creating ENTRY table...
>> Creating BLOB table...
>> Creating ATTR table...
>> Creating SUBATTR table...
>> Creating ALIAS table...
>> Creating INFO table...
>> Creating DISP table...
>> Creating DISPMODDN table...
>> Disconnecting...
>> Disconnecting...
Tuning system catalogs...
Writing the database file...
Database file written
Writing the knowledge file...
knowledge file written
Writing the initialization file...
Initialization file written
Starting the DSA...
The DSA started.
10–4
Database Tools
Creating a Database: DXnewdb
To create a new database with the DXnewdb tool, use the following command:
dxnewdb dbname
where dbname is the name of the database.
Extending a Database: DXextenddb
You can extend a database’s storage over multiple locations with the
DXextenddb utility using the following command:
dxextenddb dbname fileArea locationName
where:
■
■
■
dbname is the name of the database to extend
fileArea is the directory under which to create the additional location (must
be the absolute path name)
locationName is the name of the additional location
The DXextenddb utility is commonly used to increase the size of the database
over the current 2 GB limit for a location.
Adding Multiple
Extensions
To add multiple extensions, run DXextenddb multiple times. After you have
added all the required extensions, run DXtunedb with either the -relocate or full option. For example, on UNIX, you could use the following commands:
su – ingres
dxextenddb demo1 /local/ingres location2
dxextenddb demo1 /local/ingres location3
su – dsa
dxtunedb -relocate demo1
On Windows, you could use the following commands:
dxextenddb sampledsa c:\newlocation location2
dxtunedb -relocate sampledsa
Important! To run DXextenddb, you must be logged in as the Advantage Ingres user
(UNIX only).
Using DXtools
10–5
Database Tools
Destroying a Database: DXdestroydb
You can destroy a database that is no longer required with the DXdestroydb
utility using the following command:
dxdestroydb dbname
where dbname is the name of the database to be destroyed.
WARNING! The DXdestroydb utility removes all directory information in the database.
If you want to remove all directory information but keep the database, use DXemptydb
instead.
Important! This command also destroys checkpoints (backups) associated with the
database.
Emptying a Database: DXemptydb
You can remove all the data from a database that is no longer required with the
DXemptydb utility using the following command:
dxemptydb dbname
WARNING! The DXemptydb utility removes all data from all of the tables in the
database.
This utility differs from DXdestroydb because DXemptydb does not destroy the
database; it leaves the database tables ready to accept new data.
We recommend that you first create a backup of the database using DXbackupdb
before issuing the DXemptydb command.
10–6
Database Tools
Backing Up a Database: DXbackupdb
The DXbackupdb utility creates a checkpoint of the specified database. You can
execute the DXbackupdb utility using the following command:
dxbackupdb [+journal|-journal] [-keepold] [-deleteoldest] dbname
where:
■
■
+journal turns journaling on
■
-journal turns journaling off
■
-keepold keeps previous checkpoints
■
-deleteoldest deletes the oldest checkpoint
Important! The backup performs a database checkpoint. There must be sufficient disk
space available to save this checkpoint. Note that journaling requires additional storage.
Using the +journal and -journal options, you can enable or disable database
journaling to maintain a log of all changes made since the last checkpoint. Once
you turn journaling on, it stays on until you issue the dxbackupdb command and
the -journal option. For example:
dxbackupdb
dxbackupdb
:
dxbackupdb
:
dxbackupdb
demo
+journal demo
(no journaling)
(journaling is turned on)
demo
(journaling is still on)
-journal demo
(journaling is turned off)
Tip: To turn journaling off, the database must be offline before you run the
dxbackupdb command with the -journal option. If you run DXloaddb or
DXindexdb, you must explicitly turn journaling back on (dxbackupdb
+journal) with the database offline in order to resume journaling for all
tables.
You can run the DXbackupdb utility when the DSA is online.
Important! Backups of the database are extremely important. See the chapter
“Deploying a Directory” for more information.
Using DXtools
10–7
Database Tools
Restoring a Database: DXrestoredb
The DXrestoredb utility restores a database from a previously created
checkpoint. You can execute the DXrestoredb utility using the following
command:
dxrestoredb [+/-journal] [-list] [-fromold checkpointNumber] dbname
where:
■
dbname is the name of the database to restore
■
+journal replays the journals after the checkpoint is restored
■
-journal restores the checkpoint without replaying the journals
■
-list lists valid checkpoints.
■
-fromold checkpointNumber restores from an older backup (the default is the
most recent backup taken)
Tip: We recommend that you perform daily backups, usually at night. When
performing a restore, all DSAs that connect to the database must be shut
down.
10–8
Database Tools
Tuning a Database: DXtunedb
When populating or updating the directory, you can improve the performance of
the directory services by running the DXtunedb utility. You can execute the
DXtunedb utility with the following command:
dxtunedb [-full | -relocate] dbname
where dbname is the name of the database to tune.
The DXtunedb utility modifies the indexes, and updates statistics used by the
query optimizer.
You can run the DXtunedb utility when the DSA is online, except with the -full
option. However, it is better to tune when DSAs are not busy because tuning
consumes CPU.
Run a Full Tune
The DXtunedb utility has two options: -full and -relocate. The -full option
provides a more comprehensive tuning of the database. To run a full tune, use
the following command:
dxtunedb -full dbname
Tip: The DXtunedb utility with the -full option tunes all tables, indexes,
system tables, and statistics. All DSAs that connect to the database must be
shut down.
Enable New Locations
The -relocate option enables the use of the new locations created by
DXextenddb. Use the following command:
dxtunedb -relocate dbname
where dbname is the name of the database to be relocated.
Relocating a database is faster than performing a full tune, but less extensive in
terms of optimization.
Important! This option does not update statistics.
Using DXtools
10–9
Database Tools
Managing Indexes: DXindexdb
The DXindexdb utility is used to add, clear or list the following indexes:
■
Reverse indexes
■
Certificate component indexes
■
Certificate Revocation List (CRL) indexes
■
Wide indexes
The DXindexdb utility uses the following syntax:
dxindexdb dbname [[+ | -]reverse [attrList]]
| [[+ | -]cert [componentList]]
| [[+ | -]crl
[componentList]]
| [[+ | -]wide [attrList]]
Applying a reverse index to an attribute stores each value of that attribute in
reverse order. This aids substring searches of the type (attr=*val).
Only the first 106 characters of a value are significant in a search. If this is not
adequate, or you receive a warning to this effect in the log file, you can apply a
wide index to those attributes. For more information about wide indexes, see
Indexing Options in the chapter “General Administration.”
List Indexed Attributes,
Certificate/crl
Components
To list the currently indexed attributes, certificate/crl components and give a
list of attributes and components for indexing, specify dxindexdb with only the
database name:
dxindexdb demo
where demo is the database name.
Example output:
Reverse indexed attributes:
telephoneNumber
Component indexed attributes:
certificate(cert_version cert_issuer validity)
certificateList(crl_version crl_issuer)
Other attributes:
oc aliasedEntryName userPassword createTimestamp countryName
organizationName department givenName surname commonName
multiLineDescription cosineRfc822Mailbox
Other components:
certificate(serialNumber cert_signature subject subjectPublicKeyInfo
issuerUniqueIdentifier etc...)
certificateList(thisUpdate nextUpdate etc...)
10–10
Database Tools
Clear Existing Indexes
To clear all the existing reverse, wide, and certificate/CRL indexes, use any of
the options with no arguments:
dxindexdb demo –reverse
dxindexdb demo –cert
dxindexdb demo -crl
Add Reverse-Index
Attributes
To create one or more reverse-index attributes, use the -reverse option followed
by a space-separated list of the attributes:
dxindexdb demo -reverse attribute1 attribute2
Note: This will clear any previous reverse indexes.
To add one or more reverse-index attributes to an existing set, use the +reverse
option followed by a space-separated list of attributes:
dxindexdb demo +reverse attribute1 attribute2
This will add the new reverse indexes to the previous reverse indexes.
Add Certificate
Component Indexes
To create one or more certificate component indexes, use the -cert option
followed by a space-separated list of the components:
dxindexdb demo -cert component1 component2
Note: This will clear any previous certificate component indexes.
To add one or more certificate component indexes to an existing set, use the +cert
option followed by a space-separated list of components:
dxindexdb demo +cert component1 component2
This will add the new certificate component indexes to the previous certificate
component indexes.
Add crl Component
Index
To create one or more CRL component indexes, use the -crl option followed by
a space-separated list of the components:
dxindexdb demo -crl component1 component2
Note: This will clear any previous crl component indexes.
To add one or more CRL component indexes to an existing set, use the +crl
option followed by a space-separated list of components:
dxindexdb demo +crl component1 component2
This will add the new CRL component indexes to the previous CRL component indexes.
Using DXtools
10–11
Database Tools
Add Reverse and
Component Index
When both reverse and component indexing is required, a single command
must be used to set up the indexes:
dxindexdb demo -reverse attribute1 attribute2 -cert component1 component2
If a reverse index is added using the following command, all component indexes
will be removed:
dxindexdb demo -reverse attribute1
Add Wide Index
To add a wide index to one or more attributes, use the following command:
dxindexdb demo -wide attribute1 attribute2
Add Reverse and
Wide Index
10–12
When both reverse and wide indexing is required, use the following command:
dxindexdb demo -reverse attribute1 attribute2 -wide attribute1 attribute2
Database Tools
Displaying Database Statistics: DXstatdb
The DXstatdb utility displays statistics of a particular database. The DXstatdb
utility has the following format:
dxstatdb [-cert] [-d] dbname
where:
List Database Statistics
■
dbname is the name of the database for which statistics will be generated
■
-cert lists the statistics for the certificates stored in the database
■
-d includes statistics for entries marked as deleted
You can list the statistics for the database by using the following command:
dxstatdb dbname
Statistics:
Number of attributes types
Number of entries
Number of node entries
Number of leaf entries
Number of alias entries
Number of level 1 entries
Number of level 4+ entries
Number of values
Number of blob (>2K) values
List Certificate
Statistics
=
=
=
=
=
=
=
=
=
=
=
27
104472
4424
100048
0
12
58
341
104061
709281
0
You can list the statistics for the certificates stored in the database with this command:
dxstatdb -cert dbname
Certificate Statistics:
Number of userCertificate
Number of userCertificate issuers
Number of expired userCertificate
Number of not yet valid userCertificate
=
1
= Not Indexed
= Not Indexed
= Not Indexed
If there are CA Certificates and CRLs in the directory, the following output appears
(note that this output shows that the CA Certificate has a component index):
Certificate Statistics:
Number of userCertificate
Number of userCertificate issuers
Number of expired userCertificate
Number of not yet valid userCertificate
Number of cACertificate
Number of cACertificate issuers
Number of expired cACertificate
Number of not yet valid cACertificate
Number of certificateRevocationList
Number of certificateRevocationList issuers
Number of expired certificateRevocationList
Number of not yet valid certificateRevocationList
=
=
=
=
=
=
=
=
=
=
=
=
1
Not Indexed
Not Indexed
Not Indexed
1
0
0
0
1
Not Indexed
Not Indexed
Not Indexed
Using DXtools
10–13
Database Tools
List Deleted Entries
By default, the dxstatdb command ignores entries marked as deleted in the
database when reporting its statistics.
This is useful because two synchronized databases could give different statistics
because entries marked as deleted in a DISP shadow were being counted, but not
on the master.
To include entries marked as deleted in the listed statistics, use the '-d' option:
dxstatdb -d dbname
Listing Existing Databases: DXlistdb
List Databases Owned
by User
The DXlistdb utility lists the databases owned by the user. (The user must be a
database administrator—typically, the user who has created the database.) You
can execute the DXlistdb utility using the following command:
dxlistdb [dbname]
The output of a dxlistdb command is a list of database names, such as:
backup
demo
live
test
Test Database
Existence
You can test for the existence of a particular database by specifying the database
name as an optional parameter to the dxlistdb command:
dxlistdb mydatabase
If the database mydatabase does not exist then DXlistdb will return an error code.
Adding a Database User: DXadduser
You can create a new database administrator with the DXadduser utility using
the following command (this command is generally used only during
installation):
dxadduser dbadmin
where dbadmin is the name of the new database administrator.
Note: When dbadmin contains spaces, you must use quotation marks, for
example, “Fred Bloggs.”
10–14
Database Tools
Deleting a Database User: DXdeluser
You can delete a database administrator with the DXdeluser utility using the
following command:
dxdeluser dbadmin
where dbadmin is the name of the database administrator.
Note: When dbadmin contains spaces, you must use quotation marks, for
example, “Fred Bloggs.”
Using DXtools
10–15
Database Tools
Loading a Database: DXloaddb
Use the DXloaddb tool to load or reload a database from a prepared LDIF file.
This utility used to use schema.txt file to get schema information. It now loads
schema information directly from the DSA. This means that you now have to
specify the DSA name when you use the DXloaddb tool. The same change has
been made to DXdumpdb.
The command is:
dxloaddb options ldif-file dbname
The following are the options of the dxloaddb command:
Option
Description
-p prefix
The prefix of the DSA. Use a comma-separated LDAP format.
Use a pair of quotes “” for a NULL DN.
If a portion of prefix is more than one word, you can enclose the whole prefix in
quotes or just the problem portion. For example, both of these prefixes will
work:
■
o=“democorp test”,c=au
■
“o=democorp test,c=au”
-O
Includes standard operational attributes during the load.
-P
Hashes or encrypts passwords if in clear text:
-I "not-searchable
<attrlist>"
10–16
0:
OEM hash algorithm. This option is deprecated - use SHA-1 instead.
1:
SHA-1 (default)
2:
Salted SHA-1. This produces a different hash even for the same clear text
password, which is more secure.
3:
OEM-reversible crypt algorithm (therefore less secure)
4:
Traditional UNIX crypt algorithm
5:
MD5 password hashing
Prevents the attributes listed from loading into the search table, which reducing
the size of the search table. Small table size means less disk space used, faster
tuning, and faster loading. Also, update operations are faster on these attributes.
Search operations containing these attributes will return empty results. The list
of attributes must match those set in the database configuration file. For
information about how to make attributes not searchable, see Indexing Options
in the chapter “General Administration.”
Database Tools
Option
Description
-a attributes
The estimated average number of attributes per entry. This corresponds to the
average number of lines per entry in the LDIF file.
-n entries
The estimated number of entries.
-S dsaname
The DSA server with the schema definitions that the DXloaddb tool will use.
If you do not include this option, the DXloaddb tool parses the various
DXserver configurations to find the one that connects to the database specified.
database
The name of the database to load.
WARNING! If you use this option, all existing directory information in the database
will be lost.
The following are the parameters of the dxloaddb command:
Parameter
Description
ldif-file
The name of the LDIF file to use.
dbname
The name of the database to load.
The number of entries and the number of rows per entry are used to estimate the
size of each database table in advance. This enables the database to allocate the
appropriate resources before the load commences, greatly reducing load time.
The correct sequence in which to create and load a database is:
dxnewdb
dxextenddb
dxloaddb
(as many times as needed)
Note: There is no need to reorganize or tune the database since this is done
automatically as part of the DXloaddb process. Sort the LDIF file by
distinguished name, in ascending order.
The following example loads the data from democorp.ldif file to database
democorp:
dxloaddb –p "o=democorp test,c=au" -I "not-searchable
createTimestamp,userPassword" -S democorp democorp.ldif democorp
In this example, “o=democorp test,c=au” is the DN prefix, and the
createTimestamp and userPassword attributes are not searchable.
Using DXtools
10–17
Database Tools
Dumping a Database: DXdumpdb
Use the DXdumpdb utility to extract the data from a database to an LDIF file.
This utility used to use schema.txt file to get schema information. It now loads
schema information directly from the DSA. This means that you now have to
specify the DSA name when you use DXdumpdb. The same change has been
made to the DXloaddb tool.
The command is:
dxdumpdb options dbname [attributes]
The following are the options of the dxdumpdb command:
Option
Description
-p prefix
The prefix of the DSA. Use a comma-separated LDAP format.
If a portion of prefix is more than one word, you can enclose the whole prefix
in quotes or just the problem portion. For example, both of these prefixes will
work:
■
o=“democorp test”,c=au
■
“o=democorp test,c=au”
The prefix you specified doesn’t have to be the same as in the database. That is,
you can change the prefix to suit your needs.
-Z schema
Uses the schema file specified.
-f outfile
Dumps the data to the specified file.
-i
Includes attributes.
-O
Includes standard operational attributes.
-x
Excludes attributes.
-v
Run in verbose mode. This switches on error/status tracing.
-l
Locks the database while doing the dump.
-u
Username used to connect to the database.
-P passwd
The user’s Advantage Ingres password.
-E eidlist
Dumps only the entries specified. Eidlist is a comma-separated entry id list, for
example, “0,1,2…9”.
-S dsaname
The DSA server with the schema definitions that DXdumpdb will use.
If you do not include this option, DXdumpdb parses the various DXserver
configurations to find the one that connects to the database specified.
10–18
Database Tools
The following are the parameters of the dxdumpdb command:
Parameter
Description
dbname
The name of the database to dump.
attributes
Space-separated list of attributes that you want to include or exclude in the
dump (if no attribute list is given, you dump all).
The following example extracts the LDIF format data from database democorp
on the screen, using the o=”democorp test”,c=au DN prefix, and excludes the
createTimstamp and userPassword attributes in the output.
Dxdumpdb –p o=”democorp test”,c=au –x democorp -S democorp createTimestamp
userPassword
The following example extracts the first three entries from database democorp to
the out.ldif file, using the o=”democorp test”,c=au DN prefix.
Dxdumpdb –p o=Admin,c=au –f out.ldif
-S democorp –E 0,1,2 democorp
Granting Access to a Database: DXgrantdb
Use this command to grant a nominated user access to a database with the
DXgrantdb utility:
dxgrantdb dbname [user]
where:
■
■
dbname is the name of the database to which you are granting access
user is the name of the user to whom you are granting access
Note: If you omit the user name, all database users are granted access.
Revoking Access to a Database: DXrevokedb
Use this command to remove the permission for the nominated user to access a
database with the DXrevokedb utility:
dxrevokedb dbname [user]
where:
■
dbname is the name of the database to which access is revoked.
■
user is the name of the user whose access is revoked.
Note: If you omit the user name, all database users will have their access
revoked.
Using DXtools
10–19
Database Tools
Upgrading Previous Versions of a Database: DXupgradedb
After upgrading eTrust Directory, existing databases may require changes to
enable new features to work. For example, you may need to add new tables,
upgrade existing indexes, or update existing tables.
To upgrade a database, use the following command:
dxupgradedb dbname
where dbname is the name of the database that you want to upgrade.
Note: You must run DXupgradedb before starting the server.
Initializing Multiwrite–DISP Recovery: DXdisp
When multi-write-disp-recovery = TRUE, and you reload a DSA, or remove a
DSA from the multiwrite-DISP configuration, you must clear the last update time
using the following command:
dxdisp -clear dsaname dbname
where:
■
dsaname is the name of the newly loaded or removed DSA
■
To list the last update times of all multiwrite-DISP peers recorded in the
database, use the following command:
dxdisp -list dbname
where dbname is the name of the database for which you want to list the last
update times.
10–20
Database Tools
Reporting On and Generating Certificates: DXcertgen
The DXcertgen tool reports on currently configured certificates and generates
new DSA personality certificates and directory user certificates.
The command is:
dxcertgen options [report|generate]
The following are the options of the dxcertgen command:
Option
Description
-d days
Number of days certificate will be valid for(default days=365)
-i issuer
Generate root certificate with YOUR company's name (default:
"CN=Certificate Authority,O=DXCertGenPKI,C=AU")
-c clientcerts
Path to client certificate and private key store (default:
"$DXHOME/../jxplorer/security/clientcerts")
-C clientpass
Password for clientcerts keystore (default: <JXplorer clientcerts default>)
-s cacerts
Path to CA certificate and private key store (default:
"$DXHOME/../jxplorer/security/cacerts")
-S capass
Password for cacerts key store (default: <JXplorer cacerts default>)
-u users
LDIF file of users to generate certificates for
-p path
Write user certificates to path rather than keystore
-P keypass
Assign this password to protect private key (default: dxcertgen)
The following are the parameters of the dxcertgen command:
Parameter
Description
report
Report on configured certificates
certs
Generate certificates for DSAs (and 'users' if specified)
Using DXtools
10–21
Database Tools
Reporting Certificates
The certificate report shows who the subject of the certificate is, the Certificate
Authority who issued it, validity dates and whether the certificate is currently
valid.
Where there are multiple certificates in a file, they are numbered in the order
they are found. If you have to delete a certificate, use the report to determine
which one to delete.
To run a report on the currently configured certificates enter the command:
dxcertgen report <enter>
You will see a report like this:
TRUSTED ROOT CERTIFICATES
- trusted.pem certificate : 1
version
: 3
serialNum
: 0
issuer
: /C=AU/O=MiniPKI/CN=Certificate Authority
notBefore
: May 29 01:36:03 2003 GMT
notAfter
: May 27 01:36:03 2008 GMT
subject
status
: valid
PERSONALITY CERTIFICATES
- router.pem certificate : 1
version
: 1
serialNum
: 4
issuer
notBefore
: May 29 01:36:13 2003 GMT
notAfter
: May 27 01:36:13 2008 GMT
subject
: /C=AU/CN=DXserver
status
: valid
- democorp.pem certificate : 1
version
: 1
serialNum
: 1
issuer
notBefore
: May 29 01:36:07 2003 GMT
notAfter
: May 27 01:36:07 2008 GMT
subject
: /C=AU/O=Democorp/CN=DXserver
status
: valid
- uddi.pem certificate :
version
:
serialNum
:
issuer
:
notBefore
:
notAfter
:
subject
:
status
:
1
1
5
/C=AU/O=MiniPKI/CN=Certificate Authority
May 29 01:36:15 2003 GMT
May 27 01:36:15 2008 GMT
/O=CA/CN=UDDI
valid
- unspsc.pem certificate : 1
version
: 1
serialNum
: 2
issuer
notBefore
: May 29 01:36:09 2003 GMT
notAfter
: May 27 01:36:09 2008 GMT
subject
: /C=AU/O=UNSPSC/CN=DXserver
status
: valid
10–22
Database Tools
- ocsp.pem certificate :
version
:
serialNum
:
issuer
:
notBefore
:
notAfter
:
subject
:
status
:
1
1
4
/C=AU/O=MiniPKI/CN=Certificate Authority
Jun 6 10:39:15 2000 GMT
Jun 5 10:39:15 2005 GMT
/C=AU/O=OCSP/CN=DXserver
valid
- sample.pem certificate : 1
version
: 1
serialNum
: 3
issuer
notBefore
: May 29 01:36:10 2003 GMT
notAfter
: May 27 01:36:10 2008 GMT
subject
: /C=AU/O=Sample/CN=DXserver
status
: valid
Done.
Generating Certificates
To secure links between DSAs using SSL encryption or SSL authentication, each
DSA needs a certificate, just as if it was a directory user. These are called DSA
personality certificates, and are stored under
$DXHOME/config/ssld/personalities.
Note: To secure the system, the private key of the root certificate used to sign all
the generated certificates is not stored or written out in any way.
The tool generates a root certificate first, checks that it doesn't already exist in the
$DXHOME/config/ssld/trusted.pem file, then appends the new root certificate
to this file. It then uses the root certificate's private key to generate a new
personality certificate for each configured DSA, using the DSA-NAME from the
$DXHOME/config/knowledge file as the subject of the certificate. Any previous
personalities will be overwritten.
Using Your Company
Name as the CA Issuer
The default Certificate Authority issuer is hardcoded into the tool:
CN=Certificate Authority,O=DXCertGenPKI,C=AU. To use your company
name instead, just use the '-i issuer' option, and specify your company name as
an LDAP DN.
By default, the validity period for the certificates generated is 365 days, but you
can change by using the -d option.
Using DXtools
10–23
Database Tools
Generating
Certificates for eTrust
Directory Users
To generate user certificates and private keys, use the -u option. This should be
the complete path to an LDIF file of users. The user certificates will be
generated using the same root certificate's private key as the DSA personalities.
To write the user certificates and private keys to the file system, enter the
command:
dxcertgen -i "cn=Real Company Certificate Authority,o=Real Company PKI,c=au" -d
730 -u $USERS_PATH/users.ldif -p $TEMP_PATH/users certs <enter>
WARNING! The private keys that are written out are not password protected or
encrypted in any way - they should be moved as soon as possible.
Generating
Personality
Certificates for DSAs
To generate personality certificates for currently configured DSAs, enter the
command:
dxcertgen -i "cn=Real Company Certificate Authority,o=Real Company PKI,c=au" -d
730 certs <enter>
You will see the following output:
Generating a new trusted root certificate...
Generating a 1024-bit RSA public/private key pair...
...................................++++++
...............++++++
Appending trusted root certificate to
/.../products/dxserver/config/ssld/trusted.pem...
Generating dxserver personalities...
Generating a new personality certificate for democorp.dxc...
.............++++++
....................................................++++++
Writing personality certificate to
/.../products/dxserver/config/ssld/personalities/democorp.pem...
Generating a new personality certificate for router.dxc...
.++++++
................................++++++
/.../products/dxserver/config/ssld/personalities/router.pem...
Generating a new personality certificate for unspsc.dxc...
.++++++
................................++++++
/.../products/dxserver/config/ssld/personalities/unspsc.pem...
Done.
10–24
Database Tools
Wiring User
Certificates and
Private Keys to a
Secure Location
To generate user certificates and private keys and write them to a more secure
location, DXcertgen is able to use the keytool facility that ships with Java and
JXplorer to add the certificates and private keys to a "keystore". The keystore is
password protected and each private key is password protected as well. The
certificates and keys are separated out into "client" or user certificates/keys and
CA/self-signed/root certificates/keys.
By default the tool writes the certificates and private keys to the JXplorer
keystore, but you can specify alternate keystores. To specify an alternate keystore
for CA certs, use the '-s cacerts' option to enter the complete path to the CA
keystore. Don't forget to specify the CA certificates keystore password using '-S
capass'. To specify an alternate keystore for client certificates, use the '-c
clientcerts' option. Don't forget to specify the client certificates keystore
password using the '-C clientpass' option.
Specifying an
Alternate Private Key
Password
To specify an alternate private key password use the '-P keypass' option.
Note: JAVA_HOME must be set because the tool must run
$JAVA_HOME/bin/keytool to add the certificates and private keys to the
keystore.
To write certificates to the JXplorer keystore, enter the command:
dxcertgen -u "%DXHOME%\samples\democorp\users.ldi" certs
Generating a new trusted root certificate...
....................++++++
Appending trusted root certificate to D:\Program Files\CA\eTrust Directory\dxser
ver\config\ssld\trusted.pem...
Adding alias 'trusted' to keystore...
Certificate was added to keystore
Generating dxserver personalities...
Generating a new personality certificate for router.dxc...
....................................++++++
Writing personality certificate to D:\Program Files\CA\eTrust Directory\dxserver
\config\ssld\personalities\router.pem...
Generating a new personality certificate for unspsc.dxc...
..................................................++++++
Writing personality certificate to D:\Program Files\CA\eTrust Directory\dxserver
\config\ssld\personalities\unspsc.pem...
Generating user certificates...
Generating a new user certificate for Nadia_KITE...
..++++++
................................................++++++
Adding alias 'Nadia_KITE' to keystore...
Generating a new user certificate for Jodie_LAY...
Using DXtools
10–25
Database Tools
................................................++++++
.......................++++++
Adding alias 'Jodie_LAY' to keystore...
Generating a new user certificate for Vivienne_LEVER...
....++++++
.......................................++++++
Adding alias 'Vivienne_LEVER' to keystore...
Generating a new user certificate for Juliet_LEVY...
...................++++++
.++++++
Adding alias 'Juliet_LEVY' to keystore...
Generating a new user certificate for Craig_LINK...
..................++++++
......++++++
Adding alias 'Craig_LINK' to keystore...
Generating a new user certificate for Gavin_LOWE...
................++++++
................................................++++++
Adding alias 'Gavin_LOWE' to keystore...
Done.
10–26
LDIF Tools
LDIF Tools
The DXtools manage directory data using the LDAP Data Interchange Format
(LDIF). The LDIF file format is suitable for describing directory information or
modifications made to directory information. It is often used for transferring
directory information between LDAP-based directory servers or describing a set
of changes applied to a directory.
This section describes how you can transfer comma-separated value (CSV) data
files into LDIF directory files using the data conversion tools.
The data conversion tools are:
csv2ldif
Uses the CSV data file and the LDIF template file to prepare an LDIF file for
the dxmodify tool
ldifsort
Sorts an LDIF file or input stream on the given attribute type
ldifdelta
Calculates the change, or delta, between two LDIF files
CSV Source Data
A source data file is a comma-separated list of values. Each source data (CSV) file
can contain many lines, and each line in the file should contain information
about a single object or entry.
DXtools Example 1
CSV Data File
Fred,Jones,Manager,Administration,987 6254
Tom,Smith,Sales Person,Sales,987 6251
Bill,Smith,Foreman,Manufacturing,987 6257
Ken,Anderson,Account Manager,Sales,987 6255
Wendy,Murphy,Clerk,Administration,987 6233
Ann,Thompson,Receptionist,Administration,987 6222
Ian,Hall,Boilermaker,Manufacturing,987 6510
Linda,Bates,Accountant,Administration,987 6511
Sam,Campbell,Welder,Manufacturing,987,6510
Using DXtools
10–27
LDIF Tools
While the default separator is a comma, the DXtools support the use of
alternative and user-defined separators. See Converting CSV Data to LDIF
Format: csv2ldif in this chapter for more information.
You should enclose embedded commas within quotes. For example, if Tom
Smith's address is contained as a single field, you can include embedded commas
in the single address field as shown below:
Tom,Smith,"36 High Street,Boystown,NY"
To accommodate embedded quotation marks, as when applied to a property
name in an address field, always use two sequential quotation marks to
represent a single quotation mark in text. For example, if Tom Smith used his
property name “The Grange” in his address:
Tom,Smith,"""The Grange"",High Street,Boystown,NY"
Template Files (LDT)
The information contained in a data file is simply a list of values. To give
meanings to these values, you must specify what the values in each field
represent. To do this, define an LDIF template (LDT) file.
The LDT files describe the objects contained in the directory. The LDT file
follows the LDIF file format, which is used to add directory information to the
data values. An LDIF file consists of a series of records separated by blank lines.
A record consists of a sequence of lines describing a directory entry. Special
substitution tokens are used to place fields from the CSV file into the LDT.
Each line in the LDT file defines a rule that links a field in a CSV data file to a
directory attribute or name with an object description. These rules let the tools
translate CSV file information into LDIF file formats.
DXtools Example 2
A sample LDIF Template File
# Acme template file - LDIF format
dn:ou=$4, o="Acme", c=US
oc:organizationalUnit
dn:cn=$1 $2, ou=$4, o="Acme", c=US
oc:organizationalPerson
surname:$2
title:$3
telephonenumber:+61 3 $5
10–28
LDIF Tools
The Format of LDT files
Each record in an LDT file specifies the format of entries at that level. Each
record contains a DN and one or more attribute-value template lines.
You can treat the $ character literally when the escape character (\) precedes it.
This escape character has no significance other than escaping. Use \\ to
represent the \ character.
Using substitution tokens in the DN line lets you specify leaf nodes and their
parents. You can therefore infer hierarchy from the original CSV data. You must
explicitly code parent objects in the template file, and they must appear in
increasing-depth order in the file before any definition of leaf objects.
If you need a literal number following a substitution token, you can use the
three-digit form of the token as in the following example (the three-digit form is
shown underlined):
# leaf node
dn:cn=$1 $2,ou=$4, o=DemoCorp,c=AU
oc:organizationalPerson
Surname:$2
Description: $00199 \$ $2 \$ $3
Telephone:+61 $3
A substitution token cannot exceed three digits (maximum is $999). When this
LDT file is interpreted, the $00199 looks at the first three digits after the $ (in this
example $001 is equal to $1), so the program finds the first column of the CSV to
substitute, and appends "99" characters to it. If you use $199 rather than $00199,
the 199th column of the CSV is used to substitute, which is not the intention of
this example.
LDIF Files
Using the LDIF format, you can convey directory information or a description of
a set of changes made to directory entries. An LDIF file consists of a series of
records with line separators. Each record consists of a sequence of lines
describing either a directory entry or a set of changes to a single directory entry.
These two types of records cannot be mixed in an LDIF file. An LDIF file contains
either records that specify a set of directory entries or records that specify a set of
changes you apply to directory entries, but not both.
For further information about the LDIF format, review the Internet Engineering
Task Force (IETF) draft Request For Comments (RFCs) available at
http://www.ietf.org.
Using DXtools
10–29
LDIF Tools
Converting CSV Data to LDIF Format: csv2ldif
The csv2ldif tool uses the CSV data file and the template LDT file described in the
preceding two sections to prepare an LDIF file for the DXmodify tool.
The format is:
csv2ldif options numfields LDTfile CSVfile
The following are the options of the csv2ldif command:
Option
Description
-b badfile
Output file name for CSV lines with bad format.
-d
Permits duplicate parent nodes to be generated.
-f branching factor
The number of branching factors. The default is 32.
Note: This is a low-level option and should not be used unless directed by
Computer Associates Technical Support.
-i lines
Ignores the first lines lines of the CSV file.
-s sep
Defines a field separator (default is a comma)
The following are the parameters of the csv2ldif command:
Parameter
Description
Numfields
Total number of fields defined in the input CSV file.
LDTfile
Name of the LDT file.
CSVfile
Name of the input CSV file.
DXtools Example 3
csv2ldif
Using the example CSV data file and the LDT file, you can execute the csv2ldif
utility using the following command:
csv2ldif -i 1 7 acme.ldt acme.csv > acme.ldi
The file acme.ldt contains the specification and translation rules. The file
acme.csv contains the raw data in comma-separated value format. The CSV file is
defined as having seven fields with the first line ignored.
10–30
LDIF Tools
The output is redirected to the acme.ldi file. The following is a portion of
acme.ldi:
dn: o=Acme, c=US
oc: organization
dn: ou=Administration, o=Acme, c=US
oc: organizationalUnit
dn: cn=Fred Jones, ou=Administration, o=Acme, c=US
oc: organizationalPerson
postalAddress: 11 Main Street $ Newtown
surname: Jones
title: Manager
telephonenumber: +1 (305) 987 6254
dn: ou=Sales, o=Acme, c=US
oc: organizationalUnit
Sorting an LDIF File: ldifsort
The ldifsort program sorts an LDIF file or input stream for the given attribute
type. The default sort is DN, which sorts LDIF records based on their
distinguished names. In DN sort mode, ldifsort ensures that each record is
followed by its immediate subordinates.
The other sort option is to sort in descending order. You can use this option, for
example, when deleting the entries in an LDIF file from the directory. This sorts
the LDIF file on DN in descending order, thus ordering subordinates before
superior entries. The LDIF file can then be passed to DXmodify to delete these
entries.
Note: By default, duplicate entries are ignored or written to the bad record file
(-b file). If you do not want to ignore duplicate entries, use the -U option.
By default, the sort attribute is DN, but any attribute can be specified. You can
use another attribute, for example, to sort employee records in an LDIF file based
on their employee numbers for administration, or to sort based on telephone
numbers to allocate spare lines.
You must use ldifsort before ldifdelta to sort both input files to ldifdelta in the
same order.
ldifsort has the following command-line format:
ldifsort [options] infile [outfile]
Using DXtools
10–31
LDIF Tools
The options of the ldifsort command are:
Option
Description
-d
Sorts in descending order. The default is to sort in ascending order.
-v
Runs in verbose mode (diagnostics to standard error).
-U
Does not ignore (filter out) duplicate entries.
-a attr
Sorts entries based on the attribute attr. The default sort attribute is dn.
-b file
Writes duplicate or bad input records to file.
-m count
The number of records in each bucket. The default is 200. For best results, we
recommend that you set this option to the square root of the number of entries
in the file
(-m count = √ number of entries in file).
-r block
Number of buckets to allocate at a time. The default is 10,000.
-s bytes
Size of read buffer for each bucket. The default is 2,048 (2k).
-t dir
Uses the directory dir for temporary files.
The parameters of the ldifsort command are:
Parameter
Description
infile
The file to be sorted.
outfile
The file to which output is to be written. The default is to write output to
standard out.
DXtools Example 4
ldifsort
Make the old directory the same as the reference directory:
dxsearch -L -h oldhost "(oc=*)" > old.ldif
dxsearch -L -h referencehost "(oc=*)" > ref.ldif
ldifsort ref.ldif ref_sorted.ldif
ldifdelta old_sorted.ldif ref_sorted.ldif | dxmodify -h oldhost
10–32
LDIF Tools
Calculating the Change Between Two LDIF Files: ldifdelta
Use this tool to calculate the change, or delta, between two LDIF files. The
ldifdelta program is an offline directory synchronization tool based on the LDAP
directory interchange format. You can use ldifdelta to fully or partially
synchronize directories.
The output file produced by ldifdelta is an LDIF file containing LDIF change
records. You can apply the output file against the outdated directory with the
DXmodify tool to update it with respect to the reference directory.
The format is:
ldifdelta [options] oldfile newfile [outfile]
The following are the parameters of the ldifdelta command:
Parameter
Description
oldfile
The outdated file.
newfile
The more recent file to compare against oldfile.
outfile
The output file containing the differences between newfile
and oldfile.
The following are the options of the ldifdelta command:
Option
Description
-x
Ignores X.500 operational attributes.
-v
Verbose output.
-Z schema
File containing schema definitions.
You must do two things before using the ldifdelta tool:
1.
Obtain the two required input LDIF files by using either the -L option with
the DXsearch utility or the DXdump utility.
2.
Sort the input LDIF data files using the ldifsort tool.
Using DXtools
10–33
LDIF Tools
DXtools Example 5
Using ldifdelta and ldifsort Together
Make the old directory the same as the reference directory:
dxsearch -L -h oldhost "(oc=*)" > old.ldif
dxsearch -L -h referencehost "(oc=*)" > ref.ldif
ldifsort ref.ldif ref_sorted.ldif
ldifdelta old_sorted.ldif ref_sorted.ldif | dxmodify -h oldhost
The following are known limitations of the ldifdelta tool:
■
■
10–34
Compares distinguished name in a case insensitive way, not by schema
matching rules.
When comparing URL values, ldifdelta compares only the file names. It does
not attempt to interpret the nature or contents of the file that the URL
references.
DAP Tools
DAP Tools
The DAP import and export tools each work with LDIF files. The import tools
(DXmodify, DXrename, and DXdelete) generate updates of the directory, usually
from data in an LDIF file. The export tool (DXsearch) extracts data from the
directory and creates an LDIF file that contains the extracted data.
DXmodify
DXrename
Directory
DXsearch
LDIF
DXdelete
The following are the import and export tools:
DXmodify
Populates an empty directory; adds new entries; adds new attributes to
existing entries; modifies, renames, or deletes attributes of an entry
DXrename
Changes the common name of a directory entry
DXdelete
Deletes one or more directory entries
DXsearch
Searches a specified directory using defined filters
Note: These tools use the X.500 DAP/OSI protocol. They are similar to the public
domain LDAP tools (ldapsearch, ldapmodify, ldaprename and ldapdelete) but
offer more features.
Using DXtools
10–35
DAP Tools
Common Command Options
The following command arguments are common to the import and export tools:
Option
Value
-D binddn
Distinguished name of the user performing the bind.
-c
Continuous operation mode.
-n
Shows what would be done, but does not actually do it.
-Z schema
File containing schema definitions.
-v
Runs in verbose mode.
-f file
Reads file rather than standard input.
-w password
Bind password (for simple authentication).
-h daphost
Directory server (default is localhost).
-p dapport
Port on directory server (default is 102, the OSI port).
-H
Usage and option information is displayed.
-l timelim
Time limit (in seconds) of search.
You can include OSI addressing for transport, session, and presentation SAPs by
fully expanding the daphost:
hostname:portnumber/tsel/ssel/psel
You can include binary and ASCII characters in the tsel, ssel, and psel selectors.
The % is an escape character followed by two hexadecimal digits:
■
/ is expressed as %2F
■
% is expressed as %25
If you do not provide values for the binddn and password, the DXtools bind
anonymously.
You can combine the daphost and daport arguments into the daphost argument
only and express them as a dotted IP address or hostname. For example:
-h 192.168.19.202 -p 19389
can be expressed as:
-h hostname:1900
The examples in the following command descriptions are directed to the sample
DemoCorp directory supplied with DXserver. You can repeat the examples as a
training exercise.
10–36
DAP Tools
Searching a Directory: DXsearch
The DXsearch tool searches a specified directory using defined filters. You can
specify search output as LDIF or text, or you can have each returned attribute
written to a file.
The format is:
dxsearch [options] filter [attributes]
The following are the available options for dxsearch:
Option
Meaning
-t dir
Writes values to files in the given directory.
-e
Sorts entries by depth (shallowest first).
-E
Sorts entries by depth (deepest first).
-A
Retrieves attribute names only (no values).
-N
Retrieves distinguished names only (no attributes).
-M
Does not multicast; limits search to a single directory.
-O
Retrieves all operational attributes.
-B
Does not suppress printing of non-ASCII values.
-T
Times the search (no search results printed).
-L
Prints entries in LDIF format (-B is implied).
-F sep
Prints sep instead of = between attribute names and values.
-b basedn
Base DN for search.
-s scope
Either base, one, or sub (search scope).
-a deref
Alias dereferencing; one of the keywords never, always, search, or
find.
-z sizelim
Size limit (in entries) for search.
The following are additional arguments for dxsearch:
Argument
Value
filter
RFC2254-compliant LDAP search filter.
attributes
Space-separated list of attributes you retrieve (when no attribute
list is given, you retrieve all).
Using DXtools
10–37
DAP Tools
DXtools Example 6
DXsearch
%dxsearch -L -h 192.168.19.202:19389 "(sn=horsfall)"
dn: cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU
oc: newPilotPerson
oc: quipuObject
cn: Murray HORSFALL
sn: HORSFALL
title: Information Technology Manager
telephone: 797 8877
description: Replacements
mail: Murray.HORSFALL@DemoCorp.com
postalAddress: 173 Toorak Pde $ Berkeley NSW
postalCode: 2506
If, in the previous example, you send the output to an LDIF file, you can edit the
file contents and use the DXmodify tool to implement the changes.
dxsearch -L -h yourhost:19389 "(sn=horsfall)" > h-modify.ldi
Reporting on Certificate and CRL Indexes: DXcert
The DXcert utility searches a directory for certificates and/or crls using defined
filters. You can specify search output as LDIF or text, or you can have the results
written to a file.
DXcert lists the results, with the specified certificate/crl components returned as
attributes.
Note: You must run DXindexdb before generating each report or batch of reports
to update the certificate/crl components indexes.
The format is:
dxcert options report -cert [component1 component2 ...] -crl [component1 component2 ...] filter
attributes]
10–38
DAP Tools
Modifying a Directory: DXmodify
You can populate an empty directory, add complete new entries, add new
attributes to existing entries, modify, rename, or delete attributes of an entry
using the DXmodify tool. The key to DXmodify is the structure of the LDIF entry.
The tool DXmodify supports entry from standard input or an LDIF file. We
recommend using an LDIF file.
The format is:
dxmodify [options]
The following are the options for dxmodify:
Option
Meaning
-a
Add mode. The default is to add entries to the directory.
-r
Replace mode. The default is to replace entries in the directory
rather than add values.
-F
Forces use of all change records.
-q
Quiet mode, does not report successfully added or modified DNs
-s period
Sleeps for period (ms) after each operation
-O
Includes operational attributes.
The structure of the LDIF file specifies the modify action to take for each listed
attribute. When you do not specify a modify action, the system applies a default
action as specified in the command line. The available options are adding (-a) or
replacing (-r). This function is especially useful for importing large amounts of
data.
Note: When you do not specify a file name, the system waits for input.
DXtools Example 7
DXmodify
You can make multiple changes, such as changing the title and postal address,
adding a second telephone number, and deleting the description of an entry.
First, edit the contents of the output file h-modify.ldi from DXtools Example 6:
dn: cn=Murray HORSFALL,
ou=Repair,ou=Operations,o=DemoCorp,c=AU
changetype: modify
replace: title
title: Chief Information Officer
add: telephone
telephone: 797 8888
delete: description
Using DXtools
10–39
DAP Tools
replace: postalAddress
postalAddress: 173 Toorak Rd $ South Yarra
postalCode: 3066
This example shows that you can replace the values of multiple attributes using
one replace statement as long as the replace statement specifies the first attribute
name in the series.
Then we use DXmodify to apply the edited file as follows:
dxmodify -h localhost:19389 -f h-modify.ldi
modifying entry cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU
Loading Binary Files: DXmodify
You can also use the DXmodify tool to load binary files.
To add a binary file, first decide on the directory schema object class and
attribute to use to hold the binary data—for example, the cosineJpegPhoto
attribute within the cosinePilotObject object class.
Next, create entries in an LDIF file with the following syntax:
attributeName:< FILE://path
Dxtools Example 8
DXmodify with Binary Files
In this example, we will add a JPEG file with a personnel record from staff.ldif.
For JPEG files, the object class is cosinePilotObject, the X.500 attribute name is
cosineJpegPhoto, and the LDAP attribute name is JpegPhoto.
Create an LDIF file (staff.ldif) with the following form:
dn: cn=Peter Bell,ou=Infrastructure,ou=Support,o=DemoCorp,c=AU
oc: newPilotPerson
oc: cosinePilotObject
cn: Peter Bell
sn: BELL
cosineJpegPhoto:< FILE://d:\temp\PHOTO\BELPE01.jpg
title: Design Supervisor
telephone: 881 9256
description: Computing
mail: Peter.BELL@DemoCorp.com
postalAddress: 7-11 Fine Street$Penville CA
postalCode: 32750
Run the following dxmodify command:
dxmodify -a -c -h hostname:19389 -f staff.ldif
10–40
DAP Tools
Renaming a Directory Entry: DXrename
You can change the common name of a directory entry using the DXrename tool.
You can source the rename data for a single entry from the keyboard or source
multiple entries by using input from a file.
The format is:
dxrename [options] [dn newdn]
where:
■
-r removes the old RDN
■
dn is the distinguished name of the entry that is to be renamed
■
newrdn is the new RDN
Note: When a file name is not specified, the system will wait for input. The
content format for standard input and the file consists of multiple lines, and each
line is a unique distinguished name. The first line is the old distinguished name,
the second line is the new distinguished name, the third line is the old
distinguished name, and so on.
DXtools Example 9
DXrename
Consider an example entry Murray Horsfall and change the rdn to insert a
middle initial J. The example uses the input file option. The example file name is
filename.txt, shown below:
cn=Murray HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU
cn=Murray J HORSFALL
You can apply the dxrename command as follows:
dxrename -r -h hostname:1900 -f filename.txt.
and you can check the results of the rename with a DXsearch as shown below:
dxsearch -L -h hostname:19389 "(sn=horsfall)"
dn: cn=Murray J HORSFALL,ou=Repair,ou=Operations,o=DemoCorp,c=AU
oc: newPilotPerson
oc: 0.9.2342.19200300.99.3.2
cn: Murray J HORSFALL
sn: HORSFALL
title: Chief Information Officer
telephone: 797 8877
telephone: 797 8888
mail: Murray.HORSFALL@DemoCorp.com
postalAddress: 173 Toorak Rd $ South Yarra
postalCode: 3066
Using DXtools
10–41
DAP Tools
Deleting a Directory Entry: DXdelete
The DXdelete tool deletes one or more directory entries. You can supply the
target DN identification by a direct command-line entry, or you can delete
multiple entries by using input from a file.
The format is:
dxdelete [options] [dn]
The following is an additional argument for dxdelete:
Argument
Value
dn
Distinguished name of entry to delete.
Note: When a file name is not specified, the system waits for input. The content
format for standard input and the file consists of multiple lines, and each line is a
unique distinguished name.
DXtools Example 10
DXdelete
To delete the entry Murray J Horsfall, enter the command as follows:
dxdelete -v -h hostname:19389 "cn=Murray J HORSFALL,ou=Repair, ou=Operations,o=DemoCorp,c=AU"
and test the execution with DXsearch.
Bulk Loading Options
Traditionally, data is imported and exported from directories using the import
and export tools described earlier (see DAP Tools in this chapter for more
information) or using openly available LDAP utilities (ldapmodify and
ldapsearch). These utilities read and write LDIF files, encode or decode the data
into DAP or LDAP, and communicate with DXserver, which then decodes the
protocol and updates the underlying RDBMS database.
Importing and exporting can be made more efficient by bypassing the encoding
and decoding processes and loading or unloading LDIF directly to the database.
The bulk tools accomplish this by converting the LDIF file into a number of data
files that represent the internal database tables.
The following bulk tools are provided:
The DXloaddb tool
Creates and loads a database from a prepared LDIF file
The DXdumpdb tool
Extracts data from the database to an LDIF file
10–42
Schema Tools
Schema Tools
The DXtools manage directory schema by making it easy to access and be
converted into proprietary formats.
The schema of the eTrust Directory server is in its schema directory (for example,
$DXHOME/config/schema), and consists up of individual schema configuration
files (.dxc) and group files (.dxg).
The schema of a running directory is available to LDAP clients through the
LDAP Version 3 mechanism of schema publishing. A convenient format in which
to extract the schema is LDIF.
After extracting the schema, you can use the schema tools to convert it into the
required format.
LDAP
dxschemaldif
Directory
Schema
LDIF
ldif2dxc
eTrust
dxschematxt
Directory
Schema
schema.txt
Schema management is required whenever the schema pertaining to a directory
is changed (for example, the addition of a new object class and its associated
attributes).
Another common case is integration with other LDAP directories. There may be
additional or different schema to incorporate in the existing directory system.
To make use of new schema, it must be made available to the directory and the
DXtools. This means a new or updated .dxc file, possibly an updated .dxg file,
and an updated schema.txt file.
The schema tools are:
DXschemaldif
Extracts published LDAP schema from LDAP directories in LDIF format
ldif2dxc
Converts LDAP schema in LDIF format into eTrust Directory server-side
format (.dxc) and optionally DXtools format (schema.txt)
DXschematxt
Converts eTrust Directory server-side schema into a schema.txt file that
DXtools uses
Using DXtools
10–43
Schema Tools
Extracting Schema in LDIF Format: DXschemaldif
Use the DXschemaldif tool to extract schema from external LDAP directories.
The tool extracts the LDAP schema in the LDIF format.
The syntax is:
dxschemaldif [-v] hostaddr:port
To get help on the tool, enter dxschemaldif with neither option nor parameter.
Typically, when using this tool, you will redirect the output from the screen to a
file.
DXtools Example 11
DXschemaldif
You want to extract the schema from a Version 3 LDAP directory and redirect
the output to the new_schema.ldif file. Enter the following command:
dxschemaldif -v ldapserver:389 > new_schema.ldif
You can use the ldif2dxc tool to convert the LDIF schema into the eTrust
Directory schema format.
10–44
Schema Tools
Converting Schema from LDIF to DXserver Format: ldif2dxc
Use the ldif2dxc tool to convert LDAP schema in LDIF format into eTrust
Directory DXserver schema configuration format (.dxc). Optionally, the tool can
also update an existing schema.txt file.
The syntax is:
ldif2dxc [options] [outfile]
To get help on the tool, enter ldif2dxc with neither options nor parameter.
The options of the ldif2dxc command are:
Option
Meaning
-b badfile
Write bad schema records to the specified file.
-f file
Read input from the specified file.
-m map
Get OIDs from the specified map file. For information about the file,
see DXtools Example 14.
-M oid_arc
Generate missing OIDs from 'oid_arc'
For example:
■
x.y.z. generates x.y.z.0, x.y.z.1, etc
■
x.y.z.34 generates x.y.z.34, x.y.z.35, etc
For more information, see Example 16.
-s
Skip reserved DXserver attributes (for example, objectClass,
userPassword, …)
-x dxcFile
Exclude schema that is defined in the specified eTrust Directory
schema file.
-Z schema
Append new schema definitions in DXtools schema file format to
the specified file.
Using DXtools
10–45
Schema Tools
DXtools Example 12
ldif2dxc
You want to convert the schema in the new_schema.ldif file from DXtools
Example 11. In this case, you are not interested in the entire external schema, but
rather schema unique to the external source. The local directory also typically
sources a single DXserver schema group file (for example, default.dxg).
To convert only the schema unique to the external source, you want to instruct
the tool to exclude an existing schema file. In addition, you want to instruct the
tool not to redefine any internal DXserver schema definitions.
Enter the following command:
ldif2dxc -f new_schema.ldif -s -x default.dxg new_schema.dxc
DXtools Example 13
ldif2dxc with Errors
While converting the schema in the new_schema.ldif file, the tool stops with an
error because of schema incompatibility with eTrust Directory and does not
produce any output. The problem may be caused by an unsupported syntax or
matching rule, or an error in the published schema. In these cases, you can
instruct the tool to write any bad schema to a bad file but continue writing the
good schema to your output file. You can inspect the bad file and decide whether
it is worthwhile to correct any of the errors (for example, remove an obscure
matching rule for substrings), and then rerun the tool until you have what you
need.
To run the tool with a bad file, enter the following command:
ldif2dxc -b bad.txt -f new_schema.ldif -s -x default.dxg new_schema.dxc
10–46
Schema Tools
DXtools Example 14
ldif2dxc with Map File
Some LDAP directories publish OIDs as labels rather than dotted decimal strings
(for example, xyConfig-oid). These object classes and attributes do not load into
the directory. Instead, the tool assigns them temporary OIDs off the eTrust
Directory arc to enable you to load the new schema, but this solution may not be
suitable for all directory implementations.
If the dotted decimal form of these object class and attribute OIDs are available,
you can create a map file, and instruct the tool to look up these label OIDs in the
file and substitute the labels by the dotted decimal OIDs.
The map file is a three-column comma-separated value (CSV) file with the
following format, for example:
------------------------------------#
# format: objectClass, attributeType, oid
#
# objectClasses
xyConfig-oid,,1.2.3.4
xyAdmin-oid,,1.2.3.5
# attributeTypes
,abstract-oid,1.2.4.5
,aci-oid,1.2.4.6
-------------------------------------
You map a dotted decimal OID to either an object class or an attribute type, but
not both.
To run the tool with a map file, enter the following command:
ldif2dxc -b bad.txt -f new_schema.ldif -m map.txt -s -x default.dxg new_schema.dxc
DXtools Example 15
ldif2dxc and the schema.txt File
If the new schema has attributes that should be searchable, or object classes and
attributes that exist as data in the directory, and you plan to use the DXtools to
search, load, or dump the directory, then you must update the schema.txt
DXtools file. While converting the schema in the new_schema.ldif file, you want
to instruct the tool to append any new schema to the existing schema.txt file. For
example, on a UNIX system, you can enter the following command:
ldif2dxc -b bad.txt -f new_schema.ldif -m map.txt -s -x default.dxg -Z
$DXHOME/bin/schema.txt new_schema.dxc
Using DXtools
10–47
Schema Tools
DXtools Example 16
ldif2dxc and label OIDs
If there are a large number of “label” OIDs (e.g. xyConfig-oid) in the LDIF
schema file it may take a long time to add an entry for everyone in a map file. An
alternative is to specify an OID arc that the tool will use in place of any label
OID, incrementing it for each label OID it finds.
If your arc is new, you can specify it with a trailing ‘.’, and the tool will start
incrementing it from 0. If some OIDs have already been assigned against this
OID arc, you can specify the next available OID, and the tool will start
incrementing from that one.
To replace the map file in Example 15 with a new OID arc of “1.22.333.444.”, on a
UNIX system, enter:
ldif2dxc -b bad.txt -f new_schema.ldif -M 1.22.333.444. -s -x default.dxg -Z
$DXHOME/bin/schema.txt new_schema.dxc
If the tool encountered the OID label xyConfig-oid in new_schema.ldif, it will
assign it an OID of 1.22.333.444.0. If it then encountered the OID label abConfigoid, it will assign it an OID of 1.22.333.444.1, etc.
If twenty OIDs from this arc were assigned, the next available OID would be
1.22.333.444.20. If you were to perform another integration with schema from
new_schema2.ldif, to avoid clashing with existing OIDs in the directory, on a
UNIX system, enter:
ldif2dxc -b bad.txt -f new_schema2.ldif -M 1.22.333.444.20 -s -x default.dxg -Z
$DXHOME/bin/schema.txt new_schema2.dxc
If the tool encountered the OID label cdConfig-oid in new_schema2.ldif, it will
assign it an OID of 1.22.333.444.20. If it then encountered the OID label efConfigoid, it will assign it an OID of 1.22.333.444.21, etc.
10–48
Schema Tools
Converting Schema from DXserver Format to DXtools Format: DXschematxt
Use the DXschematxt tool to convert DXserver schema configuration files into a
DXtools schema file. This is required when the existing DXtools schema file is
badly out of date, or is lost or corrupted.
The syntax is:
dxschematxt [options] files
To get help on the tool, enter dxschematxt with neither options nor parameters.
The options of the dxschematxt command are:
Option
Meaning
-f path
Read schema from the specified path rather than the default schema
configuration path (for example, $DXHOME/config/schema).
-Z file
Write to the specified file rather than the default scheme.txt file (for
example, $DXHOME/bin/schema.txt).
files is a list of space-separated DXserver schema configuration files that you
want to convert. The list of files can include .dxc and .dxg files. The tool will read
the schema configuration files listed in the group files.
DXtools Example 17
dxschematxt
You want to rebuild the DXtools schema.txt file in $DXHOME/bin from the
default schema group file. The tool backs up the current file automatically. Enter
the following command to instruct the tool to read from that particular file:
dxschematxt default.dxg
DXtools Example 18
dxschematxt to New DXtools Schema File
You want to build a new DXtools schema file. For example, on a UNIX system,
you can enter the following command:
dxschematxt -Z $DXHOME/bin/new_schema.txt default.dxg
DXtools Example 19
dxschematxt from Other Path
You want to build a new DXtools schema file from files in another location. For
example, on a UNIX system, you can enter the following command:
dxschematxt -Z $DXHOME/bin/new_schema.txt -f $DXHOME/config/new_schema default.dxg
experimental.dxc
Using DXtools
10–49
Directory Administration Tools
Directory Administration Tools
Checking DSA configuration: DXsyntax
DXsyntax is a tool for checking the configuration of one or more DSAs. It is most
easily run on the server hosting those DSAs, but it can be run remotely, provided
the machine running it has access to the configuration directory of the server
hosting the DSAs.
DXsyntax has only one parameter: the DSA file name. Running DXsyntax
without a parameter causes it to check the configuration of every DSA.
To check a single DSA, run DXsyntax with the name of the DSA as its parameter.
The name can be a filename pattern. For example, to check all DSAs whose
names start with rk, run DXsyntax with a parameter of rk*.
DXsyntax runs through the configuration files of each DSA in turn, reporting a
detailed error message if it finds a problem. The error message specifies the line
and file where the error was detected (the actual error may be earlier), and
provides details on the error condition. Only one error is reported for each DSA
checked, because a single error can cause a cascade of problems that is
overwhelming.
If no errors are found, DXsyntax exits without a message, and with a return code
of 0. This is handy for use in routine test scripts. If one or more errors are found,
DXsyntax exits with an error message and a non-zero return code.
DXsyntax relies on the DXHOME environment variable. DXHOME must be set
to the home path of DXserver. This is done automatically when eTrust Directory
is installed. DXsyntax expects the DSA configuration files to be located in the
config folder under the path in DXHOME.
10–50
Chapter
11
Using JXplorer
JXplorer is a general purpose LDAP-compliant directory browser. It has a simple
user interface, yet supports a wide range of powerful, configurable functions.
With the JXplorer browser, you can:
■
■
■
■
■
■
■
■
■
Connect to any directory that supports LDAP and navigate, search, and
modify the directory.
Read the directory’s schema directly, rather than relying on schema
configuration files.
Visually cut, paste, and edit subtrees in the directory, including drag and drop
on Windows platforms.
Import and export LDIF files from a directory and even manipulate them
offline.
Configure the browser in many ways, including its appearance and logging
information. For example, you can configure the look of the browser to a
company standard by using company-specific icons for the directory and
company graphics within the HTML templates.
Display directory data within configurable HTML templates using a simple
extension to the HTML language.
Run in debug mode, permitting full tracing of the LDAP BER protocol.
Run on a wide variety of operating system platforms, since JXplorer is
written in the Java programming language.
Optionally use SSL to communicate securely, and SASL for secure certificatebased authentication.
eTrust Directory is a fully functional LDAP-compliant directory that lets you use
all the features of JXplorer.
Using JXplorer
11–1
The JXplorer Browser
To start JXplorer, click Start, Programs, Computer Associates, eTrust, eTrust
Directory, JXplorer.
When you start JXplorer and connect to a directory, the main browser window
appears:
The menu bar at the top of the browser provides access to a full range of browser
functions through pull-down menus.
Two toolbars below the menu bar give shortcuts to commonly used functions.
The first is a button bar, with shortcuts to commonly used menu functions. The
second, the quick search toolbar, lets you quickly execute simple searches (such
as searching a directory for an employee’s name).
The status bar at the very bottom of the browser displays the status of the
browser. For example, it shows whether the browser is connected or not.
The main body of the browser is divided into two panes. The left pane is the
directory tree, which you can navigate by using the mouse to click the entries.
The right pane shows the selected entry from the directory, shown either as an
HTML page or as a table of attributes and values.
11–2
Menu Bar
The menu bar provides the following functions:
Menu Item
Function
File
Connect
Connects to an LDAP-compliant directory.
Disconnect
Breaks the current LDAP connection.
Print
Prints the current viewed entry.
Refresh Tree
Resets the directory tree and starts reloading entries.
Exit
Closes the browser.
Edit
New
Adds a new entry under the selected position.
Copy DN
Sends the DN of the current entry to the clipboard.
Cut Branch
Cuts the currently selected entry or subtree.
Copy Branch
Copies the currently selected entry or subtree.
Paste Branch
Pastes the previously cut or copied subtree under the
selected position.
Paste Alias
Pastes the previously copied Distinguished
Name (DN) of an entry as an alias under the selected
position.
Delete
Deletes the currently selected entry or subtree.
Rename
Lets you rename the currently selected entry.
View
Show Button Bar
Displays or hides the shortcut button bar.
Show Search Bar
Displays or hides the quick search toolbar.
Refresh
Reloads the currently selected entry from the
directory.
Bookmark
Add Bookmark
Lets you add a bookmark.
Delete Bookmark
Lets you delete a bookmark.
Edit Bookmark
Lets you edit a bookmark.
Using JXplorer
11–3
Menu Item
Function
Search
Search
Performs an advanced search.
Delete Filter
Deletes a saved filter.
Return Attribute Lists Manages the attributes that you want returned in a
search.
Filter
Lists all saved filters.
Ldif
Export Full Tree
Writes the entire directory tree to an LDIF file.
Export Subtree
Writes the currently selected subtree to an LDIF file.
Import File
Imports an existing LDIF file into the directory.
View Offline
Lets you view and edit an LDIF file in the browser.
Options
Confirm Tree
Operations
Enables a safety mode, which prompts you to
confirm modifications before they are made.
Confirm Table Editor
Updates
Enables a confirmation dialog, which appears after
you make a change to the directory.
Ignore Schema
Checking
Stops the browser checking that the user’s input
conforms to the directory schema.
Resolve Aliases While Displays the alias details such as where the alias
Browsing
entry points. This affects both browsing and
searching.
Advanced Options
Displays the Advance Options dialog, which enables
you to choose the look and feel of the browser,
logging options, and LDAP levels.
Tools
Stop Action
Cancels the current browser operation.
Security
11–4
Trusted Servers and
CAs
Displays the options for server-only authentication.
Client Certificates
Displays the options for client and server
authentication.
Advanced Keystore
Options
Displays the options for setting up keystores.
Menu Item
Function
Help
Contents
Lists the titles of help topics.
Search
Lets you search for help on a particular keyword.
About
Lists information about the JXplorer browser,
including its current version number.
Button Bar
The button bar provides shortcuts for normal menu functions.
Button
Function
Connect
Connects to an LDAP-compliant directory.
Disconnect
Breaks the current LDAP connection.
Print
Prints the currently selected entry.
Cut Branch
Cuts the currently selected entry or subtree.
Copy DN
Sends the DN of the current entry to the clipboard.
Copy Branch
Copies the currently selected entry or subtree.
Paste Branch
Pastes the previously cut or copied subtree under the
selected position.
Paste Alias
Pastes the previously copied DN of an entry as an
alias under the selected position.
Delete
Deletes the currently selected entry or subtree.
New
Adds a new entry under the selected position.
Rename
Lets you rename the selected entry.
Refresh Entry Reloads the currently selected entry from the
directory.
Cancel
Stops the current operation (such as a search or a
directory update).
Using JXplorer
11–5
Quick Search Bar
The quick search bar lets you execute simple searches.
1. Choose or
type an attribute
2. Choose
an operator
3. Type a value
to search on
4. Start the search
The operators are:
■
Equal to
=
■
Not equal to
!(=)
■
Less than or equal to
<=
■
Greater than or equal to
>=
■
Approximately equal to
~=
For more information about searching, look in Chapter 13 in the User Guide.
Displaying the Directory Tree
The tree display pane (the left pane) displays the directory tree, and allows you
to graphically browse the directory.
There are usually three tree views available:
Explore
Displays the data in the current directory
Results
Shows the results of the most recent search
Schema
Displays the schema currently in use by the directory
11–6
Browsing a Directory
With JXplorer, you can browse any LDAP-compliant directory. This section
describes the browsing functions available.
Starting JXplorer
You can run JXplorer on either a Windows or UNIX computer.
On Windows
To start JXplorer on a Windows computer, click Start on the taskbar, and then
choose Programs, Computer Associates, eTrust, eTrust Directory, JXplorer.
On UNIX
To start JXplorer on a UNIX computer, issue the following command from the
JXplorer directory:
./jxstart.sh
Connecting to a Directory
When you choose File, Connect (or click the Connect button), the browser
displays the following connection dialog, requesting the information that
JXplorer needs to connect to a directory.
The browser requires the following information to make a connection:
■
The name of the computer that hosts the directory.
■
The port number of the server on that computer.
■
The base distinguished name of the directory.
If none is given, the browser is still able to connect, providing that the
directory is one (like eTrust Directory) that makes this information available.
Using JXplorer
11–7
■
■
■
The protocol that is in use, which can be Lightweight Directory Access
Protocol (LDAP) or Directory Services Markup Language (DSML). For
LDAP, this is usually Version 3, but can be Version 2 to support older
directories.
If the DSML protocol is selected, the path to the DSML service.
The security level with which you want to connect (not applicable to DSML).
You can connect to the directory anonymously, or with your user name and
password. If you require higher security, you can establish a link to the
server using SSL with either of these methods. When a client keystore is
available, you can use full client-authenticated SSL, combined with SASL
authentication at the directory.
The browser lets you save connection details for commonly used directories as
connection templates. To save the information, supply a name (or select an existing
name from the drop-down list), and then click Save. You can save any number of
connection templates, and you can edit or delete them at any time.
You can also choose to make one of the connection templates a default template.
After you specify a default template, the connection dialog opens with the details
from that template already filled in.
Note: For security reasons, the password field is not saved in any template.
Reading Schema
After the connection details are obtained, the browser attempts to contact the
directory. When the directory is contacted, the browser obtains the directory’s
current schema (provided that an LDAP Version 3 connection has been made).
Directories that support LDAP Version 3 (such as eTrust Directory) download
the schema to the browser. This lets the browser correctly create, display, and
edit entries without requiring any independent browser configuration. Since the
browser gets the schema from the directory, it is always up-to-date, and there is
no possibility of inconsistency.
Navigating the Directory Tree
You can navigate the directory tree by mouse or keyboard.
By Mouse
To expand or collapse a subtree, click on the expansion icon (which usually
appears as a small box containing either a + or -) to the left of the entry. Doubleclick on the text portion of a tree entry to display that entry in the viewing pane.
By Keyboard
Use the arrow keys to select entries. Press Enter to expand and collapse a
subtree, or display an entry in the viewing pane.
11–8
Displaying an Entry
The entry display pane (the right pane) displays the currently selected directory
entry, either in an HTML template, or in an editable table of attributes and values.
When you select an entry, whether from the Explore view, the Results view, or
even the Schema view, the browser queries the directory for the attribute values
of the entry and displays the results in the entry display pane. The results can be
displayed either in the HTML template view or in the attribute/value table view.
The HTML Viewer
The following is an employee record displayed in an HTML template. The
template contains three tabs (Main, Address, and Other) that display the
attribute information for the selected entry.
Using Different HTML Templates
When the browser initially reads an entry, it attempts to find an appropriate
HTML template in which to display the entry, as follows:
■
■
■
■
The HTML templates key on the object classes of the entry, with each HTML
template specializing in displaying one object class.
Each object class can have multiple HTML templates capable of displaying it.
HTML templates for a given object class can also display entries whose
object classes are inherited from that object class.
When you select an HTML template for a particular entry, the browser
remembers that template and uses it for other entries of the same object class.
Using JXplorer
11–9
The number of attributes and how they are displayed depend on the HTML
template. When the HTML template does not have a tag for a particular attribute,
that attribute is not displayed. A tag is available for displaying all attributes that
have values. The tag is used to simplify the display of large numbers of
attributes.
This use of HTML templates enables:
■
Different types of entries to be displayed in ways appropriate to their type
■
Site-specific help information to be included in the HTML
■
HTML hyperlinks to be used to link to existing company resources
■
Straightforward customer configuration of data display
■
■
Special purpose templates for different types of users (administrator, help
desk, office staff, and so forth)
Use of corporate branding and logos
The Table Editor
The same employee record can be edited and displayed in the table editor.
You can also use it to view the attributes an entry can contain, because it uses
schema to show all the possible attributes that the entry might have.
Attributes in bold represent mandatory attributes – these must be present for the
entry to be valid. Click the Properties button to display operational attributes
such as the date of the last modification.
You can configure the table viewer to include custom binary editors, which may
be the only way to view complex or application-specific binary data.
11–10
Refreshing Entries
For efficiency, the browser caches entries, unless you specifically request to
reload them from the directory. You can force a single entry to be reloaded by
selecting the Refresh option. You can refresh the DIT by selecting the Refresh
Tree option.
Searching
In JXplorer, you can search for an entry in two ways. You can run a quick search
using simple criteria, or you can run a complex search that you can save to
search_filters.txt as filters. Complex searches display search results as complete
directory trees, letting you browse large numbers of search results or save them
as LDIF files.
Running a Quick Search
You can quickly execute simple, single-attribute-value searches using the quick
search bar, which contains a pull down list of common attribute types. You can
add attributes to this list; the browser saves changes to the list when you exit the
browser.
The quick search bar makes it possible to do common searches, for example,
specific employee names, part numbers, and so on, without having to access the
menu bar or enter a complete LDAP-format search request.
Running a Complex Search
You can perform more complex searches using the Search dialog.
Using JXplorer
11–11
The Search dialog lets you search one of the following:
■
The selected entry
■
The next level from the selected entry, but not including the selected entry
■
The full subtree
You can use the filter constructor to create complex searches, and then save the
details in a property file for use later. You can use the Information to retrieve
drop-down list to select the definition that contains the list of attributes you want
returned. To create these definitions, choose Return Attribute Lists from the
Search menu. For more information about how to create the lists, see the online
help.
Aliases are similar to shortcuts and are used in some directories to link different
parts of the tree. When you search aliases, JXplorer returns the real entry to
which the alias points. When you do not search aliases, JXplorer does not resolve
alias references and returns all alias entries as regular entries.
You can choose to resolve aliases while:
■
■
Searching, that is, to resolve aliases for subordinate entries of the base object
Finding the base object, that is, to resolve aliases when locating the base
object of the search
Consequently, when you check both options, all aliases are resolved, and when
you do not check an option, no aliases are resolved.
Saving Complex Searches
Since constructing complex searches can be time-consuming, JXplorer lets you
save complex searches as filters for later use. With saved searches, you can:
11–12
■
Save any number of searches as filters
■
Edit or delete them at any time
■
Copy searches for modification, and save them under a different name
Search Results Tree
Regardless of whether the search is run using the quick search bar or a search
menu option, once it is run the matching entries are displayed as a results tree in
the Results view of the directory tree pane.
Parents of search results appear as empty entries in the tree. You can browse and
save the search result tree (including LDIF format) just like the directory tree.
You can edit the results.
You can set the number of entries returned from a search, and the timeout. See
Search Limits in this chapter for more information.
Creating Bookmarks
A bookmark is an entry in the directory that you identify and name for future
reference. You can use a bookmark to quickly jump to an entry.
To add a bookmark, simply select the entry that you want to mark, and choose
Add Bookmark from the Bookmark menu.
Using JXplorer
11–13
Exploring Schema
In addition to viewing the data entries held in a directory, you can directly view
the schema that is read from the directory. Use the Schema view of the directory
tree pane.
Note: Some of the following options may not be available with servers other
than DXserver, because not all servers implement full schema publishing.
The Schema pane lets you examine attribute definitions, class definitions, and
syntax definitions.
Attribute definitions include:
■
Names
■
X.500 OIDs
■
Attribute syntaxes
■
Syntax descriptions
■
A flag showing whether the attribute is single valued
■
General descriptions (if available)
Class definitions include:
■
Names
■
Parents
■
Kind (structural, auxiliary or abstract)
■
A list of must-contain OIDs
■
A translation of OIDs that must be contained in attribute names
Syntax definitions include:
11–14
■
The numeric OID
■
The text description of the OID
As with the other tree displays, you can display schema entries either in the table
view or in custom HTML template pages. Unlike the other tree displays,
however, you cannot edit the schema directly through the browser. For security
and administration reasons, many servers do not permit their schema to be
edited online and require an administrator to perform schema maintenance at
the server.
You can export schema to an LDIF file, but this is not the usual way to store
schema information and most directories cannot use it without further
processing.
Using JXplorer
11–15
Editing the Directory
You can modify entries in the directory using the browser in a large number of
ways, ranging from slight modification of a single attribute value to large-scale
tree operations affecting many thousands of entries.
JXplorer lets you use graphical cut-and-paste techniques to manipulate entire
directory subtrees; you can manipulate individual entries using the table editor.
You can rename entries from either the directory tree pane or the table editor,
depending on what is most convenient at the time.
Directory Tree Operations
As you browse the directory tree, you can modify the directory using the menus,
the button bar shortcuts, or the Context menu (accessed by right-clicking on the
entry) for the entry in the tree itself.
WARNING! This is a very powerful tool, and you can affect large areas of the directory
with a single operation. To avoid accidents, you should turn on the Confirm Tree
Operations flag on the Options menu.
Cut, Copy, Paste, and Delete
You can manipulate the directory tree using the cut, copy, paste, and delete
operations. On Windows platforms, you can copy and move entries by dragging
them with the mouse (“drag and drop”). These operations can be carried out on
individual entries within the directory tree or on whole subtrees. Since most
directories do not natively support operations on entire subtrees, the client reads
and writes all subtree entries recursively, enabling operation on all types of
LDAP-compliant directories.
When you select (and therefore display) an entry, all cut, copy, paste, and delete
operations occur relative to this selected entry. Specifically:
Delete
Removes the selected entry and any subentries
Copy Branch
Copies the selected entry and any subentries
Cut Branch
Prepares the selected entry and any subentries to be moved to a new location
Paste Branch
Either moves or copies a previously cut or copied entry (and any subentries)
under the selected entry as child entries
11–16
Since some subtree operations involving large numbers of entries can take a
significant time to complete, the browser displays a progress bar if it estimates
that the operation is extensive:
The progress bar displays the number of entries processed and estimates the
proportion of the operation completed. When you want to stop the operation,
you can either click Cancel in the Progress, or click the Stop button on the quick
search toolbar. When you do this, any changes already made will be kept.
Renaming Entries in the Directory Tree
You can rename an entry within the directory tree by selecting the Rename
option.
When an entry is renamed, the appropriate changes to the naming attributes are
also made. Naturally, when a parent is renamed, the DNs of the entries in the
entire subtree under the parent also change.
Copying Distinguished Names and Pasting Aliases
Aliases are similar to shortcuts and are used in some directories to link different
parts of the tree. To create an alias, copy the DN of an entry, and then paste it to
another part of the tree using the Paste Alias option. When you copy an entry,
you can choose to copy the full distinguished name of the entry.
You can also use the Copy Branch and Copy DN functions to copy the name of
an entry for pasting into any of JXplorer's text entry fields, or into your own
documents.
Using JXplorer
11–17
Modifying Attributes in an Entry
You can modify entries in the table editor, which is a simple tabulated list of
attribute names and corresponding attribute values. From the table editor, you
can:
■
■
■
■
■
■
■
Edit existing values
Add new attribute/value pairs
Delete attributes and values
Copy and paste attribute values
Manipulate binary attributes
Submit the results to the directory
Add or remove naming attributes
These user modifications do not affect the directory until the entry is submitted.
When you have finished modifying the entry and checked your work, click the
Submit button to send the changed entry to the directory. Only at this point is the
data in the directory changed.
Changing Attribute Values
You can edit existing values where they are by selecting the appropriate cell in
the table and retyping the value.
Note: Binary values, attributes that contain an address, and user passwords are
handled differently. See Using Binary Values, Using the Postal Address Editor,
and Entering a User Password in this chapter for more information.
Deleting Values and Attributes
You can delete values (including binary values) using one of the following
methods:
■
■
Select the text in the cell, and then press the Delete key to leave an empty
cell.
Right-click on the table row, and then choose Delete Value Attribute from the
Context menu.
When you delete the last value of a given attribute, the attribute is also deleted;
however, it is not possible to delete the last value of a mandatory attribute, and
the browser does not let you submit an entry that does not include mandatory
attributes, unless the Ignore Schema Checking option is active. See Mandatory
Attributes in this chapter for more information about mandatory attributes.
11–18
Adding Values and Attributes
When an attribute does not already have a value, but is available to a particular
entry type, you can create it by finding the attribute in the list of blank-valued
attributes at the bottom of the table and filling in the missing value. When an
attribute already exists and has values, you can create a new value by rightclicking on the attribute name and choosing Add Another Value from the
Context menu.
You can add new binary values and addresses this way, but you must fill them
in using the Binary Editor, and the Postal Address Editor, respectively. See Using
Binary Values and Using the Postal Address Editor in this chapter for more
information.
Mandatory Attributes
Some attribute names are represented in bold type. These are mandatory
attributes, which must have at least one value for the entry. The browser does
not submit an entry if it has any mandatory attributes without at least one value.
Naming Attributes
Some attributes are used to name an entry, by forming its Relative Distinguished
Name (RDN). Each entry must have at least one naming attribute. Although
attributes can have more than one attribute value, only one of these can be
chosen as the naming attribute. For example, common name may have two
values, Fred and Freddie, but only one can be used as the naming attribute.
Important! You can set naming attributes for mandatory attributes only.
To make an entry a naming attribute, select the entry in the table editor, rightclick the mouse button, and choose Make Naming Value from the Context Menu.
Naming attributes are displayed in the table editor in blue. Multiple naming
attributes appear in the tree display with a + symbol joining them.
For example, you may want to name a person by the commonName, or cn
attribute, and the surname, or sn attribute. In the case of Craig Link, Craig LINK
is the value of the cn naming attribute, and LINK is the value of the sn naming
attribute. Both entries appear in the table editor in blue, and in the tree display as
Craig LINK + LINK. The order in which the naming attributes appear in the tree
display depends on the order in which they are originally entered into the
directory.
Using JXplorer
11–19
Changing Classes
The object class attribute of an entry determines the attributes that are available
for an entry; therefore, you must modify them separately using the Change
Classes button, located at the bottom of the table editor. This displays the same
list of available object classes as is available in the New Entry panel.
WARNING! You must be careful when deleting object class values because you also
remove all related attributes.
Using the Postal Address Editor
All attributes that have an address value, for example, homePostalAddress, are
entered through the Postal Address Editor dialog, which appears when you
select an address field in the Table Editor. The dialog lets you enter the details, as
they appear in a template with the relevant line breaks and spacing.
Entering a User Password
User passwords are entered via the User Password Data dialog, which appears
when you select the userPassword attribute type in the table editor. The same
procedure applies whether you are entering a new password, or changing an
existing password. Because access to a record is controlled via the access control
settings in the directory’s configuration file (.dxc), you do not have to enter the
existing password before changing it.
Using Binary Values
LDAP is primarily a string handling protocol and many attribute values are
simple text strings. However, it is often necessary to load other types of data, for
example, certificates and images.
JXplorer allows you to load binary files to some attributes, such as Photo and
userPKCS12.
The browser also supports custom binary editors (written in Java using a
provided minimal API) that dynamically loads at run time. You key such binary
editor extensions to a particular object class. This would allow you to write, for
example, an editor for a custom certificate object class.
Standard editors are provided for X.509 certificates, and a number of standard
image and audio formats.
11–20
Importing Binary Files
With the Binary Data dialog shown below, you can:
■
Import binary files
■
Export binary files
See the online help for instructions for importing, exporting, and launching
binary files.
Adding a Photo
JXplorer lets you import a photo into the directory, and display it in an HTML
template. In table editor view, the photo is displayed using the photo editor.
JXplorer lets you import photos through the jpegPhoto dialog, which appears
when you select the jpegPhoto attribute type in the table editor. The display area
expands to display the photo you selected; however, it does exceed the size of the
window. When the photo is larger than the window, you can view the photo by
using the scroll bars. All photos must be in .jpeg format. After loading, JXplorer
gives you the option of saving the photo to another location, using your system’s
file browser.
Using JXplorer
11–21
Adding an Audio File
JXplorer lets you import an audio file into the directory, and export it using your
system’s file browser. You can also play the audio file from in JXplorer. You can
import all audio formats; however, the Audio dialog plays only the following
formats:
■
.mid
■
.au
■
.wav
■
.aiff
Audio files are imported through the Audio dialog, which appears when you
select the audio attribute type in the table editor.
Adding Files that Can Be Launched
JXplorer provides the odMultimedia class that contains attribute types that let
you launch files of the following formats:
Format
Attribute Type
.avi
odMovieAVI
.doc
odDocumentDOC
.mid
odMusicMID
.wav
odSoundWAV
.xls
odSpreadSheetXLS
A dialog appears when you click the value field of one of these attribute types in
the table editor.
For more information about how to add these files, see the online help.
11–22
Adding a New Entry
You can add an entry by selecting the New option.
The new entry is created as a child of the currently selected entry in the tree.
When a new entry is created, you must specify the entry’s RDN and list its object
classes.
Choosing Object Classes
When there are other children of the selected entry, the browser suggests object
classes based on those children; otherwise, you must select them. (To turn this
behavior off, clear the Suggest Classes checkbox). Since the browser is schema
aware, it can fill in any required parent classes.
The choice of object classes must conform to the restrictions laid down by the
schema. The server may also have additional schema rules restricting where
entries of a particular type are created. For example, it may not be possible to
create a country entry underneath an organizationalUnit entry.
Setting Initial Attribute Values
When all information is entered in the new entry dialog, the entry is set up in the
browser, and you can fill in the entry’s attributes in the table editor. Before the
entry is actually created in the directory, you must enter the information for the
attributes and submit them—especially mandatory attributes.
Using JXplorer
11–23
Submitting an Entry to the Directory
Once a new entry has been filled in, or an existing entry has been modified, you
must submit the result to the directory. The browser checks for consistency using
schema information, and the directory checks the entry again when it is
submitted.
If the entry is invalid, the browser reports the directory error to you, but leaves
your changes unaltered in the edit table. To discard your changes, click the Reset
button.
Submitted entries are:
11–24
■
Checked for gross errors by the browser.
■
Submitted to the directory through LDAP.
■
Checked for errors by the directory, after which either:
–
The user is informed if an error has occurred.
–
If no error has occurred, the browser display tree is updated.
Using LDIF Files
Using LDIF Files
LDIF files are a widely used format for saving directory information, similar to
the use of comma-separated value files for storing a table from a relational
database. LDIF is an Internet standard (RFC 2849) for storing directory entries in
a text file as a distinguished name followed by a list of attribute and value pairs.
More information about LDIF is available from the IETF (Internet Engineering
Task Force) at their web site http://www.ietf.org/rfc/rfc2849.txt.
JXplorer lets you use LDIF files to save, enter, and edit directory information,
both with and without an LDAP connection to a directory.
Importing and Exporting an LDIF File
You can import an LDIF file into or exported it from the browser. When the
browser is connected to a directory, it reads the values from the selected file and
added them to the directory, or reads the values from the directory and writes
them to an LDIF file.
JXplorer:
■
Lets the prefix of the DNs in the LDIF file be replaced when reading or
writing an entry to assist in data migration between directories
■
Automatically handles base-64-encoded binary LDIF data
■
Flags (with the help of the directory) when LDIF data entries are invalid
In addition, JXplorer provides a status display when it estimates that a large
import or export operation is taking place. The status display shows the number
of entries processed and the estimated proportion processed. Click Cancel when
you want to quit a long operation.
Using an LDIF File Without a Directory
An added feature of JXplorer is that it lets you use an LDIF file directly as a
miniature directory without any LDAP connection to a directory server. Using an
LDIF file offline in this way can be useful for:
■
Editing during data migration
■
Caching data over a slow communication link
■
Stand-alone demonstrations (on laptops, for example)
■
Reviewing data before committing it to a production environment
Using JXplorer
11–25
Using LDIF Files
Viewing and Saving Offline
To start offline operation, choose Ldif from the menu bar, and then select View
Offline. Select an LDIF file in the same way any LDIF file is imported into the
directory. Once selected, the browser loads the LDIF file, which is displayed as a
directory tree.
You can save the entire tree, or any subtree, at any time to any existing, or new,
LDIF file. To do this, choose Ldif from the menu bar, and then select Export Full
Tree or Export Subtree.
Navigating and Editing Offline
Because there is no communication lag, you may navigate the offline LDIF file
faster than using a directory. You can also edit the LDIF file, and add and
manipulate binary values. The only restriction in the use of offline LDIF files is
that they cannot be searched. To search an LDIF file, you must load the file in a
directory (or the raw LDIF file viewed using a text editor).
Binary Values in LDIF Files
Binary values in LDIF files are stored in base 64 format. This means that you can
copy and paste binary values between JXplorer and LDIF files with the same ease
as other string values.
For more information about base 64 encoding, see IETF in RFC1521, available at:
http://www.ietf.org/rfc/rfc1521.txt.
11–26
Using SSL and SASL
Using SSL and SASL
It is possible to specify that SSL should be used to communicate securely with a
directory server using two variants:
■
SSL with server authentication only (simple)
■
SSL with both client and server authentication (authenticated)
When client authentication is used for the SSL connection, it is possible for the
server to use SASL to authenticate the client, using the client’s certificate to verify
the client’s identity.
Server Authenticated SSL
For server authenticated SSL to work, you must initialize the client with the
trusted public certificate of the directory server, or the server’s certificate
authority. The default keystore for trusted certificates is the security/cacerts file,
which comes initialized with the certificate authority certificate used to create the
demonstration DXserver certificates. While you can change this, the default
setup lets the demonstration directories be contacted immediately using SSL.
You can connect to the directory using server authenticated SSL, as either an
anonymous user, or with your user name and password. To do this, from the
connection dialog, select either SSL + Anonymous, or SSL + User + Password.
Client Authenticated SSL and SASL
Client authenticated SSL requires the registration of the server’s certificate with
the browser, and in addition, the registration of the browser’s certificate (or
certificate authority) with the server. A demonstration client certificate
marjorie.pem is provided in the security directory. Client authenticated SSL
requires the use of the browser’s private key, which is held in the
…//security/clientcerts file. This file is password protected, and requires the
password to be entered in the connection dialog for client authenticated SSL to
work.
The DXserver directory is able to use SASL authentication to authenticate a user,
rather than a user name and password. This implementation of SASL uses the
certificates previously exchanged by SSL, and will only work when client
authenticated SSL is used. This differs from server authenticated SSL where no
client certificate is produced, so the directory is not able to use it to establish
identity.
Using JXplorer
11–27
Online Help
To connect to the directory using client authenticated SSL, from the connection
dialog, select SSL + SASL + Keystore Password, and enter the client certificate
keystore password.
The secure use of client authenticated SSL requires creating a new private key for
the browser rather than using the default private key. This requires using a
Public Key Infrastructure (PKI) tool, such as eTrust™ PKI or Open SSL, to
produce a PKCS8 private key.
Managing Certificates and Keystores
To use SSL in either form, you must manage a variety of certificates and private
keys. These are kept in two Java keystores, which are password protected data
stores. The first keystore, …//security/cacerts, with the password changeit, is
used for storing the public certificates of trusted certificate authorities and
servers. The second keystore, …//security/clientcerts, is used for storing the
certificates and private keys of the JXplorer browser, and it has the password
passphrase. Manage these keystores from the Security menu in JXplorer, where
you can change the default keystore passwords.
To manage the certificates of trusted certificate authorities and servers, from the
Security menu, choose Trusted Servers and CAs. From the dialog, you can view,
add and delete certificates, and set the keystore password.
To manage the certificates and private keys of the JXplorer browser, from the
Security menu, choose Client Certificates. From the dialog, you can view, add,
and delete certificates, and apply private keys to corresponding certificates. You
can also export private keys and set the keystore password.
The JXplorer browser uses the standard Java cryptography tools for its SSL
support. These two files are standard Java keystores, which you can maintain
using the Java keytool utility. This is a command line utility produced by Sun
Microsystems. For more information, see
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html.
Online Help
The online help system provides a number of immediately available aids to the
user, including:
11–28
■
An index of help topics that explain browser usage
■
A table of contents
■
Links to external web resources
Configuring JXplorer
You can customize the following JXplorer features:
■
HTML templates
■
Browser panels
■
Logging and tracing
■
Directory tree icons
You can also create plugin editors for binary files.
View Menu
The View menu lets you access the toolbar configuration and refresh options.
The button bar and quick search bar are not required for the operation of the
browser and if you are short of window space you can hide either or both of
these bars. To do this, from the View menu, choose Show Button Bar and/or
Show Search Bar.
Options Menu
A number of behavioral options are available via the Options menu. These are
described in the following sections.
Look-and-Feel Options
Java supports a number of look-and-feel options for graphical interfaces. These
let the browser adopt the same appearance as other native applications on a
particular operating system.
You can also switch between appearances on the same operating system if you
are more familiar with one particular look than another.
For example, a UNIX user may be more familiar with the Motif/X Windows
appearance and may prefer to use that on a Microsoft Windows platform. The
possible look-and-feel options are:
■
Microsoft Windows
■
Motif/X Windows
■
Java
Using JXplorer
11–29
You can set these options from the Advanced Options dialog, which can be
accessed via the Options menu. To select an interface, click on the L & F tab,
select the look-and-feel interface you want, and then click the Apply button.
For copyright reasons, the Microsoft Windows option is not available on
non-Microsoft platforms.
Safety Mode
A single JXplorer operation can affect thousands of directory entries. To prevent
accidental changes, you can choose to be reminded before you make changes to
the directory. To do this, from the Options menu, choose Confirm Tree
Operations. The following dialog appears prior to modifying the directory by a
tree operation:
To remove this behavior, deselect Confirm Tree Operations from the Options
menu.
Confirming Changes to the Directory
Some users like to receive a confirmation message when making a change to the
directory. To enable the confirmation dialog, from the Options menu, choose
Confirm Table Editor Updates. The following dialog box appears:
To remove this behavior, from the Options menu, deselect Confirm Table Editor
Updates.
11–30
Logging Level
There are a number of logging options available, ranging from no logging at all
to complete tracing of all the LDAP communications with the directory.
The client can log data to a log file, to the console window, to both, or not at all.
The following levels of logging information are currently available:
Level
Description
Meaning
0
Errors Only
Reports errors only.
1
Basic
Reports errors and additional warning information.
4
Tree
Operations
Logs internal tree operations, and other high-level
process information.
6
Extensive
Extensively logs internal browser operations.
8
All
Traces all internal operations, including the
translation system, and the resource loading system.
9
All + BER Trace Reports all of the previous information, plus has an
LDAP Basic Encoding Rules (BER) communications
trace. Useful for de-bugging directory-client
communications problems.
Usually, clients run at level 0 or level 1. However, level 4 can be useful for
auditing all transactions, and level 9 can be useful for debugging directory-client
communication problems.
Note: Level 9 may cause JXplorer to run slower.
accessed via the Options menu. To select a logging level, click on the Log Level
tab, select the logging level you want, and then click the Apply button.
Using JXplorer
11–31
Logging Method
JXplorer lets you choose the method by which you view logging details. The
methods available are as follows:
Method
Meaning
None
No logging is performed.
Console
Logging details can be viewed via a console.
File
Logging details are copied to a file in
.../jxplorer/jxplorer.log.
Console and File
Logging details can be viewed via a management console;
they are also copied to a file in …/jxplorer/jxplorer.log.
accessed via the Options menu. To select a logging method, simply click on the
Log Method tab, select the logging method you want, and then click the Apply
button.
Ignore Schema Checking
DXserver automatically checks all entries submitted to the directory to ensure
that they conform to the directory schema. However, when the network is slow,
it may be wise to check the entry on JXplorer, before you send it to the server. To
do this, from the Options menu, deselect Ignore Schema Checking.
If you do not want JXplorer to check that an entry conforms to the directory
schema when you submit it, select Ignore Schema Checking from the Options
menu.
Resolve Aliases While Browsing
When you select an alias entry in the directory, you can choose whether to view
all of the entry details or the details of the alias entry, that is, where the alias
entry points.
When you want to view all of the entry details, from the Options menu, choose
Resolve Aliases While Browsing. To display only the details of the alias entry,
deselect Resolve Aliases While Browsing from the Options menu.
11–32
Alias Example
If you create an alias entry under Human Resources for Paul Smith in
Marketing and you select Resolve Aliases While Browsing, when you select
Paul’s alias entry under Human Resources you will see all of his details, just as
if you had selected his entry under Marketing.
However, if you deselect Resolve Aliases While Browsing, when you select
Paul’s alias entry under Human Resources you will see the details of the aliased
object name.
Search Limits
JXplorer lets you define the maximum number of entries returned from a search,
and the time (in seconds) allowed to perform the search.
accessed via the Options menu. To select the search limits, click on the Search
Limits tab, select the LDAP limit and LDAP timeout that you want, and then
click the Apply button. To revert the search limits back to the last saved version
click the Reset button.
Values can also be set in the server configuration (.dxc) files. When values are set
in JXplorer and the server configuration files, the lower of the two values is
accepted.
URL Page Browser
By default, linked URL pages are launched in JXplorer. However, on a Windows
system, you can choose to launch them in an external web browser. To customize
this behavior, choose Advanced Options from the Options menu and click the
URL tab.
Using JXplorer
11–33
Creating HTML Viewing Templates
You can create HTML templates and place them in a file directory hierarchy
under the /templates subdirectory of the JXplorer root directory. When a shared
template directory exists on the file system, you can configure JXplorer to use
that directory instead by editing the dxconfig.txt configuration file in the
JXplorer directory.
Place templates in file directories corresponding to object class names. Within
these file directories, the templates can have any name (although names that
include spaces are not recommended). Templates placed directly in the
/templates directory are common to all object classes. For example, the following
file directory structure provides a general template, two templates for person,
and a default template for organizationalUnit:
Directory
Template Files
/templates/
general.html
/templates/person
employee.html
contractor.html
/templates/organizationalUnit
default.html
You can add any number of new HTML templates, including templates for
newly defined object classes by creating (if necessary) the appropriate
subdirectory under the /templates directory and placing the new HTML files in
that subdirectory. After you add new files, you may need to restart the browser
to recognize them.
HTML Tag Extensions
The HTML language is extended using a modification to the HTML <comment>
tag to set placeholders where attribute values can be filled in.
These extension tags:
■
Position individual attribute names and values in the page
■
List of all attribute names and values to be set with a single tag
■
Provide a variety of tabulated formatting options, such as HTML tables and
lists
See the JXplorer online help for more information.
11–34
HTML Forms
You can also use standard HTML forms; however, you must give each form
element a name value that corresponds to an attribute, for example, title.
JXplorer will display existing values and make updates to the directory when
you click Submit.
Important! JXplorer submits the changes to the directory, not to a Web server.
A number of example HTML forms are in the templates sub-directory. For more
information, see the JXplorer online help.
Configuring Tree Icons
The browser reads the icons used in the directory display tree from the /icons
subdirectory of the JXplorer home directory. The icons are 16-pixel-square
images in the form:
object_class_name.gif
You can easily replace the icons. To make sure the browser recognizes the new
icons, you must restart it. For more information, see the JXplorer online help.
Extending the Java Binary Editor
JXplorer can be extended with user-defined binary editors inherited from the
Java class com.cai.od.editor, AbstractBinaryEditor. Such an editor class must be
named objectclassEditor (for example, certificateEditor) and placed in the
subdirectory com/cai/od/editor. When the browser is asked to edit a binary
object, it first searches in this directory for any editors that have the name of the
entry’s object class and dynamically loads them if they exist. For more
information, see the eTrust Directory SDK Developer Guide.
Plug-in Entry Editors
JXplorer can be extended to load small Java programs, similar to Web applets,
based on an entry’s object class. For more information, see the eTrust Directory
SDK Developer Guide.
Internationalization
You can localize JXplorer by using the language resource files in the languages
directory. For more information, see the eTrust Directory SDK Developer Guide.
Using JXplorer
11–35
Troubleshooting
If you experience trouble while using JXplorer, you can run the console.bat
utility provided in the JXplorer home directory, which displays any problems.
Other LDAP and Directory Resources
A number of online resources are available on the web:
■
■
■
11–36
http://supportconnect.ca.com—Computer Associates Technical Support.
http://www.ietf.org/rfc/—Information about the LDAP protocol is
available in a number of Internet RFC documents, especially (for LDAP V3)
RFC2251 through RFC2256.
http://www.java.sun.com/products/jndi/index.html—Details of the Java
naming and directory interface (JNDI) are available from Sun Microsystems.
Chapter
12
Using DXmanager
DXmanager is a graphical web-based management portal. It lets you view and
monitor all of the namespaces and DSAs within a distributed eTrust Directory
environment.
DXmanager is a web tool that lets you monitor all of the namespaces and DSAs
in a distributed eTrust Directory environment. Using DXmanager, you can
monitor the following:
■
The status of each DSA
■
Configuration information about each DSA
■
Statistics about each DSA
■
Namespace diagrams for each DSA, server, or group of servers
Using DXmanager
12–1
How DXmanager Works
How DXmanager Works
DXmanager uses the DXadmind tool to work with DXserver.
The DXadmind tool is installed on each server that contains eTrust Directory
DSAs. This tool is a background process that enables monitoring of all DXservers
that are configured on the machine that runs DXadmind.
DXmanager works uses the data that each DXadmind tool extracts from the
DSAs on its server.
This diagram shows how DXmanager uses DXadmind to monitor DSAs within
the eTrust Directory system:
Computer 1
Internet
Browser
DXmanager
DXadmind
Democorp
DSA
UNSPSC
DSA
DXadmind
UDDI DSA
Democorp
DSA
Computer 2
DXmanager presents data collected by DXadmind
12–2
UNSPSC
DSA
Computer 3
UDDI DSA
How You Can Use DXmanager
How You Can Use DXmanager
You can use the information presented by DXmanager to diagnose problems
earlier and more accurately.
Monitor DSA Status
Monitor the status of each DSA—The status can be started, stopped, can't
connect to server
Check DSA Configuration
Check on the configuration information about each DSA—Including the DSA
name and prefix, and port numbers. See the ZZZ section for a full list of
configuration items that DXmanager can let you monitor.
Track DSA Statistics
Track statistics about each DSA—Including the time the DSA has been running,
the number of incoming and outgoing operations, and the number of
anonymous binds. See the ZZZ section for a full list of statistics that DXmanager
can let you monitor.
Check Namespace Design
DXmanager can display the namespace design for each host. It shows a tree in
which all of the DSAs on that computer are connected.
The following DXmanager page shows the namespace on a computer with the
sample DSAs Router, Democorp, and UNSPSC installed:
Using DXmanager
12–3
How DXmanager Presents Information
How DXmanager Presents Information
Using DXmanager, you can easily monitor the DSAs on a group of servers. This
is useful for systems where a single directory information tree (DIT) is spread
across many servers.
To work with server groups, you need to define the server groups first. You can
then use DXmanager to monitor the DSAs in those server groups.
When you install eTrust Directory, a single server group named Default is
created. This server group contains only the DSAs running on the local
computer.
Starting DXmanager
To start DXmanager on a Windows computer:
1.
Click Start, All Programs, Computer Associates, eTrust, eTrust Directory,
Management and Samples.
2.
Click the DXmanager link.
To start DXmanager on a UNIX or Linux computer:
12–4
1.
Open a web browser..
2.
Go to this page:
http://hostname:8080/dxmanager
where hostname is the name of the computer on which DXmanager is
running. Use localhost for the local computer.
Troubleshooting
Troubleshooting
This section describes how to deal with some problems that may occur while you
use Dxmananger.
Connectivity
The main area to investigate is usually connectivity.
If DXmanager cannot connect to the eTrust Directory Administration Daemon
(dxadmind) on the server being scanned then no information can be returned.
If this is the case, use the following steps:
Use the ping command to ping the target server from the system running
DXmanager's eTrust Directory WebServer.
If this succeeds logon to the target server and ensure that the eTrust Directory
Administration Daemon (dxadmind) is running. On windows it appears in the
Service Manager. On UNIX it appears as a process named dxadmind start. On
either system the command dxadmind status should return:
master is running
DXadmind uses a configuration file in the dxserver\config folder called
dxadmind.ldif. Ensure this contains the line:
dxadminURL: ldap://hostname:2123/
where hostname is the hostname of the target server.
DXwebserver Port Numbers
DXwebserver uses a set of ports. These default ports may conflict with existing
ports on the machine on which DXwebserver is being installed.
See the section Port Numbers Used by eTrust Directory in Chapter 2 for a list of
the default ports used by DXwebserver and other components.
If DXwebserver Does Not Start
Check the logs under the DXwebserver installation directory for port conflicts.
Look for this file in:
■
Windows: %DXHOME%\..\DXwebserver\logs
■
UNIX:
$DXHOME/../dxwebserver/logs
Using DXmanager
12–5
Troubleshooting
If there is a port number conflict, modify the DXwebserver configuration file. By
default, DXwebserver is set to use the port 8080.
To change the port number, you will need to modify the DXwebserver
configuration file server.xml:
1.
Install DXwebserver as usual.
2.
Look for this file in the following locations:
3.
-
Windows:
%DXHOME%\..\DXwebserver\conf
-
UNIX: $DXHOME/../dxwebserver/conf
In the server.xml file, look for the Connector section:

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="10" debug="0" connectionTimeout="20000"
useURIValidationHack="false" />
4.
Change the port number from 8080 to another port number.
5.
Restart DXwebserver to pick up the new port number.
If the Main HTTP Connection Port Number Is Modified
The main HTTP connection port number is set to 8080 by default. If this port
number is modified, then some of the web applications may not work correctly,
and on Windows computers, the Start menu shortcuts to Management and
Samples will be affected.
Note the new port number for future HTTP connections.
12–6
Chapter
13
Using JXweb
JXweb is a general purpose LDAP-compliant directory browser and editor,
which provides access to a directory through the Web. It provides similar
functions as those provided by JXplorer.
JXweb lets you:
■
Connect remotely to any directory that supports LDAP
■
Browse the directory
■
Update directory entries
■
Manipulate the directory tree
Using JXweb
13–1
Connecting to JXweb
Connecting to JXweb
To access JXweb, all you need is a web browser and a network connection to a
computer on which JXweb is installed.
If JXweb is installed on your Windows computer, you can start JXweb from the
Start menu:
1.
Click Start on the taskbar, and then choose Programs, Computer Associates,
eTrust, eTrust Directory, Management and Samples.
2.
On the displayed page, click JXweb.
If you want to open JXweb on another computer:
1.
Start your web browser.
2.
Enter the URL http://server:port number/jxweb/index.html, where:
-
server is the name of the server on which JXweb is installed
-
port number is the number of the JXweb port. The default is 8080.
For example: http://computer32:8080/jxweb/index.html
The browser displays the JXweb Connect dialog:
13–2
From the JXweb Connect dialog, you can connect to a directory. The browser
requires the following information for you to log in to a directory:
■
The name of the computer that hosts the directory
■
The port number of the directory server
■
■
■
(Optional) The base distinguished name of the directory, for example,
o=DEMOCORP,c=AU
(Optional) The distinguished name of your user account, if the directory to
which you want to connect has access controls enabled
(Optional) A user password that you must provide if you use your user
account
When you are connected to a directory and want to connect to another, click
Connect on the menu bar to display the JXweb Connect dialog.
When you exit your browser, you disconnect from the directory.
Using JXweb
13–3
The JXweb Environment
The JXweb Environment
When you connect to the directory, the left pane displays the Directory
Information Tree (DIT) of the directory to which you are connected. Click an
entry to display its details in the right pane. The DN of the displayed details
appears at the top of the pane. You can update the entry details (for example,
Edit) and manipulate the selected branch of the DIT (for example, Copy or
Move). For more information about JXweb, click Help from the JXweb menu bar.
Customizing JXweb
JXweb was created using Velocity tags, which render the HTML pages in JXweb.
To create your own look and feel for the packaged version of JXweb, you can
manipulate the HTML code and the Velocity tags.
For a description of the Velocity tags used in JXweb, see the JXweb online help.
For an example of how you can adjust JXweb to suit your organization, see the
Democorp sample in the dxwebserver\samples directory. This is a version of
JXweb that has been customized to work well for the fictional company
Democorp.
13–4
Using JXweb in Languages Other Than English
Using JXweb in Languages Other Than English
eTrust Directory is language certified for the following nine languages:
■
Brazilian Portuguese
■
French
■
German
■
Italian
■
Japanese
■
Korean
■
Simplified Chinese
■
Spanish
■
Traditional Chinese
This means that all eTrust Directory components run on operating systems in
those languages.
Displaying Non-English Characters in Internet Explorer
By default Internet Explorer detects the language encoding automatically.
However, if there are problems with displaying non-English characters:
■
In Internet Explorer, select View, Encoding, Auto-Select has a check mark.
Displaying Non-English Characters in Mozilla Browsers
Web browsers based on the Mozilla engine (including Netscape) do not autodetect the character encoding correctly.
If there are problems with the characters displayed:
1.
In the Mozilla browser, select View, Character Coding, Auto-Detect, Off.
2.
Select View, Character Coding, Unicode (UTF-8).
Online Help
Use the online help to learn about how to use the JXweb interface, and how to
customize JXweb.
Using JXweb
13–5
Chapter
14
Using The UDDI Server
Universal Description, Discovery and Integration (UDDI) is an evolving standard
interface to information about services. A UDDI registry is a directory of
businesses and the services they offer.
In a UDDI registry, all the information is presented in a well-defined manner so
that it can be used by automated components and by humans. This lets the
repository be used, for example, as a means for an application to locate a
replacement service, should the service it is using become unavailable.
The full details of the UDDI specification can be found at the UDDI web site
http://www.uddi.org/.
14–1
About UDDI Registries
About UDDI Registries
A UDDI registry is a directory of all the Web services in an organization, be it a
single business enterprise or a globe-spanning multinational conglomerate.
The UDDI registry provides a central point for recording all the details about
each Web service, enabling the developers in the organization to locate other
Web services to use as building blocks to construct an application, thus saving
time and effort.
What a UDDI Registry Can Do
Because the UDDI registry contains all the details about the interfaces,
developers can more easily combine or present services developed by disparate
groups, possibly in different locations.
Moreover, the UDDI protocol provides for recovery—if a needed service fails
and is replaced by another at a different location, all those services that depend
on it can recover automatically by reloading the location and connection
parameters from the UDDI registry.
About the eTrust Directory UDDI Server
The eTrust Directory UDDI Server provides repository services. It functions as a
business directory, permitting searches based upon categorizations and
relationships between businesses. It provides authentication and authorization of
users for inquiry and publishing.
A server provides UDDI services to requests from clients. A web-based UDDI
Client enables you to publish to or search the repository.
14–2
eTrust Directory UDDI Server
eTrust Directory UDDI Server
The eTrust Directory UDDI Server provides repository services. It can function
as a business directory, enabling searches based upon categorizations and
relationships between businesses. It provides authentication and authorization of
users, for inquiry and publishing. It acts as a repository for UDDI information
and as an engine for processing UDDI requests.
The UDDI server is installed under the Tomcat servlet container. It provides
UDDI services to client applications that make requests by using the Simple
Object Access Protocol (SOAP).
The UDDI Server is a multi-version server, responding to requests in UDDI
Version 1, Version 2, and Version 3 formats. For more information about the
UDDI APIs, see the eTrust Directory SDK Developer Guide.
The web-based UDDI Client enables users to:
■
Publish services to the repository.
■
Search for specific entries in the repository.
14–3
Connecting to the UDDI Client
Connecting to the UDDI Client
On Windows Only
On UNIX Or Windows
1.
Open the Management and Samples page. To do this, from the start button,
select Programs, Computer Associates, eTrust, eTrust Directory,
Management and Samples.
2.
Click on the UDDI Client link.
You can also access the UDDI Client directly from your web browser. Start your
web browser and enter the following URL, where server is the name of the host
on which the client is installed:
http://server:8080/uddiv3-client/index.html
The eTrust Directory UDDI Client Connect page appears.
14–4
Connecting to a UDDI Registry
Connecting to a UDDI Registry
The UDDI Client Connect page enables you to connect to a UDDI registry.
By default, the client uses the following URLs to connect to the UDDI Server on
the same computer as the UDDI Client:
Inquiry URL: http://localhost:8080/uddi/services/Inquiry
Publish URL: http://localhost:8080/uddi/services/Publishing
When you want to connect to a server on a different host, change localhost in both
of these URLs to the name of the UDDI Server computer, then click Connect.
When you want to change servers at any time after you have connected, click
Connect on the menu bar to return to this page.
Using tModels
A tModel is a data structure representing a service type (a generic representation
of a registered service) in the UDDI Server. Each tModel consists of a name, an
explanatory description, and a Universal Unique Identifier (UUID). It can also
provide a URL that enables users to get further information.
A tModel may represent a technical specification. Services that are compliant
with the specification may reference the tModel. This facilitates the searching of
services that are compliant with a particular specification.
You can also use a tModel to provide meaning to data. For example, a tModel
can give structure to the following address line: 12 Montgomery Street, where 12
has the meaning of street number and Montgomery Street has the meaning of
street name.
14–5
Using the UDDI Client in Languages Other Than English
Using the UDDI Client in Languages Other Than English
eTrust Directory is language certified for the following nine languages:
■
Brazilian Portuguese
■
French
■
German
■
Italian
■
Japanese
■
Korean
■
Simplified Chinese
■
Spanish
■
Traditional Chinese
This means that all eTrust Directory components run on operating systems in
those languages.
Displaying Non-English Characters in Internet Explorer
By default Internet Explorer detects the language encoding automatically.
However, if there are problems with displaying non-English characters:
■
In Internet Explorer, select View, Encoding, Auto-Select has a check mark.
Displaying Non-English Characters in Mozilla Browsers
Web browsers based on the Mozilla engine (including Netscape) do not autodetect the character encoding correctly.
If there are problems with the characters displayed:
14–6
1.
In the Mozilla browser, select View, Character Coding, Auto-Detect, Off.
2.
Select View, Character Coding, Unicode (UTF-8).
Chapter
15
Using the Sample DSAs,
Applications, and Tools
eTrust Directory comes with a number of samples for testing and demonstration
purposes:
■
Sample directories
■
Sample web applications
■
Sample configuration files
■
Sample tools
These technology previews are not covered by your usual CA Support. However,
your feedback is very welcome. Please see the Readme files in each sample
directory for how to let us know about your comments or questions.
Using the Sample DSAs, Applications, and Tools
15–1
Implementing the Samples
Implementing the Samples
In a default installation, these samples are installed but not set up. You need to
install each sample you want to work with.
By default, the sample directories and sample tools are installed under the
following directory:
■
Windows: %DXHOME%\samples
■
UNIX:
$DXHOME/samples
By default, the web applications are installed under the following directory:
■
Windows: %DXHOME%\..\dxwebserver\samples
■
UNIX:
$DXHOME/../dxwebserver/samples
The sample configuration files are installed into the main configuration file
directories. The default location is:
■
Windows: %DXHOME%\..\config
■
UNIX:
$DXHOME/../config
For more information about setting up these samples, see the appendixes
Installing eTrust Directory for Windows and Installing eTrust Directory for
UNIX, and also the Readme files in each of the sample directories.
15–2
The Sample DSAs
The Sample DSAs
This section describes the sample directories, and explains how to install them
manually.
What the Sample DSAs Are Useful For
eTrust Directory provides a number of sample directories, which contain
different DSA configurations and show different methods of populating a
directory.
You can also use these samples to explore the eTrust Directory features before
setting up your own directory.
When the Sample DSAs Are Installed
When you run a default installation of eTrust Directory, the three sample
directories are automatically installed, configured, and started.
If you run a customer installation, you can choose whether to install the sample
directories.
How the Sample DSAs Work Together
Together, the Democorp, Router, and UNSPSC sample directories form a single
logical view of all of the directory information. It does not matter which directory
you connect to. You see the same data because the DSAs cooperate to resolve a
query or update through X.500 distribution.
Router
DSA
DSP
Democorp
DSA
DSP
UNSPSC
DSA
15–3
The Sample DSAs
The Democorp DSAs
Democorp is an example of a corporate staff directory.
The Democorp sample models a fictitious company called DemoCorp. There are
about 100 organizational units in the data, with approximately 1200 employees in
total. The Democorp sample demonstrates a front-end load of the directory using
the dxmodify tool.
The Democorp Directory Setup Script
The setup script creates a DXserver called democorp using an Advantage Ingres
database called democorp. The directory is loaded using the dxmodify tool with
the prefix O=DEMOCORP, C=AU. This is a demonstration of a front-end load in
a directory. Front-end loads are useful for loading fewer than a few thousand
entries and for loading data in already populated directories.
The data is converted from comma-separated value (CSV) format to LDAP
lightweight directory interchange format(LDIF) by using the csv2ldif tool. The
resulting LDIF file is loaded in the directory by using the dxmodify tool. After
loading, the democorp Advantage Ingres database is tuned.
The setup script performs the following steps:
15–4
1.
Creates the Democorp Advantage Ingres database called democorp.
2.
Configures the Democorp initialization file, database file, knowledge file,
and knowledge group file, and start the Democorp DXserver DSA.
3.
Converts the Democorp CSV data to LDIF.
4.
Loads the LDIF data in the Democorp directory.
5.
Tunes the democorp Advantage Ingres database.
The Sample DSAs
The UNSPSC DSAs
The United Nations Development Program and Dun & Bradstreet merged their
separate commodity classification coding schemes in 1999 to form the Universal
Standard Products and Services Classification (UNSPSC).
The levels let you search products more precisely because you confine the
searches to logical categories, thus eliminating irrelevant hits. The levels also let
managers perform expenditure analysis on categories relevant to the company’s
situation.
The UNSPSC directory contains more than 10,000 entries.
The UNSPSC Directory Setup Script
The UNSPSC sample demonstrates a back-end load of the directory using the
DXloaddb tool.
The setup script creates a DXserver called unspsc using Advantage Ingres. This
is an example of a back-end or bulk load by using the DXloaddb tool. Bulk loads
are very fast because they bypass the DSA and load the data directly in the
database. They are used for initial data loads or updating the entire contents of a
directory.
The data is converted from CSV format to LDIF by using the csv2ldif tool. The
resulting LDIF file is loaded in the directory by using the DXloaddb tool.
The UNSPSC setup script performs the following steps:
1.
The script creates the UNSPSC Advantage Ingres database named unspsc.
2.
The script configures the UNSPSC initialization file, database file, knowledge
file, and the knowledge group file.
3.
The script converts the UNSPSC CSV data to LDIF.
4.
The script loads more than 10,000 LDIF entries in the UNSPSC directory.
5.
The script starts the UNSPSC DXserver DSA.
Tip: Use the bulk load tools ldifsort and DXloaddb to achieve a highperformance load of the UNSPSC data by directly loading the Advantage
Ingres UNSPSC database.
15–5
The Sample DSAs
The Router DSAs
The Router sample demonstrates a router DSA configuration, where the DSA has
no database, but has knowledge of two subordinate DSAs.
This sample demonstrates how a router DSA does not require a database of its
own. It also acts as a single point of entry into multiple directories as
demonstrated with Democorp and UNSPSC.
The Router Directory Setup Script
The setup script creates a DXserver called Router with no database and starts it.
The setup script performs the following steps:
15–6
1.
Configures the Router initialization file, knowledge file, and knowledge
group file.
2.
Starts the Router DXserver DSA.
Sample Web Applications
eTrust Directory comes with some sample web applications. You can open the
democorp and uddi applications from the Management and Samples page.
For information about the sample web applications, see the Readme files in each
of the sample tools directories.
Customized Version of JXweb: democorp
To demonstrate how easily JXweb can be customized, the Democorp version of
JXweb has been included with eTrust Directory.
What the UDDI Demonstration Shows
This technology preview is an example of how you can adjust JXweb to suit your
organization. This is a version of JXweb that has been customized to work well
for the fictional company Democorp. It displays entry details in a “business
card” format.
Running the Democorp version of JXweb
To run the Democorp version of JXweb:
1.
Open your web browser.
2.
Enter the following URL into the Address field:
http://machinename:8080/democorp
where machinename is the name of the computer on which you installed the
Democorp preview. This is the computer on which DXwebserver resides.
15–7
Sample DSML Server: dsml
This is a sample DSML server that converts DSML to LDAP and vice versa. This
allows client applications that use DSML (including web services) to
How the DSML Server Works
The following happens when JXplorer uses DSML to communicate with dxserver
through the DSML server:
1.
JXplorer sends DSML requests to the DSML server.
2.
The DSML server translates these requests into LDAP requests and passes
them onto the directory.
3.
The directory responds using the LDAP protocol.
4.
The DSML server translates the LDAP directory response into a DSML
response and sends it back to JXplorer.
Running the DSML Server Using JXplorer
JXplorer can use DSML in order to let it connect to DSML web services. This
means that you can use JXplorer to test the DSML server.
To access the DSML server technology preview using JXplorer:
15–8
1.
The file dsml.properties points to Democorp on the current machine
2.
Connect using a DSML enabled LDAP client (such as JXplorer) to the web
servers, using the following connection settings:
Setting
Value
Host
The name of the computer running the DSML server
Port
8080
Protocol
DSML v2
DSML Service
dsml-sample/services/DSML
Changing the DSML Sample Properties
1.
Open the following file in a text editor:
-
Windows:
%DXHOME%\..\dxwebserver\webapps\dsmlsample\WEB-INF\dsml.poperties
-
UNIX:
$DXHOME/../dxwebserver/webapps/dsmlsample/WEB-INF/dsml.properties
Sample SAML Server: saml-sample
This is a sample SAML server that converts SAML to LDAP and vice versa. This
allows client applications that use SAML (including web services) to
Installing the SAML Sample
1.
Navigate to the where you have installed eTrust Directory (Hint: echo your
DXHOME environment variable if you are unsure where this is). Then
navigate to dxwebserver > samples > saml.
2.
If you are on a Windows machine run the 'setup.bat', if on a Solaris machine
run the 'setup.sh'.
This setup file performs the following steps:
a.
Stops Tomcat
b. Copies the Tomcat server files and SAML files to
"%DXHOME%\..\dxwebserver\webapps\saml-sample".
c.
Restarts Tomcat.
The install should be complete in a few moments.
To Test the SAML Server
For testing you can use the example 'samlping' command line program that
allows for arbitrary SAML attribute requests to be sent to the server.
Run 'samlping -?' for more details.
To Access the SAML Server
1.
The file saml.properties points to Democorp on the current machine
2.
Connect using a SAML client to the web servers port.
15–9
Sample SPML Server: spml-sample
To Install the SPML Sample
1.
Navigate to the where you have installed eTrust Directory (Hint: echo your
DXHOME environment variable if you are unsure where this is). Then
navigate to dxwebserver > samples > spml.
2.
If you are on a Windows machine run the 'setup.bat', if on a Solaris machine
run the 'setup.sh'.
This setup file performs the following steps:
a.
Stops Tomcat
b. Copies the Tomcat server files and SAML files to
"%DXHOME%\..\dxwebserver\webapps\spml-sample".
c.
Restarts Tomcat.
The install should be complete in a few moments.
Note: the above setup files perform the following steps:
To Access The SPML Sample
15–10
1.
The file spml.properties points to Democorp on the current machine
2.
Connect using a SPML client to the web servers port.
Sample Use of UDDI: uddiv3-demo
This is a demonstration of a typical application of a UDDI server. It shows a web
site that compares prices on airline flights by looking up the prices on different
web servers, which are registered with a UDDI server.
What the UDDI Demonstration Shows
The UDDI demo web site that searches for the cheapest flights between
destinations. The web site queries a UDDI registry for a list which web services it
should connect to.
Using the UDDI Demonstration
The following instructions show how to use this demonstration web site to show
how you can immediately remove information from a dynamic web site by
removing the name of a web services from a UDDI server.
1.
Open your a web browser, and go to the following page:
http://localhost:8080/uddiv3-demo
2.
Choose an origin and destination from the dropdown lists, and click Go.
If this is first time you have used the site since the last reboot, there will be a
pause while all the code is loaded into the servers .
3.
Click the Back button to reset the appearance of the demo before the demo
starts.
4.
Open another copy of your web browser and go to the following page:
http://localhost:8080/uddiv3-client
5.
Click on Connect, because the defaults are correct
You should now have two browser windows: one page shows the flight price
search demonstration site, and the other shows the UDDI Client.
6.
Click Login from the column of commands on the left. The Login page
opens.
7.
Enter the name of the airline you want to delete. To delete the Dirt Cheap
Airline:
a.
Log in using the following details:
Login name:
Dirt Cheap Discount Airlines
Password:
secret
b. Leave the info selection alone.
c.
Click Login. This brings you to the Registered Information display for
the chosen airline.
15–11
8.
Click the Delete button under Business in the column of commands on the
left. The Delete Business page opens.
9.
Click the Add button to add the business to the Selected Business Keys.
These are the business to be deleted.
10. Click the Delete button to delete this business from the registry.
11. Return to the Demo window, and press Go again. The panel refreshes, and
the Dirt Cheap airline details no longer appear.
To reset the demonstration:
15–12
1.
Click the Refresh Demo link at the bottom of the page.
2.
Click Open to run the reset program - it reloads the entire demo directory
back to the original state.
The sample DSAs use sample configuration files.
You can use these configuration files as templates for your own files.
For information about the sample configuration files, see the Readme files in
each of the sample DSA directories.
Sample Tools
The sample tools are some extra tools for managing eTrust Directory.
A number of sample configurations and utilities are provided for testing and
demonstration purposes. These reside in the ../dxserver/samples subdirectories:
The DXcmip Tool
An executable to request CMIP counters from the directory.
The dxcmip program is a management client which retrieves management
information from an Computer Associates DXserver using the CMIP protocol.
The management information retrieved is defined in ISO 9594-10 (Committee
Draft April 1995).
Usage
The dxcmip tool has the following command line format:
dxcmip [-r[n]] host[:port] [psel]
where:
■
-r[n] refresh every n seconds. Default: 5 seconds
■
host the hostname or IP address to contact
■
port the CMIP port. Default: 19389
■
psel the OSI P-SELECTOR. Default: CMIP
15–13
Sample Tools
The dua Tool
Sample text-based Directory User Agent (DUA) that runs over DAP This
directory contains the DAP directory client scripting DUA. This can be used to
execute scripts to add, modify or remove entries from the directory. This can also
be used to perform searches.
Example test scripts reside in the samples/test directory. These can be executed
either by running the setup script from that directory.
See the eTrust Directory SDK Developer Guide for more details.
Usage
The general syntax for the dua client is:
dua <script>
The script 'init' is executed if a script name is not specified.
The init script in this directory performs an anonymous bind.
The DemoCorp DSA should be started for this to work.
If an authenticated bind is required, then the username and password lines
should be uncommented and a password set on the bind username in the
directory as specified in the script.
The DXtoolsgui Tool
Java GUI interface to the DXtools—run dxtoolsgui.bat on Windows or
dxtoolsgui.sh on UNIX.
The dxtoolsgui tool requires Java Runtime Environment (JRE).
15–14
Sample Tools
The ldua Tool
This directory contains the LDAP directory client scripting DUA. This can be
used to execute scripts to add, modify or remove entries from the directory. This
can also be used to perform searches. Example test scripts reside in the
samples/test directory. These can be executed either by running the setup script
from that directory.
See the eTrust Directory SDK Developer Guide for more details.
Usage
The general syntax for the ldua client is:
ldua <script>
The script 'init' is executed if a script name is not specified.
The init script in this directory performs an anonymous bind.
The DemoCorp DSA should be started for this to work.
If an authenticated bind is required, then the username and password lines
should be uncommented and a password set on the bind username in the
directory as specified in the script.
The schema Tool
A Perl schema translation tool to update schema.txt for the DXtools
This directory contains a perl script (transchema.pl) which translates a custom
schema file (.dxc) producing updated versions of schema.txt for the DXtools.
It also creates dxtype.txt and dxobject.txt for the DXplorer client that is no longer
supported but may still be the preferred client for some customers.
The script cannot handle schemas that contain attributes with varying OID
prefixes. Currently such schema would need to be translated manually.
Inputs
<schema-filename>
schema.bck
dxtype.bck
dxobject.bck
15–15
Sample Tools
Outputs
schema.txt in the current directory.
dxtype.txt
dxobject.txt
Usage
transchema.pl <schema-filename> <attr-prefix-name> <class-prefix-name>
where:
■
schema-filename is the name of a custom schema file e.g. custom.dxc
■
attr-prefix-name is the name of the attribute prefix used in the schema
■
class-prefix-name is the name of the object class prefix used in schema
Typically the custom schema file would contain the lines:
schema set oid-prefix customAttributeType = (2.16.840.1.113730.3.1);
schema set oid-prefix customObjectclass = (2.16.840.1.113730.3.2);
For example:
transchema.pl custom.dxc customAttributeType customObjectClass
This script requires Perl to run.
The input files need to be copied from their home directories.
On UNIX
On UNIX, use the following commands to copy the input files from their home
directories:
cp /opt/dxserver/bin/schema.txt .
cp /opt/dxserver/for_dxplorer/DXtype.txt dxtype.txt
cp /opt/dxserver/for_dxplorer/DXobject.txt dxobject.txt
On Windows
On Windows, use the following commands to copy the input files from their
home directories:
copy \opt\dxserver\bin\schema.txt .
copy \opt\dxserver\for_dxplorer\DXtype.txt dxtype.txt
copy \opt\dxserver\for_dxplorer\DXobject.txt dxobject.txt
15–16
Sample Tools
The snmp Tool
An executable to request SNMP information from the directory.
The dxsnmp program is a management client which retrieves management
information from an Computer Associates DXserver using the SNMP protocol.
The management information retrieved is defined in RFC 1567 Directory
Monitoring MIB. An eTrust Directory specific information is defined in
dxmib.asn1. This can be found in the current directory and provides the
following:
■
Multiwrite queue monitoring
■
DSA statistics monitoring
Some statistic elements require stats logging/tracing to be enabled, as these
items impact performance)
■
DXcache Monitoring
Usage
The dxsnmp tool has the following command-line format:
Usage: dxsnmp -r[n] host[/port] [community]
where:
■
-r[n] refresh every n seconds. Default: 5 seconds
■
host the hostname or IP address to contact
■
port the SNMP port. Default: 19389
■
community the SNMP community of interest. Default: 'public'
15–17
Sample Tools
The soak Tool
Soak is a testing tool used to run searches against an LDAP or DAP directory.
The soak program can be used to run one search or even millions. Soak is
designed to keep a directory busy with searches to give an accurate time in how
long it takes to the directory to compete a search. Searches can range from
complex to exact matches.
Soak also has a queuing system where you can set a queue of searches. This to
eliminate the overhead of soak setting up the search, because if you keep a
number of searches in a queue then whenever the directory has finished a search
there is another one waiting. It is for this reason the soak worked better running
from another box or have it’s own processor. If you run soak from another
computer, then it must be a fast network and the traffic must be minimal.
This program uses either LDAP or DAP to measure throughput (as
searches/sec).
It attempts to keep the Directory Server saturated with search requests. This is
done by using asynchronous search requests.
Usage
The soak tool has the following command-line format:
soak [options] hostaddr:port namefile searches queuesize attributes
Where the options are:
15–18
■
-d
use the X.500 DAP protocol. Defaults to LDAP.
■
-m
modify mode (generates random data)
-
interpret names as DNs
-
interpret attributes as: rndAttr len rndAttr len
■
-M
modify mode (LDIF modify records)
■
-n
do not ask for any attributes to be returned.
■
-s
step through searches sequentially (default is rnd).
■
-F
interpret names as filters.
■
-A
retrieve attribute names only (no values)
■
-r count
make the first count chars of rnd value the same
■
-D base_dn bind dn
■
-w bind_password bind password (for simple authentication)
■
-b base_dn search base
Sample Tools
■
-S msecs
sleep in milli-secs before each search (default=0)
■
-Z schema file containing schema definitions (DAP only)
And where the variables are:
■
hostaddr:port
Address and port of LDAP/DAP Directory Server.
■
namefile
File containing names to be searched.
■
searches
The number of searches to perform.
■
queuesize
The number of outstanding searches to maintain.
And where the attributes are a whitespace-separated list of attributes to retrieve
(if no attribute list is given, all are retrieved)
Example
For example, here is a typical soak command for exact match searches used with
the DemoCorp data:
soak 155.35.131.155:5544 /local/travis/Performance/names/tenk.name 50000 3
where
■
■
■
155.35.131.155 is the port number of the machine that the directory is
installed on.
5544 is the port number the directory is listening on.
Note: The port number and IP-ADDRESS are separated with a ‘:’
/local/travis/Performance/names/tenk.name is the name file the soak will
use to search the directory.
■
5000 is the number of searches to run
■
3 is the queue size to use for the searches.
The DemoCorp data has three different name file to used for each database for
exact matches.
■
tenk.name
■
onehundredk.name
■
onemillion.name
Example:
soak myhost:1001 names.dat 100 5
read 5 names
Connecting to myhost:1001 ...
1000: (cn=ann bradley)
998: (cn=adrian gardner)
15–19
Sample Tools
994: (cn=adam fischer)
...
6: (cn=craig link)
4: (cn=ann bradley)
2: (cn=craig link)
1: (cn=craig link)
Searches: 800
Start time: 978082934.854
Stop time: 978082940.194
Elapsed time: 5.339
Searches/Sec: 149.83
Content of names.dat (taken from democorp example)
craig link
adam fischer
adrian gardner
ann bradley
joh martinez
15–20
Sample Tools
The ssl Tool
The samples/ssl directory contains tests using the DAP and LDAP script DUA.
This sample includes examples of using DUA-DSA and DSA-DSA SSL
authentication and encryption, using SSL encryption and SSL authentication
between client and DXserver
The DAP and LDAP script DUAs connect to the DemoCorp DXserver using SSL
encryption or SSL authentication.
This directory contains the following files:
test1.dxs
This script demonstrates a client-server connection using an SSL-encrypted
link between the DUA and DemoCorp directory.
test2.dxs
This script demonstrates a mutually authenticated client–server SSL
connection between the DUA and DemoCorp directory.
test3.dxs
This script demonstrates a mutually authenticated client–server SSL
connection to the DemoCorp directory but searching the UNSPSC directory
using chaining.
test4.dxs
This script demonstrates distributed authentication. This time the DUA
connect to the UNSPSC DSA but is authenticated by the DemoCorp DSA and
searches the DemoCorp directory.
In tests 2-4 the DUA (via SSLD) requires use of client certificates stored in the
samples/ssl/certs directory. They require the certificate of a user that exists in
the DemoCorp directory, Marco Drew, in the file marco_drew.pem.
These scripts can be configured and run using the setup script.
Note: The DemoCorp and UNSPSC DSAs are assumed to be running. These can
be configured using their sample setup scripts.
The SSL Setup Script
To set up the ssl tool, run the setup script. This is setup.sh on UNIX, and
setup.bat on Windows NT.
The script performs the following steps:
1.
Starts the SSLD for Directory Server requests.
2.
Starts the SSLD for Directory Client requests.
15–21
Sample Tools
3.
Starts the DemoCorp DSA.
4.
Starts the UNSPSC DSA.
5.
Runs the DUA SSL encryption test (test1.dxs).
6.
Runs the DUA SSL authentication test (test2.dxs).
7.
Runs the DUA SSL authentication test (test3.dxs).
8.
Runs the DUA SSL distributed authentication test (test4.dxs).
9.
Runs the LDUA SSL encryption test (test1.dxs).
10. Runs the LDUA SSL authentication test (test2.dxs).
11. Runs the LDUA SSL authentication test (test3.dxs).
12. Runs the LDUA SSL distributed authentication test (test4.dxs).
The -q switch can be used to suppress user prompting.
About the Testing DUA and SSLD
The DAP and LDAP script DUAs makes use of a Client SSLD process to handle
the SSL encryption and authentication.
This should be started using the command:
ssld start client -certfiles samples/ssl/certs -ca config/ssld/trusted.pem -port
1113
The command ssld stop client can be used to stop the server SSLD.
This is in addition to the SSLD process used by the DSAs, this process listens for
SSL requests on port 1112 and is started by the command:
ssld start server -certfiles config/ssld/personalities -ca
config/ssld/trusted.pem
The command ssld stop server can be used to stop the server SSLD.
SSL encryption is enabled in the DUA by adding 'ssl-encryption' to the bind
request. The scripts explicitly use port 1113. When using SSL encryption, the
DSA will use normal access controls.
To enable SSL authentication as well as encryption, add 'ssl-auth' to the DUA
bind request. The DSA will check its list of trusted CAs to confirm that the
client's certificate is valid, then by default, the DSA will check for an entry in the
directory matching the subject name of the certificate. This check can be disabled
by setting 'ssl-auth-bypass-entry-check = true' in the DSA settings.
When binding with ssl-auth, note that the DUA bind syntax does not allow the
'user' and 'password' fields that are normally present.
15–22
Sample Tools
The test Tool
A selection of Directory scripts to modify the directory using the supplied DUA
or LDUA clients. Run the setup script to automatically configure the Test DSA
and execute the DUA and LDUA client scripts.
This directory contains sample directory client scripts. These can be executed by
running the LDAP DUA (LDUA) and DAP DUA. These reside in the directories
samples/ldua and samples/dua.
The setup script creates a DXserver called 'test' using the Ingres database 'test'.
The test DSA is loaded by the test scripts using the master script basic.tests in
this directory. These scripts are executed using first the DAP DUA and then the
LDAP DUA directory client.
Usage
setup.sh (Solaris)
setup.bat (Windows NT)
The -q switch can be used to suppress user prompting.
The script performs the following steps:
1.
Create the Test Ingres database 'test'.
2.
Configure the Test initialization file: config/servers/test.dxi.
3.
Configure the Test database file: config/database/test.dxc.
4.
Configure the Test knowledge file: config/knowledge/test.dxc.
5.
Start the Test DXserver DSA. This DSA contains a null prefix.
6.
Execute the basic directory tests using the DAP DUA Client.
7.
Execute the basic directory tests using the LDAP DUA Client.
The test scripts include tests of all X.500 services. The tests are performed on a
single DSA with an existing database with no context prefix. The test scripts
return the database to its original condition when they run successfully.
All tests add a small subtree, conduct tests on this subtree and then remove the
subtree.
If the script executes successfully then the database will be returned to its
original state.
15–23
Sample Tools
The response to each request is checked using the "if-reply" line, so the number
of entries or attributes returned, or the returned error code can be checked. A test
will fail if the wrong response is returned, such as and add-entry-refuse when an
add-entry-confirm was expected, or if the wrong number of entries was returned
on a list or read result.
If a test fails the script will display an error message and exit. This may leave
entries in the database.
The scripts do not test authentication or security, so the user can bind to the DSA
as an anonymous user.
Test 1
This script tests all the basic services apart from search.
Test 2
This script tests the search service.
Test 3
This script tests various errors.
Test 4
This script tests schema (MUST and MAY contains and distinguished
values).
Test 5
This script tests the handling of large attribute values and attributes
containing large numbers of values.
Test 6
This script tests the operation of aliases.
15–24
Sample Tools
The DXtrap Tool
Information and an example program that can receive triggers from the
directory.
The dxtrap program is a management application which receives SNMP Traps
from a Computer Associates DXserver.
Four trap types may be sent by DXserver. To enable the sending of traps in
DXserver, the following command should appear in the settings:
set snmp-log = udp <address> port <port>
where <address>:<port> is the trap address of the management application.
The traps are:
generic=6, specific=0
These are DXserver alarms. The trap contains three variables: sysName,
sysDescr and sysLocation. sysName contains the name of the DXserver and
sysLocation contains the actual alarm text.
DXserver always sends this trap when an alarm condition is detected if the
snmp-log has been configured.
This trap is sent, depending on configuration, when the DXserver has
performed an update operation. The trap contains three variables: sysName,
sysDescr and sysLocation. sysName contains the name of the DXserver
sending the trap plus some addressing information. sysLocation contains
information relating to the actual update operation.
DXserver sends this trap if the snmp-log has been configured and the
following command has been executed:
set trap-on-update = true;
This trap is sent, depending on configuration, when the DXserver detects an
authentication failure (invalid Bind credentials). The trap contains three
variables: sysName, sysDescr and sysLocation. sysName contains the name
of the DXserver and sysLocation contains the reason text.
set auth-trap = true;
This trap is sent, depending on configuration, when the DXserver refuses to
perform an operation. The trap contains three variables: sysName, sysDescr
and sysLocation. sysName contains the name of the DXserver and
sysLocation contains the reason text.
set op-error-trap = true;
15–25
Sample Tools
Usage
The dxtrap tool has the following command line-format:
dxtrap [ port ]
where port is the SNMP trap port (default: 162).
15–26
Chapter
16
Deploying a Directory
This chapter provides some general guidelines regarding the deployment of a
directory. It is broken into three major sections:
■
Directory Design
■
Operations and Practices
■
Troubleshooting
This chapter is only intended to be an introduction to good directory design,
planning, and maintenance. Good directory design and proper attention to
operational details is critical to a successful directory service.
Many of the areas listed are common sense but they are included so that you can
use this chapter as a general checklist of items to consider when deploying a
directory system.
For companies with large-scale systems, or a critical need to provide continuous
service, many more factors need to be considered. When you are designing a
large-scale system, we recommend that you contact Computer Associates
Services at http://ca.com/ for assistance.
16–1
Directory Design
Directory Design
Good directory design starts with understanding the information that the
directory contains and the way it is used.
Requirements Analysis
Generally, a requirements study will determine most of the important aspects of
the directory system such as:
■
Characteristics of the data, its size, initial load, and expected growth rate
■
The different directory applications and types of queries they use
■
The performance targets such as average response times and peak loads
■
■
The dimensioning of the hardware, network, and other supporting IT
infrastructure
How the directory is integrated with other services
Service Definition
A separate detailed service study should establish a service profile for each
directory application. This would include:
■
■
■
Type, frequency, and expected performance of searches and updates
(including adds, modifies, renames, and deletes)
Type of attributes specified in the search filter or returned from a search
Any unusual, but potentially computationally expensive, operations such as
substring and complex searches
Schema Design
After the sources and consumers of information are identified, you can
determine the set of all possible attributes. Generally, the schema designer
should try to use existing standard schema attributes where possible. Where no
standard schema exists, you should create a custom attribute.
You need to collect attributes into object classes. Generally, you combine related
attributes to form object classes. Objects should have real world meanings (such
as person, device, product), and be sensible units for directory-enabled
applications to use. See the chapter “Schema Definition” for more information.
16–2
Directory Design
Directory Enabled Applications
The schema design should take into account the way that the information will be
used by directory applications. Some applications require read-only access, while
others require both read and update. Some applications have very high demand
for particular attributes, while other attributes are rarely used. Some attributes
are shared by many applications, while other attributes are particular to only one
application.
It is essential to organize information so that the directory can cope with the
maximum loading. You can group frequently used attributes together. It can also
result in a design where objects are deliberately split or combined because some
higher-level operation (for example, setting up a role) requires updates to many
attributes across many objects.
Namespace Design
A well-designed Directory Information Tree (DIT) is a key to scalability and
manageability. The namespace design needs to consider:
■
■
■
Geographic partitioning—when the directory is distributed in regions
Security and management policies—when parts of the directory are
accessed or managed in subtrees
Common objects—to avoid duplicating information required by different
DIT branches
It is important that the naming structure is stable. This means choosing naming
attributes that do not change often and a DIT structure that is as fixed as
possible.
Security
Security policies must cover all aspects of security. This includes:
■
■
■
■
Physical security—who has access to a site, a machine, or the directory
software itself
Authentication—who is permitted to access and manage information in the
directory
Access controls—which information is protected from unauthorized changes
Sensitivity—some information may be confidential or have business value
to third parties
16–3
Directory Design
Dimensioning
A system can run many databases and many directory servers across multiple
sites. It is important that machines have enough disk memory and processors,
and that the configuration of DSAs makes best use of this hardware. Even
though the cost of hardware can be significant, an appropriate investment here
can offset large operational costs.
Performance
Performance relies upon the power of the hardware and network in use and the
configuration and tuning of the directory and database software. Often
additional indexes or additional servers can make a big difference to
performance. Items to consider include:
■
■
■
■
Security—affects performance if the access control scheme is too complex or
if every link employs SSL authentication. See the chapter “Security” for more
information about SSL authentication.
Logging—degrades performance if too much logging is enabled, particularly
diagnostic logging. See the chapter “General Administration” for more
information about logging.
Query streaming—reserves particular DSAs for high-speed lookups and
diverts known slower queries, for example substring searches to other
dedicated DSAs. It can also divert slower updates to dedicated DSAs. See the
chapter “Distribution and DSP” for more information about query
streaming.
Load sharing—lets servers share load across CPUs or across machines. See
the chapter “Distribution and DSP” for more information about load sharing.
Availability
Availability can be improved by providing a number of strategies. This may
include:
■
■
16–4
Hardware—backup power supplies, RAID disks, or backup machines
Network—providing multiple network interfaces and links between
machines
■
Directory servers—configuring alternative DSAs
■
Databases—using replication to provide alternative data stores
Directory Design
Synchronization
Often, you must synchronize data with external systems. It is important therefore
to establish a list of sources and targets, and the timing and types of data that
must be exchanged. Often, you must perform normalization to filter out
duplicate entries, rude words, or map fields from one form to another. Planning
the timing of the synchronization is important because synchronization is
usually performed using a batch mode process.
Scalability and Distribution
Many DSAs can run on one machine for the purpose of:
■
Coping with large number of users
■
Splitting a large DIT into smaller, more manageable pieces
■
Achieving load balancing or query streaming
In addition, directory servers can run at multiple sites over regions, countries or
across the world. In this case, it is important that the separation of DSAs take
advantage of geography so that servers are concentrated in areas of highest
demand.
Complexity
Keep it simple. eTrust Directory is very flexible in terms of its features. However,
complex designs can be hard to understand and maintain. Always justify why a
configuration needs to be more complex.
16–5
Directories provide a service. Often, service level agreements gives contractual
commitments on outage, response times, and escalation plans. It is critical to
define and adhere to formal practices and procedures.
Management
All aspects of the system including personnel, applications, services,
infrastructure, and day-to-day operations must be managed. There are many
factors often not considered early in a directory project lifecycle including:
■
Training—especially for operations staff
■
Support—such as hardware and software contracts
■
Upgrades—how systems will transition with minimum down time
Monitoring
Monitoring determines the health of a system. Generally, it will cover the
following areas:
■
Polling—using a protocol such as SNMP
■
Probing—involving periodical queries to test performance
■
■
■
Alarms—relying on systems to generate alerts when unexpected situations
arise
Log file analysis—scanning errors and linking into other alarm software
Indirect—inferring that something is wrong because other applications are
not functioning properly
Capacity Planning
Over time it is necessary to monitor existing platforms to show trends in growth.
When additional hardware, network capacity, or licenses are required, the
upgrades need to occur in a planned, orderly manner.
16–6
Backup and Restore
This is probably the most important procedure in the system. It is very important
that you accurately document the backup procedure and ensure that it takes
place at specified times. Backups should occur daily.
You can perform database backups using the utility dxbackupdb. The
dxbackupdb utility can perform on-line backups of the database even when there
are DSAs updating the database.
Following standard industry practices, you should regularly test your backup
procedures by attempting to restore your backups onto a test system. You should
also perform a restore before any system configuration changes or tuning. The
restore time needs to be calculated, as it is crucial in meeting outage service level
agreements.
You can perform database restores using the Dxrestoredb tool.
See the chapter Using JXplorer for more information about backup and restore
tools.
Journaling
In addition to database backups, known as checkpoints, Advantage Ingres can
maintain a journal of all committed transactions since the last checkpoint. To
enable journaling, use the command:
dxbackupdb +journal dbname
Journaling should be enabled in operational environments. If journaling is
enabled, backups (dxbackupdb) should be run more frequently, preferably every
night. This prevents the journal logs from becoming too large and reduces
recovery time if you have to roll forward the changes (dxrestoredb).
Note: If dxindexdb is used, the journals must be re-enabled to let the journals
track the new indexes. Perform the following sequence of commands:
dxbackupdb dbname
dxindexdb dbname –reverse attrName
dxbackupdb +journal dbname
See DB Tools in the chapter “Using DXtools” for more information.
16–7
Database Tuning
You should tune the directory database periodically to maintain optimum
performance.
You can use the dxtunedb utility in simple or full mode. In simple mode the
dxtunedb utility can be run while the DSA is online as it just builds table
statistics. This improves performance of the Advantage Ingres Query Optimizer.
To tune while the DSA is online, use the following command:
dxtunedb demo
In full mode the dxtunedb utility rebalances tables to optimize storage layouts,
rebuilds indexes to remove overflow pages, builds table statistics to help the
query optimizer, and tunes the system tables. We recommend that you execute
this utility after bulk loading or other large-scale modifications, and after a
period of gradual modification.
The dxtunedb utility requires at least 25 percent free disk space (for temporary
tables) and takes approximately one minute per 1,000 entries to complete a full
tune.
To perform a full tune, shut down any DSAs connected to the database and use
the following commands:
dxbackupdb demo
dxtunedb –full demo
dxbackupdb demo
Change Control
There are some basic principles of change management required to ensure the
ongoing consistency of the directory:
■
■
■
■
16–8
Subdirectories of the config directory contain the directory configuration
files. The configuration files contain the operational controls and schema
definitions for one or more DSAs. You should back up this config directory
in synchronization with copies of the matching Advantage Ingres database
set.
You should manually track modifications to the configuration files while
maintaining appropriate backup copies. You may want to consider a source
control system.
You should test configuration changes against test and development copies
of the directory database rather than the live database.
You can switch test databases into production, in a live environment, using
the hot swap facility.
Upgrades
Over time, you need to install new versions of software for the directory,
database, or operating system to fix problems, add new functionality, or provide
performance features. You should build prototype systems first on separate
machines to validate the new system before going live.
Important! Always check the latest release notes for details of software changes,
particularly in the area of schema. The product schema files can evolve to follow changing
standards. Using these latest standards can break existing applications when they have
not been modified to keep pace with these changes. When it is not desirable or practical to
change existing applications, then these should use the existing schema on the upgraded
software.
Maintenance
Periodically, systems should be scheduled for maintenance to perform various
housekeeping tasks, such as disk defragmentation, hardware upgrades, or
software patches. The first maintenance step should be a backup sequence as
follows:
dxbackupdb demo
dxtunedb –full demo
dxbackupdb demo
This ensures that the database tables and indexes are optimally laid out.
16–9
Troubleshooting
Troubleshooting
This section covers various areas that may cause problems in operational
systems. See DB Tools in the chapter “Using DXtools” for more information
about alarms, warnings, and logs.
Optimizing Performance
Performance problems generally arise because of unexpected demands on the
system. The following is a list of possible areas to investigate:
■
■
■
■
■
■
Resources—When a system is under peak loads, there may not be enough
CPU or disk to process all the required requests. Ensure that you have done
sufficient capacity planning and traffic analysis to determine the amount of
hardware required to achieve the given service levels.
Load-sharing DSAs—On a multi-CPU box it may be necessary to run a
router DSA and multiple load-sharing DSAs to make use of all the CPUs on a
given machine.
Query-streaming DSAs—When there is a large variation in the types of
queries, then different DSAs can be dedicated for different tasks, for
example, lookup queries, updates, and complex queries. If the lookup
queries are additionally handled by a load-sharing group of DSAs then the
system effectively can reserve DSAs to handle small, fast lookup queries
regardless of what else is going on in the system.
Database tuning—This optimizes the data layout in the database tables. You
should tune the database after large-scale modifications. The dxtunedb
utility can perform an on-line tune or full tune (“-full”) if all the DSAs are
taken off-line.
Advantage Ingres tuning—You can tune the cache and a number of other
Advantage Ingres parameters in mission-critical sites. Contact Computer
Associates at http://supportconnect.ca.com for advice.
File system tuning—On UNIX, the tunefs utility can optimize disk partitions
to minimize access times. We recommend that you run tunefs when you add
new hard drives, before you add data to the new device.
Managing Large Numbers of Users
The UNIX operating system limits the number of file descriptors per process (for
example, 1024). This limits the number of users who can bind to a DSA at any
one time. When the number of users is large, you can run multiple DSAs, all
connecting to the same database (DIB).
16–10
Troubleshooting
Managing Large Numbers of Entries
When the DIT contains very large numbers of entries, you can split it into a
number of subtrees (each having, for example, 100,000 entries). You can run a
DSA for each subtree with a master top-level DSA. You can then link the DSAs
with local DSP configurations.
When a database needs to have a large number of entries, then the database can
be split over multiple locations. Use the dxextenddb utility to create such
locations. (See DB Tools in the chapter “Using DXtools” for more information.)
All database tools make use of multiple locations and can handle large (> 2 GB)
files.
When you need to load a large number of entries initially, use the bulk load tool
DXloaddb. When there are a large number of changes to be made, or a large
number of entries added to an existing database, consider extracting the existing
data into an LDIF file using the DXdumpdb tool. Manipulate the LDIF file
(merge it with new data), and reload the data using the bulk load tool DXloaddb.
Limiting Users
There are many ways to control users, including the following:
■
■
■
Security—Limit access to a directory through authentication and access to
particular data through access controls.
Service controls—Set service controls such as time limits and size limits on
operations.
Flow control—Use DXserver’s “credit” facility to prevent a client flooding a
DSA with requests. This works by simply not reading bytes on that client’s
socket so that TCP/IP back pressures then restricts that client’s ability to
send data on that connection.
16–11
Appendix
A
Tailoring the RDBMS
This appendix describes how to change some Advantage Ingres database
parameters. This is usually not necessary but is desirable in certain cases as
recommended by Computer Associates Technical Support.
The customizations covered in this appendix are:
■
The default page size
■
The number of cache pages
You can configure each of these using the Advantage Ingres utility cbf
(configuration by forms). You can run cbf in an OpenWindows or CDE
(Common Desktop Environment) shell window.
Keep the following navigational tips in mind:
■
■
■
When using OpenWindows, you can move the cursor up or down using ↵,
Ctrl+J, or Ctrl+K.
When using CDE you can move the cursor up or down using ↵, ↑ (up
arrow), or ↓ (down arrow).
You can advance between fields using the Tab key.
On Windows, you can configure these using cbf from the command prompt.
Navigation instructions for cbf appear on the window.
Tailoring the RDBMS
A–1
Changing the Default Page Size
Changing the Default Page Size
Under most circumstances, the best performance is obtained with a database
page size of 2 KB. However, there may be circumstances in which you want to
change this.
To change the default page size, run cbf (configuration by forms) and enter the
following:
A–2
OpenWindow
Keystrokes
CDE Keystrokes Purpose
↵
↵
Moves to DBMS server line.
ESC+conf ↵
F10
Displays the DBMS Server Parameters
window.
dd
dd
Moves to default-page-size.
ESC+edit ↵
F10
Displays popup for new value.
8192 ↵
8192 ↵
Enters new value.
ESC+cache ↵
Insert
Displays the DBMS Caches window.
↵↵
↵↵
Moves to DMF cache 8K.
ESC+edit ↵
F11
Sets cache status to ON.
ESC+end ↵
F3
Exits DBMS Caches window.
ESC+end ↵
F3
Exits DBMS Server Parameters window.
↵
↵
Yes, saves changes and end.
ESC+quit
F4
Exits cbf.
Increasing the Number of Cache Pages
Increasing the Number of Cache Pages
For systems that have a large amount of RAM, it can help to increase the number
of cache pages used. On a large production database, optimum performance is
obtained with a cache size of 60,000 pages of 2 KB per page, requiring 128 MB of
memory for the cache.
To increase the number of cache pages, run cbf , and enter the following:
OpenWindow
Keystrokes
CDE Keystrokes Purpose
↵
↵
Moves to DBMS server line.
ESC+conf ↵
F10
Displays the DBMS Server Parameters
window.
ESC+cache ↵
Insert
Displays the DBMS Caches window.
↵
↵
Moves to the largest activated cache line.
ESC+conf ↵
F10
Displays the DBMS Cache Parameters
window.
ESC+derived ↵
F11
Displays the Derived DBMS Cache
Parameters window.
ESC+edit ↵
F10
Displays popup requesting new value.
60000 ↵
60000 ↵
Enters new value.
ESC+end ↵
F3
Exits Derived DBMS Cache Parameters
for xk window.
ESC+end ↵
F3
Exits DBMS Cache Parameters for xk
Buffers window.
ESC+end ↵
F3
Exits DBMS Caches window.
ESC+end ↵
F3
Exits DBMS Server Parameters window.
↵
↵
Yes, saves changes and end.
ESC+quit
F4
Exits cbf.
Tailoring the RDBMS
A–3
Increasing the Number of Database Connections
Increasing the Number of Database Connections
eTrust Directory ships with a default configuration of 64 database connections.
However, if you are upgrading from a previous version of eTrust Directory, the
previous limit of 32 connections applies.
If you have many data DSAs running on the same machine and you then run the
DXloaddb tool, which uses many Ingres connections, you may get the following
error in II_SYSTEM/ingres/files/errlog.log:
E_US0001 Number of users has exceeded limit.
If you see this error, then the Ingres connection limit needs to be increased.
Step 1. Increase the Shared Memory Maximum (Optional)
To successfully increase the Ingres connection limit, you may need to increase
the shared memory maximum.
You can skip this step if the shared memory maximum is already higher than the
following list:
Number of Database
Connections
RAM required
32
16 MB
64
100 MB
128
200 MB
If you need to do this step, use the following table:
A–4
Platform
Action
Solaris
Edit the value of "set shmsys:shminfo_shmmax" to the
new value in /etc/system, then restart the machine.
Linux
Run sysctl -w kernel.shmmax="new value" and sysctl w kernel.shmall="new value", then restart the machine.
HP-UX
Use the sam command to update the shmmax kernel
parameter to the new value, rebuild the kernel, then
restart the machine.
AIX
No change is required because kernel parameters are
dynamic.
Windows
No change is required.
Other Customizations
Step 2. Increase the Database Connection Limit
If enough shared memory has been allocated, then you can increase the
connection limit.
1.
As the ingres user, run Configuration-By-Forms (CBF):
% su - ingres
% setenv TERM_INGRES wxterm (csh assumed)
% cbf
2.
In CBF:
a.
Press D to highlight the DBMS Server row .
b. Press Esc and type Configure.
c.
Press c until the row connect_limit is highlighted.
d. Press Esc and type Edit.
e.
Enter the new maximum value.
f.
Press Esc and type End.
g. Press Enter to save the value.
h. Press Esc and type Quit to end CBF.
3.
Restart Ingres:
% ingstop; ingstart
Other Customizations
Several other customizations are possible, and Computer Associates Technical
Support may recommend them depending on the particular site and hardware in
use. These include:
■
Enabling the backup transaction log file
■
Configuring a separate disk area for backups
■
Configuring a separate disk area for tuning
You may want to set the Advantage Ingres log folder to a different disk drive for
improved performance.
For more information, contact Computer Associates Technical Support at
http://supportconnect.ca.com.
Tailoring the RDBMS
A–5
Appendix
B
DXserver Command Language
This appendix lists the configuration commands used by DXserver.
There are six command categories. Each command category includes a number
of valid commands.
Some commands also have additional parameters. For example, the following
command is made up of the set category, the admin-user command, and the ownentry parameter:
set admin-user = own-entry
Command Categories
Command
Description
add
Creates an additional wide index.
clear
Clears a portion of the configuration information. This command is commonly
used to ensure that you load configuration details into a clear setup, rather than
laying them on top of an (possibly contradictory) existing configuration.
close
Closes a log.
set
Defines an aspect of. There are over ninety set commands.
source
Specifies a file to be loaded. This is used to make configurations using multiple
files.
trace
Enables tracing, and defines what type of tracing is enabled.
B–1
Add Command
Add Command
Command
Description
add index-wide
Create additional wide indexes for some attributes without changing any wide
indexes that have already been set up. For more information, see the section
Creating Additional Wide Indexes in the chapter “General Administration.”
Clear Commands
Command
Description
clear access
Clears all of the static access controls. Typically, this is done before loading access
controls to ensure that conflicting controls are not loaded.
clear dsas
Clears the knowledge of all DSAs. This may be done immediately before loading
knowledge.
clear indexes
Clears all indexing options on attributes.
clear schema
Clears all of the schema information. This is done before re-loading the schema,
to ensure there are no conflicting definitions for attributes or object classes.
Close Commands
Command
Description
close summary-log
Closes the summary log.
close stats-log
Closes the statistics log.
close trace-log
Closes the trace log.
close query-log
Closes the query log.
close update-log
Closes the update log.
close alert-log
Closes the alert log.
close cert-log
Closes the certificate log.
close connect-log
Closes the connection log.
Note: The alarm log cannot be closed.
B–2
Set Commands
Set Commands
Command
Description
set access-controls
Specifies whether access controls are enabled or not
set add-oc-parents
Adds superior object classes even if the client did not specify these
while adding an entry.
set admin-user
Defines access controls that apply to users who are considered
administrators of the directory.
set agreement
Specifies the details of an agreement between two DSAs for replication
purposes.
set alarm-log
Specifies the name of the file to which the alarm-log is written.
set alert-log
Specifies the name of the file to which the alert-log is written.
set alias-integrity
Specifies whether the DSA manages the integrity of alias entries, for
example, deleting aliases that point to deleted entries.
set allow-binds
Specifies whether the DSA is accepting new binds.
set always-chain-down
Specifies whether requests are chained down, overriding X.500
controls.
set attribute
Specifies all of the information relating to an attribute.
set attr-cache-reload
The default is true. When set to false, a filter with an attribute type that
is not in the attribute cache will not cause the cache to automatically
reload from the database and is considered as not present in the
directory.
To see the current value, use get dip all;.
set attr-set
Specifies a name for a list of attributes.
set auth-trap
A mechanism that can be used to hook into the authentication
processing on the DSA using SNMP traps.
set cache-attr
Defines the attributes returned in a fast lookup (DXcache). The value
all-attributes can be used to ensure that all attributes are cached;
however, when a large number of attributes are used, this will require
a large amount of memory.
set cache-index
Sets the attributes to index in DXcache. The cache will respond to a
search filter that uses one of these attributes. You can define as many
as you like, separated by commas. Memory requirements are affected.
set cert-log
Specifies the name of the file to which the cert-log is written.
set connect-log
Specifies the name of the file to which the connect-log is written.
B–3
Set Commands
Command
Description
set credits
A control used to regulate the DSA—new requests are accepted until
the number of credits is exhausted.
set database-name
Specifies the name of the Advantage Ingres database used by the
directory.
set dbconnection
Specifies the elements of a database connection.
set dsa
Specifies the knowledge of a DSA.
set dynamic-access-control
When TRUE, enables dynamic access controls; when FALSE, disables
dynamic access controls.
set eis-count-attr
Specifies the name of the attribute that is used when you want a count
of matches, instead of a list of matching entries.
set group
Defines a group of users. Groups are used when defining access
controls.
set hold-ldap-connections
When TRUE, prevents a DSA from clearing the underlying TCP/IP
connection after a bind refusal. The default value is FALSE.
set index-reverse
Lists the attributes to which to apply reverse index.
set index-wide
Lists the attributes to which to apply wide index.
set ignore-name-bindings
Lets the DXserver operate without name bindings. This is useful when
the schema is imported from a directory that does not support name
bindings.
set limit-list
Specifies whether the DSA should reject all list requests. This is useful
when there are thousands of entries under one node.
set limit-search
Specifies whether to limit the types of searches processed by the DSA.
This causes searches with no filter or with a filter containing an
attribute present; substring any; or a range of values to be rejected.
set lookup-cache
Specifies whether DXcache is enabled or not.
set max-bind-time
Specifies the maximum time a bind is held before being disconnected.
set max-cache-size
Sets the maximum amount of memory (in MB) that DXcache uses. This
value depends on how much memory your computer has. You should
set this to around 50% to 70% of your machine’s total memory,
depending on other programs’ memory requirements on the same
computer.
set max-dsp-ops
Specifies the maximum number of DSP operations that are accepted
simultaneously.
set max-local-ops
Specifies the maximum number of simultaneous local operations that
this DSA will accept.
B–4
Set Commands
Command
Description
set max-op-time
Specifies the maximum amount of time a single operation takes before
it is aborted.
set max-op-size
Specifies the maximum size of an operation that is accepted by this
DSA.
set max-users
Specifies the maximum number of simultaneous users on a DSA.
set min-auth
Specifies the minimum level of authentication that is accepted.
set modify-on-add
Adds modifyTimestamp to a newly created entry. Used for SAP
compatibility.
set multi-casting
See set multi-chaining.
set multi-chaining
Specifies whether requests are chained to other DSAs.
set multi-write-disp-recovery
Enables or disables multiwrite DISP. The default value is FALSE.
set multi-write-queue
Specifies the maximum size of the queue of requests to be written to
other DSAs.
set multi-write-retry-time
This defines the time (in seconds) at which DXserver will attempt to
bind to a Multiwrite peer which cannot be contacted.
The default value is 60 seconds.
set name-binding
Specifies all of the information relating to a name binding, which
specifies an acceptable parent-child relationship between two object
classes.
set not-searchable
Lists attributes that are not to be searched.
set object-class
Specifies all of the information relating to an object class.
set oid-prefix
Specifies a name for an OID, which is used as a prefix when specifying
the OIDs for attributes, attr-sets, and object classes.
set op-error-trap
A mechanism that can be used to hook into the handling of errors
using SNMP traps.
set op-attrs
Specifies whether operational attributes are enabled.
set password-age
Sets the number of days a password is valid.
set password-force-change
Forces users to change their passwords after their passwords have
been reset.
set password-history
Sets the maximum number of entries to retain in the history.
set password-last-use
Sets the number of days a password remains valid. When the value is
exceeded, the password expires.
set password-length
Sets the minimum length of a password.
set password-allow-locking
Allows user accounts to be suspended by locking the password. This
B–5
Set Commands
Command
Description
does not delete the password.
set password-max-suspension
Sets the number of seconds after which a suspended password
reactivates.
set password-min-age
Sets the number of days since a password was changed last before it
can be changed again (lockout period).
set password-non-alpha-num
Sets the minimum number of nonalphanumeric characters a password
contains.
set password-numeric
Sets the minimum number of numeric characters a password contains.
set password-policy
Specifies whether password management is enabled.
set password-retries
Sets the number of consecutive failed logon attempts before a
password is suspended.
set password-storage
Specifies a password storage method.
set precedence
Specifies a precedence rule, ordering DSA knowledge.
set protected-items
Defines static access controls, which apply to an item or items within
the directory.
set prune-oc-parents
Removes redundant superior object classes when new entries are
created.
set public-user
Defines static access controls that apply to users who are public users
of the directory. A public user is an unidentified user (anonymous
user).
set query-log
Specifies the name of the file to which the query-log is written.
set reg-user
Defines static access controls that apply to users who are registered
users of the directory. A registered user is an identified user (as
opposed to an anonymous user).
set relaxed-not-search
Interprets NOT in the non-standard manner supported by some other
directories.
For example, a search for "description not equal M*" returns entries
that have nothing in the description and all entries that do not start
with M. When the flag is false (or not set), a search returns only entries
that have the attribute populated and do not start with M.
set return-oc-parents
Replaces the superior object classes of entries retrieved when
searching.
set role-subtree
Specifies the DN where the roles are defined.
set snmp-log
Specifies the port address and server to which SNMP traps is written.
set ssl-auth-bypass-entry-check
Allows a bind to skip the server authentication step if it has already
B–6
Set Commands
Command
Description
authenticated itself to the SSLD.
set stats-log
Specifies the name of the file to which the stats-log is written.
set summary-log
Specifies the name of the file to which the summary-log should be
written.
set syntax-alias
Creates a syntax alias for use when an attribute syntax is not
supported by eTrust Directory.
set super-user
Defines static access controls that apply to users who are considered
super-users of the directory.
set trace
Specifies tracing options.
set trace-level
Specifies the level of detail when tracing.
set trace-log
Specifies the name of the file to which the trace-log is written.
set transparent-routing
When set to true, enables a router DSA to route LDAP queries without
knowing the related schema.
set trap-on-update
A mechanism that can be used to hook into the processing of updates
on the DSA using SNMP traps.
set trust-sasl-proxy
Specifies the distinguished name of the trusted proxy.
set unique-attrs
Specifies attributes which are to have a unique value.
set update-log
Specifies the name of the file to which the update-log is written.
set use-roles
Set to true to enable role-based access controls; set to false to disable
role-based access controls.
set user-idle-time
Specifies the maximum time a user is idle before being disconnected.
set warn-log
Specifies the name of a separate file for error and warning messages.
Ensure that at least warn or error tracing is turned on.
set write-precedence
Specifies which DSAs are chosen to perform updates.
B–7
Set Commands
The set admin-user Command
Use the set admin-user command to specify static access controls. See the chapter
Parameter
Description
attrs
Lists attributes to which this access control applies.
auth-level
Specifies the level of authentication required. May be simple, ssl-auth.
entry
Specifies an entry to which access is granted.
group
Specifies a group of users for admin-user access.
own-entry
Specifies a user as admin-user for their own entry.
perms
Lists the permissions granted. May include read, add, remove, modify, rename,
all.
subtree
Specifies a subtree of the directory to which access is granted.
user
Specifies a named user to be treated as an admin-user.
user-subtree
Specifies a subtree within the user tree; users in this subtree are affected by this
access control.
validity
Specifies the period during which this is valid. May include start, end, on.
The set agreement Command
Use the set agreement command to define a DISP connection between two DSAs.
See the chapter “Replication” for more information.
Parameter
Description
area
Specifies the portion of the DIT covered by this agreement.
initiator
Specifies the name of the initiating DSA, and whether that DSA is the supplier or
consumer in the DISP connection.
relay
Specifies the name of the intermediate relay DSA. These parameters may include
anonymous, clear-password, ssl-auth.
responder
Specifies the name of the responding DSA, and the parameters of the connection.
These parameters may include anonymous, clear-password, ssl-auth.
strategy
Specifies when the interchange of data takes place. May include on-change,
minutely, hourly, daily, weekly, monthly, incremental, full.
B–8
Set Commands
The set attribute Command
Use the set attribute command to define an attribute, which is a basic building
block in the schema. See the chapter “Schema Definition” for more information.
Parameter
Description
description
A description of the attribute.
equality
Indicates the type of matching to apply to the attribute.
ldap-names
Alternative names for the attribute. Think of these as nicknames—
they can be used anywhere the name can be used. Often these are
shorter, and used in DNs, for example, c for country.
name
The name of the attribute. This is its formal name, and is often
descriptive.
no-user-modification
Indicates whether the user can modify the value of the attribute
ordering
Indicates the ordering rules to apply to the attribute.
single-valued / multi-valued
Indicates whether the attribute has multiple values (for example, lines
of an address), or is limited to a single value (for example, salary).
substr
Indicates the substring-matching rule to apply to the attribute.
syntax
Indicates the type of data that may be stored in the attribute.
The set dsa Command
Use the set dsa command to define the knowledge of a DSA. See the chapter
“General Information” for more information.
Important! You must declare the parameters in a set order.
Parameter
Description
prefix
Specifies a partial DN, which specifies the portion of the DIT served by this
DSA.
native-prefix
Specifies a partial DN, which the DSA recognizes as applicable to its entries—
generally only used with LDAP servers.
dsa-name
Specifies the name of the DSA as a DN; not to be confused with the name of the
server
dsa-password
Specifies the password other DSAs must supply to communicate with this DSA.
ldap-dsa-name
Specifies the name of the LDAP DSA.
ldap-dsa-password
Specifies the password of the LDAP DSA.
B–9
Set Commands
Parameter
Description
address
Specifies one or more addresses (TCP/IP address + port number) the DSA.
tsap
Specifies Transport SAP.
ssap
Specifies Session SAP.
osi-psap
Specifies Presentation SAP.
disp-psap
Specifies DISP Presentation SAP; if absent, DISP is disabled.
cmip-psap
Specifies CMIP Presentation SAP; if absent, CMIP is disabled.
snmp-port
Specifies the SNMP port.
console-port
Allows DXconsole to accept connections from the local computer. When this is
not specified, the DSA does not have a local console.
remote-console-port
Allows DXconsole to accept a connection from a remote computer on this port.
When this is not specified, there is no remote console for the DSA.
remote-console-ssl
Forces DXconsole encryptDXconsole sessions when it runs remotely.
console-password
The password required for connections from a remote computer. This password
is transmitted in clear text.
ssld-port
Specifies the port number that should be used for SSLD.
auth-levels
Specifies the levels of authentication that will be accepted by this DSA. May
include anonymous, clear-password, and ssl-auth.
dsp-idle-time
Specifies the maximum time (in seconds) that a DSP connection can be idle
before it is disconnected.
dsa-flags
Specifies the flags that control the operation of the DSA. The flags include
multiwrite, shadow, read-only, relay, load-share, no-routing-ac, limit-search, limit-list,
and multi-write-notify.
trust-flags
Specifies flags relating to trust that control the operation of the DSA. The flags
include allow-check-password, trust-conveyed-originator, allow-upgrading, allowdowngrading, and no-server-credentials.
link-flags
Specifies flags that control connecting to the DSA. The flags include dsp-ldap,
dsp-ldapv2, ms-exchange, ms-ad, ssl-encryption, and unavailable. For a complete list,
see Link Flags in the chapter “General Administration.”
B–10
Set Commands
The set name-binding Command
Use the set name-binding command to define a name binding. This defines the
hierarchy of the directory. See the chapter “Schema Definition” for more
information.
Parameter
Description
allowable-parent
Specifies the parent and child object classes.
name
The name of the name binding. This is often descriptive; it can be constructed by
concatenating the names of the object classes being connected.
named-by
Lists the attributes that name an object of the child object class. Often only one
attribute is listed.
optional
Lists attributes that may optionally be appended to the list specified in namedby.
The set object-class Command
Use the set object-class command to define an object class, which is a fundamental
part of the schema, and essential to the directory. See the chapter “Schema
Definition” for more information.
Parameter
Description
description
A description of the object class.
kind
Specifies the kind of object class—may be structural, auxiliary, or abstract.
ldap-names
Alternative names for the object class. Think of these as nicknames—they can be
used anywhere the name can be used. Often these are shorter.
may-contain
Lists the attributes that may be supplied in an instance of this object class.
must-contain
Lists the attributes that must be supplied for every instance of this object class.
name
The name of the object class. This is its formal name, and is often descriptive.
subclass-of
Specifies the object class, or object classes, from which this object class inherits.
B–11
Set Commands
The set protected-items Command
Use the set protected-items command to specify static access controls. Generally,
you use protected-items controls to protect specified attributes in a specified
portion of the DIT. See the chapter “Security” for more information.
Parameter
Description
attrs
entry
Specifies an entry to which this access control applies.
group
Specifies that this control applies to a particular group of users.
own-entry
Specifies that this control applies to a user accessing their own entry.
perms
Gives registered users access to modify 'role' attribute in their own entries.
subtree
Specifies a subtree of the directory to which this access control applies.
user
Specifies that this control applies to a particular user.
user-subtree
access control.
validity
The set public-user Command
Use the set public-user command to specify static access controls. See the chapter
Parameter
Description
attrs
entry
perms
all.
subtree
validity
B–12
Set Commands
The set reg-user Command
Use the set reg-user command to specify static access controls. See the chapter
Parameter
Description
attrs
entry
group
Specifies a group of users to be treated as a reg-user.
own-entry
Specifies that a user may be treated as a reg-user for their own entry.
perms
all.
subtree
user
Specifies a user to be treated as a reg-user.
user-subtree
access control.
validity
The set super-user Command
Use the set super-user command to specify static access controls. See the chapter
Parameter
Description
auth-level
Specifies the level of authentication required. May be simple, ssl-auth.
group
Specifies a group of users to be treated as a super-user.
own-entry
Specifies that a user may be treated as a super-user for their own entry.
user
Specifies a user to be treated as a super-user.
user-subtree
access control.
validity
B–13
Source Commands
Source Commands
A source command is a means of including shared commands. It says, “Include
the contents of this file here.” You can nest source commands, and source a file
that contains further source commands. An example is shown below:
source “file2.dxg”
set access-controls
= true;
source “file3.dxc”
set group =
source “file4.dxc”
set super-user =
set reg-user =
B–14
Trace Commands
Trace Commands
You can specify trace commands in two ways:
■
You can enter them as arguments to a trace command. For example:
trace all;
■
You can enter them as parameters to a set trace command. For example:
set trace = all;
Command
Description
trace alert
Displays authentication errors.
trace all
Traces everything.
trace dsa
Similar to the x500 trace, but also includes tracing of the module flow inside the
DSA.
trace cert
Displays certificate operations.
trace connect
Displays connections.
trace error
Displays error messages of very high severity. Compare with TRACE WARN.
trace ldap
Traces detailed LDAP operations.
trace limit
Traces any violation of size or time limits.
trace none
Traces nothing.
trace query
Displays a one-line summary containing the server request and result.
trace stack
Displays detailed protocol tracing.
trace stats
Displays statistical information for each minute the DSA is not idle.
trace summary
Displays summary information.
trace time
Displays the start time, end time, and elapsed time of an operation with a brief
summary of the operation.
trace update
Displays update operations—add, delete, modify, and rename.
trace warn
Displays error messages of moderately high severity. Compare with TRACE
ERROR.
trace x500
Displays the full details of the service request, confirmation, or error. This traces
DAP, DSP, and LDAP operations.
B–15
Appendix
C
Messages and Logs
This appendix describes the error and diagnostic logs that eTrust Directory
provides to assist you in diagnosing problems. It also explains some common
alarms and warning messages.
For further information, contact Computer Associates at
UNIX System Error Log
Both UNIX and DXserver log errors to the system error log. By default, the
system also displays all errors in the console window.
The system error log file is located in …/var/adm/messages.
A useful command for showing the most recent messages is:
%$ dmesg
Windows Event Log
Both Windows and DXserver log errors in the Windows event log. You can view
the event logs in the Windows Event Viewer.
To display the Event Viewer, click Start on the taskbar, and then choose
Programs, Administrative Tools (Common), Event Viewer.
DXserver logs errors in the Application Log. You can view the Application Log
by selecting Event Viewer Log, Application.
Messages and Logs
C–1
DXserver Logs
DXserver Logs
DXserver logs all errors, alarms, and warnings to server-specific log files. Each
server has both an alarm log and is usually configured with a trace log. The
server alarm log provides more detail than the system error log, while the trace
log provides additional diagnostic information.
Note: If an error is encountered while starting DXserver, the server cannot start,
and diagnostics are logged to these server-specific logs rather than to the system
error log.
When a DXserver fails to start or is not behaving as expected, consult the server
logs.
On UNIX, the server log files are:
$DXHOME/logs/servername_alarm.log
$DXHOME/logs/servername_trace.log
On Windows, the server log files are:
%DXHOME%\logs\servername_alarm.log
%DXHOME%\logs\servername_trace.log
In all cases, substitute the name of your server for servername.
C–2
Advantage Ingres Logs
The Advantage Ingres RDBMS server reports all database-related errors to a
single log file. This file may contain more detailed diagnostics about databaserelated problems than the DXserver alarm log.
On UNIX, the Advantage Ingres error log file is:
$II_SYSTEM/ingres/files/errlog.log
On Windows, the Advantage Ingres error log file is:
%II_SYSTEM%\ingres\files\errlog.log
DSA Does Not Start and Alarm Log Reports "Database is inconsistent"
The alarm log reports something like this:
20040305.084328 DIB001: Unable to connect to database 'democorp' as ' '
SQL error (-39100): E_US0026 Database is inconsistent. Please contact the system
manager.
Reason:
A database "goes inconsistent" when Ingres does not know what state the
database is in. This is often caused by a hardware failure or hard shutdown. The
recommended method of recovery is to restore from backup.
The Ingres error log may give some indication as to why the database is
inconsistent. Things to look for include an absence of shutdown messages,
references to hardware problems (could not write to disk, etc), or anything OS
related.
Action:
For non-critical databases, the following ingres command can be used:
verifydb -mrun -sdbname "democorp" -oforce_consistent
This will give you several warnings. The force_consistent command is used to
permit entry into a database that is inconsistent. This does not fix the problem
with the database; it merely allows you to force the database to act as if it were in
a consistent state. This can be very dangerous if used against a production
database. Hidden data damage may render one or more tables in the database
unrecoverable at some time in the future.
Messages and Logs
C–3
I get "failed to connect" errors
E_LQ0001 Failed to connect to DBMS session.
E_LC0001 CGA protocol service (GCA_REQUEST) failure.
Internal service status E)GC0139 -- No DBMS servers (for the specified
database) are running in the target installation.
Reason:
This usually means that Ingres is not started.
Action:
The easiest way to resolve this is to stop and restart Ingres. The process differs
slightly for Windows and UNIX/Linux platforms.
To stop and restart Ingres on a Windows computer:
1.
From the Services menu, look for the status of Ingres Intelligent Database.
2.
If it is "starting" then either be patient, or manually kill the processes (see
below). Stop the Service.
3.
After Ingres had stopped, check Task Manager for the following processes:
4.
-
iigcc (comms server, optional)
-
iigcn (name server)
-
iidbms (one or more DBMS servers)
-
dmfrcp (recovery server)
-
dmfacp (archiver)
Try one or more of the following:
-
Manually kill any processes remaining.
-
Reboot the computer.
-
Stop Ingres again.
5.
Start Ingres again.
6.
Check that all the processes listed above are running. If one or more
processes failed to start, then send the ingres errlog.log to CA Technical
Services.
To stop and restart Ingres on a UNIX or Linux computer:
1.
Enter the following command to stop Ingres:
ingstop
2.
After the ingstop command completes, check ps -ef' for the following
processes:
-
C–4
iigcc (comms server, optional)
3.
4.
-
iigcn (name server)
-
iidbms (one or more DBMS servers)
-
dmfrcp (recovery server)
-
dmfacp (archiver)
Try one or more of the following:
-
Manually kill any processes remaining.
-
Reboot the computer.
-
Stop Ingres again.
Enter the following command to start Ingres:
ingstart
5.
Check that all the processes listed above are running. If one or more
processes failed to start, then send the ingres errlog.log to CA Technical
Services.
6.
To test a connection, type 'sql iidbdb' at the command prompt. If you get an
asterisk prompt, then the connection succeeded. Type '\q' to quit. If the
connection failed, then screendump the output, and pass it to your favourite
Ingres whiz, along with the errlog.log.
DSA Does Not Start and Alarm Log Reports “No DBMS Servers”
If your alarm log has the following text, your IngresDBMS server is not setup
correctly.
Unable to connect to database 'democorp' as \'\' SQL error (-38100): E_LQ0001
Failed to connect to DBMS session. E_LC0001 GCA protocol service (GCA_REQUEST)
failure. Internal service status E_GC0139 -- No DBMS servers (for the specified
database) are running in the target installation..
Reason:
One of the causes of the above error is that the IngresDBMS server startup count
it set to 0 instead of 1.
Action:
If this error message has occurred on a production computer, you will need to
contact eTrust Directory support for help.
If this error message has occurred on a test computer and you previously had
enterprise eTrust Directory, and you just installed embedded eTrust Directory,
run the test again with a valid eTrust Directory license before you run the
embedded install.
For more help, please contact CA Technical Services.
Messages and Logs
C–5
Ingres Error Log Reports “Unknown ipcclean” (Windows Only)
Reason:
If you have the cygwin toolkit installed, an option inside this package includes a
file called ipcclean. If cygwin\bin is in your path, then when you install, Ingres
will try to use this ipcclean tool instead of the one installed by Ingres. This will
cause the post-installation setup to fail.
Action:
C–6
1.
Uninstall eTrust Directory.
2.
Check your computer is clean by using CleanReg.exe.
3.
Rename cygwin ipcclean to ipcclean.old and re-run the install.
4.
Do one of the following steps:
-
Move Ingres\bin to the beginning of the %PATH% environment
variable.
-
Rename the cygwin tool to ipccleanCygwin and leave the path as is.
DXserver Alarm Messages
Database dbname has more entries (n) than license allows (m)
Reason:
The number of entries in the DXserver database has been exceeded. (This is only
relevant to legacy licenses, not those issued by Computer Associates.)
Action:
Either reduce the number of entries in the database or purchase a larger license.
Database attribute attribute-name has different syntax than schema
Reason:
The syntax of the attribute-name definition in the DSA schema has been
changed; however, directory entries have been created with the old syntax.
Action:
You must roll back the syntax in the schema. When you need a new syntax,
dump the database using DXtools, and then create a new one with the new
syntax.
Database attribute attribute-name not defined in schema
Reason:
The attribute attribute-name presented in the LDAP (or DAP) call has not been
defined in the schema.
Action:
Check the attribute-name definition. It is possible that the LDAP client has
misspelled the attribute. Alternatively, the LDAP client may be using an attribute
name not defined in the schema. If the latter is true, define the attribute
appropriately.
Messages and Logs
C–7
Error in initialization files
Reason:
One or more of the DXserver initialization files (.dxi) in the servers subdirectory
are not configured correctly.
Action:
Check the configuration of the initialization files.
Out of memory
Reason:
The DSA has run out of memory when processing the result of a large search.
Action:
Reduce the number of results returned by single searches by breaking them into
a number of separate, smaller searches, each returning part of the result. Also,
consider increasing the amount of virtual memory.
Prefix too large
Reason:
The DSA prefix is greater than 255 characters.
Action:
Shorten the DSA prefix.
Rejected console request
Reason:
More than one telnet session has attempted to connect to the DXserver console.
Action:
Remember that eTrust Directory supports only one console connection at a time.
C–8
DIB001: Unable to connect to database 'production'
Reason:
This message may be because the ingres user has a password, which means that
eTrust Directory cannot connect to the database.
Action:
There are two things that can be done about this:
■
Use accessdb to remove the user’s password
■
If the user must have a password, then follow these steps:
a.
Remove the following command:
set database-name = "production";
b. Replace it with this command:
set dbconnection = {db-name=production, db-user=dba, dbpassword=mypassword};
DIB001: Unable to attr load cache
Reason:
This can happen when the user that the dxserver is trying to connect to the
database as is not the owner of the database.
Action:
To resolve the problem you must give the user grants on the database. This can
be done with the DXgrantdb tool, which is provided with eTrust Directory. To
do this, run the following command:
dxgrantdb database [user]
where:
■
■
database is the name of the database where access is granted.
user is the name of the user whose access is granted. If user is omitted, all
database users will be granted access.
After running this you will be able to operate a directory on the database.
Or, you can configure the dxserver to connect as a specific user by editing the
server configuration. To edit the server configuration:
1.
Remove the following command:
set database-name = "production";
2.
Replace it with this command:
set dbconnection = {db-name=production, db-user=dba, db-password=mypassword};
Messages and Logs
C–9
DIB003
This error code refers to a problem with allocating a new internal entry identifier.
Reason:
If this is seen, then you probably have added the maximum number of possible
entries to the directory.
Action:
You may have to use distribution.
DIB004: attr aid not in cache
The DIB004 error code refers to a problem with the attribute cache.
Reason:
During a read, search, or update operation, an attribute ID was found internally
that does not exist in the attribute cache. This may be the case if the attribute was
added for the first time by another DSA using the same database.
Depending on where this was encountered and current configuration setting the
attribute cache is usually reloaded and the operation redone.
DIB004: attr aid too big for cache - unable to resize
DIB004: subattr aid too big for cache - unable to resize
DIB004: too many attributes (number of attrs) to register
The DIB004 error code refers to a problem with the attribute cache.
Reason:
These messages are indicative of a problem resizing the attribtue cache. This is
usually due to running out of memory. These errors are usually found in
conjunction with out-of-memory errors.
C–10
DIB008
This error code refers to a problem with normalising an attribute value.
Reason:
This may be the case if the attribute value is not valid for the defined attribute
syntax. The associated error message gives futher information about the type of
attribute being processed.
DIB009
This error code refers to a problem with buffer or storage sizes.
Reason:
This may be the case if the RDN (either normalised or raw) of an entry is too big.
MW-DISP: Invalid update strategy
Reason:
Standard MW-DISP (NOT cache-only) can only receive an incremental-refresh
DISP update. This message indicates it has received something other than an
incremental-refresh.
This could happen if you have a mix of cache-only and standard DSAs
configured to replicate to each other. This is not supported.
MW-DISP: Invalid update strategy for cache-only
Reason:
Cache-only MW-DISP can only receive a total-refresh DISP update because it has
no database to apply an incremental update to. This message indicates it has
received something other than a total-refresh.
This could happen if you have a mix of cache-only and standard DSAs
configured to replicate to each other. This is not supported.
Messages and Logs
C–11
Unable to connect to database - Shutting down
Reason:
This alarm is shown if during recovery from a database error, or switching
databases the DSA is unable to connect to the configured database.
Action:
If this alarm is raised, the DSA will automatically shut down.
For more information about thi, see the section Manage Connections to the
Database.
Shutting down due to SQL error
Reason:
This alarm is shown if shutdown-on-sql-error is set to TRUE in the configuration
of a DSA and an SQL error is encountered.
Action:
If this alarm is raised, the DSA will automatically shutdown.
For more information about thi, see the section Manage Connections to the
Database.
Error in initialization file
Action:
To find out which command caused this error, look in the trace log.
For example, see the following section of a router_trace.log:
20040902.123320 ERROR : Syntax Error: Line 14 in C:\Program Files\CA\eTrust
Directory\dxserver\config\settings\default.dxc near 'set'
Expected a ';'
> Setting max-users to (255)
* 20040902.123320 Error in initialization files
C–12
DXserver Warning Messages
To prevent excessive tracing and logging of repetitive warning message,
configure the affected DSA with "set trace = error". This will prevent warnings
from being logged, but will still capture real errors.
Cannot register address
Reason:
The DSA has been configured with incorrect protocol stack information.
Action:
Check the set DSA command within the appropriate knowledge file. Check the
details in the address setting.
DIP not connected to a database
Reason:
The DSA has been requested to add or update an entry within its naming context
and found that it has not been configured with a database.
Action:
Check the set database-name command in the appropriate configuration file (.dxc)
in the database subdirectory.
Database dbname entries (n) is close to license maximum (m)
Reason:
The directory exceeds 90 percent of the licensed maximum. (This is only relevant
to legacy licenses, not those issued by Computer Associates.)
Action:
Consider reducing the number of directory entries or purchasing a larger license.
Messages and Logs
C–13
Licence expires in n days
Reason:
These warnings begin 20 days before the license is due to expire. (This is only
relevant to legacy licenses, not those issued by Computer Associates.)
Action:
Consider purchasing a new license.
No stack nor console
Reason:
The DSA has been configured without any protocol stack information.
Action:
Check the set dsa command within the appropriate knowledge file. Typically, this
message occurs when there is a mismatch between the name of the DSA (from
the initialization file (.dxi) in the servers subdirectory) and the name of the DSA
used in the set dsa command in the DXserver knowledge file.
Undefined syntax not ASN.1
The DXserver syntax binary refers only to datatypes that have an ASN.1
representation. To represent arbitrary binary data, octetString is a more suitable
choice.
Attribute (attrName) exceeds searchable size limit (106) - Refer to Managing Indexes in the
Admin Guide
Reason:
This message means that an attribute value has been added that is too big to
search reliably. Some search requests may produce incorrect results. The length
of an attribute value that will generate this message can vary, but the normalised
value can only by 106 bytes long before this message is reported. Note that due
to the different normalisation techniques that can be applied it may be possible
to add data that is much bigger than 106 bytes without causing a problem. For
example a 1MB jpeg photo will not cause this problem despite it's size, while a
110 character sentence probably will.
The search overflow message points out that some values are greater than the
106 byte normalised limit and their normalised form has been truncated.
C–14
Searches that have the same first 106 normalised values will match all entries
even if they varied past this point.
Searches for values ending with a particular value will give curious results on
this data as it will be matching on the truncated value.
Note This is a limitation for searching only, data this is returned will not be
truncated.
Action:
To overcome this problem, examine the use of the data. This could fall into one of
many categories:
■
■
■
■
Never searched or compared.
In this case the warning could be ignored, or even better to save space and
speed up operations mark the attribute as not searchable
Searched only by a begins with filter item.
If the filter items are less than the 106 byte searchable limit then the warning
can be ignored.
Searched only by an ends in filter item.
Consider adding a reverse index for the item.
Other searches.
Consider adding a wide index for this attribute. This does decrease
performance, but it also increases the searchable limit to 1900 bytes. If this is
still too small then a subsearch overflow message will be reported.
rs_rsp: Credit limit reached
Reason:
This message means that a DAP or DSP client has exceeded the number of
credits configured for that connection, and flow-control has been invoked. This is
not an error, merely and informative message.
In the case where all clients are using LDAP, then this message means that a DSP
backbone link from another DSA has exceeded the value of "max-dsp-credits".
DIP: time limit exceeded
This message only applies to search operations and means that the search has
taken longer than the configured op time limit, or the requested time limit in the
search controls.
Messages and Logs
C–15
Alias Errors
WARNING: ssld_ssl_request failed – certificate error?
Reason:
This message means that there was an error with a certificate. This error will
appear with “-debug 0” is set. Setting debug level to 5 or 9 should help to find
the actual problem.
This could be due to:
■
Invalid or expired DSA personality
■
Invalid or expired root certificate
■
Invalid client certificate
■
An error with the client application
This warning may also occur when an LDAP client disconnects an SSL
connection. When an SSL connection is set up between a client and server the
two ssl daemons perform a handshake process to determine the encryption
cypher that will be used. When a server receives an unbind request then the
SSLD daemons perform another handshake operation to close the ssl session.
However, some LDAP clients perform a "close connection" rather than an
unbind. If this occurs then the server SSLD cannot send its close SSL session
request to the client as the connection between the client and the server has
already been closed. In this case the above warning will be produced.
This warning can occur even if the connection is only using SSL encryption (no
certificates involved). The certificate error is only an indication of the possible
error.
Alias Errors
Aliases are a powerful mechanism for alternate naming. However, when you do
not use them properly, the result can be inconsistent DITs and degraded
performance.
Managing aliases properly is an application design issue. When you disable alias
integrity, the DSA does not prevent the creation of aliases to nonexistent objects.
It detects and reports invalid aliases only when it encounters them.
You should enable alias integrity. This prevents the creation of dangling aliases—
that is, aliases that point to no object entry.
See The Directory Information Base in the chapter “General Administration” for
more information about DIB commands.
C–16
Service Errors
Service Errors
In rare circumstances, the DSA may find an inconsistency that is outside the
X.500 standard (for example, corrupt database tables). In this case, an X.500 error
is returned with a message sent to the console, as shown below:
Service Error: Directory unwilling to perform
If such a situation arises, contact Computer Associates Technical Support at
Advantage Ingres Errors
DXserver relies heavily on Advantage Ingres for database integrity and
processing. Usually, appropriate Advantage Ingres error codes will accompany
any database problems.
An example of the syntax of the Advantage Ingres errors reported by DXserver is
as follows:
DSA: DIB-001: Can't logon to database 'temp'
E_US0010 Database does not exist
The first line is a general error message produced by DXserver. The second line is
the Advantage Ingres error. (See the appropriate Advantage Ingres
documentation for details.)
If an Advantage Ingres error occurs, then more detail can be obtained from the
Advantage Ingres error log.
In an extreme case, a database can be corrupted. You can usually correct this by
restoring a backup and, if journaling was enabled, rolling forward all changes
that occurred after the backup. If this is not possible or the situation still exists,
you can use a number of other Advantage Ingres tools with the help of CA
Technical Support.
Some possible errors with their solutions are:
E_LQ0001 Failed to connect to DBMS session
Action:
Determine whether Advantage Ingres is running (for example, use the UNIX
command ps).
Messages and Logs
C–17
Advantage Ingres Errors
E_US000C You are not a valid Ingres user
Action:
As the UNIX user ingres (the Advantage Ingres superuser account) run accessdb,
and authorize UNIX user dsa to use the database.
E_US0DAE SELECT on table dit: no GRANT permission
Action:
Run the DSA from the UNIX user account dsa.
E_US0028 Could not open the iidbdb database
Action:
Check that you installed Advantage Ingres by running the Advantage Ingres
command ingbuild.
C–18
Appendix
D
Installing eTrust Directory for
Windows
This appendix explains how to install eTrust Directory for Windows systems.
Installing eTrust Directory for Windows
D–1
Installation Overview
The eTrust Directory setup programs automate the installation processes. These
programs check which eTrust Directory components are installed and up-todate, and either install or upgrade those components that are missing or old.
To install eTrust Directory, perform the following activities:
1.
Check the system and disk requirements.
2.
Install or upgrade the directory components of eTrust Directory.
3.
(Optional) Install or upgrade the web components of eTrust Directory.
4.
(Optional) Run the sample scripts to install the three sample directories, the
technology previews, and the sample tools.
eTrust Directory Components
The eTrust Directory installation is split into the following two sections, which
you can install separately or on the same computer:
■
■
D–2
Directory—The main eTrust Directory installation, which includes the
following modules:
-
DXserver—The eTrust Directory server, DXtools, and DXconsole
-
Ingres—A CA open-source database, which is required by DXserver if
the data repository is used
-
JXplorer—An LDAP client that lets you browse and update a directory
-
Documentation—PDF product manuals
-
Samples—Sample DSAs and sample tools for working with DXserver
Web Components—Optional web-based modules, including the following
modules:
-
DXmanager—A web-based tool for monitoring and administration
-
JXweb—A web-based LDAP client that lets you browse a directory
-
UDDI Server—A UDDI repository that functions as a business directory.
The UDDI Server requires DXserver.
-
UDDI Client—A web-based browser for the UDDI Server
-
Samples—Sample web applications, including a DSML server, a SAML
server, and a UDDI demonstration.
Default Installation Locations
By default, the eTrust Directory components are installed into the directories
listed in the following table. You can change these locations in a custom
installation.
Component
Default Directory
DXserver
C:\Program Files\CA\eTrust Directory\dxserver
Advantage Ingres
C:\Program Files\CA\Advantage Ingres [ET]\ingres
JXplorer
C:\Program Files\CA\eTrust Directory\jxplorer
DXwebserver
C:\Program Files\CA\eTrust Directory\dxwebserver
Documentation
C:\Program Files\CA\eTrust Directory\documentation
DXconsole
C:\Program Files\CA\eTrust Directory\ttermpro
Sample Directories and
Sample Tools
C:\Program Files\CA\eTrust Directory\samples
Sample Web
Applications
C:\Program Files\CA\eTrust Directory\dxwebserver\samples
The %DXHOME% Location
Throughout this guide, %DXHOME% refers to the location in which DXserver is
installed on your computer. This location is set in the DXHOME environment
variable.
For example, in a default installation, %DXHOME% is C:\Program
Files\CA\eTrust Directory\dxserver.
Installation Logging
All installations are logged.
If the DXHOME environment variable is defined, the installation log file is
created in %DXHOME%. If DXHOME is not defined, the installation log is
created in %TEMP%.
D–3
Upgrade eTrust Directory
If you have the enterprise version of eTrust Directory, you can upgrade this by
following the installation instructions in this chapter.
If you are using a version of eTrust Directory that is embedded in another
product, you must use the upgrade package from the embedding product.
Each embedding product that installs eTrust Directory has a specific process for
upgrading eTrust Directory and if this is not followed, the products will not
work as intended.
For example, if you use eTrust SSO and the embedded version of eTrust
Directory that comes with it, you must use an eTrust SSO package to upgrade
both products.
Upgrade Advantage Ingres
For a new installation, eTrust Directory embeds the single-byte version of
Advantage Ingres II 2.6 SP2, with the installation code ET. The installation
performs a standard tuning of the database parameters. You can customize these
parameters.
For an upgrade to an existing configuration, check the Readme to find out how
eTrust Directory works with the various versions of Advantage Ingres.
If you currently use Advantage Ingres 2.0 or 2.5, check with Computer
Associates’ Technical Support to find out whether the applications that use your
existing version of Advantage Ingres also support Advantage Ingres 2.6.
If you plan to have many data DSAs running on the same machine, read the
section Increasing the Number of Database Connections in the appendix
“Tailoring the RDBMS”.
D–4
Embedded eTrust Identity and Access Management
The eTrust Directory Web Components installation includes an embedded
version of eTrust Identity and Access Management. This is a security module
that DXmanager uses to make sure that your directory system is protected.
If you install DXmanager, you will have to enter details about how the
embedded eTrust Identity and Access Management module will work.
The installation gives you four options for installing the module:
■
■
■
■
Install new local eIAM Server—Installs a new eIAM Server on the same
computer as DXmanager. You will have to supply a password for the user
EiamAdmin.
Install new local eIAM Server with an external user store—You will be
prompted to close the installation program, and go back to the Product
Explorer, where you should install eIAM from the Supporting Products
section.
You might choose this option if you want to reference another user store, or
if you want to install the eIAM server on another computer.
Reference existing local eIAM Server—Lets you reference an existing
installed eIAM Server on the local computer. You will have to supply a
password for the user EiamAdmin.
Reference existing remote eIAM Server—Lets you reference an existing
eIAM server on a remote computer. You will have to supply a password for
the user EiamAdmin.
D–5
Install eTrust Directory Using the Product Explorer
This section describes how to install eTrust Directory and the eTrust Directory
Web Components using the Product Explorer.
Step 1. Check System and Disk Requirements
This section lists the checks you should make before you install eTrust Directory.
Check the System Requirements
Check the Readme for system requirements.
The disk space required for directory information is approximately 20 times the
raw data size. This provides space for backups, journals, indexing, tuning,
import, and preprocessing.
Back Up Data
If you are upgrading from an earlier version, back up your schema files.
Design the Disk Configuration
To improve recovery and performance, you should store the database
information on a separate physical disk from the product files. Be sure that the
drives you choose are actually on separate physical disks. Do not use a single
physical disk partitioned into multiple drives.
In the following example of the layout of a typical installation, the C and D
drives are on separate physical disks:
The C drive
eTrust Directory product files
Advantage Ingres product files
Advantage Ingres transaction log
The D drive
Directory information (database files)
Advantage Ingres checkpoints (database backups)
Advantage Ingres journals
Advantage Ingres work area
In Windows Explorer, partitions local to the computer have Local Disk in the
Type column. You can configure and view logical and physical drives using the
Windows Disk Administrator.
For more information about disk configurations such as mirrored disks and RAID,
contact Computer Associates Technical Support at http://supportconnect.ca.com.
D–6
Step 2. Install eTrust Directory
To install eTrust Directory:
1.
Stop all applications that may have current open connections to an
Advantage Ingres database.
2.
Log in as a user with administrator privileges.
3.
Insert the eTrust Directory CD. The Product Explorer starts automatically.
If the Product Explorer does not start automatically, double-click on
PE_i386.exe in the top-level directory of the CD.
4.
If you plan to use JXplorer, install JRE from the Supporting Products list.
5.
Navigate to Directory for Windows and click Install.
6.
To install eTrust Directory now, select the option Install eTrust Directory.
To create a response file that can be used to install eTrust Directory silently
on many computers, select the option Build response file for unattended
installation. For information about response files, see the section Install
Silently Using Response File.
7.
Follow the instructions on the installation screens until you come to the
Setup Type screen.
To install DXserver, Ingres, JXplorer and the documentation in their default
locations, select Complete and click Next, then skip to step 9.
To choose which components to install, choose Custom Setup and click Next.
8.
Select options for the components you are installing.
If you are an advanced user, you can click the Options button to configure
some aspects of Advantage Ingres. For more information, see the section
Upgrade Advantage Ingres.
9.
When you have selected the components and selected the appropriate
options, the Setup wizard displays a message telling you that it is ready to
install the selected files.
Use the Back button to review your selections before finalizing the
installation.
10. When the installation is complete, the Advantage Ingres Intelligent Database
service starts automatically, and the sample scripts run if you selected this
option. The samples are run in a default installation, but not in a default
upgrade from a previous eTrust Directory version.
You do not have to reboot the computer after installation.
D–7
Step 3. (Optional) Install eTrust Directory Web Components
You can install the web components of eTrust Directory on a different computer
from the main directory components.
To install eTrust Directory Web Components:
1.
Log in as a user with administrator privileges.
2.
3.
If Java Runtime Environment is not already installed, install it from the
Supporting Products list.
4.
If you plan to use the UDDI Server, make sure that the directory component
is already installed.
5.
Navigate to the section eTrust Directory Web Components, and click on the
Windows option.
6.
To install the web components now, click the select the option Install eTrust
Directory Web Components Now.
To create a response file that can be used to install eTrust Directory Web
Components silently on many computers, select the option Build response
file for unattended installation. For information about creating and using
response files, see the section Install Silently Using Response File.
7.
Continue to follow the instructions on the installation screens.
8.
Select options for the components you are installing.
9.
options, the Setup wizard displays a message telling you that it is ready to
install the selected files.
Use the Back button to review your selections before finalizing the installation.
D–8
Step 4. (Optional) Install the Samples and Technology Previews
eTrust Directory comes with sample directories, technology previews, and tools.
Install the Sample Directories
You can only set up the sample directories if you have installed the directory
components of eTrust Directory.
In a default installation of the directory components, these samples are installed
but not set up. You need to install each sample you want to work with.
The schema used by the Democorp sample has changed since eTrust Directory
3.6 SP2. You should reinstall the samples by running the setup script in the
Router, Democorp, and UNSPSC directories.
Important! If you run these scripts, any existing data in the Democorp and UNSPSC
databases will be lost.
To set up the sample directories:
1.
Log in as the DXserver administrator.
2.
Open Windows Explorer, and navigate to the %DXHOME%\samples\democorp
directory.
3.
Run setup.bat.
4.
Navigate to the %DXHOME%\samples\unspsc directory.
5.
Run setup.bat.
6.
Navigate to the %DXHOME%\samples\router directory.
7.
Run setup.bat.
Install the Sample Tools
eTrust Directory includes ten sample tools that you can use to work with your
DSAs.
You can only set up the sample tools if you have installed the directory
In a default installation of the directory components, these samples are installed
but not set up. You need to install each sample you want to work with.
■
To install each of these sample tools, run the scripts in the directories under
the directory %DXHOME%\samples.
For more information, see the chapter “Samples”, and the Readme in each of the
samples sub-directories.
D–9
Install the Technology Previews
You can only set up the technology previews if you have installed the web
In a default installation of the web components, these previews are installed but
not set up. You need to install each preview you want to work with.
These technology previews are not covered by your usual CA Support. However,
your feedback is very welcome. Please see the Readme files in each sample
directory for how to let us know about your comments or questions.
For more information, see the chapter “Samples”.
To install the Democorp version of JXweb:
1.
Navigate to \dxwebserver\samples\democorp.
2.
Run setup.bat.
To install the UDDI demonstration:
1.
Navigate to \dxwebserver\samples\uddi\uddiv3-demo .
2.
Run setup.bat.
To install the DSML server technology preview:
D–10
1.
Navigate to \dxwebserver\samples\dsml.
2.
Run setup.bat.
Install eTrust Directory Using Commands
You can install eTrust Directory and eTrust Directory Web Components using
the commands dxsetup and dxwebsetup.
The dxsetup Command
You can use the dxsetup command to install the main directory components.
dxsetup [-write_responses filepath/filename] [ADDLOCAL=value] [option-value]
where:
■
-write_responses creates a response file
■
the values and arguments are any of the following:
ADDLOCAL Value
Description
ALL
Installs all components
CA_LICENSE
Installs the CA license. Must be added with DXserver and Advantage Ingres
DXServer
Installs DXserver, must also use CA_LICENSE
ETRDocumentation
Installs the eTrust Directory documentation
IngresDBMS,IngresNet Installs Ingres 2.6 with the installation code ET
JXplorer
Installs JXplorer (requires JRE 1.4.2)
TeraTerm
Installs DXconsole, which traces DXserver
Option
Value
Description
ETRDIR_DXSERVER_SAMPLES
1
DXserver samples will be set up during installation.
ETRDIR_SHORTCUTS
1
All start menu shortcut are installed (default).
ETRDIR_SILENT_INSTALL
1
No prompts are displayed, and an installation log is
created in ..\%DXHOME%.
ETRDIRBASEPATH
path
The location for the whole installation.
ETRDIR_DOCO_DESTINATION
path
The eTrust Directory documentation location.
ETRDIR_DXSERVER_DESTINATION
path
The DXserver location.
ETRDIR_JXPLORER_DESTINATION
path
The JXplorer location.
ETRDIR_TERATERM_DESTINATION
path
The DXconsole location.
ETRDIR_BASIC_UI_INSTALL
1
A small progress bar appears during installation.
D–11
Option
Value
Description
INGRES_DESTINATION
path
The location for the whole Ingres installation.
INGRES_CKPDIR
path
The Ingres check point location.
INGRES_DATADIR
path
The Ingres data location.
INGRES_DMPDIR
path
The Ingres dump location.
INGRES_JNLDIR
path
The Ingres journal location.
INGRES_PRIMLOGDIR
path
The Ingres primary log file location.
INGRES_WORKDIR
path
The Ingres work location.
INGRES_LOGFILESIZE
size (MB) The size of the Ingres log file. Default: 64 MB.
The dxwebsetup Command
You can use the dxwebsetup command to install the web components of eTrust
Directory.
dxwebsetup [-write_responses filepath/filename] [ADDLOCAL=value] [option-value]
where:
■
-write_responses creates a response file
■
the values and arguments are any of the following:
ADDLOCAL Value
Description
ALL
Installs all components
DXmanager
Installs DXmanager, a DXserver management tool (requires DXwebserver)
DXwebservers
Installs the Tomcat web server (requires JRE 1.4.2).
JXweb
Installs JXweb (requires DXwebserver)
Uddi
Installs the UDDI Server (requires DXServer, IngresDBMS and DXwebserver)
UddiClient
Installs the UDDI Client (requires DXwebserver)
Option
Value
Description
ETRDIR_DXWEBSERVER_DESTINATION
path
The DXwebserver location.
ETRDIR_SILENT_INSTALL
1
No prompts are displayed, and an installation log
is created in ..\%DXHOME%.
ETRDIR_BASIC_UI_INSTALL
1
A small progress bar appears during installation.
D–12
Limit on Number of Characters in the Commands
The Windows command line may limit the number of characters in a single
command. This could be a problem if you want to set the installation
destinations for many eTrust Directory components.
To avoid using a very long command, use the ETRDIRBASEPATH argument to
set the location for the entire installation, instead of setting the location of each
component separately.
Example Commands
The following sections show some example commands.
Install All
Components Except
Samples
To install eTrust Directory with all components except the samples, run the
following command:
Install DXmanager
only
To install only DXmanager, you must also install DXwebserver. To install them
to to the default location, run the following command:
dxsetup ADDLOCAL=ALL ETRDIR_DXSERVER_SAMPLES=0
dxwebsetup ADDLOCAL=DXwebServers,DXmanager
Install DXserver,
Ingres, and CA
Licensing only
Install JXplorer only
To install DXserver, Advantage Ingres 2.6 [ET] and CA licensing to the default
location, run the following command:
dxsetup ADDLOCAL=DXServer,IngresDBMS,IngresNet,CA_LICENSE
ETRDIR_DXSERVER_SAMPLES=1
To install only JXplorer to the specified installation directory, run the following
command:
dxsetup ADDLOCAL=JXplorer ETRDIR_JXPLORER_DESTINATION=f:\Mynewdirectory\jxplorer
File Path that Includes
Spaces
If a file path includes spaces, surround the path with quotes. For example:
dxsetup ADDLOCAL=JXplorer ETRDIR_JXPLORER_DESTINATION=”f:\My directory\jxplorer”
D–13
Install eTrust Directory Silently
You can install eTrust Directory silently (or unattended). This means that no user
input is required during the installation process, and no feedback from the
installation process appears on the screen.
To install eTrust Directory silently, you need to provide the information that
would normally be supplied by the user during installation in one of the
following two ways:
■
As options with the dxsetup command
■
In a response file
If you plan to silently install JXplorer or any of the web components, Make sure
that the correct version of the Java Runtime Environment has been installed.
Install Silently Using Commands
To silently install the main directory components of eTrust Directory, use the
following command:
dxsetup ETRDIR_SILENT_INSTALL=1 [ADDLOCAL=values]
To silently install the web components of eTrust Directory, use the following
command:
dxwebsetup ETRDIR_SILENT_INSTALL=1 [ADDLOCAL=values]
See the section Install eTrust Directory Using Commands for descriptions of the
command options.
Example: Silently
Install Using the
dxsetup Command
To silently install eTrust Directory with all components except the samples, run
the following command from …\CD ROM drive\dxserver\windows:
Example: Silently
Install UDDI Server
Only
To silently install UDDI Server only, run the following command from …\CD
ROM drive\dxserver\windows:
D–14
dxsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=ALL ETRDIR_DXSERVER_SAMPLES=0
dxwebsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=Uddi,DXwebservers
Install Silently Using Response Files
The response file is a text file that supplies the arguments to be used during the
installation process. This input would usually be supplied by the user as they
install eTrust Directory or eTrust Directory Web Components.
A response file must contain data that you cannot create using a text editor. To
create a new response file, you must use the Product Explorer on the CD
Create a Response File
To create a response file, follow these steps:
1.
On a computer that does not have eTrust Directory installed on it, log in as a
user with administrator privileges.
2.
3.
To create a response file for the directory components, navigate to Directory
for Windows and click Install.
To create a response file for the web components, navigate to Web
Components for Windows and click Install.
4.
Select the option Build response file for unattended installation, then click Next.
5.
If you accept the terms of the license agreement, scroll to the bottom of the
license agreement, then click I Agree.
6.
In the Response File Installation Options page, set the following options:
-
The location of the response file.
-
The name of the response file. This file can have any extension.
-
The level of feedback to be given during installation.
The option Small progress bar makes a bar appear during installations
that are controlled by this response file.
The option No dialogs makes the installation truly silent.
6.
Continue the installation as you would for a direct installation.
7.
options, the Setup wizard displays a message that it is ready to create the
response file.
Use the Back button to review your selections before creating the response file.
D–15
Install Using Response Files
To use a response file to install the main directory components, use the following
command:
dxsetup -responsefile filepath\filename
To use a response file to install web components, use the following command:
dxwebsetup -responsefile filepath\filename
where:
D–16
■
-responsefile sets the installation to use a response file
■
filepath/filename is the path to the response file you created
Embed eTrust Directory in Another CA Product
eTrust Directory can be installed as an embedded product so that other CA
products can use its features in their product.
The information that the user would usually supply during the installation
process are supplied as options with the dxsetup command.
How Installation Codes Work
Only one product can use a particular installation code. They must also never
change this installation code. Each installation code is recorded, so as not to
affect any other instances of eTrust Directory. They must also use this installation
code to uninstall eTrust Directory.
This means that other CA products can install eTrust Directory using their own unique
installation code. Then, if eTrust Directory needs to be removed, the customer can
remove it without removing anything that the embedding product requires.
As with silent installation, you can put the embedded and installation code
commands on the one command line.
To find out which installation codes are supported, contact CA Support.
Install eTrust Directory as an Embedded Module
To install the main directory components as an embedded module, use the
following command:
dxsetup ETRDIR_DXSERVER_EMBEDDED=1 CALLER_ID=callerID [ADDLOCAL=values [arguments]
]
where:
■
■
ETRDIR_DXSERVER_EMBEDDED=1 specifies that this is an embedded
installation
CALLER_ID callerID uniquely identifies the embedding customer.
To install the web components as an embedded module, use the following
command:
dxwebsetup ETRDIR_DXWEBSERVER_EMBEDDED=1 CALLER_ID=callerID [ADDLOCAL=values
[arguments] ]
where:
■
■
ETRDIR_DXSERVER_EMBEDDED=1 specifies that this is an embedded
installation
CALLER_ID callerID uniquely identifies the embedding customer.
D–17
Uninstall eTrust Directory After an Embedded Installation
The installation code must be used to uninstall eTrust Directory.
The uninstallation process determines if no more products require eTrust
Directory and remove the product accordingly. If other products are using eTrust
Directory then the uninstall will remove only the reference counter for that caller,
and not the eTrust Directory components used by the other callers.
Example: Install and
Uninstall the Directory
Components within
eTrust Web Access
Control
The following command installs embedded eTrust Directory silently as part of
the product eTrust Web Access Control:
dxsetup ADDLOCAL=ALL ETRDIR_DXSERVER_EMBEDDED=1 ETRDIR_SILENT_INSTALL=1
CALLER_ID=ETWAC
To silently uninstall embedded eTrust Directory as ETWAC:
dxsetup REMOVE=ALL ETRDIR_DXSERVER_EMBEDDED=1 ETRDIR_SILENT_INSTALL=1
CALLER_ID=ETWAC
D–18
Troubleshooting
Troubleshooting
Error 267 or Error 1606
Reason:
These errors occur when there are some inconsistencies with the Windows
Installer DLL.
This usually occurs because a reboot was not performed when Windows Installer
was upgraded. This problem can also occur when you are upgrading from eTrust
Directory 3.6.
Action:
To prevent this problem from occurring or to fix this error if it has already
happened, use the eTrust Directory Cleanup tool, which is located under
Unsupported on the eTrust Directory installation CD. To run this tool, use the
following command:
CleanReg.exe -fixup267
Error 1605 Could not retrieve Version String
Reason:
This error appears when the registry has rogue entries under the Windows
Installer areas. These are usually from an aborted uninstall, or a failed uninstall.
Action:
Use the eTrust Directory Cleanup tool, which is located under Unsupported on
the eTrust Directory installation CD. To run this tool, use this command:
CleanReg.exe -all
Error 1639 Invalid Command Line Argument
Reason:
This error can occur when you install eTrust Directory using commands.
Action:
If you receive this error, check the following:
■
All arguments must be in the form of =. i.e ETRDIR_SILENT_INSTALL=1
■
All characters A-Z from the PROPERTY must be uppercase.
■
All paths specified in the VALUE must have quotes if they contain spaces.
For example, FOLDER="c:\Program Files\CA"
D–19
Troubleshooting
Can’t Connect to eTrust Directory from Remote Computer (Windows XP SP2)
After you install Windows XP SP2, you may not be able to connect to eTrust
Directory from another computer.
Reason:
This is because the firewall is on by default. If you disable the firewall then you
do not need to configure anything (all ports are open).
Action:
If the Windows XP firewall is on, follow these steps to enable a program by using
this firewall:
1.
Open Control Panel.
2.
Click Windows Firewall.
3.
In the Windows Firewall dialog box, click the Exceptions tab, and then click
Add Program.
4.
In the Add a Program dialog box, click Browse to locate dxserver.exe. (This
will open all the ports that eTrust Directory uses)
5.
After you select the program, click OK.
6.
On the Exceptions tab, make sure that the checkbox next to dxserver.exe is
selected, and then click OK.
If you later decide that you do not want the program to be an exception, clear
this check box.
If you cannot identify the ports that are used by the program, you can open a
port manually. To manually open a port, follow these steps:
1.
Open Control Panel
2.
Click Windows Firewall.
3.
On the Exceptions tab, click Add Port.
4.
In the Add a Port dialog box, type the number of the port that you want to
open in the Port Number box. For example, type 2123 for DXadmind, and
then click TCP.
5.
Type a name for the port, and then click OK. For example, type DXadmind.
6.
On the Exceptions tab, notice that the new service is listed. To enable the
port, click to select the check box next to the service, and then click OK
To only allow connections to a specific DSA and block all the DSAs on the
computer:
D–20
1.
Do not add dxserver.exe to the exception list.
2.
Add the port number for that specific DSA. For example, add port number
19389 for access to the Democorp DSA only.
Troubleshooting
D–21
Appendix
E
Installing eTrust Directory for UNIX
This appendix explains how to install eTrust Directory for UNIX and Linux
systems.
E–1
The eTrust Directory setup programs automate the installation processes. These
programs check which eTrust Directory components are installed and up-todate, and either install or upgrade those components that are missing or old.
To install eTrust Directory, perform the following activities:
1.
Check the system and disk requirements.
2.
Install or upgrade the directory components of eTrust Directory.
3.
(Optional) Install or upgrade the web components of eTrust Directory.
4.
(Optional) Run the sample scripts to install the three sample directories, the
technology previews, and the sample tools.
eTrust Directory Components
The eTrust Directory installation is split into the following two sections, which
you can install separately or on the same computer:
■
■
E–2
The dxsetup program—The main eTrust Directory installation, which
includes the following modules:
-
DXserver—The eTrust Directory server, DXtools, and DXconsole
-
Ingres—A CA open-source database, which is required by DXserver if
the data repository is used
-
JXplorer—An LDAP client that lets you browse and update a directory
-
Documentation—PDF product manuals
-
Samples—Sample DSAs and sample tools for working with DXserver
The dxwebsetup program—Web-based modules, which can be installed on
a different computer to the main directory installation. This includes the
following modules:
-
DXmanager—A web-based tool for monitoring and administration
-
JXweb—A web-based LDAP client that lets you browse a directory
-
UDDI Server—A UDDI repository that functions as a business directory.
-
UDDI Client—A web-based browser for the UDDI Server
-
Samples—Sample web applications, including a DSML server, a SAML
server, and a UDDI demonstration.
Default Installation Locations
This table lists the locations into which the eTrust Directory components are
installed in a default installation.
Component
Default Directory
DXserver
/opt/CA/eTrustDirectory/dxserver
Advantage Ingres
/opt/CA/AdvantageIngresET/ingres
JXplorer
/opt/CA/eTrustDirectory/jxplorer
DXwebserver
/opt/CA/eTrustDirectory/dxwebserver
JRE
/opt/CA/eTrustDirectory/jre
Documentation
/opt/CA/eTrustDirectory/documentation
Sample Directories and /opt/CA/eTrustDirectory/dxserver/samples
Sample Tools
Sample Web
Applications
/opt/CA/eTrustDirectory/dxwebserver/samples
The $DXHOME Location
Throughout this guide, $DXHOME refers to the location in which DXserver is
installed on your computer. This location is set in the $DXHOME environment
variable.
For example, in a default installation, $DXHOME is
/opt/CA/eTrustDirectory/dxserver.
Installation Logging
All installations are logged.
If DXHOME is defined, the installation log file is created in $DXHOME/.. . If
DXHOME is not defined, the installation log is created in /tmp.
E–3
Upgrade eTrust Directory
If you have the enterprise version of eTrust Directory, you can upgrade this by
following the installation instructions in this chapter.
If you are using a version of eTrust Directory that is embedded in another
product, you must use the upgrade package from the embedding product.
Each embedding product that installs eTrust Directory has a specific process for
upgrading eTrust Directory and if this is not followed, the products will not
work as intended.
For example, if you use eTrust SSO and the embedded version of eTrust
Directory that comes with it, you must use an eTrust SSO package to upgrade
both products.
Upgrade Advantage Ingres
For a new installation, eTrust Directory embeds the single-byte version of
Advantage Ingres II 2.6 SP2, with the installation code ET. The Advantage Ingres
RDBMS installation performs a standard tuning of the database parameters. You
can customize these parameters.
For an upgrade to an existing configuration, check the Readme to find out how
eTrust Directory works with the various versions of Advantage Ingres.
If you are currently running Advantage Ingres 2.0 or 2.5, check with Computer
Associates’ Technical Support to find out whether the applications that use your
existing version of Advantage Ingres also support Advantage Ingres 2.6.
You may want to set the Advantage Ingres log folder to a different disk drive for
improved performance.
If you plan to have many data DSAs running on the same computer, read the
section Increasing the Number of Database Connections in the appendix
“Tailoring the RDBMS”.
E–4
User Accounts
eTrust Directory requires two user accounts to be set up:
■
dsa—An eTrust Directory administrator
■
ingres—An Ingres administrator
You can create these accounts manually before you install eTrust Directory, or
you can let the installation program create them.
If these accounts do not exist, the installation program will create them.
■
■
During a normal interactive installation, you will be prompted to create
passwords for these accounts.
After a silent installation, the accounts will be created without passwords.
You must manually assign passwords after the installation is complete.
E–5
Install eTrust Directory Using the Installation Program
This section describes how to install eTrust Directory using the installation
programs dxsetup and dxwebsetup.
Step 1. Check System and Disk Requirements
This section lists the checks you should make before you start installing eTrust
Directory.
Check System Requirements
Check the Readme for system requirements.
The disk space required for directory information is approximately 20 times the
raw data size. This provides space for backups, journals, indexing, tuning,
import, and preprocessing.
Back Up Data
If you are upgrading from an earlier version of eTrust Directory, make sure you
have adequate backups, including any changes to your schema files.
Verify CD-ROM Accessibility
Check that the CD-ROM is available.
You can install eTrust Directory and Advantage Ingres from either a local CDROM drive, or a remote CD-ROM drive on the same network.
Set Up User Permissions
If you are installing eTrust Directory from a local disk, you must ensure that the
parent directories have read and execute permissions for all users. This gives
newly added users (including dsa and ingres, which are created during the eTrust
Directory installation) permissions to access the tar files.
Note: You should never run DXserver as root.
E–6
Check the Kernel Settings (Solaris and HP only)
Check the kernel settings and, if required, modify them. This is not required on
computers running Linux or AIX.
Check the Kernel Settings on Solaris
eTrust Directory on Solaris requires the following kernel settings:
Kernel Setting
Value
Description
seminfo_semmap
1
Max number of semaphore map entries
seminfo_semmni
100
Number of semaphore identifiers
seminfo_semmns
1000
Max number of semaphores
seminfo_semmnu
30
Number of semaphore undo structures
seminfo_semms1
50
seminfo_semopm
10
Max number of operations
seminfo_semume
10
Semaphore undo entries per process
seminfo_semusz
96
Size of undo structures
seminfo_semvmx
32767
Semaphore maximum value
seminfo_semaem
16384
Max value adjust on exit
shminfo_shmmax
100000000 Max shared mem segment
shminfo_shmmin
1
Min shared memory segment
shminfo_shmmni
100
Number of shared memory identifiers
shminfo_shmseg
10
Shared memory segments per process
To check that the …/etc/system file has the required settings, use the following
command:
./dxsetup.sh –check_kernel
This command returns the value 1 if kernel changes are required, and 0 if no
changes are required.
To update the kernel settings, use the following command:
./dxsetup.sh -reboot_kernel y|n
where:
■
y reboots the computer after the kernel parameters are modified
■
n leaves the computer running after the kernel parameters are modified
E–7
Check the Kernel Settings on HP
eTrust Directory on HP requires the following kernel settings:
Kernel Setting
Value
Description
sema
1
Enable sys V semaphores
semmap
1
Max number of semaphore map entries
semmni
100
Number of semaphore identifiers
semmns
1000
Max number of semaphores
semmmnu
30
Number of semaphore undo structures
semume
10
Semaphore undo entries per process
semvmx
32767
Semaphore maximum value
semaem
16384
Max value adjust on exit
shmem
1
Enable sys V shared memory
shmmax
100000000 Max shared mem segment
schmmni
100
Number of shared memory identifiers
schmseg
10
Shared memory segments per process
To update the kernel, use SAM:
E–8
1.
Run SAM as root.
2.
Set each parameter to the larger of the current or suggested values.
3.
Rebuild the kernel.
4.
Restart the computer.
Design the Disk Configuration
To improve recovery and performance, you should store the database
information on a separate physical disk from the Advantage Ingres installation.
In the following example of the layout of a typical installation, the /local
partition is on a separate physical disk:
/opt/CA
DXserver product files
Advantage Ingres product files
Advantage Ingres transaction log
/local/CA
Directory information (database files)
Advantage Ingres checkpoints (database backups)
Advantage Ingres journals
Advantage Ingres work area
For information about disk configurations such as mirrored disks and RAID,
contact Computer Associates Technical Support at http://supportconnect.ca.com.
E–9
Step 2. Install eTrust Directory
The two eTrust Directory installation programs, dxsetup and dxwebsetup, are
located on the eTrust Directory CD-ROM.
These programs will ask a series of questions as the installation proceeds. In
general, you should use the defaults.
Step 2a. Run dxsetup
1.
Log in as root.
2.
If there is an existing Advantage Ingres installation on the system, stop
Advantage Ingres.
3.
Run the dxsetup installation program in one of the following ways:
-
Run dxsetup from the CD or from the location to which you copied the
CD contents. For example:
cd /dxserver/unix/install
./dxsetup.sh
-
Run dxsetup and include a parameter that specifies the location of the
installation files. For example:
./dxsetup.sh –r /dxserver/unix/install
4.
The Welcome dialog appears. It asks if you want to perform an express or
custom setup.
If you choose express setup, dxsetup installs eTrust Directory automatically,
with the default values shown in the table in the section Default Installation
Locations.
If you choose custom setup, dxsetup asks you for information during the
installation process.
E–10
Step 2b. Configure the System Kernel
The dxsetup program checks the kernel configuration. This check ensures that
the settings in the …/etc/system file are at least as good as the settings listed in
the section Check the Kernel Settings.
This is done differently for the different platforms.
Solaris
The kernel is updated as part of the installation process:L
■
If the settings in the …/etc/system file are already correct, no action is taken.
■
If any of the settings do not exist, they are created.
■
If any of the settings already exist, their values are increased if necessary.
■
If any of these values are changed, the dxsetup program asks if you want to
restart the system. If you select n, dxsetup will exit.
See the section Check the Kernel Settings (Solaris and HP only) for how to check
the kernel settings manually.
HP-UX
Make sure that the kernel is already updated. See the section Check the Kernel
Settings (Solaris and HP only) for instructions.
Linux
Not applicable.
AIX
The kernel is updated automatically. No action is required.
Step 2c. Accept the License Agreement
Before the installation begins, you must view and agree to the license
agreements.
1.
The license agreement appears.
2.
When you have finished viewing the license, the dxsetup program asks:
Do you agree to the above license? (y/n) [ ]
-
If you select n, the installation process stops.
-
If you select y, the installation process continues.
-
If you select the default (blank), the question is repeated until you select
either y or n.
E–11
Step 2d. Set Up DXserver
1.
The dxsetup program asks if you want to install the DXserver software:
Do you want to install the DXserver software? (y/n/i/q) [y]
2.
If you select n, dxsetup quits.
If you select y, and dxsetup finds an existing DXserver installation, it asks if
you want to perform an upgrade. If you select y, the existing eTrust
Directory installation is backed up.
If you select y, and you are installing eTrust Directory for the first time, you
are prompted for the shell and password for the dsa user.
Enter the login shell for the dsa account [/bin/csh]
The dsa account requires a password
New password:
4.
The dxsetup program requests an installation directory for DXserver:
Please specify the DXserver installation directory
[/opt/CA/eTrustDirectory/dxserver]
Press Enter to accept the default directory, or enter the full pathname for a
different directory.
6.
The following confirmation message appears:
The directory /opt/CA/eTrustDirectory/dxserver will be created.
Do you wish to change the directory? (y/n) [n]
7.
Enter n to accept the directory.
Step 2e. Set Up the Documentation
1.
The dxsetup program asks if you want to install the documentation:
Do you want to install the eTrust Directory documentation? (y/n/i/q) [y]
2.
The dxsetup program then requests an installation directory for the
documentation:
Please specify the Documentation installation directory
[/opt/CA/eTrustDirectory/documentation]
Press Enter to accept the default directory, or enter the full pathname for a
different directory.
3.
The following confirmation message appears:
The directory /opt/CA/eTrustDirectory/documentation will be created.
4.
E–12
Step 2f. Set Up Advantage Ingres
1.
The dxsetup program asks if you want to install the Advantage Ingres
software:
Do you want to install the Advantage Ingres software (y/n/i/q) [y]
2.
If you select y, and you are installing Advantage Ingres for the first time, you
are prompted for the shell and password for the Advantage Ingres user.
Enter the login shell for the ingres account [/bin/csh]
The ingres account requires a password
New password:
If you select n, dxsetup bypasses the Advantage Ingres installation section.
Ensure that you have adequate backups before performing an upgrade.
3.
The dxsetup program requests an installation directory for the Advantage
Ingres software:
Please specify the Advantage Ingres installation directory
[/opt/CA/AdvantageIngresET/ingres]
4.
Press Enter to specify the default directory
(/opt/CA/AdvantageIngresET/ingres), or provide the full pathname for an
alternate directory.
5.
When you press Enter, the confirmation message will appear.
The directory /opt/CA/AdvantageIngresET/ingres will be created.
6.
The installation program asks you if you want to specify separate locations
for data, work, checkpoint, dumps, and journals.
If you select Yes, you are asked to specify a separate location for each
component.
If you select No, the installation program asks you to specify the location of
the Advantage Ingres database directory:
Please specify the Advantage Ingres database directory
[/local/CA/AdvantageIngresET]
7.
Press Enter to accept the default directory (/local/CA/AdvantageIngresET),
or provide the full pathname for an alternate directory.
The directory /local/CA/AdvantageIngresET will be created.
8.
An ingres directory is added automatically to the path of the database
directory you select. For example, if you select /local2/IngresET, the
Advantage Ingres database directory is /local2/IngresET/ingres.
E–13
9.
You will then be prompted with a list of the time zones in that region.
This setting must be assigned one of the following values:
AFRICA
ASIA
AUSTRALIA
MIDDLE-EAST
NORTH-AMERICA
NORTH-ATLANTIC
SOUTH-AMERICA
SOUTH-PACIFIC
SOUTH-ASIA
GMT-OFFSET
Please enter one of the named regions:
10. You will then be asked to select from one of the time zones in the region.
11. When you enter one of the values, a confirmation message will appear.
The Time Zone you have selected is: timezone
Is this Time Zone correct? (y/n) [y]
Enter y to confirm your choice.
If dxsetup cannot upgrade a database, you will need to do this manually, using
the DXupgradedb tool.
To check for problems upgrading a database, look in the Ingres installation log files.
By default, these files are in the folder /opt/CA/AdvantageIngresET/ingres/files.
Step 2g. Set up DXadmind
1.
The dxsetup program asks for the details of DXadmind trusted hosts.
Please enter the Hostnames/IP Addresses of DXadmind Trusted Hosts.
Step 2h. Set Up JXplorer
1.
The dxsetup program asks if you want to install JXplorer:
Do you want to install the JXplorer browser software? (y/n/i/q) [y]
2.
The dxsetup program requests an installation directory for JXplorer:
Please specify the JXplorer installation directory
[/opt/CA/eTrustDirectory/jxplorer]
3.
Press Enter to choose the default directory, or provide the full pathname for
an alternate directory.
The directory /opt/CA/eTrustDirectory/jxplorer will be created.
Do you want to change the directory ? (y/n) [n]
4.
The dxsetup program installs the JXplorer files into the selected directory.
E–14
Step 2i. Set Up Java Runtime Environment (JRE)
If you chose to install JXplorer, dxsetup checks to see if the Java Runtime
Environment (JRE) is already installed.
If JRE is installed:
■
If the installed version is up-to-date, dxsetup skips to the next section:
The existing java version 1.4.2_04 is newer/identical to the version supplied
with this package. JRE will not be upgraded.
■
If the installed version is not up-to-date, dxsetup upgrades JRE.
If JRE is not installed, the dxsetup program installs it:
1.
The dxsetup program requests an installation directory for the JRE:
Please specify the JRE installation directory. [/opt/CA/eTrustDirectory/jre]
2.
Press Enter to choose the default directory, or enter a different directory.
The directory [/opt/CA/eTrustDirectory/jre will be created.
Do you want to change the directory? (y/n) [n]
3.
Step 2j. Set Up the Sample Directories
1.
If you have installed Advantage Ingres, the dxsetup program asks if you
want to install the sample directories Democorp, UNSPSC, and Router:
Do you wish to start the sample directories (y/n) [y]
2.
If you select y, the samples will be installed and set up.
If you select n, the sample files will be installed, but they will not be set up.
Note: If you do not install Advantage Ingres, you cannot run the sample
scripts, and the system displays an error message.
The installation program installs eTrust Directory, using the settings you entered.
E–15
Step 3: (Optional) Install the Web Components
Step 3a. Run dxwebsetup
1.
The dxwebsetup program asks if you want to install DXwebserver:
Do you want to install the DXwebserver software? (y/n/i/q) [y]
2.
The dxwebsetup program requests an installation directory for
DXwebserver:
Please specify the DXwebserver installation directory
[/opt/CA/eTrustDirectory/dxwebserver]
3.
The directory /opt/CA/eTrustDirectory/dxwebserver will be created.
Do you want to change the directory ? (y/n) [n]
4.
Step 3b. Accept the License Agreement
Before the installation begins, you must view and agree to the license agreement.
1.
2.
The license agreement appears.
When you have finished viewing the license, the dxsetup program asks:
Do you agree to the above license? (y/n) [ ]
-
If you select n, the installation process stops.
-
If you select y, the installation process continues.
-
If you select the default (blank), the question is repeated until you select
either y or n.
Step 3c. Set Up Java Runtime Environment (JRE)
If the Java Runtime Environment (JRE) is already installed, the dxwebsetup
program checks the version:
■
If the installed version is up-to-date, dxwebsetup skips to the next section:
The existing java version 1.4.2_04 is newer/identical to the version supplied
with this package. JRE will not be upgraded.
■
If the installed version is not up-to-date, dxwebsetup upgrades JRE.
If JRE is not installed, the dxwebsetup program installs it:
1.
The dxwebsetup program requests an installation directory for the JRE:
Please specify the JRE installation directory. [/opt/CA/eTrustDirectory/jre]
2.
The directory [/opt/CA/eTrustDirectory/jre will be created.
Do you want to change the directory? (y/n) [n]
3.
The installation program installs the web components using the settings you entered.
E–16
Step 4: (Optional) Install the Technology Previews and Sample Tools
This section describes how to set up the extras that come with eTrust Directory.
Install the Sample Directories
If you installed the samples but did not set them up, you can do this manually.
You need to install each sample you want to work with.
The schema used by the Democorp sample has changed since eTrust Directory
3.6 SP2. You should reinstall the samples by running the setup script in the
Router, Democorp, and UNSPSC directories.
Important! If you run these scripts, any existing data in the Democorp and UNSPSC
databases will be lost.
To set up the sample directories:
1.
Navigate to $DXHOME/samples/democorp.
2.
Run setup.sh.
3.
Navigate to $DXHOME/samples/unspsc.
4.
Run setup.bat.
5.
Navigate to $DXHOME/samples/router.
6.
Run setup.bat.
Install the Sample Tools
eTrust Directory includes sample tools that you can use to work with your DSAs.
In an express installation, these samples are installed but not set up. You need to
install each sample you want to work with.
■
To install each of these sample tools, run the scripts in the directories under
the directory $DXHOME/samples.
For more information, see the chapter “Samples”.
E–17
Install the Technology Previews
eTrust Directory comes with three technology previews that are examples of how
you can extend eTrust Directory, or are previews of upcoming features. For more
information, see the chapter “Samples”.
To install the Democorp version of JXweb:
1.
Navigate to dxwebserver/samples/democorp.
2.
Run setup.sh.
To install the UDDI demonstration:
1.
Navigate to dxwebserver/samples/uddi/uddiv3-demo.
2.
Run setup.sh.
To install the DSML server technology preview:
E–18
1.
Navigate to dxwebserver/samples/dsml.
2.
Run setup.sh.
You can install eTrust Directory and the eTrust Directory web components using
the commands dxsetup and dxwebsetup.
The dxsetup Command
You can use the dxsetup command to install the main directory components:
./dxsetup.sh [options]
where the options are any of the following, in any order:
Option
Action
-nojxplorer
Install eTrust Directory without installing JXplorer
-nodocs
Install eTrust Directory without installing the user documentation
-noingres
Install eTrust Directory without installing Advantage Ingres. Only use this
option if DXserver will act as a router or a relay DSA. The DXserver directory
samples will not run, as these require a database.
-nosamples
Install eTrust Directory without installing the sample DSAs
-r source_directory
Run dxsetup from a remote location
-dxuser username
Allows a username other than the 'dsa' default
-silent
Installs eTrust Directory silently. This is ideantical to the -default option, which is
still valid.
-embedded
Installs eTrust Directory as a component embedded in another product
-caller_id caller_id
The installation code of the embedding product.
-list_callers
List all embedded installations of eTrust Directory. This does not install eTrust
Directory.
-write_responses
/filepath/filename
Create a response file that can be used to install eTrust Directory silently.
This does not install eTrust Directory.
-responsefile
/filepath/filename
Install eTrust Directory using the options listed in the response file.
-check_kernel
(Solaris only) Checks if the kernel needs to be updated: returns 1 if kernel
changes are required, and returns 0 if no changes are required.
-reboot_kernel y|n
(Solaris only) Modifies kernel parameters to allow installation, and then either
reboots the computer or leaves it running. If you enter y, the computer reboots
after the kernel parameters are modified. If you enter n, the computer is left
running. This does not install eTrust Directory.
E–19
The dxwebsetup Command
Use the dxwebsetup command to install the web components of eTrust Directory:
./dxwebsetup.sh [options]
where the options are any of the following, in any order:
Option
Action
-r source_directory
Run dxwebsetup from a remote location
-silent
Installs the web components silently (no prompts are given to the user).
-embedded
Install eTrust Directory as a component embedded in another product
-caller_id caller_id
The installation code of the embedding product.
E–20
You can install eTrust Directory silently (or unattended). This means that you
need to provide the information that would normally be supplied by the user
during installation in one of the following two ways:
■
In the command used to launch the installation
■
In a response file
Install Using Commands
During a silent installation, feedback is still printed to the screen. To suppress
this feedback, send the output to /dev/null:
./dxsetup.sh -silent >/dev/null
Install the Main eTrust Directory Components
1.
Change to the /dxserver/unix/install directory.
2.
Run the following command:
./dxsetup.sh -silent [options]
where options are the options listed in the table in the section The dxsetup
Command
3.
If the users dsa and ingres did not exist before, this installation created them
without passwords.
Run the passwd utility to assign passwords to the dsa and ingres users.
Example: Silently
Install DXserver Using
a COmmand
The following command installs only DXserver and DXtools, in the default
locations (the samples are not installed because Ingres is not installed):
./dxsetup.sh –silent –nojxplorer –nodxwebserver –nodocs –noingres
Install the eTrust Directory Web Components
1.
Change to the /dxserver/unix/install directory.
2.
Run the following command:
./dxwebsetup.sh> -silent [options]
where options are the options listed in the table in the section The dxsetup
Command
3.
If the user dsa did not exist before, this installation created it without a
password.
Run the passwd utility to assign a password to the dsa user.
E–21
Install Using Response Files
A response file is a text file that supplies the arguments to be used during the
installation process. This input would usually be supplied by the user as they
install eTrust Directory.
When you create a response file, the license agreement appears, and if you agree
to the terms, a response file is created, using the options that you specify.
The eTrust Directory installation CD includes response filea that install the
components to the default locations shown in the table in the section Default
Installation Locations. You can edit these response files, or you can generate new
ones.
If you run an installation from a response file that has errors or omissions, error
messages are written to the screen, and the installation quits.
Install the Main eTrust Directory Components
To use a response file to install the main directory components, use the following
command:
./dxsetup.sh -responsefile /filepath/filename
where filepath/filename is the path to the response file
Install the eTrust Directory Web Components
To use a response file to install web components, use the following command:
./dxwebsetup -responsefile /filepath\filename
where filepath/filename is the path to the response file
Edit a Response File
The installation CD includes one response file for each of the two installation
modules:
■
The dxsetup response file: /dxserver/responsefile.txt
■
The dxwebsetup response file: /dxwebserver/responsefile.txt
To edit a response file:
E–22
1.
Copy the response file from the CD onto a computer.
2.
Edit the response file using a text editor.
Create a New Response File for the Main eTrust Directory Components
The default location for the response file is /tmp/etrdir8.rsp.
1.
To create a response file for the main directory components:
./dxsetup.sh -write_responses [/filepath/filename] [options]
where:
2.
-
/filepath/filename is the path to the new response file
-
options are the installation options listed in the section The dxsetup
Command
The installation program asks you for information as in a normal installation.
Create a New Response File for the Main eTrust Directory Components
The default location for the response file is /tmp/etrdir8.rsp.
1.
To create a response file for the web components:
./dxwebsetup.sh -write_responses [/filepath/filename] [options]
where:
2.
-
/filepath/filename is the path to the new response file
-
options are the installation options listed in the section The dxsetup
Command
The installation program asks you for information as in a normal installation.
E–23
eTrust Directory can be installed as an embedded product so that other CA
products can use its features in their product.
The information that the user would usually supply during the installation
process is supplied as options with the installation commands.
How Installation Codes Work
Only one product can use a particular installation code. Each product will always
use the same installation code. Each installation code is recorded, so as not to
affect any other instances of eTrust Directory. They must also use this installation
code to uninstall eTrust Directory.
This means that other CA products can install eTrust Directory using their own
unique installation code. Then, if eTrust Directory needs to be removed, the
customer can remove it without removing anything that the embedding CA
product requires.
All install commands can be used with the embedded and installation code
commands on the one command line.
To find out which installation codes are supported, contact CA Support.
Install the Main eTrust Directory Components as an Embedded Module
To install the main directory components as an embedded module, use the
following command:
./dxsetup.sh –embedded
-caller_id unique_id
where -caller_id unique_id uniquely identifies the embedding customer.
Install the Web Components as an Embedded Module
To install the web components as an embedded module, use the following
command:
./dxwebsetup.sh –embedded
-caller_id unique_id
where -caller_id unique_id uniquely identifies the embedding customer.
E–24
Uninstall eTrust Directory after an Embedded Installation
The installation code must be used to uninstall an embedded version of eTrust
Directory.
The uninstallation process determines if no more products require eTrust
Directory and remove the product accordingly. If other products are using eTrust
Directory then the uninstall will remove only the reference counter for that caller,
and not the eTrust Directory components used by the other callers.
Example: Installing
and Uninstalling eTrust
Directory within eTrust
Web Access Control
The following command installs eTrust Directory silently with the installation
code ETWAC, which signifies that it is embedded within eTrust Web Access
Control:
./dxsetup.sh -default -embedded –caller_id ETWAC
To uninstall eTrust Directory that was installed with the installation code
ETWAC:
./dxuninst.sh -embedded –caller_id ETWAC
E–25
Troubleshooting
Troubleshooting
This section describes how to deal with problems that might occur during or
after installing or upgrading eTrust Directory.
Diagnosing Startup Problems with eTrust Directory or Ingres
On Solaris, eTrust Directory is started and stopped at system boot and shutdown
via the /etc/init.d/dxserver script. This starts and stops Ingres, SSL daemons,
the DXadmin daemon, and any DXserver processes marked for autostart.
This file writes a log called dxserver-rc.log usually in the DXserver logs
directory, $DXHOME/logs (if DXHOME is not defined for some reason then
look for this file in the /tmp directory). This log shows each of the processes
being started or stopped.
Prior to eTrust Directory 3.6, this file was called rc.log in the DXserver logs
directory. There should always be a dxserver-rc.log file in /tmp.
DXadmind Times Out after Upgrading
Reason:
This problem occurs because DXadmind is already started.
In a standard upgrade for DXserver, DXadmind is stopped and restarted once
the upgrade is complete. However if the installation for DXserver is cancelled
part-way, DXadmind may not have stopped and then when it tries to re-start, it
times out.
Action:
To check the status of DXadmind, type the following command:
dxadmind status
To fix the problem, run the following commands:
1.
Log in a the user DXserver Administrator (the default user is DSA).
2.
Stop DXadmind:
dxadmind stop all
3.
Re-start DXadmind:
dxadmind start all
E–26
Troubleshooting
If DXadmind times out again, do the following steps:
1.
Type the following command:
ps -ef | grep dxadmind
The response includes a line similar to the following:
dsa 6204 1 0 21:23:34 ? 0:00 dxadmind start
2.
In the sample above, the number 6204 is the process number. You have to kill
that process by typing kill process number
Important! Ensure this number is typed correctly!
3.
Re-start DXadmind by typing the following command:
dxadmind start all
Note: To run the kill command, you can be logged in as root or dsa. However,
you need to be logged in as dsa to run the command dxadmind start.
E–27
Appendix
F
Licenses for Third-Party Products
eTrust Directory uses some third-party code. This appendix includes the license
agreements for that code.
See the Release Notes for a list of the components and version numbers.
Apache
This product includes software developed by the Apache Software Foundation
(http://www.apache.org/). The Apache software is distributed in accordance
with the following license agreement.
The Apache Software License, Version 1.1
Apache Ant 1.5.3
Copyright (C) 2000-2003 The Apache Software Foundation. All rights reserved.
Apache Axis 1.1
Copyright (c) 2002 The Apache Software Foundation. All rights reserved.
Apache Cactus 1.5
Copyright (c) 2001-2003 The Apache Software Foundation. All rights reserved.
Apache Jakarta-Oro 2.0
Apache Log4j 1.2.8
Apache Tomcat 4.1.29
Copyright (c) 1999, 2000 The Apache Software Foundation. All rights reserved.
Apache Xalan C++ 1.6
Apache Xalan Java 2.5.2
F–1
Apache
Apache Xerces C++ 2.3
Apache Xerces Java 2.6
Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must
include the following acknowledgment: "This product includes software
developed by the Apache Software Foundation (http://www.apache.org/)."
Alternately, this acknowledgment may appear in the software itself, if and
wherever such third-party acknowledgments normally appear.
4. The names "Ant", "Axis", "Cactus", "The Jakarta Project", "Jakarta-Oro", "log4j",
"Tomcat", "Xalan", "Xerces", "Apache" and "Apache Software Foundation" must
not be used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact
apache@apache.org.
5. Products derived from this software may not be called "Apache" or "JakartaOro", nor may "Apache" or "Jakarta-Oro" appear in their name, without prior
written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED "AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE
SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
F–2
Morten’s JavaScript Tree Menu v2.3.2
Apache Ant, Axis, Cactus, Jakarta-Oro, Log4J and Tomcat consist of voluntary
contributions made by many individuals on behalf of the Apache Software
Foundation. For more information on the Apache Software Foundation, please
see <http://www.apache.org/>.
Portions of Apache Jakarta-Oro are based upon software originally written by
Daniel F. Savarese. We appreciate his contributions.
Apache Xalan C++ and Xalan Java consist of voluntary contributions made by
many individuals on behalf of the Apache Software Foundation and were
originally based on software copyright (c) 1999, Lotus Development Corporation,
http://www.lotus.com. For more information on the Apache Software
Foundation, please see <http://www.apache.org/>.
Apache Xerces C++ and Xerces Java consist of voluntary contributions made by
many individuals on behalf of the Apache Software Foundation and were
originally based on software copyright (c) 1999, International Business Machines,
Inc., http://www.ibm.com. For more information on the Apache Software
Foundation, please see <http://wwww.apache.org/>.
Morten’s JavaScript Tree Menu v2.3.2
This product includes software developed by Morten Wang & contributors. The
software is distributed in accordance with the following copyright and
permission notices.
Copyright (c) 2001-2002, Morten Wang & contributors All rights reserved.
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
* Neither the name "Morten's JavaScript Tree Menu" nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
F–3
OpenLDAP
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
OpenLDAP
Portions of this product include software developed by the OpenLDAP
Foundation. The OpenLDAP software is distributed in accordance with the
following license agreement.
The OpenLDAP Public License
Version 2.8, 17 August 2003
Redistribution and use of this software and associated documentation
("Software"), with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions in source form must retain copyright statements and notices,
2. Redistributions in binary form must reproduce applicable copyright
statements and notices, this list of conditions, and the following disclaimer in the
documentation and/or other materials provided with the distribution, and
3. Redistributions must contain a verbatim copy of this document.
The OpenLDAP Foundation may revise this license from time to time.
Each revision is distinguished by a version number. You may use this Software
under terms of this license revision or under the terms of any subsequent
revision of the license.
F–4
OpenLDAP
THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND
ITS CONTRIBUTORS `ÀS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENLDAP
FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) OR OWNER(S)
OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
The names of the authors and copyright holders must not be used in advertising
or otherwise to promote the sale, use or other dealing in this Software without
specific, written prior permission. Title to copyright in this Software shall at all
times remain with copyright holders.
OpenLDAP is a registered trademark of the OpenLDAP Foundation.
Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, California,
USA. All Rights Reserved. Permission to copy and distribute verbatim copies of
this document is granted.
The OpenLDAP Copyright Notice
Copyright 1998-2004 The OpenLDAP Foundation
All rights reserved.
are permitted only as authorized by the OpenLDAP Public License.
A copy of this license is available in the file LICENSE in the top-level directory of
the distribution or, alternatively, at
<http://www.OpenLDAP.org/license.html>.
OpenLDAP is a registered trademark of the OpenLDAP Foundation.
Individual files and/or contributed packages may be copyright by other parties
and subject to additional restrictions.
F–5
OpenSSL
This work is derived from the University of Michigan LDAP v3.3 distribution.
Information concerning this software is available at
<http://www.umich.edu/~dirsvcs/ldap/>.
This work also contains materials derived from public sources.
Additional information about OpenLDAP can be obtained at
<http://www.openldap.org/>.
Portions Copyright 1998-2004 Kurt D. Zeilenga.
Portions Copyright 1998-2004 Net Boolean Incorporated.
Portions Copyright 2001-2004 IBM Corporation.
are permitted only as authorized by the OpenLDAP Public License.
Portions Copyright 1999-2003 Howard Y.H. Chu.
Portions Copyright 1999-2003 Symas Corporation.
Portions Copyright 1998-2003 Hallvard B. Furuseth.
are permitted provided that this notice is preserved. The names of the copyright
holders may not be used to endorse or promote products derived from this
software without their specific prior written permission. This software is
provided `às is'' without express or implied warranty.
Portions Copyright (c) 1992-1996 Regents of the University of Michigan.
Redistribution and use in source and binary forms are permitted provided that
this notice is preserved and that due credit is given to the University of Michigan
at Ann Arbor. The name of the University may not be used to endorse or
promote products derived from this software without specific prior written
permission. This software is provided `às is'' without express or implied
warranty.
OpenSSL
Terms and Conditions for the Use of The OpenSSL Toolkit
F–6
OpenSSL
Licensee agrees that the following terms (in addition to the applicable provisions
above) shall apply with respect to any open source provided by The OpenSSL
Project and Eric Young contained within the Product. Notwithstanding anything
contained in the CA End User License Agreement, solely with respect to such
open source, these terms are not superseded by any written agreement between
CA and Licensee:
Copyright (c) 1998-2000 The OpenSSL Project. All rights reserved.
This product includes software developed by the OpenSSL Project for use in the
OpenSSL Toolkit (http://www.openssl.org/).
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ”AS IS” AND
ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
This product includes cryptographic software written by Eric Young
(eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com).
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved.
The following conditions apply to all code found in this distribution, be it the
RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation
included with this distribution is covered by the same copyright terms except
that the holder is Tim Hudson (tjh@cryptsoft.com).
This product includes software written by Tim Hudson (tjh@cryptsoft.com).
F–7
Sun Microsystems, Inc. Java Web Services Developer Pack
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ”AS IS” AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED
SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT")
CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY
OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO THE TERMS
OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE
ELECTRONICALLY, INDICATE YOUR ACCEPTANCE OF THESE TERMS BY
SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT.
IF YOU DO NOT AGREE TO ALL THESE TERMS, PROMPTLY RETURN THE
UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR,
IF THE SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE
"DECLINE" BUTTON AT THE END OF THIS AGREEMENT.
F–8
1.
LICENSE TO USE. Sun grants you a non-exclusive and non-transferable
license for the internal use only of the accompanying software and
documentation and any error corrections provided by Sun (collectively
"Software"), by the number of users and the class of computer hardware for
which the corresponding fee has been paid.
2.
RESTRICTIONS. Software is confidential and copyrighted. Title to Software
and all associated intellectual property rights is retained by Sun and/or its
licensors. Except as specifically authorized in any Supplemental License
Terms, you may not make copies of Software, other than a single copy of
Software for archival purposes. Unless enforcement is prohibited by
applicable law, you may not modify, decompile, or reverse engineer
Software. Licensee acknowledges that Licensed Software is not designed or
intended for use in the design, construction, operation or maintenance of any
nuclear facility. Sun Microsystems, Inc. disclaims any express or implied
warranty of fitness for such uses. No right, title or interest in or to any
trademark, service mark, logo or trade name of Sun or its licensors is granted
under this Agreement.
3.
LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90)
days from the date of purchase, as evidenced by a copy of the receipt, the
media on which Software is furnished (if any) will be free of defects in
materials and workmanship under normal use. Except for the foregoing,
Software is provided "AS IS". Your exclusive remedy and Sun's entire
liability under this limited warranty will be at Sun's option to replace
Software media or refund the fee paid for Software.
4.
DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS
AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE OR NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO
THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY
INVALID.
5.
LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY
LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY
LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT,
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT
OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE,
EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. In no event will Sun's liability to you, whether in contract, tort
(including negligence), or otherwise, exceed the amount paid by you for
Software under this Agreement. The foregoing limitations will apply even if
the above stated warranty fails of its essential purpose.
6.
Termination. This Agreement is effective until terminated. You may
terminate this Agreement at any time by destroying all copies of Software.
This Agreement will terminate immediately without notice from Sun if you
fail to comply with any provision of this Agreement. Upon Termination, you
must destroy all copies of Software.
7.
Export Regulations. All Software and technical data delivered under this
Agreement are subject to US export control laws and may be subject to
export or import regulations in other countries. You agree to comply strictly
with all such laws and regulations and acknowledge that you have the
responsibility to obtain such licenses to export, re-export, or import as may
be required after delivery to you.
8.
U.S. Government Restricted Rights. If Software is being acquired by or on
behalf of the U.S. Government or by a U.S. Government prime contractor or
subcontractor (at any tier), then the Government's rights in Software and
accompanying documentation will be only as set forth in this Agreement;
this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for
Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and
12.212 (for non-DOD acquisitions).
F–9
9.
Governing Law. Any action related to this Agreement will be governed by
California law and controlling U.S. federal law. No choice of law rules of any
jurisdiction will apply.
10. Severability. If any provision of this Agreement is held to be unenforceable,
this Agreement will remain in effect with the provision omitted, unless
omission would frustrate the intent of the parties, in which case this
Agreement will immediately terminate.
11. Integration. This Agreement is the entire agreement between you and Sun
relating to its subject matter. It supersedes all prior or contemporaneous oral
or written communications, proposals, representations and warranties and
prevails over any conflicting or additional terms of any quote, order,
acknowledgment, or other communication between the parties relating to its
subject matter during the term of this Agreement. No modification of this
Agreement will be binding, unless in writing and signed by an authorized
representative of each party.
JAVATM WEB SERVICES DEVELOPER PACK, VERSION 1.1
SUPPLEMENTAL LICENSE TERMS
These supplemental license terms ("Supplemental Terms") add to or modify the
terms of the Binary Code License Agreement (collectively, the "Agreement").
Capitalized terms not defined in these Supplemental Terms shall have the same
meanings ascribed to them in the Agreement. These Supplemental Terms shall
supersede any inconsistent or conflicting terms in the Agreement, or in any
license contained within the Software.
1.
F–10
Software Internal Use and Development License Grant. Subject to the terms
and conditions of this Agreement, including, but not limited to Section 4
(Java Technology Restrictions) of these Supplemental Terms, Sun grants you
a non-exclusive, non-transferable, limited license to reproduce internally and
use internally the binary form of the Software complete and unmodified for
the purposes of designing, developing, testing, and running your Java
applets and applications intended to run on the Java platform ("Programs"),
except for certain files identified in the Software "Release Notes" file which
may only be used for the purposes of designing, developing, and testing
Programs.
2.
License to Distribute Software. Subject to the terms and conditions of this
Agreement, including but not limited to Section 4 (Java Technology
Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive,
non-transferable, limited license to reproduce and distribute the Software in
binary code form only, provided that you (i) distribute the Software
complete and unmodified and only bundled as part of your Programs, (ii) do
not distribute additional software intended to replace any portion of the
Software, (iii) do not remove or alter any proprietary legends or notices
contained in the Software, (iv) only distribute the Software subject to a
license agreement that protects Sun's interests consistent with the terms
contained in this Agreement, (v) agree to defend and indemnify Sun and its
licensors from and against any damages, costs, liabilities, settlement amounts
and/or expenses (including attorneys' fees) incurred in connection with any
claim, lawsuit or action by any third party that arises or results from the use
or distribution of any and all Programs and/or Software, and (vi) include the
following statement as part of product documentation (whether hard copy or
electronic), as a part of a copyright page or proprietary rights notice page, in
an "About" box or in any other form reasonably designed to make the
statement visible to users of the Software: "This product includes code
licensed from RSA Data Security".
3.
License to Distribute Redistributables. Subject to the terms and conditions of
this Agreement, including but not limited to Section 4 (Java Technology
Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive,
non-transferable, limited license to reproduce and distribute those
components specifically identified as redistributable in the Software "Release
Notes" file ("Redistributables") provided that: (i) you distribute the
Redistributables complete and unmodified (unless otherwise specified in the
applicable Release Notes file), and only bundled as part of your Programs,
(ii) you do not distribute additional software intended to supersede any
portion of the Redistributables, (iii) you do not remove or alter any
proprietary legends or notices contained in or on the Redistributables, (iv)
you only distribute the Redistributables pursuant to a license agreement that
protects Sun's interests consistent with the terms contained in the
Agreement, (v) you agree to defend and indemnify Sun and its licensors
from and against any damages, costs, liabilities, settlement amounts and/or
expenses (including attorneys' fees) incurred in connection with any claim,
lawsuit or action by any third party that arises or results from the use or
distribution of any and all Programs and/or Software, and (vi) if you
distribute the Java Secure Socket Extension package, include the following
statement as part of product documentation (whether hard copy or
electronic), as a part of a copyright page or proprietary rights notice page, in
an "About" box or in any other form reasonably designed to make the
statement visible to users of the Software: "This product includes code
licensed from RSA Data Security".
F–11
F–12
4.
Java Technology Restrictions. You may not modify the Java Platform
Interface ("JPI", identified as classes contained within the "java" package or
any subpackages of the "java" package), by creating additional classes within
the JPI or otherwise causing the addition to or modification of the classes in
the JPI. In the event that you create an additional class and associated API(s)
which (i) extends the functionality of the Java platform, and (ii) is exposed to
third party software developers for the purpose of developing additional
software which invokes such additional API, you must promptly publish
broadly an accurate specification for such API for free use by all developers.
You may not create, or authorize your licensees to create, additional classes,
interfaces, or subpackages that are in any way identified as "java", "javax",
"sun" or similar convention as specified by Sun in any naming convention
designation.
5.
Java Runtime Availability. Refer to the appropriate version of the Java
Runtime Environment binary code license (currently located at
http://www.java.sun.com/jdk/index.html) for the availability of runtime
code which may be distributed with Java applets and applications.
6.
Trademarks and Logos. You acknowledge and agree as between you and
Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET
trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANETrelated trademarks, service marks, logos and other brand designations ("Sun
Marks"), and you agree to comply with the Sun Trademark and Logo Usage
Requirements currently located at
http://www.sun.com/policies/trademarks. Any use you make of the Sun
Marks inures to Sun's benefit.
7.
Source Code. Software may contain source code that is provided solely for
reference purposes pursuant to the terms of this Agreement. Source code
may not be redistributed unless expressly provided for in this Agreement.
8.
Third Party Licenses. Additional copyright notices and license terms
applicable to portions of the software are set forth in the
THIRDPARTYLICENSEREADME file.
9.
Termination for Infringement. Either party may terminate this Agreement
immediately should any Software become, or in either party's opinion be
likely to become, the subject of a claim of infringement of any intellectual
property right.
Tom Sawyer Layout Assistant
This software is provided "AS IS," without a warranty of any kind. ALL
EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC.
("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES
SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL
SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR
DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE
OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
For inquiries please contact: Sun Microsystems, Inc. 4150 Network Circle, Santa
Clara, California 95054.
END-USER LICENSE AGREEMENT FOR Tom Sawyer Software's Layout
Assistant® SOFTWARE
IMPORTANT—READ CAREFULLY. This Layout Assistant End-User License
Agreement ("EULA") is a legal AGREEMENT between You, the Licensee (either
as a registered individual user or as the registered user/representative on behalf
of a single entity), and Tom Sawyer Software Corporation for the Layout
Assistant software product identified above, which product includes computer
software and the associated documentation ("SOFTWARE PRODUCT"). Unless
You have a different license agreement signed by Tom Sawyer Software
Corporation, your installing, copying, or otherwise using the SOFTWARE
PRODUCT indicates You agree to be bound by all the terms of this EULA. If You
do not agree to the terms of this EULA, then You MUST NOT copy, install, or use
the SOFTWARE PRODUCT.
SOFTWARE PRODUCT LICENSE
The SOFTWARE PRODUCT is protected by copyright laws and international
copyright treaties, as well as other intellectual property laws and treaties. The
SOFTWARE PRODUCT is licensed, not sold.
1) Grant of License
This EULA grants You (the Licensee) the following rights:
Applications Software
F–13
Tom Sawyer Software grants You the non-exclusive, non-sublicensable, limited
license to use one copy of the SOFTWARE PRODUCT on a single computer,
subject to the terms and conditions of this EULA. Any individual license for the
SOFTWARE PRODUCT may not be shared or used concurrently or otherwise on
different computers or by different users in a given organization.
In return for our license grant, You hereby irrevocably grant to Tom Sawyer
Software the non-exclusive, worldwide, fully-paid right to publicly disclose the
fact that You are using the SOFTWARE PRODUCT, including but not limited to
the reproduction and distribution of the software 'screen shots' and/or 'box
shots' from your applications for Tom Sawyer Software's advertising and other
promotional purposes.
Storage/Network Use
You may also store or install a copy of the SOFTWARE PRODUCT on a storage
device, such as a network server, used only to install or run the SOFTWARE
PRODUCT on your other computers over an internal network; however, you
must acquire and dedicate a distinct license for each developer using the
SOFTWARE PRODUCT from the storage device. Any given license for the
SOFTWARE PRODUCT may not be shared or used concurrently or otherwise on
different computers or by different developers in a given organization.
License Pack
If You have acquired this EULA in a Tom Sawyer Software Layout Assistant
License Pack, You may install the number of additional copies of the
SOFTWARE PRODUCT identified above on this EULA, and You may use each
copy in the manner specified above.
2) Description of Other Rights and Limitations
F–14
You acknowledge that the SOFTWARE PRODUCT in source code form remains
a confidential trade secret of Tom Sawyer Software, and therefore You agree not
to reverse-engineer, decompile, or disassemble the SOFTWARE PRODUCT, or
make any attempt to discover the source code to the SOFTWARE PRODUCT,
except and only to the extent that such activity is expressly permitted by
applicable law notwithstanding this limitation. Except as expressly permitted in
this EULA, the SOFTWARE PRODUCT may not be used, copied, translated,
redistributed, retransmitted, published, sold, rented, leased, marketed,
sublicensed, pledged, assigned, disposed of, encumbered, transferred, altered,
modified, or enhanced, whether in whole or in part, nor may You create
derivative works from or based on the SOFTWARE PRODUCT. You may not
remove any proprietary notices, marks, or labels from the SOFTWARE
PRODUCT.
The SOFTWARE PRODUCT is licensed as a single product and its components
may not be separated for use on more than one computer.
Termination
Without prejudice to any of Tom Sawyer Software’s other rights, Tom Sawyer
Software may terminate this EULA if You fail to comply with the terms and
conditions of this EULA. In such event, You must destroy any and all copies of
the SOFTWARE PRODUCT and all of its component parts; to this end You grant
to Tom Sawyer Software the right to, with or without notice, monitor your
Internet accessible activities for the purpose of verifying SOFTWARE PRODUCT
performance and/or your compliance with the terms hereof, including, but not
limited to the remote monitoring and verification of your implementation, use
and duplication of the SOFTWARE PRODUCT.
3) Upgrades
You must currently be properly licensed to use the SOFTWARE PRODUCT in
order to be eligible to purchase an upgrade. A SOFTWARE PRODUCT identified
by Tom Sawyer Software as an upgrade replaces and/or supplements the
product that formed the basis for your eligibility for such upgrade. You may use
the resulting upgraded product only in accordance with the terms of this EULA.
4) Copyright and Trademarks
F–15
All title, trademarks, and copyrights in and pertaining to the SOFTWARE
PRODUCT (including but not limited to any images, photographs, animation,
video, audio, music, text, and applets incorporated into the SOFTWARE
PRODUCT) are owned by Tom Sawyer Software Corporation. The SOFTWARE
PRODUCT is protected by copyright and trademark laws and international
treaty provisions. The SOFTWARE PRODUCT is licensed, not sold. There is no
transfer to You of any title or ownership of the SOFTWARE PRODUCT and the
license granted under this EULA should not be construed as a sale of any right in
the SOFTWARE PRODUCT. You must treat the SOFTWARE PRODUCT like any
other copyrighted materials for archival purposes.
You may not remove, modify or alter any Tom Sawyer Software copyright or
trademark notice from any part of the SOFTWARE PRODUCT, including but not
limited to any such notices contained in the electronic media or documentation,
in the Layout Assistant Setup Wizard dialogue or 'about' boxes, in any of the
runtime resources, and/or in any web-presence or web-enabled notices, code, or
other embodiments originally contained in or dynamically or otherwise created
by the SOFTWARE PRODUCT.
5) Dual-Media Software
You may receive the SOFTWARE PRODUCT in more than one medium.
Regardless of the type or size of the medium You receive, You may use only that
one medium that is appropriate for your single computer. You may not use or
install the other medium on another computer, including but not limited to
portable computers under the exclusive control of the registered developer. You
may not loan, rent, lease, or otherwise transfer the other medium to another user.
6) U.S. Government Restricted Rights
The SOFTWARE PRODUCT and documentation are provided with
RESTRICTED RIGHTS. Use, duplication, or disclosure by the U.S. Government is
subject to restrictions as set forth in subparagraph C(1)(ii) of the subparagraphs
(c) (1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR
52.227-19, as applicable. Manufacturer is: Tom Sawyer Software Corporation,
1625 Clay Street, Sixth Floor, Oakland, CA 94612, USA (or by FAX +1 510 208
4371, e-mail to info@tomsawyer.com).
7) Miscellaneous
F–16
If You acquired or use this SOFTWARE PRODUCT in the United States, this
EULA is governed by the laws of the State of California. If this SOFTWARE
PRODUCT was acquired and is used exclusively outside of the United States, the
local law may also apply. Should You have any questions concerning this EULA,
or if You desire to contact Tom Sawyer Software for any reason, please write:
Tom Sawyer Software Corporation, 1625 Clay Street, Sixth Floor, Oakland, CA
94612, USA (or by FAX +1 510 208 4371, e-mail to info@tomsawyer.com).
8) Limited Warranty
Limited Warranty Tom Sawyer Software warrants that for a period of thirty (30)
days from the date of your original purchase ("warranty period") as evidenced
by your receipt or other proof of purchase, the SOFTWARE PRODUCT, unless
modified or otherwise altered by You, will perform substantially in accordance
with the accompanying written materials.
Tom Sawyer Software does not warrant that the SOFTWARE PRODUCT will
meet your requirements or use of the SOFTWARE PRODUCT will be
uninterrupted or error-free. Tom Sawyer Software is not responsible for
problems caused by changes in the operating characteristics of computer
hardware or computer operating systems which are made after the release of the
SOFTWARE PRODUCT, nor for problems in the interactions of the SOFTWARE
PRODUCT with non-Tom Sawyer Software products.
Some jurisdictions do not allow limitations on duration of an implied warranty,
so the above limitation may not apply to You. To the extent implied warranties
may not be entirely disclaimed but implied warranty limitations are allowed by
applicable law, implied warranties on the SOFTWARE PRODUCT, if any, are
limited to thirty (30) days.
THE ABOVE WARRANTIES ARE EXCLUSIVE. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, TOM SAWYER SOFTWARE DISCLAIMS
ALL OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESS OR
IMPLIED, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE, TITLE, AND
NON-INFRINGEMENT, AND THOSE ARISING OUT OF USAGE OF TRADE
OR COURSE OF DEALING, CONCERNING THE SOFTWARE PRODUCT. NO
ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY TOM SAWYER
SOFTWARE OR ITS EMPLOYEES SHALL INCREASE THE SCOPE OF THE
ABOVE WARRANTIES OR CREATE ANY OTHER WARRANTIES.
Customer Remedies
F–17
Tom Sawyer Software's entire liability, and your exclusive remedy, shall be, at
Tom Sawyer Software's option, either (a) repair or replacement of the
SOFTWARE PRODUCT that does not meet Tom Sawyer Software's Limited
Warranty, or (b) return of the price paid, if any, and termination of this EULA.
This remedy is subject to delivery to Tom Sawyer Software of a Tom Sawyer
Software-approved "Affidavit of Destruction" together with proof of purchase
within the Warranty Period. This Limited Warranty is void if failure of the
SOFTWARE PRODUCT has resulted from accident, abuse or misapplication.
Any replacement SOFTWARE PRODUCT will be warranted for the remainder of
the original warranty period or fifteen (15) days, whichever is longer.
9) Limitation of liability for damages
REGARDLESS OF WHETHER ANY REMEDY SET FORTH HEREIN FAILS IN
ITS ESSENTIAL PURPOSE, TO THE MAXIMUM EXTENT PERMITTED BY THE
APPLICABLE LAW, IN NO EVENT SHALL TOM SAWYER SOFTWARE BE
LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT
LIMITATION, CONSEQUENTIAL, INCIDENTAL, INDIRECT, SPECIAL,
ECONOMIC, PUNITIVE, OR SIMILAR DAMAGES, OR DAMAGES FOR LOSS
OF BUSINESS PROFITS, LOSS OF GOODWILL, BUSINESS INTERRUPTION,
COMPUTER FAILURE OR MALFUNCTION, LOSS OF BUSINESS
INFORMATION, OR ANY AND ALL OTHER COMMERCIAL OR PECUNIARY
DAMAGES OR LOSSES) ARISING OUT OF THE USE OF OR INABILITY TO
USE THE SOFTWARE PRODUCT, HOWEVER CAUSED AND ON ANY LEGAL
THEORY OF LIABILITY (WHETHER IN TORT, CONTRACT, OR OTHERWISE),
EVEN IF TOM SAWYER SOFTWARE HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES, OR ANY CLAIM BY ANY OTHER PARTY.
YOU ACKNOWLEDGE THAT THE LICENSE FEE REFLECTS THIS
ALLOCATION OF RISK.
In any event, if any statute implies warranties or conditions not stated in this
EULA, Tom Sawyer Software's entire liability under any provision of this EULA
shall be limited to the greater of the amount actually paid by You to license the
SOFTWARE PRODUCT or Five United States Dollars (US$5.00). Because some
jurisdictions do not allow the exclusion or limitation of liability for consequential
or incidental damages, the above limitation may not apply to You.
F–18
Index
defining, 6-42
privileges, 6-47
.
administrator, 6-12
defining, 6-42
.dxc file type, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33
Advantage Ingres errors, C-17
.dxg file type, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33
.dxi file type, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14
agreement, 7-20
get, 7-20
set, 7-20
.dxs file type, 2-4
alarm-log file, 3-8
alarms, 3-5
multiwrite queues, 7-12
A
alert-log file, 3-8
abandon
all operations, 3-24
operation, 3-24
abort associations, 3-18
abstract object classes, 4-14
access control permissions, 6-49
alias
access controls, 6-56
dangling aliases, C-16
entry, 4-19
errors, C-16
integrity, 3-27, C-16
invalid, 3-27
name binding, 4-19
access controls, 3-23
aliases, 6-56
dynamic, 6-50
policy, 6-33, 6-34
role-based, 6-53
roles, 6-53
routing, 6-57
rule hierarchies, 6-37
rules, 6-37
secure proxy, 6-55
static, 6-37
allow-check-password trust flag, 3-53
access subdirectory, 2-2
application program interface. See API
accounts
suspending, 6-30
arguments
DXtools, 10-36
add
assoc
commands, 3-13
configuration, 3-15
database user, 10-14
administrative user
allow-downgrading trust flag, 3-53
allow-upgrading trust flag, 3-53
alt-name, 8-3
anonymous bind, 6-11
Apache Tomcat license agreement, F-1
API (application program interface)
UDDI, 14-3
Index–1
associations
aborting, 3-18
configuration, 5-7
limiting, 3-18
maximum times, 3-17
queues, 3-19
rejection, 3-18
tracing, 3-16
users, 3-16
viewing, 3-16
asynchronous
multiwrite, 7-6
attributes
changing schema, 4-12
checking, 4-7
indexing, 3-30
inherited rules, 4-7
invalid, 4-7
locally customized, 8-3
multiple, 4-18
read-only, 4-5, B-9
sets, 4-8
single-valued, 4-5
syntax, 4-2, 4-6
auditing
monitoring, 9-2
authentication
conveying, 6-19, 6-20
DISP, 6-16, 6-18
distributed user, 6-15
DSP, 5-6, 6-16, 6-18
DSP link, 6-21
setting levels, 6-11
SSL, 6-13
strong, 6-21
user, 6-13
auxiliary object classes, 4-15
anonymous, 6-11
control, 3-17
DSP requests, 6-16
maximum time, 3-17
names, 4-18
with credentials, 5-6
bookmarks, 11-13
bulk loading, 16-8
C
cache-only mode, 3-38
configuring, 3-38
example, 3-39
caches, 3-32
configuring, 3-33
enabling, 3-33
example configuration, 3-36
indexing, 3-34, 3-35
load all attributes, 3-36
maximum size, 3-35
reverse-indexing, 3-36
settings, 3-34
synchronizing with database, 3-37
viewing configuration, 3-37
caching subordinate entries, 5-16
certificates, 6-5
generating, 10-21
generation, 6-5
reporting, 10-21
certification
language, 13-5, 14-6
cert-log file, 3-9
change control, 16-8
B
changes in LDIF files, 10-33
changing schema, 4-12
backup a database, 10-7
base-object searches, 3-33
billing
monitoring, 9-2
bin directory, 2-2
bind
Index–2
characters
non-English, 13-5, 14-6
ciphers, 6-9
clear
dsas, 5-5
indexes, 3-30
CLI, 2-14
client encryption, 6-10
close logtype, 3-11
closing the management console, 2-15
CMIP (Common Management Information Protocol),
1-2, 3-22, 9-1
agent, 9-8
monitoring utility, 9-9
X.700 management, 9-8
cmip-psap, 9-8
collective attributes, 3-40
command-line
interface, 2-14
options, 2-9
commands
assoc, 3-13
controlling output, 3-8
DSP, 5-2
DXserver, 2-11
grouping by function, 2-11
help, 2-20
logs, 3-11
oper, 3-20
shortcuts, 2-21
syntax, 2-12
trace, 3-5, 3-6
commands, access control
set access-controls, 3-23
set protected-items, 6-36
set super-user, 6-41
ssld, 6-6
commands, associations
abort, 3-18
get assoc, 3-15
get users, 3-16, 3-17, 3-18, 3-24, 9-2
set allow-binds, 3-17
set authentication, 3-17
set credits, 3-19
set max-bind-time, 3-17
set max-users, 3-18
set min-auth, 6-11
set user-idle time, 3-18
commands, CMIP
cmip-psap, 9-8
dxcmip, 9-9
commands, DAP tools
common argument, 10-36
DXdelete, 10-42
DXmodify, 10-39
DXrename, 10-41
DXsearch, 10-37
commands, DB tools
DXadduser, 10-14
DXbackupdb, 10-7
DXdeluser, 10-15
DXdestroydb, 10-6
DXdumpdb, 10-18
DXemptydb, 10-6
DXextenddb, 10-5
DXgrantdb, 10-19
DXindexdb, 10-10
DXlistdb, 10-14
DXloaddb, 10-16
DXnewdb, 10-5
DXnewdsa, 10-4
DXrestoredb, 10-8
DXstatdb, 10-13
DXtunedb, 10-9
DXupgradedb, 10-20
commands, DIB
clear indexes, 3-30
get dib, 3-26
set alias-integrity, 3-27
set database-name, 2-23, 3-26
set eis-count-attr, 3-28
set index wide, 3-30
set index-reverse, 3-30
set not-searchable, 3-30
commands, DISP
disp update, 7-23
get agreement, 7-20
set agreement, 7-20, 7-21
commands, DSAs
set always-chain-down, 5-9
set dsa, 3-1, 5-8, 5-10, 5-11, 5-12, 6-6, 7-23, 8-9
set precedence, 5-19
shutdown, 3-16
commands, DSP
clear dsas, 5-3, 5-5
get dsp, 5-7
get online dsas, 5-7
get online-dsas, 5-5, 9-2
set multi-casting, 5-6
unbind, 5-3
commands, LDIF tools
csv2ldif, 10-30
ldifdelta, 10-33
Index–3
commands, local operations
get oper, 3-22
get stats, 3-22, 9-2
reset stats, 3-22
set max op-size, 3-23
set max-local-ops, 3-23
set max-op-size, 3-24
set max-op-time, 3-24, 3-27
commands, logs
close logtype, 3-11
echo, 3-12
echo-off, 3-12
echo-on, 3-12
flush logtype, 3-11
get log, 3-11
set logtype, 3-11
set summary-log, 3-12
commands, multiwrite
set multi-write-queue, 7-11
commands, schema, 4-3
get schema, 4-4
set attribute, 4-4, 4-5, 4-8
set attr-set, 4-8
set name-binding, 4-18
set object-class, 4-14
set oid-prefix, 4-4
commands, SCHEMA tools
DXschemaldif, 10-44
DXschematxt, 10-49
ldif2dxc, 10-45
commands, SNMP
snmp-port, 9-5
operations, 3-22
server, 2-2
configuration files, 1-3
grouping, 2-6
grouping commands, 2-11
configuring
another DXserver, 5-8
DSP relay, 5-15
first level DSA, 5-14
management console, 2-16
multiple local DSAs, 5-12, 5-14
third-party DSAs, 5-4, 5-6, 5-10, 5-11
connect times, 3-16
connection
address, 3-17
information, 3-16
remote, 5-4, 5-5, 5-16
time, 3-17
UDDI server, to, 14-5
connect-log file, 3-9
control
binds, 3-17
operations, 3-23, 3-24
controlling
operations, 3-23
output, 3-8
CPUs, multiple, 5-12
creating a database, 10-5
credentials, definition, 6-11
commands, traces
set trace, 3-6, 3-16
trace disable assoc, 3-16
trace enable assoc, 3-16
credits, 3-19
comments in script files, 2-13
csv2ldif, 10-27, 10-30
Common Management Information Protocol. See
CMIP
communication settings, view, 3-4
crypt password format, 3-29
CSV data, 10-27
D
complex queries, 5-24
dangling alias, C-16
config directory, 2-2
DAP (Directory Access Protocol), 1-2
configuration
DIB, 3-26
DSP, 5-2
file errors, 2-13
file type, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33
database
add user, 10-14
backup, 10-7
backups, 16-7
Index–4
creation, 10-5
data removal, 10-6
delete user, 10-15
destruction, 10-6
hot swap, 2-23
initializing, 2-22
integrity, 4-2, C-17
listing, 10-14
massive, 5-12
monitoring, 9-3
multiple directory, 2-23
name, 3-26
restore, 10-8
statistics, 10-13
tailoring, A-1
tuning, 10-9
database subdirectory, 2-3
debugging, 2-13
default port numbers, 2-24
defining
local data types, 4-20, 8-4
local schema, 4-20, 8-4
users, 6-12
delete
database user, 10-15
directory entries, 10-42
Democorp sample DSA
port number, 2-25
destroying a database, 10-6
DIB (Directory Information Base), 1-3, 3-25
manage, 3-25
directory
delete entries, 10-42
Information Shadowing Protocol (DISP), 7-20
knowledge, 3-1
modify, 10-39
rename, 10-41
samples, 1-4, 1-5, 15-13
search, 10-37
Directory Access Protocol. See DAP
Directory System Protocol. See DSP
Directory User Agent (DUA), 1-4
disk space
monitoring, 9-3
DISP (Directory Information Shadowing Protocol), 1-2
authentication, 6-16
responder, 7-20
update, 7-23
display database statistics, 10-13
distinguished name, 5-8
relative, 5-14
DIT (Directory Information Tree), 5-4
definition, 5-8
prefix, 5-4
relay DSA, 5-16
DSA
caching entries, 5-16
defining, 3-1
first level, 5-14
load-sharing, 5-20, 5-24
local, 5-8, 5-10
multiple local, 5-12, 5-14
proxy, 5-9
relay, 5-16
shadow, 7-23
stopping, 3-16
third-party, 5-4, 5-6, 5-10, 5-11
trust flags, 3-48
DSA flags, 3-25, 3-52, 5-16, 7-23
limit-list, 3-28
limit-search, 3-29
DSA processes, multiple, 2-22
dsa, ssld-port, 6-6
dsaEntriesTable, 9-4
dsaIntTable, 9-4
dsaOpsTable, 9-4
dsp
clear dsas, 5-2, 5-3
get, 5-2
set, 5-2
unbind, 5-2
unbind, 5-3
directory browser
JXplorer, 11-1
JXweb, 13-1
directory entries, counting, 3-28
Directory Information Base. See DIB
Directory Information Shadowing Protocol. See DISP
DSP
DSP (Directory System Protocol), 1-2
Index–5
authentication, 5-6, 6-16, 6-18
bind request, 6-16
commands, 5-2
configuration, 5-2, 5-7
credentials, 5-6
incoming credentials, 5-6
monitoring connections, 5-7
multiprocessing, 5-12
outgoing connections, 5-5
outgoing credentials, 5-6
relay, 5-15
dsp-ldap link flag, 3-54
dsp-ldap-proxy link flag, 3-54
dsp-ldapv2 link flag, 3-54
DUA, 1-4
dump, 10-1
DXadduser, 10-14
DXadmind
port number, 2-24
DXbackup, 16-7
DXbackupdb, 10-7
DXcache, 3-32
configuring, 3-33
enabling, 3-33
example configuration, 3-36
indexing, 3-34, 3-35
load all attributes, 3-36
maximum size, 3-35
settings, 3-34
synchronizing, 3-37
viewing configuration, 3-37
DXcertgen, 10-21
dxcmip, 9-9
DXconsole, 2-14, 9-2
DXdelete, 10-42
DXdeluser, 10-15
DXdestroydb, 10-6
DXdisp, 10-20
DXdumpdb, 10-18
DXemptydb, 10-6
Index–6
DXextenddb, 10-5
DXgrantdb, 10-19
DXI configuration file, 3-32
DXindexdb, 10-10
DXlistdb, 10-14
DXloaddb, 10-16
DXmodify, 10-39
DXnewdb, 10-5
DXnewdsa, 10-4
DXrename, 10-41
DXrestoredb, 10-8
DXschemaldif tool, 10-44
DXschematxt tool, 10-49
DXsearch, 10-37
DXserver, 1-2
alarms, C-7
commands, 2-11
configuring SSL, 6-6
logs, C-2
version, 2-10
warning messages, C-13
dxsnmp, 9-6
DXstatdb, 9-3, 10-13
DXsyntax tool, 10-50
DXtools, 1-3, 7-26
csv2ldif, 10-30
DXadduser, 10-14
DXbackupdb, 10-7
DXcertgen, 10-21
DXdelete, 10-42
DXdeluser, 10-15
DXdestroydb, 10-6
DXdisp, 10-20
DXdumpdb, 10-18
DXemptydb, 10-6
DXextenddb, 10-5
DXgrantdb, 10-19
DXindexdb, 10-10
DXlistdb, 10-14
DXloaddb, 10-16
DXmodify, 10-39
DXnewdb, 10-5
DXnewdsa, 10-4
DXrename, 10-41
DXrestoredb, 10-8
DXschemaldif, 10-44
DXschematxt, 10-49
DXsearch, 10-37
DXstatdb, 10-13
DXtunedb, 10-9
DXupgradedb, 10-20
ldif2dxc, 10-45
ldifdelta, 10-33
DXtunedb, 10-9, 16-8
DXupgradedb, 10-20
DXweb server, 1-5
F
failover
multiwrite, 7-9
file descriptors, 3-18, 16-10
file extensions
dxc, 2-4, 2-6, 3-1, 4-6, 5-8, 5-13, 5-14, 6-33
dxg, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33
dxi, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14
dxs, 2-4
files
configuration, 1-3
launch, 11-22
types, 2-4
DXwebserver
port number, 2-24
dynamic access controls, 6-50
dynamic groups, 3-40
firewall, 5-9
alternative network addresses, 5-10
flush logtype, 3-11
forward requests, 5-15
E
echo command, 3-12
embedded installation
on Windows, D-17
emptying a database, 10-6
encryption
client, 6-10
DSA to DSA, 6-10
error logs, C-1
error messages
search overflow, 3-31
G
generating certificates, 10-21
get
assoc, 3-15
dib, 3-25, 3-26
dsp, 5-3, 5-7
log, 3-11
online-dsas, 5-5, 5-7, 9-2
oper, 3-22
operations, 3-21
schema, 4-3, 4-4
stats, 3-22, 9-2
users, 3-16, 3-17, 3-18, 3-24, 9-2
errors
configuration file, 2-13
ldif2dxc tool, 10-46
script file, 2-13
statistics, 3-22
group
configuration files, 2-6
file type, 2-4, 2-6, 4-2, 5-8, 5-13, 5-14, 6-33
event logs, C-1
group membership, 3-40
events, 3-22
groups
dynamic, 3-40
hybrid, 3-41
static, 3-40
export, 10-1
guard, 5-9, 7-23
Index–7
H
invalid
aliases, 3-27
attribute, 4-7
help command, 2-20
ISO 9594-10, 9-8
history files, 3-12
hot swap, 2-23
hybrid
groups, 3-41
I
IA5 string, 4-7
idle times, 3-16
maximum, 3-18
IETF, 4-1
impersonation protection, 6-22
import, 10-1
import data, 3-23
increased user counts, 2-22
indexing
commands, 3-30
for caches, 3-35
options, 3-30
reverse, 3-36
wide indexes, 3-31
initialization
file, 2-5
file type, 2-4, 2-5, 4-2, 5-8, 5-13, 5-14
server, 2-9
initializing multiwrite–DISP recovery, 10-20
J
JXplorer, 11-1
add audio file, 11-22
add entry, 11-23
add photo, 11-21
binary values, 11-20
browse, 11-7
button bar, 11-5
connect, 11-7
display enries, 11-9
edit the directory, 11-16
file launch, 11-22
LDIF files, 11-25
managing certificates, 11-28
menu bar, 11-3
modify attributes, 11-18
navigate, 11-8
quick search bar, 11-6
refresh entries, 11-11
search, 11-11
SSL and SASL, 11-27
submit entry, 11-24
templates, 11-9
JXweb
connect to a directory, 13-3
display directory information, 13-4
K
initiator, 7-21
install directory, 2-3
Installation
logging on Windows, D-3, E-3
installation code, D-17, E-24
knowledge, 3-1, 6-5
directory, 2-3, 3-1
references, 5-3
knowledge flags, 3-48
installing eTrust Directory
for Windows, D-1, E-1
L
installing silently
on Windows, D-14
language certification, 13-5, 14-6
installing the sample tools
on Windows, D-9, E-17
Index–8
LDAP (Lightweight Directory Access Protocol), 1-2
managing, 8-3
names, 4-5, 4-8
servers, 8-9
LDAP attributes
changing, 4-12
LDAP port number, 8-2
ldap-dsa-name, 8-7
ldap-dsa-password, 8-7
LDIF
format, 10-29
tools, 10-27
LDIF file
calculating changes, 10-33
sort, 10-31
template file, 10-28
ldif2dxc tool, 10-45
error handling, 10-46
OID maps, 10-47
schema.txt file update, 10-47
ldifdelta, 10-33
ldifsort, 10-31
LDT file, 10-28
LDUA, 1-4
license agreement
Apache Tomcat, F-1
OpenLDAP, F-4
OpenSSL, F-6
SUN Java Web Services, F-8
load sharing, 2-22, 5-12
DSA, 5-20, 5-24
load-share DSA flag, 3-52
local
attributes, 4-20, 8-4
data type definition, 4-20, 8-4
DSAs, 5-8, 5-10
schema, 4-20, 8-4
local operations, 3-20
locking a password, 6-30
log files
alarm-log, 3-8
alert-log, 3-8
cert-log, 3-9
closing, 3-11
commands, 3-11
connect-log, 3-9
flush, 3-11
monitoring, 9-2
opening, 3-11
query-log, 3-9
stats-log, 3-9
summary, 3-12
summary-log, 3-10
trace-log, 3-10
types, 3-8
update-log, 3-10
viewing, 3-11
Logging
installation on Windows, D-3, E-3
logging subdirectory, 2-3
Lightweight Directory Access Protocol. See LDAP
login entries, 6-48
limiting associations, 3-18
logs directory, 2-3
limiting searches to simple only, 3-29
limit-list DSA flag, 3-52
limits subdirectory, 2-3
limit-search DSA flag, 3-52
link flags, 3-54
list
existing databases, 10-14
listen address for LDAP requests, 8-2
listen address for SNMP requests, 9-5
listening address, 2-22, 3-4, 7-20, 8-2
M
management console, 2-14, 2-16
closing, 2-15
configuration, 2-16
opening, 2-14
Management Information Base. See MIB
managing
large numbers of entries, 16-11
large numbers of users, 16-10
LDAP, 8-3
Index–9
telnet configuration, 2-16
multiwrite status, 7-12
mapping, prefixes, 8-9
multi-write-async DSA flag, 3-52
matching rules, 4-6
multiwrite–DISP recovery, 10-20
may-contain, 4-14
multi-write-disp-queue DSA flag, 3-52
md5 password format, 3-29
multi-write-notify DSA flag, 3-52
members of groups, 3-40
must-contain, 4-14
memory
maximum size of cache, 3-35
merge, 10-1
MIB (Management Information Base), 3-22, 9-4
MIB walker, 9-6
migration path, 10-1
modify
directory, 10-39
monitoring
active users, 3-17
CMIP, 9-9
databases, 9-3
disk space, 9-3
DSP, 5-7
dxconsole, 9-2
log files, 9-2
ms-ad DSA flag, 3-52
ms-ad link-flag, 3-54
ms-exchange link-flag, 3-54
multicasting, 5-6, 5-13
multiple
DSA processes, 2-22
multiwrite
asynchronous, 7-6
enabling, 7-9
retry interval, 7-10
multi-write DSA flag, 3-52
multiwrite failover, 7-9
multiwrite groups, 7-7
setting up, 5-23, 7-9
multiwrite queues
alarms, 7-12
size, 7-11
multiwrite replication, 7-5
Index–10
N
name, 8-3
name binding, 4-18
aliases, 4-19
checks, 4-18
considerations, 4-19
rules, 4-18
structural object classes, 4-19
native-prefix, 8-9
no compatible link type, 6-21
non-English characters, 13-5, 14-6
no-routing-ac DSA flag, 3-52
North American Directory Forum, 4-1
no-server-credentials trust flag, 3-53
nsap, 3-3
O
object class, 4-14
checking, 4-15, 4-16
kinds, 4-14
abstract, 4-14
auxiliary, 4-15
structural, 4-15
pruning, 4-17
replacing, 4-17
object identifier (OID), 4-4
oem-encrypt password format, 3-29
oem-hash password format, 3-29
OID prefix, 4-4
one-level searches, 5-16
opening the managment console, 2-14
pid directory, 2-3
OpenLDAP license agreement, F-4
port numbers, 2-24
LDAP, 8-2
setting with set dsa command, 3-4
OpenSSL license agreement, F-6
oper commands, 3-20
operations, 3-22
abandon, 3-24
configuration, 3-22
control, 3-23, 3-24
controlling, 3-23
remote, 5-17
statistics, 3-22
output, controlling, 3-8
preferredDelivery, 4-6
prefix
mapping, 8-9
schema, 4-4, 4-5
presentationAddress, 4-6
printable character, 4-7
privileges, 6-47
protected item, 6-42, 6-44
defining, 6-47
P
protocol tracing, 3-7
prototyping, 10-1
parallel processing, 5-12
parameters
get assoc command, 3-15
get dib command, 3-25
get dsp command, 5-3
get operations command, 3-21
get schema command, 4-3
oper command, 3-21
resetting SSLD, 6-8
set assoc command, 3-13, 7-21
set dib command, 3-25
set dsa command, 3-3
set dsp command, 5-2
set operations command, 3-20
set schema command, 4-3
password, 3-23
attribute, 6-12
expiry, 6-28
protection, 6-24, 6-48
reset, 6-24
passwords
locking, 6-30
storage formats, 3-29
performance, 5-12, 10-9
degradation, 6-35
tuning, 16-8
permissions, 6-37, 6-49
personality, 6-5
certificate generation, 6-5
proxy
DSAs, 5-9
secure, 6-55
public users, defining, 6-46
Q
query streaming, 5-24
query-log file, 3-9
R
RAM
maximum size of cache, 3-35
RDBMS
tools, 1-5
read
privileges, 6-44
unrestricted, 6-41
read-only access, 6-46
read-only attributes, 4-5, B-9
read-only DSA flag, 3-52
recovery
multiwrite–DISP, 10-20
Index–11
references, 5-3
referrals, 5-9
registered users, 6-44
relative distinguished name, 5-14
relay, 7-21
DSA, 5-16
DSP, 5-15
relay DSA flag, 3-52
reload, 10-1
remote connections, 5-4, 5-5, 5-16
remote operations, 5-17
rename a directory, 10-41
replication
clock synchronization, 7-4
directory, 2-3
multiwrite, 7-5
using DXtools, 7-26
defining local, 4-20
definition, 4-1
directory, 2-3
local, 4-20, 8-4
management, 4-3
prefixes, 4-4, 4-5
published, 4-20
validation, 4-2
viewing, 4-4
SCHEMA tools, 10-43
DXschemaldif, 10-44
DXschematxt, 10-49
ldif2dxc, 10-45
script file
description, 2-13
errors, 2-13
type, 2-4
reset stats, 3-22
search
a directory, 10-37
complex, 11-11
indexes, 3-30
quick, 11-11
return attribute lists, 11-12
templates, 11-12
resetting SSLD parameters, 6-8
search overflow error message, 3-31
resetting statistics, 3-22
searches
limiting to simple only, 3-29
simple, 5-25
repository, UDDI, 14-1
responder, 7-21
restore a database, 10-8
retry interval for multiwrite, 7-10
searching
base-object, 3-33
return attribute lists, 11-12
secure proxy, 6-55
Secure Socket Layer, 6-2
RFC1567, 9-4
security, 5-12
roles, access controls, 6-53
security level, 3-23, 3-24, 3-28
Router sample DSA
port number, 2-25
server
configuration, 2-2
DXweb, 1-5
initialization, 2-9
UDDI, 14-3
rules, 6-34
components, 6-37
servers subdirectory, 2-3
S
service
errors, C-17
samples directory, 1-4, 1-5, 2-3, 15-13
schema
commands, 4-3
Index–12
service error
administration limit exceeded, 3-24
operation abandoned, 3-24
set
name-binding, 4-18
object-class, 4-14
oid-prefix, 4-4
schema, 4-3
set commands
assoc, 3-13, 7-21
dib, 3-25
dsp, 5-2
operations, 3-20
set commands, access control
access-controls, 3-23
protected-items, 6-36
super-user, 6-41
set commands, traces
trace, 3-6
settings subdirectory, 2-3
sha-1 password format, 3-29
shadow DSA flag, 3-52
shadow DSAs, 7-23
set commands, associations
allow-binds, 3-17
credits, 3-19
max-bind-time, 3-17
max-users, 3-18
min-auth, 6-11
user-idle-time, 3-18
shortcuts for commands, 2-21
set commands, DIB
alias-integrity, 3-27
database-name, 2-22, 2-23, 3-26
eis-count-attr, 3-28
index-reverse, 3-30
index-wide, 3-30
not-searchable, 3-30
simple searches, 5-25
set commands, DISP
agreement, 7-21
set commands, DSAs
always-chain-down, 5-9
dsa, 3-1, 5-8, 5-10, 5-11, 5-12, 6-6, 7-23, 8-9
precedence, 5-19
set commands, DSP
multi-casting, 5-6
set commands, local operations
max-local-ops, 3-23
max-op-size, 3-23, 3-24
max-op-time, 3-24, 3-27
set commands, logs
logtype, 3-11
summary-log, 3-12
set commands, mutliwrite
multi-write-queue, 7-11
set commands, schema
attribute, 4-5
attribute, 4-4, 4-8
attr-set, 4-8
shutdown command, 3-16
silent installation
on Windows, D-14
Simple Network Management Protocol. See SNMP
simple queries, 5-24
single-valued attributes, 4-5
SNMP (Simple Network Management Protocol), 1-2,
3-22, 9-1
MIB walker, 9-6
SNMP monitoring
port number, 2-25
SNMP port number, 9-5
snmp-port, 9-5
sort an LDIF file, 10-31
ssha-1 password format, 3-29
SSL
configuring DXserver, 6-6
connections, 6-4
daemon, 6-3
enabling, 6-2
SSL/TLS connections
ciphers, 6-9
SSLD, 6-3
configuring, 6-6
port number, 2-24
SSLD example
ciphers for SSL/TLS connections, 6-9
four threads, 6-9
SSLD parameters
Index–13
resetting, 6-8
tModels, 14-5
ssl-encryption link-flag, 3-54
Tomcat port number, 2-24
ssl-encryption-remote link-flag, 3-54
tools
csv2ldif, 10-30
DXadduser, 10-14
DXbackupdb, 10-7
DXcertgen, 10-21
DXdelete, 10-42
DXdeluser, 10-15
DXdestroydb, 10-6
DXdisp, 10-20
DXdumpdb, 10-18
DXemptydb, 10-6
DXextenddb, 10-5
DXgrantdb, 10-19
DXindexdb, 10-10
DXlistdb, 10-14
DXloaddb, 10-16
DXmodify, 10-39
DXnewdb, 10-5
DXnewdsa, 10-4
DXrename, 10-41
DXrestoredb, 10-8
DXschemaldif, 10-44
DXschematxt, 10-49
DXsearch, 10-37
DXstatdb, 10-13
DXtunedb, 10-9
DXupgradedb, 10-20
ldif2dxc, 10-45
ldifdelta, 10-33
RDBMS, 1-5
static access controls, 6-37
static groups, 3-40
statistics
monitoring, 9-2
resetting, 3-22
traced, 3-7
viewing, 3-22
stats-log file, 3-9
statuses
multiwrite, 7-12
stopping DSAs, 3-16
strategy, 7-21, 7-22
string labels, 8-3
strong authentication, 6-21
structural object classes, 4-15
summary-log file, 3-10
SUN Java Web Services license agreement, F-8
superuser
password, 6-12
privileges, 6-47
suspend a user’s account, 6-30
synchronization, replication, 7-4
syntax
attribute, 4-2, 4-6
commands, 2-12
undefined, 4-6
trace
command, 3-5, 3-6
protocol, 3-7
statistics, 3-7
trace-log file, 3-10
tracing, 3-5
associations, 3-16
T
transparent routing, 5-15
telephoneNumber, 4-6
trust flags, 3-53
teletexTerminalId, 4-6
trust subdirectory, 2-3
telexNumber, 4-6
trust-conveyed-originator trust flag, 3-53
telnet, 9-1
tuning a database, 10-9
template file, 10-28
timeouts, 3-22
Index–14
U
monitoring, 3-17
name, 3-17
number of, 3-17
public, 6-46
registered, 6-44
superusers, 6-12, 6-41
UDDI (Universal Description, Discovery and
Integration), 14-1
API, 14-3
UDDI Client, 14-4
UDDI registries, 14-1
tModels, 14-5
UDDI Server, 14-3
UDDI servers, 14-3
connecting to, 14-5
V
version, 2-10
Universal Description, Discovery and Integration. See
UDDI
viewing
assoc configuration, 3-15
associations, 3-16
communication settings, 3-4
DIB configuration, 3-26
DSP configuration, 5-7
operation configuration, 3-22
operation statistics, 3-22
schema, 4-4
unrestricted read, 6-41
virtual attributes, 3-40
unavailable link-flag, 3-54
unbind, outgoing connections, 5-5
undefined syntax, 4-6
UNSPSC sample DSA
port number, 2-25
update access, 6-41
W
update error, naming violation, 4-18
update requests, 5-24
wide indexes, 3-31
update-log file, 3-10
upgrading Advantage Ingres, D-4, E-4
X
URL pages, launching of, 11-33
user accounts
suspending, 6-30
users
administrative, 6-12, 6-42
associations, 3-16
conveying authentication, 6-19, 6-20
current, 3-24
defining, 6-12
defining superusers, 6-41
distributed, 6-15
limit in associations, 3-18
managing large numbers, 16-10
maximum number to bind, 3-18
X.435, 4-1
X.500
guard, 5-9, 7-23
information types, 4-2
object class kinds, 4-14
schema, 4-2
tracing, 3-16
X.509 certificates, 6-2
X.520
attribute syntax, 4-6
attributes, 4-5
X.521, object classes, 4-14
Index–15

eTrust Directory Administrator Guide

Transcription

Similar documents

AIRMAN`S INFORMATiON MANUAL

Media Pack - The Directory Group

The 2015 CALED Member Directory will be a stand

NFL Game Pass Walkthrough

Oracle Net Service Name Resolution

55th Reunion - Fresno High School Alumni Association

Current Issue - Deputy Sheriffs` Association of San Diego County

System Architecture Overview

Secure Coding Practices for Middleware