eTrust ™ Directory
Administrator Guide 4.1
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 non- infringement. 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.
This product includes code licensed from RSA Data Security.
2003 Computer Associates International, Inc.
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Contents
Chapter 1: Introduction The Importance of Distributed Directories...... 1-2 Replication ...... 1-2 Distribution ...... 1-2 eTrust Directory Features...... 1-4 Directory Information Storage and Management ...... 1-4 Performance ...... 1-4 Reliability ...... 1-5 Scalability ...... 1-6 Distribution ...... 1-7 Replication ...... 1-8 Security ...... 1-8 Operational Extensions ...... 1-9 Integration ...... 1-9 eTrust Directory Modules ...... 1-10 Other Components of eTrust Directory...... 1-11 DXconsole...... 1-12 The DXserver Process ...... 1-12 The RDBMS ...... 1-13 Configuration Files...... 1-13 DXtools ...... 1-13 Samples ...... 1-14 RDBMS Tools...... 1-15 DXweb Server ...... 1-15
Chapter 2: DXserver Overview DXserver Configuration ...... 2-2 DXserver Directories ...... 2-3 The Config Subdirectories ...... 2-4 File Types ...... 2-5 DXserver Commands ...... 2-6
Contents iii
Command-line Options ...... 2-6 The Initialization File ...... 2-8 Configuration Grouping Files...... 2-9 DXserver Script Language ...... 2-10 Configuration Files ...... 2-10 Command Syntax ...... 2-11 Script Files ...... 2-12 Script File Errors and Debugging...... 2-13 DXconsole ...... 2-14 Configuring DXconsole ...... 2-14 Opening DXconsole...... 2-15 Closing DXconsole...... 2-15 Help Command ...... 2-16 Command Shortcuts ...... 2-16 Databases ...... 2-17 Multiple DSA Processes to One DIT/DIB ...... 2-17 Multiple Directory Databases on One Machine ...... 2-18 Hot Swap ...... 2-18
Chapter 3: General Administration Defining DSAs ...... 3-1 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 Assoc Commands ...... 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 Oper Commands ...... 3-20 Viewing Operation Configuration...... 3-21
iv eTrust Directory Administrator Guide
Viewing Operation Statistics ...... 3-22 Concurrent Operations ...... 3-22 Administration Limits ...... 3-23 Operational Attributes...... 3-23 Access Controls ...... 3-23 Read Only...... 3-24 Abandoning Operations ...... 3-24 The Directory Information Base ...... 3-25 Viewing DIB Configuration ...... 3-26 Database Name ...... 3-26 Alias Integrity ...... 3-27 Counting Entries ...... 3-27 Limit List...... 3-28 Limit Search ...... 3-28 Indexing Options ...... 3-28 Password Storage ...... 3-29 DXcache ...... 3-30 Configuring DXcache...... 3-30 Viewing DXcache Configuration ...... 3-32 Keeping DXcache Synchronized with the Database ...... 3-32 Which Searches Are Handled By Dxcache ...... 3-33 Running eTrust Directory in Cache-Only Mode ...... 3-33 Virtual Attributes ...... 3-35 Dynamic Groups...... 3-35 Class of Service ...... 3-38 DSA Knowledge Flags ...... 3-43 DSA Flags ...... 3-43 Trust Flags ...... 3-44 Link Flags ...... 3-45 DXmanager Portal ...... 3-46 Connecting to the Portal ...... 3-46
Chapter 4: Schema Definition Configuring Schema ...... 4-2 Grouping Schema ...... 4-2 Managing Schema ...... 4-3 Schema Commands ...... 4-3 Viewing Schema ...... 4-4 Schema Prefixes...... 4-4 Attributes ...... 4-5 Attribute Syntaxes ...... 4-6
Contents v
Attribute Checking ...... 4-7 Attribute Sets ...... 4-8 Attribute Names ...... 4-9 Object Classes...... 4-10 Object Class Kind...... 4-10 Object Class Checking ...... 4-11 Object Class Storage ...... 4-12 Name Bindings ...... 4-14 Name Binding Checks ...... 4-14 Name Bindings and Structural Object Classes ...... 4-15 Name Bindings and Aliases ...... 4-15 Considerations for Schemas that Do Not Support Name Binding ...... 4-15 Defining Local Schema...... 4-16
Chapter 5: Distribution and DSP Managing DSP ...... 5-2 DSP Commands ...... 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-9 Configuring a DXserver ...... 5-9 Proxy DSAs ...... 5-10 Configuring Another DXserver ...... 5-11 Configuring Alternative Network Addresses ...... 5-11 Configuring a Third-party DSA ...... 5-12 DXlink ...... 5-12 Configuring Multiple Local DSAs ...... 5-13 Configuring a Domain of DXservers ...... 5-14 A Domain of DXservers ...... 5-14 Sharing DXserver Configuration ...... 5-15 Configuring a First-level DSA...... 5-15 Configuring a Router DSA ...... 5-16 Transparent Routing ...... 5-16
vi eTrust Directory Administrator Guide
Configuring a Relay DSA ...... 5-17 Caching Entries from Subordinate DSAs ...... 5-17 Alternative DSAs ...... 5-18 DSA Failover ...... 5-19 Load-sharing DSAs ...... 5-20 Query Streaming...... 5-21
Chapter 6: Security SSL Encryption ...... 6-2 Secure Socket Layer ...... 6-2 DXserver and SSLD ...... 6-3 Hardware Security Module ...... 6-3 Configuring DXserver for SSL Operation ...... 6-4 DXserver and SSL Connections ...... 6-4 DXserver Personality Certificates ...... 6-5 Configuring SSLD...... 6-6 Client Encryption ...... 6-8 DSA-to-DSA Encryption (DSP and DISP) ...... 6-8 Authentication ...... 6-9 Setting the Minimum Authentication Level ...... 6-9 Anonymous Authentication...... 6-9 Simple Authentication...... 6-10 SSL Authentication...... 6-11 Distributed User Authentication...... 6-13 DSP Simple Authentication ...... 6-13 DSP SSL Authentication ...... 6-15 DISP Authentication ...... 6-15 Bypassing Mutual Authentication ...... 6-16 Conveying User Authentication ...... 6-16 DSP Link Authentication ...... 6-17 Access Controls...... 6-19 Administrative Areas and Domains...... 6-20 Access Control Policy and Rules ...... 6-20 Static Access Controls ...... 6-22 Role-based Access Controls ...... 6-32 Secure Proxy ...... 6-33 Dynamic Access Controls ...... 6-34 Viewing Access Controls ...... 6-36 Password Management...... 6-38 Setting the Life Span of Passwords...... 6-38 Setting Up Incorrect Password Handling ...... 6-39
Contents vii
Setting Up the Password Change Rules ...... 6-39 Password Reset ...... 6-40 Other Security Features ...... 6-41 Password Protection ...... 6-41 Impersonation Protection...... 6-41 Access-controlled Routing...... 6-42 Trust Flags...... 6-42 Audit File...... 6-42 Read-only DSA...... 6-43 DXconsole ...... 6-43 Access Controls and Aliases ...... 6-43
Chapter 7: Replication Replication Overview...... 7-2 Multiwrite Overview ...... 7-2 DISP Overview...... 7-2 DXtools Overview ...... 7-2 Replication Concepts ...... 7-3 Distribution Versus Replication ...... 7-4 Multimaster Versus Master-slave Replication ...... 7-4 Real Time Versus Write-behind Replication ...... 7-4 Replay-based Versus State-based Replication...... 7-5 Multiwrite Replication ...... 7-6 Configuring Multiwrite ...... 7-6 Multiwrite Queues ...... 7-7 Asynchronous Multiwrite Behavior ...... 7-8 Multiwrite Recovery With DISP...... 7-9 Miscellaneous Multiwrite Topics ...... 7-11 Manually Resynchronizing Databases ...... 7-12 DISP Replication ...... 7-13 Configuring a DISP Responder ...... 7-13 DISP Agreements...... 7-13 Setting DISP Agreements...... 7-14 Viewing DISP Agreements ...... 7-15 Shared DISP Configuration ...... 7-15 Manual Initiation of DISP ...... 7-16 Shadow DSAs ...... 7-16 DISP Routing ...... 7-16 Manual Synchronization of Replicas Using DB Tools ...... 7-17 Scenario ...... 7-17 Method ...... 7-17
viii eTrust Directory Administrator Guide
Procedure ...... 7-17
Chapter 8: LDAP and DXlink LDAP Clients...... 8-1 LDAP Port ...... 8-2 LDAP Schema ...... 8-2 Handling of LDAP Strings ...... 8-2 Schema Publishing...... 8-3 Integrating Other LDAP Servers...... 8-4 User Credentials on DXlink Binds ...... 8-5 Prefix Mapping ...... 8-6 Working with Microsoft Exchange ...... 8-7
Chapter 9: Monitoring the Directory General Monitoring ...... 9-1 DXconsole...... 9-2 Log Files ...... 9-2 Databases ...... 9-2 Disk Space ...... 9-2 Using the Administration Daemon ...... 9-3 Connecting to DXadmind ...... 9-3 DXadmind Manager ...... 9-3 Advantage Ingres Database Plug-in Library ...... 9-4 Administration Log ...... 9-5 eTrust Directory Plug-in Library...... 9-5 Policy Compliance Plug-in Library ...... 9-6 SNMP and the Directory Monitoring MIB ...... 9-7 Configuring the SNMP Agent ...... 9-8 SNMP Monitor Utility ...... 9-8 Configuring the SNMP Trap Destination ...... 9-10 CMIP and X.700 Management...... 9-12 Configuring the CMIP Agent...... 9-12 CMIP Monitor Utility...... 9-12
Chapter 10: Using DXconfig Connecting to DXconfig ...... 10-1 The DXconfig Browser ...... 10-2 Packages ...... 10-3 Naming Packages ...... 10-3
Contents ix
Displaying All Packages...... 10-4 Adding a Package ...... 10-4 Adding Comments ...... 10-4 Editing a Package...... 10-5 Adding an Item ...... 10-6 Item Editor ...... 10-7 DXservers ...... 10-8 Adding a DXserver ...... 10-8 Submitting Changes ...... 10-9
Chapter 11: Using DXtools DB Tools ...... 11-2 Creating a DSA: dxnewdsa ...... 11-3 Creating a Database: dxnewdb...... 11-4 Extending a Database: dxextenddb ...... 11-4 Destroying a Database: dxdestroydb ...... 11-5 Emptying a Database: dxemptydb...... 11-5 Backing Up a Database: dxbackupdb ...... 11-6 Restoring a Database: dxrestoredb ...... 11-7 Tuning a Database: dxtunedb ...... 11-8 Managing Indexes: dxindexdb ...... 11-9 Displaying Database Statistics: dxstatdb ...... 11-12 Listing Existing Databases: dxlistdb ...... 11-13 Adding a Database User: dxadduser...... 11-13 Deleting a Database User: dxdeluser...... 11-13 Loading a Database: dxloaddb ...... 11-14 Dumping a Database: dxdumpdb ...... 11-16 Granting Access to a Database: dxgrantdb ...... 11-17 Upgrading Previous Versions of a Database: dxupgradedb ...... 11-17 Initializing Multiwrite DISP Recovery: dxdisp...... 11-18 LDIF Tools ...... 11-18 CSV Source Data ...... 11-19 Template Files...... 11-19 LDIF Files ...... 11-21 Converting CSV Data to LDIF Format: csv2ldif ...... 11-21 Sorting an LDIF File: ldifsort...... 11-22 Calculating the Change Between Two LDIF Files: ldifdelta ...... 11-24 DAP Tools...... 11-26 Common Command Options ...... 11-26 Searching a Directory: dxsearch ...... 11-28 Reporting on Certificate and CRL Indexes: dxcert...... 11-29
x eTrust Directory Administrator Guide
Modifying a Directory: dxmodify...... 11-30 Loading Binary Files: dxmodify ...... 11-32 Renaming a Directory Entry: dxrename ...... 11-33 Deleting a Directory Entry: dxdelete ...... 11-34 Bulk Loading Options ...... 11-34 SCHEMA Tools...... 11-35 Extracting Schema in LDIF Format: dxschemaldif ...... 11-36 Converting Schema from LDIF to DXserver Format: ldif2dxc ...... 11-37 Converting Schema from DXserver Format to DXtools Format: dxschematxt...... 11-41 Directory Administration Tools ...... 11-42 Checking DSA configuration: DXsyntax ...... 11-42
Chapter 12: Using JXplorer The JXplorer Browser ...... 12-2 Menu Bar ...... 12-3 Button Bar...... 12-5 Quick Search Bar...... 12-6 Directory Tree Display ...... 12-7 Entry Display...... 12-8 Browsing a Directory...... 12-10 Connecting to a Directory...... 12-10 Reading Schema ...... 12-11 Navigating the Directory Tree ...... 12-12 Refreshing Entries...... 12-12 Searching ...... 12-12 Exploring Schema...... 12-15 Displaying an Entry ...... 12-16 Editing the Directory ...... 12-17 Directory Tree Operations ...... 12-17 Modifying Attributes in an Entry ...... 12-19 Using Binary Values...... 12-22 Adding a New Entry ...... 12-24 Submitting an Entry to the Directory ...... 12-25 Using LDIF Files ...... 12-26 Importing and Exporting an LDIF File ...... 12-26 Using an LDIF File Without a Directory ...... 12-26 Binary Values in LDIF Files ...... 12-27 Using SSL and SASL ...... 12-27 Server Authenticated SSL ...... 12-28 Client Authenticated SSL and SASL...... 12-28 Managing Certificates and Keystores...... 12-29
Contents xi
Online Help ...... 12-29 Browser Configuration...... 12-29 View Menu ...... 12-30 Options Menu...... 12-30 Creating HTML Viewing Templates ...... 12-35 Configuring Tree Icons...... 12-36 Extending the Java Binary Editor...... 12-36 Plug-in Entry Editors ...... 12-36 Internationalization...... 12-37 Troubleshooting ...... 12-37 Other LDAP and Directory Resources ...... 12-37
Chapter 13: Using JXweb Connecting to JXweb ...... 13-1 Connecting to a Directory ...... 13-2 The JXweb Environment ...... 13-2 Online Help ...... 13-3
Chapter 14: Deploying a Directory Directory Design ...... 14-2 Requirements Analysis...... 14-2 Service Definition...... 14-2 Schema Design ...... 14-2 Directory Enabled Applications ...... 14-3 Namespace Design ...... 14-3 Security ...... 14-3 Dimensioning ...... 14-4 Performance ...... 14-4 Availability ...... 14-4 Synchronization ...... 14-5 Scalability and Distribution...... 14-5 Complexity ...... 14-5 Operations and Practices ...... 14-5 Management ...... 14-5 Monitoring ...... 14-6 Capacity Planning ...... 14-6 Backup and Restore...... 14-6 Journaling ...... 14-7 Database Tuning ...... 14-7 Change Control ...... 14-8
xii eTrust Directory Administrator Guide
Upgrades ...... 14-8 Maintenance...... 14-8 Troubleshooting ...... 14-9 Optimizing Performance...... 14-9 Managing Large Numbers of Users ...... 14-9 Managing Large Numbers of Entries ...... 14-10 Limiting Users ...... 14-10
Chapter 15: UDDI Registry eTrust Directory UDDI Registry ...... 15-2 Connecting to UDDI Web Client ...... 15-3 Connecting to UDDI Servers ...... 15-3 Searching the Repository ...... 15-4 Publishing to the Repository ...... 15-4 Publishing a Service ...... 15-4 Using tModels ...... 15-5
Appendix A: The DUA Command Set Connecting and Disconnecting ...... A-2 Connecting with the Management Console ...... A-2 Configuring the Scripting DUA...... A-3 Disconnecting From the DSA...... A-3 Inquire Services ...... A-4 Read Service...... A-4 Compare Service ...... A-5 List Service ...... A-5 Search Service ...... A-6 Abandon Service...... A-8 Update Services ...... A-9 Add Service ...... A-10 Remove Service ...... A-11 Modify Service...... A-12 Modify-DN Service ...... A-13 Common Arguments...... A-14 Time Limit ...... A-14 Other Controls...... A-15 Entry Information Selection ...... A-15 Operational Attributes...... A-16 Aliases...... A-17 Reading an Alias ...... A-18
Contents xiii
Adding an Alias ...... A-18 Deleting an Alias ...... A-19 Modifying an Alias ...... A-20
Appendix B: DXserver Command Language Command Categories...... B-1 Clear Commands...... B-2 Close Commands ...... B-2 Set Commands ...... B-3 set admin-user Command Parameters ...... B-9 set agreement Command Parameters ...... B-10 set attribute Command Parameters ...... B-11 set dsa Command Parameters ...... B-12 set name-binding Command Parameters...... B-14 set object-class Command Parameters ...... B-15 set protected-items Command Parameters ...... B-16 set public-user Command Parameters ...... B-16 set reg-user Command Parameters ...... B-17 set super-user Command Parameters ...... B-18 Source Commands ...... B-19 Trace Commands ...... B-20
Appendix C: Messages and Logs UNIX System Error Log...... C-1 Windows Event Log ...... C-1 DXserver Logs ...... C-2 Advantage Ingres Logs ...... C-2 DXserver Alarm Messages ...... C-3 DXserver Warning Messages ...... C-5 Alias Errors...... C-6 Service Errors ...... C-7 Advantage Ingres Errors ...... C-8
Appendix D: Installing DXserver for Windows Installation Overview...... D-1 Check System and Space Requirements...... D-2 System Requirements ...... D-2 Space Requirements ...... D-3 Install eTrust Directory Components ...... D-5
xiv eTrust Directory Administrator Guide
Ports Used During DXwebserver Installation ...... D-7 Run the Sample Scripts ...... D-8 Democorp ...... D-8 UNSPSC ...... D-9 Router ...... D-9 Silent Installation ...... D-10 ADDLOCAL Values...... D-10 Additional arguments ...... D-11 Optional Silent Installation Examples ...... D-12 Embedded Installation ...... D-12 Uninstalling eTrust Directory After an Embedded Installation...... D-13 Install the Technology Previews (Optional)...... D-13 DSML...... D-13 UDDI ...... D-13 Upgrading Advantage Ingres ...... D-14
Appendix E: Installing DXserver for UNIX Installation Overview ...... E-1 Check System and Space Requirements ...... E-2 System Requirements ...... E-2 Space Requirements ...... E-3 Verify CD-ROM Accessibility ...... E-4 Verify Accessibility From Local CD-ROM Drive...... E-4 Verify Accessibility From Remote CD-ROM Drive ...... E-4 Dismount a Remotely Mounted CD-ROM File System ...... E-5 Eject CD...... E-5 Stop Sharing and Eject the CD-ROM ...... E-5 Install eTrust Directory ...... E-6 Step 1 – Run dxsetup ...... E-7 Step 2 – Accept the License Agreement ...... E-8 Step 3 – Set Up UNIX Kernel (for Solaris) ...... E-8 Step 4 – Set Up DXserver ...... E-9 Step 5 – Set Up Documentation ...... E-10 Step 6 – Set Up Advantage Ingres...... E-10 Step 7 – Set Up Time Zone ...... E-12 Step 8 – Set Up JXplorer ...... E-12 Step 9 – Set Up DXwebserver...... E-13 Step 10 – Set Up JRE ...... E-14 Step 11 – Install the Reboot Scripts ...... E-14 Step 12 – Set Up the Sample Directories ...... E-14 Silent Installation ...... E-16
Contents xv
Step 1 – Dxserver Setup ...... E-17 Step 2 – Advantage Ingres Setup ...... E-17 Example: Install Dxserver only...... E-17 Embedded Installation ...... E-18 Uninstalling eTrust Directory After an Embedded Installation ...... E-18 Install the Technology Previews (Optional) ...... E-19 DSML ...... E-19 UDDI ...... E-19 Upgrading from a Previous Version...... E-20 Upgrading Advantage Ingres ...... E-20
Appendix F: Installing Directory GUIs Installing JXplorer ...... F-2 Windows Installation ...... F-2 UNIX Installation...... F-3 Installing DXconfig, DXmanager, JXweb, and UDDI Web Client ...... F-4 Windows Installation ...... F-4 UNIX Installation...... F-5 Installing DXplorer ...... F-6
Appendix G: Tailoring the RDBMS Changing the Default Page Size...... G-2 Increasing the Number of Cache Pages ...... G-3 Increasing the Number of Database Connections ...... G-4 Step 1. Increase the Shared Memory Maximum (Optional) ...... G-4 Step 2. Increase the Database Connection Limit ...... G-5 Other Customizations ...... G-5
Appendix H: Licenses for Third-Party Products Apache Tomcat and others ...... H-1 General License (covers Tomcat, Axis, CLUtil, Log4j, Xalan, Xerces, XSLTC) ...... H-1 Cocoon ...... H-2 Commons ...... H-3 Velocity ...... H-4 IBM UDDI4j ...... H-6 OpenLDAP ...... H-11 OpenSSL ...... H-12 Original SSLeay License...... H-14 Sun Microsystems, Inc...... H-15
xvi eTrust Directory Administrator Guide
DSML and LDAP Extensions ...... H-15 JAVA 2 Runtime Environment ...... H-19 JavaHelp ...... H-25 Java Web Services Developer Pack ...... H-29 TeraTerm ...... H-33
Index
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 high- capacity 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 The Importance of Distributed Directories
The Importance of Distributed Directories
Two major terms are used in the design concepts of directory systems— distribution and replication.
Replication
Replication occurs when the same directory entry namespace exists on different servers. One directory services replicated across three servers
Namespace 1 Namespace 2 Namespace 3
Replication is important for recovery and sometimes for performance. Replication involves copying data. Whenever data is copied, you must ensure that the copies are synchronized. This can make the cost of developing and maintaining replicated systems expensive, and you should weigh it against the benefit of recovery (in the event of failure) and performance.
Distribution
Distribution occurs when interconnected directory servers have different entry namespaces, but they operate as one logical directory service.
Namespace 1 One directory service distributed across three namespaces
Namespace 2 Namespace 3
1–2 eTrust Directory Administrator Guide The Importance of Distributed Directories
Distribution is important for scaling. Similar to the World Wide Web, distribution lets any number of servers share and maintain their own information. However, unlike the World Wide Web, directory servers have a server-to-server protocol (DSP), which enables them to cooperate to provide distributed queries and a unified view of the whole Directory Information Tree (DIT).
Note: LDAP is a client-to-server protocol designed for accessing directories; it is not a server-to-server protocol. LDAP-only servers cannot cooperate with each other to perform distributed queries.
Replication and distribution are distinct elements of directory system design. Both impact the performance, capacity, and reliability of the system. In addition, the engineering mechanisms in the eTrust Directory product (that support the directory information model, distribution and replication) ensure these performance, capacity, and reliability functions are world-class.
Introduction 1–3 eTrust Directory Features eTrust Directory Features
Directory Information Storage and Management
The eTrust Directory implements an X.500/LDAP object-oriented directory information model and its architecture is built on an industrial-strength Relational Database Management System (RDBMS). It achieves performance and efficiency using unique designs and algorithms, which are protected by a number of worldwide patents.
Performance
The eTrust Directory performance typically provides sub-second response times over multi-million-entry databases on low-cost UNIX or Windows machines.
eTrust Directory achieves high-speed searching and retrieval (from the database engine) through a unique metadata design in which all objects, attributes, and values are automatically indexed. The DSA uses sophisticated algorithms to transform X.500/LDAP requests into highly efficient Structured Query Language (SQL) queries. These SQL queries, in turn, benefit from the indexing systems, query optimizer and the caching of the underlying RDBMS.
The design gives eTrust Directory the following performance characteristics:
■ Performance is independent of the size of the directory, the depth of the DIT, the number of attributes per entry, or the types of data in the directory.
■ Under usual operating conditions, complex searching, alias navigation, distribution, and security (applying access control information) minimally affect performance.
■ Performance is linear and only dependent on the amount of data actually retrieved.
■ Start or restart times, for example, after power failures are only a few seconds (excluding OS or RDBMS restarts) because the directory information is always held in the underlying database. This information (the complete Directory Information Base) does not need to be loaded as memory-resident before use.
More information about eTrust directory is available from Computer Associates website at http://www.ca.com/solutions/enterprise/etrust.
1–4 eTrust Directory Administrator Guide eTrust Directory Features
Reliability
eTrust Directory is able to achieve “industrial strength” data management by leveraging an underlying RDBMS. The RDBMS provides the following features:
■ Locking, database transaction logging, and forward recovery processes
■ Full transaction management, which ensures data integrity
■ Database resident information that enables very fast restart times after power failure
■ Directory namespace (DIT) online backup and recovery and online tuning without service interruptions
To support 24 x 7 operations, eTrust Directory supports the following operational features:
■ Hot Swap of databases—Organizations may require the testing of their development directory services in the operational environment. The eTrust Directory can switch underlying database images (the DIT) without disconnecting directory clients. Cutovers can be achieved in milliseconds without affecting online users.
■ Network Failover—The eTrust directory has the ability to transparently use alternate network addresses to swap to a different network link.
■ DSA Failover—The eTrust directory has the ability to transparently use alternate directory servers (DSAs) if a given DSA is unavailable.
Introduction 1–5 eTrust Directory Features
Scalability
DXserver is scalable at the database, process and network levels. It has the following characteristics:
■ Its database can be very large. This means that as the DIT size increases, the server does not require more memory.
■ More than one directory server DSA process can access a single directory database. This enables support for a very large number of concurrent users. Separate processes permit the load balancing of directory requests across multiple services. This is useful for bulk loading data or for streaming high demand users, such as many receptionists from ad hoc users performing complex searches.
■ The eTrust directory server process supports multiple-CPU (symmetric processor or loosely-coupled processor) hardware through the use of a threaded database server.
■ The eTrust directory can be distributed to support millions of entries across a number of DSAs, either on the same machine or different machines.
■ Distribution can be used to link together as many DSAs as required to support a potentially unlimited amount of entries.
1–6 eTrust Directory Administrator Guide eTrust Directory Features
Distribution
For distributed directory operations, the eTrust directory incorporates dedicated processes that deal with directory protocol routing based on namespace knowledge, operations being performed, and the roles of the directory servers attached. For example, directories can be “read only", "alternates" or "masters". For these functions the DXserver incorporates the following unique features:
■ Shortest-path routing—If required, a DSA can use its knowledge of other DSAs within the Global DIT to connect directly rather than use superior or sub-ordinate references.
■ Parallel distributed searching—A DSA can multi-chain its searches to any number of subordinate DSAs whose searches are then performed in parallel.
■ Query streaming—DSAs can be marked for a particular purpose, such as simple searches or read-only operations. This mechanism can be used to stream directory operations of different types (read, search, update, etc) to dedicated DSAs.
■ Load sharing—By configuring multiple DSAs with the same namespace prefix and DIT data (as replicas) it is possible to increase directory service performance by load sharing search requests over a number of DSAs possibly on different systems.
■ DXlink—The feature provides the ability to incorporate LDAP servers into a distributed service backbone. When DXserver needs to chain a request to an LDAP server it converts the standard DSP protocol request and response by building a suitable LDAP request for the LDAP server and then chains the result (the LDAP response) back to the client.
■ Namespace Prefix mapping—The feature provides the ability to map any existing DSA server with a given naming context into any part of the DIT. In the context of DXlink, DXserver acts as a gateway translating reference in the DXserver DIT into references within the LDAP server's namespace. This ability is generally known in the industry as creating a virtual directory.
Introduction 1–7 eTrust Directory Features
Replication
For distributed directory operations, the eTrust Directory server/service supports a number of replication schemes:
■ X.500 DISP—The X.500 standards based method of replication.
■ Multiwrite DSP—Updates to one DSA are also written (in parallel) to one or more peer DSAs.
■ Multiwrite DISP—Combines the efficiency of multiwrite with the reliability of DISP recovery.
■ Tools-based Replication—The eTrust Directory provides a number of database and LDIF tools (dxdumpdb, ldifsort, ldifdelta, dxmodify, dxloaddb) that facilitate tools based replication, external data synchronization solutions and online reconciliation.
Security The eTrust Directory supports a number of advanced security features:
■ Simple authentication with encrypted passwords
■ Secure Sockets Layer (SSL) encryption on all protocols
■ Strong authentication using SSL and certificates
■ 1993 X.500 access controls over subtrees, entries and attributes
■ Access controls applied at the directory service (domain) level
■ Access control rules that simplify the specification, testing, and management of complex security schemes
■ Dynamic access controls enable delegated rights within a DSA (often used by authorization systems)
■ Role-Based access controls enable rules to be defined based on a role
■ Security policies using access control rules
■ Distributed authentication
■ Mutual authentication between DSAs, including network address validation
1–8 eTrust Directory Administrator Guide eTrust Directory Features
Operational Extensions
The eTrust Directory incorporates a range of capabilities outside that of the X.500 and LDAP standards. Generally these capabilities are provided as operational features that are necessary for provisioning and deploying of online, large scale distributed directory information systems. These include:
■ An X.500 command-line interpreter with optional scripted input that you can use for rapid prototyping and testing without requiring programming.
■ Administrative controls to manage users, associations, and operations including time limits, size limits, connection limits and flow control.
■ Data management extensions including alias integrity, object class pruning and using searches to count entries by returning a special count attribute.
■ Dynamic configuration of data types, schema rules, security, and knowledge information.
■ Support for extremely large data types (Binary Large Objects or BLOBs) that enables the directory to store multimedia attributes, including images (such as JPEG).
■ Intelligent storage and searching of undefined attribute syntaxes, so that new syntaxes can be implemented for new directory applications without modifying the software in the DSA.
■ Transparent hot swap connection and disconnection of different databases (holding different DITs) while the DSA is operational.
■ A DSA can be started without its database when you want it to act as a Directory (protocol) Router or DSP proxy. (For example, these features are relevant for directory enabled firewall applications).
■ Engineering traces and diagnostics at various levels, and separate log files for statistics, queries, traces and audit information are provided.
Integration
The eTrust Directory has been successfully integrated into other eTrust products, for example, eTrust OCSPro, eTrust PKI, and eTrust Admin, creating a powerful directory backbone.
Users of other products are also integrating with eTrust Directory, via the Industry Standard LDAP Application Programming Interfaces (APIs).
Introduction 1–9 eTrust Directory Modules eTrust Directory Modules
The eTrust Directory includes the following modules:
Module Purpose DXadmind The eTrust Directory administration server, used to monitor all DXservers configured on the machine DXconfig The web-based eTrust Directory configuration editor, used to configure your DXservers, and accessed from DXmanager. DXconfig allows remote configuration of DXserver through the Web. DXconsole The eTrust Directory DXserver debugging console, used to control and monitor DXserver, and accessed from DXmanager. Note: The console is configured for local echo, and to send CR+LF for a new line and DEL for the Delete key. DXlink The DXserver feature that enables LDAP servers to be integrated into an eTrust Directory backbone DXmanager The graphical, web-based, eTrust Directory administration portal. DXmanager allows remote access to a DXserver through the Web. DXserver The high-performance Directory System Agent (DSA) supporting both LDAP (Version 2 and Version 3) and X.500 Directory Access Protocol (DAP) and Directory System Protocol (DSP), with Directory Information Shadowing Protocol (DISP) and multiwrite replication DXtools The flexible set of utilities for importing, exporting, and synchronizing data with external data systems, including a subset of DB tools for managing the Advantage™ Ingres® databases used by eTrust Directory JXplorer A powerful, graphical, Java-based LDAP directory browser and editor. It supports SSL and DSML V2. JXweb The powerful, graphical, web-based, LDAP directory browser and editor. JXweb allows remote access to a DXserver through the Web UDDI Web Client The graphical, web-based, UDDI Registry browser and server. The UDDI Web Client allows you to publish services to a UDDI server and to search for services on a UDDI server through the Web.
1–10 eTrust Directory Administrator Guide eTrust Directory Modules
The following illustrates the relationships between these major components:
The standard eTrust Directory release provides the DSA, script files, DXtools, DB tools, sample utilities, and the Advantage Ingres II RDBMS.
Note: The RDBMS server starts or stops independently of the DSA.
Other Components of eTrust Directory
eTrust Directory includes the following other components:
Component Purpose Configuration files For initialization RDBMS An SQL database that physically stores and retrieves information from disk RDBMS tools Database maintenance tools which are part of the RDBMS Samples Utilities and script files for testing and demonstration
Introduction 1–11 eTrust Directory Modules
DXconsole
DXconsole is a management console, which is used to control the DXserver. It can connect and disconnect at any time to a running DSA. DXconsole supports:
■ Monitoring, tracing, and setting operational parameters ■ Configuring schema, distribution, replication, and security ■ Invoking X.500 service requests (such as read, list, search) ■ Shutting down the directory processes
The console accepts commands interactively from an administrator or from scripted command files. You can find a formal definition of the command language used by the DXconsole in the appendix “DXserver Command Language.”
The DXserver Process
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–12 eTrust Directory Administrator Guide eTrust Directory Modules
The 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
■ Checkpointing 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:
■ Management of databases ■ Tuning and backup of directory data ■ Import and export of directory data ■ Bulk loading databases from a prepared LDIF file ■ Bulk extraction of a database to an LDIF file for comparison ■ LDIF sorting and comparison
For descriptions of these tools, see the chapter Using DXtools.
Introduction 1–13 eTrust Directory Modules
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:
■ dxtype.txt and dxobject.txt for DXplorer
■ 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–14 eTrust Directory Administrator Guide
Chapter 2 DXserver Overview
The eTrust Directory server component is called 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
DXserver Configuration
The DXserver configuration architecture incorporates a set of configuration files placed in named directories. These file directories are shared across all servers to ensure consistency in system operation. This architecture also enables configuration version management because you can store these files in a document or source control system.
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. These configuration files should be managed from a central station. DXserver bin config access autostart database knowledge limits logging replication schema servers settings ssld
doc lib logs samples pid (UNIX only) install (UNIX only)
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.
2–2 eTrust Directory Administrator Guide DXserver Configuration
DXserver Directories bin
This directory holds all binary executables and batch files for the product. config
This directory holds the current configuration set. DXserver always starts with the configuration information stored in this directory. This directory also holds some textual help files for your reference. We recommend that you give read- only permissions to files in these directories to prevent accidental overwriting.
The configuration files are organized into subdirectories, which contain a help file (see The Config Subdirectories in this chapter). doc
This directory contains the eTrust Directory documentation. lib
This directory contains the Application Programming Interfaces (APIs) supplied with eTrust Directory. 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 only available on UNIX platforms. It is for DXserver use only, and contains information about currently running processes. install
This directory is only available on UNIX platforms. It is for DXserver use only, and contains installation files and environment information.
DXserver Overview 2–3 DXserver Configuration
The Config Subdirectories
The config directory contains a number of subdirectories. Each subdirectory contains one or more configuration files, which deal with a component part of the DXserver configuration.
Subdirectory Description access Access control rules. 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.
Tip: For UNIX systems, DXserver uses the /autostart directory to track the servers that must start at the same time as the operating system.
2–4 eTrust Directory Administrator Guide DXserver 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:
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.
DXserver Overview 2–5 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 DXserver for Windows” and “Installing DXserver for UNIX” for information about starting and stopping a DXserver process.
Command-line Options
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, for example:
dxserver init all install serverName Adds serverName to the list of servers to start at system startup, for example:
dxserver install democorp Note: The DXserver start command will implicitly do an install in the Windows environment. remove serverName Removes serverName from the auto-startup list, for example:
dxserver remove democorp
2–6 eTrust Directory Administrator Guide DXserver Commands
Option Meaning start serverName Starts the DXserver serverName, for example:
dxserver start democorp start all Starts all DSAs. For example:
dxserver start all 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. For example:
dxserver status stop serverName Stops the DXserver serverName, for example:
dxserver stop democorp stop all Stops all DSAs, for example:
dxserver stop all version Displays version information, for example:
dxserver version
DXserver Overview 2–7 DXserver Commands
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/";
2–8 eTrust Directory Administrator Guide DXserver Commands
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 Group 2
commands A 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.
DXserver Overview 2–9 DXserver Script Language
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”)
■ Commands dealing with DSAs and distribution (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”)
2–10 eTrust Directory Administrator Guide DXserver Script Language
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=
LDAPv3 has standardized on UTF-8 for internationalization. An example, using UTF-8, is now: mod-entry-req entry=
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.)
DXserver Overview 2–11 DXserver Script Language
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";
2–12 eTrust Directory Administrator Guide DXserver Script Language
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 has facilities to monitor users, modify administrative controls, and perform actions.
DXconsole also includes a powerful co-resident directory client (DUA) Command-Line Interface (CLI), which you can use to enter user queries for diagnostic or prototyping tasks. (See the appendix “DXconsole DUA.”)
For a complete summary of all console commands, see the appendix “DXserver Command Language.”
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 Wi nd o w DSA
To enable DXconsole, you must define the console port in the knowledge file of the DSA. (See Defining DSAs in the chapter “General Administration.”
Enable Locally To enable DXconsole locally, use the following command: set dsa = { ... console-port = port_number ... };
Enable Remotely To enable DXconsole remotely, use the following command: set dsa = { ... remote-console-port = port_number ... };
2–14 eTrust Directory Administrator Guide DXconsole
Specify Console To provide security, you can specify a console password. When this is set, the Password user is prompted for a password before a connection is made. To specify a password, use the following command: set dsa = { ... console-password = password_string ... };
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.
Only one console session can be active at any one time, even if both the console- port and remote-console-port are set.
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.
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:
The telnet session closes automatically when the DSA shuts down.
DXserver Overview 2–15 DXconsole
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”.
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 =
You can execute it from DXconsole using the command: dsa> !list;
2–16 eTrust Directory Administrator Guide Databases
Databases
eTrust directory comprises 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. (See Defining DSAs in the chapter General Administration).
DXserver Overview 2–17 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 You can change the database name while the DSA is active without Name While DSA disconnecting or disrupting directory clients, using the following command: Active 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–18 eTrust Directory Administrator Guide
Chapter 3 General Administration
This chapter describes the commands you use to set up and maintain the general behavior of DXserver.
Defining DSAs
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.
General Administration 3–1 Defining DSAs
The set dsa command has the following format: set dsa serverName = { prefix =
Important! You must declare the parameters in the order shown. Only prefix, dsa- name, and address are mandatory.
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,
3–2 eTrust Directory Administrator Guide Defining DSAs
Parameter Value 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 the management console port address and the remote console port address is 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 Flags in this chapter for more information. trust-flags (Optional) Comma-separated list of trust flags; see DSA Flags in this chapter for more information. link-flags (Optional) Comma-separated list of link flags; see DSA Flags in this chapter for more information.
General Administration 3–3 Defining DSAs
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, is only meaningful to the DXserver; no other server will use it.
Example DSA The following is an example of a DSA configuration: Configuration set dsa DemoCorp = { prefix =
address = tcp Eagle port 19389
snmp-port = 19389 console-port = 19390 ssld-port = 1112
auth-levels = anonymous, clear-password, ssl-auth
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 = [email protected] snmp-name = democorp snmp-location = http://www.ca.com
3–4 eTrust Directory Administrator Guide Alarms, Traces, and Logs
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 types 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 In the DSA, the trace command controls the amount of tracing that is sent to the DXconsole and trace-log file (if open). Tracing provides debugging information and analyzes service requests. By definition, it does not control what is logged to the summary, query, and stats logs. The following trace options are supported:
General Administration 3–5 Alarms, Traces, and Logs
Trace Option Meaning alert Displays authentication errors. cert Displays certificate operations. connect Displays connections. 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. 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.
3–6 eTrust Directory Administrator Guide Alarms, Traces, and Logs
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.
Protocol Tracing
Low-level protocol can be traced. This tracing is only for debugging purposes. Enable protocol tracing by using the command: set trace = stack;
The protocol trace is written to the trace log, if open.
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. Busy Displays the percentage of the last minute the DSA is busy. Ops Displays the number of operations processed in the last minute.
General Administration 3–7 Alarms, Traces, and Logs
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;
The commands are usually defined in the configuration file (.dxc) in the logging directory; however, they are often entered manually on DXconsole.
3–8 eTrust Directory Administrator Guide Alarms, Traces, and Logs
Log Types
DXserver supports the independent log types listed in the following table.
The alarm log is always open when a DSA is running. All other logs can be opened and closed with the set and close commands.
Log Type Purpose Description alarm-log Records alarms. ■ The alarm log is always open when a DSA is running.
■ It has a default value of serverName_alarm.log.
■ It cannot be closed with the close command.
■ All alarms are written to the alarm log, regardless of the tracing level set or whether a DXconsole is open. alert-log Records all ■ The alert log is only written if it has been opened with the set authorization alert-log command. Writing to the alert log is not affected by the errors. 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. cert-log Records specific ■ The cert log is only written if it has been opened with the set cert- certificate log command. Writing to the certificate log is not affected by the operations. 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.
■ It is time and date stamped, and a new one is written daily. connect-log Records all ■ The connect log is only written if it has been opened with the set released connect-log command. Writing to the connect log is not affected by connections. the trace setting.
■ When a connect log is open, the system writes a line for each connection made when the connection is released.
■ It is time and date stamped, and a new one is written daily.
General Administration 3–9 Alarms, Traces, and Logs
Log Type Purpose Description query-log Records search ■ The query log is only written if it has been opened with the set activity. query-log 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.
■ It is time and date stamped, and a new one is written daily. stats-log Summarizes ■ The stats log is only written if it has been opened with the set operational stats-log command. Writing to the stats log is not affected by the statistics. 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.
■ It is time and date stamped, and a new one is written daily. summary-log Summarizes ■ The summary log is only written if it has been opened with the set daily activity. summary-log command. Writing to the summary log is not affected by the trace setting.
■ 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.
■ It is time and date stamped, and a new one is written daily. trace-log Records ■ When a trace log is open, tracing for all operations is written to the diagnostic trace log. tracing. ■ The level of tracing written to a trace log is dependent on the level of tracing set on the DSA. update-log Records all add, ■ The update log is only written if it has been opened with the set delete, modify update-log command. Writing to the update log is not affected by and rename the trace setting. operations. ■ When an update log is open, the system records all add, modify, rename, and delete operations.
■ It is time and date stamped, and a new one is written daily. warn-log Records errors ■ When a warn log is open, all errors and warnings are written to the and warnings 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'.
■ Each warning or error written to the log is time- and date-stamped, and a new log is written daily.
3–10 eTrust Directory Administrator Guide Alarms, Traces, and Logs
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 DSA’s name. For example: set trace-log = "logs/$S.log";
opens a log file named ../logs/DemoCorp.log when the name of the DXserver is DemoCorp.
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 To inspect the names of each of the enabled log files (including the snmp-log Files file), use the following command: get log;
The following is an example of the output: alarm-log = logs/democorp_alarm.log summary-log = logs/democorp_20010122.log stats-log = logs/democorp_stats_20010122.log trace-log = logs/democorp_trace.log query-log = logs/democorp_query_20010122.log update-log = logs/democorp_update_20010122.log alert-log = cert-log = logs/democorp_cert_20010122.log connect-log = logs/democorp_connect_20010122.log snmp-log = udp eagle port 9999
General Administration 3–11 Alarms, Traces, and Logs
History Files
Most of the log files, once opened, will 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 trace- log 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 eTrust Directory Administrator Guide 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;
Assoc Commands
The following are the parameters of the assoc set command:
Keyword Parameter Description allow-binds Boolean (T/F) When FALSE, new associations are rejected. Use this to perform a graceful shutdown. auth-trap Boolean (T/F) Turns on raising an authentication trap whenever an authentication failure occurs. authentication (min- none, clear-password, The minimum authentication level required on a bind. auth) or ssl-auth credits Integer The maximum number of concurrent operations the DSA processes for each user association. force-encrypt-anon Boolean (T/F) 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 (T/F) 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 (T/F) 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).
General Administration 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 (T/F) 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-max- Integer The number of seconds after which a suspended password suspension 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-alpha 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 (T/F) 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-entry- Boolean (T/F) Turns off automatic checking for the existence of an entry check named by the subject held in the certificate.
3–14 eTrust Directory Administrator Guide Associations
Keyword Parameter Description trap-on-update Boolean (T/F) Turns on raising an SNMP trap whenever an update occurs. trust-sasl-proxy DN The distinguished name of the trusted proxy. use-roles Boolean (T/F) 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
View Association To inspect the current association configuration, use the command: Configuration 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 = 255 max-bind-time = 0 user-idle-time = 3600 allow-binds = TRUE authentication = none credits = 5 trap-on-update = 0 auth-trap = 0 op-error-trap = 0 ssl-auth-bypass-entry-check = FALSE use-roles = FALSE hold-ldap-connections = FALSE password-policy = FALSE
General Administration 3–15 Associations
Viewing Associations
List Currently Bound The assoc module maintains information about all associations. This includes Users 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:
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 To control the association tracing, use the command: Tracing 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 To disable the association tracing, use the command: Tracing trace disable assoc = association_number
Stopping a DSA
Stop a DSA To shut down the DSA with DXconsole, use the command: dsa> shutdown;
3–16 eTrust Directory Administrator Guide Associations
Association Times
Set Maximum Bind User connections can be unconditionally aborted by setting a maximum bind Time 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 allow-binds. 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 clear-password, 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 set allow-binds = true; set min-auth = clear-password;
Disable New Binds 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.
General Administration 3–17 Associations
Aborting Associations
As described previously, to obtain information about currently connected users, use the command: get users;
Abort Associations 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 max- users value can be set to 0 to prevent any users from binding to the DSA.
Set Maximum Idle To increase availability of the directory, you should set the maximum idle time 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 eTrust Directory Administrator Guide Associations
Association Queues
The maximum number of DSA operations in progress at the same time on a per- user 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.
General Administration 3–19 Local Operations
Local Operations
You can manage local operations using the oper module commands. The operation commands have the following form: ■ set parameter = value; ■ get parameter; ■ oper action; The commands are defined in the configuration file (.dxc) in the limits directory.
Oper Commands
The following are the parameters of the operation set command:
Keyword Parameter Description access-controls Boolean (T/F) TRUE enables access controls; FALSE disables access controls. add-oc-parents Boolean (T/F) 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 (T/F) Used to enable or disable dynamic access controls. For more information, see the chapter “Security.” ignore-name-bindings Boolean (T/F) 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 The maximum number of entries that a search or list can keyword none 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 The maximum time (s) that any particular operation can last (a keyword none 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 (T/F) 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 (T/F) For more information, see the chapter “Schema Definition.” return-oc-parents Boolean (T/F) 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. For more information, see the chapter “Security.” use-roles Boolean (T/F) Used to enable and disable role-based access controls. For more information, see the chapter “Security.”
3–20 eTrust Directory Administrator Guide Local Operations
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.
Viewing Operation Configuration
The command: get oper;
shows the current operation configuration values of the DSA. Here is an example of the output of this command: max-local-ops = 200 max-op-time = 120 max-op-size = 200 access-controls = FALSE op-attrs = TRUE read-only = FALSE prune-oc-parents = FALSE return-oc-parents = FALSE add-oc-parents = FALSE dynamic-access-control = FALSE modify-on-add = FALSE ignore-name-bindings = FALSE
General Administration 3–21 Local Operations
Viewing Operation Statistics
List Operation The oper module maintains statistics about all operations. These include events, Statistics services, errors, timeouts, and so forth. The command: get stats;
returns a list of operation statistics.
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 various counters. These counters can be reset using the following command: reset stats;
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;
3–22 eTrust Directory Administrator Guide Local Operations
Administration Limits
To restrict the maximum time an operation can run and the maximum number of entries an operation can return, use the following command: set max-op-time = 20; set max-op-size = 100;
When an operation exceeds either of these limits, an administration limit exceeded error is returned.
Tip: The max-op-size parameter affects only list and search services.
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;
The op-attrs parameter should normally be set on each DSA.
If it is set to true, the DSA will automatically control the creation and updating of operational attributes (for example, last modified time)
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. Therfore an administrator will have the ability to manually update any operational attributes.
Note: If the multi-write-disp-recovery flag is set, then the op-attrs parameter must be set to true.
Access Controls
To control the level of security available on the DSA, use the command: set access-controls = true;
When access controls are enabled and no rules are defined, no entries are visible and it is not possible to view or update the directory. However, it is still possible to load the directory using the bulk load tools. For more information about access controls, see the chapter “Security.”
General Administration 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: dsa-flags = read-only
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 eTrust Directory Administrator Guide The Directory Information Base
The Directory Information Base
To manage the DIB, use the dib commands:
■ set parameter = value; ■ get parameter;
The following are the parameters of the dib set command:
Keyword Parameter Description alias-integrity Boolean (T/F) Enables or disables alias integrity checking. database-name String The name of the database connected to the server. dbconnection A compound value, which consists of a database-name, database-user, and user- password. eis-count-attr An attribute name. index-reverse A list of attributes to which to apply reverse index. index-wide A list of attributes to which to apply wide index. not-searchable A list of attributes that are not to be searched. password-storage The method used to store user passwords. See below for the list of possible values.
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:
Parameter Value dib Shows the DSA configuration values of the directory information processor.
See the appendix “DXserver Command Language” for information about accurate grouping of commands.
General Administration 3–25 The Directory Information Base
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 = demo database-user = fred database-password = ***** eis-count-attr = dxEntryCount limit-search = FALSE limit-list = FALSE password-storage = 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 eTrust Directory Administrator Guide The Directory Information Base
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.
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 =
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:
This search result indicates that there are 98 entries with a surname beginning with "C" in the DemoCorp directory.
General Administration 3–27 The Directory Information Base
Limit List
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
Limit Search
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 persons 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 more information about phonetic match searching, look in Chapter 13 in the User Guide.
Indexing Options
Indexing helps with the search process. When you use indexing options, put them in the database configuration file before the database name definition.
This database configuration file must come after the schema configuration file in the server initialization file. 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. It can be an LDAP or alternate name, but not an OID. The list is comma-separated, for example: set index-reverse = telephoneNumber, faxNumber
Important! If you have indexed the database with DXtools (for example, dxindexdb), ensure that the attributes indexed here match those in the database.
3–28 eTrust Directory Administrator Guide The Directory Information Base
Attributes listed in the not-searchable list cannot appear in the index-wide or index-reverse list.
Note: 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 last command will be indexed.
Important! If DISP replication or multi-write recovery with DISP is set up for a DSA (see the chapter “Replication”), you must not set the createTimestamp, modifyTimestamp, and deleteTimestamp attributes as not searchable.
For information about how to use these options, see the eTrust Directory User Guide.
Password Storage
The DXserver can store user passwords in a number of formats. The formats reported are:
■ oem-hash
■ oem-encrypt
■ sha-1
■ ssha-1
■ crypt
The format oem-encrypt is a reversible format. The default format is sha-1.
The ssha-1 format implements the SHA-1 algorithm used by Netscape, iPlanet, and Sun.
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.
General Administration 3–29 DXcache
DXcache
DXserver’s reliability and distribution capabilities have always made it the first choice for mission-critical systems. However, many low-end LDAP servers have achieved lookup speed using in-memory techniques. DXcache takes this idea one step further to provide even faster lookups whilst still supporting updates, distribution, multi-write, routing, relaying and access controls.
DXcache is designed for lookups on an indexed attribute, for example, sn=smith. Only attributes configured with the cache settings will be loaded into the cache at startup of DXserver. To be directed to the cache, a search must be a simple lookup of an indexed attribute in the cache. Further, the lookup can only request attributes that are in the cache. Therefore, it is important that attributes appearing in the search filter are configured for indexing and that attributes to be returned in the result are configured to be stored in the cache. Searches not conforming to this profile are sent to the database. This means that DXserver’s well-proven superior performance for complex searches is maintained.
DXcache also supports base-object searches. For these, the filter is not required but all the other DXcache conditions must be met.
Configuring DXcache
DXcache is configured with the commands: set max-cache-size = number; set cache-index = index1 [, index2 …]; set cache-attrs = {attr1 [, attr2 …] | all-attributes}; set lookup-cache = boolean;
DXcache Example1 Configuring fast look-ups for attributes commonName and surname
Add the following commands to the end of the servername.dxi file after the database-name directive. set database-name = database; : set max-cache-size = 1000; set cache-index = commonName, surname; set cache-attrs = uid, postalcode; set lookup-cache = true;
Note: DXserver loads the cache as soon as it reads set lookup-cache = true. Therefore, you must specify all settings defining the cache and the database before this command. Put the cache commands at the end of the initialization file.
Restart the DSA: dxserver stop servername dxserver start servername
3–30 eTrust Directory Administrator Guide DXcache
Note: The DSA start time depends on the number and size of the attributes that are to be loaded into the cache.
The following table provides descriptions of the cache settings:
Keyword Parameter Description cache-attrs Attributes 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. cache-index Attributes Sets the attributes to index.. 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 Boolean (T/F) Forces DXcache to load all entries in the database into the cache. DXcache can only handle some searches (those where the filter does not reference an indexed attribute) if it knows that all the entries have been loaded into the cache. See the Which Searches Are Handled By DXcache section following. cache-reverse Attributes Sets the cache to reverse-indexed the attributes. lookup-cache Boolean (T/F) Enables or disables DXcache. max-cache-size Integer 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. It is recommended to set this to around 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.
General Administration 3–31 DXcache
Viewing DXcache Configuration
To monitor the DXcache settings, use the cache module’s get commands at DXconsole.
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
Keeping DXcache Synchronized with the Database
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 cache synchronized. To achieve this, all DXservers which update the database must belong to a multi-write group (see the chapter Replication for more information about multi-write groups.) and have the dsa- flag multi-write-notify set in their knowledge file. The effect of this is that multi- write 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–32 eTrust Directory Administrator Guide DXcache
Which Searches Are Handled By Dxcache
If the cache-load-all flag is set to true, DXcache loads all entries in the database into the cache. This means that DXcache can only handle those searches where the filter does not reference an indexed attribute.
The following table shows what kind of search that Dxcache can handle in different situations:
Attributes in Filter Attributes in EIS Search Indexed Cached The search will be performed in the cache. Cached Cached The search will be performed in the cache, provided that ALL entries are in the cache. No filter Cached The search will be performed provided ALL entries are in the cache. Some attributes in either EIS or filter The search will not be performed in the are not cached cache.
Generally, NOTs can only be processed if all entries are in the cache. To ensure that all entries are loaded into the cache, set the following flag: set cache-load-all = true;
Running eTrust Directory in Cache-Only Mode
A memory-resident version of eTrust Directory can be run by setting the "cache- only = TRUE" flag in the dxserver configuration files.
This flag must come after "lookup-cache = TRUE" because it cannot operate in cache-only mode if lookup-cache has been set to FALSE.
The cache's hash table size is static and is set to twice the number of entries in the database to minimize collisions. In cache-only mode there are zero entries in the database and the hash table size defaults to 5000 entries. A new cache-only-max- entries flag has been introduced to set this to a bigger value.
For example, the following setting would suit a 50,000 entry memory-resident directory: set cache-only-max-entries = 100000
Note: Any database that is defined when running in cache-only mode will be ignored until the cache-only flag is set to FALSE.
General Administration 3–33 DXcache
All database dxtools (like dxloaddb) will not work with a directory in cache-only mode. The cache will have to be loaded by dxmodify or ldapmodify.
The cache-only mode directory does not support multi-write nor DISP.
The cache-only mode directory supports the following services:
■ search (only exact match)
■ read
■ remove
■ add
■ modify
■ compare
■ list
■ modDN
3–34 eTrust Directory Administrator Guide Virtual Attributes
Virtual Attributes
Dynamic Groups
DXserver supports dynamic groups.
Dynamic groups are useful when you know that you will often need to change the membership of a group.
Static and Dynamic Groups
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.
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.
Static groups are useful when the members do not change often, because the member DNs can be searched for within the group entry.
Dynamic groups are useful when the members do change often, because there is no overhead involved in maintaining the group data.
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 base-object search is performed on the entry.
General Administration 3–35 Virtual Attributes
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 contain 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–36 eTrust Directory Administrator Guide 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
General Administration 3–37 Virtual Attributes
Class of Service
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 CoS templates 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.
Class of Service Templates
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–38 eTrust Directory Administrator Guide Virtual Attributes
Example: The Excellent ISP Company
The customers of Excellent ISP can subscribe for 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 Before CoS is introduced, this information is stored in each entry. If there are of Service Virtual one million users, then these attributes appear one million times. If Excellent Attributes ISP increases its fees, then a large global update is required.
Here is an example entry from each class. 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 dn: cn=Mary Chen, o=Excellent ISP, c=US oc: inetOrgPerson oc: excellentISPuser cn: Mary Chen sn: Chen excellentISPmailQuotaMB: 30 excellentISPwebSpaceMB: 30 excellentISPaccessHours: Unlimited excellentISPprice: 29.95 excellentISPextraHoursPrice: 0 excellentISPpackage: Premium
General Administration 3–39 Virtual Attributes
Entries With Class of The shared information in these entries can be moved into a template and Service Virtual replaced with a special attribute and value that indicates which template to use. Attributes
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 oc: excellentISPuser cn: John Smith sn: Smith excellentISPpackage: Standard dn: cn=Mary Chen, o=Excellent ISP, c=US oc: inetOrgPerson oc: excellentISPuser cn: Mary Chen sn: Chen excellentISPpackage: Premium
Class of Service The Excellent ISP company would need to use two templates. The standard- Templates level 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" disposition = default), (type = excellentISPaccessHours value = "15" disposition = override), (type = excellentISPprice value = "19.95" disposition = default), (type = excellentISPextraHoursPrice value = "1.00" disposition = default) } };
3–40 eTrust Directory Administrator Guide 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" disposition = default), (type = excellentISPwebSpaceMB value = "30" disposition = default), (type = excellentISPaccessHours value = "Unlimited" disposition = override), (type = excellentISPprice value = "29.95" disposition = default), (type = excellentISPextraHoursPrice value = "0.00" disposition = default) } };
Configuring Class of Service Virtual Attributes
If the shared attribute values change, then 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 a 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 To use CoS templates with an entry, add the cos-attr attribute to the entry. Entries
General Administration 3–41 Virtual Attributes
Create Class of Templates can be stored in any directory. However, if there are many Service Templates templates, you should store them in separate files in the DXHOME/config/settings directory.
The Class of Service templates use the following syntax:
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 Excellent ISP, discussed 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" disposition : default attribute : excellentISPaccessHours value/s : "15" disposition : override attribute : excellentISPprice value/s : "19.95" disposition : default attribute : excellentISPextraHoursPrice value/s : "1.00" disposition : default
3–42 eTrust Directory Administrator Guide DSA Knowledge Flags
DSA Knowledge Flags
The DXserver uses three sets of flags to alter the operation of a DSA. They provide a simple method to vary the configuration, security, and interoperability of DSAs.
DSA Flags
The DSA flags restrict the type of operations that can be performed on a DSA and the cooperation between DSAs in handling queries.
DSA Flag Description limit-list Disables the list operation on the DSA. See Query Streaming in the chapter Distribution and DSP for more information. limit-search Restricts complex searches or searches with no filter on the DSA. See Query Streaming in the chapter Distribution and DSP for more information. 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 Load Sharing DSAs in the chapter Distribution and DSP for more information. 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 the “Connecting to Active Directory” in Chapter 11 of the User Guide. multi-write Marks a DSA as part of a multi-write group. The DSA should have other peer DSAs, with the same prefix, which are also marked as multi-write. Updates are automatically propagated to all peer DSAs marked as multi-write. See the chapter Replication for more information. multi-write-async Sets the multi-write behavior to asynchronous. See the Asynchronous Multi-write Behavior section in the Replication chapter. multi-write-disp- Allows multi-write queues while DISP is in progress. queue If this is set to true a multi-write master will only start DISP recovery after it has been down or its multi-write queues had reached their limits. In all other cases it just replays its queue content to any peer that was unavailable for a while. multi-write-notify Sends multi-write 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.
General Administration 3–43 DSA Knowledge Flags
DSA Flag Description relay Permits a router DSA to exist without consuming a level of the DIT. See also Configuring a Relay DSA in the chapter Distribution and DSP. shadow Permits a DSA to be updated by DISP, but prevents any other updates (for example, through DAP or LDAP) from occurring. See also the chapter Replication.
Trust Flags
Trust flags let the security on DSAs be relaxed. The more relaxed security depends upon the trust level a DSA has of other DSAs. This is sometimes required to provide interoperability with non-DXserver DSAs.
The following table provides descriptions of the trust flags:
Trust Flag Description allow-check- Permits a DSA, while processing a bind request from a user who is not local, to pass a password 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- Signifies that a DSA treats the originator and authentication level passed in DSP originator 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- Lets the DSA pass an authenticated user request across an anonymous DSP link. downgrading See Authentication in the chapter Security for more information. no-server- Removes the requirement for mutual authentication and permits a link to be set up if credentials 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–44 eTrust Directory Administrator Guide DSA Knowledge Flags
Link Flags
Link flags determine the type of link available between DSAs.
The following table provides descriptions of the 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-ldapv2 The DSA is treated as an LDAP server that supports LDAP 2.0. Other DSAs will send requests to the DSA using DXlink. See Integrating Other LDAP Servers in the Chapter LDAP and DXlink for more 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. See Integrating Other LDAP Servers in the chapter LDAP and DXlink for more 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- It is similar to ssl-encryption, but SSL encryption is not used if the target DXserver is remote on the same host. unavailable Marks a DSA as unavailable. A DSA will not forward requests to a DSA marked as unavailable.
General Administration 3–45 DXmanager Portal
DXmanager Portal
The DXmanager portal is a gateway to eTrust Directory-related web-based applications.
Connecting to the Portal
Connect to the portal as follows:
1. Start your web browser.
2. Enter the following uniform resource locator (URL): http://server:8080/index.html where server is the name of the server hosting the portal.
3–46 eTrust Directory Administrator Guide
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 eTrust Directory Administrator Guide 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:
■ set parameter = value; ■ 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
Schema Example 1 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.
Schema Example 2 Schema Prefix Definition set oid-prefix x500attr = (2.5.4); set oid-prefix x500oc = (2.5.6); set oid-prefix x500aset = (2.5.7); set oid-prefix x500nbind = (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 eTrust Directory Administrator Guide 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.
Schema Example 3 Attribute Definition set attribute x500attr:3 = { name = commonName ldap-names = cn syntax = caseIgnoreString description = "Common Name attribute" };
Schema Example 4 Read-Only Attribute Definition 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 ■ binary ■ boolean ■ caseExactString ■ caseExactStringIA5 ■ caseIgnoreIA5String ■ caseIgnoreList ■ caseIgnoreString ■ distinguishedName ■ facsimileNumber ■ generalizedTime ■ fax ■ guide ■ integer ■ jpeg ■ mhsORAddress ■ mhsORName ■ numericString ■ objectIdentifier ■ octetString ■ postalAddress ■ preferredDelivery ■ presentationAddress ■ printableString ■ telephoneNumber ■ teletexTerminalId ■ telexNumber ■ UTCTime
As more and 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.
4–6 eTrust Directory Administrator Guide Attributes
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
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.
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.
Schema Example 5 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.
4–8 eTrust Directory Administrator Guide Attributes
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 command: set attribute (2.5.4.10) = { name = organizationName ldap-names = o syntax = caseIgnoreString };
then you can use organizationName or the shorter LDAP name, o, in other commands that need to reference the attribute.
LDAP names are most convenient when defining Distinguished Names (DN).
is equivalent to:
Schema Definition 4–9 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 may- contain attributes or attribute sets, and a description.
Schema Example 6 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–10 eTrust Directory Administrator Guide 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, person, and printer.
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–11 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). 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). Note, however, that 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 lowest- level 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: ■ inetOrgPerson ■ organizationalPerson ■ Person ■ top
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: set prune-oc-parents = true; set return-oc-parents = true; set add-oc-parents = true;
4–12 eTrust Directory Administrator Guide Object Classes
The prune-oc-parents setting removes redundant superior object classes when new entries are created.
The return-oc-parents setting replaces the superior object classes to entries retrieved when searching.
The add-oc-parents setting 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-person-organizationalPerson) 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–13 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.
Schema Example 7 Name Binding Definitions set name-binding x500nbind:2 = { name = org-top organization allowable-parent top named-by organizationName }; set name-binding x500nbind:3 = { 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.
Schema Example 8 Advanced Name Binding Definition set name-binding x500nbind:22 = { 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.
4–14 eTrust Directory Administrator Guide Name Bindings
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.
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–15 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.
4–16 eTrust Directory Administrator Guide Defining Local Schema
Schema Example 9 Local Attribute, Attribute Set, Object Class, and Name Binding Definitions set oid-prefix caAttr = (1.3.6.1.4.1.3327.1.4); set oid-prefix caOclass = (1.3.6.1.4.1.3327.1.6); set oid-prefix caAset = (1.3.6.1.4.1.3327.1.7); set oid-prefix caNbind = (1.3.6.1.4.1.3327.1.14); set attribute caAttr:0 = { name = caNearestPrinter syntax = caseIgnoreString description = "Local Printer Attribute" }; set attribute caAttr:1 = { name = caMobilePhone syntax = caseIgnoreString description = "Mobile Phone Attribute" }; set attribute caAttr:3 = { name = caAlternateContact syntax = caseIgnoreString description = "Local Contact Attribute" }; set attr-set caAset:0 = { name = caAttributeSet caNearestPrinter, caMobilePhone, caAlternateContact }; set object-class caOclass:0 = { name = caOrgPerson subclass-of organizationalPerson kind = structural may-contain caAttributeSet description = "CA Organizational Person Object Class" }; set name-binding caNbind:0 = { name = caOrgPerson-org caOrgPerson allowable-parent organization named-by commonName };
Schema Definition 4–17
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.
Distribution and DSP 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:
■ set parameter = value; ■ get parameter; ■ clear dsas; ■ unbind parameter;
DSP Commands
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 chaining-prohibited 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. 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 eTrust Directory Administrator Guide 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.
Distribution and DSP 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.
DSP Example 1 Limiting the Number of Remote Operations to 100 set max-dsp-ops = 100;
5–4 eTrust Directory Administrator Guide 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 You can remove all knowledge of remote DSAs using the command: Knowledge clear dsas;
Unbinding Remote Connections
Display Outgoing When a DSA communicates with a remote DSA using DSP, it sets up a Connections 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 You can unbind all or some connections using this information and one of the Connections following commands (assuming 3 is a valid connection identifier): unbind all; unbind dsa 3;
Unbind Outgoing A DSA can automatically unbind outgoing connections when they exceed Connections That global values set in the remote-DSA definition, for example: Exceed Global Values set dsa “Eagle” = { ... dsp-idle-time = 60 ... };
Distribution and DSP 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 local- scope 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 eTrust Directory Administrator Guide 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 To view the DSP configuration, use the command: Configuration get dsp;
A sample of the output from this command is below: max-dsp-ops = 100 local-prefix =
View Remote To view remote connections, use the command: Connections get online-dsas;
A sample of the output from this command is shown below: dsa> get online-dsas;
Remote: DSA 2 (DEMOCORP) Association: state 3, idle for 2 seconds, 0 operations waiting 0 operations abandoned prefix:
Distribution and DSP 5–7 Managing DSP
Display Each DSA for Also useful is the command: Which the Current get dsas; DSA Has Knowledge This displays information similar to the previous example about each DSA for which the current DSA has knowledge, including itself.
5–8 eTrust Directory Administrator Guide 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 DXserver
The following example defines a DSA called DemoResearch, which is subordinate to the pre-configured DemoCorp DSA in the standard version.
DSP Example 2 Defining a Subordinate DSA set dsa “DemoResearch” = { prefix =
The DSA definition contains a prefix: prefix =
that defines the area of the DIT that is covered by this DSA. 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).
Distribution and DSP 5–9 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.
Ext e rn a l DUA/ DSA
Pro xy DSA
Interna l Interna l DSA1 DSA2
Interna l Interna l DSA3 DSA4
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 chaining-prohibited 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–10 eTrust Directory Administrator Guide Configuring Another DXserver
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.
Distribution and DSP 5–11 Configuring Another DXserver
Configuring a Third-party DSA
To configure the knowledge of third-party DSAs, use the set dsa command.
DSP Example 3 Setting a Remote DSA Reference set dsa “DemoUni” = { prefix =
address = tcp “demouni.edu” port 389
auth-levels = anonymous dsp-idle-time = 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 simply 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; however, 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–12 eTrust Directory Administrator Guide Configuring Another DXserver
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.
DSP Example 4 Setting Two DSA References on the Same Machine # Knowledge configuration file: localTwo.dxc set dsa “LocalTwo” = { prefix =
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.
Distribution and DSP 5–13 Configuring a Domain of DXservers
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.
DSA1
DSA2 DSA3
DSA4 DSA5
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–14 eTrust Directory Administrator Guide Configuring a Domain of DXservers
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.
dom.dxg .dxc DSA-A DsaA.dxi (copy) (copies)
DsaA.dxc
dom.dxg
DsaB.dxc
dom.dxg .dxc DSA-B DsaB.dxi (copy) (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.
Distribution and DSP 5–15 Configuring a Domain of DXservers
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 =
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–16 eTrust Directory Administrator Guide Configuring a Domain of DXservers
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.
Distribution and DSP 5–17 Alternative DSAs
Alternative DSAs
You can define more than one DSA with the same prefix (naming context). This results in better system availability because when a DSA tries to connect to each alternative DSA, it only returns a referral if all of the alternative DSAs are unavailable. A group of alternative DSAs are usually configured with a router DSA above them. When the router DSA receives a client request it forwards the request to the DSA that can best process the request.
Ro u t e r DSA
DSA1 DSA2 DSA3
DB1 DB2 DB3
Note: This diagram assumes that the alternative DSAs are running on different servers, and accessing a replicated copy of the database.
5–18 eTrust Directory Administrator Guide Alternative DSAs
DSA Failover
You can define a number of DSAs with the same prefix, each on a different machine, and each with a copy of the same data. All requests can be sent to the first DSA, but if this DSA fails then requests are sent to the next DSA. Alternatively, when the DSAs are widely separated geographically, clients can access the closest DSA, but if this fails then they can access a more remote DSA that contains the same information.
Set Precedence When more than one DSA is defined by the same prefix, the router DSA usually selects remote DSAs in their order of occurrence in the configuration files. You can override this order with the precedence command. For example, if the DSAs, EAST and WEST, contain the same information, DSAs in the EAST can ensure that they select EAST before WEST with the command: set precedence = EAST, WEST;
or, simply: set precedence = EAST;
When this command occurs in a configuration file, you must source it after knowledge.
Distribution and DSP 5–19 Alternative DSAs
Load-sharing DSAs
A DSA can be part of a load-sharing group. The benefit of load-sharing DSAs is to increase throughput by running parallel DSAs. A router DSA distributes queries among the load-sharing DSAs using a least-busy algorithm. Each DSA in the group has the same prefix. Before sending a DSP request for this prefix, the whole group is checked to see which DSA has the least number of outstanding requests. The new request is sent to this DSA.
The notion of load is subjective and relates to the number of requests sent by the DSA making the determination. No assessment is made of the potential load caused by each operation or of the effect of requests from other DSAs.
To create a group of load-sharing DSAs for a particular prefix, add load-share to the dsa-flags for each of them: set dsa DemoCorp = { ... dsa-flags = load-share, ...... };
The following diagram illustrates a load-sharing configuration:
Ro u t e r DSA
DSA1 DSA2 DSA3
DB1
5–20 eTrust Directory Administrator Guide Alternative DSAs
Query Streaming
A router DSA that forwards requests to a group of alternative DSAs can direct operations to particular DSAs. By using the dsa-flags in the set dsa command, a router can mark certain DSAs as read-only, so that no update requests are forwarded to those DSAs. The limit-search flag can also be set so that no complex searches are forwarded to such a DSA.
Note: A DSA is multithreaded. You specify the number of threads to start for complex searches, simple searches, and updates of the directory. For more information about multithreading, see Configuring DSA threads in the chapter “General Administration.”
Create Read-only To create a DSA as a read-only DSA, add read-only to its dsa-flags: DSA set dsa DemoCorp = { ... dsa-flags = read-only, ...... };
Process Simple To limit a DSA to processing simple lookups, add the following dsa-flags: Lookups set dsa DemoCorp = { ... dsa-flags = read-only, limit-search, limit-list...... };
The following diagram shows a domain of DXservers configured to handle query streaming. DSA1 to DSA5 all have the same prefix.
Ro u t e r DSA
DSA1 DSA2 DSA3 DSA4 DSA5
DB1
Distribution and DSP 5–21 Alternative DSAs
DSA1, DSA2 and DSA3 form a load share group and are configured to handle simple searches. DSA4 is an update DSA and DSA5 is configured to handle complex searches. The dsa-flags for the DSAs are as follows: DSA1: dsa-flags = read-only, limit-search, limit-list, load-share... DSA2: dsa-flags = read-only, limit-search, limit-list, load-share... DSA3: dsa-flags = read-only, limit-search, limit-list, load-share... DSA4: dsa-flags = limit-search, limit-list... DSA5: dsa-flags = read-only...
Tip: The DSAs marked as load-share should occur at the start of the list of subordinate DSAs in the router DSA’s group knowledge file (.dxg), and you should list them consecutively so they form a load-share group.
5–22 eTrust Directory Administrator Guide
Chapter 6 Security
DXserver supports a powerful and integrated set of security features, including:
■ Secure Socket Layer (SSL) Encryption ■ Authentication ■ Access Controls
SSL Encryption is provided by means of a companion security server to DXserver called SSLD. The SSLD server supports:
■ SSL (both version 2 and 3) ■ Transport Layer Security (TLS)
Authentication provides a means of identifying a user or directory client. Authentication is used within DXserver to apply the access-control regime for that user.
DXserver supports the following authentication methods:
■ Anonymous—no credentials required ■ Simple—name and password authentication ■ SSL—X.509 certificate based authentication
Access Controls regulate what data a user can read or update. DXserver access controls support the following major features:
■ Rules—simplify the specification of access controls ■ Policies—collections of rules ■ Domains—enable a set of DSAs to enforce consistent access controls
A number of other security features are provided so that security can be distributed and combined in various ways. For example:
■ Using simple authentication over encrypted links ■ Having access control levels based on authentication
Security 6–1 SSL Encryption
SSL Encryption
This section describes how to use SSL to protect link connections to or from DXserver.
Secure Socket Layer
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 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.
DXserver supports SSL as an encryption method, and an authentication method. We refer to this as SSL encryption and SSL authentication.
Note: SSL authentication will always use SSL encryption.
6–2 eTrust Directory Administrator Guide SSL Encryption
DXserver and 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.
The SSLD executable is found in the DXserver bin directory. One SSLD process can serve multiple DXservers simultaneously. For security, SSLD must run on the same machine as the DXserver.
The following diagram displays this:
Directory DSA DB Client
Person- SSLD ality Certs
HSM Trusted Certs
SSLD holds certificates in its configuration directory.
There are two types of certificates used:
■ 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; however, if a Hardware Security Module (HSM) is in use, it is a hardware reference.
Hardware Security Module
A Hardware Security Module (HSM) is used to manage private keys in hardware.
For more information about DXserver HSM support, contact Computer Associates at http://supportconnect.ca.com.
Security 6–3 SSL Encryption
Configuring DXserver for SSL Operation
DXserver needs to know which port the SSLD is using for connections. This is configured in the DSA’s configuration file (.dxc) in the knowledge directory.
For example: set dsa DemoCorp = { ... ssld-port = port_number ... };
DXserver and SSL Connections
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 sequence of events occur: 1. If the DXserver is not already connected, it connects to the SSLD (assuming it is running – see note below). 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 DB DSA Client
1 2 3
SSLD
Note: When 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).
6–4 eTrust Directory Administrator Guide SSL Encryption
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’s configuration file in the knowledge directory. set dsa 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.
Generating Personality Certificates
You generate personality certificates by using separate certificate authority software. A popular certification authority software package called 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.
The dsa-name in the DSA knowledge (for example, dsa-name =
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.
Important! Simply renaming the shipped personality files (for example, from democorp.pem to mydsaname.pem) and editing the subject lines will not work. This text is just comments for the real certificate—changing the text does not alter the certificate. A new one must be generated.
Security 6–5 SSL Encryption
Configuring SSLD
The format of the SSLD command line is as follows: ssld action [arguments]
The syntax of the various ssld action commands are shown below:
Install Action ssld install ssld-server-name -certfiles path -ca file [options]
This command saves the startup arguments and options and causes the SSLD to start automatically at system startup.
Start Action ssld start ssld-server-name [-certfiles path -ca file [options] ]
This command starts the SSLD. If you previously install the SSLD, you can omit the arguments and options. To start all previously installed SSLDs, use the command: ssld start all
Stop Action ssld stop ssld-server-name
This command stops the specified SSLD. To stop all SSLDs, use the command: ssld stop all
Remove Action ssld remove ssld-server-name
This command removes the specified SSLD from the list of automatically restarting SSLDs so that it does not restart at the next system startup. To remove all SSLDs, use the command: ssld remove all
Status Action ssld status
This command displays the status of all configured SSLDs.
6–6 eTrust Directory Administrator Guide SSL Encryption
The following tables provide more details about the parameters and options.
Parameter Meaning -certfiles path Directory that contains certificate and private-key files 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. -ca file File containing 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 options of the ssld command are:
Option 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 to be used. -help Displays command usage. -port n The listen port. This is the port number that 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. -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 0, which makes the SSLD single-threaded. We recommend that you specify twice the number of CPUs; however, when your host has a large number of CPUs, you can use the number of CPUs plus 5.
Security 6–7 SSL Encryption
SSLD Example Configuring Four Threads
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 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
For more information about starting and stopping the SSLD, see the readme file. This is located in the ssl directory, in the samples distribution. Examples of how to run the SSLD are found in the same directory.
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 encryption between DXserver DSAs, simply set the link-flags flag to ssl-encryption in the DSA’s configuration file in the knowledge directory.
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 …
OP BIND DUA DemoCorp UNSPSC DSA 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.
6–8 eTrust Directory Administrator Guide 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 To force authentication of at least a name and password, set min-auth to Authentication 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 To force authentication by certificate, set the following command: Authentication set min-auth = ssl-auth;
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.
Security 6–9 Authentication
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. ■ min-auth is not 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
6–10 eTrust Directory Administrator Guide Authentication
SSL Authentication
SSL authentication has two parts: 1. Establish the SSL connection. 2. Establish the directory connection (using a bind).
Establish SSL The SSL client provides a certificate with the SSL connection Connection
SSL DemoCorp Client 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 Trusted Certs
SSL DemoCorp Client DSA
The SSL connection is then established.
SSL SSL DemoCorp Client DSA
Security 6–11 Authentication
Establish Directory The SSL client uses the SSL bind procedure. In LDAP, this is known as Connection SASL/EXTERNAL. (In X.500, we use the Bind External Procedure.) This tells the directory to use the certificate from the link layer.
BIND SSL DemoCorp Client SSL 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 (DSAs), 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 DemoCorp Client SSL DSA
6–12 eTrust Directory Administrator Guide Authentication
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 set the correct trust-flags in the DSA definition.
For example, to enable the DemoCorp DSA to forward a password check on to the UNSPSC DSA, the UNSPSC DSA must set the trust-flags in its DSA definition:
set dsa UNSPSC = … trust-flags = allow-check-password …
BIND OP DemoCorp UNSPSC DUA DSA DSA
The DSA receiving the bind request passes a compare request of the password value to the remote DSA. If this returns a compare confirm with assertion true, the DSA returns a bind-confirm to the user.
Bypass 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.
DSP Simple Authentication
DSP and DISP binds are subject to the min-auth setting. If the local DSA has enabled authentication, an incoming DSP (or DISP) bind request must have bind credentials.
See Managing DSP in the chapter “Distribution and DSP” for more information about sending credentials with a DSP bind request.
Security 6–13 Authentication
The bind credentials are part of the DSA’s configuration file in the knowledge directory:
set dsa DemoCorp = … dsa-name =
BIND DemoCorp UNSPSC DSA DSA
The 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 dsa-name.
■ The password in the credentials matches the remote DSA password.
■ The address of the binding DSA matches the address of the remote DSA.
Note: We recommend that a number of 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.
For the Bind Response, the initiating DSA expects credentials to match the target DSA.
set dsa UNSPSC = … dsa-name =
BIND DemoCorp RESPONSE UNSPSC DSA DSA
This two-way authentication is known as mutual authentication.
6–14 eTrust Directory Administrator Guide Authentication
DSP SSL Authentication
To enable SSL authentication between DSAs, you need to configure the authorization level within the DSA’s configuration file in the knowledge directory.
For example, to enable SSL authentication between a DemoCorp DSA and a UNSPSC DSA, the UNSPSC DSA must set the auth-levels flag in its knowledge configuration:
set dsa UNSPSC = … auth-levels = ssl-auth …
BIND DemoCorp UNSPSC DSA DSA
Important! 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 ssl-encryption.
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–15 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 to return credentials by doing the following:
set dsa UNSPSC = … trust-flags = no-server-credentials …
BIND RESPONSE UNSPSC DemoCorp rd 3 PARTY DSA 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.
Conveying User Authentication
A DXserver DSA can authenticate a user who binds to the DSA. The user can then request information held on another DSA. The DXserver can convey the authentication to another DSA when you set certain distributed authentication parameters.
To have privileges on a remote DSA, the originator DSA must be trusted.
When trust-flags is set as follows, users authenticated on DemoCorp are treated as if they are authenticated on UNSPSC.
set dsa DemoCorp = … trust-flags = trust-conveyed-originator …
OP OP UNSPSC DUA DemoCorp DSA DSA
6–16 eTrust Directory Administrator Guide Authentication
DSP Link Authentication
Traffic on any link is generally carried at the same authorization level.
The idea is that:
■ “high” travels on “high” (SSL authentication)
■ “medium” travels on “medium” (simple)
■ “low” travels on “low” (anonymous)
SSL authentication
DSA Simple authentication DSA
No 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 authorization 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.” 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.
Security 6–17 Authentication
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 …
simple DemoCorp UNSPSC DUA anon DSA 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 simple UNSPSC DUA DemoCorp DSA DSA
6–18 eTrust Directory Administrator Guide Access Controls
Access Controls
Access controls protect data from unauthorized access or modification. In particular, access controls work by asking the following 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 and/or a particular day of the week.
When the answer is yes, the operation can proceed.
Access controls are complex because any number of access controls can apply to a particular data item, and there is a positive way (grant) and negative way (deny) to express these rules. There are complex rules regarding the final result involving precedence. When a system does not explicitly give a grant (or it explicitly denies), the directory behaves as if that protected item does not exist, that is, it is invisible.
DXserver manages access controls by defining easy-to-understand rules. There are two types of rules:
■ Static rules apply to individuals and/or groups of individuals, and are stored as text files in the DXserver configuration files (see Static Access Controls in this chapter).
■ Dynamic rules are stored in an attribute in the directory, and can be set by anyone who has the power to delegate the permissions being created (see Dynamic Access Controls in this chapter). In addition, eTrust Directory supports the following:
■ Role-based rules are applied to roles, and the roles are represented by entries in the directory (see Role-based Access Controls in this chapter).
■ Secure proxy lets a user assume the identity of another user, for example, a ‘single-sign-on process’ can access the directory on behalf of a user who may or may not have an entry in the directory (see Secure Proxy in this chapter).
The access controls are described in detail in the following sections.
Security 6–19 Access Controls
Administrative Areas and Domains
An administrative area in eTrust Directory is a single DSA. This means that when access controls (or knowledge, schema, and so forth) are defined, they only have effect on the DSA for which they are configured. The X.500 Standards permit more than one administrative area inside a DSA. If this is required, simply define another DSA covering the required subtree. In this case, two required administrative areas are effected by having two DSAs.
A Domain is any collection of DSAs that share the same configuration. For static access controls (and knowledge, schema, and so on.), a number of DSAs can collectively form a domain of DSAs with the same controls by sharing or copying the configuration files for each of them.
Access Control Policy and Rules
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.
In DXserver, you define an access control policy as a set of rules (that map inside the server into 1993 X.500 Access Controls). Dynamic access controls are defined by a rule stored in a special attribute. Static access controls are defined in configuration files (.dxc) in the access directory. Generally, you group these files together by using a group configuration file (.dxg), which constitutes a policy. You can share policies among a number of DSAs.
Rules
A set of rules best describes an access control policy. For example:
■ 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.
6–20 eTrust Directory Administrator Guide Access Controls
Policies
When developing an access control policy, you should adhere to the following principles:
■ Make use of domains. 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 (see Access-controlled Routing in this chapter for more information).
■ Grant rather than deny access to data. Do not grant access to all data and then deny access to portions of the data, because sensitive data (protected items) 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. The reasons are: – Complexity—defining many different groups with different subtrees can become a security problem over time if you do not maintain careful control of valid users and subtrees. – Performance—complex access control schemes can result in performance degradation 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.
Security 6–21 Access Controls
Static Access Controls
Static access controls are applied to individuals or groups of individuals, and stored in the DXserver configuration files. Static access controls are activated when DXserver is initialized, that is, at the time DXserver starts up, or when an administrator reinitializes the system.
Static Access Control Rules
In general, you can express all common access control rules by combinations of the following elements:
■ Groups ■ Superusers ■ Administrative users ■ Registered users ■ Public users ■ Protection of subtrees, entries, and attributes
Each rule has a powerful set of parameters that specify who, where, and what the rule applies to. In addition, all rules are cumulative; hence, you can define very complex access control polices.
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.
6–22 eTrust Directory Administrator Guide Access Controls
Rule Hierarchies
These rules have a hierarchy of power: 1. Superuser 2. Administrative user 3. Protected item 4. Registered user 5. Public user
Thus, a superuser rule always overrides any administrative user rule, and so on.
Also, note the inheritance:
■ 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.
Managing Static Access Controls
You can manage access control configuration by using the following access module commands at the management console:
■ set parameter = value; ■ get parameter ■ clear all;
Multiple set command parameters let you change the access control configuration. The following table summarizes the commands, and the following sections explain them in more detail.
Important! Commands issued at the management console are not stored in the configuration files; they are only valid for the run-time of the DSA.
The following are the parameters of the access module set command:
Parameter Meaning group Defines a group of users. super-user Grants unlimited access to particular users
Security 6–23 Access Controls
Parameter Meaning 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.
The access module supports the following get commands:
Parameter Meaning access Displays access control details.
The access module supports the following action commands:
Value Meaning clear all Resets (clears) all access controls.
Static Groups
Groups simplify the management of many users. You can group users together with the set group command and form the group so that you can use it in other access control commands. The command has the format: set group name = { users =
where name is the name you give to the group.
This command lets you add a single group containing one or more users.
Access Control Forming a Group Example 1 set group “admin-user-group” = { users =
This command defines a group containing two users. The group is named admin-user-group, suggesting that the users have dministrative user privileges.
Note: Group definitions are effective only when you enable access controls.
6–24 eTrust Directory Administrator Guide Access Controls
Static Rule Components
A static access control rule must state:
■ To which user it applies ■ To which area of the directory it applies ■ What permissions it gives ■ When it applies ■ What authentication level it requires
Generally, a rule has the following format: set ruleType tag = { acUser acArea acOptAttrs acOptPerms acOptAuth acOptValidity };
where:
acUser defines the users to whom the rule applies. Specify this using:
■ A user’s own entry, own-entry ■ A user’s distinguished name, user =
See Role-based Access Controls for more information about roles.
acArea defines the part of the directory to which the rule applies. Specify this using:
■ The distinguished name of an individual entry, entry =
acOptAttrs defines specific attributes in this area to which you want to limit access, attrs = attributeName1 [, attributeName2 …]
acOptPerms applies permissions to a particular rule type. Specify this using one or more of the following permission items:
■ read ■ add ■ remove ■ modify ■ rename ■ all perms = optPerm1 [, optPerm2 …]
Security 6–25 Access Controls
acOptAuth defines the authentication level with which the user must bind. This can be either simple or ssl-auth.
acOptValidity states when the rule applies. Specify this using:
■ A particular time of the day ■ A particular day, or days, of the week validity = ([start hhmm][end hhmm] [on daystring])
where daystring is a string like 12345 or 67 (1 is Monday).
Note: You can give the name of an attribute set in place of the attributeName. (See Attribute Sets in the chapter “Schema Definition” for more information).
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 = { acUser acOptAuth acOptValidity };
Each instance of the command lets you add a single user, single group of users, or single user subtree.
Access Control Adding Superusers Example 2 set super-user “dsa-manager” = { user =
This command defines a single user with superuser privileges across the domain of this DSA.
Access Control Being a Superuser of One’s Own Entry Example 3 set super-user “self” = { own-entry validity = ( start 0800 end 1800 on 12345 ) };
This 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. 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.
6–26 eTrust Directory Administrator Guide Access Controls
Static 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. The command has the format: set admin-user Tag = { acUser acArea acOptAttrs acOptPerms acOptAuth acOptValidity };
Each instance of the command lets you add a single user, single group of users, roles, or a single user subtree for a single administrative range.
Access Control Adding Administrative Users Example 4 set admin-user “administrators” = { group = “admin-user-group” subtree =
In this example, there is one specified subtree: AU/DemoCorp. This subtree has administrators defined by the group admin-user-group.
Access Control Allowing Update Privileges on a Role Example 5 set admin-user “project-leaders” = { role =
In this 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.
Security 6–27 Access Controls
Access Control Allowing Update Privileges on a Single Attribute Example 6 set admin-user “work-phone” = { group = “pabx-mgmt-group” subtree =
In this example, all users in the group pabx-mgmt-group have update privileges on the attribute workPhone in the subtree AU/Democorp/R&D.
Access Control Allowing Users Update Privileges on Specific Attributes in Their Own Entry Example 7 set admin-user “my-own-work-details” = { own-entry subtree =
In this example, all users in the subtree AU/Democorp/R&D have update privileges on the attributes workPhone and description in their own entry.
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.
Static Registered Users
In a specified subtree, you can assign users the authority of a registered user. Registered users have read privileges over a specified viewing scope. This scope is a subtree, entry, or the designated attributes in an entry or subtree. Protected items in the viewing scope are invisible. You add users to the list of registered users, either as single users, groups of users, roles, or all users in a specified subtree. The command has the format: set reg-user = Tag { acUser acArea acOptAttrs acOptPerms acOptValidity };
Access Control Adding Registered Users Example 8 set reg-user “R&D-Users”= { user-subtree =
In this example, all the users in the subtree AU/DemoCorp/R&D can access the subtree AU/DemoCorp.
6–28 eTrust Directory Administrator Guide Access Controls
Access Control Allowing Read Privileges on an Entry Example 9 set reg-user “democorp-staff” = { group = “staff” entry =
In the above example, all users in the group, staff, have read privileges on the entry AU/DemoCorp.
Access Control Allowing Read and Modify Privileges on a Number of Attributes Example 10 set reg-user “self-view” = { user-subtree =
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.
Access Control Allowing Users Read Privileges on Particular Attributes in Their Own Entry Example 11 set reg-user = { own-entry subtree =
This example lets any user in the subtree AU/DemoCorp view only the selected attributes in their entry. This differs from the previous example (Access Control Example 10—Allowing Read Privileges on a Number of Attributes) where all users in the subtree DemoCorp can view all entries in that subtree.
Note: Registered user definitions are effective only when you enable access controls.
Security 6–29 Access Controls
Static 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. Public ranges are made available to public users with the following command: set public-user Tag = { acArea acOptAttrs acOptPerms acOptValidity };
Access Control Adding a Public Subtree Example 12 set public-user “public-attr” = { subtree =
In this 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.
Note: Public user definitions are effective only when you enable access controls.
Static Protected Items
You can protect specific subtrees, entries, or designated attributes in a subtree or entry so that superusers have read and update privileges, administrative users have read and update privileges (if the subtree is in the administrative user’s administrative area), and other users do not see the items, that is, they are invisible. The command that protects items has the following format: set protected-items tag = { acUser acArea acOptAttrs acOptValidity };
Note: Protecting this subtree from employees also makes it invisible to public users, as described in the section Rule Hierarchies.
6–30 eTrust Directory Administrator Guide Access Controls
Access Control Protecting a Subtree Example 13 set protected-items “hide-finance-from-employees” = { group = “employees” subtree =
Access Control Protecting an Entry Example 14 set protected-items “hide-schema-from-employees” = { group = “employees” entry =
You can use this specification, for example, to hide the existence of some management information about a DSA definition stored within the directory.
Important! If you rename a protected subtree or entry, or any of its parents, this access control rule no longer protects the item.
Access Control Protecting Attributes Example 15 set protected-items “hide-passwords-and-home-phone” = { subtree =
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.
Note: This command does not protect naming attributes.
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.
Note: Protected item definitions are effective only when you enable access controls.
Important! 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.
Security 6–31 Access Controls
Role-based Access Controls
When access control rules are applied to a role, they are known as role-based access controls. The 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. To add an identity to a role entry, you must enter its distinguished name as an attribute value of the member attribute type. You can control access to the role subtree using access controls.
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 machine.
Activate Role-based To activate role-based access controls, enter the following commands: Access Controls set role-subtree =
where dn is the distinguished name of the subtree used to store the roles.
Disable Role-based To disable role-based access controls, enter the following command: Access Controls set use-roles = false;
Access Control Activating Role-based Access Controls Example 16 set role-subtree =
In this example, when a user binds to DXserver, DXserver searches the member attribute of the subtree c=au, o=Democorp, ou=Roles for that user’s distinguished name. The entries containing that member identify the roles this member has.
6–32 eTrust Directory Administrator Guide Access Controls
Access Control Adding Roles Example 17 add-entry-req entry =
In this example, the role AdminFinance is added with two members, Noelene Correa and Linda Deacon.
Secure Proxy
The secure proxy feature lets an authorized user (or process) impersonate a user 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.
Note: 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;
Security 6–33 Access Controls
Activate Secure Proxy To activate proxy access, enter the following command: set trust-sasl-proxy =
where dn is the distinguished name of a trusted proxy. The proxy must bind using SASL/EXTERNAL over SSL.
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=
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 machine.
Scope
Dynamic rules apply downwards from the entry in the DIT where the dxDynamicAccess attribute is stored.
Enable Dynamic To enable dynamic access controls, enter the following command: Access Controls set dynamic-access-control = true;
Dynamic access control only works when the access-controls flag is set to TRUE. Make sure you have also used the following command: set access-controls = true;
6–34 eTrust Directory Administrator Guide Access Controls
Disable Dynamic To disable dynamic access controls, enter the following command: Access Controls set dynamic-access-control = false;
Dynamic Access The rules governing dynamic access controls take the following form: Control Rules
where tag is an identifier used for documentation purposes, dn is a distinguished name, and attr is an attribute.
Access Control The following example gives everyone permission to read the commonName Example 18 attribute. The tag Joe is used to assist with maintenance and problem analysis; DXserver does not interpret it. Joe all read commonName
Access Control The following example gives everyone permission to read all attributes: Example 19 Joe all read all
Access Control The following example denies the roles of CEO and AdminFinance within Example 20 Democorp access to the ssoHelicopter attribute: Joe role cn=ceo,o=Democorp deny ssoHelicopter
Access Control The following example lets a user with the common name Craig write to the Example 21 ssoHelicopter attribute: Joe user cn=Craig,o=Democorp write ssoHelicopter
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.
Transitive Delegation
If A delegates power to B, then B can only delegate power to C for entries below the one that granted B its power.
Security 6–35 Access Controls
Viewing Access Controls
You can view the actual 1993 X.500 Access Control details using the command: get access;
An example of the output of this command is: ------node ------Subtree base: AU.ORG.PUBLIC exclusions: nil minimum 0, maximum –1 ACI Items precedence 1, auth level 0 userFirst userClass allUsers group: nil name: nil subtree: nil user permissions precedence 1 protected item entry allUserAttributeTypes grantsAndDenials grantDiscloseOnError grantRead grantBrowse grantReturnDN grantCompare grantFilterMatch precedence 1, auth level 0 itemFirst protected item attributeType: userPassword item permissions precedence 1 userClass allUsers group: nil name: nil subtree: nil grantsAndDenials denyAll
6–36 eTrust Directory Administrator Guide Access Controls
------node ------Subtree base: AU exclusions: nil minimum 0, maximum –1 ACI Items precedence 4, auth level 100 userFirst userClass group: nil name: super.user subtree: nil user permissions precedence 4 protected item entry allUserAttributeTypes grantsAndDenials grantAll precedence 2, auth level 100 userFirst userClass allUsers group: nil name: nil subtree: nil user permissions precedence 2 protected item entry allUserAttributeTypes grantsAndDenials grantAll
For full details of access controls, see the 1993 X.500 standard.
Security 6–37 Password Management
Password Management
Password management enables you to set up policy for the following:
■ Life span of passwords
■ Incorrect password handling
■ Password change rules
You can set up the policy in the settings configuration file by using set commands. You can enable or disable password management by setting the following parameter: set password-policy = TRUE | FALSE;
Setting the Life Span of Passwords
Use the following commands to control password expirations:
Command Meaning set password-age = Sets the number of days a password is valid. By number-of-days | 0; default, this feature is disabled (0). set password-last-use = Sets the number of days a password remains valid if it number-of-days | 0; is not used. If the value is exceeded, the password expires. By default, this feature is disabled (0).
Password You want passwords to be valid indefinitely except when they are not used for Management 30 days. Set the parameters as follows: Example 1 set password-policy = TRUE; set password-last-use = 30;
You do not need to use the set password-age command because you are using its default.
6–38 eTrust Directory Administrator Guide Password Management
Setting Up Incorrect Password Handling
Use the following commands to set up how you want to handle incorrect passwords:
Command Meaning set password-max-suspension Sets the number of seconds after which a = number-of-seconds | 0; suspended password reactivates. By default, this feature is disabled (0). set password-retries = Sets the number of consecutive failed logon number-failed-logons; attempts before a password is suspended. The default is 3.
Password You want to suspend an account after three consecutive failed logon attempts Management and do not want the suspended password to reactivate. Set the parameters as Example 2 follows:
set password-policy = TRUE;
Setting Up the Password Change Rules
Use the following commands to set up the rules for changing passwords:
Command Meaning set password-history = Sets the maximum number of entries to retain in the maximum-number | 0; 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-length = Sets the minimum length of a password. The default number-of-characters; is 6 characters. set password-min-age = Sets the number of days since a password was number-of-days | 0; changed until it can be changed again (lockout period). By default, this feature is disabled (0). set password-non-alpha = Sets the minimum number of nonalphanumeric number-of-nonalpha characters a password must contain. The default is 0. set password-numeric = Sets the minimum number of numeric characters a number-of-numeric password must contain. The default is 0.
Security 6–39 Password Management
Password You want to set up the following rules: Management Example 3 ■ Passwords can be reused. You do not want to keep a history of old passwords.
■ You do not want to impose a lockout period.
■ A password must be at least eight characters in length with no restrictions to the type of characters.
Set the parameters as follows: set password-policy = TRUE; set password-length = 8;
Password Reset
Password logins are secure only if each person can change only their own password. Therefore, it is essential to configure access control so each user can update only their password. The exception is an administrator who should be permitted to update any user password. Whenever an administrator updates a user password, the password policy attributes for that entry are reset.
For example, if password-age is configured as 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.
6–40 eTrust Directory Administrator Guide Other Security Features
Other Security Features
DXserver has many safeguards to prevent attacks and potential trapdoors in an operational directory.
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.
Impersonation Protection
DSA authentication is completely separate from DUA authentication. This means that a DUA cannot gain access using a DSA’s credentials, and a DSA cannot gain access using a DUA’s credentials.
DSA authentication checks network addresses and credentials. This makes it difficult for one DSA to impersonate another DSA.
Security 6–41 Other Security Features
Access-controlled Routing
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 UNSPSC DSA DSA
Trust Flags
DXserver uses trust flags to vary the security between DSAs.
By default, security is tight. The trust flags provide a mechanism to selectively relax security between DSAs. The trust flags are part of the set dsa definition. See DSA Knowledge Flags in the chapter “General Administration” for more information.
Audit File
You can send tracing of DSA operations to a log file. This log file forms the basis of recording all update activity in the DSA. For more information, see Alarms, Traces and Logs in the chapter “General Administration” for more information.
6–42 eTrust Directory Administrator Guide Other Security Features
Read-only DSA
To guarantee update security (over and above access controls), you can limit the DSA to a read-only DSA using the command: set dsa Eagle = { ... dsa-flags = read-only; ... };
This feature 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.
For more information about read-only directories, see Local Operations in the chapter “General Administration” for more information).
DXconsole
The management console only accepts one telnet session.
You can define a console-port in the DSA knowledge. This scheme uses the local host security. An administrator must have an account on the local machine to communicate with the DSA through this port. This prevents attacks from remote telnet sessions.
You can use the console remotely when you configure remote-console-port. You can attach a password, and SSL may be required. See Configuring the Management Console in the chapter “DXserver Overview” for more information.
If the administrator always runs DXconsole, this prevents anyone else from starting up DXconsole.
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–43
Chapter 7 Replication
Replication is the process of copying data from one server to another. It is usually deployed for one, or both, of the following reasons:
■ Availability—to enable fail-over to an alternative server ■ Performance—to move the data closer to where it is needed
However, replication complicates any system because of the problem of synchronizing the copied data. It requires considerable effort to put configurations and procedures in place that ensure data remains consistent across servers and that the system can recover and resynchronize after network or server failures. This extra effort may outweigh any availability or performance advantages that replication offers so you must take special care when designing a replicated system.
If you intend running any form of replication, you should ensure that you synchronize the operating system clocks regularly. This is required because conflict resolution is time-based—the most recent update wins.
eTrust Directory supports the following types of replication:
Replication Characteristics Most Suitable Deployment Scheme Multiwrite Multi-master Where machines and communications links Real time are reliable. Simple configuration High Performance DISP Master-slave Where interoperability is required with Write-behind other vendor’s X.500 directories. High flexibility DXtools Batch mode Where synchronization is required between High traceability two directories or with a legacy system.
This chapter includes information about replication concepts and describes each of the above replication schemes.
Replication 7–1 Replication Overview
Replication Overview
eTrust Directory supports three standards-based mechanisms of replication.
Multiwrite Overview
Multiwrite uses DSP (Directory System Protocol) to chain updates between servers in real time. When a set of DSAs is configured in a multiwrite group, an update to any DSA is also applied to the others.
Multiwrite replication is in three parts, as illustrated in the following diagram:
1. Write to yourself—client sends an update request to DSA1, which applies it locally 2. Write to peers—if the local request succeeds, then the request is sent, in parallel, to each peer DSA 3. Send the response—when each of the peers has confirmed, the response is sent back to the client
DISP Overview
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.
DXtools Overview
eTrust Directory supports synchronization of external directories or legacy systems using an intermediate LDIF (Lightweight Directory Interchange Format) file. This technique may use a number of import, export, and synchronization tools to manipulate and merge data.
7–2 eTrust Directory Administrator Guide Replication Concepts
Replication Concepts
Before describing the details of the replication schemes, it is important to cover some replication concepts. To do this, it is helpful to look at a real-life example.
The previous configuration 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.
The essence of this configuration can be summarized in the following table:
DSA Function Prefix Dsa-flags R1, R2 Router DSA
Replication 7–3 Replication Concepts
Distribution Versus Replication
Distribution differs from Replication. Within a distributed directory, only one server holds any single piece of data.
The diagram in Replication Concepts in this chapter 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.
Multimaster Versus Master-slave Replication
When the copying of data between servers is always one way, it is known as master-slave replication, or shadowing. When the copying is bi-directional, it is known as multimaster replication.
The diagram in Replication Concepts in this chapter shows a multimaster system by virtue of the fact that it can send queries to either of the routers. However, it is not unusual for a system to be operated in a master-slave arrangement where all clients send updates to Machine 1 in preference. Running a system in a master- slave arrangement generally increases manageability.
Real Time Versus Write-behind Replication
When the copying of data between servers occurs as part of a client update, it is known as real time replication. If it occurs periodically, independent of the client update, it is known as write-behind replication.
Write-behind replication can occur on-demand—where the updates are transferred immediately after they occur, or scheduled—where the updates are transferred according to a periodic schedule.
Note: Real time and on-demand are different. In real time replication, the update confirmation is not sent to the client until after the update-confirm is received from each of the (online) slave/peer DSA(s). With on-demand replication, the update confirmation is sent as soon as the operation completes locally.
The diagram in Replication Concepts in this chapter shows a real time replication scheme, using multiwrite. Real time replication is usually preferred to write- behind replication to overcome the problem of latency. Latency is a measure of the time where the shadow server(s) is out-of-date with respect to a master server. There are many applications (such as an authentication service) where any latency is unacceptable.
7–4 eTrust Directory Administrator Guide Replication Concepts
Replay-based Versus State-based Replication
The fundamental mechanisms in which incremental changes are propagated to a peer/slave directory are replay-based and state-based.
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. State-based deltas are very efficient for repeated updates; for example, when an entry is modified 100 times in the given period, only a single entry delta is transferred (instead of 100 changes in a replay based system). However, state- based systems are generally not designed to operate in real time.
The following table summarizes the two schemes:
Replication Advantages Disadvantages Example Strategy Replay-based Simple Poor recoverability Multiwrite Can be real time State-based Efficient Cannot be real time DISP High recoverability
You can configure the system shown in Replication Concepts in this chapter to have the immediacy of the multi-write 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.
Replication 7–5 Multiwrite Replication
Multiwrite Replication
eTrust Directory’s multiwrite replication has the following properties:
■ Fast and efficient—uses DSP chaining.
■ Real time—essential for many applications.
■ Simple—multiwrite is enabled with a single dsa-flag. Because this capability is built into DXserver, it does not require a separate product or additional licensing.
■ Flexible—can be set up in master-slave, primary-backup or multimaster configurations; also can be used with any combination of other DSA flags to support load balancing and query streaming.
■ Choice of recovery—can use simple queues or DISP recovery.
■ Heterogeneous—can perform replication on LDAP servers using DXlink.
Multiwrite replication is most suitable in environments with reliable network links, machines, and power supplies. Treat system crashes and unreliable networks as disaster recovery scenarios that involve reconciliation between databases using DXtools.
Configuring Multiwrite
Create a Multiwrite To create a multiwrite group, configure all of the DSAs in the group as follows: Group ■ Configure all DSAs with the same context prefix. ■ Connect each DSA to a database holding synchronized information. ■ Each DSA must share the same knowledge information and the DSA knowledge for each DSA in the group must contain the multi-write dsa flag as follows: set dsa DemoCorp = { ... dsa-flags = multi-write, ...... };
Note: DSA flags must occur after dsp-idle-time and before the trust and link flags.
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 =
The default value is 60 seconds.
7–6 eTrust Directory Administrator Guide Multiwrite Replication
Multiwrite Queues
Multiwrite DSAs are usually online. If one of the DSAs in the group goes offline, the update is queued in memory until it becomes available.
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 Queue Pool The queue pool has a default size of 200 updates for each peer. You can change Size the queue pool size with the following command: set multi-write-queue = n;
where n defines 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 Size of Multiwrite To see the current size of the multiwrite queue, use the command: Queue get dsp;
A sample of the output from this command is: max-dsp-ops = 100 local-prefix =
Replication 7–7 Multiwrite Replication
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.
Asynchronous Multiwrite Behavior
Multiwrite is usually synchronous. This means that an update operation is not confirmed until all the multiwrite peers have applied it
This provides for loadsharing 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 you set the multi-write-async flag in the knowledge for a DSA, when other DSAs multiwrite to this DSA, they will not to hold the confirmation on account of this DSA. That is, the confirm is returned once all the multiwrite peers NOT marked multi-write-async have applied the update.
7–8 eTrust Directory Administrator Guide Multiwrite Replication
Multiwrite Recovery With DISP
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.
Configure Multi-write- To turn on multiwrite with DISP recovery, use the following command: DISP 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.
Replication 7–9 Multiwrite Replication
A new configuration flag has been introduced: multi-write-disp-queue =
If this is set to true, a multi-write master will only start DISP recovery after it has been down or its multi-write queues had reached their limits. In all other cases it replays its queue content to any peer that was unavailable for a while.
Granularity of DISP Reconciliation
When DISP resynchronization starts it propagates all changes to the DSA since the last successful multiwrite update. In a multi-master 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.
Adding and Removing Database Replicas
Add a Replica To add a replica: 1. Follow the instruction in Manual Synchronization of Replicas Using DB 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 dxdisp –clear dsaname dbname 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. Start the source and target DSAs.
7–10 eTrust Directory Administrator Guide Multiwrite Replication
Remove a 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 dxdisp. 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
Miscellaneous Multiwrite Topics
LDAP and Replication
You can use multiwrite replication to replicate updates applied to eTrust Directory to an LDAP server. Enter dsa-flags = multi-write in the knowledge of the LDAP server. This forwards all updates on DXserver to the LDAP server.
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 setting the dsa- flag 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–11 Multiwrite Replication
Manually Resynchronizing Databases
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, and to inform the master and other peers that a manual resynchronization has taken place.
Generally, taking a snapshot of the master and reloading it on the slave is achieved using dxdumpdb and dxloaddb.
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
In summary, to perform a manual resynchronization, perform the following steps: 1. Shut down the master. 2. Dump the master database using dxdumpdb. 3. Inform the master (and any other peer DSA) that a manual resynchronization has occurred using dxdisp. 4. Restart the master. 5. Copy the LDIF file to the slave machine.
6. Reload the slave database using dxloaddb. 7. Start the slave.
7–12 eTrust Directory Administrator Guide DISP Replication
DISP Replication
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.
DISP Example 1 Configuring the DISP Responder # Sample DSA Knowledge configuration file: DemoCorp.dxc set dsa “DemoCorp” = { prefix =
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–13 DISP Replication
Setting DISP Agreements
You can set agreements using the set command. It has the following general form: set agreement id.ver = { initiator = name mode responder = name authlevel [relay = name authlevel ] area =
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: name—DSA name as defined in a set dsa definition authlevel—anonymous, clear-password, or ssl-auth relay (Optional) An intermediate DSA used to relay the DISP update: name—DSA name as defined in a set dsa definition 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
7–14 eTrust Directory Administrator Guide DISP Replication
DISP Example 2 A DISP Agreement set agreement 0.0 = { initiator = EAGLE supplier responder = BACKUP anonymous area =
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 = EAGLE supplier responder = BACKUP area =
Shared DISP Configuration
You can achieve replication between two DSAs using point-to-point DISP.
DISP DB DSA DSA DB
(Supplier) (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–15 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 Multi-write. 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.
Routing DB DSA DSA DB DSA
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.
DISP Example 4 A DISP Agreement with Relay set agreement 0.0 = { initiator = EAGLE supplier responder = BACKUP anonymous relay = DSA-RELAY anonymous area =
7–16 eTrust Directory Administrator Guide Manual Synchronization of Replicas Using DB Tools
Manual Synchronization of Replicas Using DB Tools
Scenario
eTrust Directory Databases should be manually synchronized when:
■ The dxstatdb utility 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.
Method
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 shutdown during these operations.
dxdumpdb dxloaddb Source LDIF ldifsort LDIF Target DB File File DB
Procedure
To manually resynchronize eTrust Directory databases:
1. Dump the source database and produce an LDIF file using dxdumpdb.
2. Sort the source LDIF file into DIT depth order using ldifsort. 3. If the databases are on different systems, copy the LDIF file from the source system to the target system.
4. Load the target database with the LDIF data using dxloaddb. 5. Start the source and target DSAs.
Replication 7–17
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 Clients
DXserver can be accessed from LDAP clients, such as web browsers, address books, and Lightweight Directory User Agents (LDUAs).
LDAP and DXlink 8–1 LDAP Clients
LDAP Port
You define the LDAP address using the set dsa command, which contains a port number that listens for LDAP protocol 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. See the section Defining DSAs in the chapter “General Administration” for more information.
LDAP Schema
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.
Handling of 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 quite different syntaxes and uses for it.
8–2 eTrust Directory Administrator Guide 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)) . . .
LDAP and DXlink 8–3 Integrating Other LDAP Servers
> value: (1.3.6.1.4.1.3327.77.4.2.1 NAME 'uNSPSC' SUP (top) STRUCTURAL MUST (uNSPSCCode$uNSPSCTitle) MAY (uNSPSCContractManager$uNSPSCContractID$uNSPSCContractAuth$uNSPSCContractSupplier $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))
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.
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 =
8–4 eTrust Directory Administrator Guide Integrating Other LDAP Servers
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 user=J.Bloggs password=yellow password=yellow LDA P Client DSA se rv e r
However, if either of the following is true:
■ 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.
then you can set the credentials used in the DXlink connections in the LDAP server configuration file, as in this example: set dsa LDAP1 = { ... ldap-dsa-name =
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-server-credentials, which indicates to the DSA that the LDAP server will not return credentials on a bind. 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 ... };
LDAP and DXlink 8–5 Integrating Other LDAP Servers
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=CA o=CAI
ou=CA North America
You can enable prefix mapping by defining a native-prefix in the server definition: set dsa LDAP1 = { ... prefix =
8–6 eTrust Directory Administrator Guide Integrating Other LDAP Servers
Working with Microsoft Exchange
An example Microsoft Exchange knowledge file is shown below: set dsa EXCHANGE = { prefix =
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”)
LDAP and DXlink 8–7
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.
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.
Monitoring the Directory 9–1 General Monitoring
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.
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–2 eTrust Directory Administrator Guide Using the Administration Daemon
Using the Administration Daemon
A background process is installed with eTrust Directory called DXadmind, which enables monitoring of all DXservers that are configured on the machine that runs DXadmind. You can connect to DXadmind with an LDAP browser, for example, JXplorer.
DXadmind uses plug-in libraries located in DXHOME/lib to generate a Management Information Tree (MIT). An API lets you create custom libraries for displaying site-specific monitoring information. The libraries are loaded when the DXadmind is started.
Connecting to DXadmind
DXadmind responds to Policy Compliance Check LDAP requests on port 2123; the port to DXadmind is not configurable. You can connect to DXadmind with JXplorer by specifying localhost and the port number 2123. This connects to the MIT and lets monitoring take place.
DXadmind Manager
The top level of the MIT is the Manager node. This contains information about the configuration of the current DXadmind.
Monitoring the Directory 9–3 Using the Administration Daemon
Advantage Ingres Database Plug-in Library
The Advantage Ingres database plug-in library lets you view information about Advantage Ingres, for example, the Advantage Ingres error log for diagnosing database related problems, and the databases that reside on the current machine.
9–4 eTrust Directory Administrator Guide Using the Administration Daemon
Administration Log
The Administration Log lets you view the DXadmind log file. JXplorer has a plug-in editor that lets you scroll through a log file in real time. See the chapter “General Administration” for more information about log files.
eTrust Directory Plug-in Library
The eTrust Directory plug-in library enables you to monitor specific DXserver- information. You can view information such as DXserver log files, status, and settings using this part of the MIT.
Monitoring the Directory 9–5 Using the Administration Daemon
Policy Compliance Plug-in Library
The Policy Compliance library is used for PCM checks, but also forms part of the MIT. You can extract the following PCM checks about DXservers running on the machine where DXadmind resides: ■ All access controls on ■ List dsa flags ■ All consoles disabled ■ List dsa-dsa auth levels ■ All DSA consoles require passwords ■ List link flags ■ All DSAs disallow anonymous access ■ List logs configured ■ All require SSL security ■ List optional ports ■ All SSL bypass entries off ■ List password methods ■ List client authentication ■ List size limits ■ List database names ■ List time limits ■ List dsa addresses ■ List trust flags
The first six checks are pass/fail checks. A message is produced in the case of failure. The last 12 checks display information about the configuration of certain settings for a DXserver.
9–6 eTrust Directory Administrator Guide SNMP and the Directory Monitoring MIB
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:
■ Multi-write 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.
Monitoring the Directory 9–7 SNMP and the Directory Monitoring MIB
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.
SNMP Example 1 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 snmp-description = “SNMP monitor” set snmp-contact = “[email protected]” set snmp-name = myDXserver set snmp-location = myOffice
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.
You can start the SNMP utility using 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.
9–8 eTrust Directory Administrator Guide SNMP and the Directory Monitoring MIB
SNMP Example 2 Starting the SNMP MIB Walker dxsnmp –r localhost/19389
The following is a sample output: $ dxsnmp localhost/19389
sysDescr : CA eTrust DXserver sysObjectID : 1.3.6.1.4.1.3327.20.0.0 sysUpTime : 8323.00 sysContact : [email protected] sysName : democorp sysLocation : http://www.ca.com sysServices : 0 dsaAnonymousBinds.1 : 11 dsaUnauthBinds.1 : 0 dsaSimpleAuthBinds.1 : 0 dsaStrongAuthBinds.1 : 8 dsaBindSecurityErrors.1 : 0 dsaInOps.1 : 99 dsaReadOps.1 : 0 dsaCompareOps.1 : 0 dsaAddEntryOps.1 : 0 dsaRemoveEntryOps.1 : 0 dsaModifyEntryOps.1 : 0 dsaModifyRDNOps.1 : 0 dsaListOps.1 : 0 dsaSearchOps.1 : 30 dsaOneLevelSearchOps.1 : 20 dsaWholeTreeSearchOps.1 : 0 dsaReferrals.1 : 0 dsaChainings.1 : 0 dsaSecurityErrors.1 : 0 dsaErrors.1 : 11 dsaMasterEntries.1 : 0 dsaCopyEntries.1 : 0 dsaCacheEntries.1 : 0 dsaCacheHits.1 : 0 dsaSlaveHits.1 : 0
SNMP Example 3 Monitoring multi-write replication
This is only displayed if multi-write replication is enabled.
The following is a sample output: dxRemoteDsaName.1 : DSA2 dxMWQueueLength.1 : 1 dxMWStatus.1 : 2 (failed) dxMWPendingRemote.1 : 0 dxMWConfirmedLocal.1 : 1 dxRemoteDsaName.2 : DSA3 dxMWQueueLength.2 : 0 dxMWStatus.2 : 1 (ok) dxMWPendingRemote.2 : 0 dxMWConfirmedLocal.2 : 0 dxRemoteDsaName.3 : DSA4 dxMWQueueLength.3 : 5 dxMWStatus.3 : 2 (failed) dxMWPendingRemote.3 : 0 dxMWConfirmedLocal.3 : 5
Monitoring the Directory 9–9 SNMP and the Directory Monitoring MIB
SNMP Example 4 Monitoring DXserver statistics
The dxStatsNoTicks and dxStatsBusy items only appear if stats logging is enabled.
The following is a sample output: dxStatsAssocs : 1 dxStatsNilCredit : 0 dxStatsNoTicks : 1 dxStatsQueue : 3 dxStatsBusy : 2 dxStatsOps : 11
SNMP Example 5 Monitoring Dxcache
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.
The following is a sample output: dxCacheStatus : 3 (cache_ok) dxCacheSize : 456789 dxCacheSearchHits : 15 dxCacheMisses : 10
Configuring the SNMP Trap Destination
Deliver Alarms as To configure the delivery of alarms as SNMP traps, use the following console SNMP Traps command: set snmp-log = udp host port port;
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.
9–10 eTrust Directory Administrator Guide SNMP and the Directory Monitoring MIB
Send Traps About By default, all alarms are sent to the trap destination. However, you can Any Update configure the DXserver to send traps that contain information about any update Operations 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.
Monitoring the Directory 9–11 CMIP and X.700 Management
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.
CMIP Example 1 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/port [psap]
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–12 eTrust Directory Administrator Guide CMIP and X.700 Management
CMIP Example 2 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.
The following is a sample output: $ dxcmip localhost/19389 objectClass : 2.5.30.2.0 nameBinding : 2.5.30.3.0 packages : (Not decoded) commonName : DSA accessPoint : (Not decoded) masterEntries : 0 copyEntries : 0 loopsDetected : 0 securityErrors : 0 nameErrors : 1 foundLocalEntries : 41 referrals : 0 serviceErrors : 0 aliasDereferences : 0 chainings : 0 invalidReferences : 0 unableToProceed : 0 outOfScope : 0 noSuchObject : 1 aliasProblem : 0 aliasDereferencingProblem : 0 affectsMultipleDSAs : 0 unavailableCriticalExtension : 0 timeLimitExceeded : 0 sizeLimitExceeded : 0 adminLimitExceeded : 0 maxSizeLimit : 0 maxTimeLimit : 0 prohibitChaining : False readOpsProc : 0 compareOpsProc : 0 abandonOpsProc : 38 listOpsProc : 0 searchOpsProc : 30 search1levelOpsProc : 20 searchSubtreeOpsProc : 0 addOpsProc : 0 removeOpsProc : 0 modifyOpsProc : 0 modifyDNOpsProc : 0 readOpsProc : 0 compareOpsProc : 0 abandonOpsProc : 0 listOpsProc : 0 searchOpsProc : 0 search1levelOpsProc : 0 searchSubtreeOpsProc : 0 addOpsProc : 0 removeOpsProc : 0 modifyOpsProc : 0 modifyDNOpsProc : 0 dSAScopeOfReferral : 0 dSAScopeOfChaining : 0
Monitoring the Directory 9–13 CMIP and X.700 Management
peerEntityAuthenticationPolicy : 0 requestAuthenticationPolicy : 0 resultAuthenticationPolicy : 0 dSPAssociationEstablishment : 0 dOPAssociationEstablishment : 0 dISPAssociationEstablishment : 0 maxDAPAssociations : 0 maxDSPAssociations : 0 maxDOPAssociations : 0 maxDISPAssociations : 0 dAPAssociationTimeout : 0 dSPAssociationTimeout : 0 dOPAssociationTimeout : 0 dISPAssociationTimeout : 0 dSAActiveAssociations : 0 pagedResultsMaxIDs : 0 pagedResultsTimer : 0 supportedApplicationContexts : (Not decoded)
9–14 eTrust Directory Administrator Guide
Chapter 10 Using DXconfig
DXconfig is a configuration editor that lets you view and edit all of the DXserver configuration files on a single computer. DXconfig is run from a web browser, which lets you configure DXserver remotely.
DXconfig uses the text configuration files as its only input and output, so it is completely compatible with, and interchangeable with, text editing of the configuration files.
Connecting to DXconfig
You can access DXconfig from any computer by using a web browser.
Note: Only one person can connect to DXconfig at a time.
Tip: To start DXconfig locally on Windows, click Start on the taskbar, and then choose Programs, eTrust Directory, DXconfig.
To connect to DXconfig manually: 1. Start your web browser. 2. Enter http://server: port number/cocoon/dxconfig/start.html in the URL field, where: – server is the name of the server on which DXconfig is installed. – port number is the number of your eTrust Directory web server port. The standard eTrust Directory installation uses 8080 as the default. The DXconfig Start page is displayed. 3. Do one of the following: – If you are using DXconfig for the first time, choose Use FRESH Copy of the Config. – If you want to continue from a previous session, choose Use EXISTING Copy of the Config.
Note: DXconfig uses working copies of the configuration files. Copy the modified files to the live configuration area ($DXHOME/config) when you submit the changes.
Using DXconfig 10–1 The DXconfig Browser
The DXconfig Browser
The DXconfig browser comprises two panes:
■ Navigation pane ■ Content pane
The Navigation pane contains high-level commands such as List DXservers and List Packages. The Navigation pane is always present, and you can resize it by dragging the divider bar.
The Content pane is the work area. This is where you display and edit configuration details. Any changes made in this pane affect the local copy of the configuration files and do not take effect until you submit them to the live configuration area. See Submitting Changes in this chapter for more information.
10–2 eTrust Directory Administrator Guide Packages
Packages
DXconfig groups configuration commands in packages. This lets you create a number of simple packages and then group them together in a higher-level package. For example, you can group together limits configuration commands: # size limits set max-users = 255; set credits = 5; set max-local-ops = 100; set max-dsp-ops = 100; set max-op-size = 200; set multi-write-queue = 200;
# time limits set max-bind-time = none; set user-idle-time = 3600; set max-op-time = 600;
in a simple package called limits1.dxc.
You can create a higher-level package containing this package, plus other packages and commands. A complete package that contains the entire configuration of a DXserver can then be generated. A complete package will typically include small packages that are shared between multiple DXservers of that type.
A package is in fact a file. The term package is used to emphasize the concept of grouping. You can group low-level commands in whatever classification is appropriate to your application. You can then group low-level packages, and possibly commands, into higher-level packages, and so on.
Naming Packages
Packages are stored in the %DXHOME%\config or $DXHOME/config directory, and named by their subdirectory and file name. For example, an access configuration file has the name access\filename.dxc, where filename is the name of the file. File extensions are dxi, dxc or dxg; however, use other extensions if required, for example, dxa, dxb.
DXconfig uses the following convention:
■ dxc for packages that contain commands ■ dxg for grouping a number of dxc or other packages ■ dxi for runnable DXserver packages in the servers subdirectory
Using DXconfig 10–3 Packages
Displaying All Packages
The All Packages page appears when you log on to DXconfig. It displays all packages from the config directory and its subdirectories. From this page, you can choose to add a new package or edit an existing package. You can display this page at any time by selecting List Packages. Alternatively, you can select List DXservers to display all DXserver packages.
Adding a Package
You can add a package from the All Packages page by selecting Add New Package. In the Add New Package dialog, enter the package name and any comments.
When you create a new package it is an empty container. To add packages, items, and values to it, you must select the package from the All Packages page.
Adding Comments
You can add comments to:
■ A package ■ A simple command ■ A complex command ■ Single line items in a complex command
All comments entered via DXconfig are stored in the text configuration files as comment text. Comment text is added to a text configuration file by preceding the comment with a hash (#) on each line.
DXconfig adds a hash to a single line comment automatically; however, when you enter multi-line comments, you must enter the additional hash at the start of each line.
When DXconfig displays comments from an existing text file, it automatically applies the following rules:
■ Package comments are those at the start of a package, terminated by a blank line or the first command
■ Command comments are those before the command (and after the previous command)
10–4 eTrust Directory Administrator Guide Packages
Editing a Package
To edit a package, select the package from the All Packages page to display the package contents. The contents can be other packages or commands. When you select another package, a list displays all commands or packages in that package, and so on. Eventually, a package will contain only commands.
Once a package is displayed, you can copy it by selecting Copy Package, or delete it by selecting Delete Package.
You can edit the contents of a package as follows:
■ Select Add Item to add an item
■ Select Reorder Items to reorder the items
■ Select Comment in the table to edit the package comment
■ Select alongside an item to delete it
■ Select the link for an item in the table to edit the value or comment for that item
Note: Item refers to a simple command, a complex command, or a package within a package. See Adding an Item for more information.
When you add a new command, DXconfig displays an Item Editor for that command.
When you select a complex command such as set dsa, access control commands, or schema commands, a summary page appears. You can then select a particular item from that page for editing.
The idea in DXconfig is to drill down from higher levels to lower levels until the lowest level of detail is reached.
Note: Items in the set dsa command must be in a fixed order; however, DXconfig does not enforce this.
Using DXconfig 10–5 Packages
Adding an Item
An item can be one of the following:
■ A package ■ A simple command ■ A complex command
Within a complex command, an item is an element of that command, for example, within set dsa, trust-flags is an item.
To add a new item, select Add Item from the Package Contents page to display a list of the items.
Select the item that you want to add, and then click .
Selecting a Package
The list of Packages contains all available packages. When you add a package, it is sourced from the current package.
Selecting a Simple Command
The list of simple commands displays all available simple commands. When you add a simple command, an edit dialog for that command appears with the default values.
10–6 eTrust Directory Administrator Guide Packages
Selecting a Complex Command
The list of complex commands displays all available complex commands. When you add a complex command, a summary page appears for that command initialized with arbitrary template values. The initial template does not show all available items. You can add other items by selecting Add Item. When this is selected, only items for that command appear in the selection list. Adding an item to a simple command behaves the same as adding a simple command to a package, with one difference—saving the completed complex command must occur before calling the parser, which performs error checking.
Item Editor
The Item Editor is used for editing simple commands and items that are part of a complex command.
The Item Editor varies depending on the syntax of that item. For example, the Item Editor for max-users only contains one free-form text box; however, the Item Editor for trust-flags contains multiple defined choices. The trust-flags Item Editor is as follows:
The browser checks some input, such as ensuring numeric input for numeric items. When you save the command, the DXserver parser is run at the Web server host and this performs a more thorough check. Errors from the parser are displayed in the list table for that package.
For items that permit multiple values, a plus (+) button is provided to add additional values to that item.
Using DXconfig 10–7 DXservers
DXservers
A DXserver exists if it has knowledge defined using the set dsa command.
A DXserver is runnable if it has an initialization file (or package) called %DXHOME%\config\servers\dsa-name.dxi, where dsa-name is the name of the DXserver. We call this a DXserver package. A runnable DXserver attempts to start when the dxserver start all command is initiated from DXserver.
DXconfig has introduced the idea of a DXserver package that is not runnable. The page that lists DXserver packages lets you toggle a DXserver between being runnable and not runnable. A non-runnable DXserver will not start; however, it is a package that you can build and save, and make runnable later. It is implemented by renaming a dsa-name.dxi file to dsa-name.dxg. This seemingly trivial facility encourages a configuration methodology of creating a hierarchy of common packages that are used by multiple DXservers.
Adding a DXserver
A DXserver requires knowledge (a set dsa command, typically the only command in a package in the knowledge subdirectory), and a DXserver package in the servers subdirectory.
You can add a new DXserver package by selecting Add DXserver. Alternatively, you can copy and edit an existing DXserver package.
To add knowledge, create a new package from the All Packages window and add a set dsa command to it, or copy and edit an existing DXserver knowledge package.
To make the DXserver runnable, from the DXserver Packages window, you must check the Runnable? box for that DXserver.
For a DXserver that is already runnable, checking the Runnable? box (which has a tick in it) makes the DXserver not runnable. This is achieved by renaming its extension to .dxg.
10–8 eTrust Directory Administrator Guide Submitting Changes
Submitting Changes
Whatever changes you make in the content pane will not take effect until you submit them to the live configuration directory. To submit the changes, from the Navigation pane select Submit.
Note: To apply the changes to a currently running DXserver you must reinitialize the DXserver.
Using DXconfig 10–9
Chapter 11 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: DB 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 Ingres II and OpenIngres, unless one or the other is explicitly specified.
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 11–1 DB Tools
DB Tools
The database tools provide a set of utilities that simplify the creation and management of directory databases and the DSA tables.
The database tools are:
Tool Description 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 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
Important! The RDBMS (Advantage Ingres) must be running for the database tools to execute successfully.
11–2 eTrust Directory Administrator Guide DB Tools
Creating a DSA: dxnewdsa
You can create a new DSA configuration with the dxnewdsa utility 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.
Using DXtools 11–3 DB Tools
Creating a Database: dxnewdb
You can create a new database with the dxnewdb utility using 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.
Add Multiple To add multiple extensions, run dxextenddb multiple times. After you added all Extensions the required extensions, you must run dxtunedb with either the -relocate or -full option, for example: su – ingres dxextenddb demo1 /local/ingres location2 dxextenddb demo1 /local/ingres location3 su – dsa dxtunedb -relocate demo1
Important! To run dxextenddb, you must be logged in as the Advantage Ingres user.
11–4 eTrust Directory Administrator Guide DB 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
where dbname is the name of the database.
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.
Using DXtools 11–5 DB 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:
■ dbname is the name of the database ■ +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 demo (no journaling) dxbackupdb +journal demo (journaling is turned on) : dxbackupdb demo (journaling is still on) : dxbackupdb -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.
11–6 eTrust Directory Administrator Guide DB 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|-journal] dbname
where:
■ dbname is the name of the database
■ + journal turns journaling on
■ - journal turns journaling off
Tip: The restore recovers the database only from the last checkpoint. We therefore recommend that you perform daily backups, usually at night. When performing a restore, all DSAs that connect to the database must be shut down.
Using DXtools 11–7 DB 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
where dbname is the name of the database.
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.
11–8 eTrust Directory Administrator Guide DB Tools
Managing Indexes: dxindexdb
The dxindexdb utility is used to add, clear or list:
■ 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]]
where dbname is the name of the database.
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.
List Indexed Attributes, To list the currently indexed attributes, certificate/crl components and give a Certificate/crl list of attributes and components for indexing, specify dxindexdb with only the Components 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...)
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
Using DXtools 11–9 DB Tools
Add Reverse-Index To create one or more reverse-index attributes, use the -reverse option followed Attributes 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 To create one or more certificate component indexes, use the -cert option Component Indexes 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 To create one or more CRL component indexes, use the -crl option followed by Index 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.
Add Reverse and When both reverse and component indexing is required, a single command Component Index 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
11–10 eTrust Directory Administrator Guide DB Tools
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 When both reverse and wide indexing is required, use the following command: Wide Index dxindexdb demo -reverse attribute1 attribute2 -wide attribute1 attribute2
Using DXtools 11–11 DB Tools
Displaying Database Statistics: dxstatdb
The dxstatdb utility displays statistics of a particular database. The dxstatdb utility has the following format: dxstatdb [-cert] dbname
where dbname is the name of the database.
List Database Statistics You can list the statistics for the database by using the following command: dxstatdb dbname
The following is a sample output: Statistics: Number of attributes types = 27 Number of entries = 104472 Number of node entries = 4424 Number of leaf entries = 100048 Number of alias entries = 0 Number of level 1 entries = 12 Number of level 2 entries = 58 Number of level 3 entries = 341 Number of level 4+ entries = 104061 Number of values = 709281 Number of blob (>2K) values = 0
List Certificate You can list the statistics for the certificates stored in the database by using the Statistics following command: dxstatdb -cert dbname
The following is a sample output: Certificate Statistics: Number of userCertificate = 1 Number of userCertificate issuers = Not Indexed Number of expired userCertificate = Not Indexed Number of not yet valid userCertificate = Not Indexed
When there are CA Certificates and CRLs in the directory, the following output is displayed: Certificate Statistics: Number of userCertificate = 1 Number of userCertificate issuers = Not Indexed Number of expired userCertificate = Not Indexed Number of not yet valid userCertificate = Not Indexed
Number of cACertificate = 1 Number of cACertificate issuers = 0 Number of expired cACertificate = 0 Number of not yet valid cACertificate = 0
Number of certificateRevocationList = 1 Number of certificateRevocationList issuers = Not Indexed Number of expired certificateRevocationList = Not Indexed Number of not yet valid certificateRevocationList = Not Indexed
Note: In the example output, the CA Certificate has a component index.
11–12 eTrust Directory Administrator Guide DB Tools
Listing Existing Databases: dxlistdb
List Databases Owned The dxlistdb utility lists the databases owned by the user. (The user must be a by User 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 You can test for the existence of a particular database by specifying the database Existence 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: 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.”
This command is generally used only during installation.
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 11–13 DB Tools
Loading a Database: dxloaddb
Use the dxloaddb utility to load or reload a database from a prepared LDIF file.
This utility used to use schema.txt file to get schema information. In Directory 4.1, it now loads schema information directly from the DSA. This means that you now have to specify the DSA name when you use dxloaddb. 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” -P Hashes or encrypts passwords if in clear text: 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 -I "not-searchable Disables the loading of attributes that are not searchable into the search table,
11–14 eTrust Directory Administrator Guide DB 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 dxloaddb will use. If you do not include this option, dxloaddb 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 (as many times as needed) dxloaddb
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 “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 11–15 DB 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. In Directory 4.1, 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 dxloaddb.
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.
11–16 eTrust Directory Administrator Guide DB 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.
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 (dxserver start).
Using DXtools 11–17 LDIF Tools
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 ■ dbname is the name of the database 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.
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
11–18 eTrust Directory Administrator Guide LDIF Tools
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
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
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.
Using DXtools 11–19 LDIF Tools
DXtools Example 2 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
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.
11–20 eTrust Directory Administrator Guide LDIF Tools
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.
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.
Using DXtools 11–21 LDIF Tools
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.
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.
11–22 eTrust Directory Administrator Guide LDIF Tools
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]
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 old.ldif old_sorted.ldif ldifsort ref.ldif ref_sorted.ldif ldifdelta old_sorted.ldif ref_sorted.ldif | dxmodify -h oldhost
Using DXtools 11–23 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.
11–24 eTrust Directory Administrator Guide 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 old.ldif old_sorted.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:
■ 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.
Using DXtools 11–25 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 DXsearch DXrename Directory 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.
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.
11–26 eTrust Directory Administrator Guide DAP Tools
Option Value -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). -l timelim Time limit (in seconds) of search.
Tip: If you enter a command with -H (or any nonexistent option), usage and option information is displayed.
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.
Using DXtools 11–27 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).
11–28 eTrust Directory Administrator Guide 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: organizationalPerson oc: newPilotPerson oc: quipuObject cn: Murray HORSFALL sn: HORSFALL title: Information Technology Manager telephone: 797 8877 description: Replacements mail: [email protected] 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]
Using DXtools 11–29 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.
11–30 eTrust Directory Administrator Guide DAP Tools
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, we 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 - 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
Using DXtools 11–31 DAP Tools
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: organizationalPerson 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: [email protected] postalAddress: 7-11 Fine Street$Penville CA postalCode: 32750
Run the following dxmodify command: dxmodify -a -c -h hostname:19389 -f staff.ldif
11–32 eTrust Directory Administrator Guide 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: organizationalPerson 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: [email protected] postalAddress: 173 Toorak Rd $ South Yarra postalCode: 3066
Using DXtools 11–33 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: dxloaddb Creates and loads a database from a prepared LDIF file dxdumpdb Extracts data from the database to an LDIF file
11–34 eTrust Directory Administrator Guide 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 eTrust dxschemaldif ldif2dxc dxschematxt Directory LDIF Directory schema.txt Schema Schema
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 11–35 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.
11–36 eTrust Directory Administrator Guide 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 11–37 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
11–38 eTrust Directory Administrator Guide 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 11–39 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 abConfig- oid, 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 efConfig- oid, it will assign it an OID of 1.22.333.444.21, etc.
11–40 eTrust Directory Administrator Guide 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 11–41 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.
11–42 eTrust Directory Administrator Guide
Chapter 12 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 certificate based authentication.
eTrust Directory is a fully functional LDAP-compliant directory that lets you use all the features of JXplorer.
Using JXplorer 12–1 The JXplorer Browser
The JXplorer Browser
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.
12–2 eTrust Directory Administrator Guide The JXplorer Browser
Menu Bar
The menu bar provides the following functions:
Menu Item Function File Menu 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 Menu 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. Copy DN Sends the DN of the current entry to the clipboard. New Adds a new entry under the selected position. View Menu 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 Menu Add Bookmark Adds a bookmark. Edit Edits a bookmark. Bookmark Lists all bookmarks.
Using JXplorer 12–3 The JXplorer Browser
Menu Item Function Search Menu 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 Menu 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 Menu Confirm Tree Ops Enables a safety mode, which prompts you to confirm modifications before they are made. Confirm Table Editor Enables a confirmation dialog, which appears after Updates you make a change to the directory. Ignore Schema Stops the browser checking that the user’s input Checking 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 Menu Stop Action Cancels the current browser operation. Security Menu Trusted Servers and Displays the options for server-only authentication. CAs Client Certificates Displays the options for client and server authentication. Advanced Keystore Displays the options for setting up keystores. Options
12–4 eTrust Directory Administrator Guide The JXplorer Browser
Menu Item Function Help Menu 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 12–5 The JXplorer Browser
Quick Search Bar
The quick search bar lets you execute simple searches quickly.
The search bar contains the following items:
Item Function Attribute List Lets you select search attributes from a user- configurable pull-down list of commonly used attributes. You can add new attributes. Operator List Lets you select an operator from a list of basic operators: equal (=), not equal (!(=)), less than or equal (<=), greater than or equal (>=), and approximately equal (~=). For more information about searching, look in Chapter 13 in the User Guide. Search Term Lets you enter a search value. Quick Search button Executes your search.
12–6 eTrust Directory Administrator Guide The JXplorer Browser
Directory Tree Display
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
Select the view you want by clicking on the appropriate tab at the top of the directory tree.
Using JXplorer 12–7 The JXplorer Browser
Entry Display
The entry display pane (the right pane) displays the currently selected directory entry, either in an HTML template (Html view), or in an editable attribute/value table (Table Editor view).
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.
12–8 eTrust Directory Administrator Guide The JXplorer Browser
Next, the same employee record is displayed in the table editor. In addition to the current attributes of this entry, all other possible attributes of the entry are displayed. Attributes in bold represent mandatory attributes that must be present for the entry to be valid. The editor also provides the Properties button, which you can click to display the operational attributes such as the date of the last modification.
Using JXplorer 12–9 Browsing a Directory
Browsing a Directory
With JXplorer, you can browse any LDAP-compliant directory. This section describes the browsing functions available.
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.
12–10 eTrust Directory Administrator Guide Browsing a Directory
The browser requires the following information to make a connection. For more information, click Help.
■ 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.
■ 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.
Using JXplorer 12–11 Browsing a Directory
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. Double- click 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.
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
The browser provides a range of search types, from simple, quick searches to arbitrary complex searches that you can save to search_filters.txt as filters. It displays search results as complete directory trees, letting you browse large numbers of search results or save them as LDIF files.
Using the Quick Search Bar
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.
12–12 eTrust Directory Administrator Guide Browsing a Directory
Performing Complex Searches
You can perform more complex searches using the Search dialog.
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 create complex searches with the aid of the filter constructor and 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
Using JXplorer 12–13 Browsing a Directory
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, the browser lets you save complex searches as filters for later use. With saved searches, you can:
■ 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 search limits, that is, 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.
12–14 eTrust Directory Administrator Guide Browsing a Directory
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, since not all servers implement full schema publishing.
The Schema pane lets you examine:
■ Attribute Definitions, including: – Names – X.500 OIDs – Attribute syntaxes – Syntax descriptions – A flag showing whether the attribute is single valued – General descriptions (if available)
■ Class Definitions, including: – 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, including – 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.)
Using JXplorer 12–15 Browsing a Directory
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.
Displaying an Entry
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.
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.
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
12–16 eTrust Directory Administrator Guide Editing the Directory
Table Viewer
The table editor is generally used for editing data, but it can also function as a simple, but robust, entry viewer. 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.
In addition, you can configure the table viewer to include custom binary editors, which may be the only way to view complex or user-specific binary data.
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.
Using JXplorer 12–17 Editing the Directory
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
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.
12–18 eTrust Directory Administrator Guide Editing the Directory
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.
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.
Using JXplorer 12–19 Editing the Directory
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.
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 right- clicking 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.
12–20 eTrust Directory Administrator Guide Editing the Directory
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, right- click 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.
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.
Using JXplorer 12–21 Editing the Directory
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.
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.
12–22 eTrust Directory Administrator Guide Editing the Directory
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.
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.
Using JXplorer 12–23 Editing the Directory
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.
12–24 eTrust Directory Administrator Guide Editing the Directory
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:
■ 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 JXplorer 12–25 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
12–26 eTrust Directory Administrator Guide Using SSL and SASL
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.
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.
Using JXplorer 12–27 Using SSL and SASL
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.
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.
12–28 eTrust Directory Administrator Guide Online Help
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:
■ An index of help topics that explain browser usage ■ A table of contents ■ Links to external web resources
Browser Configuration
The browser is highly configurable, which lets you:
■ Customize HTML templates ■ Configure browser panels ■ Use a variety of logging and tracing options ■ Customize directory tree icons ■ Use plug-in binary editors
Using JXplorer 12–29 Browser Configuration
View Menu
The View menu lets you access the toolbar configuration and refresh options.
Toolbar Configuration
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 interfaces are:
■ Microsoft Windows ■ Motif/X Windows ■ Java
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.
12–30 eTrust Directory Administrator Guide Browser Configuration
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.
Using JXplorer 12–31 Browser Configuration
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 Logs internal tree operations, and other high-level Operations 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.
You can set these options from the Advanced Options dialog, which can be 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.
12–32 eTrust Directory Administrator Guide Browser Configuration
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.
You can set these options from the Advanced Options dialog, which can be 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.
Using JXplorer 12–33 Browser Configuration
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.
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.
You can set these options from the Advanced Options dialog, which can be 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.
12–34 eTrust Directory Administrator Guide Browser Configuration
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
These extension tags:
■ Positions individual attribute names and values in the page ■ Lists of all attribute names and values to be set with a single tag ■ Provides a variety of tabulated formatting options, such as HTML tables and lists
See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
Using JXplorer 12–35 Browser Configuration
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. See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
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. See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
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. See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
Plug-in Entry Editors
JXplorer can be extended to load small Java programs, similar to Web applets, based on an entry’s object class. See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
12–36 eTrust Directory Administrator Guide Browser Configuration
Internationalization
You can localize JXplorer by using the language resource files in the languages directory. See the Configuration Documents in JXplorer docs.zip, provided on the installation CD for more information.
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:
■ 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.
Using JXplorer 12–37
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
Connecting to JXweb
You can access JXweb by using a web browser.
Tip: To start JXweb on Windows locally, click Start on the taskbar, and then choose Programs, eTrust Directory, DXmanager. On the displayed page, click JXweb.
To connect to JXweb manually from a web browser: 1. Start your browser. 2. Enter http://server:port number/jxweb/index.html as the URL, where: – server is the name of the server on which JXweb is installed – port number is the number of the JXweb port. The standard eTrust Directory installation uses 8080 as the default. The browser displays the JXweb Connect dialog.
Using JXweb 13–1 Connecting to a Directory
Connecting to a Directory
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.
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.
13–2 eTrust Directory Administrator Guide Online Help
Online Help
The online help system provides procedures for common tasks. It includes an index of topics, and links to external Web resources.
Using JXweb 13–3
Chapter 14 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://supportconnect.ca.com/ for assistance.
Deploying a Directory 14–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.
14–2 eTrust Directory Administrator Guide 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
Deploying a Directory 14–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:
■ 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
14–4 eTrust Directory Administrator Guide Operations and Practices
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.
Operations and Practices
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
Deploying a Directory 14–5 Operations and Practices
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.
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 utility dxrestoredb.
See the chapter Using DXtools for more information about backup and restore tools.
14–6 eTrust Directory Administrator Guide Operations and Practices
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.
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
Deploying a Directory 14–7 Operations and Practices
Change Control
There are some basic principles of change management required to ensure the ongoing consistency of the directory:
■ 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.
14–8 eTrust Directory Administrator Guide 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).
Deploying a Directory 14–9 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 (dxdumpdb). 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.
14–10 eTrust Directory Administrator Guide
Chapter 15 UDDI Registry
Universal Description, Discovery and Integration (UDDI) is an evolving standard interface to information about services. A UDDI repository is a directory of businesses and the services they offer.
In a UDDI repository, 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/).
UDDI Registry 15–1 eTrust Directory UDDI Registry eTrust Directory UDDI Registry
The eTrust Directory UDDI Registry 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 Registry provides access to the repository through the UDDI 2.0 API. (For information about the API, open index.html under the uddi-sample, help directory.) The web-based UDDI Web Client enables users to:
■ Publish services to the repository. ■ Search for specific entries in the repository.
15–2 eTrust Directory Administrator Guide Connecting to UDDI Web Client
Connecting to UDDI Web Client
To connect to UDDI Web Client, enter the following URL at your web browser: http://web-service-host:8080/uddi-browser-sample
The browser displays the UDDI Web Client Connect page.
Connecting to UDDI Servers
The UDDI Web Client Connect page enables you to connect to a UDDI server. By default, when you click Connect, the connection is to the server local to the UDDI Web Client. When you want to connect to a server on a different host, enter the following in the Inquiry URL and the Publish URL fields before you click Connect: http://server-host:8080/uddi-sample/services/Inquiry http://server-host:8080/uddi-sample/services/Publishing
When you want to change servers after you have connected, click Connect on the menu bar.
UDDI Registry 15–3 Searching the Repository
Searching the Repository
You can search the repository by business or by tModel. Specify your search criteria, and click Submit. The discovered entries are displayed in the left pane of the UDDI Search Page. For information about how to set up a search, click Help.
To view the contents of a returned entry, click it.
To perform a new search, click Business Search or tModel Search.
Publishing to the Repository
You can publish your services by adding them to the repository. Click Publish Login on the menu bar, and log in.
Note: When you are logging in for the first time, you must register by clicking the link at the bottom of the Publish API Login page and complete the displayed User Register Page.
The entries that you can work on are displayed in the left pane. To expand an entry, click .
The right pane displays the attributes of a selected entry, if any. To update a value, click .
For more information about how to use the UDDI Web Client to publish, click Help.
Publishing a Service
Before you can publish a service, you must register the business that provides that service. To register a business, click the BusinessEntity folder in the left pane and then click the Add Business button on the displayed Edit Business Entity page.
After you register the business, you can add services to it. You can also add contacts for potential customers.
For each service, you can add bindings that provide access points for potential customers to obtain additional information.
15–4 eTrust Directory Administrator Guide Publishing to the Repository
Using tModels
A tModel is a data structure representing a service type (a generic representation of a registered service) in the UDDI registry. 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.
Adding a tModel
To add a tModel, click the tModel folder in the left pane and then click the Add tModel button on the displayed Edit tModel page.
UDDI Registry 15–5
Appendix A The DUA Command Set
For most operations on the directory, use the GUI applocations, including JXplorer.
For large administration tasks, you can use the DUA to run batch operations and tests on the DSA.
The commands described here fully implement every aspect of every X.500 service and form the basis for testing DXserver. You can consult the test scripts released with DXserver for various examples of any given service.
This appendix briefly explains each X.500 service. See the X.500 standards documentation for full details of the services. The X.500 service commands covered are:
■ bind-req ■ unbind-req ■ abort-req ■ read-req ■ search-req ■ compare-req ■ abandon-req ■ list-req ■ add-entry-req ■ mod-entry-req ■ rem-entry-req ■ mod-dn-req
The DUA Command Set A–1 Connecting and Disconnecting
Connecting and Disconnecting
From the management console or remote DUA command line, you must first connect to the DSA using the bind service. A bind remains active until it is:
■ Released by the user using the unbind service ■ Aborted as the result of a network failure ■ Shut down by the DSA (if a time limit expired) ■ Shut down by the system administrator (using abort users) ■ Shut down as a result of the DSA being shut down
Connecting with the Management Console
When you enter the bind command at the management console, the system treats it as if it had come from a remote DUA. You can have a command as simple as an anonymous login using the command: bind-req;
After you enter the command, the dsa> prompt returns immediately, and a short time later the BIND CONFIRM message appears. The console interface is asynchronous (that is, you can enter commands at any time, and the responses return whenever they complete).
When you enable authentication, you must also supply the user and password fields as part of the command. For example: bind-req user =
The user field supplies the DN of the user initiating the bind. You cannot have aliases in the DN (see the X.500 standard). Enter the password as a string.
The DSA checks both the name and password, so you must supply a password when you supply a name.
A–2 eTrust Directory Administrator Guide Connecting and Disconnecting
Configuring the Scripting DUA
DXserver comes with a number of utilities, one of which is the scripting DUA. The following file initializes the DUA and connects it to the DSA specified by the remote-addr in the bind request. # DXcli Startup Script Sample #open-log "dxcli.log" ; # keep a record of session #echo-on # output commands to log
# Include schema definitions. source "../schema/schema.dxg"; # schema rules
# Automatically log on, for convenience bind-req user =
When using the scripting DUA utility, the prompt is dua>.
Disconnecting From the DSA
You can disconnect from the DSA using one of the following methods.
Unbind Request You can issue an unbind request command at any time. The system discards any unfinished operations on the association, and closes the connection. unbind-req;
Because the management console supports multiple associations (for every bind request it creates a new pseudo user), an unbind request reverts to the previous user. This is similar to the way you can superimpose UNIX shells over the top of one another.
Abort Request You can also issue an abort request; this drops all communication immediately, regardless of what is in progress. abort-req;
The DUA Command Set A–3 Inquire Services
Inquire Services
The operations used for retrieving or comparing information are: Read Extracts information from a given entry Compare Compares a supplied value against the values stored in an entry List Lists the immediately subordinate entries of a given entry Search Searches a portion of the DIT for entries of interest Abandon Abandons one of the previous operations
You can use each of the inquire services (read, compare, list, and search) to resolve aliases (see Aliases in this appendix), and you can give each a time limit.
All the examples have string values delimited by double quotes (whether required or not) to help distinguish between attributes and their values.
Read Service
You can return all or selected information from a single entry using the read service.
DXconsole Example 1 Read Service
To read an entry: read-req entry =
The command returns all attributes and values, for example: Entry:
You can use the attr-only option, the attrs = .... option, or both to return selective information (see Entry Information Selection in this appendix).
See the test scripts for more examples.
A–4 eTrust Directory Administrator Guide Inquire Services
Compare Service
The DSA uses the compare service for password checks, but you can use them for comparing any provided information with the contents of a directory entry.
DXconsole Example 2 Compare Service
To compare a telephone number: compare-req entry =
When the DSA finds the attribute and value provided by the compare request in the entry, the compare service returns an assertion TRUE. When it does not find them, the compare service returns an assertion FALSE.
When the DSA does not find the entry or the attribute, a compare-refused message is returned. See the test scripts for more examples.
List Service
You can use the list service to obtain a list of immediate subordinates for an entry.
DXconsole Example 3 List Service
To list from the root: list-req entry = <>;
List from organizational unit Corporate under organization DemoCorp: list-req entry =
The list result returns the relative distinguished names of the objects immediately under the list object.
When the DSA has knowledge references to other DSAs, the list makes these references visible. For example, when the domain of the DSA is AU/DemoCorp and you define a remote DSA US/OpenDirectory, a list at the root returns both AU and US and a list under US returns OpenDirectory. (See Knowledge References in the chapter “Distribution and DSP” for more information.)
See the test scripts for more examples.
The DUA Command Set A–5 Inquire Services
Search Service
The search service lets you locate entries of interest on a portion of the DIT.
A search is either as simple as locating a base object or as complex as selecting objects in a portion of the DIT that satisfy a complex search filter involving checking for the existence of multiple attributes and values in a particular combination.
The search (and list) services can return many objects, but if you reach a size limit or time limit or if you receive an abandon request, you can interrupt the services. In this case, they may return partial results (the objects they collected before interruption).
A search is successful when it can find its base object (where to begin the search). The system ignores invalid aliases or attributes, or other problems encountered while filtering entries. A search returns no information when none of the entries matches the given filter.
Search is a very powerful service, and the following are examples demonstrating a variety of capabilities.
DXconsole Example 4 Search Service for One Entry
Simulate a read and retrieve all attributes and values of an entry using search: search-req base-object =
Tip: The default scope of a search is base-object-only.
DXconsole Example 5 Search Service for Single Level
Simulate a list and retrieve the names of all objects from one level under DemoCorp using search: search-req base-object =
A–6 eTrust Directory Administrator Guide Inquire Services
DXconsole Example 6 Search Service for Subtree
Search all objects under (and including) DemoCorp, retrieving all objects that contain an attribute surname with a value of Smith, and retrieve all information contained in those entries: search-req base-object =
DXconsole Example 7 Search Service for Local Directory Tree
Search the local directory tree, retrieving all objects that contain a surname attribute with a value of Smith and a title attribute with a value of Manager and a telephoneNumber attribute. You retrieve only the commonName, surname, and telephoneNumber attributes of the objects matching the search filter. search-req base-object = <> whole-subtree filter = { and {attr = surname value = “Smith”, attr = title substrings [ any “Manager”], attr = telephoneNumber present} } attrs = commonName, surname, telephoneNumber common-args = { local-scope };
You can turn off the resolution of aliases during a search by setting the dont- search-aliases flag in the search service.
You can receive selected information for each entry that matches the search filter using attr-only and attrs = ... (see Entry Information Selection in this appendix).
LDAP-only examples
These commands are supported by the LDUA, which is the LDAP version of the DUA. Because the LDUA uses the LDAP protocol, it has access to LDAP controls, which allow operations to be modified. For example, the search command can include server-side sorting and paged results.
DXconsole Example 8 Search and Sort Results
Search all objects under DemoCorp, retrieving all objects with common name beginning with H, and sort the objects in reverse order by description: search-req base-object=
The DUA Command Set A–7 Inquire Services
DXconsole Example 9 Search and Page Results
Search all objects under DemoCorp, retrieving all objects that contain an attribute common name beginning with H, and page the results: search-req base-object=
DXconsole Example 10 Search and Sort and Page Results
These LDUA commands can be used together. The following example searches all objects under DemoCorp, retrieves all objects that contain an attribute common name beginning with H, and sorts and pages the results: search-req base-object=
Abandon Service
You can stop an inquire service in process by using the abandon service.
Abandon stops the request having the specified invoke-id (or the last request if no invoke-id is given) and returns any partial results up to the time of the abandon request, for example: abandon-req invoke-id-to-abandon = 1234;
An abandon confirmed message is returned when you abandon the operation. If the operation completes or you cannot abandon it, then an abandon refuse message is returned.
A–8 eTrust Directory Administrator Guide Update Services
Update Services
Services that update the DIT are: Add Adds a leaf entry Remove Deletes a leaf entry Modify Adds or removes attributes or attribute values (not distinguished values) of any entry Modify-DN Changes the name of any entry
None of these services returns any data—only a confirmation or an error message is returned. The format of the confirmation or error message returned to the management console depends on the tracing modules activated at the time.
For all update services:
■ The DSA does not resolve aliases; the system ignores the dont-deref-aliases common argument.
■ Size limit is not relevant because no results return; the system ignores the size-limit common argument.
■ You cannot abandon them.
See the X.500 standards for details.
The remove service must occur at a leaf entry (the entry at the end of a branch of the DIT).
You can delete a subtree only by deleting leaves recursively.
The DUA Command Set A–9 Update Services
Add Service
You can add entries under any existing entry (or root, if it is a first-level DSA). The entry you add must obey the name-binding rules in force and the attributes in the entry must obey the object-class rules of that entry.
All attribute types in an add request must be unique.
DXconsole Example 11 Add Service for Single Entry
To add an entry: add-entry-req entry =
Multivalue attributes let you record more than one value in a single attribute. The telephoneNumber attribute in the example contains two values.
You can define some attributes with schema as single-valued (for example, postalCode).
The postalAddress is a multi-line attribute with each new line separated by a period in the grammar.
The naming attribute and its value—
In the next example, a multivalue attribute commonName has the value John Smith used for naming. The commonName attribute must be present in the contents of the add request so that you can add the value J SMITH.
A–10 eTrust Directory Administrator Guide Update Services
DXconsole Example 12 Add Service for Multivalue Naming Attribute
To add an entry with a multivalue naming attribute: add-entry-req entry =
In the previous examples, the object-class values are depicted as strings. We can just as easily use the equivalent object-class identifiers (for example, 2.5.6.7).
See the test scripts for more examples.
Remove Service
You can remove leaf entries from the directory.
DXconsole Example 13 Remove Service for Organizational Unit
To remove an organizational unit Sales from under organization DemoCorp: rem-entry-req entry =
DXconsole Example 14 Remove Service for Organization
To remove the organization OpenDirectory from under root: rem-entry-req entry =
See the test scripts for more examples.
The DUA Command Set A–11 Update Services
Modify Service
The modify service lets you add or remove attributes and values.
DXconsole Example 15 Modify Service to Add Attributes
To add a fax number (attribute and value) to organizational unit Corporate under organization DemoCorp: mod-entry-req entry =
DXconsole Example 16 Modify Service to Add and Remove Attributes
To add another phone number (value) for John Smith under organization DemoCorp under country AU, while removing one of his common names (the nondistinguished value—J SMITH): mod-entry-req entry =
An attribute (in an entry) must have at least one value present. Removing the last value automatically removes the attribute. You cannot remove mandatory attributes.
When an attribute already exists, you cannot add the same attribute again. You can add additional (multi-) values to an existing attribute. Thus, the order in which you add or remove entries within one modify service is important.
Note: Some attributes are single-value attributes. Attempting to add a second value to a single-value attribute results in an error.
See the test scripts for more examples.
A–12 eTrust Directory Administrator Guide Update Services
Modify-DN Service
The modify-DN service lets you rename an entry. Renaming a non-leaf entry changes the distinguished name of all entries under it.
In the modify-DN service, the system supplies a new RDN along with an option to delete the old RDN. If you do not delete the old RDN, it becomes part of the normal attribute (its values are no longer distinguished).
DXconsole Example 17 Modify-DN Service for Entry
To change the name of the organizational unit R&D (under organization DemoCorp) to Research & Development:: mod-dn-req entry =
You can now move an entry and all of its subordinates to a different place in the tree, using this option: new-superior =
The following example moves the R&D entry and all of its subordinates from AU,Democorp to under the entry AU, DemoCorp, Corporate.
DXconsole Example 18 Modify-DN Service to Move the Entry and Any Sub-Entries mod-dn-req entry =
You can change the case of a value (for example, DemoCorp to DEMOCORP) using the modify-DN service if you set the delete-old option. Although the matching rules treat the two values as identical, their raw values are different, which prevents a duplicate value error from occurring.
DXconsole Example 19 Modify-DN Service to Change Case of a Value
To change the case of a value: mod-dn-req entry =
The DUA Command Set A–13 Common Arguments
See the test scripts for more examples.
Common Arguments
The size-limit service control is only applicable to list and search operations. It indicates the maximum number of objects returned. search-req base-object =
When you reach a size limit, the service returns that number of objects and the qualifier: Partial Outcome: Size Limit Exceeded
Also refer to the administrative limit max-op-size, usually set in the configuration file, which can conditionally override this service control.
Time Limit
The time-limit service control is only applicable to read, compare, list, and search operations. It indicates the maximum number of seconds that a service takes for execution. The time limit has a granularity of one second. However, a time limit of zero can still result in a successful operation (because the DSA may process the operation in less than one second). search-req base-object =
In some cases, when a time limit expires, partial results may not return. For example, when a list takes three seconds to return 100 subordinates, then a time limit of one or two seconds can result in an error with no subordinates returned: Partial Outcome: Time Limit Exceeded
Also refer to the administrative limit max-op-time, usually set in the configuration file, which can conditionally override this service control.
A–14 eTrust Directory Administrator Guide Common Arguments
Other Controls
The system provides support for all other X.500 common arguments. These include service control flags:
■ prefer-chaining ■ chaining-prohibited ■ local-scope ■ dont-use-copy ■ dont-deref-aliases
and the service modifiers:
■ priority ■ scope-of-referral
See the test scripts for more details.
Entry Information Selection
You can control the amount of entry information returned by read and search operations by using attr-only or attr-and-vals options.
DXconsole Example 20 EIS for Attribute Types
To read all attribute types only: read-req entry =
The command returns all attributes but no values, for example: Entry:
Note: Returning both attributes and values is the default setting for returning entry information.
You can select which attributes to return. The read service returns an error if it does not find attributes in the entry.
The DUA Command Set A–15 Common Arguments
DXconsole Example 21 EIS for Attributes and Values To read selected attributes and values: read-req entry =
Note: The default for returning entry information is all attributes.
Operational Attributes In addition to the entry information selection controls, you can possibly receive extra entry information with the read and search operations. This information is the operational attributes associated with each entry. Using the all-extra-attrs or extra-attrs options returns the operational attributes.
DXconsole Example 22 OpAttrs for All Attributes To read an entry returning all operational attributes: read-req entry =
A–16 eTrust Directory Administrator Guide Aliases
DXconsole Example 23 OpAttrs for Selected Attributes
To read an entry returning selected operational attributes: read-req entry =
The command returns attributes and values of the entry, plus the requested operational attributes: Entry:
When you enable the op-attrs operational control, operational attributes are added to an entry automatically when it is created or modified: set op-attrs = true;
Aliases
Some entries at the leaves of the DIT are alias entries, while all other entries are object entries. Alias entries point to object entries or other alias entries and thus provide an alternative name for the corresponding object. The DXserver DSA resolves alias entries to the distinguished name of the object entry to which they point (the actual object).
Aliases interplay with many aspects of a DSA. For more information, see the following sections for more details:
■ Name bindings and aliases (see Managing Schema in the chapter “Schema Definition” for more information)
■ Access controls and aliases (see Other Security Features in the chapter “Security” for more information)
The DUA Command Set A–17 Aliases
Reading an Alias
Aliases resolve during navigation (the starting point for any service). This means that the alias object is transparent to the user. When you make a read request of an alias, the object read is the object to which the alias points.
To let a user read the alias object (as opposed to what it points to), you need a mechanism. You can turn off alias resolution during navigation with the X.500 service control dont-deref-aliases.
DXconsole Example 24 Reading an Alias
To read an alias object: read-req entry =
Adding an Alias
Adding an alias uses the normal add entry request. You must supply the object class alias and the attribute aliasedObjectName. Any attribute that satisfies the name binding between the alias and its parent can name the alias.
DXconsole Example 25 Adding an Alias
To add an alias: add-entry-req entry =
Important! When the DSA has alias integrity enabled and you add an alias, the object to which the alias points must exist within the domain of the DSA, and the DSA must be able to navigate to the object entry.
A–18 eTrust Directory Administrator Guide Aliases
Deleting an Alias
You can delete aliases using the normal remove-entry request.
DXconsole Example 26 Deleting an Alias
To delete an alias: rem-entry-req entry =
Tip: When the DSA has alias integrity enabled and you delete an object entry with an alias entry pointing to it, both the object entry and the alias entry are deleted.
The DUA Command Set A–19 Aliases
Modifying an Alias
You can modify alias entries using the normal modify request. When you change the aliasedObjectName attribute, the alias points to a different entry.
DXconsole Example 27 Modifying an Alias
To modify an alias: mod-entry-req entry =
Even though the DSA permits modification of the object class attribute, you cannot make a non-alias entry an alias entry. To perform such a modification, first delete the entire entry and then re-add it as an alias (see the X.500 standard).
Important! When the DSA has alias integrity enabled and you modify an alias entry so that it points to a new object entry, the DSA must be able to navigate to the new object entry for the modify to succeed.
A–20 eTrust Directory Administrator Guide
Appendix B DXserver Command Language
This appendix lists the configuration commands used by DXserver. There are five command categories. Each command category consists of a number of valid commands. Some commands also have additional parameters. For example, set admin-user = own-entry is made up of the set category, the admin-user command, and the own-entry parameter.
Command Categories
Command Description clear Clears a portion of the configuration information. The following word defines what is being cleared. 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. The following word defines which log is being closed. set Defines something. The word after indicates what is being defined. This is the most important command. You can set many different things. source Specifies a file to be loaded. This is used to make configurations using multiple files. trace Enables tracing. The following words specify what type of tracing is enabled.
DXserver Command Language B–1 Clear Commands
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 eTrust Directory Administrator Guide 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.
DXserver Command Language B–3 Set Commands
Command Description 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. 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 dsa-database-threads Apportions threads (up to 25) between complex and simple searches, and updates. 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 fe-threads Specifies the number of DSA threads to be used for receiving and sending operations and responses. The default is 0 (not threaded). 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.
B–4 eTrust Directory Administrator Guide Set Commands
Command Description 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. 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 compatability. set multi-casting See set multi-chaining. set multi-chaining Specifies whether requests are chained to other DSAs. set multi-write-disp- Enables or disables multiwrite DISP. The default recovery value is FALSE. set multi-write-queue Specifies the maximum size of the queue of requests to be written to other DSAs.
DXserver Command Language B–5 Set Commands
Command Description 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-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-max- Sets the number of seconds after which a suspension 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 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.
B–6 eTrust Directory Administrator Guide Set Commands
Command Description 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- A means whereby a bind can be allowed to skip the check server authentication step if it has already 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.
DXserver Command Language B–7 Set Commands
Command Description 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. This only works for LDAP clients. Default value is FALSE. 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 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.
B–8 eTrust Directory Administrator Guide Set Commands
set admin-user Command Parameters
Use the set admin-user command to specify static access controls. See the chapter “Security” for more information.
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.
DXserver Command Language B–9 Set Commands
set agreement Command Parameters
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–10 eTrust Directory Administrator Guide Set Commands
set attribute Command Parameters
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- Indicates whether the attribute has multiple values valued (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.
DXserver Command Language B–11 Set Commands
set dsa Command Parameters
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. 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 Specifies the port number for the console for this DSA. When this is not specified, the DSA does not have a local console.
B–12 eTrust Directory Administrator Guide Set Commands
Parameter Description remote-console-port Specifies the port that accepts remote connections for the console for the DSA. When this is not specified, there is no remote console for the DSA. remote-console-ssl Encrypts console sessions where the console may be attached to from a remote host. console-password Specifies the password required when connecting to the console. 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 multi-write, 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, allow-downgrading, and no-server- credentials.
DXserver Command Language B–13 Set Commands
Parameter Description 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.” set name-binding Command Parameters
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 named-by.
B–14 eTrust Directory Administrator Guide Set Commands
set object-class Command Parameters
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.
DXserver Command Language B–15 Set Commands
set protected-items Command Parameters
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 Lists attributes to which this access control applies. 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. 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 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. set public-user Command Parameters
Use the set public-user command to specify static access controls. See the chapter “Security” for more information.
Parameter Description attrs Lists attributes to which this access control applies. entry Specifies an entry to which access is granted. 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. validity Specifies the period during which this is valid. May include start, end, on.
B–16 eTrust Directory Administrator Guide Set Commands
set reg-user Command Parameters
Use the set reg-user command to specify static access controls. See the chapter “Security” for more information.
Parameter Description attrs Lists attributes to which this access control applies. entry Specifies an entry to which access is granted. 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 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 user to be treated as a reg-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.
DXserver Command Language B–17 Set Commands
set super-user Command Parameters
Use the set super-user command to specify static access controls. See the chapter “Security” for more information.
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 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.
B–18 eTrust Directory Administrator Guide 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 =
DXserver Command Language B–19 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, or 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–20 eTrust Directory Administrator Guide
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 provides explanations and suggested actions for some of the more common alarms and warning messages. For further information, contact Computer Associates at http://supportconnect.ca.com/.
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.
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 database- related problems than the DXserver alarm log.
Note: Throughout this guide, references to Advantage Ingres include both Ingres II and OpenIngres, unless one or the other is explicitly specified.
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
C–2 eTrust Directory Administrator Guide DXserver Alarm Messages
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–3 DXserver Alarm Messages
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–4 eTrust Directory Administrator Guide DXserver Warning Messages
DXserver Warning Messages
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–5 Alias Errors
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.
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–6 eTrust Directory Administrator Guide 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 http://supportconnect.ca.com/.
Messages and Logs C–7 Advantage Ingres Errors
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.)
Some possible errors with their solutions are:
■ E_LQ0001 Failed to connect to DBMS session—Determine whether Advantage Ingres is running (for example, use the UNIX command ps).
■ E_US000C You are not a valid Ingres user—As 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—Run the DSA from the UNIX user account dsa.
■ E_US0028 Could not open the iidbdb database—Check that you installed Advantage Ingres by running the Advantage Ingres command ingbuild.
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.
C–8 eTrust Directory Administrator Guide
Appendix D Installing DXserver for Windows
This appendix explains how to install the DXserver software (including Advantage Ingres) for Windows systems.
Note: Throughout this guide, references to Advantage Ingres include both Ingres II and OpenIngres, unless one or the other is explicitly specified.
Installation Overview
eTrust Directory 4.1 is backward-compatible with all earlier versions.
To install the DXserver you must perform the following activities: 1. Check system and space requirements 2. Install Java Runtime if you require JXplorer and/or DXwebserver 3. Install or upgrade eTrust Directory components 4. Install, keep existing, or upgrade Advantage Ingres 5. Run the sample scripts 6. Install the technology previews (optional)
The eTrust Directory distribution provides a setup program that automates these activities. This program checks whether Advantage Ingres, or any of the eTrust Directory components are already installed. It then upgrades existing components if required.
The remainder of this chapter provides detailed procedures for completing these installation activities.
Installing DXserver for Windows D–1 Check System and Space Requirements
Check System and Space Requirements
System Requirements
The minimum system requirements are:
Requirement Description
Operating ■ Windows 2000 SP2 system ■ Windows XP Professional 5.1
■ Windows .Net 2003 Server Hardware An Intel Pentium or higher computer with a CD-ROM drive
Software ■ Java Runtime Environment 1.4 (provided on the eTrust Directory installation CD)
■ Winsock-compatible TCP/IP installed and configured
■ Adobe Acrobat Reader 5.1 to view the documentation (provided on the eTrust Directory installation CD) RAM At least 256 MB of RAM
Hard disk ■ At least 400 MB for the DXserver and Advantage Ingres II space product files (including sample databases)
■ Sufficient hard disk space for the directory data Permissions Windows administrator access to the system
For production systems with very large databases or where maximum performance or fault-tolerance is required, consult Computer Associates at http://supportconnect.ca.com/ for advice on choosing server and disk configurations before installing this product.
D–2 eTrust Directory Administrator Guide Check System and Space Requirements
Space 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.
DXserver and Advantage Ingres require 250 Mb of disk space for the product files.
For production systems, you should store databases on a separate physical disk from the Advantage Ingres installation for both performance and recovery reasons. Therefore, in the following table, the drive: partition indicates a separate physical disk.
You can have a single physical disk partitioned into multiple drives. Because it is important for recovery and performance that you 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.
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.
The following table shows the layout of a typical installation:
File System Component C: DXserver product files Advantage Ingres product files Advantage Ingres transaction log drive Directory information (database files) Advantage Ingres checkpoints (database backups) Advantage Ingres journals Advantage Ingres work area
For more information regarding disk configurations such as mirrored disks and RAID, contact Computer Associates Technical Support at http://supportconnect.ca.com/.
Installing DXserver for Windows D–3 Check System and Space Requirements
Check That the Machine Has Adequate Disk Space 1. Double-click My Computer and choose View, Details.
2. Check the Free Space columns for the drive on which you want to install the product files, and the drive you want to use for your directory information (the database files) to be sure there is adequate space.
D–4 eTrust Directory Administrator Guide Install eTrust Directory Components
Install eTrust Directory Components
If you are upgrading from an earlier version of eTrust Directory, you should back up your schema files first.
See http://support.ca.com/etrustdir_supp.html for detailed upgrade information.
The following table lists the components that you can install. For a description of all of the eTrust Directory modules, see the table in the eTrust Directory Modules section in Chapter 1.
Component Description DXserver The eTrust Directory server. Its installation also includes the following: ■ DXtools ■ DXconsole Advantage Ingres Advantage Ingres Intelligent Database, which is required by DXserver if the data repository is used. If there is an existing version of Advantage Ingres installed on your computer, the Setup wizard gives the option of upgrading to the latest version of Advantage Ingres. JXplorer To run JXplorer, you need the Java Runtime Environment, which is provided on the eTrust Directory product CD. Dxwebserver Clients and tools consisting of the following:
■ DXconfig
■ DXmanager
■ JXweb
■ UDDI Web Client Note: When you select DXwebserver, the following components are also installed: DXconfig, DXmanager, JXweb, and UDDI Server and UDDI Web Client.
To install the eTrust Directory components: 1. Install JRE 1.4 from the Supporting Products list in the eTrust Directory Product Explorer. eTrust Directory 4.1 Dxwebserver and JXplorer require Java Runtime Environment (JRE) 1.4, which must be installed first. 2. Stop all applications that may have current open connections to an Advantage Ingres database. 3. Log in as a user with Administrator privileges. Insert the eTrust Directory CD. The Product Explorer starts automatically.
Installing DXserver for Windows D–5 Install eTrust Directory Components
If the Product Explorer does not start automatically, click on autorun.inf in the top-level directory of the CD. Alternatively, you can use Windows Explorer to navigate to …\dxserver\windows on the CD and run dxsetup.exe from there. 4. Navigate to DXserver for Windows and click Install. 5. Follow the installation instructions. By default, all components will be installed. If you wish to install a subset only, choose Custom Setup. See the previous table for a list of the components and what they contain. 6. Select options for the components you are installing. eTrust Directory components are installed under C:\Program Files\CA\eTrust Directory and Advantage Ingres under: C:\Program Files\CA\Advantage Ingres [ET]. Note that you can change these locations in a custom setup. If you are an advanced user, you can click the Options button to configure some aspects of Advantage Ingres.
Tip: You may want to set the Advantage Ingres log folder to a different disk drive for improved performance.
7. 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. At this point, you may want to use the Back button to review your selections before finalizing the installation. 8. When the installation is complete, it automatically starts the Advantage Ingres Intelligent Database service, and runs the sample scripts (only if selected). The samples are run in a default install, but not in a default upgrade from a previous eTrust Directory version.
You do not have to reboot your computer after installation.
D–6 eTrust Directory Administrator Guide Install eTrust Directory Components
Ports Used During DXwebserver Installation
The DXwebserver installation uses the following five ports by default:
■ 8080 (HTTP 1.1)
■ 8081 (HTTP 1.0)
■ 8443 (HTTP SSL)
■ 8009 (AJP13)
■ 8008 (WARP)
These default ports may conflict with existing ports on the machine on which DXwebserver is being installed.
If DXwebserver Does Not Start
Check the logs under the DXwebserver installation directory for port conflicts. Look for this file in: C:\Program Files\CA\eTrust Directory\DXwebserver\logs
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: 1. Install Dxwebserver as usual. 2. Look for this file: C:\Program Files\CA\eTrust Directory\DXwebserver\conf 3. In the server.xml file, look for the Connector section:
If the Main HTTP (8080) Connection Port Number Is Modified
If the main HTTP (8080) connection port number is modified, then the Start menu shortcuts to DXmanager will be affected. The new port number should also be noted for future HTTP connections.
Installing DXserver for Windows D–7 Run the Sample Scripts
Run the Sample Scripts
eTrust Directory provides a number of sample directories, which contain different DSA configurations and show different methods of populating a directory. The installation process lets you choose whether to install those sample directories. This section describes the sample scripts, and explains how to run the scripts manually.
There are further samples in the subdirectories of %DXHOME%\samples on Windows. To configure each sample, run setup.bat on Windows. See the readme.txt in the samples directory for more information.
The schema used by the DemoCorp sample has changed since Version 3.6 SP 2. Therefore, it is recommended that you 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.
Democorp
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.
To set up the democorp directory: 1. Log in as the DXserver administrator (if you have not already done so). 2. Open a command prompt window. 3. Configure and populate the directory using the setup batch file: C:\> cd “%DXHOME%\samples\democorp” C:\> setup The batch file automatically configures and starts the DemoCorp DSA. The data is loaded by a front-end load using the dxmodify DAP tool. After loading, the database is tuned using the dxtunedb tool. Once started, use one of the eTrust Directory browsers to browse the DemoCorp data.
D–8 eTrust Directory Administrator Guide Run the Sample Scripts
UNSPSC
The UNSPSC sample demonstrates a back-end load of the directory using the dxloaddb tool.
To set up the UNSPSC directory: 1. Log in as the DXserver administrator (if you have not already done so). 2. Open a command prompt window. 3. Configure and populate the directory using the setup batch file: C:\> cd “%DXHOME%\samples\unspsc” C:\> setup The batch file automatically configures and starts the UNSPSC DSA. The data is loaded using the dxloaddb bulk load tool. Once started, use one of the eTrust Directory browsers to browse the UNSPSC data.
Router
The Router sample demonstrates a router DSA configuration, where the DSA has no database, but has knowledge of two subordinate DSAs (democorp and UNSPC).
To set up the router directory: 1. Log in as the DXserver administrator (if you have not already done so). 2. Open a command prompt window. 3. Configure and populate the directory using the setup batch file: C:\> cd “%DXHOME%\samples\router” C:\> setup The batch file automatically configures and starts the Router DSA. Once started, use one of the eTrust Directory browsers to browse the directory. When the DemoCorp and UNSPSC DSAs are also started, their data is visible through the Router DSA connection. This demonstrates chaining between DSAs using the DSP protocol.
Installing DXserver for Windows D–9 Silent Installation
Silent Installation
You can install eTrust Directory silently (or unattended), provided JRE 1.4 has been installed.
Important! Read the license agreements in the Licenses for Third-Party Products Appendix before running the unattended installation and only proceed if you agree.
■ From …\CD ROM drive\dxserver\windows, run the following command: dxsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=ALL ETRDIR_DXSERVER_SAMPLES=0
This will install eTrust Directory with all components (JXplorer, DXwebserver, DXplorer, Advantage Ingres, DXserver, DXconsole), but the directory samples will not be automatically configured. All components are installed to the default location.
Alternatively, you can select the components to install with any combination of the following command line options:
ADDLOCAL Values
Note: Values have to be exact.
Value Description ALL All components are installed CA_LICENSE CA license. Must be added with DXserver and Ingres DXServer Dxserver, must also use CA_LICENSE IngresDBMS,IngresNet Installs Ingres 2.6 ET Dxplorer Dxplorer, x500(Dap) browser JXplorer JXplorer (requires JRE 1.4) DXwebServers Tomcat, MUST have JRE 1.4 or install will fail. Some samples require dxserver JXweb Web based LDAP client (requires DxwebServers) TeraTerm Console application for tracing DXserver ETRDocumentation eTrust Directory Documentation
D–10 eTrust Directory Administrator Guide Silent Installation
Additional arguments
Argument Value Description ETRDIR_DXSERVER_SAMPLES 1 DXserver samples will be setup during install 0 DXserver samples are installed but not configured (default) ETRDIR_SHORTCUTS 1 All start menu shortcut are installed (default) 0 No start menu shortcuts are installed ETRDIR_SILENT_INSTALL 1 No prompts will be displayed, install log will be in %DXHOME% ETRDIR_DXPLORER_DESTINATION
Installing DXserver for Windows D–11 Embedded Installation
Optional Silent Installation Examples
■ To install only DXwebserver and the eTrust Directory documentation to the default location, run the following command: dxsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=DXwebServers,ETRDocumentation
■ To install DXserver, Advantage Ingres 2.6 [ET] and ca licensing to the default location, run the following command on one line: dxsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=DXServer,IngresDBMS,IngresNet,CA_LICENSE ETRDIR_DXSERVER_SAMPLES=1
■ To install only JXplorer to the specified installation directory, run the following command: dxsetup ETRDIR_SILENT_INSTALL=1 ADDLOCAL=JXplorer ETRDIR_JXPLORER_DESTINATION=f:\Mynewdirectory\jxplorer
■ If a file path includes spaces, surround the path with quotes. For example: ETRDIR_JXPLORER_DESTINATION=”f:\My new directory\jxplorer”
Embedded Installation
eTrust Directory can now be installed as an embedded product so that other CA products can use its features in their product.
This means that other CA products can install eTrust Directory using their own unique caller ID. Then, if eTrust Directory needs to be removed, the customer can remove it without removing anything that the embedding CA product requires.
Only one product can use a particular caller ID. They must also never change this caller ID. Each caller ID will be mapped to an upgrade Guid, but this will not have any affect on anyone else’s instance of eTrust Directory. They must also use this caller ID to uninstall eTrust Directory.
Embedding users should add two extra command-line parameters when running dxsetup:
Parameter Description ETRDIR_DXSERVER_EMBEDDED=1 Lets (Dxserver) the black box know that we will be using an embedded directory. CALLER_ID=
For example, to install eTrust Directory as eTrust Directory Web Access Control: dxsetup ADDLOCAL=ALL ETRDIR_DXSERVER_EMBEDDED=1 CALLER_ID=ETWAC
To find out which caller ID's are supported, contact CA Support.
D–12 eTrust Directory Administrator Guide Install the Technology Previews (Optional)
Uninstalling eTrust Directory After an Embedded Installation
The caller ID must be used to uninstall eTrust Directory.
The uninstall process will determine what components were installed by the caller and then will uninstall only those components. If other products are using those components as well, they will not be removed until the last caller performs an uninstall.
For example, to uninstall eTrust Directory as ETWAC, use: dxsetup REMOVE=ALL ETRDIR_DXSERVER_EMBEDDED=1 CALLER_ID=ETWAC
Install the Technology Previews (Optional)
DSML This version includes a technology preview of a Directory Services Markup Language (DSML) server, which allows you to connect to eTrust Directory’s sample router with the DSML 2.0 protocol. To start the DSML server, you must set it up by running setup in the %DXHOME%\..\dxwebserver\samples\dsml directory. After this, you can use JXplorer to connect to this DSML server by using the following connection settings:
Setting Value Host The computer name of the machine running the DSML server Port 8080 Protocol DSML v2 DSML Service dsml-sample/services/DSML
UDDI
This release includes a technology preview of the Universal Description, Discovery and Integration (UDDI) server and browser. To try the UDDI server, you must set up its server by running setup in the %DXHOME%\..\dxwebserver\samples\uddi directory.
Installing DXserver for Windows D–13 Upgrading Advantage Ingres
Upgrading Advantage Ingres
eTrust Directory embeds Advantage Ingres II 2.6. The Advantage Ingres RDBMS installation performs a standard tuning of the database parameters. You can customize these parameters in some installations.
eTrust Directory 4.1 does not force you to upgrade any existing pre-2.6 Advantage Ingres installation. If you are 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.
If you choose to upgrade, your Advantage Ingres installation code and all your existing databases will be converted to “ET”.
The eTrust Directory installation implements the following:
■ If you say No to the upgrade prompt, the pre-existing Advantage Ingres installation will not be changed.
■ If eTrust Directory previously installed Advantage Ingres 2.6, this upgrade will apply the latest Advantage Ingres 2.6 SP 1 upgrade but keep the installation code that was used last time.
■ If the previous Advantage Ingres Installation is version 2.0 or 2.5 and you say Yes to the upgrade prompt, the Advantage Ingres 2.6 SP 1 upgrade will be applied and your Advantage Ingres installation code will be changed to “ET.”
■ If there is no previous Advantage Ingres installation, eTrust Directory will install Advantage Ingres [ET]. If you are upgrading from eTrust Directory 3.6 SP 2 or earlier, existing database schemas are automatically upgraded with the following command:
dxupgradedb database-name
where database-name is the name of the database to upgrade. This also applies if you installed eTrust Directory 4.1 after you installed any other eTrust product that embeds a pre-4.1 version of eTrust Directory. If you recover a pre-4.1 database from backup, you will have to run dxupgradedb manually.
D–14 eTrust Directory Administrator Guide
Appendix E Installing DXserver for UNIX
This appendix tells you how to install the DXserver software (including Advantage Ingres) for UNIX systems.
Note: Throughout this guide, references to Advantage Ingres include both Ingres II and OpenIngres, unless one or the other is explicitly specified.
Installation Overview
To install DXserver you must perform the following activities: 1. Check system and space requirements. 2. Verify CD-ROM accessibility. 3. Install eTrust Directory or upgrade from previous version. 4. Install the technology previews (optional).
The eTrust Directory distribution provides a setup program that automates the installation process. This program checks whether the following programs are installed, or are up-to-date:
■ Advantage Ingres
■ DXserver
■ DXwebserver − DXconfig − DXmanager − JXweb − UDDI Web Client
■ JXplorer
The remainder of this chapter provides detailed procedures for completing the installation activities.
Installing DXserver for UNIX E–1 Check System and Space Requirements
Check System and Space Requirements
System Requirements
The standard eTrust Directory 4.1 CD supports the following platforms:
Operating System Versions Solaris (Ultra SPARC) 7, 8, 9 Linux/Intel Red Hat 7.2, 7.3, 8.0
Additional ports for the following platforms are available on request from http://supportconnect.ca.com/:
Operating System Versions Linux/S390 with SuSse Kernel 2.4 (glibc 2.1.3) Linux/S390 with RedHat Kernel 2.4.9 (glibc 2.1.3) Solaris (Non-Ultra SPARC) 2.6, 7, 8 HP-UX 11.0, 11i AIX 4.3x (Dxserver only), 5.1
The minimum system requirements are:
Requirement Description Hardware CD-ROM drive
Software ■ Adobe Acrobat Reader 5.06 to view the documentation (provided on the eTrust Directory installation CD)
■ Java Runtime Environment (JRE) 1.4 (embedded in the eTrust Directory installation) RAM At least 256 MB of RAM
Hard disk ■ At least 500 MB hard disk space for the DXserver and space Advantage Ingres II product files (including sample databases)
■ Sufficient hard-disk space for the directory data Permissions Superuser (root) access to the system
E–2 eTrust Directory Administrator Guide Check System and Space Requirements
The person installing eTrust Directory should have general UNIX system administration skills.
For production systems with very large databases, or where maximum performance or fault-tolerance is required, please consult Computer Associates at http://supportconnect.ca.com/ for advice on choosing server and disk configurations before installing this product.
Space Requirements
The disk space required for directory information is approximately 20 times the raw data size. This provides space for backups, journals, indexing, tuning, importing, and pre-processing. In addition to this, you need the same amount of temporary disk space if you plan to bulk load data.
For production systems, you should store databases on a separate physical disk from the Advantage Ingres installation for both performance and recovery reasons. Therefore, in the following table, the …/local partition is on a separate physical disk.
The following table shows the layout of a typical installation:
File System Component /opt DXserver product files Advantage Ingres product files Advantage Ingres transaction log /local Directory information (database files) Advantage Ingres checkpoints (database backups) Advantage Ingres journals Advantage Ingres work area
For more information about disk configurations such as mirrored disks and RAID, contact Computer Associates Technical Support at http://esupport.ca.com/
Installing DXserver for UNIX E–3 Verify CD-ROM Accessibility
Verify CD-ROM Accessibility
You can install DXserver and Advantage Ingres from either a local CD-ROM drive, or a remote CD-ROM drive on the same network.
Verify Accessibility From Local CD-ROM Drive
To verify accessibility from a local CD-ROM drive: 1. Log in as root. 2. Insert the eTrust Directory CD into the CD-ROM drive. 3. Verify that the CD-ROM is auto mounted and accessible: # ls /cdrom/cdrom0/dxserver/unix/install If the command succeeds, the CD-ROM is accessible. If there is an error, verify that you entered the correct path; otherwise, the CD-ROM was not auto mounted, or it was not configured at start time. To make the CD-ROM drive visible, reconfigure the kernel by entering the following commands to restart the machine: # init 0 ok boot –r
Verify Accessibility From Remote CD-ROM Drive
To verify accessibility from a remote CD-ROM drive: 1. Log in to the server with the CD-ROM drive as root and verify accessibility from a local CD-ROM drive. See steps 1 to 3 in Verify Accessibility From Local CD-ROM Drive for the procedure. 2. Check that the nfs and mount daemons are running: cdhost# ps -ef | egrep ‘(nfsd|mountd)’ | grep –v grep If they are not running, enter: cdhost# /usr/lib/nfs/nfsd -a 16 cdhost# /usr/lib/nfs/mountd 3. Share the CD in the CD-ROM drive by entering: cdhost# share –F nfs –o ro /cdrom/cdrom0 4. Log in as root on the local server and mount the remote CD-ROM file system: # mkdir –p /cdrom/cdrom0 # mount –r cdhost:/cdrom/cdrom0 /cdrom/cdrom0 5. Verify that the CD-ROM is accessible on the local server by entering: # ls /cdrom/cdrom0/dxserver/unix/install
E–4 eTrust Directory Administrator Guide Verify CD-ROM Accessibility
Dismount a Remotely Mounted CD-ROM File System
■ To dismount a remotely mounted CD-ROM file system, enter: # unmount /cdrom/cdrom0
Eject CD
■ To eject the CD, enter the following command on the machine with the CD- ROM drive: # eject cd
Stop Sharing and Eject the CD-ROM
■ To stop sharing and eject the CD-ROM on the cdhost, enter: cdhost# unshare /cdrom/cdrom0 cdhost# eject cd
Installing DXserver for UNIX E–5 Install eTrust Directory
Install eTrust Directory
The DXserver installation program, dxsetup, is located on the eTrust Directory CD-ROM. When there is an existing Advantage Ingres installation on the system, you must stop Advantage Ingres before running the dxsetup program.
The Advantage Ingres installation performed by the dxsetup program is for a stand-alone RDBMS.
The dxsetup program will do the following: 1. Install DXserver 2. Install Advantage Ingres 3. Install JXplorer 4. Install DXwebserver (DXmanager and DXconfig, JXweb, and UDDI Web Client) 5. Configure DXserver
If you are installing eTrust Directory from a local disk, you must ensure that the parent directories have rx permissions for all users so newly added users (such as dsa and ingres) have permissions to access the tar files.
Note: You should never run dxserver as root. After installing eTrust Directory, you must log in as user ‘dsa’ before executing dxserver start all. Always make sure $DXHOME is defined before running dxserver.
The dxsetup program will ask a series of questions as the installation proceeds. In general, you should use the defaults.
E–6 eTrust Directory Administrator Guide Install eTrust Directory
Step 1 – Run dxsetup 1. Log in as root. 2. Run the dxsetup installation program: # cd /cdrom/cdrom0/dxserver/unix/install # ./dxsetup.sh
Alternatively, you can give the dxsetup program a parameter that specifies the location of the installation files. This lets you use an updated dxsetup program with an existing CD-ROM. To run dxsetup in this mode, use the following command: # ./dxsetup.sh –r /cdrom/cdrom0/dxserver/unix/
Component Default Directory DXserver /opt/CA/eTrustDirectory/dxserver Advantage Ingres /opt/CA/AdvantageIngresET/ingres Databases Databases /opt/CA/AdvantageIngresET/ingres JXplorer /opt/CA/eTrustDirectory/jxplorer DXwebserver /opt/CA/eTrustDirectory/dxwebserver JRE /opt/CA/eTrustDirectory/jre Documentation /opt/CA/eTrustDirectory/documentation Samples /opt/CA/eTrustDirectory/dxserver/samples - Router directory - DemoCorp directory - UNSPSC directory
Note: The component DXwebserver installs DXmanager, DXconfig, JXweb, and UDDI Web Client.
Installing DXserver for UNIX E–7 Install eTrust Directory
Step 2 – Accept the License Agreement
Before the installation begins you must agree to the license agreements. The following message is displayed: Do you agree, not agree, or want to view the license? (y/n/v) [v] When you select the default, the license is displayed. After viewing it, the message is displayed again. When you select n, dxsetup will exit. When you select y, the setup process continues.
Step 3 – Set Up UNIX Kernel (for Solaris)
1. The dxsetup program checks the kernel configuration. This check ensures that the …/etc/system file has the following settings. If any of the settings already exist in the file, their values are increased, if necessary, to those specified below: set semsy:seminfo_semmap=1 set semsys:seminfo_semmni=100 set semsys:seminfo_semmns=1000 set semsys:seminfo_semmnu=30 set semsys:seminfo_semms1=50 set semsys:seminfo_semopm=10 set semsys:seminfo_semume=10 set semsys:seminfo_semusz=96 set semsys:seminfo_semvmx=32767 set semsys:seminfo_semaem=16384 set shmsys:shminfo_shmmax=16000000 set shmsys:shminfo_shmmin=1 set shmsys:shminfo_shmmni=100 set shmsys:shminfo_shmseg=10 forceload: sys/semsys forceload: sys/shmsys If any of these values are changed, you must restart the system for the changes to take effect.
2. The dxsetup program asks if you want to restart the system. When you select n, dxsetup will exit.
E–8 eTrust Directory Administrator Guide Install eTrust Directory
Step 4 – Set Up DXserver
Note: If you are upgrading from a previous version of DXserver, see Upgrading from a Previous Version at the end of this appendix.
1. The dxsetup program asks if you want to install the DXserver software: Do you wish to install the DXserver software (y/n/i/q) [y]
Note: You can select option i for further information about DXserver.
2. When you select y, and you are installing DXserver for the first time, you are prompted for the name of the DXserver administrator’s account: Enter the name of the account to use/create [dsa] If the setup program finds an existing DXserver installation, it asks if you want to perform an upgrade.
If you select y, dxsetup moves the existing installation to a new directory under the existing path, and renames it with the existing version number, for example $DXHOME/etrdir3.6. If there is more than one copy of that version number, it takes the next available number, for example, $DXHOME/etrdir 3.6.1. 3. The account is created, and you are asked to enter a login shell and a password: Enter the login shell for the DSA account [/bin/csh] The DSA account requires a password New Password:
4. The dxsetup program then requests an installation directory for the DXserver: Please specify the DXserver installation directory /opt/CA/eTrustDirectory/dxserver] 5. Press Enter to specify the default directory (/opt/CA/eTrustDirectory/dxserver), or provide the full pathname for an alternate directory. 6. When you press Enter, the confirmation message will appear. The directory /opt/CA/eTrustDirectory/dxserver will be created. Do you wish to change the directory? (y/n) [n]
Important! Do not make the DXserver installation directory the same as the directory that you select for the Advantage Ingres installation in Step 4.
7. When you select a directory other than the default directory, dxsetup creates a symbolic link from /opt/CA/eTrustDirectory/dxserver to the selected directory.
Installing DXserver for UNIX E–9 Install eTrust Directory
Step 5 – Set Up Documentation
1. The dxsetup program asks if you want to install the documentation: Do you wish 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] The directory /opt/CA/eTrustDirectory/documentation will be created. Do you wish to change the directory? (y/n) [n] 3. When you select n, the documentation will be installed in the default directory (/opt/CA/eTrustDirectory/documentation).
Step 6 – Set Up Advantage Ingres
Note: If you are upgrading from a previous version of Advantage Ingres, see Upgrading Advantage Ingres in this appendix for more information.
1. The dxsetup program asks if you want to install the Advantage Ingres software: Do you wish to install the IngresII software (y/n/i/q) [y]
Note: You can select option i for more information about Advantage Ingres.
2. When 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 the dxsetup program finds an existing Advantage Ingres installation that is the same as the version you are installing, it checks for a patch. If it does not find one, or it is different, it asks if you would like to install the new patch.
If you select n, dxsetup bypasses the Advantage Ingres installation section. Ensure that you have adequate backups before performing an upgrade.
3. The account is created, and the dxsetup program requests an installation directory for the Advantage Ingres software: Please specify the IngresII 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. Do you wish to change the directory? (y/n) [n]
E–10 eTrust Directory Administrator Guide Install eTrust Directory
6. When you select a directory other than the default directory, dxsetup creates a symbolic link from …/opt/CA/AdvantageIngresET/ingres to the selected directory.
Important! Do not make the Advantage Ingres installation directory the same directory that you chose for the DXserver installation in step 3 above. 7. The installation program asks you if you want to specify separate locations for data, work, checkpoint, dumps, and journals. When you select Yes, you are asked to specify a separate location for each component. When you select No, the installation program asks you to specify the location of the Advantage Ingres database directory: Please specify the IngresII database directory [/local/CA/AdvantageIngresET] 8. Press Enter to specify the default directory (/local/CA/AdvantageIngresET), or provide the full pathname for an alternate directory. The directory /local/CA/AdvantageIngresET will be created. Do you wish to change the directory? (y/n) [n]
9. Enter n to specify the default directory. 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.
Important! The value entered as II_DATABASE in the Advantage Ingres installation (see the table in Custom Installation) must be the same as the value you enter here.
Note: eTrust Directory 4.1 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 plan to have many data DSAs running on the same machine, read the Increasing the Number of Database Connections in Appendix G.
Installing DXserver for UNIX E–11 Install eTrust Directory
Step 7 – Set Up Time Zone
You must now specify the Time Zone this installation is located in. to specify a Time Zone, you must first select the region of the world. 1. 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-AMECIA SOUTH-PACIFIC SOUTH-ASIA GMT-OFFSET Please enter one of the named regions: 2. You will then be asked to select from one of the time zones in the region. 3. When you enter one of the values, a confirmation message will appear. The Time Zone you have selected is: the value that you have chosen. Is this Time Zone correct? (y/n) [y] Enter y to confirm your choice.
Step 8 – Set Up JXplorer
1. The dxsetup program asks if you want to install JXplorer: Do you wish to install the JXplorer browser software? (y/n/i/q) [y]
Note: If you select this component you must also select JRE below. You can select option i for more information about JXplorer.
2. When you answer y, dxsetup asks where you want to install the software. The user specified in Step 3 – DXserver Setup owns the software.
E–12 eTrust Directory Administrator Guide Install eTrust Directory
Step 9 – Set Up DXwebserver
1. The dxsetup program asks if you want to install DXwebserver: Do you wish to install the DXwebserver software? (y/n/i/q) [y]
Note: If you select this component you must also select JRE below. You can select option i for more information about DXwebserver.
2. When you answer y, dxsetup asks where you want to install the software. The user specified in Step 3 – DXserver Setup owns the software.
3. The dxsetup program installs the DXwebserver product files into the directory selected in Step 3 – DXserver Setup.
Ports Used During DXwebserver Installation
The DXwebserver installation uses the following five ports by default:
■ 8080 (HTTP 1.1)
■ 8081 (HTTP 1.0)
■ 8443 (HTTP SSL)
■ 8009 (AJP13)
■ 8008 (WARP)
These default ports may conflict with existing ports on the machine on which DXwebserver is being installed.
If DXwebserver does Check the logs under the DXwebserver installation directory for port conflicts. not start Look for this file in: /opt/CA/eTrustDirectory/dxwebserver/logs
If a conflict occurs If a conflict occurs, you will need to modify the DXwebserver configuration file server.xml. 1. Look for this configuration file in: /opt/CA/eTrustDirectory/dxwebserver/conf 2. Search this file for the port numbers that are causing problems and replace them. 3. Restart DXwebserver to pick up the new port number.
If the main HTTP If the main HTTP (8080) connection port number is modified, then the Start (8080) connection menu shortcuts to DXmanager will be affected. The new port number should port number is also be noted for future HTTP connections. modified
Installing DXserver for UNIX E–13 Install eTrust Directory
Step 10 – Set Up JRE
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 specify the default directory [/opt/CA/eTrustDirectory/jre), or provide the full pathname for an alternate directory. The directory [/opt/CA/eTrustDirectory/jre will be created. Do you wish to change the directory? (y/n) [n] 3. Enter n to specify the default directory.
Step 11 – Install the Reboot Scripts
■ When you install DXserver, Advantage Ingres, or DXwebserver, the reboot scripts are installed automatically.
Step 12 – Set Up the Sample Directories
The DXserver distribution contains a number of example directories that contain different DSA configurations, and different methods of populating a directory.
1. you have installed Advantage Ingres, the dxsetup program asks if you want to install the sample directories: Do you wish to start the sample directories (y/n) [y]
2. n you select y, the samples will install automatically. When you select n, you can install them manually. The output of the samples can be viewed in etrdir_samples_setup.log.
Note: If you do not install Advantage Ingres, you cannot run the sample scripts, and the system displays an error message to this effect.
Install the UNSPSC The UNSPSC sample demonstrates a back-end load of the directory using the sample dxloaddb tool.
To set up the UNSPSC directory: 1. Log in as the DXserver administrator (if you have not already done so). By default, this is the dsa user. 2. Configure and populate the directory using the setup batch file: % cd $DXHOME/samples/unspsc % setup.sh The batch file automatically configures and starts the UNSPSC DSA. The data is loaded using the dxloaddb bulk-load tool. Once started, use one of the eTrust Directory browsers to browse the UNSPSC data.
E–14 eTrust Directory Administrator Guide Install eTrust Directory
Install the Democorp The Democorp sample models a fictitious company called DemoCorp. There sample 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.
To set up the Democorp directory: 1. Log in as the DXserver administrator (if you have not already done so). By default, this is the dsa user. 2. Configure and populate the directory using the setup batch file: % cd $DXHOME/samples/democorp % setup.sh The batch file automatically configures and starts the Democorp DSA. The data is loaded by a front-end load using the dxmodify DAP tool. After loading, the database is tuned using the dxtunedb tool. Once started, use one of the eTrust Directory browsers to browse the Democorp data.
Install the Router The Router sample demonstrates a router DSA configuration, where the DSA sample has no database, but has knowledge of two subordinate DSAs (Democorp and UNSPSC).
To set up the router directory: 1. Log in as the DXserver administrator (if you have not already done so). By default, this is the dsa user. 2. Configure and populate the directory using the setup batch file: % cd $DXHOME/samples/router % setup.sh The batch file automatically configures and starts the Router DSA. Once started, use one of the eTrust Directory browsers to browse the directory. If the Democorp and UNSPSC DSAs are also started, their data should be visible through the Router DSA connection. This demonstrates chaining between DSAs using the DSP protocol.
Installing DXserver for UNIX E–15 Silent Installation
Silent Installation
You can install eTrust Directory silently (or unattended).
Important! Read the license agreements in the Licenses for Third-Party Products Appendix before running the unattended installation and only proceed if you agree.
From /cdrom/cdrom0/dxserver/unix/install, do one of the following:
■ If installing locally, run the following command: ./dxsetup.sh –default
■ If installing from a remote CD drive, change from the current directory to the install directory and then run the dxsetup command.
Default installation will install eTrust Directory components automatically, with the default values listed below.
Component Default Directory DXserver /opt/CA/eTrustDirectory/dxserver Advantage Ingres Databases /opt/CA/AdvantageIngresET/ingres Databases /opt/CA/AdvantageIngresET/ingres JXplorer /opt/CA/eTrustDirectory/jxplorer DXwebserver /opt/CA/eTrustDirectory/dxwebserv er JRE /opt/CA/eTrustDirectory/jre Documentation /opt/CA/eTrustDirectory/documenta tion Samples /opt/CA/eTrustDirectory/dxserver/s amples - Router directory sample - DemoCorp directory sample - UNSPSC directory sample
E–16 eTrust Directory Administrator Guide Silent Installation
Step 1 – Dxserver Setup
If you are installing Dxserver for the first time, you are asked to enter a password: The dsa account requires a password New password:
Step 2 – Advantage Ingres Setup
When you enter the password, you are prompted for the password for the Advantage Ingres user. The Ingres account requires a password New password: If you do not wish to install all default components, you can specify this on the command line:
Command line Action option -nojxplorer Do not install the JXplorer LDAP Client. -nodxwebserver Do not install the DXwebserver component. -nodocs Do not install the User Documentation -noingres Do not install Advantage Ingres. This is option should only be used if the DXserver will act as a router or a relay DSA. Note that the DXserver directory samples will not be run, as these require a database. -nosamples Do not install the DXserver directory samples Router, Democorp & UNSPSC
Example: Install Dxserver only
This will install dxserver and DXtools only in the default location: #./dxsetup.sh –default –nojxplorer –nodxwebserver –nodocs –noingres
Since Ingres is not installed, the samples are not installed either.
Installing DXserver for UNIX E–17 Embedded Installation
Embedded Installation
eTrust Directory can now be installed as an embedded product so that other CA products can use its features in their product. This means that other CA products can install eTrust Directory using their own unique caller ID. Then, if eTrust Directory needs to be removed, the customer can remove it without removing anything that the embedding CA product requires.
Only one product can use a particular caller ID. They must also never change this caller ID. Each caller ID is recorded, so as not to affect any other instances of eTrust Directory.
As with silent installation, all install commands can be used with the embedded and caller ID commands on the one command line. Embedding users will need to add in two extra command line parameters when running dxsetup.
Parameter Description
-embedded Lets (Dxserver) the black box know that we will be using an embedded directory. -caller_id Uniquely identifies the embedding customer. Only one "unique_id" product can use a particular caller ID. They must also never change this caller ID. They must also use this caller ID to uninstall eTrust Directory.
For example, the following command installs eTrust Directory silently as product eTrust Web Access Control: ./dxsetup.sh -default -embedded –caller_id "ETWAC"
The uninstall will also require this flag: ./dxuninst.sh -embedded –caller_id "ETWAC"
To find out which caller IDs are supported, contact CA Support.
Uninstalling eTrust Directory After an Embedded Installation
The caller ID must be used to uninstall eTrust Directory.
The uninstallation process will determine if no more products require 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.
E–18 eTrust Directory Administrator Guide Install the Technology Previews (Optional)
Install the Technology Previews (Optional)
DSML
This version includes a technology preview of a Directory Services Markup Language (DSML) server, which allows you to connect to eTrust Directory’s sample router with the DSML 2.0 protocol. To start the DSML server, you must set it up by running setup in the $DXHOME/../dxwebserver/samples/dsml directory. After this, you can use JXplorer to connect to this DSML server by using the following connection settings:
■ Host:
■ Port: 8080
■ Protocol: DSML v2
■ DSML Service: dsml-sample/services/DSML
UDDI
This release includes a technology preview of the Universal Description, Discovery and Integration (UDDI) server and browser. To try the UDDI server, you must set up its server by running setup in the $DXHOME/../dxwebserver/samples/uddi directory.
Installing DXserver for UNIX E–19 Upgrading from a Previous Version
Upgrading from a Previous Version
This section describes how to upgrade DXserver and Advantage Ingres.
When upgrading from a previous eTrust Directory version, the Advantage Ingres RDBMS is also upgraded to the latest Advantage Ingres II 2.6. You can choose to not upgrade Advantage Ingres.
If you are upgrading from a previous eTrust Directory version, existing databases are automatically upgraded with the following command:
dxupgradedb database-name
where database-name is the name of the database to upgrade. This also applies if you install eTrust Directory 4.1 after you installed any other eTrust product that embeds a pre-4.1 version of eTrust Directory.
See http://support.ca.com/etrustdir_supp.html for detailed upgrade information.
Upgrading Advantage Ingres
The eTrust Directory installation process does not force you to upgrade any existing pre-2.6 Advantage Ingres installation. If you are running Advantage Ingres 2.0 or 2.5, you must check with Computer Associates Technical Support to find out whether your applications that use your existing version of Advantage Ingres also support Advantage Ingres 2.6. eTrust Directory supports Advantage Ingres 2.0 and 2.6.
To upgrade, run the install process as for a new installation of DXserver. The install script detects an installed version of either DXserver or Advantage Ingres and asks if you want to upgrade.
The eTrust Directory installation implements the following:
■ If you say No to the upgrade prompt, the pre-existing Advantage Ingres installation will not be changed.
■ If eTrust Directory previously installed Advantage Ingres 2.6, this upgrade will apply the latest Advantage Ingres 2.6 SP 1 upgrade but keep the installation code that was used last time.
■ If the previous Advantage Ingres Installation is version 2.0 or 2.5 and you say Yes to the upgrade prompt, the Advantage Ingres 2.6 SP 1 upgrade will be applied. The installation code will remain the same as before.
■ If there is no previous Advantage Ingres installation, eTrust Directory will install Advantage Ingres [ET].
E–20 eTrust Directory Administrator Guide
Appendix F Installing Directory GUIs
The eTrust Directory distribution CD contains the following graphical user interfaces (GUIs):
■ DXconfig ■ DXplorer ■ DXmanager ■ JXplorer ■ JXweb ■ UDDI Web Client
DXconfig enables you to configure your DSAs. DXmanager provides an administrative portal to a directory. UDDI Web Client enables you to connect to a UDDI server.
DXplorer, JXplorer, and JXweb are directory browsers. The differences are:
■ DXplorer uses DAP, while JXplorer and JXweb use LDAP.
■ DXplorer is a Windows-based client; JXplorer is a Java-based client; JXweb is a web-based client.
■ JXplorer and JXweb can be used on platforms other than Windows.
■ JXweb can be used remotely on any machine with a TCP/IP connection through a web browser.
Use the following table to determine which browser your platform supports:
Platform DXplorer JXplorer JXweb Windows Yes Yes Yes Linux and UNIX No Yes Yes
The machine on which you install the directory browser must have TCP/IP access to the server running your DXserver directory.
Installing Directory GUIs F–1 Installing JXplorer
Installing JXplorer
You can install JXplorer on either a Windows or UNIX machine.
Windows Installation
You can install the JXplorer client on any Windows or Windows 2000 machine with Java Runtime Environment (JRE), and TCP/IP access to the server running your DXserver directory. The installation will check whether your system already has a compatible JRE and make recommendations as required.
Note: JXplorer does not work on a monitor with a 16-color palette.
Install JXplorer To install JXplorer: 1. Insert the CD in the CD-ROM drive. The Product Explorer starts automatically. 2. Expand eTrust Directory, DXserver, and select Windows. 3. Click Install to start the eTrust Directory Installation Wizard. (Alternatively, you can run …\\dxserver\windows\dxsetup.exe from the CD.) 4. Follow the installation wizard.
Start JXplorer To start JXplorer, click Start on the taskbar, and then choose Programs, eTrust Directory, JXplorer.
F–2 eTrust Directory Administrator Guide Installing JXplorer
UNIX Installation
You can install the JXplorer client on any UNIX machine with the following:
■ TCP/IP access to the server running your DXserver directory ■ Java
Tip: JXplorer needs Java Runtime Environment (JRE). The installation loads the JRE into the product directory tree when you respond to its prompt that the JRE is required.
Install JXplorer To install JXplorer: 1. Insert the CD in the CD-ROM drive. 2. Change to the jxplorer directory on the mounted CD, for example, on Solaris: % cd /cdrom/cdrom0/jxplorer/solaris 3. Run the installer: ./jxsetup.sh 4. Follow the installation wizard.
Start JXplorer To start JXplorer, run the following command from the jxplorer directory: ./jxstart.sh
Note: You can run this with the –console option, which is useful for debugging connection issues.
Installing Directory GUIs F–3 Installing DXconfig, DXmanager, JXweb, and UDDI Web Client
Installing DXconfig, DXmanager, JXweb, and UDDI Web Client
You can install DXconfig, DXmanager, JXweb, and UDDI Web Client on either a Windows or UNIX machine. You install them in a group as DXwebServers.
Windows Installation
You can install the DXwebServers clients on any Windows 2000 or Windows XP machine with Java Runtime Environment (JRE), and TCP/IP access to the server running your DXserver directory. The installation will check whether your system already has a compatible JRE and make recommendations as required.
Install DXwebServers To install the DXwebServers clients: Clients 1. Insert the CD in the CD-ROM drive. The Product Explorer starts automatically. 2. Expand eTrust Directory, DXserver, and select Windows. 3. Click Install to start the eTrust Directory Installation Wizard. (Alternatively, you can run …\\dxweb\windows\dxsetup.exe from the CD.) 4. Follow the installation wizard.
Start DXwebServers To start a DXwebServers client, click Start on the taskbar, and then choose Clients Programs, eTrust Directory, client (DXconfig, DXmanager, JXweb, or UDDI Web Client).
F–4 eTrust Directory Administrator Guide Installing DXconfig, DXmanager, JXweb, and UDDI Web Client
UNIX Installation
You can install the DXwebServers clients on any UNIX machine with the following:
■ TCP/IP access to the server running your DXserver directory ■ Java
Tip: DXwebServers clients need Java Runtime Environment (JRE). The installation loads the JRE into the product directory tree when you respond to its prompt that the JRE is required.
Install DXwebServers To install the DXwebServers clients: Clients 1. Insert the CD in the CD-ROM drive. 2. Change to the dxwebserver directory on the mounted CD, for example, on Solaris: % cd /cdrom/cdrom0/dxwebserver/solaris 3. Run the installer: ./dxwebsetup.sh 4. Follow the installation wizard.
Start DXwebServers To start the DXwebServers clients, run the following command from the Clients dxwebserver directory: ./dxwebstart.sh
Installing Directory GUIs F–5 Installing DXplorer
Installing DXplorer
You can install the DXplorer client on any Windows 2000 machine with TCP/IP access to the server running your DXserver directory.
Install DXplorer To install DXplorer: 1. Insert the CD in the CD-ROM drive. The Product Explorer starts automatically. 2. Expand eTrust Directory, DXserver, and select Windows. 3. Click Install to start the eTrust Directory Installation Wizard. (Alternatively, you can run …\dxserver\windows\dxsetup.exe from the CD.) 4. Follow the installation wizard.
Start DXplorer To start DXplorer, click Start on the taskbar, and then choose Programs, eTrust Directory, DXplorer.
F–6 eTrust Directory Administrator Guide
Appendix G 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.
Note: Throughout this guide, references to Advantage Ingres include both Ingres II and OpenIngres, unless one or the other is explicitly specified. 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 G–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:
OpenWindow CDE Keystrokes Purpose Keystrokes
↵ ↵ 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.
G–2 eTrust Directory Administrator Guide 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 CDE Keystrokes Purpose Keystrokes
↵ ↵ 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 G–3 Increasing the Number of Database Connections
Increasing the Number of Database Connections
eTrust Directory 4.1 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 dxloaddb, 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 RAM required Connections 32 16 MB 64 100 MB 128 200 MB
If you need to do this step, use the following table:
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.
G–4 eTrust Directory Administrator Guide 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
For more information, contact Computer Associates Technical Support at http://supportconnect.ca.com/.
Tailoring the RDBMS G–5
Appendix H Licenses for Third-Party Products
eTrust Directory uses some third-party code. This appendix includes the license agreements for that code.
Apache Tomcat and others
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.
General License (covers Tomcat, Axis, CLUtil, Log4j, Xalan, Xerces, XSLTC)
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
The Apache Software License, Version 1.1
Copyright (c) 2000 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.
Licenses for Third-Party Products H–1 Apache Tomcat and others
4. The names "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 [email protected].
5. Products derived from this software may not be called "Apache", nor may "Apache" 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.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see
Portions of this software are based upon public domain software originally written at the National Center for Supercomputing Applications, University of Illinois, Urbana-Champaign.
Cocoon
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
The Apache Software License, Version 1.1
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.
H–2 eTrust Directory Administrator Guide Apache Tomcat and others
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 "Apache Cocoon" 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 [email protected].
5. Products derived from this software may not be called "Apache", nor may "Apache" 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 (INCLU- DING, 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.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally created by Stefano Mazzocchi
Commons
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
The Apache Software License, Version 1.1
Copyright (c) 2001 The Apache Software Foundation. All rights reserved.
Licenses for Third-Party Products H–3 Apache Tomcat and others
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 acknowlegement: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowlegement may appear in the software itself, if and wherever such third-party acknowlegements normally appear.
4. The names "The Jakarta Project", "Commons", 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 [email protected].
5. Products derived from this software may not be called "Apache", "Velocity" nor may "Apache" appear in their names without prior written permission of the Apache Group.
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.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see
Velocity
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
H–4 eTrust Directory Administrator Guide Apache Tomcat and others
The Apache Software License, Version 1.1
Copyright (c) 2000-2001 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 acknowledgement: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgement may appear in the software itself, if and wherever such third-party acknowledgements normally appear.
4. The names "The Jakarta Project", "Velocity", 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 [email protected].
5. Products derived from this software may not be called "Apache", "Velocity" nor may "Apache" appear in their names without prior written permission of the Apache Group.
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.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see
Licenses for Third-Party Products H–5 IBM UDDI4j
IBM UDDI4j
Portions of this product include software provided by IBM under the IBM Public License, Version 1.0. Installation and use of this product requires agreement to the terms of the following IBM License. This IBM License is separate and apart from any license agreement between you and Computer Associates International, Inc. or its predecessors.
Copyright © 2003, International Business Machines Corporation and others. All Rights Reserved.
IBM Public License Version 1.0
THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS IBM PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
1. DEFINITIONS
"Contribution" means:
a) in the case of International Business Machines Corporation ("IBM"), the Original Program, and
b) in the case of each Contributor,
i) changes to the Program, and
ii) additions to the Program;
where such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.
"Contributor" means IBM and any other entity that distributes the Program.
"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.
"Original Program" means the original version of the software accompanying this Agreement as released by IBM, including source code, object code and documentation, if any.
H–6 eTrust Directory Administrator Guide IBM UDDI4j
"Program" means the Original Program and Contributions.
"Recipient" means anyone who receives the Program under this Agreement, including all Contributors.
2. GRANT OF RIGHTS a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form. b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder. c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program. d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of this Agreement; and b) its license agreement:
Licenses for Third-Party Products H–7 IBM UDDI4j
i) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;
iii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and
iv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.
When the Program is made available in source code form:
a) it must be made available under this Agreement; and
b) a copy of this Agreement must be included with each copy of the Program.
Each Contributor must include the following in a conspicuous location in the Program:
Copyright © {date here}, International Business Machines Corporation and others. All Rights Reserved.
In addition, each Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.
4. COMMERCIAL DISTRIBUTION
H–8 eTrust Directory Administrator Guide IBM UDDI4j
Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.
For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.
6. DISCLAIMER OF LIABILITY
Licenses for Third-Party Products H–9 IBM UDDI4j
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), 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 OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. In addition, If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.
All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.
H–10 eTrust Directory Administrator Guide OpenLDAP
IBM may publish new versions (including revisions) of this Agreement from time to time. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. No one other than IBM has the right to modify this Agreement. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.
This Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.
OpenLDAP
This product includes software developed by the OpenLDAP Foundation, OpenLDAP Project (http://www.openldap.org/). The OpenLDAP software is distributed in accordance with the following agreement.
The OpenLDAP Public License
Version 2.3, 28 July 2000
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 of source code 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.
3. Redistributions must contain a verbatim copy of this document.
4. The name "OpenLDAP" must not be used to endorse or promote products derived from this Software without prior written permission of the OpenLDAP Foundation.
Licenses for Third-Party Products H–11 OpenSSL
5. Products derived from this Software may not be called "OpenLDAP" nor may "OpenLDAP" appear in their names without prior written permission of the OpenLDAP Foundation.
6. Due credit should be given to the OpenLDAP Project (http://www.openldap.org/).
7. The OpenLDAP Foundation may revise this license from time to time. Each revision is distinguished by a version number. You may use the Software under terms of this license revision or under the terms of any subsequent revision of the license.
THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND CONTRIBUTORS ``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 OPENLDAP 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.
OpenLDAP is a trademark of the OpenLDAP Foundation.
Copyright 1999-2000 The OpenLDAP Foundation, Redwood City,
California, USA. All Rights Reserved. Permission to copy and distributed verbatim copies of this document is granted.
OpenSSL
This product includes software developed by the OpenSSL Project. The OpenSSL software is distributed in accordance with the following agreement.
Copyright (c) 1998-2002 The OpenSSL Project. 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.
H–12 eTrust Directory Administrator Guide OpenSSL
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. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].
5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment:
"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) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This product includes cryptographic software written by Eric Young ([email protected]). This product includes software written by Tim Hudson ([email protected]).
Licenses for Third-Party Products H–13 OpenSSL
Original SSLeay License
This product includes cryptographic software written by Eric Young ([email protected]). The software is distributed in accordance with the following license agreement.
Copyright (C) 1995-1998 Eric Young ([email protected])
All rights reserved.
This package is an SSL implementation written by Eric Young ([email protected]).
The implementation was written so as to conform with Netscapes SSL. This library is free for commercial and non-commercial use as long as the following conditions are aheared to. 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 ([email protected]).
Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package.
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 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. All advertising materials mentioning features or use of this software must display the following acknowledgement:
"This product includes cryptographic software written by Eric Young ([email protected])"
The word 'cryptographic' can be left out if the rouines from the library being used are not cryptographic related :-).
4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement:
H–14 eTrust Directory Administrator Guide Sun Microsystems, Inc.
"This product includes software written by Tim Hudson ([email protected])"
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.
The licence and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution licence [including the GNU Public Licence.]
Sun Microsystems, Inc.
DSML and LDAP Extensions
Sun Microsystems, Inc.
Binary Code License Agreement
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.
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.
Licenses for Third-Party Products H–15 Sun Microsystems, Inc.
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. You acknowledge that Software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun 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.
H–16 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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).
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.
SUPPLEMENTAL LICENSE TERMS
For Java Naming and Directory InterfaceTM (JNDI), Version 1.2.1 and any of the following:
DNS Service Provider Version 1.2,
LDAP Service Provider Version 1.2.4,
NIS Service Provider Version 1.2.1,
RMI Registry Service Provider Version 1.2.1,
FS Context Service Provider Version 1.2 beta 3 release,
Licenses for Third-Party Products H–17 Sun Microsystems, Inc.
COS Naming Service Provider Version 1.2.1,
DSML v1 Service Provider Version 1.2,
JNDI/LDAP Booster Pack Version 1.0,
or Demo.
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. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java(TM) 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 for the sole purpose of designing, developing and testing your Java applets and applications ("Programs").
2. License to Distribute Software. In addition to the license granted in Section 1 (Software Internal Use and Development License Grant) of these Supplemental Terms, subject to the terms and conditions of this Agreement, including but not limited to Section 3 (Java Technology Restrictions), Sun grants you a non- exclusive, non-transferable, limited license to reproduce and distribute the Software in binary 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 component(s) 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, and (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.
H–18 eTrust Directory Administrator Guide Sun Microsystems, Inc.
3. 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.
4. Trademarks and Logos. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET-related 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.
5. 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.
6. 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.
For inquiries please contact: Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A
(LFI#107226/Form ID#011801)
JAVA 2 Runtime Environment
This product includes code licensed from RSA Security, Inc.
Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/
Licenses for Third-Party Products H–19 Sun Microsystems, Inc.
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.
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.
H–20 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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).
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.
Licenses for Third-Party Products H–21 Sun Microsystems, Inc.
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 2 RUNTIME ENVIRONMENT (J2RE), STANDARD EDITION, VERSION 1.4.1_X
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. 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 sole purpose of designing, developing and testing your Java applets and applications intended to run on the Java platform ("Programs").
H–22 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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, provided that (i) you distribute the Software complete and unmodified (unless otherwise specified in the applicable README file) and only bundled as part of, and for the sole purpose of running, your Programs, (ii) the Programs add significant and primary functionality to the Software, (iii) you do not distribute additional software intended to replace any component(s) of the Software (unless otherwise specified in the applicable README file), (iv) you do not remove or alter any proprietary legends or notices contained in the Software, (v) you only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms contained in this Agreement, and (vi) 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. (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 Security, Inc.", and (vii) include the statement, "Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/".
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 files specifically identified as redistributable in the Software "README" file ("Redistributables") provided that: (i) you distribute the Redistributables complete and unmodified (unless otherwise specified in the applicable README file), and only bundled as part of Programs, (ii) you do not distribute additional software intended to supersede any component(s) of the Redistributables (unless otherwise specified in the applicable README file), (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, (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 Security, Inc.", and (vii) include the statement, "Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/".
Licenses for Third-Party Products H–23 Sun Microsystems, Inc.
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. Notice of Automatic Software Updates from Sun. You acknowledge that the Software may automatically download, install, and execute applets, applications, software extensions, and updated versions of the Software from Sun ("Software Updates"), which may require you to accept updated terms and conditions for installation. If additional terms and conditions are not presented on installation, the Software Updates will be considered part of the Software and subject to the terms and conditions of the Agreement.
6. Notice of Automatic Downloads. You acknowledge that, by your use of the Software and/or by requesting services that require use of the Software, the Software may automatically download, install, and execute software applications from sources other than Sun ("Other Software"). Sun makes no representations of a relationship of any kind to licensors of Other Software. 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 OTHER SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
7. 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 iPLANET-related 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.
8. 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.
H–24 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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.
For inquiries please contact: Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
JavaHelp
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.
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. You acknowledge that Software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun 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.
Licenses for Third-Party Products H–25 Sun Microsystems, Inc.
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).
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.
H–26 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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.
JAVAHELPTM VERSION 1.1.3
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. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (JavaTM 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 sole purpose of designing, developing and testing your Java applets and applications intended to run on the Java platform ("Programs").
2. License to Distribute Redistributables. In addition to the license granted in Section 1 (Software Internal Use and Development License Grant) of these Supplemental Terms, subject to the terms and conditions of this Agreement, including but not limited to Section 3 (Java Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce and distribute those files specifically identified as redistributable in the Software "README" file ("Redistributables") provided that: (i) you distribute the Redistributables complete and unmodified (unless otherwise specified in the applicable README file), and only bundled as part of your Programs, (ii) you do not distribute additional software intended to supersede any component(s) 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, and (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.
Licenses for Third-Party Products H–27 Sun Microsystems, Inc.
3. 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.
4. 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.
5. 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 iPLANET-related 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.
6. 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.
7. 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.
For inquiries please contact: Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303
H–28 eTrust Directory Administrator Guide Sun Microsystems, Inc.
Java Web Services Developer Pack
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.
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.
Licenses for Third-Party Products H–29 Sun Microsystems, Inc.
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).
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.
H–30 eTrust Directory Administrator Guide Sun Microsystems, Inc.
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. 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".
Licenses for Third-Party Products H–31 Sun Microsystems, Inc.
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".
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 iPLANET-related 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.
H–32 eTrust Directory Administrator Guide TeraTerm
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.
8. 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.
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 NON- INFRINGEMENT, 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.
TeraTerm
This product includes software developed by Takashi Teranishi, Copyright © 1994-1998.
Licenses for Third-Party Products H–33
Index
ACI Items, 6-36, 6-37 . add, A-9 a leaf entry, A-9 alias, A-18 .dxc file type, 2-5, 2-9, 3-1, 4-6, 5-9, 5-14, 5-15, 6-20 database user, 11-13 service, A-10 .dxg file type, 2-5, 2-9, 4-2, 5-9, 5-14, 5-15, 6-20 add-entry-req, A-1, A-10 .dxi file type, 2-5, 2-8, 3-2, 4-2, 5-9, 5-14, 5-15 alias, A-18 .dxs file type, 2-5 Administration daemon, 9-3 administrative areas, domains, 6-20 A administrative user defining, 6-27 privileges, 6-30 abandon, A-4 all operations, 3-24 administrator, 6-10 operation, 3-24 defining, 6-27 request, A-6 Advantage Ingres errors, C-8 service, A-8 agreement, 7-13 abandon-req, A-1, A-8 get, 7-13 abort associations, 3-18 set, 7-13 abstract object classes, 4-10 alarm-log file, 3-9 access controls, 3-23, 6-19 alarms, 3-5 aliases, 6-43 multiwrite queues, 7-8 configuration, 6-23 alert-log file, 3-9 dynamic, 6-34 groups, 6-24 alias managing, 6-23 access controls, 6-43 policy, 6-20, 6-21 add, A-18 role-based, 6-32 dangling aliases, C-6 roles, 6-32 delete, A-19 routing, 6-42 entry, 4-15, A-17, A-20 rule hierarchies, 6-23 errors, C-6 rules, 6-20, 6-25 integrity, 3-27, A-18, C-6 secure proxy, 6-33 invalid, 3-27 static, 6-22 modify, A-20 viewing, 6-36 name binding, 4-15 reading, A-18 access subdirectory, 2-4 aliasedObjectName, A-18
Index–1
all-extra-attrs, A-16 conveying, 6-16 DISP, 6-13, 6-15 alt-name, 8-2 distributed user, 6-13 anonymous bind, 6-9 DSP, 5-6, 6-13, 6-15 DSP link, 6-17 Apache Tomcat license agreement, H-1 setting levels, 6-9 API (application program interface) SSL, 6-11 UDDI, 15-2 strong, 6-17 user, 6-11 application program interface. See API autostart subdirectory, 2-4 arguments common, A-14 auxiliary object classes, 4-11 DXtools, 11-26 assoc commands, 3-13 B configuration, 3-15 associations backup a database, 11-6 aborting, 3-18 base-object, A-6 configuration, 5-7 limiting, 3-18 billing maximum times, 3-17 monitoring, 9-2 queues, 3-19 rejection, 3-18 bin directory, 2-3 tracing, 3-16 bind users, 3-16 anonymous, 6-9 viewing, 3-16 confirm, A-2 attr-and-vals, A-15 control, 3-17 DSP requests, 6-13 attributes maximum time, 3-17 add or remove, A-9 names, 4-14 checking, 4-7 request, A-2 index, 3-28 with credentials, 5-6 inherited rules, 4-7 invalid, 4-7 bind-req, A-1, A-2 locally customized, 8-2 bookmarks, 12-14 multi-line, A-10 multiple, 4-14 bulk loading, 14-7 multi-valued, A-10 multi-valued naming, A-11 naming, A-10 C operational, A-16 read-only, 4-5, B-11 sets, 4-8 caching subordinate entries, 5-17 single-valued, 4-5 certificates, 6-5 syntax, 4-2, 4-6 generation, 6-5 attr-only, A-7, A-15 cert-log file, 3-9 audit file, 6-42 chaining-prohibited, A-15 auditing change control, 14-8 monitoring, 9-2 changes in LDIF files, 11-24 authentication, A-2
clear set min-auth, 6-9 dsas, 5-5 set user-idle time, 3-18 indexes, 3-28 commands, bind services CLI, 2-14 bind-req, A-2 client encryption, 6-8 commands, CMIP cmip-psap, 9-12 close logtype, 3-11 dxcmip, 9-12 closing the management console, 2-15 commands, DAP tools CMIP (Common Management Information Protocol), common argument, 11-26 1-12, 3-22, 9-1 dxdelete, 11-34 agent, 9-12 dxmodify, 11-30 monitoring utility, 9-12 dxrename, 11-33 X.700 management, 9-12 dxsearch, 11-28 cmip-psap, 9-12 commands, DB tools dxadduser, 11-13 command-line dxbackupdb, 11-6 interface, 2-14 dxdeluser, 11-13 options, 2-6 dxdestroydb, 11-5 commands dxdumpdb, 11-16 assoc, 3-13 dxemptydb, 11-5 controlling output, 3-8 dxextenddb, 11-4 DSP, 5-2 dxgrantdb, 11-17 DXserver, 2-10 dxindexdb, 11-9 grouping by function, 2-10 dxlistdb, 11-13 help, 2-16 dxloaddb, 11-14 logs, 3-11 dxnewdb, 11-4 oper, 3-20 dxnewdsa, 11-3 shortcuts, 2-16 dxrestoredb, 11-7 syntax, 2-11 dxstatdb, 11-12 trace, 3-5, 3-7 dxtunedb, 11-8 dxupgradedb, 11-17 commands, access control get access, 6-36 commands, DIB set access-controls, 3-23 clear indexes, 3-28 set admin-user, 6-27 get dib, 3-26 set group, 6-24 set alias-integrity, 3-27 set protected-items, 6-30 set database-name, 2-18, 3-26 set public-user, 6-30 set eis-count-attr, 3-27 set read-only, 6-43 set index wide, 3-28 set reg-user, 6-28 set index-reverse, 3-28 set super-user, 6-26 set not-searchable, 3-28 ssld, 6-6 commands, DISP commands, associations disp update, 7-16 abort, 3-18 get agreement, 7-13 get assoc, 3-15 set agreement, 7-13, 7-14 get users, 3-16, 3-17, 3-18, 3-24, 9-2 commands, DSAs set allow-binds, 3-17 set always-chain-down, 5-10 set authentication, 3-17 set dsa, 3-1, 5-9, 5-11, 5-12, 5-13, 5-20, 5-21, 6-4, 6- set credits, 3-19 5, 7-6, 7-16, 8-6 set max-bind-time, 3-17 set precedence, 5-19 set max-users, 3-18
shutdown, 3-16 ldif2dxc, 11-37 commands, DSP commands, SNMP clear dsas, 5-3, 5-5 snmp-port, 9-8 get dsp, 5-7 commands, traces get online dsas, 5-7 set trace, 3-7, 3-16 get online-dsas, 5-5, 9-2 trace disable assoc, 3-16 set max-dsp-ops, 5-4 trace enable assoc, 3-16 set multi-casting, 5-6 unbind, 5-3 commands, update services add-entry-req, A-10 commands, inquire services mod-entry-req, A-12, A-20 abandon-req, A-8 rem-entry-req, A-11, A-19 compare-req, A-5 list-req, A-5 comments in script files, 2-12 read-req, A-4, A-15, A-16 search-req, A-6 common arguments, A-14 commands, LDIF tools Common Management Information Protocol. See csv2ldif, 11-21 CMIP ldifdelta, 11-24 communication settings, view, 3-4 commands, local operations compare, A-4 get oper, 3-21 service, A-5 get stats, 3-22, 9-2 reset stats, 3-22 compare-req, A-1, A-5 set max op-size, 3-23 config directory, 2-3 set max-local-ops, 3-22, 3-23 set max-op-size, 3-24 configuration set max-op-time, 3-24 DIB, 3-26 directories, 2-3 commands, logs DSP, 5-2 close logtype, 3-11 file errors, 2-13 echo, 3-12 file type, 2-5, 2-9, 3-1, 4-6, 5-9, 5-14, 5-15, 6-20 echo-off, 3-12 operations, 3-21 echo-on, 3-12 server, 2-2 flush logtype, 3-11 subdirectories, 2-4 get log, 3-11 set logtype, 3-11 configuration files, 1-13 set summary-log, 3-12 grouping, 2-9 grouping commands, 2-10 commands, multiwrite set multi-write-queue, 7-7 configuring access controls, 6-23 commands, schema, 4-3 another DXserver, 5-9 get schema, 4-4 DSP relay, 5-16 set attribute, 4-4, 4-5, 4-9, 4-17 first level DSA, 5-15 set attr-set, 4-8, 4-17 management console, 2-14 set name-binding, 4-14, 4-17 multiple local DSAs, 5-13, 5-15 set object-class, 4-10, 4-17 the remote DXcli DUA, A-3 set oid-prefix, 4-4, 4-17 third-party DSAs, 5-4, 5-6, 5-11, 5-12 set prune-oc-parents, 4-12 set return-oc-parents, 4-12 connect times, 3-16 commands, SCHEMA tools connection dxschemaldif, 11-36 address, 3-17 dxschematxt, 11-41 information, 3-16
remote, 5-4, 5-5, 5-17 defining time, 3-17 administrative users, 6-27 UDDI server, to, 15-3 groups, 6-24 UDDI Web Client, to, 15-3 local data types, 4-16, 8-3 local schema, 4-16, 8-3 connect-log file, 3-9 protected items, 6-30 control public users, 6-30 binds, 3-17 registered users, 6-28 operations, 3-23, 3-24 superusers, 6-26 users, 6-9, 6-10 controlling operations, 3-22, 3-23 delete output, 3-8 alias, A-19 database user, 11-13 CPUs, multiple, 5-13 directory entries, 11-34 creating a database, 11-3, 11-4 leaf entry, A-9 credentials, definition, 6-9 delete-old, A-13 credits, 3-19 destroying a database, 11-5 CSV data, 11-19 DIB (Directory Information Base), 1-13, 3-25 manage, 3-25 csv2ldif, 11-18, 11-21 directory components, 1-11 configuration, 2-3 D delete entries, 11-34 Information Shadowing Protocol (DISP), 7-13 dangling alias, C-6 knowledge, 3-1 modify, 11-30 DAP (Directory Access Protocol), 1-12 modules, 1-10 rename, 11-33 database samples, 1-14 add user, 11-13 search, 11-28 backup, 11-6 backups, 14-6 Directory Access Protocol. See DAP creation, 11-3, 11-4 data removal, 11-5 directory browser delete user, 11-13 JXplorer, 12-1 destruction, 11-5 JXweb, 13-1 hot swap, 2-18 directory entries, counting, 3-27 initializing, 2-17 integrity, 4-2, C-8 Directory Information Base. See DIB listing, 11-13 Directory Information Shadowing Protocol. See DISP massive, 5-13 monitoring, 9-2 Directory System Protocol. See DSP multiple directory, 2-18 Directory User Agent (DUA), 1-14 name, 3-26 restore, 11-7 disconnecting from the DSA, A-3 statistics, 11-12 disk space tailoring, G-1 monitoring, 9-2 tuning, 11-8 DISP (Directory Information Shadowing Protocol), 1- database subdirectory, 2-4 12 debugging, 2-13 authentication, 6-13
responder, 7-13 get, 5-2 update, 7-16 set, 5-2 unbind, 5-2 display database statistics, 11-12 unbind, 5-3 distinguished name, 5-9, 5-22 DSP relative, 5-15 authentication, 6-15 DIT (Directory Information Tree), 5-4 DSP (Directory System Protocol), 1-12 definition, 5-9 authentication, 5-6, 6-13, 6-15 prefix, 5-4 bind request, 6-13 relay DSA, 5-17 commands, 5-2 docs directory, 2-3 configuration, 5-2, 5-7 credentials, 5-6 dont-deref-aliases, A-9, A-15, A-18 incoming credentials, 5-6 dont-search-aliases, A-7 monitoring connections, 5-7 multiprocessing, 5-13 dont-use-copy, A-15 outgoing connections, 5-5 DSA outgoing credentials, 5-6 caching entries, 5-17 relay, 5-16 defining, 3-1 DUA, 1-14 first level, 5-15 remote, A-1 load-sharing, 5-20, 5-21 remote CLI, A-2 local, 5-9, 5-11 management console, A-1 dump, 11-1 multiple local, 5-13, 5-15 dxadduser, 11-13 proxy, 5-10 read-only, 6-43 DXadmind relay, 5-17 connecting to, 9-3 shadow, 7-16 Manager, 9-3 stopping, 3-16 dxbackup, 14-6 third-party, 5-4, 5-6, 5-11, 5-12 trust flags, 6-42 dxbackupdb, 11-6 DSA processes, multiple, 2-17 DXcache configuring, 3-30 dsa, ssld-port, 6-4 synchronizing, 3-32 dsaEntriesTable, 9-7 viewing, 3-32 dsa-flags, 3-25, 5-17, 5-20, 5-21, 5-22, 7-6, 7-16 dxcmip, 9-12 limit-list, 3-43 DXconfig limit-search, 3-43 adding a DXserver, 10-8 load-share, 3-43 adding a package, 10-4 multi-write, 3-43 adding an item, 10-6 multi-write-notify, 3-43 browser, 10-2 no-routing-ac, 3-43 connecting to, 10-1 read-only, 3-43 displaying packages, 10-4 relay, 3-44 editing a package, 10-4, 10-5 shadow, 3-44 naming packages, 10-3 dsaIntTable, 9-7 packages, 10-3 submitting changes, 10-9 dsaOpsTable, 9-7 DXconsole, 1-12, 2-14, 6-43, 9-2 dsp clear dsas, 5-2, 5-3 dxdelete, 11-34
dxdeluser, 11-13 dxindexdb, 11-9 dxlistdb, 11-13 dxdestroydb, 11-5 dxloaddb, 11-14 dxdumpdb, 11-16 dxmodify, 11-30 dxnewdb, 11-4 dxemptydb, 11-5 dxnewdsa, 11-3 dxextenddb, 11-4 dxrename, 11-33 dxrestoredb, 11-7 dxgrantdb, 11-17 dxschemaldif, 11-36 dxindexdb, 11-9 dxschematxt, 11-41 dxsearch, 11-28 dxlistdb, 11-13 dxstatdb, 11-12 dxloaddb, 11-14 dxtunedb, 11-8 dxupgradedb, 11-17 DXmanager portal, 3-46 ldif2dxc, 11-37 dxmodify, 11-30 ldifdelta, 11-24 dxnewdb, 11-4 dxtunedb, 11-8, 14-7 dxnewdsa, 11-3 dxupgradedb, 11-17 dxrename, 11-33 DXweb server, 1-15 dxrestoredb, 11-7 dynamic access controls, 6-34 dxschemaldif tool, 11-36 dxschematxt tool, 11-41 E dxsearch, 11-28 DXserver, 1-12 echo command, 3-12 adding, 10-8 emptying a database, 11-5 alarms, C-3 commands, 2-10 encryption configuring SSL, 6-4 client, 6-8 logs, C-2 DSA to DSA, 6-8 version, 2-7 entry information selection, A-15 warning messages, C-5 error logs, C-1 DXserver statistics monitoring, 9-7 errors configuration file, 2-13 dxsnmp, 9-8 ldif2dxc tool, 11-38 dxstatdb, 9-2, 11-12 script file, 2-13 statistics, 3-22 DXtools, 1-13, 7-17 csv2ldif, 11-21 event logs, C-1 dxadduser, 11-13 events, 3-22 dxbackupdb, 11-6 dxdelete, 11-34 export, 11-1 dxdeluser, 11-13 extra-attrs, A-16 dxdestroydb, 11-5 dxdumpdb, 11-16 dxemptydb, 11-5 dxextenddb, 11-4 dxgrantdb, 11-17
F help command, 2-16 history files, 3-12 file descriptors, 3-18, 14-9 hot swap, 2-18 file extensions dxc, 2-5, 2-9, 3-1, 4-6, 5-9, 5-14, 5-15, 6-20 dxg, 2-5, 2-9, 4-2, 5-9, 5-14, 5-15, 6-20 I dxi, 2-5, 2-8, 3-2, 4-2, 5-9, 5-14, 5-15 dxs, 2-5 IA5 string, 4-7 files configuration, 1-13 IBM UDDI4j license agreement, H-6 launch, 12-23 idle times, 3-16 types, 2-5 maximum, 3-18 filter, A-6 IETF, 4-1 firewall, 5-10 impersonation protection, 6-41 alternative network addresses, 5-11 import, 11-1 flush logtype, 3-11 import data, 3-23 forward requests, 5-16 increased user counts, 2-17 initialization G file, 2-8 file type, 2-5, 2-8, 3-2, 4-2, 5-9, 5-14, 5-15 server, 2-6 get access, 6-36 initiator, 7-14 access module, 6-24 install directory, 2-3 assoc, 3-15 dib, 3-25, 3-26 installation dsp, 5-3, 5-7 directory browsers, F-1 log, 3-11 DXplorer, F-6 online-dsas, 5-5, 5-7, 9-2 JXplorer, F-2, F-4 oper, 3-21 invalid operations, 3-21 aliases, 3-27 schema, 4-3, 4-4 attribute, 4-7 stats, 3-22, 9-2 users, 3-16, 3-17, 3-18, 3-24, 9-2 invoke-id, A-8 grant, 6-19 ISO 9594-10, 9-12 group configuration files, 2-9 defining, 6-24 J file type, 2-5, 2-9, 4-2, 5-9, 5-14, 5-15, 6-20 guard, 5-10, 7-16 JXplorer, 12-1 add audio file, 12-23 add entry, 12-24 H add photo, 12-23 binary values, 12-22 browse, 12-10 Hardware Security Module, 6-3 button bar, 12-5
connect, 12-10 ldifdelta, 11-24 display enries, 12-16 ldifsort, 11-22 edit the directory, 12-17 file launch, 12-23 LDT file, 11-19 LDIF files, 12-26 managing certificates, 12-29 LDUA, 1-14 menu bar, 12-3 leaf entry, A-9, A-11 modify attributes, 12-19 navigate, 12-12 license agreement quick search bar, 12-6 Apache Tomcat, H-1 refresh entries, 12-12 IBM UDDI4j, H-6 search, 12-12 OpenLDAP, H-11 SSL and SASL, 12-27 OpenSSL, H-12 submit entry, 12-25 SUN Java Web Services, H-29 templates, 12-16 Sun JavaHelp, H-25 SUN JRE 1.4, H-19 JXweb TeraTerm, H-33 connect, 13-1 connect to a directory, 13-2 Lightweight Directory Access Protocol. See LDAP display directory information, 13-2 limiting associations, 3-18 limits subdirectory, 2-4 K link-flags dsp-ldap, 3-45 dsp-ldapv2, 3-45 knowledge, 3-1, 6-5 ms-ad, 3-45 directory, 2-4, 3-1 ms-exchange, 3-45 references, 5-3 ssl-encryption, 3-45 ssl-encryption-remote, 3-45 unavailable, 3-45 L list, A-4 existing databases, 11-13 service, A-5 LDAP (Lightweight Directory Access Protocol), 1-12 managing, 8-2 listen address, 8-2 names, 4-5, 4-9 listening address, 2-17, 3-4, 7-13, 8-2 servers, 8-6 list-req, A-1, A-5 ldap-dsa-name, 8-5 load sharing, 2-17, 5-13 ldap-dsa-password, 8-5 DSA, 5-20, 5-21 LDIF local format, 11-21 attributes, 4-16, 8-3 tools, 11-18 data type definition, 4-16, 8-3 LDIF file DSAs, 5-9, 5-11 calculating changes, 11-24 schema, 4-16, 8-3 sort, 11-22 local operations, 3-20 template file, 11-19 local-scope, A-15 ldif2dxc tool, 11-37 error handling, 11-38 log files OID maps, 11-39 alarm-log, 3-9 schema.txt file update, 11-39 alert-log, 3-9
cert-log, 3-9 mod-dn-req, A-1, A-13 closing, 3-11 mod-entry-req, A-1, A-12, A-20 commands, 3-11 connect-log, 3-9 modify, A-9 flush, 3-11 alias, A-20 monitoring, 9-2 directory, 11-30 opening, 3-11 service, A-12 query-log, 3-10 stats-log, 3-10 modify-DN service, A-9, A-13 summary, 3-12 monitoring summary-log, 3-10 active users, 3-17 trace-log, 3-10 CMIP, 9-12 types, 3-8 databases, 9-2 update-log, 3-10 disk space, 9-2 viewing, 3-11 DSP, 5-7 logging subdirectory, 2-4 dxconsole, 9-2 log files, 9-2 login entries, 6-31 multicasting, 5-6, 5-14 logs directory, 2-3 multiple associations, A-3 DSA processes, 2-17 M multi-write monitoring, 9-7 management console, 1-12, 2-14, 6-43 multiwrite queues closing, 2-15 alarms, 7-8 configuration, 2-14 size, 7-7 connecting, A-2 opening, 2-15 multiwrite status, 7-8 Management Information Base. See MIB must-contain, 4-10 managing large numbers of entries, 14-10 large numbers of users, 14-9 N LDAP, 8-2 telnet configuration, 2-14 name, 8-2 mapping, prefixes, 8-6 name binding, 4-14 matching rules, 4-6 aliases, 4-15 max-op-size, A-14 checks, 4-14 considerations, 4-15 max-op-time, A-14 rules, 4-14 structural object classes, 4-15 may-contain, 4-10 name change, A-9 merge, 11-1 native-prefix, 8-6 metadata design, 1-4 navigation, A-18 MIB (Management Information Base), 3-22, 9-7 no compatible link type, 6-17 MIB walker, 9-8 North American Directory Forum, 4-1 migration path, 11-1 nsap, 3-3
O set dsp command, 5-2 set operations command, 3-20 set schema command, 4-3 object class, 4-10, A-11 ssld command, 6-6 checking, 4-11, 4-12 partial results, A-6 kinds, 4-10 abstract, 4-10 password, 3-23, A-2, A-5 auxiliary, 4-11 attribute, 6-10 structural, 4-11 expiry, 6-38 pruning, 4-12 incorrect, 6-39 replacing, 4-12 management, 6-38 protection, 6-31, 6-41 object identifier (OID), 4-4 reset, 6-40 OID prefix, 4-4 performance, 5-13, 11-8 one-level searches, 5-17 degradation, 6-21 tuning, 14-7 opening the managment console, 2-15 permissions, 6-25 OpenLDAP license agreement, H-11 personality, 6-5 OpenSSL license agreement, H-12 certificate generation, 6-5 oper commands, 3-20 pid directory, 2-3 operational attributes, A-16 precedence, 6-19 operations, 3-22 prefer-chaining, A-15 abandon, 3-24 configuration, 3-21 preferredDelivery, 4-6 control, 3-23, 3-24 prefix controlling, 3-22, 3-23 mapping, 8-6 remote, 5-18 schema, 4-4, 4-5 statistics, 3-22 presentationAddress, 4-6 output, controlling, 3-8 printable character, 4-7 priority, A-15 P privileges, 6-30 protected item, 6-27, 6-28 packages, DXconfig, 10-3 defining, 6-30 parallel processing, 5-13 protocol tracing, 3-7 parameters prototyping, 11-1 get access module, 6-24 get assoc command, 3-15 proxy get dib command, 3-25 DSAs, 5-10 get dsp command, 5-3 secure, 6-33 get operations command, 3-21 public users, defining, 6-30 get schema command, 4-3 oper command, 3-21 set access module, 6-23 set assoc command, 3-13, 7-14 Q set dib command, 3-25 set dsa command, 3-2 query-log file, 3-10
R return attribute lists, 12-13 RFC1567, 9-7 RDBMS, 1-4 roles, access controls, 6-32 tools, 1-15 rules, 6-19 read, A-4 components, 6-25 privileges, 6-28 service, A-4 unrestricted, 6-26 S read-only access, 6-30 read-only attributes, 4-5, B-11 samples directory, 1-14, 2-3 read-only DSA, 6-43 schema read-req, A-1, A-4, A-15, A-16 commands, 4-3 defining local, 4-16 references, 5-3, A-5 definition, 4-1 directory, 2-4 referrals, 5-10 local, 4-16, 8-3 registered users, 6-28 management, 4-3 prefixes, 4-4, 4-5 relative distinguished name, 5-15 published, 4-16 relay, 7-14 validation, 4-2 DSA, 5-17 viewing, 4-4 DSP, 5-16 SCHEMA tools, 11-35 reload, 11-1 dxschemaldif, 11-36 dxschematxt, 11-41 rem-entry-req, A-1, A-11, A-19 ldif2dxc, 11-37 remote scope-of-referral, A-15 DUA, A-1 DXcli DUA, A-3 script file description, 2-12 remote connections, 5-4, 5-5, 5-17 errors, 2-13 remote operations, 5-18 type, 2-5 remove, A-9 search, A-4 alias, A-19 a directory, 11-28 service, A-11 complex, 12-13 indexing options, 3-28 rename a directory, 11-33 quick, 12-12 replication, 7-1 return attribute lists, 12-13 clock synchronization, 7-1 service, A-6 directory, 2-4 templates, 12-14 using DXtools, 7-17 UDDI repositories, 15-4 repository, UDDI, 15-1 search-req, A-1, A-6 reset stats, 3-22 secure proxy, 6-33 resetting statistics, 3-22 Secure Socket Layer, 6-2 responder, 7-14 security, 5-13 restore a database, 11-7 security level, 3-23, 3-24, 3-28
server assoc, 3-13, 7-14 configuration, 2-2 dib, 3-25 DXweb, 1-15 dsp, 5-2 initialization, 2-6 operations, 3-20 UDDI, 15-2 set commands, access control servers subdirectory, 2-4 access-controls, 3-23 admin-user, 6-27 service group, 6-24 abandon, A-8 protected-items, 6-30 add, A-10 read-only, 6-43 compare, A-5 super-user, 6-26 errors, C-7 list, A-5 set commands, associations modify, A-12 allow-binds, 3-17 modify-DN, A-13 authentication, 3-17 read, A-4 credits, 3-19 remove, A-11 max-bind-time, 3-17 search, A-6 max-users, 3-18 min-auth, 6-9 service commands user-idle-time, 3-18 abandon-req, A-1 add-entry-req, A-1 set commands, DIB bind-req, A-1 alias-integrity, 3-27 compare-req, A-1 database-name, 2-17, 2-18, 3-26 list-req, A-1 eis-count-attr, 3-27 mod-dn-req, A-1 index-reverse, 3-28 mod-entry-req, A-1 index-wide, 3-28 read-req, A-1 not-searchable, 3-28 rem-entry-req, A-1 set commands, DISP search-req, A-1 agreement, 7-14 unbind-req, A-1 set commands, DSAs service controls always-chain-down, 5-10 chaining-prohibited, A-15 dsa, 3-1, 5-9, 5-11, 5-12, 5-13, 5-20, 5-21, 6-4, 6-5, 7- dont-deref-aliases, A-15 6, 7-16, 8-6 dont-use-copy, A-15 precedence, 5-19 local-scope, A-15 prefer-chaining, A-15 set commands, DSP max-dsp-ops, 5-4 service error multi-casting, 5-6 administration limit exceeded, 3-24 operation abandoned, 3-24 set commands, local operations max-local-ops, 3-22, 3-23 service modifiers max-op-size, 3-23, 3-24 priority, A-15 max-op-time, 3-24 scope-of-referral, A-15 set commands, logs set logtype, 3-11 prune-oc-parents, 4-12 summary-log, 3-12 public-user, 6-30 reg-user, 6-28 set commands, mutliwrite return-oc-parents, 4-12 multi-write-queue, 7-7 schema, 4-3 set commands, schema set commands attribute, 4-5 access, 6-23 attribute, 4-4, 4-9, 4-17
attr-set, 4-8, 4-17 structural object classes, 4-11 name-binding, 4-14, 4-17 summary-log file, 3-10 object-class, 4-10, 4-17 oid-prefix, 4-4, 4-17 SUN Java Web Services license agreement, H-29 set commands, traces Sun JavaHelp license agreement, H-25 trace, 3-7 SUN JRE 1.4 license agreement, H-19 settings subdirectory, 2-4 superuser shadow DSAs, 7-16 password, 6-10 privileges, 6-30 shortcuts for commands, 2-16 synchronization, replication, 7-1 shutdown command, 3-16 syntax Simple Network Management Protocol. See SNMP attribute, 4-2, 4-6 single-valued attributes, 4-5 commands, 2-11 undefined, 4-6 size limit, A-6, A-9, A-14 SNMP (Simple Network Management Protocol), 1-12, 3-22, 9-1 T MIB walker, 9-8 snmp-port, 9-8 telephoneNumber, 4-6 sort an LDIF file, 11-22 teletexTerminalId, 4-6 SSL authentication, 6-11 telexNumber, 4-6 configuring DXserver, 6-4 telnet, 9-1 connections, 6-4 daemon, 6-3 template file, 11-19 enabling, 6-2 TeraTerm license agreement, H-33 SSLD, 6-3 test script, A-1 configuring, 6-6 time limit, A-6, A-14 static access controls, 6-22 manage, 6-23 timeouts, 3-22 rules, 6-22 tModels, 15-5 statistics tools monitoring, 9-2 csv2ldif, 11-21 resetting, 3-22 dxadduser, 11-13 traced, 3-7 dxbackupdb, 11-6 viewing, 3-22 dxdelete, 11-34 stats-log file, 3-10 dxdeluser, 11-13 dxdestroydb, 11-5 statuses dxdumpdb, 11-16 multiwrite, 7-8 dxemptydb, 11-5 stopping DSAs, 3-16 dxextenddb, 11-4 dxgrantdb, 11-17 strategy, 7-14, 7-15 dxindexdb, 11-9 string labels, 8-2 dxlistdb, 11-13 dxloaddb, 11-14 strong authentication, 6-17 dxmodify, 11-30 dxnewdb, 11-4
dxnewdsa, 11-3 unbind-req, A-1, A-3 dxrename, 11-33 undefined syntax, 4-6 dxrestoredb, 11-7 dxschemaldif, 11-36 Universal Description, Discovery and Integration. See dxschematxt, 11-41 UDDI dxsearch, 11-28 dxstatdb, 11-12 unrestricted read, 6-26 dxtunedb, 11-8 update access, 6-26 dxupgradedb, 11-17 ldif2dxc, 11-37 update error, naming violation, 4-14 ldifdelta, 11-24 update-log file, 3-10 RDBMS, 1-15 URL pages, launching of, 12-34 trace, 6-42 command, 3-5, 3-7 users protocol, 3-7 administrative, 6-10, 6-27 statistics, 3-7 associations, 3-16 authentication, 6-11 trace-log file, 3-10 conveying authentication, 6-16 tracing, 3-5 current, 3-24 associations, 3-16 defining, 6-9, 6-10 defining superusers, 6-26 transparent routing, 5-16 distributed, 6-13 trust subdirectory, 2-4 limit in associations, 3-18 managing large numbers, 14-9 trust-flags maximum number to bind, 3-18 allow-check-password, 3-44 monitoring, 3-17 allow-downgrading, 3-44 name, 3-17 allow-upgrading, 3-44 number of, 3-17 no-server-credentials, 3-44 public, 6-30 trust-conveyed-originator, 3-44 registered, 6-28 superusers, 6-10, 6-26 tuning a database, 11-8
U V
version, 2-7 UDDI (Universal Description, Discovery and Integration), 15-1 viewing API, 15-2 access controls, 6-36 assoc configuration, 3-15 UDDI Registry, 15-2 associations, 3-16 UDDI repositories, 15-1 communication settings, 3-4 business entities, 15-4 DIB configuration, 3-26 publishing to, 15-4 DSP configuration, 5-7 search, 15-4 operation configuration, 3-21 tModels, 15-5 operation statistics, 3-22 schema, 4-4 UDDI servers, 15-2 connecting to, 15-3 UDDI Web Client, 15-3 unbind, outgoing connections, 5-5
X schema, 4-2 tracing, 3-16 X.509 certificates, 6-2 X.435, 4-1 X.520 X.500 attribute syntax, 4-6 access controls, 6-36 attributes, 4-5 guard, 5-10, 7-16 information types, 4-2 X.521, object classes, 4-10 object class kinds, 4-10