eTrust® Directory
Administrator Guide r8.1
Second Edition
This documentation (the “Documentation”) and related computer software program (the “Software”) (hereinafter collectively referred to as the “Product”) is for the end user’s informational purposes only and is subject to change or withdrawal by CA at any time.
This Product may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Product 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 the Documentation for their own internal use, and may make one copy of the Software as reasonably required for back-up and disaster recovery purposes, 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 provisions of the license for the Software are permitted to have access to such copies.
The right to print copies of the Documentation and to make a copy of the Software 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 certify in writing to CA that all copies and partial copies of the Product have been returned to CA or destroyed.
EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS PRODUCT “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS PRODUCT, 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 this Product and any product referenced in the Documentation is governed by the end user’s applicable license agreement.
The manufacturer of this Product is CA.
This Product is provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7013(c)(1)(ii), as applicable, or their successors.
All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Copyright © 2005 CA. All rights reserved.
Contents
Chapter 1: Introduction 1 What is eTrust Directory? ...... 1 eTrust Directory Modules...... 2 Documentation ...... 7 Formatting Conventions ...... 9 CA Product References...... 9
Chapter 2: DXserver Overview 11 What is DXserver?...... 11 Configuration Files ...... 13 eTrust Directory Commands ...... 18 DXserver Script Language ...... 19 DXconsole...... 22 Databases...... 35
Chapter 3: General Administration 39 Defining DSAs with the set dsa Command...... 39 Alarms, Traces, and Logs ...... 42 Associations ...... 45 Local Operations ...... 53 The Directory Information Base...... 57 Cache DSAs ...... 67 Cache-Only DSAs...... 80 Virtual Attributes ...... 84 Virtual Directory ...... 96 Knowledge Flags ...... 108
Chapter 4: Schema Definition 113 What Is a Schema? ...... 113 Supported Schema Protocols ...... 114 Configuring Schema ...... 115 Attributes ...... 119 Object Classes...... 130 Dynamic Objects...... 134 Name Bindings ...... 143
Contents iii
Defining Local Schema...... 146
Chapter 5: Distribution and DSP 149 Distribution Protocols...... 149 Managing DSP ...... 150 Configuring a DSA...... 157 Configuring Another DSA...... 160 Configuring a Domain of DSAs ...... 163 Alternative DSAs...... 168 Aliases ...... 178
Chapter 6: Security 179 Protecting Communications with SSL Encryption ...... 179 Authentication ...... 193 How Password Management Works ...... 206 Managing Passwords ...... 212 Access Control Overview ...... 220 Static Access Controls...... 224 Dynamic Access Controls...... 233 Groups, Roles, and Proxies ...... 235 Access-Controlled Routing ...... 243
Chapter 7: Replication 245 Replication Concepts ...... 245 About Multiwrite Replication...... 250 Work with Multiwrite Replication...... 266 DISP Replication ...... 274 Manually Synchronizing Replicas Using Database Tools ...... 283
Chapter 8: LDAP and DXlink 285 LDAP Integration with eTrust Directory...... 285 LDAP Clients...... 286 Schema Publishing ...... 288 LDAP Controls ...... 290 Integrating Other LDAP Servers ...... 293
Chapter 9: Monitoring the Directory 301 Supported Protocols ...... 301 General Monitoring...... 302
iv Administrator Guide
SNMP and the Directory Monitoring MIB ...... 304 CMIP and X.700 Management ...... 310
Chapter 10: Tools for Managing eTrust Directory 313 What Are the DXtools?...... 313 Using DXtools...... 313 Database Tools ...... 314 LDIF Tools ...... 316 DAP Tools ...... 320 Schema Tools...... 321
Chapter 11: About JXplorer 323 What Is JXplorer?...... 324 The JXplorer Browser...... 325 How JXplorer Connects to a Directory...... 333 How JXplorer Searches a Directory ...... 336 Bookmarks...... 343 How JXplorer Lets You Edit the Directory ...... 344 How JXplorer Reads the Schema ...... 358 How JXplorer Handles Importing and Exporting Data ...... 361 How JXplorer Works with Aliases ...... 362 How JXplorer Handles Passwords...... 367 How JXplorer Handles SSL, SASL, and Certificates ...... 370 JXplorer Logging ...... 373 Customize JXplorer...... 373 Troubleshooting ...... 373 LDAP and Directory Resources ...... 374
Chapter 12: Using JXplorer 375 Connect...... 375 Search the Directory...... 380 Display Directory Information ...... 386 Work with Directory Entries ...... 388 Work with Attributes...... 395 Add Binary Files...... 400 Launch and Save Binary Files...... 403 Import and Export Using LDIF Files...... 405 Manage Certificates ...... 408 Manage Bookmarks ...... 413 Configure JXplorer...... 415
Contents v
Chapter 13: Using JXweb 425 About JXweb ...... 426 Get Started with JXweb...... 428 Search the Directory...... 432 Create and Delete Entries...... 435 Modify Entries ...... 440 Change Entry Names ...... 443 Copy and Move Entries ...... 446 Manage Certificates ...... 447 View Schemas ...... 449 Configure JXweb ...... 453
Chapter 14: Using DXmanager 457 What is DXmanager...... 457 How DXmanager Works ...... 460 How Polling Works...... 462 What Are Alerts ...... 462 DXmanager Security...... 463 Setting Up and Securing DXmanager ...... 467 Working with DXmanager...... 478 Troubleshooting ...... 487
Chapter 15: Using The UDDI Server and UDDI Client 491 About the UDDI Server ...... 492 About UDDI Registries ...... 493 Sample Data ...... 494 Work with the UDDI Client...... 495 Use the UDDI Client in Languages Other Than English ...... 500 Using tModels...... 501
Chapter 16: Using the DSML Server 503 About DSML ...... 503 What Is the DSML Server?...... 503 How the DSML Server Works ...... 504 Connect to the DSML Server ...... 506 Change the DSML Properties...... 507
Chapter 17: Using the Sample DSAs, Applications, and Tools 509 Implementing the Samples...... 509
vi Administrator Guide
The Sample DSAs ...... 510 Sample Web Applications ...... 515 Sample Configuration Files ...... 520 Sample Tools...... 521
Chapter 18: Deploying a Directory 543 Directory Design ...... 543 Operations and Practices...... 548 Troubleshooting ...... 552
Chapter 19: Tailoring the RDBMS 555 Tips for Navigation ...... 555 Changing the Default Page Size...... 556 Stop and Restart Ingres on Windows...... 557 Stop and Restart Ingres on UNIX...... 558 Test Connection to the Database ...... 558 Increasing the Number of Cache Pages...... 559 Increasing the Number of Database Connections ...... 560 Other Customizations ...... 562
Chapter 20: Error and Diagnostic Logs 563 Types of Logs ...... 563 Working with Logs...... 568
Chapter 21: Installing eTrust Directory for Windows 571 Installation Overview...... 571 Upgrade eTrust Directory ...... 577 Install eTrust Directory Using the Product Explorer...... 580 Install eTrust Directory Using Commands ...... 588 Install eTrust Directory Silently ...... 594 Uninstall eTrust Directory ...... 598 Troubleshooting ...... 599
Chapter 22: Installing eTrust Directory for UNIX 601 Installation Overview...... 601 Upgrade eTrust Directory ...... 606 Install eTrust Directory Using the Installation Program ...... 607 Install eTrust Directory Using Commands ...... 624 Install eTrust Directory Silently ...... 626
Contents vii
Install on Solaris...... 630 Troubleshooting ...... 634
Glossary 637
viii Administrator Guide
Chapter 1: Introduction
This section contains the following topics: What is eTrust Directory? (see page 1) eTrust Directory Modules (see page 2) Documentation (see page 7) Formatting Conventions (see page 9) CA Product References (see page 9) Contact Customer Support (see page 9)
What is eTrust Directory?
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 eTrust Directory Modules
eTrust Directory Modules
The following diagram shows the components of eTrust Directory:
DXserver
This is the eTrust Directory server component.
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, advanced security, and multiwrite replication.
2 Administrator Guide
eTrust Directory Modules
The Relational Database Management System (RDBMS)
The Ingres r3 RDBMS is supplied with eTrust Directory.
Relational databases provide proven robustness and reliability, scalability, ability to work with legacy SQL systems, and performance. However, relational databases lack the distribution facilities provided by X.500.
eTrust Directory works with an SQL database that physically stores and retrieves information from disk. eTrust Directory uses an SQL interface and a meta-data table design to connect to the embedded RDBMS.
Instead of duplicating services, eTrust Directory passes the following issues to the RDBMS:
Logging
Caching
Query optimization
Multiprocessing and locking
Check-pointing and recovery
International character sets and collating sequences
Database table and indexing management
Housekeeping and tuning utilities
RDBMS tools that provide support for the RDBMS. See the Ingres documentation set for more information.
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 the cache is configured. For more information, see Cache DSAs (see page 67).
DXmanager
DXmanager is a graphical, web-based eTrust Directory administration tool. Use DXmanager to monitor and control your DSAs.
JXplorer
JXplorer is a Java-based LDAP browser and editor. You can use JXplorer to work with directory data, schemas and certificates.
For more information, see Using JXplorer (see page 375).
Introduction 3 eTrust Directory Modules
JXweb
JXweb is a web-based LDAP browser and editor. You can use JXweb to do almost everything that JXplorer can do.
For more information, see Using JXweb (see page 425).
DSML Server
This is a DSML server that converts DSML to LDAP and vice versa. This allows client applications that use DSML (including web services) to communicate with eTrust Directory without using LDAP directly.
UDDI Server and UDDI Client
The UDDI Server is an implementation of the UDDI standards.
The UDDI Client is a web-based browser and editor that lets you work with the UDDI Server.
For more information, see Using The UDDI Server and UDDI Client (see page 491).
DXtools
The DXtools are a flexible set of utilities for importing, exporting, and synchronizing data with external data systems. This includes some database tools for managing the Ingres database.
The DXtools provide general data management facilities, including:
Managing databases
Tuning and backing up directory data
Importing and exporting directory data
Bulk loading databases from a prepared LDIF file
Bulk extracting a database to an LDIF file for comparison
LDIF sorting and comparison
For descriptions of these tools, see Using DXtools (see page 313).
4 Administrator Guide
eTrust Directory Modules
RDBMS Tools
The RDBMS tools provide support for the RDBMS. See the Ingres product documentation set for further details.
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).
Samples
eTrust Directory comes with some sample configuration files and utilities, to help you with testing and demonstrating eTrust Directory. These samples are installed in the following ../dxserver/samples subdirectories: 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 ldua Sample text-based DUA that runs over LDAP router An example router DSA that does not use a database and has the prefix c = AU, and is aware of the Democorp and UNSPSC DSAs.
schema A Perl schema translation tool to update schema.txt for the DXtools snmp An executable to request SNMP information from the directory. soak An executable to measure the throughput (in searches per second) of a DSA. ssl Examples of using DUA-DSA and DSA-DSA SSL authentication and encryption.
Introduction 5 eTrust Directory Modules
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.
Web Samples
eTrust Directory comes with some samples of web applications. You can also create your own web-based GUIs to suit your organization. Sample SAML server The SAML server is a lightweight SAML attribute server. This allows client applications that use SAML (including web services) to communicate with eTrust Directory without using LDAP directly. Sample SPML server The SPML server lets you add users to the directory, modify the attributes of existing users, or delete users. UDDI demonstration This sample application is a demonstration of a typical application of a UDDI server. It shows a web site that compares prices on airline flights by looking up the prices on different web servers, which are registered with a UDDI server.
For more information, see Sample Web Applications (see page 515).
6 Administrator Guide
Documentation
Documentation
eTrust Directory comes with documentation to help you get the most out of it.
Use this section to find out which documents are designed to help you in which circumstances.
Release Information
The following release information comes with eTrust Directory: Readme The Readme lists the supported platforms and system requirements, known issues, and any last-minute notices. Use the Readme to find out if any known issues affect areas of eTrust Directory that you plan to use. Release Notes The Release Notes list the issues that have been fixed in this release, with the associated STAR or LabTrack numbers. Use the Release Notes to track when the issues you are interested in are fixed. Release Summary (a PDF guide) The eTrust Directory Release Summary briefly describes new features and enhancement sin this release. Use this guide to find out what's new. You can then find out more in the eTrust Directory Administrator Guide.
Introduction 7
Documentation
PDF Guides
The following PDF guides come with eTrust Directory: Administrator Guide The eTrust Directory Administrator Guide is a PDF guide that includes detailed descriptions of how eTrust Directory works, and how to use it. Use this guide if you need to understand a feature or learn how to use it. Reference Guide The eTrust Directory Reference Guide is a PDF guide that includes lists of commands, settings, files, and so on. This guide is useful if you already understand a feature and just need to be reminded. Getting Started The eTrust Directory Getting Started is a PDF guide that includes a brief description of how to install eTrust Directory, and some short tutorials on how to use some of the components. This guide is useful for getting to know eTrust Directory. User Guide The eTrust Directory User Guide gives instructions for implementing some of the features described in the eTrust Directory Administrator Guide. Developer Guide The eTrust Directory Developer Guide describes how to extend eTrust Directory. It describes how to customize JXplorer, how to use the DUA commands for batch operations, and how to extend the UDDI Server.
Online Help
The following online help comes with eTrust Directory clients: JXplorer online help The JXplorer online help describes how to use JXplorer. Use the online help when you want to know how to do a task. Use the eTrust Directory Administrator Guide to find out how JXplorer works. JXweb online help The JXweb online help describes how to use JXweb. Use the online help when you want to know how to do a task. Use the eTrust Directory Administrator Guide to find out how JXweb works.
8 Administrator Guide
Formatting Conventions
Formatting Conventions
In this guide, commands are shown in a different font from the main text, as in this example:
get dynamic-group;
If a command includes a variable that you must replace, that variable appears in italic text. In this example, you must replace the text assoc-number with the actual association number:
abort user assoc-number;
If you must enter only one of a list of options, the options are shown separated by the pipe character |. In this example, you should choose either true or false:
set access-controls = true | false;
CA Product References
This document references the following Computer Associates International, Inc. (CA) products:
eTrust® Embedded IAM (eIAM)
eTrust® Single Sign-On (eTrust SSO)
Ingres
Contact Customer Support
For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact Customer Support at http://ca.com/support.
Introduction 9
Chapter 2: DXserver Overview
This section contains the following topics: What is DXserver? (see page 11) Configuration Files (see page 13) eTrust Directory Commands (see page 18) DXserver Script Language (see page 19) DXconsole (see page 22) Databases (see page 35)
What is DXserver?
The eTrust Directory server component is named DXserver.
DXserver can be operated as a directory in a standalone mode similar to other LDAP servers. DXserver can also be configured to operate in a distributed environment as a full-featured X.500 Directory System Agent (DSA) supporting all the powerful X.500 features such as chaining, parallel searching, distributed management and advanced security.
DXserver supports many communications protocols and management facilities, including:
User access protocols (DAP, LDAP)
System (inter server) protocols (DSP, DISP)
Management protocols (SNMP, CMIP)
Input commands (from script files or management console)
Logging Services (alarms, traces, management responses)
DXserver Overview 11
What is DXserver?
64-Bit DXserver
A 64-bit DXserver is included in those UNIX packages that contain $DXHOME/bin/lp64.
To activate the 64-bit DXserver 1. For the user dsa, add the path $DXHOME/bin/lp64 to the $PATH variable. To do this, add the following lines to the end of the .dxcshrc login script (by default this is in $DXHOME/install/.dxcshrc):
# 64-bit DXserver set path = ($DXHOME/bin/lp64 $path )
2. Add the following lines to the end of the .dxprofile login script (by default this is in $DXHOME/install/.dxprofile):
# 64-bit DXserver PATH=$DXHOME/bin/lp64:${PATH} export PATH
To switch from 64-bit back to 32-bit
Remove the additional lines from the login scripts.
12 Administrator Guide
Configuration Files
Configuration Files
eTrust Directory stores configuration information in a structured directory tree. The easy-to-use, hierarchical tree defines the conventions and the strategy for managing the directory system that can extend to multiple servers, multiple machines, and multiple platforms.
The configuration files should be managed from a central station. The directories are shared across all servers to ensure consistency in system operation. This architecture also lets you manage versions of the configuration files, because you can store these files in a document or source control system.
For a list of the types of configuration files, see Configuration File Types in the eTrust Directory Reference Guide.
Sample Configuration Files
DXserver contains a working example DSA configuration. You can use the example server without modification as described in the appendixes “Installing DXserver for Windows” and “Installing DXserver for UNIX.” The example contains three DXserver configurations-Router, Democorp and UNSPSC.
DXserver Overview 13
Configuration Files
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/";
14 Administrator Guide
Configuration Files
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:
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.
For 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, you need to edit only one file: TestCorp.dxg.
DXserver Overview 15
Configuration Files
Knowledge Files
This section describes what knowledge files are, and how to use them.
In most situations, each DSA has a single knowledge file, which contains a single set dsa command. This command contains many options, which control how that DSA works, including what operations from remote DSAs are to be permitted or denied.
The knowledge files are usually named dsaname.dxc, where dsaname is the case-insensitive name of the DSA. The knowledge files for the DSAs on a computer are kept in the DXHOME\config\knowledge directory.
Each DSA must source its own knowledge file, which defines how that DSA works. Each DSA can also source the knowledge files for other (remote) DSAs. These files define how the local DSA works with the remote DSA.
For information about knowledge flags, see Knowledge Flags (see page 108).
The commands in the knowledge file must appear in the correct order. For information about this order, see the text file DXHOME\config\knowledge\knowledge.help.
Using Knowledge Files in a Single-Server Environment
If your directory includes more than one DSA, you need to consider how you work with your knowledge files.
If all of the DSAs happen to be one the same computer, they can all source the same copy of the knowledge files.
Router DSA Server A
router.dxc
unspsc.dxc
democorp .dxc
Democorp UNSPSC DSA DSA
16 Administrator Guide
Configuration Files
Using Knowledge Files in a Distributed Environment
However, it is more likely that the DSAs in a distributed system are on different computers. To make sure that operations are not slowed down by network limitations, each DSA should use its own local copy of the knowledge files.
We recommend that you make any changes to only one of these sets of knowledge files, and then copy the changed files to the other locations. This will help you keep the knowledge files synchronized.
For example, in the system shown here, you could use the knowledge files on Server A as the master copies. Whenever you need to change a knowledge file, you would make the change on Server A. You could then copy the changed files to the other two servers.
Server A
router.dxc
Router DSA unspsc.dxc
democorp .dxc
Server C router.dxc Democorp unspsc.dxc router.dxc DSA unspsc.dxc democorp .dxc UNSPSC DSA democorp .dxc Server B
DXserver Overview 17 eTrust Directory Commands
eTrust Directory Commands
When a DSA starts, 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 a DSA 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).
Important! You must start the database before starting the DSA. If an error occurs while reading the configuration files, the DSA cannot start. You can find information about this error in both the operating system error log and the DSA alarm and trace log files in the dxserver/logs directory.
For a full description of the commands, see the chapter eTrust Directory Commands in the eTrust Directory Reference Guide.
See Installing eTrust Directory for Windows (see page 601) and Installing eTrust Directory for UNIX (see page 601) for information about starting and stopping a DSA.
18 Administrator Guide
DXserver Script Language
DXserver Script Language
You can use the DXserver commands to control every aspect of eTrust Directory 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 General Administration (see page 39))
Schema commands (see Schema Definition (see page 113))
DSA and distribution commands (see Distribution and DSP (see page 149))
Security commands (see Security (see page 179))
Replication commands (see Replication (see page 245))
X.500 commands (see the eTrust Directory Developer Guide)
DXserver Overview 19
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=
But how is this done in other languages? LDAPv3 has standardized on UTF-8 for internationalization. An example, using UTF-8, is now:
mod-entry-req entry=
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, the following continuation prompt displays until you enter a semicolon:
--->
You can interrupt the execution of a script file from the management console using the telnet commands Ctrl-c or Ctrl-x. See DXconsole (see page 22) for more information.
20 Administrator Guide
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";
A configuration file (.dxi, .dxc, or .dxg) is a special form of script file.
Within a script file, the # sign introduces a comment. DXserver treats the # and all text after it, to the end of the line, as a comment.
A script file can source other script files. The source command is relative to the file that invokes it. For example, when you source the file schema.dxg using the command:
source "../schema/schema.dxg";
then the schema.dxg script can source a file in its own directory using the command:
source "attr.dxc";
Script File Errors and Debugging
Usually the system does not echo commands in script files before they are executed. If there is an error in the script file, a message similar to the following is displayed:
>>>> set allow-binds = 1; ------^ (line 12 in 'test.dxc') Syntax Error: Expected 'true' or 'false'
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 21
DXconsole
DXconsole
The management console, DXconsole, lets you enter commands interactively. It lets you monitor users, modify administrative controls, and perform actions.
DXconsole also includes a powerful co-resident directory client (DUA) command-line interface, which you can use to enter user queries for diagnostic or prototyping tasks.
For more information about the DUA, see the eTrust Directory Developer Guide.
DXconsole Security
For security reasons, DXconsole is only accessible from the local computer.
The management console only accepts one telnet session. To prevent anyone else from starting up DXconsole, make sure you keep DXconsole always running.
To prevent attacks from remote telnet sessions, define a console port in the DSA knowledge. This scheme uses the local host security. An administrator must have an account on the local computer to communicate with the DSA through this port.
You can use the console remotely when you set the remote-console-port flag. You can attach a password, and SSL may be required. See Configuring DXconsole (see page 24) for more information.
22 Administrator Guide
DXconsole
Opening 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
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 23
DXconsole
Configuring DXconsole
DXconsole can be enabled either locally or remotely.
The remote DXconsole provides the DSA administrator with a means of managing the DSA. The access protocol is telnet. To remotely manage a DSA using DXconsole, either log in 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 Wind o w DSA
By default, DXconsole is only accessible from localhost for security reasons.
To enable DXconsole, you must define the console port in the knowledge file of the DSA. For more information, see Defining DSAs (see page 39).
For a list of all ports in a default installation of eTrust Directory, see the section Port Numbers Used by eTrust Directory in the eTrust Directory Reference Guide.
The DXconsole Command Options
To configure DXconsole, include the following options in the DSA knowledge file:
Option Parameter Description console-port Port number Allows DXconsole to accept connections from the local computer. When this is not specified, the DSA does not have a local console. remote-console-port Port number Allows DXconsole to accept a connection from a remote computer on this port. When this is not specified, there is no remote console for the DSA. console-password Password The password required for connections from a remote computer. This password is transmitted in clear text. remote-console-ssl Boolean Forces DXconsole to encrypt sessions when it runs remotely.
Note: The commands in the knowledge file must appear in the correct order.
For information about this order, see the text file DXHOME\config\knowledge\knowledge.help.
24 Administrator Guide
DXconsole
Configure DXconsole to Run Locally
To enable DXconsole locally, include the following command in the DSA knowledge:
set dsa dsaname = { ... console-port = port_number ... };
where dsaname Specifies the name of the DSA port_number Specifies the DSA's console port
Example DXconsole Configuration: Local
In the following sample configuration, the line console-port = 19390 defines the port that DXconsole will use to accept local connections only:
set dsa DEMOCORP = { prefix =
DXserver Overview 25
DXconsole
Configure DXconsole to Run Remotely
You can connect to DXconsole from a remote computer, using a password for authentication.
Although this method allows remote access and some security, the password that is sent to DXconsole from the client is transmitted in clear text. This poses a moderate security risk on unsecured networks.
To provide security, you can specify a console password. When this is set, the user is prompted for a password before a connection is made.
Important! If you do not want the password to be displayed when it is entered, you must turn local echo OFF on the Telnet session.
To enable DXconsole remotely, include the following commands in the DSA knowledge:
set dsa dsaname = { ... remote-console-port = port_number console-password = password ... };
where dsaname Specifies the name of the DSA port_number Specifies the DSA's remote console port password Specifies the DXconsole password
26 Administrator Guide
DXconsole
Example DXconsole Configuration: Remote
In the following sample configuration, the console is running remotely:
set dsa DEMOCORP = { prefix =
DXserver Overview 27
DXconsole
Configure DXconsole to Run Securely and Remotely
You can force the remote console connection to run over TLS. This ensures that console commands and passwords are not transmitted in-the-clear over public networks.
Only one console session can be active at any one time, even if both the console-port and remote-console-port flags are set.
To force DXconsole to use SSL/TLS when it is running remotely, add the following settings:
set dsa dsaname = { ... remote-console-port = port_number remote-console-ssl = true console-password = password ... }
where dsaname Specifies the name of the DSA port_number Specifies the DSA's remote console port password Specifies the DXconsole password
28 Administrator Guide
DXconsole
Example DXconsole Configuration: Remote and Secure
In the following sample configuration, the console is running remotely, and SSL-encrypted:
set dsa DEMOCORP = { prefix =
DXserver Overview 29
DXconsole
Encrypt the DXconsole Password
The console password may be hashed for security.
To store the DXconsole password as a hash, follow these steps: 1. Choose an algorithm to encrypt the password. 2. Use the algorithm to encrypt your chosen password. 3. Add the following line to the DSA knowledge:
set dsa dsaname = { ... console-password = "{password-format}password-hash" ... };
password-format Specifies one of the following encryption formats: SHA Specifies that the password was encrypted using SHA1 SSHA Specifies that the password was encrypted using Salted SHA1 CRYPT Specifies that the password was encrypted using UNIX encryption MD5 Specifies that the password was encrypted using MD5 encryption password-hash Is the password, encrypted using the specified algorithm
The double quotes are necessary to escape the { character.
Important! Do not use password as a password.
30 Administrator Guide
DXconsole
Example DXconsole Configuration: Encrypted Password
The following example uses the SHA-1 hash of the word password:
set dsa DEMOCORP = { ... console-password = "{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=" ...
};
Important! Do not use the hash in this example in your own configuration. You must choose your own password, then encrypt it.
Test the Secure Remote DXconsole Using TLSclient
The TLSclient utility establishes an encrypted tunnel between the remote console client and the DSA. The steps to configure the DSA and TLSclient are as follows: 1. Create the TLSclient configuration file on the client machine 2. Configure the DSA for SSL connections to DXconsole on the server machine 3. Start TLSclient on the client 4. Start the DSA on the server 5. Test the connection
DXserver Overview 31
DXconsole
Create the TLSclient Configuration File
To configure TLSclient, you will need to create the following file on the client computer:
Windows: %DXHOME%\config\tlsclient\tlsclient.cfg
UNIX: $DXHOME/config/tlsclient/tlsclient.cfg
This implies that eTrust Directory is also installed on the client computer, although this may not be required. The only requirement should be that the environment variable DXHOME is set and the trusted root certificate is available.
The format for tlsclient.cfg is:
inPort outPort remoteAddress
inPort The port on the client computer that will be used for tunneling outPort The DXconsole remote-console-port on the server remoteAddress The hostname of the server running the DXconsole you wish to connect to.
Here is an example for the sample Democorp DSA running on the server computer:
19390 19395 hostname.ca.com
Start TLSclient
TLSclient can be installed to the system services using the command:
tlsclient install
Here is an example for the Democorp DSA:
tlsclient install democorp -ca config/ssld/trusted.pem
You can then start the TLSclient instance with:
tlsclient start
For the Democorp DSA example, this would be:
tlsclient start Democorp
32 Administrator Guide
DXconsole
Starting DXserver
To start DXserver, do the following: 1. Ensure that the DSA is stopped: dxserver stop dsaname
2. Start the DSA: dxserver start dsaname
Testing the Connection
To test this connection, do the following: 1. Open the DXconsole client, or your favorite Telnet program, on the client machine 2. Connect to the inPort (defined in tlsclient.cfg) on the local machine (19390 in the Democorp sample) 3. Enter the DXconsole password when prompted
You now have a fully-functioning SSL-encrypted connection to DXconsole on the server machine.
To verify this, try one of the following:
Start TLSclient with the debug option
Set trace all; on the DSA
Use a packet-snooping application.
DXserver Overview 33
DXconsole
Help Command
The help command lists the outer-level commands for the DSA administration modules, X.500 services, and management scripts.
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;
34 Administrator Guide
Databases
Databases
eTrust Directory consists of two major components. These are the DSA process and its underlying database. The DSA process is the X.500/LDAP directory object and protocol processing system and the database is used to store and retrieve the dismantled directory objects (entries) in the specially designed database tables.
You can use the DSA process as a router engine, or configure it to be responsible for a portion (or all) of the DIT. When a DSA process is not acting just as a directory protocol router (for distribution or alternate, load balancing DSAs), it should be considered as a process that is responsible for a DIT Namespace.
Set Database Name
When a DSA starts, 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 = database-name;
where database-name is the name of a database.
For information about restrictions on database names, see the Readme.
For more information about setting database names see The Directory Information Base (see page 57).
DXserver Overview 35
Databases
Multiple DSA Processes to One DIT/DIB
More than one DSA can access the same X.500 DIT/DIB database (for example, to provide load sharing and increased user counts). There is no possibility of database inconsistency because the database management system enforces full locking controls.
When multiple DSAs on the same machine access the same database, you must configure each DSA with unique listening addresses within their knowledge files. For more information, see Defining DSAs with the set dsa Command (see page 39).
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.
36 Administrator Guide
Databases
Hot Swap: Change Database Name While DSA Active
You can change the database name while the DSA is active without disconnecting or disrupting directory clients, using the following command:
set database-name = newdb;
where newdb is the name of another RDBMS database, which must already exist.
You can switch to a newly reorganized database, a hot standby copy, or a restored copy by using the hot swap of a database.
DXserver Overview 37
Chapter 3: General Administration
This section contains the following topics: Defining DSAs with the set dsa Command (see page 39) Alarms, Traces, and Logs (see page 42) Associations (see page 45) Local Operations (see page 53) The Directory Information Base (see page 57) Cache DSAs (see page 67) Cache-Only DSAs (see page 80) Virtual Attributes (see page 84) Virtual Directory (see page 96) Knowledge Flags (see page 108)
Defining DSAs with the set dsa Command
The set dsa command defines the basic properties of each DSA or LDAP server in the system. These DSAs include the local DSA itself, any remote DSAs (either on the same system or on other systems), and other X.500 or LDAP servers. Information about other directories, how to connect to them, their role (for example, Replicas) and the entry namespace they manage is referred to as knowledge. The total “knowledge” of the system is used to form a backbone of directory servers to which each DSA belongs (a directory system).
The DSA is defined in a configuration file (.dxc) in the knowledge directory (along with other DSA definitions). A DXserver determines its own entry (identity) by looking for its own name among all the set dsa definitions.
Important! A DSA must use its own name (case insensitive) from the initialization file: serverName.dxi.
Note: The commands in the knowledge file must appear in the correct order. For information about this order, see the text file DXHOME\config\knowledge\knowledge.help.
For information about the set dsa command, see eTrust Directory Commands in the eTrust Directory Reference Guide.
General Administration 39
Defining DSAs with the set dsa Command
Setting DSA Port Numbers
When you are running eTrust Directory on Windows, you usually use a port number between 1700 and 64K (65536). When you are running eTrust Directory on a UNIX platform, your system administrator will allocate available port numbers. On most systems, the port numbers also go up to 64K (65536).
Port numbers are used differently from one DSA to another. For example, DXserver listens for connections on ports defined in its knowledge file, but communicates to other DSAs on ports defined in their knowledge files. Some parameters, for example, console-port, are only meaningful to the DXserver. No other servers use these parameters.
For a list of all port numbers used in a default installation, see Port Numbers Used by eTrust Directory in the eTrust Directory Reference Guide.
NSAP, PSAP, and TSAP Port Numbers
You can use the set dsa command to configure NSAP, PSAP, and TSAP ports. However, we recommend that you do not use these options.
These options are available in the set dsa command to ensure interoperability with third-party X.500 server products. They are not required for LDAP.
This is because the X500 standard was built on top of the OSI model, whereas LDAP was layered directly over TCP/IP. TCP/IP effectively maps to the Network and Transport layers, and the concept of ports negates the need for NSAPs and PSAPs.
40 Administrator Guide
Defining DSAs with the set dsa Command
View Communications Settings
To view the listen addresses of the DSA, use the following command in DXconsole:
get stack;
Example: Output from the get stack Command
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
General Administration 41
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 high-level non-maskable events that system administrators need to be aware of. Some triggers of alarms are: A configuration problem For example, a DSA fails to start because it has the same listen address as one already running. A usage problem For example, sending a DAP request to an LDAP port. A system problem For example, running out of memory or disk space.
Unlike trace and log messages, 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.
42 Administrator Guide
Alarms, Traces, and Logs
Traces
Tracing provides debugging information and analyzes service requests.
Tracing does not control what is logged to the summary, query, or stats logs.
In the DSA, the trace command controls the amount of tracing that is sent to the DXconsole and trace-log file (if open).
Tracing Protocol
Low-level protocol can be traced. The protocol trace is written to the trace log, if open. This tracing is only for debugging purposes. To enable protocol tracing, use this command:
set trace = stack;
Tracing Statistics
The stats trace option enables you to retrieve the following minute-by-minute statistical information about a DSA: 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 following three numbers:
The number of current outstanding operations being process locally
The number of current outstanding operations being processed remotely
The number of current outstanding queued multiwrite operations Active Displays the percentage of the time during the last minute that there was activity. Activity covers local operations and chained operations. If Active is 0 it is safe to shut down the DSA. Ops Displays the number of operations processed in the last minute.
General Administration 43
Alarms, Traces, and Logs
Logs
The logs contain the output from a DSA.
For descriptions of log types and instructions for working with logs, see the chapter Error and Diagnostic Logs (see page 563).
For a list of the types of logs, see Log Types in the eTrust Directory Reference Guide.
For descriptions of error messages, see Error Messages in the eTrust Directory Reference Guide.
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. 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.
44 Administrator Guide
Associations
Associations
An association is a connection to a DSA. The number of DSA associations can be managed using the commands in the Assoc module.
The Assoc module includes the following commands:
abort Command
get mib Command
get user Command
get users Command
set allow-binds Command
set allow-native-prefix-reauthentication Command
set auth-trap Command
set credits Command
set disable-client-binds Command
set disable-non-peer-binds Command
set force-encrypt-anon Command
set force-encrypt-auth Command
set hold-ldap-connections Command
set max-bind-time Command
set max-pdu-size Command
set max-users Command
set min-auth Command
set multi-write-retry-time Command
set op-error-trap Command
set op-error-trap Command
set password-age Command
set password-allow-ignore-expired Command
set password-allow-locking Command
set password-alpha Command
set password-alpha-num Command
set password-force-change Command
set password-grace-logins Command
set password-history Command
General Administration 45
Associations
set password-last-use Command
set password-lowercase Command
set password-max-length Command
set password-max-repetition Command
set password-max-substring-repetition Command
set password-max-suspension Command
set password-min-age Command
set password-min-length Command
set password-min-length-repeated-substring Command
set password-non-alpha Command
set password-non-alpha-num Command
set password-numeric Command
set password-policy Command
set password-proxy-user Command
set password-retries Command
set password-suspended-trap Command
set password-uppercase Command
set password-username-substring Command
set relay-non-cache-queries Command
set role-subtree Command
set ssl-auth-bypass-entry-check Command
set transparent-routing Command
set trap-on-update Command
set trust-sasl-proxy Command
set user-idle-time Command
set use-roles Command
46 Administrator Guide
Associations
View Association Configuration
To inspect the current association configuration, use the following command in DXconsole:
get user;
This command shows the current association configuration values of the DSA.
Example: Output from the get user Command
max-users = 255 max-bind-time = 0 user-idle-time = 3600 allow-binds = TRUE min-auth = 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
View Associations
eTrust Directory maintains information about all associations. This includes connection information, connect times, idle times, and so on.
To see a list of currently bound users, use the following command in DXconsole:
get users;
This command shows the current association configuration values of the DSA.
Example: Output from the get users Command
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:
General Administration 47
Associations
Trace 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.
See Viewing Associations (see page 47) for more information.
To control the association tracing
Use the following command:
trace enable assoc = association_number;
Example: To trace a specific association 1. Open a DXconsole session using telnet. 2. Set the tracing to error only:
set trace = error;
3. Determine the association number of the user that requires tracing:
get user;
4. Supply that number to the trace enable command.
To disable the association tracing
Use the following command:
trace disable assoc = association_number;
Stop a DSA
To shut down the DSA with DXconsole
Use the following command:
shutdown;
48 Administrator Guide
Associations
Association Times
User connections can be unconditionally aborted by setting a maximum bind time. Any user bound to the directory for longer than the maximum bind time automatically has their association aborted. To set the maximum bind time, use the command:
set max-bind-time = 3600;
The value is the maximum number of seconds a user can be bound to the DSA (the example shows 3,600 seconds, or one hour). 0 = no limit.
General Administration 49
Associations
Control Binds
Two commands control the bind operation: set allow-binds When set to false, the system rejects all binds. For a full description of the syntax, see set allow-binds Command in the eTrust Directory Reference Guide. set min-auth Sets the minimum authentication level required on a bind. For a full description of the syntax, see set min-auth Command in the eTrust Directory Reference Guide.
For more information about authentication and binds, see the chapter (see page 179)Security.
To allow binds
Use the following commands:
set allow-binds = true; set min-auth = clear-password;
To shut down the DSA gracefully
The administrator can disable new users binding to the DSA and then wait until each association unbinds or times out.
To disable new binds
Use the following 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
To see who is currently bound
Before allowing or disabling binds, you may want to see who is currently bound to the DSA.
Use the following command:
get users;
The command displays the number of users, their connection time, connection address, and user name.
50 Administrator Guide
Associations
Abort Associations
To abort all or some associations
Use the following command:
abort;
Concurrent Associations
You can configure the maximum number of users that can be bound to the DSA.
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.
Example: To set maximum number of users to 100
Use the following command:
set max-users = 100;
Set Maximum Idle Time
To increase availability of the directory, you should set the maximum idle time parameter. The idle time for a user is the time elapsed since the DSA performed the last operation on that user's association. Any connected user idle for longer than the maximum idle time automatically has the association aborted.
To set the maximum idle time
Use the following 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.
General Administration 51
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 (see page 53) for more information. 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.
Process Concurrent Binds from SiteMinder
SiteMinder uses a single thread for authentication. If SiteMinder does not detect a Netscape, iPlanet, or SunOne server, this thread serializes authentication binds to the directory, which slows performance.
To let SiteMinder process authentications asynchronously, the DSA must do both of the following:
Pretend to be a Netscape server to SiteMinder (see set mimic-netscape- for-siteminder Command in the eTrust Directory Reference Guide)
Process concurrent binds (see set concurrent-bind-user Command in the eTrust Directory Reference Guide)
52 Administrator Guide
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.
View Operation Configuration
To view the current operation configuration values of the DSA, use the following command in DXconsole:
get oper;
Example: Output from the get oper 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 unique-attrs = attr1, attr2 ignore-name-bindings = FALSE
General Administration 53
Local Operations
Viewing Operation Statistics
List Operation Statistics
eTrust Directory maintains statistics about all operations, including events, services, errors, timeouts. The following command returns a list of operation statistics:
get stats;
Here is an example of the output of a get stats command:
anonymous binds = 43 in ops = 789 read ops = 350 add entry ops = 1 modify entry ops = 3 modify-dn ops = 1 list ops = 371 search ops = 6 whole tree search ops = 6 errors = 2 name errors = 1 found local entries = 187 no such object = 1
DSA statistics can be read using SNMP or CMIP. The Management Information Base (MIB) being read defines the names displayed from those actions. For example, noSuchObject displays as “no such object.”
Reset Counters
The statistics are stored in counters. To reset these counters, use this command:
reset stats;
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;
54 Administrator Guide
Local Operations
Administration Limits
To restrict the maximum time (in seconds) that the list and search services can run and the maximum number of entries these operations can return, use the following commands
set max-op-time = 20; set max-op-size = 100;
If an operation exceeds either of these limits, the following error is returned:
Administration limit exceeded
Operational Attributes
To control the automatic creation and updating of operational attributes (for example, last modified time) on entries in the DSA, use the following command:
set op-attrs = true;
If it is set to true, the DSA will automatically control the creation and updating of operational attributes.
The op-attrs parameter should normally be set on each DSA.
Note: If the multi-write-disp-recovery flag is set, the op-attrs parameter must be true.
If the op-attrs parameter is set to false, then:
The DSA will not create or update operational attributes
All no-user-modification schema settings will be overridden. This means that an administrator will be able to update any operational attributes manually.
Access Controls
To control the level of security available on the DSA, use this command:
set access-controls = true;
When access controls are enabled and no rules are defined, no entries are visible and the directory cannot be viewed or updated. However, it is still possible to load the directory using the bulk load tools. For more information about access controls, see Access Control Overview (see page 220).
General Administration 55
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
This guarantees update security and over-ride any access controls. It is very useful for public DSAs. In conjunction with a public DSA, an administrator can start up a local DSA that connects to the same database to perform updates.
Abandoning Operations
To abandon any outstanding operations, use the abandon command, which must identify the association and operations that are to be abandoned:
abandon { all | operation operation-number } on association assoc-number;
To find out the current association numbers, use the following command:
get users;
The result returned by an abandoned operation depends on how far the operation progressed before being abandoned. The display shows either partial results (with the partial outcome qualifier set to the appropriate problem), or the following error message:
Service error: administration limit exceeded
An update operation cannot be abandoned.
If a service exceeds global limits, the requests are not abandoned. Instead, they return an error or partial result. A DSA can truncate processing an operation when it exceeds the global configuration values. For example, you can use the following commands to limit the time (in seconds) and size (number of entries returned) of operations:
set max-op-time = 60; set max-op-size = 100;
For a full description of the abandon command and the other commands listed here, see the chapter eTrust Directory Commands in the eTrust Directory Reference Guide.
56 Administrator Guide
The Directory Information Base
The Directory Information Base
To manage the DIB, use the commands:
set parameter = value;
get parameter;
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, ...... };
View DIB Configuration
To view the DIB configuration variables and their values, use the following command in DXconsole:
get dib;
Example: Output from the get dib Command
alias-integrity = TRUE database-name = demo database-user = fred database-password = ***** eis-count-attr = dxEntryCount password-storage = sha-1
General Administration 57
The Directory Information Base
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, the following command sets the DSA to use the Ingres database named demo:
set database-name = demo;
In certain situations, because of the access controls required to access 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 Ingres when accessing the database. If this situation arises, use the alternate form of the database configuration command:
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.
For information about restrictions on database names, see the Readme.
For more information about databases, see Databases (see page 35).
58 Administrator Guide
The Directory Information Base
Manage Connections to the Database
eTrust Directory manages problems with the DSA connection to the database in two ways:
If a DSA cannot connect to a database, it raises an alarm and shuts down.
You can set each DSA to shut down when a database error occurs
DSA Shuts Down If Database Connection Lost
If a DSA cannot connect to a database, it raises an alarm and shuts down. For a description of the alarms, see Error Messages in the eTrust Directory Reference Guide.
If a DSA shuts down due to an Ingres error, you should check the Ingres logs to find out what the problem was. For more information about Ingres logs, see Ingres Log Messages in the eTrust Directory Reference Guide.
Shut Down DSA If a Database Error Occurs
You can set each DSA to shut down if the database produces an error. By default, this option is off.
To set a DSA to shut down if the database produces an error, use the following command:
set shutdown-on-sql-error = true;
General Administration 59
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;
For more information, see Aliases in the chapter The DUA Command Set in the eTrust Directory Reference Guide.
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 aliases that point to no object entry.
60 Administrator Guide
The Directory Information Base
Counting Entries
If you want to count the number of entries in a directory, you can do one of the following:
Search for all of the entries in the directory, and then count the number of entries returned. This is not feasible in an automated system or in a system where the search returns large numbers of entries.
Use the eis-count-attr parameter to find out how many entries in the directory satisfy a search This is much more efficient.
Use the eis-count-attr Parameter to Count Entries
To search for the number of entries that satisfy a search filter 1. Set the eis-count-attr parameter to an unused attribute. We recommend that you use the attribute dxEntryCount in the database settings file DXHOME/config/database/default.dxc:
set eis-count-attr = dxEntryCount;
2. Create a search request that includes a filter that will return all of the entries you want to count, and specifies the attribute you chose in the previous step as the only attribute to return. 3. Run the search request.
General Administration 61
The Directory Information Base
Example: Counting Entries in Democorp with Surname Starting with C
This is a subtree search, which means that the filter is applied to the base object and all entries in the tree below the base object.
To count how many entries in the Democorp DSA have a surname starting with the letter C 1. Add the following line to DXHOME/config/database/default.dxc:
set eis-count-attr = dxEntryCount;
2. Run the following search:
dxsearch -h computer-name -p 19389 -s subtree -b "o=DEMOCORP,c=AU" (sn="C*") dxEntryCount
where computer-name is the computer that contains the Democorp DSA. This search returns a single entry with a dxEntryCount attribute, which is set to the number of entries that satisfy the search filter. 3. Check the result for the number of entries:
o=DEMOCORP,c=AU dxEntryCount=98
This search result indicates that there are 98 entries with a surname beginning with C in the Democorp DSA.
Example: Counting All Entries in Democorp
This is also a subtree search, which means that the filter is applied to the base object and all entries in the tree below the base object.
To count all of the entries in the Democorp DSA 1. Make sure that the file DXHOME/config/database/default.dxc includes the following line:
set eis-count-attr = dxEntryCount;
2. Run the following search:
dxsearch -h computer-name -p 19389 -s subtree -b "o=DEMOCORP,c=AU" (objectclass="*") dxEntryCount
where computer-name is the computer that contains the Democorp DSA. 3. Check the result for the number of entries:
o=DEMOCORP,c=AU dxEntryCount=1380
This search result indicates that there are 1380 entries in the Democorp DSA.
62 Administrator Guide
The Directory Information Base
Example: Counting Entries at a Single Level in the Democorp DSA
This is a one-level search, which means that the filter is applied to the entries immediately below the base object, but not to the base object itself.
To count how many top-level department names in the Democorp DSA include the letter C 1. Make sure that the file DXHOME/config/database/default.dxc includes the following line:
set eis-count-attr = dxEntryCount;
2. Run the following search:
dxsearch -h computer-name -p 19389 -s one -b "o=DEMOCORP,c=AU" (ou="*c*") dxEntryCount
where computer-name is the computer that contains the Democorp DSA. 3. Check the result for the number of entries:
o=DEMOCORP,c=AU dxEntryCount=6
This search result indicates that 6 of the top-level department names contain the letter "c".
General Administration 63
The Directory Information Base
Example: Counting Entries in a Distributed DIT
The sample DSAs (Router, Democorp, and UNSPSC) comprise a distributed DIT. If you apply a search filter to the base object c=AU, the filter is then applied to each of the two subordinate DSAs Democorp and UNSPSC.
To count the entries in the whole DIT controlled by the Router DSA 1. Make sure that the file DXHOME/config/database/default.dxc includes the following line:
set eis-count-attr = dxEntryCount;
2. Run the following search:
dxsearch -h computer-name -p 19289 -s subtree -b "c=AU" (objectclass="*") dxEntryCount
where computer-name is the computer that contains the Router DSA. 3. Check the result for the number of entries:
o=DEMOCORP,c=AU dxEntryCount=1380
o=UNSPSC,c=AU
dxEntryCount=10160
This search result indicates that The Democorp DSA contains 1380 entries, and the UNSPSC DSA contains 10,160 entries.
64 Administrator Guide
The Directory Information Base
Rejecting All list Commands
There can be instances where a DIT has a very flat structure and there are many thousands of entries under one node. In this case, the list operation is not useful.
The DSA can be set to reject all list requests by setting the limit-list DSA flag in the knowledge directory, using the set dsa command:
dsa-flags = limit-list
For information about using the limit-list flag to set up query streaming, see Query Streaming (see page 175).
Rejecting All Unfiltered Searches
There may be instances where a DSA is set up to handle large numbers of simple lookup searches, and a high throughput is very important. Large complex searches can put unwanted pressure on the performance of the DSA.
It is possible to limit the types of searches processed by setting the limit- search DSA flag in the knowledge directory, using the set dsa command:
dsa-flags = limit-search
This flag causes searches with no filter or with a filter containing an attribute present, substrings any, or a range of values (>=, <=) to be rejected. Only simple (or exact) searches are accepted.
For example, if you want to search for all people with a surname of Smith and enter sn=smith, your request is processed; however, if you search for all surnames that sound like Smith, and enter sn~=smith, your request is rejected.
For information about using the limit-search flag to set up query streaming, see (see page 175)Query Streaming.
For more information about phonetic match searching, see the eTrust Directory User Guide.
Password Storage
To check a password, an application requests a compare operation. The DSA then hashes (encrypts) the candidate password, and compares it with the value saved in the directory.
General Administration 65
The Directory Information Base
Indexing Options
Indexing helps with the search process.
Indexing options can appear anywhere in the database configuration after the schema definitions. If they appear after the database definition, then warning messages for items already indexed in the database will be produced. This database configuration file must come after the schema configuration file in the server initialization file.
You can use the tool DXindexdb to set up the index. For more information, see DXindexdb Tool in the eTrust Directory Reference Guide.
Important! If you have indexed the database with DXtools (for example, DXindexdb), ensure that the attributes indexed here match those in the database.
Indexing Commands
Use the following commands to set up indexing for a DSA:
set not-searchable = attribute-list set index-wide = attribute-list set index-reverse = attribute-list
One set index-xxxx command initializes all indexes of that type. This means that if you specify two commands for the same special index, only the attributes of the second command will be indexed.
Use the following commands to add more attributes to an existing special index: add index-wide = attribute-list add not-searchable = attribute-list
Use the following command to clear all indexes: clear indexes
For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide.
66 Administrator Guide
Cache DSAs
Cache DSAs
eTrust Directory includes DXcache, which uses in-memory techniques to make lookups on indexed attributes even faster.
This lets you create DSAs in which some or all attributes are preloaded into memory. When a search request involving one of these preloaded attributes is sent to the directory, the request is directed to the cache, instead of to the data stored on the disk.
To see a list of all commands related to enabling and configuring a cache DSA, see Index of DXserver Commands by Module in the eTrust Directory Reference Guide.
You can also set up cache-only DSAs. Cache-only DSAs are entirely memory- resident, and are particularly useful for web applications. For information, see Cache-Only DSAs (see page 80).
General Administration 67
Cache DSAs
How Cache DSAs Work
When a DSA starts up, it looks in the DXI configuration file to work out which attributes should be indexed or cached. It caches and indexes those attributes.
The time that a DSA takes to start up depends on the number and size of the attributes that are to be loaded into the cache.
How Cache DSAs Handle Search Requests
When a search request is sent to the directory, it might be directed to the cache, or it might go to the database.
The decision is based on what attributes have been requested to be returned to the client and what attributes appear in the filter. If all these attributes have been cached, by appearing in the cache-index, cache-reverse or cache- attrs commands, the search will be processed in the cache.
How Cache DSAs Handle Update Requests
When a cache DSA receives an update, it applies the update first to the database and then to the cache.
All updates successfully applied to the database are applied to the cache. Therefore, if no other DSA is updating the database, the cache will remain synchronized.
If the database is updated by other DSAs, you should configure the DSAs to keep their caches synchronized. To achieve this, set the following:
All DSAs that update the database must belong to a multiwrite group. For more information about multiwrite groups, see How Multiwrite Groups Work (see page 253).
All cache DSAs must have the DSA flag multi-write-notify set in their knowledge file.
The effect of this is that multiwrite updates are sent to the cache but they will update only the cache contents - they are not reapplied to the database. Thus, the cache remains synchronized with the database.
68 Administrator Guide
Cache DSAs
Design a Cache DSA System
If you plan to use a cache DSA, you need to decide which attributes your users are likely to search on, and which attributes they are likely to want to return. Then, set up the following:
Index the attributes that users are likely to enter in the search filter.
Cache the attributes that users are likely to request.
Note: The indexed attributes are also automatically cached.
You can load all attributes into the cache, to make all searches faster. This makes the cache much larger than if you only load some attributes.
Cache DSAs with Base-Object Searches
eTrust Directory also supports base-object searches in cache DSAs, in which the search is restricted to the base object.
For base-object searches, the filter is not required, but all the other caching conditions must be met. This means that the attributes to be returned must be loaded in the cache.
Cache DSAs with Multiwrite–DISP Recovery
The cache is only effective if it does not need to be reloaded frequently.
The cache must be reloaded each time a DISP update is received. For example, the cache would have to be reloaded when the multiwrite queues have overflowed with multiwrite–DISP updates or when you are running basic DISP replication.
The cache is reloaded automatically, but this may affect the usefulness of using a cache DSA in an environment where frequent DISP updates can be expected.
General Administration 69
Cache DSAs
Example: Using a Cache DSA to Speed Up Lookups of Customer Details
You are setting up a directory of customer details for the call center of a phone company.
The call center staff usually look up customer details using the customer's account number, and they usually want to see the customer's name and account balance.
To speed up these lookups, you should cache and index as follows:
Account number: index
Customer name: cache
Account balance: cache
Because the account number is indexed, it is also automatically cached.
70 Administrator Guide
Cache DSAs
Create a Cache DSA
The following sections describe how to enable a cache DSA using commands in the DXI file.
For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide.
Enable Caching
To enable caching for a DSA, add the following command to the DXI initialization file:
set lookup-cache = true;
Make sure that the set cache-lookup command appears after the cache and database definitions in the initialization file. The DSA loads the cache as soon as it reads the set lookup-cache command. For an example initialization file, see Example: democorp.dxi with Cache Commands (see page 79).
To configure a cache DSA, you need to add further commands to the initialization file. These commands must also precede the set lookup-cache command. These commands are described in the following sections.
Cache the Searched Attributes
To cache and index some or all attributes, add the following command to the DXI initialization file:
set cache-index = attribute-list | all-attributes;
Use this command to cache and index attributes that will appear in search filters.
Any entry that contains one or more of the attributes listed in this command is held in the cache. The attributes in listed here do not have to appear in a set cache-attrs command.
Entries that contain none of the attributes in this list are not loaded into the cache. Therefore, your choice of indexed attributes directly affects the number of entries in the cache.
Make sure that none of the attributes listed here are also marked not- searchable. If this is the case, the cache will not load properly.
General Administration 71
Cache DSAs
Cache the Returned Attributes
To cache some or all attributes, add the following command to the DXI initialization file:
set cache-attrs = attribute-list | all-attributes};
Use this command to cache the attributes that will be returned by the search request.
If an attribute is included in a set cache-index command, you do not need to include it in a set cache-attrs command. The indexed attributes are already cached so you only need to use this command to specify any additional attributes.
Search requests that do not specifically request particular attributes to be returned are actually implicitly requesting the return of all attributes. To cater for this type of request, you can cache all attributes:
set cache-attrs = all-attributes;
If you cache all attributes, the cache DSA will require more memory than if you cached only some attributes.
Set the Maximum Cache Size
The cache will not work unless you have set the maximum cache size. To set the maximum cache size, add the following command to the DXI initialization file:
set max-cache-size = size;
The cache uses the minimum amount of memory required to store the indexes and results. If the cache requires more memory than defined with the max- cache-size setting, an alarm is raised and the cache is disabled.
Make sure that you set the maximum cache size to less than the RAM available. Leave at least 250 MB RAM free for the operating system, and allow additional RAM for other programs on the same computer. You should usually set the maximum cache size to 50-70% of the memory available.
One million entries, including their attributes, occupy about 2 GB of memory. On 32-bit Windows operating systems, eTrust Directory and other applications each have a virtual address space limitation of 2 GB, regardless of the amount of memory in the system. UNIX-like operating systems have a limit of 4 GB.
72 Administrator Guide
Cache DSAs
View the Cache Configuration
To view the cache configuration variables and their values, add the following command to the DXI initialization file:
get cache;
This command displays whether the cache is enabled and provides some statistical information about the cache configuration.
Example: Output from the get cache Command
Cache enabled cache-max-size = 4000000 cache-max-index-size = 1377 cache-attrs = all-attributes cache-index = cosineRfc822Mailbox telephoneNumber title surname commonName organizationalUnitName organizationName cache-reverse =
All entries loaded Number of Entries 1377 Memory used by cache: 3063208 out of 3529916 (Memory initially used by data only: 2312572) Memory leaked 0
Number of Cache Hits 0 Number of Cache Misses 1 Number of Sequential Scans 0 Free lists: EntryLists: 0 Constrained values: 0 Unconstrained values: 0 IndexList: 0
General Administration 73
Cache DSAs
Configure a Cache DSA
The following sections describe the options for configuring the way that a cache DSA works.
The cache settings are kept in the DSA initialization file.
For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide.
Reverse-Index Cached Attributes
If the users use searches of the form (telephonenumber=*1234), you may index some attributes so they index the values after reversing the order of the bytes.
To reverse-index a cached attribute, add the following command to the DXI initialization file:
set cache-reverse = attribute-list;
For example, 123-4567 will be indexed as if it were 7654-321.
Send all Searches to the Cache
To set the cache to process all search requests, add the following commands to the DXI initialization file:
set cache-load-all = true; set cache-attrs = all-attributes;
The set cache-load-all command ensures that all entries are loaded into the cache. The set cache-attrs = all-attributes command ensures that all attributes in each entry are loaded.
Each of these options increases the amount of memory used by the cache, so make sure that you only use them if required. You still need to index attributes used in search filters.
If a search filter contains NOTs, the search can only be processed if all entries are in the cache.
74 Administrator Guide
Cache DSAs
Load Only Some Entries
You can set a DSA to load some, but not all, entries into the cache. The DSA and the cache then work as usual. The cache will ignore the entries that are not loaded in the cache, which will affect the results of some searches.
To set the cache to load only some entries, add the following command to the DXI initialization file:
set cache-load-filter = none | attribute-name = attribute-value [ or attribute- value2 ...];
This can be useful if you want to cache only some entries, but you prefer not to partition the DIT.
Increase the Maximum Number of Entries in a Cache DSA
To increase the number of entries in a cache DSA, add the following command to the DXI initialization file:
set max-cache-index-size = number-entries;
This command sets the maximum number of entries (or distinct attribute values for each attribute type) that a cache DSA can index.
If you leave this setting at its default value, the cache DSA can contain up to about 8 million entries, or about 8 million distinct attribute values. For example, if each entry had two unique telephone numbers then by default the cache could hold only 4 million entries. Attributes that are not indexed are not affected.
You should only use this command if you are sure you need more than 8 million entries or distinct attribute values. If you set this value too high, the DSA will have high memory requirements, and its performance may degrade.
Reject or Forward Long Queries
To set a cache DSA to not process long queries, add the following command to the DXI initialization file:
set relay-non-cache-queries = true | false;
If the cache DSA has a peer DSA, the long request will be forwarded to it, otherwise the error admin-limit-exceeded will be returned to the client.
This is useful if it is important that the cache DSA does not spend a long time processing any individual search request.
General Administration 75
Cache DSAs
Monitor a Cache DSA
To check that a cache DSA is working correctly, trace the SQL requests. Use the following command in DXconsole:
trace sql;
If you see any SQL requests, that means that some requests are bypassing the cache and being sent to the database. This would indicate a problem with the cache DSA.
Summary of Cache Commands
To set up and configure a cache DSA, you need to add commands to the DXI initialization file. You could also set up a cache.dxc file in a cache directory and source it to form the DXI file.
The following list describes the settings that you use to set up cache DSAs: set cache-attrs Defines the attributes that are to be cached but not indexed. Use this for the attributes that are commonly returned in search results. There is no need to specify indexed attributes here, because they are loaded automatically. For more information, see Cache the Returned Attributes (see page 72). set cache-index Defines which attributes will be indexed. Use this for the attributes that are commonly used in search requests. These attributes will be loaded automatically so there is no need to specify them with the set cache-attrs command. For more information, see Cache the Searched Attributes (see page 71). set lookup-cache Enables or disables caching for this DSA. set max-cache-size Sets the maximum amount of memory (in MB) that the cache is permitted to use. For more information, see Set the Maximum Cache Size (see page 72).
76 Administrator Guide
Cache DSAs
The following list describes the options that you use to configure cache DSAs: set cache-load-all Forces the cache DSA to load all entries in the database into the cache. A cache DSA can only handle searches where the filter does not reference an indexed attribute if it knows that all the entries have been loaded into the cache. For more information, see Send all Searches to the Cache (see page 74). set cache-load-filter Sets the cache DSA to load some, but not all, entries. The cache DSA then works as if these entries did not exist. For more information, see Load Only Some Entries (see page 75). set cache-only Enables cache-only mode. In this mode, a DSA uses the cache as its repository, which means that all data is kept in memory. For information, see Cache-Only DSAs (see page 80). set cache-reverse Sets the cache to reverse-index the attributes. set max-cache-index-size Sets the maximum number of entries (or distinct attribute values for each attribute type) that a cache DSA can contain For more information, see Increase the Number of Entries in a Cache DSA (see page 75). set relay-non-cache-queries Prevents a cache DSA from performing long queries.
General Administration 77
Cache DSAs
Sample Cache DSA Configurations
The following examples show how to configure cache DSAs for various possible scenarios.
To learn more about how these settings work, try applying them to the Democorp DSA. To do this, add the cache commands to the end of democorp.dxi.
Example: Cache Some Attributes
The following commands index the attributes cn and sn and cache the attributes telephoneNumber and postalCode.
This would be useful if search filters often search using cn and sn and often request values for telephoneNumber and postalCode.
There is no need to list cn and sn in the set cache-attrs command, because they are listed in the set cache-index command.
set cache-index = cn, sn; set cache-attrs = telephoneNumber, postalCode; set max-cache-size = 1500; set lookup-cache = true;
Example: Cache and Index All Attributes
The following commands cache and index all attributes.
This would be useful if you had no way of predicting what searches you’d be handling, but you wanted all to proceed as quickly as possible.
set cache-index = all-attributes; set max-cache-size = 1500; set lookup-cache = true;
78 Administrator Guide
Cache DSAs
Example: democorp.dxi with Cache Commands
The following DXI file shows democorp.dxi plus commands to cache all attributes.
close summary-log; close trace-log; source "../logging/default.dxc";
clear schema; source "../schema/default.dxg";
clear dsas; source "../knowledge/sample.dxg"; source "../settings/default.dxc"; source "../limits/default.dxc"; source "../database/democorp.dxc"; source "../database/default.dxc";
clear access; source "../access/default.dxc";
set multi-write-disp-recovery = false;
set cache-index = all-attributes; set max-cache-size = 1500; set lookup-cache = true;
General Administration 79
Cache-Only DSAs
Cache-Only DSAs
You can run eTrust Directory in cache-only (memory-resident) mode.
In this mode, eTrust Directory uses a cache DSA as its repository, rather than a database.
Why Cache-Only DSAs are Useful
Traditional directories were designed with the following assumptions:
Persistent data storage
More queries than updates
However, with the advent of web applications and web services, there is a growing need for a directory service with the following characteristics:
Transient data storage
As many updates as queries
80 Administrator Guide
Cache-Only DSAs
How Cache-Only DSAs Work
A cache-only DSA reads and writes data extremely quickly. It can service thousands of updates per second, rather than the tens or hundreds of updates per second for traditional directories.
This update speed is achieved because the data in the repository is never written to disk.
There is no write-behind strategy of any kind. A cache-only DSA does not even require Ingres or any other database to be running.
If a cache-only DSA is shut down or is stopped by a software or hardware problem, all data is lost and cannot be recovered. Thus, it is ideally suited for storing short-lived data that needs to be updated frequently.
None of the database DXtools can be used with a cache-only DXserver. You must use the DXmodify or ldapmodify tools to load the cache and the DXsearch or ldapsearch tools to dump its contents.
Cache-Only Replication
In a high-availability directory implementation with cache-only DSAs, a configuration will normally consist of a router forwarding requests to a group of replicating cache-only DSAs.
Real-time replication is performed using multiwrite, and recovery is performed using multiwrite-DISP.
Important! You cannot mix cache-only and non-cache-only DSAs in a replication set. They have different DISP recovery requirements.
For example, a re-started cache-only DSA has no data, so a DISP update must be a total refresh of the data, not just an incremental update.
The set cache-only Command
The set cache-only command is equivalent to the following cache parameters and also enables extra cache-only functionality:
set cache-attrs = all-attributes; set cache-load-all = true; set lookup-cache = true;
General Administration 81
Cache-Only DSAs
Example: Store Web Session Objects in a Cache-Only DSA
For example, you could use a cache-only DSA to store web session objects. Web session objects are only required for a short time and may be updated repeatedly. They have no long-term value. At peak times, thousands of web session objects might be in use.
The applications that use these objects still need to be scalable and highly available, which means that a directory is ideal for storing the web session object. However, storing such objects in a traditional directory is prohibitively expensive because of the cost of large updates which must eventually be written to disk.
If you use a cache-only DSA instead, you could avoid these problems.
To do this, you could use a cache-only DSA to manage only the web session objects, and use a traditional DSA to manage persistent data.
82 Administrator Guide
Cache-Only DSAs
Work with Cache-Only DSAs
This section describes how to work with cache-only DSAs.
Create a Cache-Only DSA
To create a cache-only DSA
Add the following to the DSA configuration (at the bottom of the dsa- name.dxi file):
set max-cache-size = size; set cache-only = true;
Add a Cache-Only DSA to a Cache-Only Replication Set
To add a cache-only DSA to a cache-only replication set 1. Add the following to the DSA knowledge configuration:
dsa-flags = multi-write
2. Add the following to your server configuration:
set multi-write-disp-recovery = true;
Note: Synchronization is only guaranteed if multiwrite-DISP recovery is completed. If a DSA recovering another cache-only peer crashes before replaying its multiwrite queues, the peer DSA will be out of sync.
Using Other Commands with a Cache-Only DSA
The following cache configuration parameters are compatible with a cache-only DSA:
set cache-index = attribute-list | all-attributes; set cache-reverse = attribute-list;
The following commands are incompatible with a cache-only DSA, and it will fail to start if they are set:
set database-name = database_name; set dbconnection = dbconnection; set multi-write-disp-queue = true; set cache-attrs = all-attributes; set cache-load-all = true; set cached-only-attrs = attribute-list; set lookup-cache = true;
General Administration 83
Virtual Attributes
Virtual Attributes
This section describes two different kinds of virtual attributes: Dynamic groups These can reduce the time you spend updating the membership of groups. Class of Service templates These can reduce the size of the directory, reduce the time you spend doing bulk updates, and help keep information consistent.
Dynamic Groups
eTrust Directory supports static, dynamic, and hybrid groups.
Static groups are useful for directories when the members of groups do not change often.
Dynamic groups are useful when you know that you will often need to change the membership of a group, because there is no overhead involved in maintaining the group data.
Hybrid groups let you use the features of both static and dynamic groups.
How Static Groups Work
Users and other entries can be grouped in the directory using a static group entry. A static group entry contains a list of member DNs. The static group entry usually has an object class of “groupOfNames” and an attribute “member” that has one value for each of the members in the group.
If a user is removed from the directory, then the user must also be removed from any static groups that they belonged to. This must be done manually by removing the user's member DN from each group that the user was a member of.
How Dynamic Groups Work
A dynamic group does not store each member DN in its directory entry. Instead, it stores an LDAP search request that is executed when a base-object search is performed on the dynamic group entry. This LDAP search finds all the members that satisfy the search filter and return the DNs of those members.
If a user is removed from the directory, then their user entry will not be found by the LDAP search, so the user will have been automatically removed from the dynamic group.
84 Administrator Guide
Virtual Attributes
How Hybrid Groups Work
It is possible to create a hybrid group. This is a group entry that contains both an LDAP search attribute and a list of one or member DNs.
To create a hybrid group, make sure that the “member-attr” in the dynamic group definition is the same as the attribute used to store the static members. This means that the static and dynamic members will be combined when a base-object search is performed on the entry.
Enabling Dynamic Groups
To turn on dynamic groups, add the following to the DSA configuration file.
clear dynamic-group; set dynamic-group GROUP = { object class = groupOfURLs url-attr = memberURL member-attr = member };
You can also use other object classes and attributes than those shown here. However, the url-attr must have a string syntax and must be a MUST or MAY container attribute of the object class. The member-attr must have a distinguishedName syntax, because it is used to return the DNs of the members.
General Administration 85
Virtual Attributes
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??scope?filter
base-dn The base DN for the search. This is the DN from which the search filter is applied. scope (Optional) The scope of the search. 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
filter (Optional) 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))
86 Administrator Guide
Virtual Attributes
View Dynamic Groups
To view the dynamic group configuration in use in a DSA, use the following command in DXconsole:
get dynamic-groups;
This produces a list of dynamic groups in use.
Example: Output from the get dynamic-groups Command
************** GROUP ************** Group object class : groupOfURLs Group Search URL : memberURL Member to Append : member
General Administration 87
Virtual Attributes
Class of Service Templates
When directory information needs to be shared across multiple entries, the shared information can be stored in a Class of Service (CoS) template.
Then, when a search returns an entry that contains a Class of Service attribute, the attributes and values from the associated template are included in the entry.
This means that the information in CoS templates is only stored once, which is good for three reasons:
Directory size is reduced
Simple bulk updates are faster
Information is consistent
The shared information is usually a level of service, such as a standard or premium subscription to an internet service provider.
How Class of Service Templates Work
The virtual attributes and values are stored in templates, which are kept in a DXserver configuration file.
When a search returns an entry that contains the CoS attribute, the attributes and values from the associated template are presented.
A template can have multiple attributes and values. All attributes in a template will be added to the entry.
If an entry already has an value for an attribute in a template, the attribute in the template can either over-write the value, or the value can be left untouched. This is controlled by the disposition of the template attribute. The two possible dispositions are:
default-The value from the template replaces the existing value
override-If the entry already contains this attribute, the existing value will persist. Use this when a customer requires special treatment.
The attributes that are stored in CoS templates are not searchable.
88 Administrator Guide
Virtual Attributes
Example: The Excellent ISP Company
The company Excellent ISP is an internet service provider. The customers of Excellent ISP can subscribe for one of two classes of service:
Standard Premium
Mail Storage 20 MB 30 MB
Web Space 20 MB 30 MB
Hours per Month 15 hr Unlimited
Cost per Month $19.95 $29.95
Cost of Extra Hours $1.00/hr $0.00/hr
The Excellent ISP customer directory includes the subscription information in each customer entry.
General Administration 89
Virtual Attributes
Entries Without Class of Service Virtual Attributes
Before CoS is introduced, this information is stored in each entry. If there are one million users, then these attributes appear one million times. If Excellent ISP increases its fees, then a large global update is required.
Here is an example entry for an Excellent ISP customer who has the standard class of service:
dn: cn=John Smith, o=Excellent ISP, c=US oc: inetOrgPerson oc: excellentISPuser cn: John Smith sn: Smith excellentISPmailQuotaMB: 20 excellentISPwebSpaceMB: 20 excellentISPaccessHours: 15 excellentISPprice: 19.95 excellentISPextraHoursPrice: 1.00 excellentISPpackage: Standard
Here is an example entry for an Excellent ISP customer who has the premium class of service:
dn: cn=Mary Chen, o=Excellent ISP, c=US oc: inetOrgPerson oc: excellentISPuser cn: Mary Chen sn: Chen excellentISPmailQuotaMB: 30 excellentISPwebSpaceMB: 30 excellentISPaccessHours: Unlimited excellentISPprice: 29.95 excellentISPextraHoursPrice: 0 excellentISPpackage: Premium
90 Administrator Guide
Virtual Attributes
Entries With Class of Service Virtual Attributes
To save space and time, the shared information in these entries can be moved into a template. The shared information in the entries is then replaced with a new attribute, whose value indicates which CoS template to use.
The attributes from the CoS template will be added to the entry on a search.
dn: cn=John Smith, o=Excellent ISP, c=US oc: inetOrgPerson 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
General Administration 91
Virtual Attributes
Class of Service Templates
The Excellent ISP company would need to use two templates. The standard- 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)
} };
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
92 Administrator Guide
Virtual Attributes
value = "29.95" disposition = default),
(type = excellentISPextraHoursPrice value = "0.00" disposition = default) } };
Configuring Class of Service Virtual Attributes
When the shared attribute values change, they can be updated in the configuration files. Therefore, make sure that configuration files are stored in a source code control system to permit rollbacks.
Distribution of CoS entries is achievable, but requires the DSA configuration to be manually copied to all nodes.
Configure the DSA
Add the following line to the local DSA configuration to clear any currently cached CoS information.
clear class-of-service;
This allows CoS attribute modifications to be made which can be included while the DSA is still running using the command dxserver init.
Make sure that the template configuration file is sourced after the schema is sourced. The template uses attributes that are defined in the schema configuration.
Add CoS Attributes to Entries
To use CoS templates with an entry, add the cos-attr attribute to the entry.
General Administration 93
Virtual Attributes
Create Class of Service Templates
Templates can be stored in any directory. However, if there are many templates, you should store them in separate files in the DXHOME/config/settings directory.
The Class of Service templates use the following syntax:
Note: The cos-attr used in a Class of Service template must be a single- valued attribute.
94 Administrator Guide
Virtual Attributes
View Class of Service Templates
To view templates in use in a DSA, use the following command in DXconsole:
get class-of-service;
This produces a listing of each class of service template in use, with the template label at the top.
Example: Output from the get class-of-service Command
The template for the standard class of service at Excellent ISP 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
General Administration 95
Virtual Directory
Virtual Directory
A virtual directory is a combination of two other directories: a reference and an overlay. A virtual directory includes the entries and attributes in the reference directory, plus any new or changed attributes or entries in the overlay directory.
An overlay directory is an eTrust Directory DSA that is used to add attributes and entries to a third-party DSA that is read-only or have its schema extended. This is useful when you have data in an existing directory such as Microsoft Active Directory.
The overlay directory stores only the new and changed attributes. This overlay provides a virtual view of all the information from the reference directory, overlaid with new information from the overlay directory.
When a client accesses the DSA, it sees the virtual directory, which includes the sum of the entries and attributes in the reference and overlay directories. From the client's point of view, there is only one directory.
96 Administrator Guide
Virtual Directory
The Structure of a Virtual Directory
The reference directory defines the structure of the virtual directory. Almost every entry in the overlay DSA has a matching entry in the reference directory.
An overlay directory can only overlay a reference directory that has the same prefix.
The overlay DSA uses the reference DSA's schema to differentiate between internal and external attributes.
The overlay DSA stores OIDs from the reference DSA in a cache of external attributes. An attribute will be considered external if its OID is in the cache of external attributes. If its OID is not in the cache, it will be assumed to be internal.
How an Overlay DSA Starts
The following steps describe what happens when an overlay directory is started: 1. The overlay DSA starts. 2. The overlay DSA connects to the reference DSA, using the configured ldap-dsa-name and ldap-dsa-password credentials from the knowledge. If the reference cannot be contacted, the overlay logs an alarm and stops. 3. The overlay DSA reads the reference DSA's published schema to determine which attributes and object classes are stored in the reference DSA. If the schema cannot be read, the overlay logs an alarm and stops. 4. The overlay DSA loads the attributes and object classes. If the overlay DSA does not load any external attributes and object classes, the overlay directory stops. When the overlay DSA has loaded the cache of external attributes, the virtual DSA is ready to service requests.
General Administration 97
Virtual Directory
Configuration for Overlay and Reference Directories
When the knowledge of a DSA contains the DSA flag overlay, this DSA behaves as an overlay DSA. The sole purpose of the directory is to overlay a reference store and it will therefore not support many distributed features. Services including chaining, multi-chaining, and load-sharing will be restricted.
When the knowledge of a DSA contains the DSA flag overlay-reference, this DSA will be treated as a reference directory. This directory will be ignored by DSAs that are not marked overlay. The reference directory can also be marked read only using the DSA flag read-only.
If a DSA has knowledge of an overlay reference but is not itself an overlay, then the link will be marked unavailable so that the reference will not be chained to. This supports the good practice of have symmetric configuration.
Example: Configuration for a Reference Directory
The following is an example knowledge file for a Microsoft Active Directory DSA that you plan to use as a reference directory:
set dsa MS-AD = { prefix =
98 Administrator Guide
Virtual Directory
Example: Configuration for an Overlay Directory
The following is an example knowledge file for a DSA that you plan to use as an overlay directory:
set dsa OVERLAY = { prefix =
Example: Overlay DSA Publishes Reference DSA Schema
The overlay and router DSAs are to source additional schema of object classes and attributes to be stored in the overlay DSA.
It may be useful to have the overlay DSA run with and publish the overlay reference schema. Especially if there is the potential for conflicts between the overlay schema and the overlay reference schema.
A possible overlay.dxg to be source by the overlay and router (if this exists) would be:
source "ms-ad.dxc"; source "dxserver.dxc"; source "eTAdmin.dxc";
The file ms-ad.dxc needs to be generated from Active Directory. To use existing DXtools to perform this function, follow these steps:
rm $DXHOME/config/schema/ms-ad.bad rm $DXHOME/config/schema/ms-ad.dxc
dxschemaldif -D cn=administrator,cn=users,dc=ca,dc=local -w ad-password 155.35.131.49:389 | ldif2dxc -b $DXHOME/config/schema/ms-ad.bad -x $DXHOME/config/schema/overlay.dxg $DXHOME/config/schema/ms-ad.dxc
If items appear in the file ms-ad.bad they will not be supported and may require attention.
General Administration 99
Virtual Directory
Working with Overlay Directories
This section describes how to work with Overlay Directories.
Repair Orphan Entries
An orphan entry is an entry in an overlay directory that has been removed from the reference directory.
To check for orphan entries, you may need to look at the contents of the overlay DSA and ignore the reference DSA.
For example, an application could retrieve overlay entries (with bypass control present) and perform a base object search (no bypass control) for each entry retrieved. Every base object search that fails with the message No Such Object indicates and orphan entry. Orphans could be maintained via updates with bypass control present.
There are some situations where it might be helpful to perform operations ignoring the reference.
To send a request to the overlay directory only (ignoring the reference directory) include the following LDAP control with any LDAP request message:
overlayReferenceBypassControl
controlType: 1.3.6.1.4.1.3327.23.1 criticality: TRUE controlValue: None
Monitor an Overlay DSA
To dump the OID hash table, use the following command:
get overlay;
If the left column is an OID, this schema is specific to the reference store. Otherwise, if DXserver knows about it a name will be displayed. If the schema is sourced as shown here, then the left column will display all the names.
100 Administrator Guide
Virtual Directory
How a Virtual Directory Processes Requests
When a client applies an operation to the virtual directory, the operation is applied to the reference, the overlay, or both, depending on the mix of internal and external attributes.
Processing an Add Request
When you add an entry to a virtual directory, the following happens: 1. If the reference DSA is marked read-only, the operation fails, and an error is returned to the client. 2. The add operation is split into two operations:
Adding the new entry
Adding any internal attributes 3. The new entry is added to the reference directory. 4. Any internal attributes are added to the overlay DSA. If the new entry was successfully added to the reference DSA but the internal attributes were not added to the overlay DSA, an alarm is triggered and the Ingres error is returned to the client with the message Unwilling to Perform.
Processing a Remove Request
When you remove an entry from a virtual directory, the following happens: 1. If the reference DSA is marked read-only, the operation fails and an error is returned to the client. 2. The entry is removed from the reference directory. 3. Any internal attributes are removed from the overlay DSA. If the new entry was successfully removed from the reference DSA but the internal attributes were not removed from the overlay DSA, an alarm is triggered and the Ingres error is returned to the client with the message Unwilling to Perform.
General Administration 101
Virtual Directory
Processing a Search Request
When you search within a virtual directory, the following happens: 1. The virtual directory receives a search request. 2. The virtual directory checks the attributes contained in the filter. Here is a list of what to expect for different types of searches: Without filters Searches without filters will be performed against the reference and internally with the results being merged. External attributes only Searches with a filter containing only external attributes will be performed against the reference. For each entry returned a local base object search will be performed and the attributes returned merged into the entry. Internal attributes only Searches with a filter containing only internal attributes will be performed locally. For each entry returned a reference base object search will be performed and the attributes returned merged into the entry. NOT external attribute Searches with a filter containing a NOT of an external attribute will be performed against reference. For each entry returned a local base object search will be performed and the attributes returned merged. NOT internal attribute Searches with a filter containing a NOT of an internal attribute will be refused with an 'unwilling to perform'. AND internal and external Searches containing AND filters with a mixture of internal and external attributes will be refused with an 'unwilling to perform'. OR internal and external Searches containing OR filters with a mixture of internal and external attributes will be split into two searches. For each reference entry returned perform a local base object search to retrieve the entry's internal attributes. For each overlay entry returned perform a base object search against the reference to retrieve the entry's external attributes. 3. If a search against a reference DSA results in an error (including base- object searches retrieving attributes), an error is returned to the client. Any internal errors except No Such Object will be sent to the client.
102 Administrator Guide
Virtual Directory
Processing a Compare Request
When you send a compare request to a virtual directory, the following happens: 1. The assertion attribute is checked. 2. If the assertion attribute is external, the compare operation is performed against the reference DSA. Otherwise, the operation is performed against the overlay DSA. If the reference compare or the overlay compare fails, an error is returned to the client.
Processing a Modify Request
When you send a modify request to a virtual directory, the operation is checked for attributes:
External attributes only
Internal attributes only
Both internal and external attributes
Modifying External Attributes
When you modify an entry that includes only external attributes, the following happens: 1. If the reference DSA is marked read-only, the operation fails, and an error is returned to the client. 2. The external attributes are modified in the reference DSA. If the modify operation is successful, the operation is finished. If the external-only modify operation fails at any point, a modify error is returned to the client.
General Administration 103
Virtual Directory
Modifying Internal Attributes
When you modify an entry that includes only internal attributes, the following happens: 1. The internal attributes are modified in the overlay DSA. If this is successful, the operation is finished. If this operation is refused with the message No Such Object, this means that the entry does not yet exist. 2. Check if the entry being created exists in the reference store. 3. If the entry exists, the modify request is transformed into an add request containing the add-attribute and add-values from the original request. Attributes being deleted will be ignored. Schema checking will be bypassed as object-classes may not be present. If the internal-only modify operation fails at any point, a modify error is returned to the client.
104 Administrator Guide
Virtual Directory
Modifying a Mixture of Internal and External Attributes
When you modify an entry that includes both internal and external attributes, the following happens: 1. If the reference DSA is marked read-only, the operation fails, and an error is returned to the client. 2. The operation is split into two operations:
Modifying the external attributes in the reference DSA
Modifying the internal attributes in the overlay DSA 3. The external attributes in the reference DSA are modified. If this operation is successful, the second modify operation continues.
When you modify an entry that includes only internal attributes, the following happens: 1. The internal attributes are modified in the overlay DSA. If this is successful, the operation is finished. If this operation is refused with the message No Such Object, this means that the entry does not yet exist. 2. Check if the entry being created exists in the reference store. 3. If the entry exists, the modify request is transformed into an add request containing the add-attribute and add-values from the original request. Attributes being deleted will be ignored. Schema checking will be bypassed as object-classes may not be present. If the internal-only modify operation fails at any point, a modify error is returned to the client. If the external modify succeeds and the internal modify fails, the Ingres error will be returned to the client with the message Unwilling to Perform.
General Administration 105
Virtual Directory
Processing a Modify DN Request
When you send a modify-dn request to a virtual directory, the following happens: 1. If the reference DSA is marked read-only, the operation fails, and an error is returned to the client. 2. The modify-dn operation is split into two operations:
Modifying the entry in the reference DSA
Modifying the entry in the overlay DSA 3. The DN is modified in the reference directory. If the modify-dn fails in the reference DSA, an error is returned to the client. 4. The DN is modified in the overlay directory, if required. If the modify-dn fails in the overlay DSA with the message No Such Object, this message is ignored and the original request confirmed. If the modify-dn succeeds in the reference DSA but fails in the overlay DSA, the message Unwilling To Perform is returned to the client.
Processing a Bind Request
When a bind is received the overlay will bind to the reference using that user's credentials (if connecting directly) or using the ldap-dsa-name/ldap-dsa- password credentials (if connecting over DSP). If the bind is refused by the reference the bind will be refused by the overlay.
The overlay will trust users authenticated against the reference store.
Processing Unbind and Abandon Requests
The unbind and abandon requests work as they do for other DSAs.
106 Administrator Guide
Virtual Directory
Troubleshooting Overlay Directories
If you find any problems while you are setting up an overlay directory, check the following:
The overlay and reference directories must service the same prefix.
The reference directory does not support any other DSA flags other than the overlay-reference flag.
The overlay directory cannot have multiple overlay references.
If you rename an entry in the reference DSA, the corresponding entry in the overlay DSA will be orphaned. This may cause subsequent operations to produce inconsistent results.
General Administration 107
Knowledge Flags
Knowledge Flags
This section describes how to use knowledge flags to define the configuration, security, and interoperability of DSAs.
For lists of all the possible knowledge flags, see the chapter Knowledge Flags in the eTrust Directory Reference Guide.
For information about how knowledge files work, see Knowledge Files (see page 16).
The commands in the knowledge file must appear in the correct order. For information about this order, see the text file DXHOME\config\knowledge\knowledge.help.
Three Kinds of Knowledge Flags
eTrust Directory DSAs use three sets of flags to define the configuration, security, and interoperability of DSAs: DSA Flags DSA flags define which operations that can be performed on the local DSA. These flags can be used by the local DSA to determine which operations it can process. They can also be used by remote DSAs to determine which operation the local DSA will process.. Trust Flags Trust flags define how a DSA works with a remote DSA. Trust flags only affect how a remote DSA works. Link Flags Link flags define any special conditions for linking to the remote DSA, including the protocol, encryption level, and any interoperability requirements for specific applications.
For full lists of the knowledge flags, see Knowledge Flags in the eTrust Directory Reference Guide.
108 Administrator Guide
Knowledge Flags
Example: Flags in a Knowledge File
The following example knowledge file includes all three types of flags:
set dsa democorp = { ... dsa-flags = multi-write, shadow, load-share, no-routing-ac, limit-search, no-service-while-recovering trust-flags = allow-check-password, trust-conveyed-originator, allow- upgrading, allow-downgrading, no-server-credentials link-flags = dsp-ldap, ssl-encryption-remote, ms-ad };
The DSA flags will be used by the Democorp DSA when a client or another DSA attempts to run an operation on it. Also, other (remote) DSAs can use the DSA flags to check which operations can be sent to the Democorp DSA.
The trust flags will be used by remote DSAs to check how much they should trust the Democorp DSA.
The link flags will be used by remote DSAs to define how they should link to the Democorp DSA.
General Administration 109
Knowledge Flags
Example: How the limit-search DSA Flag Works
DSA flags are used by a DSA to define how it responds to operations that other DSAs or clients attempt to perform on it.
The following example shows how the limit-search DSA flag works: 1. The UNSPSC receives an unfiltered search request from a client. The UNSPSC DSA cannot fulfill the search request, but it knows that the Company A DSA can. 2. The UNSPSC DSA checks the Company A knowledge file to see whether there are any conditions for searching the Company A DSA. The limit-search flag indicates that the Company A DSA will reject any unfiltered or complex searches. 3. The UNSPSC DSA returns a Search Refused response to the client.
set dsa companya = {
dsa-flags = limit-search
}; 2. Check Company A DSA flags companya.dxc 1. Search request Client o=”Company A” Company A Application UNSPSC DSA DSA (JXplorer) 3. Search response
For information about particular DSA flags, see List of all DSA Flags.
110 Administrator Guide
Knowledge Flags
Example: How the allow-check-password Trust Flag Works
Remote DSAs use trust flags to define how much they should trust a DSA.
By default, security is tight. The trust flags provide a mechanism to selectively relax security between DSAs.
The following example shows how a DSA uses the allow-check-password trust flag : 1. The UNSPSC DSA receives a bind request from a user whose credentials are stored in the Democorp DSA. The UNSPSC DSA cannot check the user's credentials, but it knows that the Democorp DSA can. 2. The UNSPSC DSA checks the Democorp knowledge file to see whether it can trust the Democorp DSA to authenticate a user. The allow-check- password flag indicates that this is permissible. 3. The UNSPSC DSA requests the Democorp DSA to authenticate the user. 4. The Democorp DSA responds with the user's authentication. 5. The UNSPSC DSA returns the bind confirmation to the client.
set dsa democorp = {
trust-flags = allow-check- password
2. Check Democorp }; trust flags dn= Client 1. Bind request 3. Authentication request Democorp Application UNSPSC DSA DSA (JXplorer) 5. Bind response 4. Authentication response For information about particular trust flags, see List of all Trust Flags. General Administration 111 Knowledge Flags Example: How the dsp-ldap Link Flag Works Remote DSAs use link flags to define any special conditions for a link to another DSA. The following example shows how the dsp-ldap flag works. 1. The UNSPSC DSA receives a request to search the remote DSA named Company A, which happens to be an LDAP server. 2. The UNSPSC DSA checks the Company A knowledge file to see whether there are any special conditions for linking to that DSA. The flag dsp-ldap indicates that the Company A DSA requires that any links use LDAP. 3. The UNSPSC DSA uses DXlink to make an LDAP search request of the Company A DSA. 4. The Company A DSA responds with the search result (also using LDAP). 5. The UNSPSC DSA returns the search result to the client. set dsa companya = { link-flags = dsp-ldap }; 2. Check Company A link flags companya.dxc 1. Search request Client o=”Company A” 3. Search request (LDAP) Company A Application UNSPSC DSA LDAP server (JXplorer) 5. Search response 4. Search response (LDAP) For information about particular link flags, see List of all Link Flags. 112 Administrator Guide Chapter 4: Schema Definition This section contains the following topics: What Is a Schema? (see page 113) Supported Schema Protocols (see page 114) Configuring Schema (see page 115) Attributes (see page 119) Object Classes (see page 130) Dynamic Objects (see page 134) Name Bindings (see page 143) Defining Local Schema (see page 146) What Is a Schema? A schema is a formal definition of the contents and structure of the directory data. It governs where each entry can be placed within the directory structure, how entries are to be named, and what attributes each entry can contain. A DSA reads the schemas, and then enforces the schema rules 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) The schema of a running directory is available to LDAP clients via the LDAP Version 3 mechanism of schema publishing. For more information, see Schema Publishing (see page 288). Schema Definition 113 Supported Schema Protocols Supported Schema Protocols 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) 114 Administrator Guide Configuring Schema Configuring Schema eTrust Directory 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 DSA, you must also update schema.txt for the tools. For information about how to update schema.txt, see Schema Tools (see page 321). 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 initialization file (for instance, democorp.dxi) sources this schema definition. # DSA initialization file - democorp.dxi ... # SCHEMA source “../schema/schema.dxg”; ... Schema Definition 115 Configuring Schema Commands for Working with Schema Use the following commands for working with schemas: clear schema Command get schema Command set attr-set Command set attribute Command set name-binding Command set object-class Command set oid-prefix Command set syntax-alias Command set unique-attrs Command For more information about these commands, see the chapter eTrust Directory Commands in the eTrust Directory Reference Guide. 116 Administrator Guide Configuring Schema View Schema To view schema, use one of the following methods: The get schema command For more information, see get schema Command in the chapter DXserver Commands in the eTrust Directory Reference Guide. A directory browser such as JXplorer or JXweb. For information about viewing schemas in JXweb, see View Schemas (see page 449). For information about viewing schemas in JXplorer, see Displaying Schema (see page 386). Example: Viewing Schema Definition To retrieve the definition of commonName, use the command: get schema for commonName; or get schema for (2.5.4.3); An example output of this command is: Attribute (2.5.4.3) name = commonName ldap-names = cn syntax = caseIgnoreString You can use the name, ldap-names, or object identifier with this command. Schema Definition 117 Configuring Schema Schema Prefixes All attribute, attribute set, object class, and name binding definitions have a unique object identifier (for example, 2.5.4.6) that uniquely identifies that object. When defining a schema, you can find many definitions on the same branch of the schema definition tree. You can define a schema prefix that replaces the branch of the tree in all subsequent definitions. Example: Schema Prefix Definition set 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. 118 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. Example: Attribute Definition set attribute x500attr:3 = { name = commonName ldap-names = cn syntax = caseIgnoreString description = "Common Name attribute" }; Example: Read-Only Attribute Definition schema set attribute (2.5.18.1) = { name = createTimestamp syntax = generalizedTime no-user-modification }; Schema Definition 119 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 numericString objectIdentifier octetString postalAddress printableString telephoneNumber teletexTerminalId UTCTime As more applications become directory-enabled, you can define new attribute syntaxes. To support these new syntaxes, particularly with their search matching rules, you may need special syntax coding and decoding functions. Generally this requires a software update to the DSA and DUA processes. However, to more readily support new attribute syntaxes on demand in operational systems, the DXserver has a feature for using unknown syntaxes. 120 Administrator Guide Attributes 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. See the configuration files (.dxc) in the schema directory for the latest supported syntaxes. To ensure DIT data integrity over configuration changes, the DSA stores the names of its current attributes and attribute syntaxes securely within the directory. The list names the ones that have been used to create directory entries. This list is not the same as that of all possible attribute names and syntaxes. When you attempt to change the syntax of an attribute after an instance of that attribute exists, the following message occurs: ** ALARM **: Database attribute attribute has different syntax than schema 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. 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 121 Attributes Syntax Aliases for Unsupported Attribute Syntax Syntax aliasing is useful if you add a new schema object definition that uses an attribute syntax that is not supported by eTrust Directory. The command for setting up a syntax alias is: [ schema ] set syntax alias For example, set syntax-alias (1.3.6.1.4.1.1466.115.121.1.18) = { name = dlSubmitPermissions alias-for = caseIgnoreString }; Attribute Sets Attribute sets let you easily group attribute definitions under a label so you can use them later in object class and other definitions. Define attribute sets in the configuration file using the set attr-set command. The attribute set is given an object identifier and a definition. The definition consists of a name and a list of attributes or attribute sets that are contained in the attribute set being defined. Example: Attribute Set Definition set attr-set x500aset:3 = { name = organizationalAttributeSet description, localeAttributeSet, postalAttributeSet, telecommunicationAttributeSet, businessCategory, seeAlso, searchGuide, userPassword }; Attribute sets are a convenient way of grouping large numbers of attributes together for use in object class definitions. Attribute sets can contain other previously defined attribute sets. 122 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 following command, you can use organizationName or the shorter LDAP name o in other commands that need to reference the attribute: set attribute (2.5.4.10) = { name = organizationName ldap-names = o syntax = caseIgnoreString }; LDAP names are most convenient when defining distinguished names (DN). The following DN: is equivalent to: Schema Definition 123 Attributes Unique Attributes Some applications that use eTrust Directory as a repository may require that the value of some attributes are unique across the repository. Information such as user name, user ID, or key may need to be unique for correct operation of a service. For example, an e-mail service will not operate effectively if a user chooses an ID that is already in existence. The benefits of this change will be to push uniqueness checking from the application to the directory. This removes the potential for attributes existing with duplicate values. Distribution and Replication Unique attributes cannot be used in a distributed environment, because there is no way of ensuring that attribute values across multiple DSAs are not being updated concurrently. This means that the attribute value check will only apply to the local DSA. Make sure that the DSA design does not assume that the attribute value check will be performed across multiple DSAs. In a replicated environment, unique attributes can be used in a single-master scenario only. This is also because of the issue of concurrent updates. Unique Attribute Flag Set the unique attributes using the DSA set command: set unique-attrs = attr1, attr2, …; To see a list of all of the unique attributes in a DSA, use the DSA console to issue a get oper command. Implementing Unique Attributes Before you implement unique attributes: Choose the attributes carefully. Make sure you understand how client applications handle problems when trying to add or modify attribute values that already exist. During operation, take care to not inadvertently switch off this feature if it is still required. 124 Administrator Guide Attributes How Unique Attributes Work When a client application tries to update an attribute that is set to be unique, eTrust Directory checks that the attribute value is not already in existence. If the value does already exist, an error message is sent back to the client application. If the value does not yet exist, the client request is confirmed. Limitation: Access Controls Bypassed If these attributes have access controls imposed, the triggered search will bypass these to ensure uniqueness. This means that a user may be able to write a client application to determine these values. If the unique attributes contain sensitive information, then this may be an issue. Limitation: Uniqueness Cannot Be Restricted to a Sub-Tree If attribute value uniqueness is required, but only need to be unique for a particular sub-tree, then separate DSAs will be required. Schema Definition 125 Attributes Limitation: Uniqueness Not Enforced In Pre-Existing Data We recommend that this feature be enabled on empty directories or new attributes. This will ensure uniqueness. There is no DSA mechanism for finding duplicates. If this feature is being enabled on a running system, the administrator should perform checks for duplicate attribute values. Uniqueness will not be enforced on back-end loads. This has a similar impact as turning on this feature with an existing set of data. The following example shell script shows how to find duplicates: #!/bin/sh if [ $# -ne 2 ]; then echo "Usage: $0 database attribute" exit 1 fi DATABASE=$1 ATTRIBUTE=$2 sql $DATABASE < The organizationalAttributeSet referred to in this example was defined in Example: Attribute Definition (see page 119). 130 Administrator Guide Object Classes 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. Structural Classes Most of the object classes in a directory are structural, because they define what an entry is. They also impose rules on the entries that are stored beneath them. For example, the object class organization (o) may require that all objects stored beneath it belong to the object class organizationalUnit (ou). Other examples of structural object classes are groupOfNames, inetOrgPerson, and person. Auxiliary Classes The LDAP rules require each entry to belong to only one structural object class, but an entry can also belong to one or more auxiliary object classes. An auxiliary object class adds attributes to entries already defined by a structural object class. An auxiliary object class cannot stand on its own in an entry. The entry must contain a structural object class. Unlike structural object classes, auxiliary object classes place no restrictions on storing an entry. Schema Definition 131 Object Classes 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! eTrust Directory DSAs support multiple inheritance of object class. This means that an object class can inherit attributes from more than one parent object class. Object Class Storage By definition, the object class attribute used by every object or entry in the directory can have multiple values of object identifiers. This enables object classes to indicate their refinement (for example, through the use of object class refinement or the addition of auxiliary object classes). Configuring How the OC Attribute Is Stored You can configure how the object class attribute (single value or multiple values) is stored within the directory. By default, the DSA adds the object classes to the entry exactly as specified in the LDAP or DAP add request (for example, the object class attribute may have multiple OIDs). However, directory performance improves slightly when the object class attribute only contains a single value (the OID of the refined OC). However, this should not be the main influence over the object class design of attributes. Where entries contain a single inherited object class and explicitly list all its superiors (their OC OIDs), the superiors can be removed, leaving the 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, if a directory contains entries corresponding to people, then each entry can explicitly contain the following object classes within the database: inetOrgPerson organizationalPerson Person top 132 Administrator Guide Object Classes Pruning and Replacing Object Classes It is more space-efficient to configure the DSA to prune all inherited 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 Boolean Removes redundant superior object classes when new entries are created. set return-oc-parents Boolean Replaces the superior object classes to entries retrieved when searching. set add-oc-parents Boolean Causes parent objectclasses to be added when entries are added. e.g. Consider adding a democorp entry with the classes: inetOrgPerson This control adds the parent (top-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 133 Dynamic Objects Dynamic Objects eTrust Directory lets you dynamically extend the schema of a DSA in two ways: Use ANY attribute defined in the schema eTrust Directory lets you define an object to be extensible. The object can then include any attributes that are defined in the schema. For information, see Extensible Objects (see page 134). Use ANY attribute NOT defined in the schema eTrust Directory lets you define an object to use auto-registered attributes. The object can then dynamically define attributes that are not included in the schema definition. For information, see Auto-registered Attributes (see page 135). Extensible Objects If you define an object as extensible, it may contain any attribute that is already defined in the DSA schema. Extensible objects are defined in section 7.1 in the LDAP V3 RFC 2252. This standard defines the auxiliary object class extensibleObject. The auxiliary object class extensibleObject is defined in the schema file ldapv3.dxc, which is supplied with eTrust Directory. However, it is not in the default schema group. If you want a DSA to use this schema, you must add it to the DSA's initialization file. There are two ways to make an object extensible: Add the extensibleObject object class to an object For instructions, see Make an Existing Object Extensible (see page 139). Add all-attributes to the may-contain list in the schema For instructions, see Create a New Extensible Object (see page 138). 134 Administrator Guide Dynamic Objects Auto-registered Attributes If you permit an object to use auto-registered attributes, it may contain any attribute that is not already defined in the DSA schema. This can be useful if an LDAP application uses attributes that are not defined in the DSA's schema. Auto-registered Attributes and Other Features Auto-registered attributes are supported with LDAP clients only. This list describes how auto-registered attributes work with eTrust Directory tools and features: DAP Tools Auto-registered attributes do not work with the DAP tools (DXmodify, DXrename, DXdelete, and DXsearch). DXloaddb Tool You can use the DXloaddb tool to load auto-registered attributes from an LDIF file into a database. However, you cannot use schema.txt, which is no longer supported. The DXloaddb tool only auto-registers an attribute if it is using the schema from the DSA configuration. Replication Auto-registered attributes work with DISP, multiwrite, and multiwrite-DISP DSAs, but only with other eTrust Directory DSAs. Other features Auto-registered attribute names are not supported within the configuration files. This means that special indexing, access controls, class of service, and other features will not support auto-registered attribute names. Schema Definition 135 Dynamic Objects Limitations of Auto-registered Attributes Auto-registered attributes are limited to 40 characters, and are always multi- valued. You cannot use an auto-registered attribute as the naming attribute for an object. Attributes that are automatically registered use the following template for their virtual schema definition: attribute auto-generated-OID = { name = supplied-name equality = caseIgnoreMatch substr = caseIgnoreSubstringsMatch syntax = directoryString } You can use JXplorer and JXweb to display extensible attributes, but you cannot use them to add a new value to an extensible attribute. 136 Administrator Guide Dynamic Objects Risks of Dynamic Attributes When you define your directory system, you must design your schema carefully. You should try to define your schema without resorting to using auto-registered attributes or extending the object. Do not use dynamic attributes as a way to avoid designing the schema. If you do use dynamic attributes, you have less control over which attributes can be added to an object. You can still control which of the defined attributes are included, but you cannot control which unknown attributes are added. Example: Two Applications Using the Same Auto-registered Attribute If you use auto-registered attributes, different applications may use an attribute of the same name for different purposes. For example, the following diagram shows a single DSA that is used by two applications. The application Client 1 uses the auto-registered attribute newPerson: However, problems occur when Client 2 attempts to also register an attribute named newPerson, which has different parameters: Schema Definition 137 Dynamic Objects Use Dynamic Objects You can extend an object to use either auto-registered attributes, or any non- defined attributes, or both. Create a New Extensible Object If you are writing a schema for an eTrust Directory DSA, you can make an object class extensible. To allow an object class to use any attributes defined in the DSA schema 1. Open the schema file, and find the object class that you want to update. 2. Add all-attributes to the may-contain list: schema set object-class prefix:2 = { ... may-contain all-attributes ... }; 3. Initialize the DSA. 138 Administrator Guide Dynamic Objects Make an Existing Object Extensible If you are using an existing schema, you can still make an object extensible. This section describes how to do this using JXplorer. To make an existing object extensible 1. If the DSA does not include ldapv3.dxc in its schema, do the following: a. Add ldapv3.dxc to the DSA initialization file after the clear schemas command, and after the X.500 schema is sourced. For example: clear schema; source "../schema/default.dxg"; source "../schema/ldapv3.dxc"; b. Initialize the DSA: dxserver init dsa-name 2. In JXplorer, connect to the DSA. 3. Navigate to the object that you want to change. 4. In the right pane, select the Table Editor tab to display the attributes for this object. 5. Click the Change Class button. 6. In the Set Object Entry Classes dialog, find the object class extensibleObject in the Available Classes list. 7. Select the object class extensibleObject, click Add, and click OK. 8. Click Submit to save your change to this object. This object can now use any attribute that is defined in the DSA schema. Schema Definition 139 Dynamic Objects Add an Attribute to an Extensible Object After you have made a object extensible, you can add any attribute in the schema to that object. You cannot do this using JXplorer or JXweb. This section describes how to do this using DXconsole commands. To add an attribute to an extensible object 1. Make sure that the object is extensible, as described in the previous section. 2. Open DXconsole, and bind to the DSA: bind-req; 3. Add the attribute to the entry: mod-entry-req entry=DN add-attr {attribute-name "attribute-value"}; For example, to add the carLicense attribute with the value EXT 133 to the Democorp organization entry, use this command: mod-entry-req entry= Use Auto-registered Attributes in an Object To allow a DSA to use attributes from an LDAP client, even if those attributes are not defined in the DSA schema, you need to enable auto-registered attributes in a schema used by the DSA. To allow an object class to use auto-registered attributes 1. Open the schema file, and find the object class that you want to update. 2. Add auto-register-attributes to the may-contain list: schema set object-class prefix:2 = { ... may-contain auto-register-attributes ... }; 3. Initialize the DSA. 140 Administrator Guide Dynamic Objects Use Both Auto-registered Attributes and Extensible Attributes You can allow an object class to use auto-registered attributes and also any attributes defined in the DSA schema. This allows the class to use all attributes already defined in the schema, and also contain any attribute that is not already defined in the DSA schema To allow an object class to use all defined and non-defined attributes 1. Open the schema file, and find the object class that you want to update. 2. Add both all-attributes and auto-register-attributes to the may-contain list: schema set object-class prefix:2 = { ... may-contain auto-register-attributes all-attributes ... }; 3. Initialize the DSA. Schema Definition 141 Dynamic Objects Example Schemas for Dynamic Objects The following sections show example schema definitions for dynamic objects. Example: Object Class Definition Using Auto-registered Attributes The following schema definition defines the object class autoOrganization, which inherits from the organization object class. The organization object class must contain the attribute organizationName and may contain any attribute in the organizationalAttributeSet: these requirements are inherited by the object class autoOrganization. In addition, it must contain the attribute description and may contain any other attribute that is not defined in the DSA's schema. schema set object-class myprefix:2 = { name = autoOrganization subclass-of organization may-contain auto-register-attributes must-contain description }; Example: Extending an Object Class Definition The following schema definition defines the object class newPerson, which inherits from the person object class. The person object class must contain the attributes cn and surname, which means that the newPerson object class must also include those attributes. In addition, it may contain any other defined attribute. schema set object-class myprefix:1 = { name = newPerson subclass-of person may-contain all-attributes }; 142 Administrator Guide Name Bindings Name Bindings Name bindings define where entries appear in the DIT. eTrust Directory requires a separate name binding for each allowable parent-object and child- object relationship in the directory. Example: Name Binding Definitions set name-binding x500nbind:2 = { name = org-top organization allowable-parent top named-by organizationName }; 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. Example: Advanced Name Binding Definition set name-binding x500nbind:22 = { name = orgUnit-orgPerson organization allowable-parent organizationalUnit named-by commonName optional surname }; Schema Definition 143 Name Bindings Name Binding Checks The DSA checks name binding rules whenever you add or rename an entry. To enforce both the parent-child relationships in the directory, and the naming attributes used by a particular entry, name bindings are necessary. The system reports any name binding errors as: Update Error: Naming Violation. When you enable warnings (set trace = warn,…;), the system sends a message describing the reason for the name binding failure to the console. There is one exception regarding name binding checks. When an object is added under the naming context (or prefix) of a DSA, 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, eTrust Directory 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. 144 Administrator Guide Name Bindings 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 145 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 described in Name Bindings and Aliases (see page 144). 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 following schema definition 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. 146 Administrator Guide Defining Local Schema Example: 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 147 Chapter 5: Distribution and DSP This section contains the following topics: Distribution Protocols (see page 149) Managing DSP (see page 150) Configuring a DSA (see page 157) Configuring Another DSA (see page 160) Configuring a Domain of DSAs (see page 163) Alternative DSAs (see page 168) Aliases (see page 178) Distribution Protocols 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. eTrust Directory 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 Distribution and DSP 149 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. DSP Commands The following DSP commands let you change the DSP configuration: set always-chain-down set dsa set max-dsp-ops set multi-chaining set multi-write-disp-recovery set multi-write-queue get dsp get online-dsas get dsas clear dsas unbind For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide. 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 For more information see the eTrust Directory Developer Guide. Access controls can hide the presence of a subordinate DSA, making that subtree invisible to a list service or any other service. For more information, see Access-Controlled Routing (see page 243). 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. 150 Administrator Guide 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 (see page 159) for more information. Access controls hide the existence of the remote DSA. See Access- Controlled Routing (see page 243) for more information. The remote DSA is unavailable. You cannot establish a link of the appropriate authentication level to the remote DSA. There is no DSA knowledge configured for the area of the operation. Depending on the circumstance, the remote operation returns a: Result Referral Service error Security error See the X.500 standards for a complete specification of how distributed DSAs cooperate to resolve a query. Limiting Remote Operations In a multi-DSA environment a DSA may have to forward requests to other DSAs to process. You can limit the maximum number of concurrent remote operations that a DSA manages by setting max-dsp-ops in the configuration file (.dxc) in the limits directory. Example: Limiting the Number of Remote Operations to 100 set max-dsp-ops = 100; Distribution and DSP 151 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. For more information, see List of all DSA Flags. A DSP connection to a remote DSA unbinds after the dsp-idle-time is exceeded. Remove Remote DSA Knowledge You can remove all knowledge of remote DSAs using the command: clear dsas; 152 Administrator Guide Managing DSP Unbinding Remote Connections Display Outgoing Connections When a DSA communicates with a remote DSA using DSP, it sets up a connection (bind) to the remote DSA. You cannot abort this connection using the abort user command because it is an outgoing connection. You can obtain information about outgoing connections with the command: get online-dsas; Unbind All or Some Connections You can unbind all or some connections using this information and one of the following commands (assuming 3 is a valid connection identifier): unbind all; unbind dsa 3; Unbind Outgoing Connections That Exceed Global Values A DSA can automatically unbind outgoing connections when they exceed global values set in the remote-DSA definition, for example: set dsa “Eagle” = { ... dsp-idle-time = 60 ... }; Distribution and DSP 153 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. For more information, see Encrypt DSA-to-DSA Communication (DSP and DISP) (see page 188). 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 (see page 157) 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. For more information, see Access-Controlled Routing (see page 243). 154 Administrator Guide Managing DSP View DSP Configuration To monitor DSP connections, use following command in DXconsole: get dsp; This command displays the DSP configuration values and details of current outgoing connections. View DSP Configuration To view the DSP configuration, use the following command in DXconsole: get dsp; Example: Output from the get dynamic-dsp Command max-dsp-ops = 100 local-prefix = Distribution and DSP 155 Managing DSP View Online Connections To view the DSP connections that are currently active, use the following command in DXconsole: get online-dsas; Example: Output from the get online-dsas Command Remote: DSA 2 (DEMOCORP) Association: state 3, idle for 2 seconds, 0 operations waiting 0 operations abandoned prefix: Display Each DSA for Which the Current DSA Has Knowledge Use the following command to display information about each DSA for which the current DSA has knowledge, including itself: get dsas; 156 Administrator Guide Configuring a DSA Configuring a DSA You can configure all DSAs, including the local one, using the set dsa command. For more information, see Defining DSAs with the set dsa Command (see page 39). You can dynamically issue the set dsa command from the DXconsole, but it is recommended that you include it in a DSA definition file (.dxc) in the knowledge directory. You then source this file from another configuration file, either a .dxg file in the knowledge directory or a .dxi file in the servers directory. Configuring a Subordinate DSA The following example defines a DSA called DemoResearch, which is subordinate to the pre-configured Democorp DSA in the standard version. Distribution and DSP 157 Configuring a DSA Example Configuration for a Subordinate DSA set dsa “DemoResearch” = { prefix = The DSA definition contains a prefix that defines the area of the DIT that is covered by this DSA: prefix = 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). 158 Administrator Guide Configuring a DSA Proxy DSAs There are a number of situations where a group of DSAs must appear to the outside world as a single DSA. External DUA or DSA Proxy DSA Internal Internal DSA 1 DSA 2 Internal Internal DSA 3 DSA 4 For example, an organization can make a single DSA visible through an Internet firewall, but internally let that DSA send DSP requests to other internal DSAs that control subtrees subordinate to the visible DSA. This configuration fails when the external DUA sets the local-scope or chaining- prohibited service controls. In this case, the visible DSA returns a referral, but the DUA cannot connect to the referred DSA because there is no access to this DSA through the firewall. The solution to this problem is overriding the local-scope and 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. Distribution and DSP 159 Configuring Another DSA Configuring Another DSA To configure the knowledge of a remote DSA, use the set dsa command. For more information, see Defining DSAs with the set dsa Command (see page 39). Local DSA Remote DSA A DSA is identified by its name and prefix. The relationship between two DSAs is represented by the corresponding relationship between the prefixes. For more information, see A Domain of DSAs (see page 163). 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. 160 Administrator Guide Configuring Another DSA Configuring a Third-party DSA To configure the knowledge of third-party DSAs, use the set dsa command. Example: Setting a Remote DSA Reference set dsa “DemoUni” = { prefix = 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. eTrust Directory has a feature, DXlink, which treats a remote LDAP server as another DSA. To activate DXlink, set the dsp-ldap link flag in the set dsa command in the knowledge directory of the LDAP server: link-flags = dsp-ldap Note: When you are using LDAP Version 3, use the dsp-ldap link flag. When you are using LDAP version 2, use dsp-ldapv2. For more information about DXlink, see Integrating Other LDAP Servers (see page 293). Distribution and DSP 161 Configuring Another DSA 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 DSAs on the same computer. You configure each DSA with its own definition and connect the DSAs together using DSP. Example: Setting Two DSA References on the Same Machine # Knowledge configuration file: localTwo.dxc set dsa “LocalTwo” = { prefix = 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. 162 Administrator Guide Configuring a Domain of DSAs Configuring a Domain of DSAs 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 knowledge. A Domain of DSAs 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. In this diagram, DSA1 is the superior of DSA2 and DSA3. DSA4 and DSA5 are subordinates of DSA3. DSA 1 DSA 2 DSA 3 DSA 4 DSA 5 A request received by one DSA that requires an operation on an entry that is not contained in that DSA's area of control, is chained (forwarded) to the relevant DSA. A request may be chained through a number of DSAs before finding the DSA capable of processing the request. When a domain of DSAs has shared knowledge, a DSA receiving a request is able to forward that request directly to any other DSA within the domain. A search request can require a subtree search spread over more than one DSA. In this case, the DSA containing the base object of the search performs the search locally and multi-chains the search to any DSAs that control part of the subtree to be searched. These DSAs will then return the search results back to the originating DSA, which will collate them and return the result back to the client. Distribution and DSP 163 Configuring a Domain of DSAs 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. 164 Administrator Guide Configuring a Domain of DSAs 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 (see page 168) 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 = Distribution and DSP 165 Configuring a Domain of DSAs 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. 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, ...... }; 166 Administrator Guide Configuring a Domain of DSAs 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 DSA 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 167 Alternative DSAs Alternative DSAs If you define more than one DSA with the same prefix (naming context) and data, these DSAs can be used to improve the performance and availability of the directory service. This section describes three ways that groups of DSAs with the same prefix and the same data can be used: Failover To improve the availability of the service, when one DSA fails, another automatically takes over its request load. Load sharing To improve performance, read requests are divided between two or more DSAs. Query streaming To improve performance, requests of different types are routed to different DSAs. 168 Administrator Guide Alternative DSAs DSA Failover The purpose of failover is to improve the availability of the directory service. In the following example, the router DSA usually sends requests to DSA 1. If DSA 1 fails, the router DSA automatically sends all requests to DSA 2. This change is invisible to the clients. In this system, DSA 2 is simply a backup: it is only used if DSA 1 fails. Router DSA DSA 1 DSA 2 Replication Database Database Computer A Computer B In the following example, the San Diego and Tokyo offices each use local replica DSAs, to improve performance. During normal operation, each local router DSA sends requests to the local data DSA. If either of the local data DSAs fails, the routers automatically fail over to the remote data DSA. San Diego Tokyo Router DSA Router DSA DSA 1 DSA 2 Replication Database Database Computer A Computer B (San Diego) (Tokyo) Distribution and DSP 169 Alternative DSAs Set the DSA Precedence For Failover When more than one data DSA fails, the router DSA fails over to other DSAs in the order in which they are listed in the configuration files. You can override this order with the following commands: set precedence = precedence-list; set write-precedence = precedence-list; The set precedence command defines the order of the DSAs that the router DSA fails over to. The set write-precedence command defines the order in which DSAs are chosen to perform updates. You can use it to direct the write requests from a failover computer to a preferred master. If the set write-precedence command is not present, updates follow the normal precedence, which is defined by the order of the DSAs in the configuration file, or the set precedence command. The DSAs in these lists have precedence over those that are not listed, and DSAs earlier in the lists have precedence over those later in the lists. To maximize performance, in general you should give faster DSAs precedence over slower DSAs, and local DSAs precedence over remote DSAs. When these commands occur in a configuration file, source them after the knowledge. These commands should appear once only in the configuration files that are sourced by any particular DSA. Example: Using precedence for geographically separated DSAs The DSAs EAST, WEST, NORTH and SOUTH contain the same information. The following command ensures that DSAs in the east fail over to EAST before WEST: set precedence = EAST, WEST; The DSAs NORTH and SOUTH are not listed, so if both EAST and WEST are unavailable, DSAs will fail over to them in the order that they are listed in the configuration file. Example: Using write precedence set write-precedence = home-dsa,work-dsa; 170 Administrator Guide Alternative DSAs DSA Load-Sharing Load-sharing is a way to use a router DSA and multiple data DSAs to improve performance. In a system with load-sharing, the router uses a least-busy algorithm to send read requests to the DSA with the least load at the time. In the example load-sharing configuration shown here, DSA2 has the smallest queue of outstanding queries, so the router DSA will send the next query to that DSA. Queries Router DSA Queue: Queue: Queue: 20 queries 10 queries 0 queries DSA 1 DSA 2 DSA 3 Database When the router DSA is checking the DSAs, it only considers requests that it has sent, and it does not assess the load that might be caused by the request about to be sent, or the effect of requests that are being sent from other DSAs. You can examine the statistics logs of the data DSAs to understand how often the load is such that all three are busy. If all three are often busy, you might need more data DSAs. Distribution and DSP 171 Alternative DSAs Load-Sharing Groups In a load-sharing system, DSAs work to balance the number of read requests. You can use load-sharing groups to constrain load-sharing to a sub-set of the DSAs that have the same prefix. Example: Load-Sharing Group The following example shows a router DSAs and three data DSAs with the same prefix. Two of these data DSAs are in a load-sharing group, and the router shares the load of read requests between these two DSAs. The third DSA is ignored because it is not in the load-sharing group. Read Requests Load-sharing group Router DSA DSA 1 DSA 2 DSA 3 Database Computer A 172 Administrator Guide Alternative DSAs Example: Load-Sharing Groups across Two Sites In the following example, the San Diego and Tokyo offices each use local load- sharing groups of DSAs to improve performance. During normal operation, each local router DSA sends requests to the local group. If all of the DSAs in one local load-sharing group fail, the router can fail over to the remote load- sharing group. Read Read Requests Requests San Diego Tokyo Router DSA Router DSA DSA 1 DSA 2 DSA 3 DSA 4 Load-sharing groups Database Database Replication Computer A (San Diego) Computer B (Tokyo) Set the DSA Precedence For Failover with Load-Sharing Groups You can use precedence rules to affect how failover works with load-sharing groups. For information about setting precedence, see Set the DSA Precedence For Failover (see page 170). If you use the set precedence command to list DSAs that are also in load- sharing groups, then a load-sharing group has the precedence of the highest DSA in that group. For example, consider the following command: set precedence = DSA1, DSA2, DSA3, DSA4; A load-sharing group that includes DSA1 and DSA4 has precedence over a group that includes DSA2 and DSA3. Also, a load-sharing group that includes DSA4 has precedence over a group that includes no listed DSAs. Distribution and DSP 173 Alternative DSAs Set Up a Load-Sharing System To set DSAs to share the load for a particular context prefix, do the following: 1. Decide how many DSAs you will use to share the load of read requests. 2. Set up these DSAs with the same prefix and the same data. 3. Set each DSA to share the same knowledge information. 4. Add the load-share DSA flag to the shared knowledge: set dsa dsaname = { ... dsa-flags = load-share, ...... }; 5. In the router DSA's group knowledge file (.dxg), list the load-sharing DSAs consecutively. 6. (Optional) To create a load-sharing group, add the load-share-group item to the knowledge for the DSAs in the group: set dsa dsaname = { ... load-share-group = group-name dsa-flags = load-share, ...... }; Note: The commands in the knowledge file must appear in the correct order. For information about this order, see the text file DXHOME\config\knowledge\knowledge.help. 174 Administrator Guide Alternative DSAs DSA Query Streaming Query streaming is a way to send particular types of queries to different DSAs. This allows you to dedicate DSAs to particular types of operations, which can improve performance consistency. You can use query streaming with load sharing, to direct queries to different load-sharing groups. How Query Streaming Works Query streaming is somewhat like checkout lanes in a supermarket. In a supermarket, the express lanes are reserved for small sales, to permit people with only a few items to be served quickly. In a supermarket without an express lane, people with only a few items can be stuck behind people with many items. Similarly, you can dedicate some DSAs to small, fast queries (such as authentications) so that they are not held up by complex queries (such as reports). In the following example, the Router DSA sends queries in the following manner: Simple searches only go to DSA 1 and DSA 2 Complex searches only go to DSA 3 Update requests only go to DSA 4 Queries Router DSA Simple Simple Complex Update queries queries queries requests DSA 1 DSA 2 DSA 3 DSA 4 load-share load-share read-only limit-search limit-search read-only read-only Distribution and DSP 175 Alternative DSAs Set Up Query Streaming To set up query streaming, follow these steps: 1. Decide how many data DSAs your distributed system will include. 2. Decide what queries each data DSA will accept. 3. For each data DSA, set one or more of the following flags in the DSA knowledge file: The read-only flag A router will not forward update requests to a DSA that has the flag read-only set in its knowledge file. This routes update requests to any DSAs without the flag read-only. The limit-list flag A router DSA will not forward any list requests to a DSA that has the flag limit-list set in its knowledge file. The limit-search flag A router DSA will not forward any complex searches to a DSA that has the flag limit-search set in its knowledge file. For more information about the limit-search flag, see the section Example: How the limit-search DSA Flag Works (see page 110). 176 Administrator Guide Alternative DSAs What Is a Simple Search? This section describes simple and complex searches. If a DSA includes the limit-search flag in its knowledge file, no complex searches will be sent to that DSA. The following searches are simple: Exact match searches-For example, cn=john smith Initial substring searches-For example, cn=john s* Searches that include exact-match and initial-substring searches combined with simple ANDs or ORs,-For example, (&(cn=john smith)(cn=john s*)) All base-object searches (reads), regardless of the filter The following searches are complex: (objectclass=*) (!(cn~=john smith)) (&(objectclass=*)(cn~=john smith)) (|(cn=jon*)(cn=john*)) These complex searches could only be sent to a DSA that does not have the limit-search flag set. Distribution and DSP 177 Aliases Aliases An alias is a directory entry that contains the name of another entry. When you search or browse a directory, you can decide whether to resolve aliases (show the details of the target entry) or to show the details of the alias entry itself. An alias entry has the object class of alias. An entry of this type has the mandatory attribute aliasedObjectName which must contain the DN of the entry that the alias is pointing to. For example, if cn=Staff,o=Democorp is an alias entry that points to ou=People,o=Democorp, then: cn=Staff,o=Democorp has the object class alias cn=Staff,o=Democorp has the attribute aliasedObjectName with the value ou=people,o=Democorp. 178 Administrator Guide Chapter 6: Security This section contains the following topics: Protecting Communications with SSL Encryption (see page 179) Authentication (see page 193) How Password Management Works (see page 206) Managing Passwords (see page 212) Access Control Overview (see page 220) Static Access Controls (see page 224) Dynamic Access Controls (see page 233) Groups, Roles, and Proxies (see page 235) Access-Controlled Routing (see page 243) Protecting Communications with SSL Encryption SSL (Secure Socket Layer) encryption may be used to protect any link connections to or from eTrust Directory DSAs. eTrust Directory supports SSL methods for ensuring confidentiality, by encryption, and for authentication. We refer to these as SSL encryption and SSL authentication. Note: SSL authentication always uses SSL encryption. For information, see SSL Authentication (see page 195). The SSL Protocol SSL is a protocol for providing secure communications over TCP/IP. With its successor Transport Layer Security (TLS), SSL has become the industry standard for confidentiality and integrity services. SSL may also be used for authentication when used in conjunction with application layer services. For more information about SSL, see the SSL 3.0 Specification (http://home.netscape.com/eng/ssl3/index.html). Certificates SSL supports X.509 certificates. You must properly manage these certificates through a Certification Authority or by using appropriate software. JXplorer lets you manage certificates, private keys, and keystores. Security 179 Protecting Communications with SSL Encryption How eTrust Directory Uses SSL This section describes how eTrust Directory uses the SSLD component to maintain secure communications. How an SSL Connection is Established In an SSL transaction, the client sends a handshake to the server. In response, the server sends its certificate to the client. The certificate asserts the server's identity and includes its public key. It also includes the distinguished name of the Certification Authority that issued the key. Provided the client trusts the Certification Authority, the server's identity can be verified. The SSLD SSLD is a stand-alone background process, or daemon, that works with eTrust Directory to perform SSL authentication and encryption operations. SSLD is based on OpenSSL The OpenSSL library has been modified to limit the cipher suites to those that comply with US export controls. Symmetric keys are limited to 128 bits or less and asymmetric keys, used in key exchange, are limited to 1024 bits or less. eTrust Directory uses SSLD to handle all its SSL and TLS communications. So that there is no possibility of decrypted information being intercepted, the SSLD must run on the same computer as the DSA. SSLD is multithreaded, which means that one SSLD process can serve many DSAs simultaneously. There is no need to run multiple SSLD processes on the same computer. The SSLD server supports: SSL (both version 2 and 3) Transport Layer Security (TLS) 180 Administrator Guide Protecting Communications with SSL Encryption eTrust Directory Personality Certificates To configure SSLD, you need to use personality certificates. A personality certificate is a file that contains a public key certificate and the corresponding private key. The personality files are in PEM format, as used for privacy-enhanced mail. Using this text-based format, multiple certificates may be stored in one file. eTrust Directory also allows the private key to be stored in a hardware security module (HSM). DXserver Personality Certificates SSLD is configured with personality files, each containing a public key certificate and the corresponding private key. eTrust Directory also allows the private key to be stored in hardware, called the Hardware Security Module (HSM). When a DSA connects to the SSLD it passes its DSA server name as its SSLD personality. The server name is the name specified by the set dsa dsaName command in the DSA configuration file in the knowledge directory. For example, for the Democorp DSA, the SSLD personality name is democorp. This personality name determines the personality certificate file that the SSLD uses to support authentication of the DSA. It is mapped to a filename in the form personality.pem (where the personality string is converted to lowercase). The personality files are in PEM format, as used for Privacy-Enhanced Mail. Using this text-based format, multiple certificates may be stored in one file. How SSLD Works with a DSA When a DSA connects to the SSLD it passes its DSA server name as its SSLD personality. The server name is the name specified by the set dsa dsaName command in the DSA configuration file in the knowledge directory. For example, for the Democorp DSA, the SSLD personality name is democorp. This personality name determines the personality certificate file that the SSLD uses to support authentication of the DSA. It is mapped to a filename in the form personality.pem (where the personality string is converted to lowercase). Security 181 Protecting Communications with SSL Encryption Hardware Security Module (HSM) Private keys may be stored in an HSM instead of a personality file. The SSLD accesses the HSM using Public Key Cryptography Standard (PKCS) #11. The general operation of eTrust Directory with an HSM is as follows: Using supporting tools from the HSM manufacturer: 1. Generate the directory server key pairs and sign a certificate request, using the root certificate. The subject in the certificate must be the directory server name. 2. Export the certificate in PEM format and copy it to the SSLD’s personality directory. Name this file using the directory server name. 3. Start SSLD with the required HSM parameters. The general form of the command is: ssld install When an SSL session occurs, SSLD uses the certificate subject to get a handle for the matching HSM private key, and, when signing is required, this handle will be passed to the HSM. eTrust Directory supports the following HSMs: nCipher nFast/nForce Rainbow HSM, now SafeNet Eracom CSA-7000 and CSA-8000 series Chrysalis-ITS Luna Any later model HSM that supports PKCS#11 182 Administrator Guide Protecting Communications with SSL Encryption How the SSLD Works with Certificates SSLD uses the following types of certificates, which are stored in its configuration directory: Trusted root certificates (“trusted.pem”) that contain one or more certificates of trusted Certification Authorities. Personality certificates that identify the one or more DSAs that are communicating with the SSLD. There is one personality certificate for each DSA (dsaName.pem), and each one contains a private key. The following diagram illustrates this: Directory DSA DB Client Person- SSLD ality Certs HSM Trusted Certs Security 183 Protecting Communications with SSL Encryption How eTrust Directory Works with SSL Binds Unlike other directory implementations, the eTrust Directory DSA handles DAP, LDAP, DSP and DISP protocols through a single port in SSL-encrypted and unencrypted forms. When SSL encryption or decryption is required, the DSA passes the packets to the SSLD to handle the operation. When a client binds to a DSA using SSL, the following happens: 1. If it is not already connected, the DSA connects to the SSLD. Note: If the SSLD is not running or is configured incorrectly, perhaps directed to the wrong port, the DSA refuses the client connection and the bind request fails. 2. The DSA passes all SSL handshaking to the SSLD, which establishes an SSL connection with the client. 3. The DSA uses SSLD to decrypt requests and encrypt responses. The following diagram illustrates this: Directory DB DSA Client 1 2 3 SSLD 184 Administrator Guide Protecting Communications with SSL Encryption Setting Up SSL For eTrust Directory To set up SSL for eTrust Directory you need a root certificate, a DSA personality certificate, and an SSLD instance to service DSA requests. Generate Personality Certificates You must not simply rename the personality files that come with eTrust Directory (for example, from democorp.pem to mydsaname.pem) and edit the subject lines. This text is only a comment, not a certificate: changing the text does not alter the certificate. You must generate a new certificate. To generate personality certificates, you can use one of the following tools: DXcertgen For more information, see DXcertgen Tool in the eTrust Directory Reference Guide Certificate Authority software such as OpenSSL OpenSSL is available from http://www.openssl.org/ (http://www.openssl.org/). You can either build the package from the source code (which requires a compiler) or locate a binary (precompiled) package for your operating system. When you are generating a personality certificate: Make sure that the DSA name in the subject field of the certificate matches the DSA name in the DSA knowledge. For example, for the Democorp DSA, this is 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. Configure a DSA for SSL Operation The DSA needs to know which port the SSLD is using for connections. This is configured in the DSA configuration file (.dxc) in the knowledge directory, as in the following example: set dsa dsaname = { ... ssld-port = port_number ... }; Where port-number is the SSLD port number. If this is not specified, port 1112 is used by default. Security 185 Protecting Communications with SSL Encryption Configure SSLD To work with the SSLD, use the ssld commands, which are described in SSLD Commands in the eTrust Directory Reference Guide. Reset SSLD Parameters The parameters of the ssld start command are stored. This means that even if you stop and restart the SSLD, it continues to use the parameters that you set when you first started the SSLD. For example, if you run the following commands, the logging level set in the first line is not reset: ssld start xxx -debug 9 ssld stop xxx ssld start xxx There are two ways to reset SSLD parameters: Reset the parameter directly You can stop and start the SSLD again, making sure that you explicitly re- set all parameters. For example, to re-set the logging parameter: ssld stop xxx ssld start xxx -debug 0 Install the SSLD again, with the new parameters Another way to reset SSLD parameters is to remove and re-install the SSLD. The installation re-sets the parameters: ssld stop xxx ssld remove xxx ssld install xxx [arguments] ssld start xxx The parameters are stored in the following locations: Windows—The following registry variable : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ssld_instance name\Parameters UNIX and Linux—The ssld_name.args file in $DXHOME/config/ssld 186 Administrator Guide Protecting Communications with SSL Encryption Configure Multiple Threads SSLD can be configured to run more than one instance on each computer. However, we recommend that you use only one instance of SSLD per computer. You should only run one instance of SSLD on each computer. This is because, due to the way Windows allocates TCP ports, SSLD cannot determine if there is another SSLD instance on the same port when it starts up. As a result, two SSLD instances might be running on the same port, with unpredictable results, including Assertion Error messages, SSLD hanging, or refusing to accept new requests. It is not necessary to run multiple instances of SSLD. Instead, use the - threads parameter to set the required number of threads. We recommend that you set the number of threads to twice the number of CPUs, unless you have a large number of CPUs, in which case set the - threads to the number of CPUs plus five. In the following example, the SSLD process uses four CPUs, and is started automatically when the Democorp DSA is started. The certificate and private key files are in the directory DXHOME/config/ssld/personalities, and the trusted Certification Authority (CA) certificate is in config/ssld/trusted.pem. ssld install democorp –certfiles config/ssld/personalities –ca config/ssld/trusted.pem –threads 4 Encrypt LDAP Binds You can force SSL encryption over LDAP links. To force SSL encryption on anonymous binds Use the following command: set force-encrypt-anon = true | false 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. To force SSL encryption on authenticated binds Use the following command: set force-encrypt-auth = true | false 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. Security 187 Protecting Communications with SSL Encryption Specify the Cipher for SSL and TLS Connections You can specify which cipher is to be used for SSL and TLS connections. When you start the server, use the -cipher option, as in this example: ssld start democorp –certfiles config/ssld/personalities –ca config/ssld/trusted.pem -cipher RC4-MD5 For a list of ciphers currently supported, see the section Encryption Formats for SSL in the eTrust Directory Reference Guide. For more information about ciphers, see the OpenSSL home page (http://www.openssl.org/). Enforce Client Encryption A DSA automatically detects an SSL session from an LDAP client or a DAP Directory User Agent (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. To enforce SSL authentication Include the following line in the knowledge file: auth-level = ssl-auth Encrypt DSA-to-DSA Communication (DSP and DISP) To enable a DSA to use encryption when communicating with a remote DSA, set the link flags to ssl-encryption in the knowledge file of the remote DSA. For example, to enable encryption from a Democorp DSA to a UNSPSC DSA, ensure that, in the knowledge, the UNSPSC link flag is set to ssl-encryption. set dsa UNSPSC = … link-flags = ssl-encryption … OP BIND DUA DemoCorp UNSPSC DSA DSA 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. 188 Administrator Guide Protecting Communications with SSL Encryption Configure DXlink to use SSL Encryption DXlink is a feature of eTrust Directory that allows any LDAP-compliant data source to be integrated into the eTrust Directory X.500 backbone infrastructure. To protect sensitive data, you can secure a DXlink connection using SSL encryption. 1. Ensure that you have access to a Certificate Authority. This may be achieved by using OpenSSL, which is freely downloadable. 2. Using your Certificate Authority, produce server certificates for both the LDAP server and the DSA, and sign them with the Certificate Authority's root certificate. 3. Configure eTrust Directory and the LDAP server to trust the Certificate Authority by importing the root certificate. 4. Configure eTrust Directory and the LDAP server to use the server certificate signed by the Certificate Authority for SSL operations. 5. Configure eTrust Directory to connect to the LDAP server by adding the following line to the DXlink knowledge file: link-flags = dsp-ldap, ssl-encryption 6. Start SSLD, start the LDAP server, and start the DSA to test that everything is working correctly. 7. To verify that SSL is being used on the DXlink connection, use the following command in DXlink: trace x500; Security 189 Protecting Communications with SSL Encryption Generating Certificates Using DXcertgen Tool eTrust Directory includes a tool for generating certificates. This section describes how the DXcertgen tool works. For a description of the command syntax of DXcertgen, see the section DXcertgen Tool in the chapter DXtools in the eTrust Directory Reference Guide. About DXcertgen The DXcertgen tool does the following: Reports on currently configured certificates Generates new DSA personality certificates Generates new directory user certificates You can generate certificates for DSAs and users at the same time. If you do this, the user certificates will be generated using the same root certificate's private key as the DSA personalities. The reports generated by DXcertgen show the subject of each certificate, the Certificate Authority who issued it, validity dates and whether the certificate is currently valid. As an additional security precaution against widely available sample private keys, the DXcertgen tool does not write out the private key of the trusted root certificate. DSA personality certificates are stored in the following locations: UNIX: $DXHOME/config/ssld/personalities Windows: %DXHOME%\config\ssld\personalities Write Certificates to a Secure Location When the DXcertgen tool generates user certificates and private keys, it can also write them to a more secure location. To do this, DXcertgen uses the Keytool facility that ships with Java and JXplorer to add the certificates and private keys to a keystore. The keystore is password protected and each private key is password protected as well. The certificates and keys are separated out into "client" or user certificates/keys and CA/self-signed/root certificates/keys. By default, the DXcertgen tool writes the certificates and private keys to the JXplorer keystore, but you can specify other keystores. 190 Administrator Guide Protecting Communications with SSL Encryption Keep the Root Certificate Secure The certificate and private key of the root certificate used to sign all the generated certificates is stored as the following: UNIX: $DXHOME/config/ssld/personalities/dxcertgen.pem Windows: %DXHOME%\config\ssld\personalities\dxcertgen.pem This is not very secure. When you have generated all the certificates, you should archive this file off the network, or write it to a Java keystore similar to the one JXplorer uses. Delete Certificates Where there are multiple certificates in a file, they are numbered in the order they are found. If you have to delete a certificate, use the report to determine which one to delete. How User Certificates Are Generated To generate user certificates and private keys and write them to a more secure location, DXcertgen uses Keytool (which ships with Java) and JXplorer to add the certificates and private keys to a keystore. The keystore is password protected and each private key is password protected as well. The certificates and keys are separated out into "client" or user certificates/keys and CA/self-signed/root certificates/keys. By default, DXcertgen writes the certificates and private keys to the JXplorer keystore, but you can specify other keystores. To generate a user certificate, DXcertgen does the following: 1. DXcertgen generates a root certificate 2. DXcertgen checks that the certificate does not already exist in the following file: UNIX: $DXHOME/config/ssld/trusted.pem Windows: %DXHOME%\config\ssld\trusted.pem 3. DXcertgen appends the new root certificate to this file. 4. DXcertgen uses the root certificate's private key to generate a new personality certificate for each configured DSA, using the DSA-NAME from the knowledge file as the subject of the certificate. Note: Any previous personalities will be overwritten. Security 191 Protecting Communications with SSL Encryption How DSA Personality Certificates Are Generated To generate a DSA personality certificate, DXcertgen does the following: 1. DXcertgen attempts to source a root certificate and private key from the following location: UNIX: $DXHOME/config/ssld/personalities/dxcertgen.pem Windows: %DXHOME%\config\ssld\personalities\dxcertgen.pem 2. If DXcertgen finds no certificate, it generates one. 3. DXcertgen checks the following locations to see if the certificate already exists: UNIX: $DXHOME/config/ssld/trusted.pem Windows: %DXHOME%\config\ssld\trusted.pem 4. DXcertgen appends the new root certificate to this file. 5. DXcertgen uses the root certificate's private key to generate a new personality certificate for each configured DSA, using the DSA-NAME from the following file as the subject of the certificate. UNIX: $DXHOME/config/knowledge Windows: %DXHOME%\config\knowledge Note: Any previous personalities will be overwritten. 192 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?” eTrust Directory 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 DSA. No Authentication Setting no authentication permits any type of authentication (including anonymous). To permit any authentication, use the following command in the initialization script or at the management console: set min-auth = none; Name and Password Authentication To force authentication of at least a name and password, set min-auth to clear-password. This ensures that a user provides a user name and clear-text password or provide a certificate (to be checked using SSL authentication) on a bind. set min-auth = clear-password; Certificate Authentication To force authentication by certificate, set the following command: set min-auth = ssl-auth; Security 193 Authentication Anonymous Authentication When no credentials are provided or only simple credentials are provided without a password (for instance, just a name), then the bind is treated as anonymous. An anonymous bind is accepted only when the minimum authentication level is none. Simple Authentication When a name and password are supplied with the following conditions, the bind is treated as simple. The name corresponds to a real entry in the directory. That entry has a password attribute. The supplied password matches it. The min-auth flag does not include the value ssl-auth. For simple authentication, all users must have corresponding directory entries containing the password attribute. Authentication fails and the bind is refused when: The entry named by the user cannot be found. The entry named by the user name does not contain a password attribute. The password provided does not match the password value of the attribute in the entry named by the user name. When the user does not provide a user name and password or only provides a user name, and if the minimum authentication level is set to “none,” the bind is accepted as anonymous. You can add the password attribute to an object with a remote DUA. When access controls are in force, users can add or change a password only when they have the appropriate privilege, for example: Superuser Administrator of a subtree (only for entries in the subtree and only when the administrator has privileges on the password attribute) Administrators of their own entry Registered user with update permissions on the password attribute 194 Administrator Guide Authentication SSL Authentication SSL authentication has two parts: Establish the SSL connection. Establish the directory connection (using a bind). Establishing the SSL Connection The SSL client provides a certificate with the SSL connection: SSL DemoCorp Client DSA The DSA and SSLD validate 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 195 Authentication Establishing the Directory Connection The SSL client uses the SSL bind procedure. In LDAP, this is known as SASL/EXTERNAL. (In X.500, we use the Bind External Procedure.) This tells the directory to use the certificate from the link layer. 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, the DSA will check the DSA name in its knowledge. To bypass this last check of the certificate's subject DN Use the following command: set ssl-auth-bypass-entry-check = TRUE; This establishes the directory connection. X.500/ LDAP SSL DemoCorp Client SSL DSA Restricted Chaining If a DSA receives a bind request and passes a compare request to a remote DSA, then the compare request will have a chaining-prohibited control set. This prevent the remote DSA from passing the compare request to another DSA and ensures that the compare is only processed by a trusted DSA. If users are storing a hierarchy of DSAs, then it is a good idea for the DSAs to share knowledge so that compare requests can be sent straight to the DSA that contains the entry. 196 Administrator Guide Authentication Overriding Restricted Chaining It is possible for a DSA to override the chaining-prohibited control by setting always-chain-down to true. This can be useful when you want to configure proxy DSAs. For information about proxy DSAs, see Proxy DSAs (see page 159). However, we recommend that you do not override the chaining-prohibited control, because this breaks the trust relationship between DSAs. Bypassing the Entry Check Usually, during SSL authentication, the DSA verifies that the entry exists. This can be bypassed with the command: set ssl-auth-bypass-entry-check = TRUE; In this case, when authenticating the client, the DSA will not check that an entry with a distinguished name matching the subject field in the certificate of the client exists in the directory. Security 197 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 DSA can forward a check to another DSA when certain distributed authentication parameters are set. During simple authentication, the local DSA can forward the password check to a remote DSA only when the local DSA can make an authenticated connection to the remote DSA. The remote DSA must have the correct trust-flags set in the DSA definition. For example, to enable the Democorp DSA to forward a password check on to the UNSPSC DSA, the Democorp DSA must check its knowledge of the UNSPSX DSA. If the UNSPSC knowledge file contains the trust flag allow- check-password, then the Democorp DSA can pass the password compare request to the UNSPSC DSA. set dsa UNSPSC = ... trust-flags = allow-check-password ... bind request compare request Democorp UNSPSC DUA DSA DSA bind response compare response If the DSA receiving the bind request passes a compare request of the password value to the remote DSA, and this returns a compare confirm with assertion true, then the DSA returns a bind-confirm to the user. 198 Administrator Guide Authentication DSP Simple Authentication DSP and DISP binds are subject to the min-auth setting. This means that if the local DSA has enabled authentication, an incoming DSP or DISP bind request must have valid bind credentials. Authenticated DSP binds use mutual authentication. During the bind process, each DSA supplies its own credentials to the other DSA, and each DSA also checks the credentials supplied to it by the other DSA. Credentials Used During DSA Binds An incoming bind is accepted only when there is a DSA knowledge configuration that meets all the following conditions: The distinguished name of the credentials matches the remote DSA name. The password in the credentials matches the remote DSA password. The address of the binding DSA matches the address of the remote DSA. We recommend that the DSAs in a DSP-meshed network share the same group knowledge configuration file so that all the combinations of names and passwords are known to each DSA. For more information about sending credentials with a DSP bind request, see Managing DSP (see page 150). Security 199 Authentication How Mutual Authentication Works This section describes the mutual authentication process. 1. The DSA sending the bind request includes its credentials with the bind request. It gets these credentials from its own knowledge file. 2. The DSA receiving the bind request checks the credentials against its knowledge of the sending DSA. In this example, the UNSPSC DSA receives a bind request from the Democorp DSA, and checks its credentials: set dsa Democorp = ... dsa-name = bind request Democorp UNSPSC DSA DSA 3. The DSA that received the bind requests now sends a bind response back, including its own credentials in this bind response. 4. The DSA that sent the bind request checks the credentials of the other DSA against its knowledge of the other DSA. In the following example, the UNSPSC DSA receives a bind response from the Democorp DSA, and checks its credentials: set dsa UNSPSC = ... dsa-name = Democorp UNSPSC DSA DSA bind response 5. If all the credential checks match, the bind succeeds. 200 Administrator Guide Authentication DSP SSL Authentication To enable SSL authentication between DSAs, the auth-levels flag of the receiving DSA must include the value ssl-auth. If you simply want DSA-to-DSA connections to be encrypted, SSL authentication is unnecessary. Instead, set the link-flags element in the DSA knowledge to ssl-encryption. How DSP SSL Authentication Works This section describes the DSP SSL authentication process. 1. The DSA sending the bind request checks its own knowledge file to determine if it can use SSL. 2. The sending DSA then checks the knowledge file of the receiving DSA to see if it can accept an SSL connection. If it cannot, the bind attempt is aborted. If it can, the DSA sends the SSL bind request. In this example, the Democorp DSA finds the ssl-auth flag in its copy of the UNSPSC knowledge file, so it sends the SSL bind request: set dsa UNSPSC = … auth-levels = ssl-auth … BIND DemoCorp UNSPSC DSA DSA DISP Authentication DISP authentication is controlled by the DISP agreement. For more information, see DISP Agreements (see page 275). Depending on the setting of auth-level in the agreement, the authentication method follows the DSP simple or DSP SSL procedures outlined previously. Security 201 Authentication Bypassing Mutual Authentication In the case of simple authentication, DSAs always exchange name and password if configured. Not all third party DSAs or LDAP servers support the returning of credentials on bind confirm. You can set a trust flag in the knowledge file of the third-party DSA to bypass the return credentials check: set dsa UNSPSC = … trust-flags = no-server-credentials … 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. 202 Administrator Guide Authentication Conveying User Authentication In a networked system of DSAs, a user can bind to a DSA, and then request information that is held on another DSA. You can use the trust-conveyed-originator flag to permit the first DSA to convey the user's authentication to the second DSA. How User Authentication Is Conveyed Between DSAs 1. A user binds to a DSA. The bind request includes the user's DN, and the user's credentials. 2. The DSA authenticates the user. 3. The user makes another request which the current DSA cannot fulfill. 4. The DSA passes the request to another DSA that will be able to fulfill the request. The request includes the user's DN and authentication 5. The receiving DSA must decided whether to trust the user's authentication. To do this, it looks at the knowledge file of the first DSA for the trust-conveyed-originator flag. 6. If the receiving DSA finds the trust-conveyed-originator flag, it accepts the request. Even though the user was authenticated on Democorp, it will be treated as if it had been authenticated on UNSPSC. 7. The receiving DSA uses the DN of the originating user to determine what access controls to apply to the request. In this example, the UNSPSC DSA trusts the user authentication of the request that has been passed to it by the Democorp DSA: set dsa DemoCorp = … trust-flags = trust-conveyed-originator … OP OP UNSPSC DUA DemoCorp DSA DSA Security 203 Authentication DSP Link Authentication Traffic on any link is generally carried at the same security level. That is: High security SSL authentication is carried on an SSL bind Medium security Simple authentication is carried on a simple bind Low security Anonymous authentication is carried on an anonymous bind SSL authentication DSA Simple authentication DSA No authentication Possible Problems with Link Authentication This can present problems if a user makes a successful simple bind to a directory, but is refused any distributed operations because all distributed links have a minimum authentication level of ssl-auth. Similarly, a user might make a successful SSL authenticated bind to a directory, only to be refused distributed operations because the distributed directories cannot support SSL authentication. In either case, the error reported is “No compatible link type.” Possible Solutions to the “No compatible link type” Error One solution is to change the “auth-levels” so that a compatible DSP link can be established. Another solution is to either upgrade or downgrade the trust levels on the link between distributed DSAs. A user who makes a successful simple bind can be upgraded to permit distributed operations over an SSL link; a user who makes a successful SSL bind can be downgraded to permit 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. 204 Administrator Guide Authentication Examples: Upgrading and Downgrading the Link Type The following example demonstrates the upgrade of anonymous bind user on a simple link between a Democorp DSA and a UNSPSC DSA: set dsa UNSPSC = … trust-flags = allow-upgrading … 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 Impersonation Protection DSA authentication is completely separate from DUA authentication. This means that a DUA cannot gain access using the credentials of a DSA, and a DSA cannot gain access using the credentials of a DUA. DSA authentication checks network addresses and credentials. This makes it difficult for one DSA to impersonate another DSA. Security 205 How Password Management Works How Password Management Works Password management rules define how to deal with passwords during operation, including: Life span of passwords Suspending user accounts manually Locking user accounts after incorrect login attempts Resetting passwords Grace logins after the password has expired Password Policies and Rules A policy is a set of rules that defines behavior. In eTrust Directory, you can define a policy for passwords. This password policy controls the password that users enter to bind to a DSA. There are two kinds of password rules: Password quality checking rules Password management rules Password quality checking rules define the quality of a new password. The rules are applied when a user changes their own password. The rules include: Setting the length of the password: Setting the minimum number of particular types or characters: Limiting repetition within the password: Preventing the user from including their own user name in the password Preventing the user from re-using a recent password 206 Administrator Guide How Password Management Works How Password Rules Are Applied Password rules (except vetting checks) are only applied when operations are being performed by the user that owns the password. For example, if an administrator updates the password then no history check will occur. This effectively resets the password. Each DSA can have a single set of password rules. You cannot apply different password policies to users stored within the same DSA. You can apply different policies to different groups of users by splitting the users up by sub-tree and having each sub-tree serviced by a separate DSA. Each DSA can then have its own set of password policies. Password Protection You cannot read passwords directly. An attempt to read a password attribute results in the return of the encrypted value. For more information about encryption algorithms, see Password Storage (see page 65). Passwords are always single-valued. This means that an administrator cannot add a secret value and use this as an unpublished entry point into the DSA. Passwords are encrypted before they are stored in the database. This prevents the possibility of interrogating the database directly for the value of any passwords. Password logins are secure only if each person can change only their own password. Make sure that you set access controls so that each user can update only their own password. Also make sure that administrators are allowed to update any user password. Resetting a Password Whenever an administrator updates a user password, the password policy attributes for that entry are reset. These attributes include: Any password history The time of the last use of the password The time the password was created For example, if password-age is set to 30 days and a user has not logged in for more than 30 days, the administrator can update that user's password to enable that user to log in again. Security 207 How Password Management Works Tracking Password Suspensions You can track how often passwords are suspended for the following reasons: The password is too old The retry limit has been exceeded There are two ways to track password suspensions: Look in the alert log for PASSWORD-SUSPENDED. If the alert log is open and a password policy is active, one of these messages is written to the alert every time a password is suspended. Look in the SNMP log or use an SNMP aggregator. If the SNMP log is open and a password policy is active, you can choose to raise an SNMP trap every time a password is suspended. Some Password Controls Require an LDAP Client Some password controls can only be used with LDAP clients that are aware of LDAP password policy controls (for example, LDUA and the PAM-LDAP client). This section of the eTrust Directory password policy is specified in an Internet Draft on the IETF home page (http://www.ietf.org). It is possible for the specification of its operation to change over time. Also, the name of the draft document will change as revisions are made. At the time of writing, the document name is draft-behera-ldap-password-policy-08.txt. PasswordPolicyResponseValue ::= SEQUENCE { warning [0] CHOICE { timeBeforeExpiration [0] INTEGER (0 .. maxInt), graceLoginsRemaining [1] INTEGER (0 .. maxInt) } OPTIONAL, error [1] ENUMERATED { passwordExpired (0), accountLocked (1), changeAfterReset (2), passwordModNotAllowed (3), mustSupplyOldPassword (4), <== Not required (handled by bind) insufficientPasswordQuality (5), passwordTooShort (6), passwordTooYoung (7), passwordInHistory (8) } OPTIONAL } timeBeforeExpiration and graceLoginsRemaining are provided where appropriate. For example, password policy must be enabled in eTrust Directory. 208 Administrator Guide How Password Management Works Account Management The following command does not require the control but is handy for informing the user: set password-allow-locking = true or false; This feature requires the control: set password-force-change = true or false; LDAP Response Controls eTrust Directory uses two password commands to mimic the non-standard functionality of some other directories. The set password-mimic-netscape-response-controls command adds LDAP response controls about password expiry to bind and compare responses. This mimics the way that Netscape directories work with LDAP password response controls. The set password-age-warning-period command sets the number of days before warnings about the password expiring are added to bind and compare responses. Use this command with the set password-mimic-netscape- response-controls command. For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide. Security 209 How Password Management Works Example Password Policy This section describes a sample password policy, and then lists the commands to create that policy. For this policy, you want to set up the following rules: Passwords can be reused. You do not want to keep a history of old passwords. A password must be at least eight characters in length with at least one numeral. If a user's password is ever reset, you want the user to change the password immediately after their first login. If a password is not used for sixty days, you want the account to be locked. To set up this policy, set the following password rules: set password-policy = true; set password-min-length = 8; set password-numeric = 1; set password-force-change = true; set password-min-age = 60; 210 Administrator Guide How Password Management Works Summary of Password Commands You can use the following commands to manage the password configuration. The default for most values is 0, which means that the option is off: set password-age Command set password-age-warning-period Command set password-allow-ignore-expired Command set password-allow-locking Command set password-alpha Command set password-alpha-num Command set password-force-change Command set password-history Command set password-last-use Command set password-lowercase Command set password-max-repetition Command set password-max-suspension Command set password-mimic-netscape-response-controls Command set password-min-length Command set password-non-alpha-num Command set password-numeric Command set password-policy Command set password-storage Command set password-suspended-trap Command set password-username-substring Command For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide. Security 211 Managing Passwords Managing Passwords This section describes how to use the password commands to create password policies. Enable or Disable Password Management Even if you have other password options set, they will only take effect if you set the password-policy option to true. To enable or disable password management Set the following option: set password-policy = true | false; 212 Administrator Guide Managing Passwords Check Password Quality You can set up rules to make sure that users only choose strong passwords. If you have set rules about password quality, these rules are applied when a user attempts to change their own password. If the new password does not pass the tests, the user will have to try again with another new password. When an administrator changes a password for a user, the password policy rules are not applied. The rules will be applied the next time that the user changes their own password. To set the length of the password Use one or both of these commands: set password-min-length set password-max-length To set the minimum number of types of characters Use one or more of these commands: set password-alpha set password-alpha-num set password-lowercase set password-non-alpha set password-non-alpha-num set password-numeric To limit repetition within the password Use one or more of these commands: set password-max-repetition set password-max-substring-repetition set password-min-length-repeated-substring Note: The password-min-length-repeated-substring option only affects those users whose entries include the attribute maxSubstrRep. To prevent the user from including their own user name in the password Use this command: set password-username-substring = true | false; Security 213 Managing Passwords Set the Life Span of Passwords Use the following commands to control password expirations. Set the Maximum Life Span of Passwords To set the number of days for which a password will remain valid Use the following command: set password-age = number-of-days | 0; To set the number of days a password remains valid if it is not used Use the following command: set password-last-use = number-of-days | 0; If the value is exceeded, the password expires. Example: Making Passwords Valid Indefinitely To make passwords valid indefinitely except when they are not used for 30 days, set the parameters as follows: set password-policy = TRUE; set password-last-use = 30; You do not need to use the set password-age option because you are using its default value of 0 (off). Set the Minimum Life Span of Passwords You can also set the minimum life span of a password. This is the number of days since a password was changed until it can be changed again. You can use this to prevent people from changing their password many times to fill up the password history. To set the minimum life span of passwords Use the following command: set password-min-age = number-of-days | 0; 214 Administrator Guide Managing Passwords Set Passwords to Never Expire Accounts can be made to never expire. This is useful for accounts shared by many users. To set a user's password to never expire 1. Set the password-allow-ignore-expired option to true: set password-allow-ignore-expired = true; 2. Add the attribute dxPwdIgnoreExpired to the user's entry. To check which user passwords are set to never expire Search for all user accounts with the attribute dxPwdIgnoreExpired. You can only find out if entries have this attribute by searching for it explicitly. Set the Number of Grace Logins In a grace login system, passwords expire but users can use an expired password for limited number of times. This gives them the opportunity to change the password. If the number of grace logins is exceeded, the account will behave as if it were expired. The number of grace logins remaining will be sent back to the binding client in the presence of the password policy request control. To set the number of grace logins Use the following command: set password-grace-logins = number-of-grace-logins | 0; Security 215 Managing Passwords Force Password Changes after Reset To force users to change their passwords after their passwords have been reset Use the following command: set password-force-change = true; When a user logs in with their new password, the only operation the user can perform is to change their password. After the user has changed their password, their normal operations are restored. This password control can only be used with LDAP clients that are aware of LDAP password policy controls (for example, LDUA and the PAM-LDAP client). Lock an Account after Incorrect Login Attempts You can set accounts to be locked if someone has made too many unsuccessful attempts to log in. To set accounts to be locked after a certain number of attempts to log in Use the following command: set password-retries = number-of-attempts; To let users attempt to log in again after a certain amount of time has passed Use the following command: set password-max-suspension = time-in-seconds | 0; Example: Limiting the number of login attempts You want to let users try to log in only two times before their account is locked, and you want to let them try to log in again after six hours. To do this, use the following commands: set password-policy = TRUE; set password-retries = 2; set password-max-suspension = 21600; 216 Administrator Guide Managing Passwords Suspend an Account Manually You can suspend a user's account manually by locking their password. You can later remove the suspension, and the user can continue to use that password. Note: This only works with LDAP clients that are aware of LDAP password policy controls (for example, LDUA and the PAM-LDAP client). To suspend a user's account 1. Set access controls as required (see the other sections in this chapter). 2. Enable password locking. To do this, use the following command: set password-allow-locking = true; 3. Lock the user's password. To do this, add the attribute dxPwdLocked to the user's entry. To unlock the account Remove the attribute dxPwdLocked from the user's entry. Do not set the value to 0. If this attribute is present, the account will still be locked. To check which user accounts are locked Search for all user accounts with the attribute dxPwdLocked. The only way to find out if entries have this attribute if you search for it explicitly. Prevent Users from Re-using Passwords To prevent users from re-using passwords, you need to set the maximum number of entries to retain in the history. By default, this feature is disabled (0). To prevent users from re-using old passwords Use the following command: set password-history = maximum-number; To not check new passwords against old passwords Use the following command: set password-history = 0; Security 217 Managing Passwords Raise an SNMP Trap When Passwords are Changed To cause an SNMP trap to be raised each time a password is suspended Use the following command: set password-suspended-trap = true; Notify Clients of Expiring and Expired Passwords eTrust Directory uses two password commands to mimic the way that Netscape directories work with LDAP password response controls. To include LDAP response controls about password expiry to bind and compare responses Use the following command: set password-mimic-netscape-response-controls = true; To set the number of days before warnings about the password expiring are added to bind and compare responses Use the following command: set password-age-warning-period = number-days; For the full syntax of these commands, see DXserver Command Syntax in the eTrust Directory Reference Guide. 218 Administrator Guide Managing Passwords Apply Password Policies to the Password Proxy User Some applications implement password policy by binding as a single user. All password comparisons and modifications are then performed by that user on behalf of all users. This means that if someone binds as a different user for account administration reasons, password checks and changes password policy is ignored. To overcome this restriction a password administration account can be created and included in the set password-proxy-user = DN command. This command specifies the DN of the password proxy user. When an application binds as this password proxy user, the password policy will be applied to password compares and modifications. To apply password policies to the password proxy user 1. Set access controls as required (see the other sections in this chapter). 2. Create an account for the password proxy user. 3. Use the following command to identify this account as the password proxy user: set password-proxy-user = DN; where DN is the distinguished name of the password proxy user. Security 219 Access Control Overview Access Control Overview Access controls protect data from unauthorized access or modification. Access controls work by asking this question before performing an operation: Is this client permitted to perform this operation, on this data, in this subtree, at this time? where: A client is a user, a role, a group of users, or a subtree of users. An operation is one of the usual directory services, including compare, list, search, read, add, remove, modify, or modify-dn. The data (protected item) is an entry, attribute, or attribute value. A subtree is a particular area of the DIT. The time is a particular minute of the day or a particular day of the week. When the answer to this question is yes, the operation can proceed. When the answer is no, the operation is refused. Access Control Policies A number of access controls are usually in place. The net effect is known as an access control policy. By definition, only one access control policy is in place at any given time. An access control policy can have different effects at different times. A single policy could contain different rules for different times of the day or week. For example, a policy can contain one set of rules for business hours and another for after hours To define your access control policy, you define a set of rules access control. During operation, the DSA maps these rules onto the 1993 X.500 access controls. 220 Administrator Guide Access Control Overview Access Control Rules eTrust Directory manages access controls by letting you define rules. There are two types of rules: Static rules These apply to individuals and groups of individuals, and are stored as text files in the DSA configuration files, or run as commands on DXconsole. Dynamic rules These are stored in an attribute in the directory, and can be set by anyone who has the power to delegate the permissions being created. In addition, eTrust Directory lets you define users groups and roles, which can help you apply access controls to many users at once. Important! The 1993 X.500 access controls are not exposed directly; rather they are defined by rules. This is because the 1993 X.500 access controls are difficult to understand and because the definitions of DSA rules are mathematically proven not to have security loopholes. Designing Your Access Control Scheme We recommend that you use these principles while you are developing your access control scheme: Plan your access control scheme before you start implementing it Use domains to limit the range of your access controls Grant access rather than denying access Keep access control schemes simple Plan Your Access Control Scheme Before you start setting access controls, plan your access control scheme. To do this, write your scheme out carefully. Here is an example of a set of access control rules written in plain language: The DSA manager has all privileges. Authenticated users can update their own entries. PABX operators can update all telephone numbers. Public (anonymous) users can view only name, e-mail addresses, and telephone numbers of staff, but they can view anything in the public subtree. Passwords must be invisible to everyone except DSA administrators. Security 221 Access Control Overview Use Domains to Limit the Range of Access Controls A static access control policy can apply to a single DSA, or a group of DSAs that share the same (or have copies of) group configuration files. Sharing the same access control configuration across many (or all) DSAs makes administration easier, and enables access-controlled routing. Grant Access Rather than Denying Access In general, you should grant rather than deny access to data. If you grant access to all data and then deny access to portions of the data, sensitive data that you have protected can become visible inadvertently. For example, when items within a subtree are protected and the root of the subtree (or a parent) is renamed, the protection no longer exists. Any new attributes are also automatically visible, unless specific denials are implemented. Keep Access Control Schemes Simple You should design your access control scheme to be as simple as possible. This might involve re-designing your DSAs. This is important because overly complex access control scheme can lead to the following problems: Security breaches If you define many different groups with different subtrees, you must maintain careful control of valid users and subtrees. If you lose track of valid users and subtrees, this will eventually cause a security problem. Performance Complex access control schemes can result in performance degradation. This is because the DSA may need to evaluate every control for every piece of information returned, depending on the circumstance and privileges of the user in question. 222 Administrator Guide Access Control Overview Working with Access Controls The following sections summarize the ways of working with access controls. For more information about the commands, see the chapter eTrust Directory Commands in the eTrust Directory Reference Guide. Enable Access Controls To enable access controls, follow these steps: 1. Enable access controls using the following command: set access-controls = true; 2. Set static or dynamic access control rules. Clear Access Controls To reset all access controls, use the following command: clear access; Display Access Controls To display the 1993 X.500 access control details, use the following command: get access; For full details of access controls, see the 1993 X.500 standard Security 223 Static Access Controls Static Access Controls Static access controls are applied to individuals or groups of individuals. Overview of Static Access Control Rules This section describes static access controls and how they work Static Rule Components A static access control rule can include the following information: The rule type Which user, groups, or roles it applies to Which area of the directory it applies to What attributes it applies to What additional permissions it gives What authentication level it requires When it applies Because all rules are cumulative, you can define very complex access control polices. Hierarchy of Rules The static access control rules have a hierarchy of power. Here are the rules listed from superior to inferior: Superuser Administrative user Protected item Registered user Public user A superior rule always overrides an inferior user rule. For example, a superuser rule always overrides any administrative user rule. 224 Administrator Guide Static Access Controls Rule Inheritance Rules are inherited: Grants are inherited above If a grant is defined for a given level, then all levels above inherit that grant. For example, if all registered users are granted read/write permission to their password, then superusers and administrative users are granted the same permission automatically. Denies are inherited below If a deny is defined for a given level, then all levels below inherit the deny. For example, if a registered user is denied access to home address, then all public users are denied the same. Running Static Access Control Commands You can run access control commands from DXconsole, or you can include them in a DXserver configuration file (.dxc) in the access directory. If you issue these commands using DXconsole, the commands are not stored in the configuration files. This means that they are only valid for the run-time of the DSA. If you include static access control rules in the DXserver configuration file, they are activated when DXserver is initialized. This occurs when DXserver starts up, and when an administrator reinitializes the system. Generally, you group these files together by using a group configuration file (.dxg), which constitutes an access control policy. You can share policies among a number of DSAs. Security 225 Static Access Controls Setting Up Static Access Controls This section shows the command for setting access control rules, and describes the options you can use with these rules. The command for setting static access control rules has the following format: set rule-type tag = { user-type subtree = DN attrs = attribute-list perms = permission-list auth-level = simple | ssl-auth [ validity = ( start hhmm end hhmm on daystring ) ] }; rule-type Defines the action of this command, with the following possible values: super-user Grants unlimited access to particular users. admin-user Grants read and update privileges to particular users. reg-user Grants read privileges to particular users. public-user Grants read privileges to all users protected-items Protects a subtree, entry, or attribute. tag A human-readable name for the access control rule. user-type Defines the users that this rule applies to, with the following possible values: own-entry A user's own entry user = DN A user's distinguished name role = DN A role's distinguished name 226 Administrator Guide Static Access Controls user-subtree = DN The distinguished name of a user-subtree group = string The name of a predefined group of users subtree Defines the part of the directory to which the rule applies, with the following possible values: entry = DN The distinguished name of an individual entry subtree = DN The distinguished name of a user-subtree attrs = attribute-list The attributes to which you want to limit access. The value attribute-list is a comma-separated list of one or more attributes. You can give the name of an attribute set in place of the attribute names. For more information, see Attribute Sets (see page 122). perms = permission-list The permissions to be applied to this rule type. The value permission-list is a comma-separated list of one or more of the following: read Permits the user to read the defined attributes or entries. The other permission levels all include read access. add Permits the user to add new defined attributes or entries remove Permits the user to delete the defined attributes or entries modify Permits the user to modify the defined attributes or entries rename Permits the user to rename the defined entries all Permits the user to carry out all operations on the defined attributes or entries auth-level Security 227 Static Access Controls Defines the authentication level at which the user must bind, with the following possible values: simple (Default) The user must bind using simple authentication ssl-auth The user must bind using SSL authentication validity Defines the times when the rule applies. If this option is not included, the rule applies at all times. Include the following values: start hhmm The time at which this rule becomes valid end hhmm The time at which this rule is no longer valid on daystring A string that defines the days on which this rule is valid. Each day of the week is represented by a number, starting with 1 for Monday. For example, 45 represents Thursday and Friday. 228 Administrator Guide Static Access Controls 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. Example: Add Superusers The following command defines a single user with superuser privileges across the domain of the Democorp DSA: set super-user “dsa-manager” = { user = Example: Being a Superuser of One's Own Entry The following command gives all users in the domain of this DSA superuser privileges on their own entry from 0800 hours to 1800 hours on Monday to Friday: set super-user “self” = { own-entry validity = ( start 0800 end 1800 on 12345 ) }; When you include this command in an access.dxc file that multiple DSAs source, all users in the domains of those DSAs will have superuser privileges on their own entries. This is the only type of superuser rule that does not grant the user access to all parts of the DSA. Security 229 Static Access Controls Defining Administrative Users Within a specified subtree, you can assign administrator authority to users. Administrative users have read and update privileges over a specified administrative scope. This scope is a subtree, entry, or designated attributes in an entry or subtree. The administrative user can view and update protected items within the administrative scope. Add users to the list of administrative users either as single users, groups of users, roles, or all users in a specified subtree. Note: Administrative user definitions are effective only when you enable access controls. An administrator with access to only selected attributes within a subtree cannot add or remove entries. To define an registered user, use the set registered-user command. For information about using this command, see the eTrust Directory Reference Guide. Defining Registered Users In a specified subtree, you can assign users the authority of a registered user. Registered users have read privileges over a specified scope: a subtree, entry, or the designated attributes in an entry or subtree. Protected items in the scope are invisible. Note: Registered user definitions are effective only when you enable access controls. To define a registered user, use the set registered-user command. For information about using this command, see the eTrust Directory Reference Guide. 230 Administrator Guide Static Access Controls Defining Public Users You can make specific subtrees available to public (anonymous) users. Public users have read-only access to all entries and attributes within the specified public range. This range is a subtree, entry, or the designated attributes in an entry or subtree. Any permission granted to public users is also automatically granted to authenticated users. Protected items within the specified public range are invisible to public users. Note: Public user definitions are effective only when you enable access controls. To make public ranges available to public users, use the set public-user command. For information about using this command, see the eTrust Directory Reference Guide. Security 231 Static Access Controls Protecting Items You can protect specific subtrees, entries, or particular attributes in a subtree or entry. For a protected item: Superusers have read and update privileges Administrative users have read and update privileges if the subtree is in the user's administrative area Other users do not see the items To set protected items, use the set protected-items command. For information about using this command, see the eTrust Directory Reference Guide. Protecting Entries and Subtrees There is a subtle difference between protecting entries and protecting subtrees. When you protect an entry, neither a registered, nor public user can read it. It can, however, appear in a list result if the user can access the parent. This occurs because the protected entry may have subordinates that are visible to the user. If the same entry has protection as a subtree, a registered or public user cannot read it, and it does not appear in a list result as a subordinate entry. Protecting Passwords Protecting a password makes the password attribute invisible to unauthorized users. Because authentication requires the name of an entry, and that entry must contain a password, hiding the password makes login entries indistinguishable from other entries. 232 Administrator Guide Dynamic Access Controls 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 the command set database=database-name) before the directory reads the command set dynamic-access-control=true command. This is because the set dynamic-access-control=true command causes the directory to perform a search on the database, so it needs to know the database name. Note: Dynamic access controls are limited to local DSAs, which means that they cannot be used in a distributed environment. This even applies to a router DSA on the local computer. Dynamic rules apply downwards from the entry in the DIT where the dxDynamicAccess attribute is stored. Enabling and Disabling Dynamic Access Controls To enable dynamic access controls 1. Enable access controls: set access-controls = true; 2. Enable dynamic access controls: set dynamic-access-control = true; To disable dynamic access controls Enter the following command: set dynamic-access-control = false; Security 233 Dynamic Access Controls Dynamic Access Control Rules The rules governing dynamic access controls take the following form: tag {all| roles dn| user dn} {read | write | deny} attr… tag An identifier used for documentation purposes dn A distinguished name attr An attribute When creating rules, remember that a rule specified for a particular user prevails over one specified for a role, and that both prevail over all. Also, when creating the rule, the user or role need not exist. Example: Letting all read one attribute The following command gives everyone permission to read the commonName attribute. The tag Joe is to help you with maintenance and problem analysis; the DSA does not interpret it. Joe all read commonName Example: Letting all read all attributes The following command gives everyone permission to read all attributes: Joe all read all Example: Denying permission for roles to read an attribute The following command denies the roles of CEO and AdminFinance within Democorp access to the ssoHelicopter attribute: Joe role cn=ceo,o=Democorp deny ssoHelicopter Example: Letting one user write to an attribute The following command lets a user with the common name Craig write to the ssoHelicopter attribute: Joe user cn=Craig,o=Democorp write ssoHelicopter 234 Administrator Guide Groups, Roles, and Proxies Groups, Roles, and Proxies This section describes how groups, roles, and proxies work. Defining Groups of Users You can define groups of users to make it easier to manage those users. Define groups such that you can use it in other access control commands. Note: Group definitions are effective only when you enable access controls. The command has the format: set group tag = { users = DN1 [, DN2 …] name = GroupName }; users A list of the distinguished names of one or more users in the new group name The name you give to the group. Example: Forming a Group The following command defines a group containing two users. The group is named admin-user-group, suggesting that the users have administrative user privileges. set group = { name ="admin-user-group" users = Security 235 Groups, Roles, and Proxies Role-Based Access Controls When access control rules are applied to a role, they are known as role-based access controls. A role is a directory entry that can be associated with user entries. These associated user entries are member entries. A role may contain any number of members. This can be useful in a large distributed directory environment where people change their roles frequently, and when the directory is to be used as an authorization engine. Both static and dynamic rules support roles. Roles are maintained in a subtree of the directory information tree (DIT), using the object class groupOfNames. You can control access to the role subtree using access controls. How Role-Based Access Controls Work When role-based access controls are in use, the following happens when a user binds to a DSA: 1. A user binds to a DSA. 2. To verify the user's credentials, the DSA searches the role subtree for the user's distinguished name in the member attribute of any entry with the object class groupOfNames. 3. The DSAs stores the name(s) returned by this search as the roles pertaining to the connection, and uses them in access control decisions. 236 Administrator Guide Groups, Roles, and Proxies How Role-Based Access Controls Work in a Router System A router DSA can be set to perform role lookups using its own credentials. The roles DSA must contain an access control rule that gives the Router DSA access to the role subtree. This means that when a user connects to a local DSA and the password is confirmed, the DSA looks up the user's roles without bypassing access controls. The following diagram shows how a client application binds to a router DSA. This router DSA does not contain the users or the roles, so it must check these in other DSAs. Set up Role-Based Access Controls To activate role-based access controls, include the following commands in the DSA's configuration: set role-subtree = dn; set use-roles = true; where dn is the distinguished name of the subtree used to store the roles. Security 237 Groups, Roles, and Proxies Example: Activate Role-Based Access Controls The following commands activate role-based access controls for the Democorp DSA: set role-subtree = When a user binds to the Democorp DSA, the DSA searches the member attribute of the entries with oc in the groupofNames in the subtree c=au, o=Democorp, ou=Roles for that user's distinguished name. The entries which contain that member identify the roles of the member. Set Up Role-Based Access Controls in a Router DSA You can allow a router DSA to compare passwords and look up roles using its own credentials. To set up role-based access controls 1. Include the following command in the router DSA's configuration: set check-roles-with-dsa-credentials = true; 2. Include permission to read the section of the DIT that includes the roles in the router DSA's configuration. 238 Administrator Guide Groups, Roles, and Proxies Example: Configuration for Role-Based Access Control in a Router System The following diagram shows a distributed directory in which users and roles are handled by separate DSAs: The Router and Roles DSAs include the following commands in their configuration: clear access; set access-controls = true; set role-subtree = set reg-user = { user = Disable Role-Based Access Controls To disable role-based access controls, enter the following command: set use-roles = false; Security 239 Groups, Roles, and Proxies Add a User Entry to a Role To add a user entry to a role, add the DN of the user entry to the role entry, as an attribute value of the member attribute type. Example: Add a New Role with Two Users This example shows how to add the new role AdminFinance with the two members, Noelene Correa and Linda Deacon. add-entry-req entry = 240 Administrator Guide Groups, Roles, and Proxies Secure Proxies The secure proxy feature lets an authorized user (or process) impersonate a user or role for whom it has responsibility, and bind to DXserver to elicit access control decisions (for example, when the directory is used as an authorization engine, such as a web server). The proxy must bind to DXserver using certificate-based authentication. Those users permitted to proxy (impersonate someone else) are identified to DXserver as a list of distinguished names held in the trust-sasl-proxy list. When using a proxy, the impersonating user can never obtain more power than they already have. In other words, in assuming the identity of another user, they may not obtain all the privileges of that user. Once bound to DXserver, the proxy may change identity by changing the value of dxProxyUser in the entry cn=roles to the distinguished name of the new identity. This has the effect of evaluating the roles for the new identity. An exception is, where the proxy also changes the value of dxProxyRole in cn=roles. In this case, roles are taken directly from the attribute value, not by accessing role entries in the directory. The entry cn=roles is a magic entry, and does not appear in the DIT. To permit the proxy to impersonate users not in the directory (external users), the proxy replaces the value of the dxProxyUser attribute in the magic entry with the distinguished name of the new identity, and at the same time replaces the value of the dxProxyRole attribute with the roles of the new identity. In this instance, the roles provided in the replace operation are used directly, provided set ssl-auth-bypass-entry-check = true; Activate Secure Proxy To activate proxy access, enter the following command: set trust-sasl-proxy = dn, … where dn is the distinguished name of a trusted proxy. The proxy must bind using SASL/EXTERNAL over SSL. Security 241 Groups, Roles, and Proxies 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. 242 Administrator Guide Access-Controlled Routing Access-Controlled Routing This section describes how access controls work in a distributed environment. If the DSA determines that it needs to chain or multicast an operation to a remote DSA but the area controlled by that DSA is completely invisible because of static access controls, the DSA refuses to route the request to the remote DSA. By default, a DSA prevents the forwarding of a request to another DSA according to its static access controls. To permit the forwarding of a request regardless of access control constraints, set the no-routing-ac DSA flag in the configuration file (.dxc) in the knowledge directory. This lets a DSA pass a request to another DSA even when the user's access controls on the local DSA do not permit access to the particular entry or subtree in the request. For example, to let a Democorp DSA pass a request to a UNSPSC DSA regardless of the user's local static access control constraints, you must set the DSA flags in UNSPSC's knowledge configuration: set dsa UNSPSC= … dsa-flags=no-routing-ac … DemoCorp UNSPSC DSA DSA Security 243 Chapter 7: Replication This section contains the following topics: Replication Concepts (see page 245) About Multiwrite Replication (see page 250) Work with Multiwrite Replication (see page 266) DISP Replication (see page 274) Manually Synchronizing Replicas Using Database Tools (see page 283) Replication Concepts This section describes some important concepts about replication. These concepts are used in explanations of the three different types of replication that you use with eTrust Directory. In a replicated directory, information stored in one part of the directory is also stored elsewhere as one or more copies. Replication involves copying data, and whenever data is copied, you must ensure that the copies are synchronized. Developing and maintaining replicated systems can be expensive, and you should weigh these costs against the benefits of performance and recovery in the event of failure. Compare Distribution and Replication Distribution differs from replication. In a distributed directory, each piece of data is stored on only one server. The directory information tree (DIT) is split and each section is stored on a different server. In a replicated directory, each piece of data is held on more than one server. The entire DIT is stored in more than one place. You can use both replication and distribution in the same system. The DIT is split and stored in many different servers, and at least some sections of the DIT are also copied and stored in more than one place. Replication 245 Replication Concepts Benefits of Replication Replication is deployed for one or both of the following reasons: Improved availability Replication can make a system more robust by enabling the directory on one server to failover to an alternative server. Applications can continue working as there are alternate DSAs or servers in the network which can serve the same parts of the namespace. Improved performance Replication can place frequently accessed information closer to where it is needed, which improves response times. Compare Multimaster and Master-Slave Replication In a system with multimaster replication, all DSAs are masters. Data is copied between all DSAs. Master DSAs are also called peer DSAs. In a system with master-slave replication, data is always copied in one direction, from a master DSA to one or more slave DSAs. Read and Update Read and Update Read and Update Requests Requests Requests Master DSA Master DSA Updates Master DSA Updates Updates Update Update Update Master DSA Slave DSA Slave DSA Slave DSA Read and Update Requests Multimaster Replication Master-Slave Replication 246 Administrator Guide Replication Concepts Compare Real-Time and Write-Behind Replication In a system with real-time replication, data is replicated to other servers as soon as an update request is received from a client. The update confirmation is not sent to the client until each of the slave or peer DSAs has sent an update confirmation message. In a system with write-behind replication, data is replicated periodically, independent of the client update. The update confirmation is sent as soon as the operation completes locally. Write-behind replication can happen in these two ways: On-demand write-behind replication The updates are transferred immediately after they occur. Scheduled write-behind replication The updates are transferred according to a periodic schedule. In a system with multiple servers, a non-master server is also known as a backup or shadow server. Latency describes the time during which the shadow servers are out-of-date with respect to a master server. For many applications, such as an authentication service, any latency is unacceptable. To overcome the problem of latency, use a real-time replication system rather than write-behind replication. Replication 247 Replication Concepts Compare Replay-Based and State-Based Replication In a replay-based system, every update applied to a master is subsequently applied to the slaves. This system is simple and can operate in real time, but it is not robust when something goes wrong with the replay or when conflicting updates occur in a system with many masters. In a state-based system, a difference is calculated between the current state of the master system and the most recently stored state of the slave system. The calculated difference between these two states is then sent across to update the slave. If conflict resolution is built-in, then this mechanism can also reconcile a system with many masters. A state-based system deals very efficiently with repeated updates. For example, even if an entry were modified 100 times since the last update, only one update is transferred. In a replay-based system, 100 updates would be sent. However, state-based systems are not usually designed to operate in real time. The following table summarizes the two systems: Replication Type Advantages Disadvantages Example Replay-based Simple Poor recoverability Multiwrite Can be real-time State-based Efficient Cannot be real-time DISP High recoverability 248 Administrator Guide Replication Concepts Three Types of Replication Used with eTrust Directory eTrust Directory supports three standards-based methods of replication: Replication Characteristics Most Suitable Deployment Scheme Multiwrite Multimaster Where network links, computers, and Real-time power supplies are reliable Simple configuration High performance Replay-based DISP Master-slave Where interoperability is required with Write-behind another vendor's X.500 directory High flexibility State-based DXtools Batch mode Where synchronization is required High traceability between two directories or with a legacy system Keep System Clocks Synchronized eTrust Directory replication relies on synchronized system clocks on each directory system to perform collision resolution. The product does not provide time synchronization software. It is the responsibility of the directory or system administrator to implement time synchronization using their preferred product. Time information is recorded in GMT to cater for systems running in different time zones. For any replication system, you should synchronize the operating system clocks regularly. If the system clocks are not set to the same time, replication will not work as you expect. Conflict resolution is time-based: the most recent update wins. Replication 249 About Multiwrite Replication About Multiwrite Replication Multiwrite replication is a good choice for a system that includes applications requiring real-time replication. Multiwrite replication uses the fast and efficient Directory System Protocol (DSP) to chain updates between servers in real time. To use multiwrite replication successfully, your network links, computers, and power supplies should be reliable. Important! Treat system crashes and unreliable networks as disaster scenarios. Recovery will require manual reconciliation between databases using DXtools. 250 Administrator Guide About Multiwrite Replication How Multiwrite Replication Works You can configure DSAs into multiwrite groups. When an update is applied to a DSA belonging to a group, it passes the update on to the other DSAs in the group. Multiwrite replication uses DSP chaining to apply updates to all replication peers in real time. When a client makes an update request, that update is applied immediately to the local DSA, and then to all other DSAs. The client receives a confirmation response only after all DSAs have successfully applied the update. The following diagram shows these steps: 1. Write to self. A client sends an update request to DSA1, and this DSA applies the update to itself. 2. Write to peers. If the local update succeeds, DSA1 sends the request to its peer DSAs. If these updates succeed, the peers send confirmations to DSA1. 3. Send response to client. When DSA1 has received confirmation from each peer, it sends the confirmation response to the client. 2 2 1 2 Client DSA 1 DSA 2 DSA 3 3 2 1 1 22 22 Update Request Update Confirmation Database Database Database 1 2 3 When a multiwrite update fails, the system must be recovered. See Recover a Multiwrite System Using Queues and Recover a Multiwrite System Using DISP (see page 257). Replication 251 About Multiwrite Replication How Asynchronous Multiwrite Replication Works Multiwrite is usually synchronous: an update operation is not confirmed until all the multiwrite peers have applied it. This provides for load-sharing and failover. However, this synchronous behavior may be undesirable if peer DSAs are connected by slow links, or if latency is an issue. If a DSA is set to multiwrite asynchronously, the other DSAs in its group will not hold up the confirmation on account of this DSA. Confirmation is returned once all the multiwrite peers not marked multi-write-async have applied the update. This is very useful if you have some unlimited-cache DSAs and some non- cache DSAs, all working with the same database. In this situation, set the cache DSAs to use asynchronous multiwrite replication for unlimited cache DSAs. This allows updates to proceed on the database writer DSAs without waiting for the busy cache DSAs, and let any cache DSAs that are not swamped handle the remaining searches. If all the cache DSAs are swamped then failover will occur to the database writer DSAs, which is desirable in this scenario as it provides continuity of service. To set a DSA to multiwrite asynchronously, add the DSA flag multi-write-async to the DSA's knowledge. For information about knowledge flags and files, see Knowledge Flags (see page 108). 252 Administrator Guide About Multiwrite Replication How Multiwrite Groups Work In a system that includes at least one slow network link between DSAs, delays caused by this slow link can slow down the whole multiwrite system. Multiwrite groups let you avoid delays due to a slow network link. How a Slow Network Link Causes Delays A single slow link can delay a multiwrite system because the DSA making the update must wait for confirmation from all DSAs before sending confirmation back to the client. This can cause a bottleneck if many updates are made each second. The following diagram shows a multiwrite system in which three of the DSAs are connected by slow network links. In this system, DSA 1 must wait until it has received confirmation from these three DSAs before it can send the update confirmation back to the client. From the client's point of view, each update takes much longer than it should. DSA 2 DSA 3 2 2 1 Client DSA 1 2 DSA 4 3 2 2 Update Request DSA 6 Update Confirmation DSA 5 Slow Network Link Replication 253 About Multiwrite Replication How Multiwrite Groups Avoid Bottlenecks To avoid delays due to slow network connections, you can put the DSAs on each side of a slow link into separate groups. Each group has one hub DSA. This is the DSA that will accept multiwrite requests from DSAs in other groups. Multiwrite Group C DSA 9 5 Multiwrite DSA 8 Group A 5 DSA 10 (Hub) DSA 2 DSA 3 5 4 DSA 11 2 2 DSA 1 4 1 3 DSA 5 5 Client DSA 4 5 DSA 6 (Hub) 5 Multiwrite DSA 7 Group B 254 Administrator Guide About Multiwrite Replication The diagram shows these steps: 1. Write to self: A client sends an update request to DSA1, and this DSA applies the update to itself. 2. Write to peers in group: If the local update succeeds, DSA1 sends the request to its peer DSAs in the same multiwrite group. If these updates succeed, the peers send confirmations to DSA1. 3. Send response to client: When DSA1 has received confirmation from each peer in its multiwrite group, it sends the confirmation response to the client. 4. Write to hub DSAs in other multiwrite groups: DSA1 sends the request to the hub DSAs in each of the other multiwrite groups. 5. Hub DSAs write to peers: Each hub DSA sends the request to the other DSAs in its group. When each hub DSA has received confirmation from each peer in its multiwrite group, it sends the confirmation response to the first DSA. The client confirmation will not be affected by the slow links, because the updates over these links are asynchronous. Multiwrite Hub Failover If an update sent to a hub fails because the hub DSA cannot be reached, then the DSA tries the next hub in the list. If all hubs fail, then the update will be queued against the first hub DSA. This DSA takes care of queuing for the offline DSAs. Replication 255 About Multiwrite Replication How Multiwrite Recovery with Queues Works With multiwrite replication, you can choose between two methods of recovery: queues or DISP. This section describes queue recovery. Multiwrite DSAs are usually online. If one of the DSAs in the group goes offline, any updates are queued in memory until the DSA becomes available once more. After queuing, a confirmation is sent to the directory client. In effect, multiwrite reverts to a write-behind scheme until the offline DSA becomes available. Important! A queued update is stored in memory only and will be lost if the master DSA has to be restarted. For this reason, multiwrite queues should not be used if the system may become unstable. 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 were 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, the peer DSA ignores the unavailable DSA. It discards all the queued requests for the unavailable DSA and drops it from the multiwrite set. To bring this DSA back into service, you must resynchronize the databases and restart the DSAs. If a DSA has attempted a multiwrite operation, the get dsp command returns one of the following statuses: Failed Indicates that the multiwrite DSA is not responding to an update. Updates for that DSA are held in the multiwrite queue until the DSA responds. The queue is retained until the multiwrite queue size is exceeded. Recovering Indicates that the DSA has become available and still has old updates in its queue. OK This is the normal multiwrite DSA status. 256 Administrator Guide About Multiwrite Replication How Multiwrite with DISP Recovery Works This section describes how DISP recovery works. When the set multi-write-disp-recovery command is set to true, offline multiwrite queuing is disabled. 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 calculating and sending an update for the period in which the DSA was offline. While this is occurring, any further 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 257 About Multiwrite Replication Benefits of DISP Recovery Enabling DISP recovery generally avoids manual resynchronization of the databases. DISP recovery works with multiwrite replication by handling all recovery operations. In effect, fast multiwrite is used during uptime and DISP is only used for recovery after a downtime. DISP recovery has the following advantages: Database tables Updates are calculated from the original database tables, not queued in memory. This means that recovery can survive restarts of a master (whereas you can lose the in-memory queues). State-based Resynchronization uses state-based updates. This is more efficient than replay-based recovery. Reconciliation 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! DISP recovery uses the highest available authentication level. Specify the ssl-auth authentication level only if you have set up the necessary SSL certificates for the DSAs in the multiwrite group. Note: Multiwrite-DISP recovery cannot be used where more than one DSA is attached to the same database. Queuing Multiwrite-DISP A multiwrite master typically replays its queue content to any peer that has been unavailable for a while. However, if the set multi-write-disp-queue command is set to true, a multiwrite master will only start DISP recovery after it has been down or if its multiwrite queues have reached their limits: set multi-write-disp-queue = true | false; 258 Administrator Guide About Multiwrite Replication Consistency During Recovery If a DSA goes offline in a multiwrite-DISP system and the set disable-non- peer-binds command is set to true, only binds from multiwrite peers are allowed. This stops the recovering DSA from receiving non-peer (client, relay, router, or chained) requests that may provide inconsistent results. When a DSA comes online, check that the DSA has been synchronized. Use the get dsp command, or use an SNMP client to check when the multiwrite queues have complete. When the DSA is fully synchronized, change this setting back to false. The DSA will accept binds after a few minutes. To guarantee consistency during recovery Add the following command to the DSA config: set disable-non-peer-binds = true | false; Granularity of DISP Reconciliation When DISP resynchronization starts, it propagates all changes to the DSA since the last successful multiwrite update. In a multimaster system, some changes might 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, if 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, which does not have the changes to the surname. Replication 259 About Multiwrite Replication Maintaining Data Integrity During Recovery When a DSA in a multiwrite system goes offline, its peer DSAs may receive update requests. This means that when the DSA comes back online, it is out- of-date. If a client queries the DSA, the data may be incorrect. To avoid this problem, you should apply the DSA flag no-service-while- recovering to all peer DSAs in a multiwrite system. When this flag is included in a DSA's knowledge, that DSA will always start in recovery mode. A DSA in recovery mode has been offline and its data is now inconsistent with its replication peer DSAs. In recovery mode, a DSA only accepts binds and updates from its replication peers. This prevents clients and parent or non- peer DSAs from querying or updating the recovering DSA. A DSA in recovery mode has a list of the peer DSAs that have more up-to-date data. When the data in a recovering DSA has been synchronized with one of these peers, it is removed from the list. When the list is empty, the DSA is recovered and returns to service. 260 Administrator Guide About Multiwrite Replication Example: How Recovery Works This diagram shows how a DSA in simple multiwrite system recovers. Stage A In a functioning multiwrite system, a single router DSA passes client requests to two data DSAs, which replicate any changes to each other. Stage B DSA 2 goes offline. When the client makes an update request, the following happens:. 1. The Router DSA passes the update request to DSA 1. 2. DSA 1 makes the update to itself and queues the update for DSA 2. 3. DSA 2 is now out-of-date. Stage C 1. DSA 2 comes online again. 2. DSA 2 starts up in recovery mode. In recovery mode, DSA 2 receives binds only from its peer, DSA 1. 3. When DSA 1 finishes sending queued updates to DSA 2, it also sends a notification that the data is synchronized. This switches DSA 2 out of recovery mode, returning it to service (Stage A). Replication 261 About Multiwrite Replication How Multiwrite Replication Works with Cache DSAs If you have a shared database and are using cache DSAs to improve search performance, you can still take advantage of multiwrite replication. You can configure updates to be sent directly to the cache DSAs by applying the multi-write-notify DSA flag to the cache DSAs. When a multiwrite update is received, the cache DSAs will be updated without changing the shared database. At least one DSA in the multiwrite group must be configured such that the database continues to be updated and synchronized. For more information about caching, see Cache DSAs (see page 67). 262 Administrator Guide About Multiwrite Replication How Multiwrite Replication Works with Third-Party Servers When using multiwrite to replicate to non-eTrust Directory X.500 or LDAP servers, set multi-write-serial to true, especially when replicating the construction of a DIT structure. If multi-write-serial is set to false (the default value), the following sequence of requests may cause an error: add entry a add entry a-b In this example, the request to add the second entry is sent before the first operation is complete. Some servers might attempt to perform the second operation immediately, causing the following error for the parent entry: entry does not exist A similar problem would arise if you were to add an entry, and then immediately modify that entry. If a third-party server to which you are replicating reports an error in these circumstances, then set multi-write-serial to true. If you plan to replicate to a third-party server, you might test for this problem in advance. Use both multi and single CPU machines for testing, if possible, as they may return different results. To perform the tests: 1. Stop the third-party server. 2. While the third party server is down, construct a DIT, or modify an entry just after it has been created, or both. 3. Start the third-party server. 4. Check that all operations have completed successfully. Note: There is a performance penalty for setting multi-write-serial. Replication 263 About Multiwrite Replication Example: Multiwrite Replication The diagram shows the effective combination 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 particular data DSA when the base object of the query, that is the point from which the query starts, falls within the subtree of that DSA. You could configure the system shown in the preceding diagram to have the immediacy of the multiwrite replay system with the recoverability of the state- based system. In this case, DSP would be used to chain requests in real time to peer or slave DSAs while DISP might be used to recover requests if any DSAs are restarted. 264 Administrator Guide About Multiwrite Replication The system shown in this diagram has the following properties: Read operations are load-shared The load of the read, list, search, compare operations is shared between the two machines according to the order that the DSAs are defined. By making use of both machines, you can double the system throughput. Write operations occur in real time using multiwrite The modify, rename, add, delete operations happen in real time, which ensures that both machines are synchronized at the time the update confirmation is sent back to the client. If a data DSA shuts down, the router redirects queries The primary router (R1) can automatically redirect or retry any queries sent to a data DSA (RO1, RW1, RO2, RW2) that unexpectedly shuts down. When this DSA returns to operation, it is automatically resynchronized. Client applications fail over If either Computer 1 or the R1 DSA shuts down unexpectedly, the client application fails over to the backup router (R2). If the client retries (to R2) any queries outstanding (on R1), then there is no possibility of the system losing transactions. This table summarizes the configuration: DSA Function Prefix DSA flags R1, R2 Router DSA RO1, RO2 Read DSA RW1, RW2 Read/Write DSA Replication 265 Work with Multiwrite Replication Work with Multiwrite Replication This section describes how to work with a multiwrite replication system. Set Up a Multiwrite System You can set up a multiwrite replication system in many different configurations, including master-slave, primary-backup, multimaster, or multiwrite groups. You can also use other DSA flags to support load balancing and query streaming. Enable Multiwrite Replication To enable multiwrite replication 1. Decide which DSAs will be included in the multiwrite system. 2. Configure these DSAs with the same context prefix. 3. Connect each DSA to a database holding synchronized information. 4. Set each DSA to share the same knowledge information. 5. Add the DSA flags multi-write and no-service-while-recovering to the shared knowledge, as follows: set dsa dsaname = { ... dsa-flags = multi-write, no-service-while-recovering ...... }; Note: Place DSA flags after dsp-idle-time and before any trust and link flags. 266 Administrator Guide Work with Multiwrite Replication Set Up a Multiwrite Group To set up multiwrite groups 1. Decide which DSAs will be included in the multiwrite system. 2. Decide how many multiwrite groups you need, and which DSAs will be grouped together. 3. For each group of DSAs, choose a hub DSA. 4. Configure all DSAs with the same context prefix. 5. Connect each DSA to a database holding synchronized information. 6. Set each DSA to share the same knowledge information. 7. Add the multi-write DSA flag to the shared knowledge: set dsa dsaname = { ... dsa-flags = multi-write, ...... }; 8. In the knowledge for each DSA, define the multiwrite group: set multi-write-group = group-name; Define the Hub DSA for a Multiwrite Group To set a DSA as the hub for a multiwrite group, put it first in the list of DSAs in the knowledge group file (.dxg). Set the Retry Interval If a DSA fails to bind with a multiwrite peer at the first attempt, it tries again. By default, the interval between tries is 60 seconds. To set a different interval between attempts to bind to an unresponsive DSA Add the following command to the DSA knowledge: set multi-write-retry-time = Replication 267 Work with Multiwrite Replication Send Multiwrite Updates to an LDAP Directory You can use multiwrite replication to take updates applied to an eTrust Directory and replicate them to an LDAP server. To forward all updates on an eTrust Directory server to an LDAP server Include the following line in the knowledge of the LDAP server: dsa-flags = multi-write Send Multiwrite Updates to a Cache DSA To send multiwrite updates to a cache DSA Include the following line in the knowledge of the cache DSA: dsa-flags = multi-write-notify 268 Administrator Guide Work with Multiwrite Replication Work with Multiwrite DSAs Use the following procedures to work with multiwrite DSAs. Display Multiwrite Status of a DSA The get dsp command shows the current DSP configuration values of the DSA. The output of this command displays the following, if they exist: Multiwrite queues Recovery notification list The value of the set wait-for-multiwrite command To display this data 1. Use DXconsole to connect to the DSA. 2. Enter this command: get dsp; Prevent a DSA from Stopping if It Has Multiwrite Queues If you stop a DSA that has multiwrite queues, those queues are lost. This means that you could lose data. If the set wait-for-multiwrite command is set to true and you attempt to use dxserver stop to stop the DSA, the DSA stops processing but it does not exit if it has multiwrite queues. If it has no multiwrite operations queued, or if the queues have now drained, the dxserver stop command succeeds. To prevent any multiwrite queues from being lost when the DSA stops Add the following command to the DSA configuration: set wait-for-multiwrite = true; To check if this command is set, use the get dsp command. For more information, see the chapter eTrust Directory Commands in the eTrust Directory Reference Guide. Stop a Multiwrite DSA Immediately To stop a DSA immediately, regardless of the state of its multiwrite queues Use the following command: dxserver forcestop dsaname Replication 269 Work with Multiwrite Replication Stop a Multiwrite DSA from Telnet To shut down a DSA from a Telnet session, you would usually use the following command: shutdown; If the DSA has multiwrite queues, the shutdown command causes it to stop processing, but continues to clear its multiwrite queues. To shut down a DSA even though it has multiwrite queues Use the following command from a Telnet session: force-shutdown; Stop a Database for Maintenance To prevent the loss of multiwrite data sent from master to slave (which is held in memory), when the slave DSA is stopped: 1. Set the master to read-only, using the following command: set read-only = true; 2. Wait a few seconds for the queues to empty. 3. Stop the slave DSA that requires maintenance. 4. Once the maintenance is completed, restart the slave DSA. 5. Turn off the read-only setting on the master: set read-only = false; 270 Administrator Guide Work with Multiwrite Replication Work with a Multiwrite System with Queue Recovery This section describes how to work with DSAs in a multiwrite system that uses queues for recovery. Increase the Queue Size The queue pool has a default size of 200 updates for each peer. You can gauge the required size from, for example, the number of updates in your LDIF file. To change the queue pool size Use the following command: set multi-write-queue = queue-size; where queue-size is the size of the update queue View the Size of a Multiwrite Queue To view the current size of the multiwrite queue, add the following command to the DXI initialization file: get dsp; Example: Output from the get dsp Command max-dsp-ops = 100 local-prefix = Replication 271 Work with Multiwrite Replication Work With Multiwrite-DISP DSAs This section describes how to work with DSAs in a multiwrite system that uses DISP recovery. Enable Multiwrite-DISP To turn on multiwrite with DISP recovery Add the following command to the DSA knowledge: set multi-write-disp-recovery = TRUE; Add a Database Replica to a Multiwrite-DISP System To add a database replica to a multiwrite-DISP system 1. Create another database containing the same data as the source. To do this, follow the instructions in Manually Synchronizing Replicas Using Database Tools (see page 283). 2. Create a new peer DSA that will use the new populated database. 3. Change the DSA flags in the knowledge file to contain the multi-write flag for both the source and target DSAs. 4. Use the dxdisp -clear command for all multiwrite DSAs running multiwrite DISP recovery, that is, where multi-write-disp-recovery is set to 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 DSA's internal database tables. When the Source DSA starts, it sets this time to the Source DSA's startup time and then only sends DISP updates containing changes since that time. 5. Start the source and target DSAs. 272 Administrator Guide Work with Multiwrite Replication Remove a Database Replica from a Multiwrite-DISP System To remove a replica from a multiwrite-DISP system 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 tool. For example, if Apple, Banana, and Pear are DSAs in a replication set and you remove the Pear DSA, issue the following commands: On the system running the Apple DSA: dxdisp -clear Pear AppleDB On the system running the Banana DSA: dxdisp -clear Pear BananaDB Replication 273 DISP Replication DISP Replication eTrust Directory 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 X.500 defines a master-slave replication scheme using 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. Configuring a DISP Initiator or Responder To configure for DISP, include a disp-psap definition in the DSA configuration file (.dxc), in the knowledge directory. Example: Configuring the DISP Responder # Sample DSA Knowledge configuration file: Democorp.dxc set dsa “Democorp” = { prefix = This responder remains active, awaiting incoming DISP protocol requests. 274 Administrator Guide DISP Replication DISP Agreements An agreement is a set of statements that defines a replication strategy. 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 Define each agreement with an agreement identifier and an agreement version. Replication 275 DISP Replication Setting DISP Agreements You can set agreements using the set command, which takes the following form: set agreement id.ver = { Initiator = name modeENTRY_941 Responder = name authlevelENTRY_942 [relay = name authlevel ] Area = The following are the parameters of the set agreement command: 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 276 Administrator Guide DISP Replication area The top of the subtree being replicated; the value is the distinguished name of the entry at the top of the subtree. strategy (Optional) Enables automatic DISP update to be performed. The strategy either has the keyword value on-change or has the following three values: frequency has one of the keyword values hourly, daily, weekly, or monthly time either dd:hh:mm or hh:mm type either incremental or full Filter A search filter restricting the entries to be included in the DISP update searchFilter an X.500 filter attributes A list of attributes to include or exclude from a DISP update: AttrSelectionList ::= attrSelection | attrSelection attrSelectionList AttrSelection ::= { [object-class = objectClass,] IncludeExclude } IncludeExclude ::= [all-attributes] | [include = attrTypeList] | [exclude = attrTypeList] AttrTypeList ::= attributeName [, attributeName] Example: A DISP Agreement set agreement 0.0 = { initiator = EAGLE supplier responder = BACKUP anonymous area = Replication 277 DISP Replication View DISP Agreements To view the details of a DISP agreement, use the following command in DXconsole: get agreement 1.0; where 1 is the agreement identifier and 0 is the agreement version. Example: Output from the get agreement Command 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, where one of the DSAs is an initiator (or supplier) and the other a responder (or consumer), the system performs automatic DISP updates as determined by the strategy. Note: DXserver supports the push DISP scenario, not the pull DISP scenario. In DXserver DISP replication systems, the initiator is always the supplier and the responder is always the consumer. See DISP Agreements (see page 275) for more information. 278 Administrator Guide DISP Replication DISP Routing eTrust Directory 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. Example: A DISP Agreement with Relay set agreement 0.0 = { initiator = EAGLE supplier responder = BACKUP anonymous relay = DSA-RELAY anonymous area = Manual Initiation of DISP You can manually perform a DISP update, even when there is a strategy, using the command: disp update agreement id.ver; The strategy in the agreement defines the type of update that will occur. An incremental update refreshes all entries that have changed since the last DISP update or since the DSA started. If there is no strategy, a full update is performed by default. Replication 279 DISP Replication Shadow DSAs A router directs update requests away from DSAs that are marked shadow or read-only. The read-only flag has the downside of preventing all updates to the database, including DISP updates. The shadow flag prevents all updates to the database, except via DISP or multiwrite. Clients can query, but cannot update, the DSA using DAP or LDAP. The master DSA can still update the slave using DISP. If you are using a router, you can mark a DSA as a shadow using DSA flags: set dsa ShadowDSA = { ... dsa-flags = shadow, ...... }; 280 Administrator Guide DISP Replication Selective Shadowing You can restrict the data that a shadow supplier replicates to a shadow consumer. There are three ways to achieve this: Specifying the replicated area Specifying a subtree filter for the replication area Specifying the set of attributes to be shadowed Specifying the Replicated Area Use the area parameter in the DISP agreement to specify the top of the subtree that is to be replicated. Specifying a Subtree Filter Use the optional filter parameter in the DISP agreement to specify entries under a particular area context prefix. The filter parameter is defined as: filter = { Using the subtree filter may cause problems when shadowing to other vendors' directories if, for example, a full refresh is requested, or if an entry is shadowed but its parent entry does not exist on the shadow consumer. The eTrust directory overcomes this potential problem by automatically creating glueDSEs for any missing entries. A glueDSE is a Directory Specific Entry (DSE) that has a name but no attributes. If using the subtree filter, base restrictions on object class, for example where the object class is person, not on other attributes, for example where all surnames begin with S. If the subtree filter contains anything other than comparisons of object class values, there is a danger that the replicated entry might be modified on the master DSA such that it no longer matches search filter. Subsequent DISP updates will not contain this entry leaving the shadow DSA with unmodified and incorrect data. Replication 281 DISP Replication Specifying a Selection of Attributes Use the optional attributes parameter in the DISP agreement to specify the set of attributes to be shadowed. Each element of attrSelectionList is an attrSelection element, which specifies the attributes that the shadow supplier is to select for shadowing. Specification of attributes for an object superclass also applies its subclasses. If the class is omitted, the selection applies to all classes. When using the exclude specification, any attributes contained in an entry which are not explicitly excluded are implicitly included. Attributes are implicitly included where all-attributes is specified. The attribute object class, all attributes that are described in the schema as must contain, and all operational attributes will be replicated unless they are explicitly excluded (that is, listed in an exclude list). Where entries belong to more than one of the specified classes, the specifications are cumulative. In the case of conflicting specifications, include has priority over explicitly excluded attributes and exclude has priority over implicitly included attributes. It is possible for a selective DISP update to include entries that do not satisfy the schema requirements of the shadow consumer. For example, all mandatory attributes may not be present in an entry contained in the DISP update. With eTrust Directory, such an update is allowed, because the master DSA verifies the schema of the complete entry and allows the partial replication to the shadow DSA. This may, however, cause problems when replicating to other vendors' directories. If you flag the DSA as a shadow so that it is read-only for non-DISP operations, the fact that not all attributes are present for a particular entry is of no consequence. Example: Selective Shadowing Example Agreement set agreement 2.1 = { initiator = EAGLE supplier responder = BACKUP anonymous area = 282 Administrator Guide Manually Synchronizing Replicas Using Database Tools Manually Synchronizing Replicas Using Database Tools Even if you use automatic recovery, you should also have procedures in place that use tools to resynchronize databases manually. If a DSA is offline for a long period of time, then a large number of updates may be required to synchronize that DSA with the master. When this is the case, it can be quicker to reload the data from a snapshot of the master database. If you do this, you must also inform the master and other peers that a manual resynchronization has taken place. eTrust Directory databases should be manually synchronized in either of these situations: The databases in a replication set have different number of entries Use the DXstatdb tool to check the numbers of entries between databases in a replication set when the system is quiet. In this case, you should usually resynchronize all the directory databases to have the same number as the master database. There is a large mismatch between directory entries This might happen because a multiwrite peer or DISP responder is unavailable for a long period of time while updates are applied to other systems in the replication set. How Manual Synchronization Works eTrust Directory provides a powerful set of database tools that can be used for resynchronization. This technique extracts directory information directly from the directory database into an intermediate LDIF file and then populates the target directory database directly from this file. Note: Both the source and target DSAs should be shut down during these operations. Replication 283 Manually Synchronizing Replicas Using Database Tools Re-synchronize Databases Manually These instructions describe how to take a snapshot of the source database and reload it on the target computer. For more information about the tools used here, see the chapter DXtools in the eTrust Directory Reference Guide. To manually resynchronize eTrust Directory databases 1. Shut down the source DSA. 2. Use the DXdumpdb tool to dump the source database to an LDIF file. 3. Use the ldifsort tool to sort the source LDIF file. 4. If the databases are on different systems, copy the LDIF file from the source system to the target system. 5. Use the DXdisp tool to inform the source DSA (and any other peer DSA) that a manual resynchronization has occurred. To do this, use the following command: dxdisp -clear dsaname dbname dsaname The name of the target DSA dbname The name of the database associated with the peer DSA 6. Use the DXloaddb tool to load the LDIF data into the target database. 7. Start the source and target DSAs. 284 Administrator Guide Chapter 8: LDAP and DXlink This section contains the following topics: LDAP Integration with eTrust Directory (see page 285) LDAP Clients (see page 286) Schema Publishing (see page 288) LDAP Controls (see page 290) Integrating Other LDAP Servers (see page 293) LDAP Integration with eTrust Directory eTrust Directory supports Lightweight Directory Access Protocol (LDAP), which enables any LDAP-conformant client access to eTrust Directory. LDAP is fully integrated with eTrust Directory 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. eTrust Directory also supports the integration of LDAP servers into a distributed directory backbone. DXlink lets eTrust Directory send requests to one or more LDAP servers and process the results returned from them as if they were normal X.500 directory servers. This enables LDAP servers to be integrated into a fully distributed directory framework. LDAP and DXlink 285 LDAP Clients LDAP Clients DXserver can be accessed from LDAP clients, such as web browsers, address books, and Lightweight Directory User Agents (LDUAs). DXserver LDAP Client LDAP DXserver Server Defining the LDAP Port You define the LDAP address using the set dsa command, which contains a port number that listens for LDAP requests, as follows: set dsa “Eagle” = { ... address = tcp “eagle” port 389 ... }; This address definition is mandatory; it automatically enables LDAP as the DSA listens for different protocols on the same port. For more information, see Defining DSAs with the set dsa Command (see page 39). For a list of all ports in a default installation of eTrust Directory, see Port Numbers Used by eTrust Directory in the eTrust Directory Reference Guide. 286 Administrator Guide LDAP Clients Configuring LDAP Names You configure LDAP names along with the usual schema attribute and object class definitions: set attribute 2.5.4.3 = { name = commonName ldap-names = cn syntax = caseIgnoreString }; LDAP names are integrated into the DSA schema. For more information, see (see page 113)Schema Definition. Handling LDAP Strings LDAP uses only string labels for information, so eTrust Directory 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 DSA 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 DSA schema definition process. Developers should remember that LDAP names are not necessarily unique. For example, two organizations can define the string mail, but have different syntaxes and uses for it. Transparent Routing When using a router DSA to route client requests to external LDAP directories using DXlink, it may not be feasible or convenient to include all third-party schema. For more information, see Transparent Routing (see page 166). LDAP and DXlink 287 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) 288 Administrator Guide Schema Publishing . . . > value: (1.3.6.1.4.1.3327.77.4.1.9 NAME 'uNSPSCdateto' SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE) > type: objectClasses > value: (2.5.6.0 NAME 'top' ABSTRACT MUST (objectClass)) > value: (2.5.6.1 NAME 'alias' SUP (top) STRUCTURAL MUST (aliasedObjectName)) . . . > value: (1.3.6.1.4.1.3327.77.4.2.1 NAME 'uNSPSC' SUP (top) STRUCTURAL MUST (uNSPSCCode$uNSPSCTitle) MAY (uNSPSCContractManager$uNSPSCContractID$uNSPSCContractAuth$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)) LDAP and DXlink 289 LDAP Controls LDAP Controls LDAP controls are a mechanism for extending or changing the way a server handles a particular operation. Controls may be attached to LDAP operations and generally change the semantics for that specific operation. Controls which are not recognized will be ignored if not marked 'critical'. If a control is marked 'critical' and is not recognized, the error 'unsupported critical extension' will be returned and the operation will not be performed. Because eTrust Directory supports distribution, it is possible that a control will not be honored even though it is recognized. For example, if server-side sorting is requested but the request has to be multi-chained to complete the operation, the server-side sorting control will not be honored. If the control is marked 'critical', an error will be returned to the client, otherwise the control will be ignored. Controls recognized by eTrust Directory are published through the root DSE as per RFC 2252. Server-Side Sorting The server-side sorting LDAP control allows a client to request that a search response be sorted. It is only available when DXcache has been enabled. See RFC 2891. Simple Paged Results The simple paged results LDAP control allows a search result to be returned a page at a time. It is only available when DXcache has been enabled. See RFC 2696. 290 Administrator Guide LDAP Controls Password Policy Control It may be useful, when writing applications that manage accounts and passwords, to receive extra information on operation responses. The information returned via this control includes account status (password expiring/expired, account locked) and reasons for password change failure (password too short, etc). This control is specified in an Internet Draft on the IETF home page (http://www.ietf.org). It is possible for the specification of its operation to change over time. Also, the name of the draft document will change as revisions are made. At the time of writing, the document name is draft- behera-ldap-password-policy-09.txt. Proxied Authorization Control The proxied authorization control gives a client the ability to perform operations as the user specified in the control value. This is similar to the ‘su’ (substitute user) function available on UNIX operating systems. To restrict the ability of a user to impersonate anyone, the 'trust SASL proxy' feature described in Section 6: "Secure Proxies" of the Administrators Guide must be set. This feature is useful for auditing changes to the DIT. If the link flag dsa-ldap-proxy is used in conjunction with DXlink, the proxied authorization control is added to operations chained to third-party LDAP servers containing the entry of the request's originator. The root DSE of the third-party LDAP server should be queried to check that it supports this control. This control is specified in an Internet Draft on the IETF home page (http://www.ietf.org). It is possible for the specification of its operation to change over time. Also, the name of the draft document will change as revisions are made. At the time of writing, the document name is draft- weltmann-ldapv3-proxy-13.txt Netscape Password Policy Controls The Netscape password policy controls are used to notify an application that the connecting user's password is expiring (number of seconds to expiry) or has expired. These are response-only controls and are enabled in eTrust Directory with the following command: set password-mimic-netscape-response-controls = true; These controls are described in an Internet Draft which has expired. They are not subject to IETF standardization. LDAP and DXlink 291 LDAP Controls Persistent Search This control allows a client to request notification when entries in a specified scope change. This control can only be used if the scope it specifies is mastered by the DSA it is sent to. This is because the DSA will not coordinate with other directories (including eTrust Directory DSAs) holding the same or other parts of the DIT. To enable persistent searching Use the following command: set persistent-search = true; The control is specified in an Internet Draft which has expired. It is not subject to IETF standardization. For more information, see draft-ietf-ldapext-psearch-03.txt on the IETF home (http://www.ietf.org)page. Limitations on Persistent Searching Persistent searching can only be used where the directory information tree (DIT) is managed by a single DSA. Only the local DIT is accessed, which means that there is little point in using it with routers. For example, persistent searching will not work in the following situations: If you have update and search DSAs then the persistent search is not likely to work unless it is done in the router. If there are multiple routers then persistent search in the router will not work. Instead, it will need to be done on the update DSA. If there is query streaming and persistent search is done in the update DSA, the search will never be sent to the update DSA, so it will not work in this situation either. Routing LDAP Controls If eTrust Directory has to chain (forward) a request to another directory, it will also forward any associated controls, even if it doesn’t recognize them. It will not forward these controls when multicasting a search request. Controls on responses will also be passed back to the client even when not recognized, provided that the result is not an error. 292 Administrator Guide Integrating Other LDAP Servers Integrating Other LDAP Servers LDAP servers do not support the DSP protocol. This means that you cannot perform a distributed search over a number of LDAP directory servers. eTrust Directory has a facility called DXlink that lets LDAP servers link into an X.500 backbone. The DXserver can send requests to one or more LDAP directories and process the results returned from them as if they were X.500 directory servers. DXserver LDAP DXserver DXlink To configure DXlink, configure the LDAP server as if it is a DSA, and add the dsp-ldap link flags to the DSA definition as follows: set dsa “LDAPserver” = { prefix = 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. LDAP and DXlink 293 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 LDAP Client DSA Server 294 Administrator Guide Integrating Other LDAP Servers Setting User Credentials for LDAP Operations If either of the following is true, you can set the credentials used in the DXlink connections in the LDAP server configuration file: The user invoking the request is authenticated using a DN that is outside the LDAP server. More than one DSA is in the path to the LDAP server. For example: set dsa LDAP1 = { ... ldap-dsa-name = The value for ldap-dsa-name must be a valid entry in 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 295 Integrating Other LDAP Servers Automatically Authorizing LDAP Operations When a directory backbone performs operations over DXlink, some operations on the target LDAP server may require that the user be authorized for that operation. You can include the dsp-ldap-proxy link flag in the DXlink knowledge, to cause the last DSA in the chain to use the authorization of the originating user to perform operations on the LDAP server. Important! This may compromise security, because the originating user is never authenticated by the LDAP server. Usually, the last DSA in the chain binds to the LDAP server using the credentials specified in the ldap-dsa-name and ldap-dsa-password flags. If the dsp-ldap-proxy flag is also set, then the DN of the user that made the initial bind is added to the following subsequent requests: search compare modify add delete modify DN If the initial bind was anonymous, no DN is added to subsequent requests. This is achieved by the DSA chaining the operation over DXlink adding the originator DN to a LDAP proxy control on the request. The LDAP server will need to permit the DN specified ldap-dsa-name authorization to proxy all users. Note: The dsp-ldap-proxy link flag can only be used if the target LDAP server supports the LDAP Proxy Authorization control. 296 Administrator Guide 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. LDAP and DXlink 297 Integrating Other LDAP Servers Example: Prefix Mapping An example is an X.500 directory system that controls the nodes c=US and c=US, o=CAI. There is also an LDAP server with the X.500 naming context: “c=US, o=CA” The LDAP server does not contain the c=US node but controls the tree beneath the c=US node that starts with the o=CA entry. It was set up to control the North American part of CA but is now required to be incorporated into the entire CA directory. This context can be mapped into the host's X.500 naming context “c=US, o=CAI” as: “c=US, o=CAI, ou=CA North America” Thus, a subtree search of “c=US, o=CAI, ou=CA North America” is mapped to a subtree search of “c=US, o=CA” before being forwarded to the LDAP server. The results are mapped back into the host DIT space. C=US O=CAI O=CA North America You can enable prefix mapping by defining a native-prefix in the server definition: set dsa LDAP1 = { ... prefix = 298 Administrator Guide Integrating Other LDAP Servers Working with Microsoft Exchange Here is an example Microsoft Exchange knowledge file: 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 299 Chapter 9: Monitoring the Directory This section contains the following topics: Supported Protocols (see page 301) General Monitoring (see page 302) SNMP and the Directory Monitoring MIB (see page 304) CMIP and X.700 Management (see page 310) Supported Protocols 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 Monitoring the Directory 301 General Monitoring General Monitoring During normal operation of a directory: Data is added to and deleted from the directory. User and other DSA connections are made and released. Log files are generated. You should review DXserver operation periodically to ensure DXserver continues to run smoothly. Monitoring with 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; Monitoring 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. 302 Administrator Guide General Monitoring Monitoring Databases The DXstatdb tool prints a summary of a given database. The database itself has monitoring facilities. For more information, see Using DXtools (see page 313). Monitoring 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. Monitoring the Directory 303 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: Multiwrite replication DXserver statistics Caching 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. 304 Administrator Guide 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. Example: Configuring the SNMP Agent set dsa “DEMOCORP” = { ... snmp-port = 19389 ... }; Define the UDP/IP port that listens for incoming SNMP requests by setting the snmp-port. This is the only UDP port that the DSA uses, so it can accept any value and it does not interfere with TCP port numbers. You can set the following SNMP parameters: snmp-description snmp-contact snmp-name snmp-location set snmp-description = “SNMP monitor” set snmp-contact = “[email protected]” set snmp-name = myDXserver set snmp-location = myOffice For a list of all ports in a default installation of eTrust Directory, see Port Numbers Used by eTrust Directory. Monitoring the Directory 305 SNMP and the Directory Monitoring MIB SNMP Monitor Utility eTrust Directory supplies a sample SNMP MIB walker utility called DXsnmp in the samples/snmp directory. The SNMP utility polls the server periodically and prints nonzero parameters. To start the SNMP utility, use the following command: dxsnmp -r[n] ipaddress/port The -r option is the refresh rate (in seconds). You can enter a number after the -r to indicate the number of seconds between each refresh. The default value is 5. Example: Starting the SNMP MIB Walker dxsnmp -r localhost/19389 The following is a sample output: $ dxsnmp localhost/19389 sysDescr : 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 306 Administrator Guide SNMP and the Directory Monitoring MIB dsaCacheEntries.1 : 0 dsaCacheHits.1 : 0 dsaSlaveHits.1 : 0 Example: Monitoring multiwrite replication This is only displayed if multiwrite replication is enabled. The following is a sample output: dxRemoteDsaName.1 : DEMOCORP2 dxRemoteDsaName.2 : DEMOCORP3 dxRemoteDsaName.3 : DEMOCORP4 dxMWQueueLength.1 : 0 dxMWQueueLength.2 : 1 dxMWQueueLength.3 : 0 dxMWStatus.1 : 1 (ok) dxMWStatus.2 : 2 (failed) dxMWStatus.3 : 1 (ok) dxMWPendingRemote.1 : 0 dxMWPendingRemote.2 : 0 dxMWPendingRemote.3 : 0 dxMWConfirmedLocal.1 : 0 dxMWConfirmedLocal.2 : 1 dxMWConfirmedLocal.3 : 0 Example: 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 Monitoring the Directory 307 SNMP and the Directory Monitoring MIB Example: Monitoring Cache DSAs This option always appears, but will only show information when caching is enabled. The dxCacheSearchHits value increments whenever a search 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 308 Administrator Guide SNMP and the Directory Monitoring MIB Configuring the SNMP Trap Destination Deliver Alarms as SNMP Traps To configure the delivery of alarms as SNMP traps, use the following console command: set snmp-log = udp host port portnumber; You can place this command in the appropriate configuration file (.dxc) within the logging directory. Disable Alarms as SNMP Traps To stop logging SNMP events, use this command: close snmp-log; The trap contains three variables: sysName, sysDescr, and sysLocation. sysName contains the name of the DSA sending the trap, sysDescr contains sufficient information to reconstruct the actual update operation, and sysLocation contains the actual alarm text. Send Traps About Any Update Operations By default, all alarms are sent to the trap destination. However, you can configure the DSA to send traps that contain information about any update operations it receives. To do this, set an associated boolean setting, trap-on-update, as follows: set trap-on-update = true; Typically, you set this in the DSA settings configuration file (.dxc) in the settings directory. Monitoring the Directory 309 CMIP and X.700 Management CMIP and X.700 Management eTrust Directory has an integral CMIP management agent for monitoring the operation of the DSA. The DSA provides limited support for ISO 9594-10 (Committee Draft April 1995) as follows: The MIB fully supports the DSA-managed object definitions. You can determine its structure and naming by setting scope=wholeSubTree or scope=baseObject. eTrust Directory supports all packages of the DSA-managed object. Each component of each package is read-only because the intended use is for monitoring. Configuring the CMIP Agent You configure the listening address for the CMIP agent through the management console or in the DSA initialization scripts. Example: Configuring the CMIP Agent set dsa “DEMOCORP” = { ... cmip-psap = CMIP ... }; The cmip-psap option 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. 310 Administrator Guide CMIP and X.700 Management CMIP Monitor Utility eTrust Directory supplies a sample CMIP monitoring utility called DXcmip in the samples/cmip directory. This very simple CMIP manager performs periodic get requests on the DSA. You can start the CMIP utility using the following command: dxcmip -r[n] ipaddress/portnumber [psel] The -r option is the refresh rate (in seconds). You can enter a number after the -r to indicate the number of seconds between each refresh. The default value is five. Example: Starting the CMIP Monitoring Application dxcmip -r localhost/19389 This example starts the CMIP monitor. It monitors operations on the server configured in SNMP Example 1-Configuring the SNMP Agent. 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 Monitoring the Directory 311 CMIP and X.700 Management 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 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) sdfasf : -0 312 Administrator Guide Chapter 10: Tools for Managing eTrust Directory This section contains the following topics: What Are the DXtools? (see page 313) Using DXtools (see page 313) Database Tools (see page 314) LDIF Tools (see page 316) DAP Tools (see page 320) Schema Tools (see page 321) What Are the DXtools? The DXtools provide a sophisticated set of utilities that simplify the management of directory data and databases. Together, these tools provide a fast start to any directory project, letting you easily load existing data for demonstration and prototyping. They help you manage directory data on an ongoing basis. The tools also provide a migration path, a method, or both, for controlled exchange of data when DSP is not appropriate. This chapter gives a brief overview of the tools. For a detailed description of each tool, see the eTrust Directory Reference Guide. Using DXtools You can run the DXtools in the following ways: Run the DXtools locally on the host Windows or UNIX server Execute them from a Windows client workstation to a directory server over a TCP/IP network. Incorporate them into your custom scripts. All tools return zero on success and non-zero when an error occurs. Tools for Managing eTrust Directory 313 Database Tools Database Tools The database tools provide a set of utilities that simplify the creation and management of directory databases and the DSA tables. The database tools are: DXnewdsa Creates a new DSA configuration, generating the initialization, database, and knowledge files, and creating the database if necessary DXnewdb Creates a new database including the tables that DXserver requires DXextenddb Adds extra 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 314 Administrator Guide Database Tools 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 DXcertgen Reports on currently configured certificates and generates new DSA personality certificates. User Permissions for Database DXtools eTrust Directory r8.1 includes Ingres r3. The security of Ingres r3 is tighter than in previous Ingres versions, which has changed how eTrust Directory works. For previous releases of eTrust Directory, any user could run all of the DXtools. This means that any user could load, destroy or back up databases. For eTrust Directory 8.1, only the user that installed or upgraded Ingres r3 is permitted to run the database DXtools. This is similar to how eTrust Directory has always worked on UNIX. During installation on Windows XP and 2003, the DXserver services now log on as LocalService, which is added as an Ingres user. During installation on Windows 2000, the DXserver services continue to log on as LocalSystem. This applies to the following situations: eTrust Directory r8.1 installed on a clean computer eTrust Directory r8 SP1 upgraded to eTrust Directory r8.1 and Ingres r3 Tools for Managing eTrust Directory 315 LDIF Tools LDIF Tools The DXtools manage directory data using the LDAP Data Interchange Format (LDIF). The LDIF file format is suitable for describing directory information or modifications made to directory information. It is often used for transferring directory information between LDAP-based directory servers or describing a set of changes applied to a directory. This section describes how you can transfer comma-separated value (CSV) data files into LDIF directory files using the data conversion tools. The LDIF 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 316 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. While the default separator is a comma, the DXtools support the use of alternative and user-defined separators. 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: 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" Example: 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 Tools for Managing eTrust Directory 317 LDIF Tools Template Files (LDT) The information contained in a data file is simply a list of values. To give meanings to these values, you must specify what the values in each field represent. To do this, define an LDIF template (LDT) file. The LDT files describe the objects contained in the directory. The LDT file follows the LDIF file format, which is used to add directory information to the data values. An LDIF file consists of a series of records separated by blank lines. A record consists of a sequence of lines describing a directory entry. Special substitution tokens are used to place fields from the CSV file into the LDT. Each line in the LDT file defines a rule that links a field in a CSV data file to a directory attribute or name with an object description. These rules let the tools translate CSV file information into LDIF file formats. Example: 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 318 Administrator Guide LDIF Tools The Format of LDT files Each record in an LDT file specifies the format of entries at that level. Each record contains a DN and one or more attribute-value template lines. You can treat the $ character literally when the escape character (\) precedes it. This escape character has no significance other than escaping. Use \\ to represent the \ character. Using substitution tokens in the DN line lets you specify leaf nodes and their parents. You can therefore infer hierarchy from the original CSV data. You must explicitly code parent objects in the template file, and they must appear in increasing-depth order in the file before any definition of leaf objects. If you need a literal number following a substitution token, you can use the three-digit form of the token as in the following example (the three-digit form is shown underlined): # leaf node dn:cn=$1 $2,ou=$4, o=Democorp,c=AU oc:organizationalPerson Surname:$2 Description: $00199 \$ $2 \$ $3 Telephone:+61 $3 A substitution token cannot exceed three digits (maximum is $999). When this LDT file is interpreted, the $00199 looks at the first three digits after the $ (in this example $001 is equal to $1), so the program finds the first column of the CSV to substitute, and appends "99" characters to it. If you use $199 rather than $00199, the 199th column of the CSV is used to substitute, which is not the intention of this example. LDIF Files Using the LDIF format, you can convey directory information or a description of a set of changes made to directory entries. An LDIF file consists of a series of records with line separators. Each record consists of a sequence of lines describing either a directory entry or a set of changes to a single directory entry. These two types of records cannot be mixed in an LDIF file. An LDIF file contains either records that specify a set of directory entries or records that specify a set of changes you apply to directory entries, but not both. For further information about the LDIF format, review the Internet Engineering Task Force (IETF) draft Request For Comments (RFCs) available at the IETF home page (http://www.ietf.org). Tools for Managing eTrust Directory 319 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. These are the import 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 This is the export tool: DXsearch Searches a specified directory using defined filters Bulk Loading Options Traditionally, data is imported and exported from directories using the import and export tools described earlier (see DAP Tools (see page 320) 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 a DSA, 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. 320 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. 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. Tools for Managing eTrust Directory 321 Chapter 11: About JXplorer This section contains the following topics: What Is JXplorer? (see page 324) The JXplorer Browser (see page 325) How JXplorer Connects to a Directory (see page 333) How JXplorer Searches a Directory (see page 336) Bookmarks (see page 343) How JXplorer Lets You Edit the Directory (see page 344) How JXplorer Reads the Schema (see page 358) How JXplorer Handles Importing and Exporting Data (see page 361) How JXplorer Works with Aliases (see page 362) How JXplorer Handles Passwords (see page 367) How JXplorer Handles SSL, SASL, and Certificates (see page 370) JXplorer Logging (see page 373) Customize JXplorer (see page 373) Troubleshooting (see page 373) LDAP and Directory Resources (see page 374) About JXplorer 323 What Is JXplorer? What Is 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 view 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. SSL to communicate securely, and SASL for secure certificate-based authentication. 324 Administrator Guide The JXplorer Browser The JXplorer Browser When you start JXplorer, 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. The Tree Pane 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 About JXplorer 325 The JXplorer Browser The Explore Tree In the Explore tree, you can browse the directory tree: You can also display the schema rules for this directory by clicking on World, which is always shown at the top of the Explore pane: 326 Administrator Guide The JXplorer Browser The Results Tree Regardless of whether the search is run using the quick search bar or a search menu option, once it is run the matching entries are displayed as a results tree in the Results view of the directory tree pane. Parents of search results appear as empty entries in the tree. You can browse and save the search result tree (including LDIF format) just like the directory tree. You can edit the results. You can set the number of entries returned from a search, and the timeout. See Search Limits (see page 343) for more information. About JXplorer 327 The JXplorer Browser The Schema Tree In addition to viewing the data entries held in a directory, you can directly view the schema that is read from the directory. The Schema pane lets you examine attribute definitions, class definitions, and syntax definitions. Note: Some of these options may not be available with directories other than eTrust Directory, because not all servers implement full schema publishing. You can display schema entries either in the HTML View tab or the Table Editor tab. Unlike the other tree displays, however, you cannot edit the schema directly through the browser. For security and administration reasons, many servers do not permit their schema to be edited online and require an administrator to perform schema maintenance at the server. You can export schema to an LDIF file, but this is not the usual way to store schema information and most directories cannot use it without further processing. 328 Administrator Guide The JXplorer Browser The Quick Search Bar The quick search bar lets you execute simple searches. The operators are: Equal to = Approximately equal to ~= Greater than or equal to >= Less than or equal to <= Not equal to !(=) About JXplorer 329 The JXplorer Browser The Entry Display The entry display pane (the right pane) displays the currently selected directory entry, either in an HTML template, or in an editable table of attributes and values. When you select an entry, whether from the Explore view, the Results view, or even the Schema view, the browser queries the directory for the attribute values of the entry and displays the results in the entry display pane. The results can be displayed either in the HTML template view or in the attribute/value table view. The HTML Viewer The following is an employee record displayed in an HTML template. The template contains three tabs (Main, Address, and Other) that display the attribute information for the selected entry. 330 Administrator Guide The JXplorer Browser 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 About JXplorer 331 The JXplorer Browser The Table Editor The same employee record can be edited and displayed in the table editor. You can also use it to view the attributes an entry can contain, because it uses schema to show all the possible attributes that the entry might have. Attributes in bold represent mandatory attributes - these must be present for the entry to be valid. Click the Properties button to display operational attributes such as the date of the last modification. You can configure the table viewer to include custom binary editors, which may be the only way to view complex or application-specific binary data. 332 Administrator Guide How JXplorer Connects to a Directory How JXplorer Connects to a Directory When you connect JXplorer to a directory the browser displays a connection dialog, requesting the information that JXplorer needs to connect to a directory: Host The name of the computer that hosts the directory. Port The port number of the DSA on that computer Protocol The protocol that is in use, which can be LDAP or DSML. For LDAP, this is usually Version 3, but can be Version 2 to support older directories. If you select DSML, you also need to enter the path to the DSML service. DSML Service The path to the DSML service dsml/services/DSML Base DN (Optional) 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. Security Level 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. User DN Password About JXplorer 333 How JXplorer Connects to a Directory Security Levels for LDAP Connections When you use JXplorer to connect to an LDAP server, you can choose the level of security for that connection: Security Level Description Anonymous Connects to the directory anonymously. User + Password Connects to the directory using your user name and password. SSL + Anonymous Connects to the directory anonymously via an SSL link. The SSL connection uses either the trusted public certificate of the directory server, or the public certificate of the directory server's certificate authority. SSL + User + Connects to the directory using your user name and password via an SSL link. Password The SSL connection uses either the trusted public certificate of the directory server, or the public certificate of the directory server's certificate authority. SSL + SASL + Connects to the directory via an SSL link. Keystore Password The SSL connection is authenticated using either the trusted public certificate of the directory server (or the public certificate of the directory server's certificate authority), and the client's trusted public certificate (or the public certificate of the client's certificate authority), and the client's private key. GSSAPI Basic GSSAPI/Kerberos support 334 Administrator Guide How JXplorer Connects to a Directory Save Connection Details in a Template JXplorer lets you save connection details for commonly used directories as connection templates. You can save any number of connection templates, and you can edit or delete them at any time, using the list at the bottom of the Connection dialog: 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. About JXplorer 335 How JXplorer Searches a Directory How JXplorer Searches a Directory In JXplorer, you can search for an entry in two ways: Quick search using simple criteria Complex search using a wider range of criteria. You can save complex searches as filters, join these filters to create new searches, or write your own LDAP filters. The search results are displayed as complete directory trees, which lets you browse large numbers of search results. You can save the search results as LDIF files. Quick Searches 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. 336 Administrator Guide How JXplorer Searches a Directory 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 About JXplorer 337 How JXplorer Searches a Directory Choose Which Attributes to Return When you search a DSA, you can define which attributes you want to have returned. The default is none. To create these definitions, choose Return Attribute Lists from the Search menu: You can then use the Information to retrieve drop-down list in the Search dialog to select the definition that contains the list of attributes you want returned: 338 Administrator Guide How JXplorer Searches a Directory Save Searches for Later Use JXplorer lets you save searches as filters for later use. Your saved searches appear in the Search menu, so you can access them quickly. 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 View saved search filters About JXplorer 339 How JXplorer Searches a Directory Write Your Own Searches The Quick Search bar and the Search dialog are useful for helping you to build filters. However, if you already have an LDAP search filter, you do not need to re- create it in one of these dialogs. Instead, you can use the Text Filter tab in the Search dialog: 340 Administrator Guide How JXplorer Searches a Directory Search Operators The following table lists the operators you can use in JXplorer searches, and the effects of these operators. Try applying these example filters to the Democorp DSA. In the Search In the Example Filter Result of Example Filter on Democorp dialog Quick Data Search bar Beginning With sn=Br* All entries with a surname that begins with Br, including Bruce, Brazier, and Bradley Not Beginning (!(sn=Br*) All entries other than those in which the With surname begins with Br Containing sn=*JOR* All entries with a surname that includes the letter JOR, including Major, Jordan, and Jorgenson. Not Containing (!(sn=*a*)) All entries with a surname that does not contain the letter a Equal To = sn=marten All entries with a surname of Marten. Not Equal To ~= (!(title=Secretary)) All entries with a title other than Secretary. Ending In sn=*s All entries with a surname that end with s, including Lucas, Watts, and Giddings Not Ending In (!(sn=*s)) All entries with a surname that do not end with s Greater Than or >= sn>=w All entries with a surname starting with w, Equal To and any subsequent letter of the alphabet, including Whittle, Young, and Ziegler postalCode>=6000 All entries with a postalCode greater than or equal to 6000, including 6000, 6018, and 7000. Not Greater (!(sn>=w)) All entries with a surname starting with Than or Equal any letter after w, but not including w. To This operator is equivalent to "less than". (!(postalCode>=2000)) All entries that have a postalCode less than 2000, including 0810, 0860, but not 2000. This operator is equivalent to "less than". About JXplorer 341 How JXplorer Searches a Directory In the Search In the Example Filter Result of Example Filter on Democorp dialog Quick Data Search bar Less Than or <= sn<=b All entries with a surname starting with Equal To the letters up to b, including Anderson, Ash, and B. This does not return entries starting with b and followed by other letters. That is, this search would not return Baker. postalCode<=2000 All entries with a postalCode less than or equal to 2000, including 0810, 0860, and 2000. Not Less Than (!(sn<=b)) All entries with a surname starting with or Equal To any letter before b, but not including b. This operator is equivalent to "greater than". (!(postalCode<=2000)) All entries that have a postalCode less than 2000, including 0810, 0860, but not 2000. This operator is equivalent to "greater than". Present sn=* All entries with a surname. In the Democorp DSA this returns all of the leaf entries. Not Present !(sn=*) All entries with no data in the attribute sn, and all entries that do not have the attribute sn Similar To ~= sn~=marten All entries with a surname that sounds like marten, including Martin, Martyn, and Martinez Not Similar To (!(sn~=marten)) All entries with that do not have a surname similar to marten, including entries that do not have the attribute sn 342 Administrator Guide Bookmarks 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. 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. About JXplorer 343 How JXplorer Lets You Edit the Directory How JXplorer Lets You Edit the Directory You can modify entries in the directory using the browser in many ways, ranging from slight modification of a single attribute value to large-scale tree operations affecting many thousands of entries. JXplorer lets you cut, paste, and delete entire directory subtrees using the tree pane on the left. 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 any of these items:: The menus The toolbars Dragging and dropping The context menu (accessed by right-clicking on the entry) for the entry in the tree itself Important! This is a very powerful tool, and you can affect large areas of the directory with a single operation. To avoid accidents, you should select Confirm Tree Operations on the Options menu. 344 Administrator Guide How JXplorer Lets You Edit 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. About JXplorer 345 How JXplorer Lets You Edit the Directory Rename Entries in the Directory Tree To change the name of an entry, you need to change the value of the naming attribute. The naming attribute is the single attribute used to uniquely identify each entry in the directory. JXplorer lets you rename an entry within the directory tree by selecting the Rename option: You can then type a new name for the entry. JXplorer then changes the naming attribute of the entry to the new name. The naming attribute of an entry is shown in blue in the Table Editor: 346 Administrator Guide How JXplorer Lets You Edit the Directory When a parent is renamed, the DNs of the entries in the entire subtree under the parent also change. If you rename an entry with subordinates, the subordinates are also renamed. Modify 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. Change 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 (see page 354), Using the Postal Address Editor (see page 352), and Entering a User Password (see page 353) for more information. About JXplorer 347 How JXplorer Lets You Edit the Directory Delete 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 (see page 348) for more information about mandatory attributes. Add 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 add 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. See Using Binary Values (see page 354) and Using the Postal Address Editor (see page 352) 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, unless you have selected Ignore Schema Checking on the Options menu.. 348 Administrator Guide How JXplorer Lets You Edit 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. 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. Change 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. Important! You must be careful when deleting object class values because you also remove all related attributes. About JXplorer 349 How JXplorer Lets You Edit the Directory Attribute Editors Some attributes cannot be easily edited in the Table Editor fields. Instead, JXplorer provides special editors for some kinds of attributes and syntaxes. When you click on any of the following attributes, an appropriate editor is launched: userPassword userCertificate odSpreadSheetXLS odSoundWAV odMusicMID odMovieAVI odDocumentDOC ocspRSAPrivateKey jpegPhoto audio When you click on any attribute with one of the following syntaxes, and appropriate editor is launched: 1.3.6.1.4.1.1466.115.121.1.24 Generalized Time 1.3.6.1.4.1.1466.115.121.1.41 Postal Address 1.3.6.1.4.1.1466.115.121.1.8 Certificate 1.3.6.1.4.1.1466.115.121.1.5 Binary 1.3.6.1.4.1.1466.115.121.1.7 Boolean 350 Administrator Guide How JXplorer Lets You Edit the Directory Work with Audio Files JXplorer lets you import and export audio files into and out of the directory, using the Audio dialog, which is launched from the Table View: You can import and export audio files of any format. JXplorer also lets you play audio files with the following formats, using the HTML view: .aiff .au .it .mid .mp3 .ram .rmi .s3m .stm .voc .wav .xm About JXplorer 351 How JXplorer Lets You Edit the Directory Work with Photos 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. All photos must be in .jpeg or .jpg format. You can also use this dialog to save the photo to another location. Work with Postal Addresses 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. 352 Administrator Guide How JXplorer Lets You Edit the Directory Work with User Passwords If you use the Table Editor view to edit a user password, a dialog opens that lets you create a new password and change the way the password is stored (plain text, MD5 encryption or SHA encryption): If you edit a user password from the HTML view, you can only change the password: Access to an entry is controlled via the access control settings in the directory's configuration file (.dxc). This means that you do not have to enter the existing password before changing it. About JXplorer 353 How JXplorer Lets You Edit the Directory 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 jpegPhoto 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 let you 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. Import Binary Files With the following Binary Data dialog, you can import and export binary files: 354 Administrator Guide How JXplorer Lets You Edit the Directory Files that Can Be Launched eTrust Directory provides the odMultimedia object class that contains attribute types that let you launch files of the following formats: .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. About JXplorer 355 How JXplorer Lets You Edit the Directory Add 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. Choose 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. Set 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. 356 Administrator Guide How JXplorer Lets You Edit the Directory Submit 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 (unless you have selected Ignore Schema Checking in the Options menu), 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. About JXplorer 357 How JXplorer Reads the Schema How JXplorer Reads the Schema After the connection details are obtained, the browser attempts to contact the directory. After a connection to the directory has been made (through LDAP v3 or DSML), JXplorer obtains the directory's current schema. Directories that support LDAP v3 (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. If you connect to the directory using DSML instead of LDAP, JXplorer can still get the schema, as long as the DSML server can use LDAP v3 to communicate with the DSA. 358 Administrator Guide How JXplorer Reads the Schema Data in Each Schema Object A schema contains the following schema objects: Attribute Types Attribute types define the attribute's syntax and how the attribute is compared and sorted. LDAP Syntaxes LDAP syntaxes describe the representation of the attribute's value. Object Classes Object classes define what kind of attributes an entry can contain. DIT Structure Rules DIT structure rules define where entries appear in the directory information tree. DIT structure rules are part of the name bindings. Name Forms Name forms specify which attributes the entry can be named by. Name forms are part of the name bindings. This table lists the data contained in each of these schema objects: Attribute LDAP Object DIT Structure Name Types Syntaxes Classes Rules Forms OID Yes Yes Yes Yes Yes NAME Yes Yes Yes Yes DESC Yes Yes Yes SUP Yes Yes Yes SYNTAX Yes SYNTAX Description Yes EQUALITY Yes SINGLE-VALUED Yes OC Yes MUST Yes Yes MAY Yes Yes FORM Yes About JXplorer 359 How JXplorer Reads the Schema Checking Entries for Schema Conformance eTrust Directory automatically checks all entries submitted to the directory to ensure that they conform to the directory schema. JXplorer also checks that each entry conforms to the schema. For example, if you try to submit an entry that has a mandatory attribute with no value, JXplorer rejects the change you have made: If you do not want JXplorer to check that each entry conforms to the schema, select the Ignore Schema Checking option in the Options menu: 360 Administrator Guide How JXplorer Handles Importing and Exporting Data How JXplorer Handles Importing and Exporting Data You can import an LDIF file into JXplorer, edit it, and then save the LDIF file. When JXplorer is connected to a directory, it reads the values from the selected file and adds them to the directory, or reads the values from the directory and writes them to an LDIF file. JXplorer does the following: 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. 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 MIME (Multipurpose Internet Mail Extensions) Part One (http://www.ietf.org/rfc/rfc1521.txt). Use 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 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). About JXplorer 361 How JXplorer Works with Aliases How JXplorer Works with Aliases An alias is a directory entry that contains the name of another entry. When you search or browse a directory, you can decide whether to resolve aliases (show the details of the target entry) or to show the details of the alias entry itself. Aliases are similar to shortcuts and are used in some directories to link different parts of the tree. 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. Alias entries are displayed with a green icon in the tree pane. The following screenshot shows two alias entries: You can choose to resolve aliases while browsing and while searching. 362 Administrator Guide How JXplorer Works with Aliases Create a New Alias Entry You can create a new alias entry by copying an entry, and then using the Paste Alias option: About JXplorer 363 How JXplorer Works with Aliases Resolve Aliases While Browsing JXplorer lets you choose whether to show resolve aliases while you are browsing the tree. If you choose to resolve aliases, when you browse to an entry that is an alias, the details of the target entry will be displayed. There will be no indication that you have browsed to an alias entry. If you choose to not resolve aliases, when you browse to an entry that is an alias, the details of the selected entry will be displayed. This means that you will see the DN of the target entry, instead of the details of the target entry. Note: This only applies to browsing the tree. When you search the directory, this option is ignored. 364 Administrator Guide How JXplorer Works with Aliases Example: Resolving Aliases While Browsing This example shows part of the directory information tree for the Democorp DSA. The tree has been edited to include the following two aliases: In the Aviation subtree, a new alias entry has been created. This alias entry points to the Bernd Stark entry in the Construction sub-tree. In the Projects subtree, a new alias entry that points to the Construction entry. If you select Resolve Aliases While Browsing in the Options menu and then browse the directory tree to Bernd Stark's entry under ou=Aviation, you will see all of his details. However, if you de-select Resolve Aliases While Browsing in the Options menu and then do the same thing, you will see the details of the alias entry (that is, "cn=Bernd STARK,ou=Construction,ou=Projects, o=DEMOCORP,c=AU"), but no details about Bernd Stark. About JXplorer 365 How JXplorer Works with Aliases This table shows the data that will be displayed in different circumstances: Resolve Aliases Browse To Display While Browsing Selected cn=Bernd STARK,ou=Construction, Full details of Bernd Stark, as stored in his ou=Aviation, o=DEMOCORP,c=AU entry in the Construction subtree De-selected cn=Bernd STARK,ou=Construction, Details of the alias entry (that is, ou=Aviation, o=DEMOCORP,c=AU "cn=Bernd STARK,ou=Construction, ou=Projects,o=DEMOCORP,c=AU"), but no details about Bernd Stark Selected cn=Bernd STARK,ou=Construction, Full details of Bernd Stark ou=Projects, o=DEMOCORP,c=AU De-selected cn=Bernd STARK,ou=Construction, Full details of Bernd Stark ou=Projects, o=DEMOCORP,c=AU Resolve Aliases While Searching When you set up a complex search using the Search dialog, you can choose whether to resolve aliases during the search: When you resolve aliases, JXplorer returns the real entry to which the alias points. When you do not resolve aliases, JXplorer returns all alias entries as regular entries. However, each search operation has two components: the search for the base object (if you specified one), and the search for the entries to return. you can choose whether to resolve aliases in each of these components. 366 Administrator Guide How JXplorer Handles Passwords How JXplorer Handles Passwords This section discusses how JXplorer handles passwords. Password Storage When you use the Connection dialog to connect to a DSA using a password, JXplorer saves the password. These saved passwords are not stored in connections.txt. Instead, JXplorer stores these passwords internally. When JXplorer is shut down, any stored passwords are discarded. For instructions, see Turn Off Password Storage (see page 424). About JXplorer 367 How JXplorer Handles Passwords Password Hashing When you create or edit a user password using JXplorer, this password has to be sent from JXplorer to the underlying directory. To make sure that the password is kept secure: Do not send unencrypted passwords over unsecure connections Do not store passwords in clear text (unencrypted). JXplorer with eTrust Directory If you use JXplorer with eTrust Directory, the following happens when you create a new user password: 1. JXplorer binds to an eTrust Directory DSA. You should use SSL or another secure connection for this binding. 2. In JXplorer, you create a user password, using plain encryption, MD5 or SHA. 3. JXplorer sends the password to the DSA, using the SSL connection. 4. The eTrust Directory DSA hashes the password, then stores it. This means that if you use eTrust Directory and bind to it using SSL, JXplorer does not need to hash the password. The password is kept secure during transmission because the connection to the DSA uses SSL, and the password is stored securely because eTrust Directory hashes it. However, if you do choose to hash the password, an eTrust Directory DSA will recognize the hash format, and can compare hashes to check that the password is correct. Make sure you use the same hash algorithm for the password in both JXplorer and the DSA. 368 Administrator Guide How JXplorer Handles Passwords JXplorer with Other LDAP Directories Not all directories are capable of hashing passwords before they are stored. This means that if you use JXplorer with another LDAP directory, you may need to set JXplorer to hash the password before it is sent to the directory. If you use JXplorer with a directory that doesn't hash passwords, the following should happen when you create a new user password: 1. JXplorer binds to the directory. You should use SSL or another secure connection for this binding. 2. In JXplorer, you create a user password. 3. JXplorer hashes the password using MD5 or SHA. 4. JXplorer sends the hashed password to the directory, using the SSL connection. 5. The directory stores the password exactly as it was received. To set JXplorer to hash a user password, use the drop-down list in the User Password Data dialog. For more information, see Adding a User Password (see page 398). About JXplorer 369 How JXplorer Handles SSL, SASL, and Certificates How JXplorer Handles SSL, SASL, and Certificates You can use Secure Sockets Layer (SSL) authentication to communicate securely with a directory server. Two variants are allowed: SSL with server authentication only (simple SSL) SSL with both client and server authentication (authenticated SSL) Simple SSL authenticates the server only, whereas authenticated SSL authenticates both the client and the server. Both variants require the client to be initialized with the trusted public certificate of the directory server, or the public certificate of the directory server's certificate authority. The trusted public certificates of servers are stored in the cacerts keystore file, located in the security directory, under JXplorer. In addition to the above, Authenticated SSL requires the registration of the client's trusted public certificate (or the public certificate of the client's certificate authority) with the directory server, and use of the client's private key. Trusted public certificates and private keys of clients are stored in the clientcerts keystore file, located in the security directory, under JXplorer. When you add or delete a certificate, or private key, the keystore files are updated and encrypted. You can set a password to stop unauthorized changes to these files. 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. 370 Administrator Guide How JXplorer Handles SSL, SASL, and Certificates 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. Client-authenticated SSL also 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. A demonstration client certificate marjorie.pem is provided in the security directory. eTrust Directory can 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. 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 tool, such as eTrust® PKI or Open SSL, to produce a PKCS8 private key. Manage 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. JXplorer 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 keytool - Key and Certificate Management Tool (http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html). About JXplorer 371 How JXplorer Handles SSL, SASL, and Certificates How Certificates Are Stored By default, the trusted public certificates of servers and certificate authorities are stored in the cacerts keystore file, and the trusted public certificates and private keys of clients are stored in the clientcerts keystore file, which are located in the JXplorer security directory. However, you can change the location and type of the keystore file. See the online help for instructions. How to Decide Where to Store Certificates If you want to use Secure Sockets Layer (SSL) authentication to communicate securely with a directory server, you must add the trusted public certificate of the directory server, or the public certificate of the directory server's certificate authority, to the cacerts keystore file. If you want to strengthen the security and validate the client as well, you must add the client's trusted public certificate (or the public certificate of the client's certificate authority), and the corresponding private key, to the clientcerts keystore file. How to Work with Private Keys The password protecting the client's private key must be the same as that used to protect the clientcerts keystore file; therefore, you cannot change the keystore password after entering the private key password. If you want to change the keystore password, you must export the private key first, change the keystore password, and then re-import the private key into the keystore. Private keys can only be imported as a special type of password-protected file called pkcs8. The password of the private key must be the same as that protecting the keystore. How to Work with Public Keys The cacerts keystore file has a default password of changeit; the clientcerts keystore file has a default password of passphrase. For instructions for setting a new password to stop unauthorized access to these files, see the online help 372 Administrator Guide JXplorer Logging JXplorer Logging 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. To change the level and target of the logging, use the Advanced Options dialog. For more information, see Set the Logging Level (see page 421) and Set the Logging Method (see page 422). Customize JXplorer You can customize the following JXplorer features: HTML templates Logging and tracing Directory tree icons You can also create plugin editors for binary files and entries. For information about customizing JXplorer, see the eTrust Directory Developer Guide. 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. About JXplorer 373 LDAP and Directory Resources LDAP and Directory Resources For more information about JXplorer See the following: The eTrust Directory Developer Guide The JXplorer API, which is installed at: – Windows: %DXHOME%\..\jxplorer\api – UNIX: $DXHOME/../jxplorer/api The JXplorer page on SourceForge (http://sourceforge.net/projects/jxplorer) Customer Support at http://ca.com/support (http://ca.com/support). For more information about Java See the following: Java home page (http://java.sun.com/) API Specification for Java 2 Standard Edition 1.4.2 (http://java.sun.com/j2se/1.4.2/docs/api/) Java naming and directory interface (JNDI) page (http://www.java.sun.com/products/jndi/index.html) For information about LDAP See the Request For Comments (RFC) documents, especially rfc2251 to rfc2256, at the RFC page on the IETF home page (http://www.ietf.org/rfc/). 374 Administrator Guide Chapter 12: Using JXplorer This section contains the following topics: Connect (see page 375) Search the Directory (see page 380) Display Directory Information (see page 386) Work with Directory Entries (see page 388) Work with Attributes (see page 395) Add Binary Files (see page 400) Launch and Save Binary Files (see page 403) Import and Export Using LDIF Files (see page 405) Manage Certificates (see page 408) Manage Bookmarks (see page 413) Configure JXplorer (see page 415) Connect This section describes how to start JXplorer, connect to a directory using LDAP or DSML, and how to disconnect. It also describes how to save connections details in a template. Start JXplorer You can run JXplorer on Windows, UNIX and Linux computers. To start JXplorer on Windows Click Start on the taskbar, and then choose Programs, Computer Associates, eTrust, eTrust Directory, JXplorer. To start JXplorer on UNIX or Linux Issue the following command from the JXplorer directory: ./jxstart.sh Using JXplorer 375 Connect Connect to a Directory through LDAP This section describes how to connect to a directory using LDAP. You can also use JXplorer to connect to a directory using DSML. For more information, see Connect to a Directory through DSML (see page 377). To connect to a directory 1. From the JXplorer main window, do one of the following: Click on the button bar. From the File menu, choose Connect. The Open LDAP/DSML Connection dialog appears. 2. (Optional) If you want to connect using a pre-defined template, select the template from the Use a Template drop-down list, and then click OK. 3. Enter the following connection settings: Host The name of the computer running the directory server Port The port on which the directory server listens for connections. You can find the port number in the knowledge configuration files. Protocol The protocol version for this connection. The default is LDAP v3. Base DN (Optional) The base DN of the entry in the tree to which you want to connect. Enter no spaces. 4. (Optional) Click the Level drop-down list, select the security level with which you want to connect. For more information, see Security Levels for LDAP Connections (see page 334). 5. (Optional) To save the details in a template, click Save, enter a template name, and then click OK. Note: The template is saved at the end of the list. 6. Click OK. 376 Administrator Guide Connect Connect to a Directory through DSML JXplorer can use DSML to let it connect to DSML web services. This section describes how to connect to a directory using DSML. You can also use JXplorer to connect to a directory using LDAP. For more information, see Connect to a Directory through LDAP (see page 376). By default, the DSML server connects to the Router DSA on the local computer. For more information about the DSML Server, see Using the DSML Server (see page 503). To connect to the Router DSA using the DSML Server supplied with eTrust Directory 1. Open JXplorer, and click to open the Open LDAP/DSML Connection dialog. 2. At the bottom of the dialog, select the DSML template. This template automatically populates the dialog. 3. Check that the URL is as follows: dsml/services/DSML?ldapHost=computername&ldapPort=19289 If you upgraded from an older version of eTrust Directory, the URL may still be dsml-sample/services/DSML. Update the URL if it still has this old value. 4. Click OK. Using JXplorer 377 Connect To connect to a DSA using any DSML server 1. Open JXplorer, and click to open the Open LDAP/DSML Connection dialog. 2. Enter the following connection settings: Host The name of the computer running the DSML server Port The port on which the DSML server listens for connections. Protocol DSML v2 DSML Service The path to the DSML server. Base DN (Optional) The DN of the entry in the tree that you want displayed 3. Click OK, then browse the directory as usual. Disconnect from a Directory To disconnect from a directory, do one of the following Click on the button bar From the File Menu, choose Disconnect 378 Administrator Guide Connect Save Connection Details in a Template If you regularly connect to a particular directory, it may be useful to save the connection details in a template. To save connection details in a template 1. From the JXplorer main window, do one of the following: Click on the button bar. From the File menu, choose Connect. The Open LDAP/DSML Connection dialog appears. 2. In the connection dialog, enter the details for connecting to the directory. 3. Click Save, enter a template name, and then click OK. The template has been saved. You can now click OK on the Open LDAP/DSML Connection to connect to the directory, or you click Cancel to close the dialog. The template is saved at the end of the list. If you want to use this template to connect to the directory now, you must select it from the Use a Template drop-down list. To connect to a directory using a template 1. From the JXplorer main window, open the Open LDAP/DSML Connection dialog. 2. In the Use a Template area, select a template from the drop-down list. 3. Click OK. To make a template the default 1. From the JXplorer main window, open the Open LDAP/DSML Connection dialog. 2. In the Use a Template area, select the template from the drop-down list. 3. Click Default. This template will now be selected by default when the Connection dialog is opened. Using JXplorer 379 Search the Directory Search the Directory You can use JXplorer to run a quick or complex search on your directory. This section describes how to run these searches, how to set up search filters, and how to determine the attributes to be returned. Run a Quick Search The Quick Search Bar allows you to execute a simple single-attribute search: To perform a simple search 1. From the Attribute List, select a search attribute or enter a new one. Note: Any changes or additions to this list are saved when JXplorer shuts down. 2. From the list of search operators, select the matching relationship for your search: 3. Enter the search criteria in the Search Term text box. 4. Click the Quick Search button. For a list of search operators, see Search Operators (see page 341). 380 Administrator Guide Search the Directory Run a Complex Search A complex search enables you to search the full DIT, or use the currently selected entry as the search base distinguished name (DN). It also allows you to create search filters that comply with LDAP, and join them together, as per RFC 2254. For more information about RFC documents, see http://www.rfc- editor.org/rfc/. To perform a complex search 1. Do one of the following to open the Search dialog: From the Search menu, choose Search Right-click an entry in the DIT, and then select Search from the drop- down list Press Ctrl + F 2. Enter the DN of the subtree you want to search in the Start Searching From text box. 3. (Optional) Select the Resolve Aliases While Searching check box if you want to return alias entries for subordinate entries of the base object. 4. (Optional) Select the Resolve Aliases When Finding Base Object check box if you want to return alias entries while locating the base object of the search. If you choose to resolve aliases while searching (Step 3) and when finding the base object (Step 4), all aliases are resolved; however, if you do not choose either option, no aliases are resolved. 5. (Optional) From the Select Search Level list, select one of the following: Search Full Subtree if you want to search the whole of the DIT from the current entry down Search Next Level if you want to search one level down from the current entry Search Base Object if you want to search the selected entry only 6. (Optional) From the Information to Retrieve list, select a Return Attribute list to tell the search to return a list of nominated attribute values. To create a Return Attribute list, choose Return Attribute lists from the Search menu. 7. From the Build Filter tab, select an attribute from the drop-down list. 8. Select a function from the drop-down list. 9. Enter the search criteria in the empty text box. Using JXplorer 381 Search the Directory 10. Click More, select an operator from the drop-down list, and repeat steps 6 through 8 until you have completed the filter. To view the current filter in LDAP format, click View. To delete the last line of the filter, click Less. 11. (Optional) To negate the entire filter, select the Not check box. 12. (Optional) To save the filter, enter a name in the Filter Name text box, and then click Save. You must save the filter if you want to join it to another filter. When you have saved the filter you can load it from the Search dialog by clicking Load. If you want, you can join this filter to another pre-defined filter to create a more complex search. 13. Click Search to execute the search. To repeat a saved search, you can select it from the Search Menu. If you receive an error indicating that a search limit is exceeded, you get a partial result. To set the search limits, choose Advanced Options from the Options menu and click the Search Limits tab. For more information, see Set Search Limits (see page 419). 382 Administrator Guide Search the Directory Save a Search as a Filter If you plan to use the same search more than once, you can save it as a filter. This lets you run it later without having to create it again. A complex search comprises one or more filters. If you save the filters when you define a search, you can create an even more complex search by joining them together. Any filter can be joined; you can also join joined filters. To save a search as a filter 1. In the Search dialog, set up a complex search. 2. Enter a name in the Filter Name text box (at the top of the dialog). 3. Click Save (at the bottom of the dialog). To edit a filter 1. In the Search dialog, click Edit next to the filter that you want to edit. 2. When you have made the changes, select the Join Filters tab to continue. To join filters 1. In the Search dialog, choose the Join Filters tab. 2. Select the filter that you want to join from the drop-down list and click More. 3. Select an operator from the drop-down list and repeat steps 1-2 until you have joined all of the filters you want. 4. (Optional) To negate the entire filter, select the Not check box. 5. (Optional) To save the joined filters, enter a name in the Filter Name text box, and then click Save. To delete a filter 1. From the Search Menu, choose Delete Filter. 2. From the Delete Filter dialog, choose the filter that you want to delete, and then click Delete. A confirmation dialog is displayed. If the filter is used by a joined filter, the dialog lists the joined filters, which will also be deleted. 3. If you want to delete the filter (and any dependant joined filters), click Yes. Using JXplorer 383 Search the Directory Edit Return Attributes Lists The Return Attributes dialog lets you manage lists that tell a search to return a list of nominated attribute values. To create a return attributes list 1. To select an attribute to return, double-click it in the Available Attributes list box. 2. Repeat Step 1 for the required attributes. If you want to remove an attribute from your selection, double-click it in the Selected Attributes list box. If you plan to sort the results, you should return the attributes that you plan to use for sorting. For example, if you plan to sort by email address, ensure that the mail attribute is returned in the search result. 3. To save your list, specify a name for the list in the Name field and click Save. To edit a return attributes list 1. Click Load to display the Select List box. 2. Select the required list from the drop-down list box. 3. Click OK. 4. Update your selection. 5. To save your changes, click Save and click OK in response to the List Exists prompt. To delete a return attributes list 1. Click Load to display the Select List box. 2. Select the required list from the drop-down list box. 3. Click OK. 4. Click Delete, and then click OK in response to the Delete List? prompt. 384 Administrator Guide Search the Directory View the Search Results The Search Results window is displayed when you use a Return Attribute list in the search. It displays the values found for the attributes to be returned. You can right-click a value and choose Go to Entry to display the corresponding entry in JXplorer. To sort the search results You can sort your result according to the returned values in a selected column. To sort your result, click the heading of a column. You can also reorder columns by dragging the heading of a column to the required position. To keep a record of the search results To keep a record of your result, you can: Click Print to send it to a printer. Click Save to save it to a file as comma-separated values (CSV). Using JXplorer 385 Display Directory Information Display Directory Information This section describes how to display entries, and navigate the directory information tree (DIT). Display Entry Details When you select an entry in the Directory Information Tree (DIT), the results are displayed in the right pane. You can choose to display the results in HTML (through a template) or a table. To display the details of a directory entry 1. Locate the entry that you want to view in the DIT. 2. Do one of the following: Click the entry Use the arrow keys to select the entry The details are displayed in the Entry Display Pane. 3. Select one of the following: HTML View tab, if you want to display the results in a template Table Editor tab, if you want to display the results in a table The Table Editor displays all possible attributes, whereas the template only displays those attributes that have been tagged for display. The Table Editor also provides the Properties button, which you can click to display the operational attributes such as the date of the last modification. Display Schema You can use JXplorer to view the schema of the directory to which you are connected. However, you cannot use JXplorer to edit the schema. Note: Not all servers implement full schema publishing; therefore, some details may not be available. To display the schema Do one of the following: In the left pane, click the Schema tab. In the left pane, click on World, which is always the top entry in the tree pane on the left. 386 Administrator Guide Display Directory Information Print an Entry This option allows you to print the details of a directory entry. To print an entry 1. From the Directory Information Tree (DIT), select the entry that you want to print. 2. Position the cursor in the Entry Display, situated to the right of the screen. 3. Do one of the following: Click on the button bar From the File Menu, choose Print Abort an Action This option allows you to abort an action, for example, a complex search, rather than wait until it has finished. Note: The button bar changes to red when JXplorer is performing an action. To abort an action 1. Do one of the following: Click on the button bar From the Tools Menu, choose Stop Action 2. From the dialog, select the action that you want to cancel, and then click the Delete Query button. 3. Click the Exit button to close the dialog. Using JXplorer 387 Work with Directory Entries Work with Directory Entries You can use JXplorer to add, create, delete, and edit entries in a directory. If you plan to make many changes to a directory, consider using the DXtools and scripting. For information about the DXtools, see Using DXtools (see page 313) . Add a New Entry This option allows you to add a new entry to the directory. If you are adding a large number of entries, you should either perform a bulk load, or import an LDIF file that contains the entries. To add a new entry 1. From the Directory Information Tree (DIT), select the parent entry, that is, the level under which you want to insert the new entry. For example, if you want to add a person to the Administration Department, select Administration. 2. Do one of the following: Click on the button bar. From the Edit Menu, choose New. Right-click the parent entry in the DIT, and then select New from the drop-down list. Press Ctrl + N. 3. (Optional) Select the Suggest Classes check-box if you want JXplorer to display the compulsory object classes for the new entry. 4. Check that the distinguished name (DN) of the parent entry in the Parent DN text box is correct. 5. Enter the relative distinguished name (RDN) of the new entry in the Enter RDN text box. For example, if you want to add John Smith to the Administration Department, you may enter cn=John SMITH. JXplorer displays the mandatory object classes for this entry in the Selected Classes pane. 6. (Optional) If you want to add another mandatory object class, select the item from the Available Classes pane, and then click the Add button. 7. (Optional) Repeat step 6 for all required object classes, and then click OK. 8. Enter the attribute values for the new entry. If the entry contains any mandatory attributes, you must enter values for these attributes. 388 Administrator Guide Work with Directory Entries For more information on adding attribute values, see Add an Attribute Value (see page 395). 9. If the details are correct, click the Submit button. Note: If you do not click the Submit button, the details will not be saved. Copy an Entry This option allows you to copy an entry or a subtree to another location in the Directory Information Tree (DIT). To copy an entry or a subtree 1. From the Directory Information Tree (DIT), select the entry, or parent of the subtree that you want to copy. 2. Do one of the following: Click on the button bar. From the Edit Menu, choose Copy Branch. Right-click the parent entry in the DIT, and then select Copy Branch from the drop-down list. Press Ctrl + O. 3. From the Directory Information Tree (DIT), select the parent entry under which you want to insert the entry. For example, if you want to insert the entry in the Administration Department, select Administration. Important! This procedure copies the selected subtree and all entries. If you want a dialog to appear before a change to the directory is implemented, see Set the Safety Mode (see page 423). 4. Do one of the following: Click on the button bar. From the Edit Menu, choose Paste Branch. Right-click the parent entry, and then select Paste Branch from the drop-down list. Press Ctrl + P. Using JXplorer 389 Work with Directory Entries Move an Entry You can move an entry or subtree from one location in the directory to another. To move an entry or a subtree in one step In the tree pane on the left, drag the entry from its old location to its new location. To move an entry or a subtree in two steps 1. From the tree pane on the left, select the entry or the parent of the subtree that you want to move. 2. Do one of the following: Click on the button bar. From the Edit Menu, choose Cut Branch. Right-click the parent entry in the DIT, and then select Cut Branch from the drop- down list. Press Ctrl + U. Important! This procedure removes the selected subtree and all entries. If you want a dialog to appear before a change to the directory is implemented, see Set the Safety (see page 423)Mode. 3. From the DIT, select the parent entry under which you want to move the entry or subtree. For example, if you want to move the entry to the Administration Department, select Administration. 4. Do one of the following: Click on the button bar. From the Edit Menu, choose Paste Branch. Right-click the parent entry, and then select Paste Branch from the drop-down list. Press Ctrl + P. 390 Administrator Guide Work with Directory Entries Rename an Entry This option allows you to rename an entry in the tree. When you rename an entry, naming attribute is updated, and the distinguished names of the entries in the subtree below the parent are also updated. Note: If this entry is referenced in any search templates, connection templates, or queries, you will have to edit them manually. For descriptions of how to work directly with naming attributes, see Add a Naming Attribute (see page 395) and Remove a Naming Attribute (see page 396). To rename an entry 1. From the Directory Information Tree (DIT), select the entry that you want to rename. 2. Do one of the following: Click on the button bar. From the Edit Menu, choose Rename. Right-click the parent entry in the DIT, and then select Rename from the drop-down list. Press Ctrl + R. 3. Type over the old entry name with the new name, and press Enter. Using JXplorer 391 Work with Directory Entries Delete an Entry This option allows you to delete an entry or a subtree in the directory information tree. To delete an entry or a subtree 1. From the tree pane on the left, select the entry or the parent of the entry that you want to delete. Important! This deletes the selected subtree and all entries. If you want a dialog to appear before a change to the directory is implemented, see Set the Safety Mode (see page 423). 2. Do one of the following: Click on the button bar From the Edit Menu, choose Delete Right-click the parent entry in the DIT, and then select Delete from the drop-down list Press Ctrl + D Refresh Entries For efficiency, the browser caches entries, unless you specifically request to reload them from the directory. To refresh the data in a single entry Select the Refresh option. To refresh the tree Select the Refresh Tree option. 392 Administrator Guide Work with Directory Entries Create an Alias An alias is similar to a shortcut. It is used to link different parts of the Directory Information Tree (DIT). For example, a person may work in the Human Resources department, but is also Manager of the Sporting Committee; therefore, you may want to link the two entries together to save re-typing the information, and maintaining two entries. The easiest way to create an alias is to copy an entry and then paste it to another part of the DIT. When you copy an entry, you can choose to copy the full DN. Note: When performing a search, you can choose to return alias entries as well. For more information, see Edit Return Attribute Lists (see page 384). To create an alias 1. From the Directory Information Tree (DIT), select the entry that you want to copy. 2. Do one of the following: Click or on the button bar. From the Edit Menu, choose Copy Branch or Copy DN. Right-click the parent entry, and then select Copy Branch or Copy DN from the drop-down list. Press Ctrl + O to copy the entry or Ctrl + Y to copy the DN. 3. From the DIT, select the parent entry under which you want to place the alias. 4. Do one of the following: Click on the button bar. From the Edit Menu, choose Paste Alias. Right-click the parent entry, and then select Paste Alias from the drop- down list. Using JXplorer 393 Work with Directory Entries Add a Class to an Entry To add a class to an entry 1. Select the entry in the Directory Information Tree (DIT), and make sure you are in Table view. 2. Click Change Class. 3. From the displayed Set Entry Object Classes dialog, select a class, click Add, and then click OK. The attributes types in the new class become available in the Table Editor. Note: If you add a class to a virtual entry such as c=AU in Democorp, it will become a real entry. 394 Administrator Guide Work with Attributes Work with Attributes Each entry in a directory consists of attributes. An attribute comprises the attribute type identification, for example, telephoneNumber, and one or more attribute values, for example, 02 9923 1234. Add an Attribute Value To add an attribute value 1. Select the entry in the Directory Information Tree (DIT) to which you want to add an attribute value. If an attribute value already exists, go to Step 2. Otherwise, go to Step 3. 2. Right-click the mouse, and select Add Another Value from the drop-down list. 3. Position the cursor in the Value column, alongside the attribute type to which you want to add a value. If you are adding an address attribute, the Postal Address Editor appears. Go to Edit Postal Addresses (see page 399). If you are adding an audio file, the Audio dialog appears. Go to Add an Audio File (see page 401). If you are adding a file that can be launched, a dialog pertaining to that file type appears. Go to Launch Binary Files (see page 403). If you are adding a photo, the jpegPhoto dialog appears. Go to Add a Photo (see page 402). If you are adding a time, the Generalized Time dialog appears. Go to Set Generalized Time (see page 399). For all other attribute types, go to step 4. 4. Enter the attribute value. 5. (Optional) Repeat steps 1-4 for all new attribute values. 6. Click the Submit button. Add a Naming Attribute To add a naming attribute 1. In the table editor on the right, right-click on an attribute 2. Select Make Naming Attribute. The attribute becomes bold, to show that it is now a naming attribute. Using JXplorer 395 Work with Attributes Remove a Naming Attribute If an entry has more than one naming attribute, you may remove one. These instructions describe how to make a naming attribute a non-naming attribute, If you want to delete the attribute from the entry, you must do that afterwards. To remove a naming attribute 1. In the table editor on the right, right-click on an attribute. 2. Select Remove Naming Attribute. The bold formatting of the attribute is removed, to show that it is no longer a naming attribute. Delete an Attribute or Value Each entry in a directory consists of attributes. An attribute comprises the attribute type identification, for example, telephoneNumber, and one or more attribute values, for example, 02 9923 1234. This option allows you to delete an attribute type or attribute value. If the value deleted is the last value of a given attribute, the attribute is also deleted. It is not possible to delete a mandatory attribute, or the last value of a mandatory attribute. Mandatory elements are shown in bold. At least one value must exist for the entry to be valid. Note: You can only delete attribute types in the Table Editor (see page 332). To delete an attribute or value 1. Select the entry in the Directory Information Tree (DIT) from which you want to delete an attribute type or value. 2. Do one of the following: From the Table Editor, right-click the attribute type or value that you want to delete, select Delete Value from the drop-down list, and then click the Submit button From HTML View, select the value that you want to delete, press the Delete key on your keyboard, and then click the Update button. 396 Administrator Guide Work with Attributes Edit an Attribute Value Each entry in a directory consists of attributes. An attribute comprises the attribute type identification, for example, telephoneNumber, and one or more attribute values, for example, 02 9923 1234. This option allows you to edit an attribute value. Note: You can only edit binary values in the Table Editor (see page 332). To edit an attribute value 1. Select the entry in the directory information tree that you want to edit. 2. Do one of the following: From HTML View, select the value that you want to edit. Go to step 3. From the Table Editor, position the cursor in the Value column, and then select the value that you want to edit. – If you are editing an address attribute, the postalAddress dialog appears. See Edit Postal Addresses (see page 399). – If you are editing an audio file, the Audio dialog appears. Add an Audio File (see page 401). – If you are editing a photo, the jpegPhoto dialog appears. See Add a Photo (see page 402). – If you are editing a time, the Generalized Time dialog appears. Set Generalized Time (see page 399). For all other attribute types, go to step 3. 3. Re-enter the value. 4. Click the Submit button. Using JXplorer 397 Work with Attributes Add a User Password The User Password Data dialog allows you to add or change a user password. The dialog appears when you select the userPassword attribute type in the Table Editor (see page 332). Note: Access to a record is controlled via the access control settings in the directory's configuration file; therefore, you do not have to enter the existing password before changing it. To add or change a password 1. Ensure that you are in Table Editor view. 2. Select the entry in the Directory Information Tree (DIT) to which you want to add or change a password. 3. Click in the Value column next to the attribute type userPassword. 4. Enter the password in the Enter Password text box. 5. Re-enter the password in the Re-enter Password text box. 6. Select one of the following password encryption methods from the drop- down list: plain The password is not hashed before it is sent to the directory. Use this option if you use eTrust Directory. md5 Hashes the password using MD5 before the password is sent to the directory sha Hashes the password using SHA-1 before the password is sent to the directory For more information about these options, see Password Hashing (see page 368). 7. Click OK, then click the Submit button to save the password to the directory. 398 Administrator Guide Work with Attributes Edit Postal Addresses The Postal Address Editor allows you to add and edit all attributes that contain an address, for example, homePostalAddress. The dialog appears when you select an ad (see page 332)dress field in the Table Editor. It allows you to enter the details as they will appear in a template, that is, with the relevant line breaks and spacing. To add or edit a postal address attribute 1. Ensure that you are in Table Editor view. 2. Select the entry in the Directory Information Tree (DIT) to which you want to add or change an address. 3. Position the cursor in the Value column, alongside the address attribute type. 4. From the Postal Address Editor dialog, enter the address in the text box as you want it to display, and click OK. Note: To revert to the last saved value, click the Reset button. 5. Click the Submit button to save the changes to the directory. Set Generalized Time The Generalized Time dialog allows you to easily add a value to an attribute that contains the syntax generalizedTime. The dialog appears when you select the attribute in The Table Editor (see page 332). To set generalized time 1. Ensure that you are in Table Editor view. 2. Select the entry in the Directory Information Tree (DIT) to which you want to set generalized time. 3. Position the cursor in the Value column, alongside the time attribute type. 4. From the Generalized Time dialog, do one of the following: Click the Now button to display the current time Enter the date and time manually using the drop-down lists Note: If you enter a day and a month, you must select the Month first; this displays the Days in the drop-down list. 5. (Optional) If you want to show coordinated universal time (UTC), select the UTC check box. A 'Z' is added to the end of the time, for example, 20010925104130.999Z. 6. Click OK. 7. Click the Submit button to save the changes to the directory. Using JXplorer 399 Add Binary Files Add Binary Files Some attribute values, for example, certificates, are not text; therefore, they cannot be displayed or edited in the Table Editor (see page 332). JXplorer stores these values as binary data. Add a Binary File to an Attribute You can use the Binary Data dialog to import binary values from an external file, and also to export the binary value from an attribute. To load a binary file into an attribute 1. In the Table Editor view of an entry, click in the Value column of a binary attribute. 2. The Binary Data dialog opens. 3. Navigate to the file you want to import and select the file name. 4. Make sure that the Load option is selected, then click OK. 5. Click OK at the message box, then click Submit to save the data. Save a Binary File To save binary data from an attribute 1. In the Table Editor view of an entry, click in the Value column of a binary attribute that has a binary file. 2. The Binary Data dialog opens. 3. Navigate to the directory where you want to save the exported file.. 4. Type a file name into the File Name field. 5. Select the Save option, then click OK. 6. Click OK at the message box. The file has been saved to the location you chose. 400 Administrator Guide Add Binary Files Add an Audio File JXplorer allows you to import an audio file into the directory, and export it using your system's file browser. You can also play the audio file from within JXplorer. All audio file formats can be imported, but only some formats can be played. For a list of formats, see Work with Audio Files (see page 351). To add an audio file 1. Ensure that you are in Table Editor view. 2. In the tree, select the entry to which you want to add an audio file. 3. Find the audio attribute, and click in the Value column to its right. The Audio dialog opens. 4. From the Audio dialog, click Load. 5. Select the audio file that you want to import, and then click Open. Note: If you want to play the audio file, click Play. Click Stop to stop playing the audio file. 6. Click OK. 7. Click Submit to save the audio file to the directory. To launch an audio file 1. Open the Audio dialog as described previously. 2. Click Play. To save an audio file 1. Click on an audio value as described previously. 2. Click Save, then navigate to the directory in which you want to save the file. 3. Click Save. The audio file is saved to the selected directory. Using JXplorer 401 Add Binary Files Add a Photo JXplorer allows you to import a photo in .JPEG format into the directory, and export it using your system's file browser. To add a photo 1. Ensure that you are in Table Editor view. 2. In the tree, select the entry to which you want to add an audio file. 3. Find the jpegValue attribute, and click in the Value column to its right. The jpegValue dialog opens. 4. From the jpegValue dialog, click Load. 5. Select the photo that you want to import, and then click Open. 6. Click OK. 7. Click Submit to save the photo to the directory. To save a photo 1. Click on a jpegPhoto value as described previously. 2. Click Save, then navigate to the directory in which you want to save the file. 3. Click Save. 4. The photo is saved to the selected directory. 402 Administrator Guide Launch and Save Binary Files Launch and Save Binary Files JXplorer provides the odMultimedia class that contains attribute types that allow you to launch and save files of the following formats: odMovieAVI Play .avi files odDocumentDOC Open .doc files odMusicMID Play .mid files odSoundWAV Play .wav files odSpreadSheetXLS Open .xls files Add the odMultimedia Class to an Entry To add the odMultimedia schema to an entry 1. Select the entry in the Directory Information Tree (DIT), and make sure you are in Table view. 2. Click Change Class. 3. From the displayed Set Entry Object Classes dialog, select odMultimedia, click Add, and then click OK. The following attributes types become available in the Table Editor: odMovieAVI odDocumentDOC odMusicMID odSoundWAV odSpreadSheetXLS Using JXplorer 403 Launch and Save Binary Files Add a Multimedia File To add a file using an odMultimedia attribute type 1. In the Table Editor view of an entry, click in the Value column of one of these binary attributes: odMovieAVI odDocumentDOC odMusicMID odSoundWAV odSpreadSheetXLS 2. The Binary Data dialog opens. 3. Navigate to the file you want to import and select the file name. 4. Make sure that the Load option is selected, then click OK. 5. Click OK at the message box, then click Submit to save the data. Launch a Binary File from an odMultimedia Attribute Type JXplorer can only launch a binary file if your computer already has an application that can use it. For example, you may not be able to launch XLS and DOC files on UNIX computers. To launch a binary file from an odMultimedia attribute type 1. Select the entry in the Directory Information Tree (DIT) to that contains the file you want to launch. 2. Ensure that you are in the Table Editor view. 3. Find the attribute that contains the file, then click in the Value column of that attribute. 4. In the displayed dialog, click Launch. The file appears in the appropriate application. 404 Administrator Guide Import and Export Using LDIF Files Import and Export Using LDIF Files JXplorer lets you use LDIF files to save and enter directory information, both with and without an LDAP connection to a directory. 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. For more information, see the IETF home page (http://www.ietf.org). Export the Full Tree To export the full DIT into an LDIF file 1. Select LDIF, Export Full Tree The LDIF dialog displays the current Root Distinguished Name (DN). If you want to change the root DN in the LDIF file, go to step 2. If you want the LDIF file to retain this DN, go to step 3. 2. Enter the new root DN in the New Root DN text box, with no spaces. For example, if the Root DN is ou=Finance,o=Democorp,c=au, and you want to rename the organizational unit Marketing, enter ou=Marketing,o=Democorp,c=au. 3. Click OK. 4. Select the folder in which you want the LDIF file saved, and then enter a file name in the File Name text box. Note: If you create a new folder, the system names it New Folder. 5. Click Save. Using JXplorer 405 Import and Export Using LDIF Files Export a Subtree To export a subtree into an LDIF file 1. Select LDIF, Export Subtree. The LDIF dialog displays the current Root Distinguished Name (DN). If you want to change the root DN in the LDIF file, go to step 2. If you want the LDIF file to retain this DN, go to step 3. 2. Enter the new root DN in the New Root DN text box, with no spaces. 3. For example, if the Root DN is ou=Finance,o=Democorp,c=au, and you want to rename the organizational unit Marketing, enter ou=Marketing,o=Democorp,c=au. 4. Click OK. 5. Select the folder in which you want the LDIF file saved, and then enter a file name in the File Name text box. Note: If you create a new folder, the system names it New Folder. 6. Click Save. Import an LDIF File When JXplorer is connected to a directory, you can import the values from an LDIF file directly into the directory. If you want to check the values before importing them, you can view the entries offline. For more information, see Use LDIF Files Offline (see page 407). To import an LDIF file 1. From the Directory Information Tree (DIT), select the parent entry, that is, the level under which you want to insert the LDIF file. 2. From the LDIF Menu, choose Import File. 3. Select the LDIF file that you want to import, and then click the Open button. Note: You may need to refresh the browser to see the change. 406 Administrator Guide Import and Export Using LDIF Files Use LDIF Files Offline JXplorer allows you to import an LDIF file without an LDAP connection to a directory server. This can be useful for reviewing data before committing it to a production environment, or performing a stand-alone demonstration. To import an LDIF file while offline 1. From the LDIF Menu, choose View Offline. 2. Select the LDIF file that you want to view, and then click the Open button. JXplorer loads the LDIF files, which you can now view. Using JXplorer 407 Manage Certificates Manage Certificates You can use Secure Sockets Layer (SSL) authentication to communicate securely with a directory server. Two variants are allowed: SSL with server authentication only (simple SSL) SSL with both client and server authentication (authenticated SSL) Add a Certificate When you add a certificate, the keystore files are updated and encrypted. To add a certificate 1. Do one of the following: If you are setting up server authenticated SSL, from the Security Menu, choose Trusted Servers and CAs. If you are setting up client authenticated SSL, from the Security Menu, choose Client Certificates. 2. Click the Add Certificate button. 3. From the Open dialog, choose the trusted public certificate that you want to add to the keystore, and then click the Open button. 4. Confirm that this is the certificate that you want to add, and then click OK. 5. Enter a name for the certificate, and then click OK. 6. Enter the keystore password, and then click OK. 7. Click OK to close the dialog. 408 Administrator Guide Manage Certificates View a Certificate The trusted public certificates of servers are stored in the cacerts keystore file, and the trusted public certificates (and private keys) of clients are stored in the clientcerts keystore file. This option allows you to view trusted public certificates currently held in the keystores, and copy the details to another location. To view a certificate 1. Do one of the following: From the Security Menu, choose Trusted Servers and CAs, select the certificate that you want to view, and then click the View Certificate button. From the Security Menu, choose Client Certificates, select the certificate that you want to view, and then click the View Certificate button. From the Table Editor, click in the Value column alongside the certificate that you want to view. The system displays the General certificate details. Click the Details and Certification Path tabs to display other details. If you want to copy the certificate to a file, go to step 2. If you do not want to copy the certificate to a file, go to step 4. 2. To copy the certificate to a file, click the Copy to File button. 3. From the Save dialog, enter a name for the certificate in the File Name text box, and then click Save. 4. Click OK to close the Certificate dialog. 5. Click OK to close the dialog. Using JXplorer 409 Manage Certificates Delete a Certificate The trusted public certificates of servers are stored in the cacerts keystore file, and the trusted public certificates (and private keys) of clients are stored in the clientcerts keystore file. This option allows you to delete trusted public certificates from the keystores. To delete a certificate 1. Do one of the following: If you want to delete a trusted server certificate, from the Security Menu, choose Trusted Servers and CAs. If you want to delete a trusted client certificate, from the Security Menu, choose Client Certificates. 2. Select the trusted public certificate that you want to delete, and then click the Delete Certificate button. 3. From the Confirm Certificate Deletion dialog, click OK. If you are deleting a trusted server certificate, go to step 5. If you are deleting a trusted client certificate, go to step 4. 4. Enter the keystore password, and then click OK. 5. Click OK to close the dialog. Add a Private Key To add a private key 1. From the Security Menu, choose Client Certificates. 2. Select the client certificate to which you want to add the private key, and then click the Set Private Key button. 3. Select the private key that you want to add to the client certificate, and then click the Open button. 4. Enter the keystore password, and then click OK. 5. Click OK to close the dialog. 410 Administrator Guide Manage Certificates Export a Private Key To export a private key 1. From the Security Menu, choose Client Certificates. 2. Select the client certificate that contains the private key that you want to export, and then click the Export Private Key button. 3. Enter the name of the file to which you want to export the private key, and then click the Open button. 4. Enter the keystore password, and then click OK. 5. Click OK to close the dialog. Change the Keystore To change a keystore 1. From the Security Menu, choose Advanced Keystore Options. 2. To change the keystore for trusted public certificates of servers, click Load alongside CA/Server Keystore. 3. From the Open dialog, select the new keystore and then click the Open button. 4. Select the CA/Server keystore type from the drop-down list. The default is JKS (Java Keystore). 5. To change the keystore for trusted public certificates and private keys of clients, click Load alongside Client Keystore. 6. From the Open dialog, select the new keystore and then click the Open button. 7. Select the Client keystore type from the drop-down list. The default is JKS. 8. Click OK. Using JXplorer 411 Manage Certificates Set a Keystore Password To set a keystore password 1. Do one of the following: If you are setting a password for the cacerts keystore, from the Security Menu, choose Trusted Servers and CAs. If you are setting a password for the clientcerts keystore, from the Security Menu, choose Client Certificates. 2. Click the Set Password button. 3. Enter the current password in the Enter Old Password text box. 4. Enter the new password in the New Password text box. 5. Re-enter the new password in the Confirm New Password text box, and then click OK. A dialog confirms that the password has been successfully changed. 6. Click OK to close the dialog. 412 Administrator Guide Manage Bookmarks Manage Bookmarks To make it easier to navigate in a large directory, you can bookmark entries that you know you will return to frequently. The Bookmark menu allows you to add, edit and delete bookmarks. To jump to a bookmarked entry, choose the bookmark name from the Bookmark menu. Add a Bookmark 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 1. From the tree on the left, select the entry for which you want to add a bookmark. 2. Do one of the following: From the Bookmark Menu, choose Add Bookmark. Right-click the parent entry in the tree, and then select Add to Bookmarks from the drop-down list. Press Ctrl + B. The Add Bookmark dialog appears. The default bookmark name is the naming attribute of the entry. 3. (Optional) Enter a new name in the Bookmark Name text box. 4. (Optional) Enter a description in the Description text box. 5. Click Save. The bookmark is added to the list of bookmarks on the Bookmark Menu. 6. Click OK to close the confirmation dialog. Using JXplorer 413 Manage Bookmarks Edit a Bookmark 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 edit an existing bookmark 1. From the Bookmark menu, choose Edit Bookmark. 2. Select the bookmark that you want to edit from the Bookmark Name drop- down list, then click OK. 3. Edit the bookmark. 4. Click Save. 5. Click OK to confirm that you want to change the bookmark, then click OK again to close the confirmation dialog. Delete a Bookmark 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 delete a bookmark 1. From the Bookmark Menu, choose Delete Bookmark. 2. Select the bookmark that you want to delete from the Bookmark Name drop-down list. 3. Click OK. 4. Click OK again to confirm that you want to delete the bookmark. The bookmark is deleted from the list of bookmarks on the Bookmark Menu 5. Click OK on the confirmation dialog. 414 Administrator Guide Configure JXplorer Configure JXplorer This section describes how to use the Options menu and the Advanced Options dialog to configure JXplorer. Change Look-and-Feel JXplorer can be displayed with the 'look and feel' of an OS with which you are more familiar. For example, some UNIX users would feel happier displaying JXplorer with a Motif appearance. JXplorer supports the following interfaces: Microsoft Windows (only available on Microsoft platforms) Motif/X-Windows Java To select a viewing interface 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the Look & Feel tab at the top of the dialog. 3. Choose the viewing interface you want. 4. Click Apply. Note: To revert the viewing options back to the last saved version, click the Reset button. Using JXplorer 415 Configure JXplorer Confirm Changes to the Directory Some users like to receive a message after performing an operation to confirm that the operation was successful. This option enables the display of a confirmation dialog when a change has been made to the directory. To enable the confirmation dialog From the Options Menu, select Confirm Table Editor Updates. A check mark appears alongside the option. To disable the confirmation dialog Deselect Confirm Table Editor Updates. The check mark is removed. Now, every time you change an entry, a Confirmation Message dialog appears. 416 Administrator Guide Configure JXplorer Create a Connection Template When you connect to a directory, or perform a complex search, JXplorer allows you to save the details in a template. This is particularly useful if you perform the same task on a regular basis. To create a template 1. Do one of the following: Click on the button bar, to open the Open ldap Connection dialog From the Search Menu, choose either Full Tree, or Current, to open the Advanced Search dialog 2. Enter details, as required. 3. Click Save. 4. At the Replace/Create Template dialog, enter a template name, and then click OK. The template is saved at the end of the list. 5. (Optional) If you want to use this template now, select it from the Use a Template drop-down list, and then click OK. 6. Click Cancel to close the dialog. Make one of the connection templates a default template 1. Create one or more connection templates as describe previously. 2. In the Connection dialog, select one of the templates, then click Default. 3. Next time you open the Connection dialog, the template you chose will be selected by default, so you only need to click OK to connect. Using JXplorer 417 Configure JXplorer Ignore Schema Checking eTrust Directory automatically checks all entries submitted to the directory to ensure that they conform to the directory schema. However, if the network is slow, it may be wise to check the entry via JXplorer, before you send it to the server. To turn off schema checking From the Options Menu, select Ignore Schema Checking. A check mark appears beside the option. To enable schema checking From the Options Menu, deselect Ignore Schema Checking. The check mark is removed. Resolve Aliases While Browsing Aliases are similar to shortcuts and are used in some directories to link different parts of the tree. When you browse the directory, you can choose whether to follow these links and view all of the entry details, or the details of the alias entry, that is, where the alias entry points. This option only affects the navigation. When you search the directory, this option is ignored. To resolve aliases while browsing From the Options Menu, select Resolve Aliases While Browsing. A check mark appears beside the option. To not resolve aliases while browsing From the Options Menu, deselect Resolve Aliases While Browsing. The check mark is removed. 418 Administrator Guide Configure JXplorer Set Search Limits This option allows you to define the maximum number of entries returned from a search, and the time allowed to perform the search. Values can also be set in the server configuration files. If values are set in JXplorer and the server configuration files, the lower of the two values is accepted. To set the search limits 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the Search Limits tab at the top of the dialog. 3. Enter the maximum number of entries to be returned from a search in the LDAP Limit text box. If you set the value to 0, the value set in the server configuration file will apply. 4. Enter the maximum number of seconds allowed before the search request is stopped in the LDAP Timeout text box. If you set the value to 0, the value set in the server configuration file will apply. 5. Click Apply. To revert the search limits back to the last saved version, click the Reset button. Using JXplorer 419 Configure JXplorer Set the Browser for URL Pages This option allows you to indicate to JXplorer how to launch a page when you click a URL link. JXplorer can launch the linked page either internally, or externally in the default web browser. This option is supported on Windows only. To launch URLs in JXplorer 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the URL tab, then select JXplorer. 3. Click Apply. To launch URLs in a web browser 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the URL tab, then select launch. 3. Click Apply. 420 Administrator Guide Configure JXplorer Set the Logging Level JXplorer provides six logging options, ranging from reporting errors only to reporting all operations. To set the logging level 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the Log Level tab. 3. Choose the logging level you want: Severe Logs only those messages indicating a serious failure Warning (Default) Logs messages indicating potential problems and serious failure Info Logs messages indicating potential problems, serious failure, and information messages Fine Logs some trace information Finest Logs a highly detailed trace All + BER Trace Logs all messages plus an LDAP BER communications trace. This is useful for de-bugging directory-client communications problems. The BER tracing is only sent to the console, never to the log file. Note: This logging level may cause JXplorer to run slower. 4. Click Apply. Note: To revert to the logging level last saved, click the Reset button. Using JXplorer 421 Configure JXplorer Set the Logging Method JXplorer provides a number of logging options, ranging from no logging to complete tracing of all LDAP communications. This option allows you to choose the method by which you view these logs. To set the logging method 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the Log Method tab. 3. Choose the logging method you want: None No logging is performed. Console Logging can be viewed via a management console. File Logging details are copied to a file named JX.log in the following directory: Windows: %DXHOME%\..\jxplorer UNIX: $DXHOME/../jxplorer Console and File Logging details can be viewed via a management console; they are also copied to a file in the ../dxserver/logs folder. 4. Click Apply. Note: To revert the logging method back to the last saved version, click the Reset button. 422 Administrator Guide Configure JXplorer Set the Safety Mode A single JXplorer operation can affect thousands of directory entries. As a safety measure, you can choose to have a dialog appear before any changes are implemented, which asks you to confirm your action. To set the safety mode From the Options Menu, select Confirm Tree Operations. A check mark appears alongside the option. To remove the safety mode Deselect Confirm Tree Operation. The check mark is removed. Show and Hide the Toolbars The View menu lets you access the toolbar configuration and refresh options. The button bar and quick search bar are not required for the operation of the browser and if you are short of window space you can hide either or both of these bars. To hide the button bar or search bar 1. Select the View menu. 2. Deselect Show Button Bar or Show Search Bar. Using JXplorer 423 Configure JXplorer Turn Off Password Storage By default, JXplorer stores the passwords used in a single JXplorer session. You can prevent JXplorer from storing passwords. For more information, see Password Storage (see page 367). To stop storing passwords 1. From the Options Menu, choose Advanced Options. The JXplorer Advanced Options dialog appears. 2. Select the Cache Passwords tab. 3. Select No, then click Apply. Note: To revert the password setting back to the last saved version, click Reset. 424 Administrator Guide Chapter 13: Using JXweb This section contains the following topics: About JXweb (see page 426) Get Started with JXweb (see page 428) Search the Directory (see page 432) Create and Delete Entries (see page 435) Modify Entries (see page 440) Change Entry Names (see page 443) Copy and Move Entries (see page 446) Manage Certificates (see page 447) View Schemas (see page 449) Configure JXweb (see page 453) Using JXweb 425 About JXweb About 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 View schemas View certificates Special Characters in Distinguished Names If you must use a special character in the value of a distinguished name (DN) component, escape it with a backslash (\). The following characters are special in DNs: Backslash \ Comma , Double quotation " Greater than > Less than < Pound or hash # Plus + Semicolon ; Space at the beginning or end of a value 426 Administrator Guide About JXweb JXweb Editors JXweb includes attribute editors, which let you edit the values of attributes. Text Editor For most attributes, JXweb lets you edit the attribute value in a Modify section. This is useful for plain text attributes, such as names and telephone numbers: Attribute Name Editor JXweb includes special editors for some attributes names. This means that if you try to edit any of the following attribute names, a special attribute editor appears: userPassword userCertificate odSpreadSheetXLS odSoundWAV odMusicMID odMovieAVI odDocumentDOC Syntax Editor JXweb also includes special attribute editors for some attribute syntaxes. If an entry contains an attribute that is specified by one of the listed OIDs, a special attribute editor appears: 1.3.6.1.4.1.1466.115.121.1.24 Generalized Time 1.3.6.1.4.1.1466.115.121.1.41 Postal Address 1.3.6.1.4.1.1466.115.121.1.8 Certificate 1.3.6.1.4.1.1466.115.121.1.5 Binary 1.3.6.1.4.1.1466.115.121.1.7 Boolean Using JXweb 427 Get Started with JXweb Get Started with JXweb This section describes how to start JXweb, connect to a directory, and browse through the directory. Start JXweb You can run JXweb on a Windows or UNIX computer. To start JXweb on a Windows computer 1. Open Management and Samples. See the Management and Samples section for instructions. 2. Click on the JXweb link. The JXweb Connect page opens in your Internet browser. To start JXweb on a UNIX computer 1. Open a web browser. 2. Go to the following URL: http://servername:8080 where servername is the name of the computer on which JXweb is installed. 3. Click on the JXweb link. The JXweb Connect page opens in your Internet browser. 428 Administrator Guide Get Started with JXweb Connect to a Directory There are two ways to connect to a directory using JXweb. You can either use the JXweb Connect page to enter the details of the directory, or you can construct a URL that contains the connection information. To connect to a directory using the interface 1. Do one of the following: To connect to a directory for the first time in this session, start JXweb. To connect to a directory while you are browsing another directory, click Connect from the menu bar. Your current connection is disconnected, and the JXweb Connect page appears. To cancel any changes in this page, click Reset. 2. From the JXweb Connect page, enter the following data: Host The name of the computer on which the DSA resides Port The port number of the DSA Base DN (Optional) The base distinguished name of the DSA to which you want to connect (for example, o=DEMOCORP,c=au). User DN (Optional) The DN of your user account. Only use this option if the DSA has access controls enabled. Password (Optional) The password of your user account. Only use this option if the DSA has access controls enabled. Use SSL (Optional) Specifies an SSL connection between the directory and the web server. Remember my connection settings Sets a cookie which populates the Connect page when you next open it. 3. Click Connect. Using JXweb 429 Get Started with JXweb Connect to a Directory Using a URL To connect to a directory using a direct URL In your browser, enter the following URL: http://jxweb-hostname:8080/jxweb/ConnectServlet?host=hostname&port=port- number&baseDN=DN where jxweb-hostname Specifies the name of the computer on which JXweb is installed dsa-hostname Specifies the name of the computer on which the DSA is running port-number Specifies the DSA port number DN Specifies the base DN to which you want to connect, where the = symbols are replaced with %3d and the commas are replaced with %2c For example, the following URL connects JXweb to the DSA that uses port 19289 on the computer named COMP01, at the level o=DEMOCORP,c=AU: http://localhost:8080/jxweb/ConnectServlet?host=COMP01&port=19289&baseDN=o%3dDEMO CORP%2cc%3dAU Disconnect from a Directory When you close the browser, you are automatically disconnected from the directory. 430 Administrator Guide Get Started with JXweb Navigate the Directory There are two ways to navigate the directory in JXweb. You can either use the tree (on the left) or the data pane (on the right). To navigate the directory using the tree In the left pane of JXweb, use the and icons to expand and collapse sub-trees. To resize the panes, drag the vertical split bar. To navigate the directory using the data pane If the page has a DN link at the top, click it to list the entry immediately above, and its peers. If the pane contains a list, click a listed entry to display the entries below. Using JXweb 431 Search the Directory Search the Directory Browsing is not always the best way to find the entry you want. JXweb includes quick and advanced search capabilities. Run a Quick Search A quick search lets you enter the exact terms of the search. To search for entries in a directory 1. From the menu bar, click Search to display the Quick Search page. 2. In the From DN text box, specify the distinguished name of the entry from which you want the search to start. 3. Use the Attribute, Filter, and Value fields to construct your search criteria. 4. After you specify your search criteria, click the Search button. The results of the search are displayed on the List of Results page. Click the Details icon to display an entry's details. For results from an advanced search, you can sort a column by clicking its heading. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). 432 Administrator Guide Search the Directory Run an Advanced Search An advanced search lets you use complex criteria. To search the directory by using complex criteria 1. From the menu bar, click Search. 2. From the displayed Quick Search page, click Advanced Search. 3. In the From DN text box, specify the distinguished name of the entry from which you want the search to start. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). 4. In the Using Filter text box, specify an LDAP search filter. For example, if you want to search for common names that resemble Bernie S, specify cn~=bernie s. For information about how to construct the filter, see RFC 2254 (http://www.rfc-editor.org/rfc/rfc2254.txt). 5. At the Search Level drop-down list, select the scope of the search. Search Full Subtree Searches the whole branch from the entry specified in the From DN text box down. Search Next Level Searches only one level down from the entry specified in the From DN text box. Search Base Object Searches the entry specified in the From DN text box only. 6. In the Search Limit text box, specify a value to limit the number of entries to be returned from a search. If you specify 0, the max-op-size value in the configuration file applies. 7. In the Search Timeout text box, specify a value in seconds to limit the time taken for the search. If you specify 0, the max-op-time value in the configuration file applies. If you have access to DXconsole, you can use the get oper command to display the values of max-op-size and max-op-time (in seconds). 8. If you want specific attributes to be returned for the found entries, select them one by one in the Available Attributes to Return list and add them to the Selected Attributes to Return list. 9. After you specify your search criteria, click the Search button. The results of the search are displayed on the List of Results page. Click the Details icon to display the details of an entry. Using JXweb 433 Search the Directory Sort Results of an Advanced Search After you have run an advanced search, you can sort the results. To sort the results Click on the heading of one of the attribute columns. How Sorting Works If the attribute is multivalued, the results are sorted based on the first value in the attribute. For example, if the attribute cn has the values fred, adam, and zoe, sorting is based on fred, because it is listed first. If the attribute is an integer, the results are sorted numerically. If the attribute is a string, the results are sorted alphabetically. If the attribute is binary (for example, jpegPhoto), the results are not sorted. 434 Administrator Guide Create and Delete Entries Create and Delete Entries This section describes how to add entries and aliases, and how to delete an entry, an attribute, or a whole subtree. Add an Entry You can add a subordinate to a selected entry. To add a subordinate entry 1. Navigate to an entry. 2. From the menu bar, click New. 3. On the New Entry page, enter the following details: Parent DN Identifies the entry under which the new entry will be created. Only change this if you selected the wrong entry in Step 1. RDN for New Entry Specifies the relative distinguished name of the subordinate entry (for example, cn=USER01). 4. Select the required object classes in the Available list and click Add to move them to the Selected list. 5. Click Submit. 6. When you are asked for confirmation, click OK to continue. The Fill In Mandatory Elements page opens. 7. Fill in the attribute values as required. You must specify values for the attributes that are in bold. 8. Click Submit. 9. When you are asked for confirmation, click OK to add the entry. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). Using JXweb 435 Create and Delete Entries 436 Administrator Guide Create and Delete Entries Add an Alias for an Entry An alias is similar to a shortcut. It is used to link different parts of the DIT. For example, a person might work in the Human Resources department but is also the manager of the Sporting committee. You can have an entry in the Human Resources branch and use an alias in the Sporting branch, to save retyping the information and maintaining two entries. To add an alias, use the same procedure as for Adding an Entry with the following considerations: An alias requires the alias object class, which specifies the aliasedObjectName attribute. The aliasedObjectName attribute must specify the DN of the entry to which the alias refers. To add an alias 1. Navigate to the place in the tree that you want to create the alias. The entry that you select will become the parent entry for the alias. 2. From the menu bar, click New. 3. In the New Entry page, do the following: a. In the RDN for New Entry box, enter the naming attribute for the alias.. b. Add the alias object class c. Remove other object classes. d. Click Submit. 4. In the Fill In Mandatory Elements page, do the following: a. In the aliasedObjectName box, enter the DN of the actual entry. b. Click Submit. The alias (indicated by the icon) is added as a subordinate of the entry you selected in Step 1. Using JXweb 437 Create and Delete Entries Example: Add an Alias to Craig Link in Democorp The following instructions describe how to add an alias in the sample Democorp directory, as follows: Actual location: cn=Craig LINK,ou=Administration,ou=Corporate,o=DEMOCORP,c=AU Location of alias: cn=Craig LINK,ou=Finance,ou=Corporate,o=DEMOCORP,c=AU To add an alias for Craig Link in Corporate Finance 1. In the navigation pane, click the Finance entry (the superior of the alias). 2. From the menu bar, click New. 3. In the New Entry page, do the following: a. In the RDN for New Entry box, enter cn=Craig LINK. b. Add the alias object class c. Remove other object classes. d. Click Submit. 4. In the Fill In Mandatory Elements page, do the following: a. In the aliasedObjectName box, enter cn=Craig LINK,ou=Administration,ou=Corporate,o=DEMOCORP,c=AU. b. Click Submit. The Craig LINK alias (indicated by the icon) is added as a subordinate of the Finance entry. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). Delete an Entry To delete an entry 1. Navigate to the entry. 2. From the menu bar, click Delete. 3. On the Delete Tree page, confirm the DN and then click Delete Tree. 4. When you are asked for confirmation, click OK to delete the entry. 438 Administrator Guide Create and Delete Entries Delete a Branch To delete a branch 1. Navigate to the entry at the head of the branch. 2. From the menu bar, click Delete. 3. On the Delete Tree page, confirm the DN and then click Delete Tree. 4. When you are asked for confirmation, click OK to delete the branch. Delete an Attribute Value To delete an attribute value from an entry 1. Navigate to the entry. 2. Click the Edit icon for the attribute value you want to delete. 3. On the Modify page, click Delete. 4. When you are asked for confirmation, click OK to delete the value. Using JXweb 439 Modify Entries Modify Entries You can use JXweb to update the information in the directory entries. You can change an entry’s naming attribute, change an entry’s object class, and change the value of attributes. Add an Attribute Value To add an attribute value to an entry 1. Navigate to the entry. 2. Click the Edit icon for the attribute to which you want to add a value. 3. On the Modify page, specify the value you want to add and click Add. 4. When you are asked for confirmation, click OK to add the value. Each addition creates an attribute-value pair. Modify an Attribute Value To modify an attribute value 1. Navigate to the entry. 2. Click the Edit icon for the attribute that you want to modify. 3. On the Modify page, enter the new value and click Modify. 4. When you are asked for confirmation, click OK to save the change. 440 Administrator Guide Modify Entries Add or Remove Object Classes from an Entry Object classes contain attributes that you can use to qualify an entry. You can include new attributes by adding classes and remove unwanted attributes by removing classes. To add or remove classes from an entry 1. Navigate to the entry. 2. Click the Edit icon for any of the object classes. 3. From the Add or Remove Object Classes page, use the Add and Remove buttons to add or remove object classes from the Selected list. 4. Click the Submit button. When you are asked for confirmation, click OK. 5. If a class contains an attribute that must have a value, the Fill in Mandatory Attributes page appears. Enter the values, and then click Submit. The List of entry attributes and values page appears, showing the list of attributes from the updated classes. Using JXweb 441 Modify Entries Assign Icons for Object Classes You can assign your own icons to the object classes. For example, you might want to assign an icon to an object class that does not have an icon, as indicated by the icon. To assign an icon to an object class 1. Create or select an icon in one of the following formats (and file extensions): GIF (.gif), JPEG (.jpeg), or JPG (.jpg). 2. Ensure that the name of the icon is the same as the name of the object class. 3. Place the icon in the menu-images folder (for example, … \CA\eTrustDirectory\dxwebserver\webapps\jxweb\docs\menu-images). The following object class icons may appear in the DIT: Tree Icon Object Class country locality organization, organizationalUnit, and top inetOrgPerson, organizationalPerson, and person Default icon when an object class has no assigned icon 442 Administrator Guide Change Entry Names Change Entry Names To change the name of an entry, you need to change the value of the naming attribute. The naming attribute is the single attribute used to uniquely identify each entry in the directory. If you rename an entry with subordinates, the subordinates are also renamed. Rename an Entry To rename an entry 1. Navigate to the entry. 2. Click the Edit icon for the naming attribute. The naming attribute is shown in blue text. 3. On the Modify page, enter the new value and click Modify. 4. When you are asked for confirmation, click OK to save the change. The old name still appears as a value. If the old name is of no use, you can delete it. Choose a Different Naming Attribute You can choose a different attribute to be the naming attribute for a particular entry. If you rename an entry that has subordinates, the DNs of the subordinates are also changed. To change the naming attribute of an entry 1. Navigate to the entry. 2. From the List of entry attributes and values page, click Change Name. 3. In the Change Name page, enter the following: Attribute The naming attribute. For example, enter cn. Value The attribute value. For example, enter Craig LINK. 4. Click Change. 5. When you are asked for confirmation, click OK to set the new name. Using JXweb 443 Change Entry Names How Second Naming Attributes Work You can rename an entry by including an additional attribute as part of its name. For example, if the entry had the naming attribute cn=Craig LINK and you added to the new naming attribute sn=LINK, the name of this entry would be cn=Craig LINK+sn=LINK. This could be useful if you find that one naming attribute cannot provide unique names to your entries, and you need to add a second naming attribute to make the names unique. If you plan to use more than one naming attribute, they must be different attributes. For example, while you can have two cn values for Craig Link, they cannot both be naming attributes. Instead, you would need to use one of the cn values, plus a different attribute such as sn. Add a Second Naming Attribute To add a naming attribute to the name of the entry 1. Navigate to the entry. 2. If the attribute you want to use as the second naming attribute does not already have a value, create it now. For instructions, see Add an Attribute Value (see page 440). 3. From the List of attributes and values page, click Add Name. 4. In the Add Name page, enter the attribute and its value. For example, you could enter sn=LINK. 5. Click Add. 6. When you are asked for confirmation, click OK to set the new name. The entry is now named by the sum of all of the naming attributes. 444 Administrator Guide Change Entry Names Delete a Naming Attribute If an entry has more than one naming attribute, you can delete one of them. If the attribute is not mandatory, it will be deleted from the entry. If the attribute is mandatory, it will not be deleted. Instead, it will still be present in the entry, but it will no longer be a naming attribute. To delete a naming attribute 1. Navigate to the entry. 2. Click the Edit icon for the naming attribute you want to delete. 3. In the Modify Value for Naming Attribute page, click Delete. If the attribute is mandatory, the attribute still exists in the entry but it is no longer a naming attribute. If the attribute is not mandatory, the attribute is deleted. Using JXweb 445 Copy and Move Entries Copy and Move Entries You can use JXweb to update the structure of the DIT (directory information tree). You can copy or move a subtree to another location in the tree. Copy a Branch of the DIT To copy a branch 1. Navigate to the entry at the head of the branch. 2. From the menu bar, click Copy. 3. On the Copy Tree page, enter the following: From DN The location of the original sub-tree To DN The location to which the sub-tree is to be copied 4. Click Copy Tree. 5. When you are asked for confirmation, click OK to copy the branch. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). Move a Branch of the DIT To move a branch 1. Navigate to the entry at the head of the branch. 2. From the menu bar, click Move. 3. On the Copy Tree page, enter the following: From DN The location of the original sub-tree To DN The location to which the sub-tree is to be moved 4. Click Move Tree. 5. When you are asked for confirmation, click OK to copy the branch. Note: If you use special characters in the DN, be sure to escape them correctly. For information, see Creating and Deleting Entries (see page 435). 446 Administrator Guide Manage Certificates Manage Certificates You can use JXweb to add, delete and view a certificate in a directory entry. View a Certificate To view a certificate 1. Navigate to the relevant entry. 2. Find the certificate attribute, then click the icon next to the certificate attribute. The Modify page opens, displaying the certificate. Using JXweb 447 Manage Certificates Add a Certificate To add a certificate to an entry 1. Make sure that the entry includes an attribute with certificate syntax. 2. Navigate to the entry. 3. Make sure that the entry is displayed showing all attributes. For more information, see Change the Entry View (see page 453). 4. Click the drop-down section List of attributes without values. 5. Scroll down to find the attribute that you want to add the certificate to (you can use userCertificate or 1.3.6.1.4.1.1466.115.121.1.8), then click next to it. 6. Enter the path to the certificate in the empty field, or click Browse to locate the certificate file. 7. Click Browse to choose the certificate that you want to add to the entry, and then click Add. The certificate is now saved in the directory. Delete a Certificate This option allows you to delete trusted public certificates from the keystores. To delete a certificate 1. Navigate to the relevant entry. 2. Click the icon next to the attribute that contains the certificate that you want to delete. The Modify page opens. 3. Click Delete. The certificate is deleted. 448 Administrator Guide View Schemas View Schemas JXweb lets you look at the schema for the current directory. You cannot edit the schema using JXweb: use JXplorer instead. To view schema 1. Click the Schema button. 2. Select the schema type and name. 3. To return all the schema of a certain type, leave the Name field blank. To search for a single schema object, enter its name in the Name field. For example, enter Attribute Types and cn to return the schema for the cn attribute type: Using JXweb 449 View Schemas Schema Types A schema is a formal definition of the contents and structure of the directory data. It governs where each entry can be placed within the directory structure, how entries are to be named, and what attributes each entry can contain. Attribute Types Attribute types define what the attribute's syntax is and how the attribute is compared and sorted. An attribute type can contain the following information: OID The unique identifier for this object NAME The name of the object class DESC A description of the syntax SUP The name of a superior object from which this object class is derived SYNTAX The syntax OID SYNTAX Description The descriptive word for the syntax OID EQUALITY The matching rule if substring matching is allowed SINGLE-VALUED Included if the value is not multivalued LDAP Syntaxes LDAP syntaxes describe the representation of the attribute's value. An LDAP syntax can contain the following information: OID The unique identifier for this object DESC A description of the syntax 450 Administrator Guide View Schemas Object Classes An object class defines what kind of attributes an entry will contain. An object class can contain the following information: OID The unique identifier for this object NAME The name of the object class DESC A description of the syntax SUP The name of a superior object from which this object class is derived MUST A mandatory attribute MAY A optional attribute DIT Structure Rules A DIT structure rule is part of the name bindings in that these define where entries appear in the directory information tree. A DIT structure rule can contain the following information: OID The unique identifier for this object NAME The name of the DIT structure rule SUP The name of a superior object from which this object class can be a child FORM The rest of the name binding for this DIT structure rule Using JXweb 451 View Schemas Name Forms A name form is part of the name bindings in that these specify which attributes the entry can be named by. A name form can contain the following information: OID The unique identifier for this object NAME The name of the name form OC The object class MUST A mandatory attribute MAY A optional attribute 452 Administrator Guide Configure JXweb Configure JXweb JXweb was created using Velocity tags, which render the HTML pages in JXweb. To create your own look and feel for the packaged version of JXweb, you can manipulate the HTML code and the Velocity tags. JXweb comes with some example custom views, which are different sets of velocity templates. Change the Entry View When you open an entry, JXweb displays it using a view. Each entry type can have more than one possible view. To change how entries of some types are displayed in JXweb To change the way an entry is displayed, select an option from the Change view drop-down list at the top of the right pane. If only one option appears in the list, this entry type currently has only one display type. Using JXweb 453 Configure JXweb Change the Default Entry View One of these views is the default view, which JXweb uses when it opens an entry of that type. The user can then change the view if they want to. For example, by default, person entries are displayed using the All Attributes view. For more information, see Example Custom Views (see page 455). If an entry type has more than one possible view, you can change which of these views is the default. To change the default view for an entry type 1. Create a new view using Velocity tags. 2. Find the jxweb.properties file, which is installed in the following folder: Windows: %DXHOME%\..\dxwebserver\webapps\jxweb UNIX: $DXHOME/../dxwebserver/webapps/jxweb 3. In jxweb.properties, change the value of the useCustom setting to true. Create Custom Views Using Velocity Tags To implement custom views using Velocity tags 1. Learn about the Velocity Template Language (VTL), and how is it used: Velocity User Guide (http://jakarta.apache.org/velocity/user-guide.html) 2. Learn about how the Velocity tags are used in JXweb: ../../JXwebVelocityTags.html 3. Create the custom views, then save each view with the name of the relevant object class. 4. Install the files for the new custom views in DXHOME\dxwebserver\webapps\jxweb\WEB-INF\velocity\custom. See this folder for examples of other custom view files. 454 Administrator Guide Configure JXweb Example Custom Views JXweb comes with some custom views already set up, to demonstrate how it works. The following image shows the default All Attributes view of an entry: This image shows the inetOrgPerson view of the same entry: Using JXweb 455 Configure JXweb JXweb in Languages Other Than English eTrust Directory is language certified for the following nine languages: Brazilian Portuguese French German Italian Japanese Korean Simplified Chinese Spanish Traditional Chinese This means that all eTrust Directory components run on operating systems in those languages. Display Non-English Characters in Internet Explorer By default Internet Explorer detects the language encoding automatically. However, if there are problems with displaying non-English characters, you can change an Internet Explorer setting to fix the problem. To fix language encoding problems in Internet Explorer In Internet Explorer, select View, Encoding, Auto-Select has a check mark. Display Non-English Characters in Mozilla Browsers Web browsers based on the Mozilla engine (including Netscape and Firefox) do not auto-detect the character encoding correctly. To fix language encoding problems in Mozilla 1. In the Mozilla browser, select View, Character Coding, Auto-Detect, Off. 2. Select View, Character Coding, Unicode (UTF-8). 456 Administrator Guide Chapter 14: Using DXmanager This section contains the following topics: What is DXmanager (see page 457) How DXmanager Works (see page 460) How Polling Works (see page 462) What Are Alerts (see page 462) DXmanager Security (see page 463) Setting Up and Securing DXmanager (see page 467) Working with DXmanager (see page 478) Troubleshooting (see page 487) What is DXmanager DXmanager is a web-based management tool that lets you monitor and control all of the DSAs in a distributed eTrust Directory environment. DXmanager polls all of the DSAs in your environment to present updated information about the health and the load of your system. The following image shows a sample DXmanager screen: Using DXmanager 457 What is DXmanager Monitoring a Distributed eTrust Directory Environment Using DXmanager, you can monitor various aspects of a distributed eTrust Directory environment. The health of the DSAs in your environment can be determined by monitoring the: Status of each DSA (stopped or started). Alarm logs. Replication queues (if configured for replication). The load on the DSAs in your environment can be determined by monitoring the: Operations performed. Activity %busy during last minute of DSA activity statistics (updates, searches, and so on). Cache performance (hits and misses). Administrative information that is available about the DSAs in your environment: The version of the DXserver. The uptime of each DSA. Configuration information of each DSA. Namespace diagrams for each host. A connectivity diagram for DSAs on each host. You can also use DXmanager to: Create a report about a host or host group. Modify options including: change monitoring preferences, define host group names, and edit host group. Set DXmanager to send email notifications for any new alerts it identifies in a poll. 458 Administrator Guide What is DXmanager Controlling a Distributed eTrust Directory Environment Using DXmanager, you can control the status of each DSA in a distributed eTrust Directory environment. For each DSA, you can: Start the DSA. Stop the DSA. Initialize the DSA. Initializing a DSA lets you apply the latest changes to configuration files without taking the DSA offline. Note: To control the DSAs, you must have eTrust Embedded Identity and Access Management (eIAM) installed in your network, and DXmanager configured appropriately. Using DXmanager 459 How DXmanager Works How DXmanager Works To effectively configure DXmanager for your installation, you should first understand how DXmanager monitors DSAs in a distributed eTrust Directory environment. By understanding the actions DXmanager takes, you can choose how best to implement DXmanager in your enterprise, choosing computers with appropriate resources and maintenance schedules. The following diagram shows how DXmanager uses DXadmind to monitor DSAs on one host within the distributed eTrust Directory environment. DXmanager polls all of the DSA hosts that are defined in all of the host groups. For each DSA host: 1. DXmanager uses the DXadmind process to work with the DSA. DXadmind is installed on each host that contains eTrust Directory DSAs. This is a background process that enables monitoring of all DSAs that are configured on the host. If DXmanager cannot establish a connection to DXadmind, the polling of that host is terminated and DXmanager continues polling any other DXserver hosts using their local DXadmind process. 460 Administrator Guide How DXmanager Works 2. DXadmind extracts from the DSAs on its host information as requested by DXmanager. This information includes DSA status, configuration information, and log files. 3. DXmanager retrieves the data that DXadmind collated from each DSA, including SNMP port connection details. 4. Using the SNMP port, DXmanager polls the DSA for additional information. Note: After the initial polling of each DSA is complete, different aspects about each DSA are polled at different intervals. For more information on DSA polling, see How Polling Works (see page 462). The same process is then performed with each of the DSA hosts in a sequence, as illustrated in the following diagram: Using DXmanager 461 How Polling Works How Polling Works Different types of polling occur at different intervals. This lets you view important up-to-date information about each DSA while reducing network bandwidth required to monitor more static information. The polling of each DSA is divided into three categories, each occurring at different configurable intervals: Status and alarm log, by default every minute. Configuration information, by default every six hours. SNMP counters, by default every two minutes. To optimize polling to suit your distributed eTrust Directory environment, you can configuring the intervals for the different types of polling. You can configure polling intervals by changing DXmanager preferences. For more information, see Set Up Polling Preferences (see page 475). What Are Alerts Alerts are any events that the user should be made aware of. In this version of DXmanager, the alerts are harvested from the alarm logs. Alerts can be displayed in two ways: On the main DXmanager screen All alerts are displayed on the DXmanager screen in the Alerts section. In email messages You can also configure DXmanager to send email notifications as alerts are raised. 462 Administrator Guide DXmanager Security DXmanager Security When evaluating your security requirements for DXmanager, you should consider the following: Should you secure access to DXmanager? Anyone with access to the DXmanager URL can use this tool to monitor DSAs on hosts that DXmanager is set to monitor. To secure access to DXmanager, you need to use eTrust Embedded Identity and Access Management (eIAM). This also lets you grant users control of the DSAs that they can monitor. Which DSA hosts should you let DXmanager monitor? When you first install DXmanager, you can only use it to monitor DSAs on the local computer as by default, each DSA host is configured to only trust itself. To let DXmanager monitor DSAs on remote hosts, you need to configure each DSA host to trust the DXmanager host. If you decided to use eIAM to secure access to DXmanager, you should also consider the following: Who are your DXmanager users? To grant users access to DXmanager, you need to have a pool of users. You can use an existing eIAM user directory, an existing external user directory, or you can create your DXmanager users in eIAM. What access should you grant to each DXmanager user? Once you have your DXmanager users defined, using eIAM, you need to define the appropriate level of access for each of these users. When should you let authorized users control DSAs? By default, authorized users can control DSAs according to a pre- configured calendar (8 pm to 6 am). You can use the Control Calendar to specify the periods in which these users (controllers) can start, stop, or initiate DSAs. The following sections explain the concepts related to securing DXmanager. For information on implementing your security requirements, see Setting Up and Securing DXmanager (see page 467). Using DXmanager 463 DXmanager Security eTrust Embedded Identity and Access Management You can use eTrust® Embedded Identity and Access Management (eIAM) to secure the connection to DXmanager and manage user accounts. eIAM offers a common, shared approach to managing identities and access policies. You can use the eIAM web-based administrative interface to manage identities and access policies, and change the configuration of the eIAM server. eIAM is available on the eTrust Directory CD as a supporting product. eIAM is also used by many CA products, so it may already be installed. If you already have eIAM installed, DXmanager can use this installation. How DXmanager Uses eIAM eIAM provides authentication and authorization for DXmanager. It keeps records of users, their authentication details, and their authorization levels. eIAM lets you set up authentication and authorization rules for DXmanager users: Authentication lets you define the users that you want to permit access to DXmanager. Users you define can log in to DXmanager using their credentials. Authorization lets you define what level of access each user has by using roles to define user access levels. 464 Administrator Guide DXmanager Security DXmanager Access Levels An eIAM administrator or a DXmanager superuser can assign DXmanager users with privileges to suit their access requirements. Access levels are determined by the DXmanager roles defined for the user. DXmanager roles are defined as application group membership in eIAM, where each DXmanager role is determined by the user's group membership. You can assign each user one or more of the following roles in ascending order of access: Monitors Users with Monitor privileges can only monitor DSAs and customize monitoring functionality. Controllers Users with Control privileges can start, stop, and initialize DSAs (belongs to Controllers user group). Changers Users with Change privileges have no additional rights. This role will be used for future functionality. SuperUsers Users with Superuser privileges can define security configurations, including: group, security preferences, user authorization, and group policies. Note: Users with more than one role assigned to them are granted the privileges of the role with the highest level of access. The following table summarizes the privileges associated with these roles: Privilege Monitors Controllers Changers Superusers Monitor DSAs Set preferences Create reports Start, stop, and initialize DSAs Create and define host groups Change eIAM server configuration for DXmanager Manage DXmanager users Modify the control calendar Using DXmanager 465 DXmanager Security Using an External User Directory eIAM comes with an internal management database for storing users and groups. If preferred, you can configure eIAM to point to an external directory. For example, you may want to point eIAM to an existing corporate Active Directory user directory. When a user then logs on to DXmanager, their credentials are validated against the corporate Active Directory host via eIAM. Note: If eIAM uses an external directory, the DXmanager superuser you define should already exist in the directory. The password you set for the superuser is ignored. For information on configuring eIAM to point to an external directory, refer to the eIAM documentation. Limiting Access through a Policy Calendar In addition to the restrictions access levels impose on users, you can further restrict certain activities (roles) from being performed at given time periods. Using a policy calendar, you can define time periods when authorized users are affected by the policies associated with the calendar. For example, you can use the Control Calendar to prevent Controllers from controlling DSAs during working hours. Note: For this release, you can only restrict Control access. Important! The policy calendars specify time periods for the eIAM server time zone. The actual local time periods when the policy is applied depend on the user's locale. 466 Administrator Guide Setting Up and Securing DXmanager Setting Up and Securing DXmanager Once you have your distributed eTrust Directory environment set up, you can implement DXmanager as your monitoring solution. Following is a summary of the steps that you need to perform to set up DXmanager for monitoring your distributed eTrust Directory environment. The sections that follow explain each step in detail. For more information about DXmanager security, see DXmanager Security (see page 463). Note: We recommend that you install the Web Components, which include DXmanager, on a separate host to the Directory components. Setting up DXmanager on a dedicated web server lets you run the DXserver host without compromising eTrust Directory performance. To set up DXmanager to securely monitor and control your distributed eTrust Directory environment, follow these steps: 1. (Optional) Secure DXmanager using eIAM. a. If you do not already have eIAM implemented, install eIAM as required. b. Configure the eIAM server for securing DXmanager. c. Set up the other users in eIAM. d. (Optional) Modify the Control Calendar. 2. Set each of the eTrust Directory hosts to trust remote DXmanager hosts. 3. Create and define host groups. 4. Decide what information to display about each DSA. 5. Set up polling preferences. 6. Set alert notifications. The following diagram shows a possible implementation of DXmanager to monitor and control a distributed eTrust Directory environment. Using DXmanager 467 Setting Up and Securing DXmanager 468 Administrator Guide Setting Up and Securing DXmanager Step 1. Secure DXmanager using eIAM (Optional) Anyone with access to the DXmanager URL can use this tool to monitor DSAs on hosts that DXmanager is set to monitor. To secure access to DXmanager, you need to use eTrust Embedded Identity and Access Management (eIAM). This also lets you grant users control of the DSAs that they can monitor. To secure DXmanager using eIAM, follow the steps outlined in the following sections. Step 1a. Install eIAM If you do not already use eIAM in your organization, you need to install eIAM so you can use it to secure DXmanager. eIAM is available on the eTrust Directory CD as a supporting product. For information on installing eIAM, see Installing eTrust Directory for Windows (see page 571) or Installing eTrust Directory for UNIX (see page 601). Using DXmanager 469 Setting Up and Securing DXmanager Step 1b. Configure the eIAM server To secure DXmanager you need to set it up to use the eIAM server for authentication and authorization. As part of this configuration, you will also create a DXmanager superuser. To configure the eIAM server 1. From the DXmanager menu, choose Options, Preferences, Security tab. The Preferences page opens and the Security tab displays. 2. Complete the following information: eIAM Server The hostname or IP address of the eIAM server that you want to use to authenticate and authorize DXmanager users. eIAM Admin Username The name of the eIAM administrator you want to use to register the DXmanager application with eIAM and to add a superuser (the default is EiamAdmin). This is the user name that you created when eIAM was installed. eIAM Admin Password The password of the eIAM administrator. The password was specified for the default EiamAdmin administrator when eIAM was installed. This is the password that you created when eIAM was installed. DXmanager Superuser A case-sensitive name of a DXmanager user that will have superuser privileges. For more information on user privileges, see DXmanager Access Levels (see page 465). You can use the name dxmanager for this user name. DXmanager Superuser Password The password for the DXmanager user that will have superuser privileges. Confirm Password The DXmanager superuser password retyped as a safety measure. Note: If eIAM uses an external directory, the DXmanager superuser you define should already exist in the directory. The password you set for the superuser is ignored. 3. Click Save. The browser navigates to the DXmanager Login page letting you log in with your newly created superuser name and password. 470 Administrator Guide Setting Up and Securing DXmanager Step 1c. Set Up the Other Users in eIAM Once you have eIAM configured for DXmanager, log in using the superuser credentials you created when configuring eIAM for DXmanager, and set up all the users you want to use DXmanager. To grant users access to DXmanager, you need to assign them with the appropriate access rights. You can use an external user directory, an exiting eIAM user directory, or you can manually add the new users to eIAM. To add new users to eIAM 1. Log in to DXmanager using superuser credentials. Use the superuser credentials you created when configuring eIAM for DXmanager. 2. From the DXmanager menu, choose Security, Advanced. eIAM opens in a new browser window and logs in for you using the DXmanager superuser credentials. 3. Click Manage Identities. The Manage Identities tab is displayed. Use the following instructions to add new users to eIAM or to grant access to DXmanager to users from an existing user directory. 4. Click . The New User panel opens, letting you create a new user. 5. Enter the required information for your user, making sure you enter the following details: User Name A case-sensitive name your user will use to log in to DXmanager. DXmanager User Details The role or roles that define what access level the user has for using DXmanager. You need to click the Add Application User Details button to display the information you need to select. For more information on access levels, see DXmanager Access Levels (see page 465). 6. Click Save. The new user is added as a DXmanager user. To grant users in an existing user directory access to DXmanager 1. Search for the user. 2. Select the user name to display the attributes. 3. Specify the DXmanager User Details. 4. Click Save. Using DXmanager 471 Setting Up and Securing DXmanager For more information on using eIAM to modify or add users, refer to the eIAM online documentation. Step 1d. Modify the Control Calendar (Optional) To set when authorized DXmanager users can control DSAs, you can set the eIAM Control Calendar. Important! The policy calendars specify time periods for the eIAM server time zone. The actual local time periods when the policy is applied depend on the user's locale. Step 2. Set eTrust Directory Hosts to Trust Remote DXmanager Hosts When you first install DXmanager, you can only use it to monitor DSAs on the local host. As a security precaution, you cannot monitor or control DSAs on remote hosts. To enable DXmanager to monitor and control DSAs in a distributed eTrust Directory environment, you need to configure eTrust Directory to trust your remote DXmanager hosts. To set each of the eTrust Directory hosts to trust remote DXmanager hosts 1. On the eTrust Directory host, open a command line. 2. Navigate to the eTrust Directory installation folder. 3. Enter the following commands: dxadmind stop master dxadmind remove master dxadmind install master -e DXADMIND_SETUP_DEFAULT= 1 -e DXADMIND_TRUSTED_HOSTS=host1,host2,host3 dxadmind start master where host1, host2, and host3 are the names or IP addresses of the DXmanager hosts that can monitor the DSAs on the local eTrust Directory host. For example, the following command lets DXmanager, installed on a local host and on the hosts named webServer1 and webServer2, control and monitor DSAs on the local host: dxadmind install master -e DXADMIND_SETUP_DEFAULT=1 -e DXADMIND_TRUSTED_HOSTS=localhost,webServer1,webServer2 472 Administrator Guide Setting Up and Securing DXmanager Step 3. Create and Define Host Groups To facilitate monitoring and add meaning to what you would view in DXmanager, you need to group the hosts in your distributed eTrust Directory environment into one or more groups. Note: To view the status of a DSA host, you have to add the host to a host group. You can use host groups to group several hosts by function or geography. This is useful for systems where a single directory information tree (DIT) is spread across many servers. For example, you may want to monitor the overall status of DSAs in all of your European hosts, or you may want to group together all of your DSAs that serve your Human Resources department. Note: The Default group is automatically created by the DXmanager installation and contains all of the hosts on the computer hosting DXmanager. To create a host group and define the hosts that belong to the group 1. From the DXmanager menu, choose Options, Define Host Group Names. The Define Host Group Names page opens. 2. (Optional) Select one or more existing host groups from the Existing Host Groups selection list, and then click to remove these. The removed host groups appear in the Deleted Host Groups selection list. 3. Type a group name into the New Host Group field, then click Add. The new host group name appears in the Existing Host Groups selection list. 4. Repeat step 3 for all the host groups you want to add, then click Save. Any newly added groups are saved and DXmanager displays the Status page. Note: Newly added host groups: Automatically contain the host on which DXmanager resides. Are not shown until the browser is refreshed. 5. From the DXmanager menu, choose Options, Edit Host Group. The Edit Host Group page opens. 6. For each host group you want to edit, select it and then: Type a host name into the New Host field, then click Add. Select hosts you want to remove from the group, then click . Click Save to save your changes. Using DXmanager 473 Setting Up and Securing DXmanager Step 4. Decide What Information to Display about Each DSA To define what information you would monitor about the DSAs in your distributed eTrust Directory environment, you need to set what configuration information and which SNMP counters to display. To configure what configuration information you want to see about each DSA 1. From the DXmanager menu, choose Options, Preferences, and select the DXserver Config tab. The Preferences page shows with the DXserver Config tab open. 2. Select the configuration information about each DSA you want DXmanager to show on the dashboard, and then click Save. The new settings are saved and the main DXmanager page opens. To configure which SNMP counters you want to see about each DSA 1. From the DXmanager menu, choose Options, Preferences, and select the SNMP Counters tab. The Preferences page shows with the SNMP Counters tab open. 2. Select the SNMP counters about each DSA you want DXmanager to show on the dashboard, and then click Save. The new settings are saved and the main DXmanager page opens. 474 Administrator Guide Setting Up and Securing DXmanager Step 5. Set Up Polling Preferences To efficiently monitor the DSAs on all of the hosts you configured, you need to make sure that the timers related to gathering the DSA information and presenting it on the browser are set to suit your environment and your requirements for a real-time view. To set the monitoring timers 1. From the DXmanager menu, choose Options, Preferences. The Preferences page opens with the Timers tab displayed. 2. Set the following timers as required: Browser refresh interval The time between each refresh of the browser. Ideally, the browser should refresh after each DSA polling completes. Set the browser refresh to approximately half that of the Status polling sleep period. Status polling sleep period The time that DXmanager will wait between polls of the status of DSAs and their log files on all hosts. CONFIG polling sleep period The time that DXmanager will wait between polls of the configuration information about the DSAs on all hosts. SNMP polling sleep period The time that DXmanager will wait between polls of the SNMP counters about the DSAs on all hosts. Note: The poll period varies depending on many factors including network performance and the number of DSAs and hosts polled. As there is no way to predict how long each poll takes, you should set the polling sleep period to suit the highest frequency you require. 3. Click Save. The timers are set and DXmanager retrieves and displays information according to your new settings. Using DXmanager 475 Setting Up and Securing DXmanager Step 6. Set Up Alert Notification The alarms recorded in the DSA alarm logs are also displayed as alerts on the main DXmanager window. You can also configure DXmanager to send email notifications as alerts are raised. To view the alarm log related to a particular alert In the Alerts panel, scroll to the alert you want to investigate and click on the DSA name. The Logs tab opens and the page scrolls to the alarm log for the DSA that raised the alert. To set DXmanager to send email notifications for raised alerts 1. From the DXmanager menu, choose Options, Preferences, and select the Notifications tab. The Preferences page shows with the Notifications tab open. 2. Type the mail server name or IP address into the Mail Server field. 3. Type a list of comma-separated email addresses into the Address(es) to notify field. 4. (Optional) Click the Test Mail Configuration button to test your input. DXmanager will attempt to send a test email to all of the email addresses you entered using the mail server you specified. It will then report on any failure to connect to the mail server. 5. Set your email preferences, and then click Save. Your notification settings are saved and the recipients you specified should now receive emails from DXmanager for alerts raised. Note: Each email notification contains all of the alarms detected on a single host during the most recent poll. The following image is an example of an email notification sent to an administrator. The email notifies Craig Link, the administrator, of new alerts raised on host host1_sthAsia: 476 Administrator Guide Setting Up and Securing DXmanager Using DXmanager 477 Working with DXmanager Working with DXmanager You can use the information presented by DXmanager to diagnose problems earlier and more accurately. Connect to DXmanager To connect to DXmanager on any platform 1. Open a web browser. 2. Navigate to this page: http://hostname:8080/ where hostname is the name of the computer on which DXmanager is running. The eTrust Directory Home page opens. 3. Click the DXmanager link. To connect to DXmanager on a Windows computer that has DXmanager installed 1. Click Start, All Programs, Computer Associates, eTrust, eTrust Directory, Management and Samples. The eTrust Directory Home page opens. 2. Click the DXmanager link. 478 Administrator Guide Working with DXmanager Monitor DSA Status The main page of DXmanager lets you monitor the status of DSAs in your distributed eTrust Directory Environment. To monitor the overall status of all the DSAs in each of the host groups From the DXmanager menu, choose View, All Host Groups. The Status page displays the section Status of all Host Groups, showing the overall status of DSAs in each of the host groups using icons. To monitor the overall status of all the DSAs on each of the hosts in a group From the DXmanager menu, choose View, Host Group, groupname, where groupname is the name of the host group containing the host you are interested in. The Status page displays the section Status of the groupname Host Group, showing the overall status of DSAs in each of the hosts in the group using icons. To monitor the status of each DSA on one host From the DXmanager menu, choose View, Host, hostname, where hostname is the name of the host you are interested in. The Status page displays the section Status of DSAs on hostname, showing the status of each of the DSAs on the host using icons. To monitor the status of each DSA on all hosts From the DXmanager menu, choose View, All Hosts. The Status page displays a section for each of the DSAs on each of the hosts, showing the status of each of the DSAs using icons. Using DXmanager 479 Working with DXmanager Views Depending on the view you choose, you can monitor the status of individual DSAs on a host, or of all the DSAs on a host or group of hosts. You can drill down to display more detail about the status of DSAs by clicking the host group, the host, or the DSA as shown in the following diagram: 480 Administrator Guide Working with DXmanager Status of DSAs, Groups, and Hosts The status of each group, host, and DSA is displayed using icons. The following table summarizes the possible status indicators for groups, hosts, and DSAs: Icon Represents Status Group of DSAs, LDAP servers, or a All running combination Group of DSAs, LDAP servers, or a All stopped combination Group of DSAs, LDAP servers, or a Some stopped combination Group of DSAs, LDAP servers, or a At least one is combination unknown LDAP server All DSAs running LDAP server All DSAs stopped LDAP server At least one DSA is unknown DSA Running DSA Stopped DSA Unknown Using DXmanager 481 Working with DXmanager Note: An unknown status can indicate a connection failure or simply that the status is not yet known (that is, polling is still in progress). The following diagram shows how the status of DSAs affects the host and groups it belongs to: DSA Connectivity The Status map shows connectivity between DSAs, letting you see which DSAs have knowledge of which other DSAs, LDAP servers, and X.500 servers. You can display the connectivity diagram showing remote knowledge clustered by a common host (the default), or showing individual connections between local and remote DSAs. Arrows indicate knowledge sharing, with the arrow's color and label providing additional information on the nature of the connection. Where both the local and remote hosts are monitored a double-headed arrow should appear, showing knowledge sharing in both directions. A purple arrow indicates that replication is configured and labels indicate the form of multiwrite replication (mw for multiwrite, or mwdr for multiwrite–DISP recovery). Note: DISP replication is not currently detected. 482 Administrator Guide Working with DXmanager Start, Stop, and Initialize DSAs DXmanager lets you control the status of DSAs in your distributed eTrust Directory environment. You can use DXmanager to start, stop, or initialize each of the DSAs you have monitored. Note: To be able to control the status of DSAs, you must have eIAM set up correctly and you must be logged in using an account with Controller permissions or higher. To control the status of a DSA 1. On the main DXmanager screen, select the Dashboard tab. The Dashboard tab displays all of the DSAs for each of the hosts in your distributed eTrust Directory environment. 2. Select the checkbox alongside one or more of the DSAs, and then click Start, Stop, or Initialize. DXmanager attempts to start, stop, or initialize the selected DSAs and reloads the page. A message showing the result of this operation appears below the menu when the page displays again. Using DXmanager 483 Working with DXmanager Check Namespace Design DXmanager can display the namespace design for the DSAs on each host. It shows a tree in which all of the DSAs on that host are connected. The icon of each DSA shows its status. Note: This is not the namespace of each DSA, it is the partitioning of the namespace across DSAs. The following DXmanager page shows the namespace on a host with some sample DSAs installed: 484 Administrator Guide Working with DXmanager Check DSA Configuration DXmanager lets you check on the configuration information about each DSA. This information, for example, includes the DSA name and prefix, and port numbers. To display configuration information about each DSA Select the Dashboard tab on the main DXmanager screen. You can also save this information into a report. For information on selecting the configuration information you want to see about each DSA, see Decide what information to Display about Each DSA (see page 474). Track DSA Statistics and View SNMP Counters DXmanager lets you view SNMP counters and statistical information about each DSA. Statistical information about each DSA can help you monitor the activity on each of the hosts and DSAs and iron out any potential hot spots or network congestion. To view SNMP counters, select the Dashboard tab on the main DXmanager screen. To display statistical information about each DSA, select the Statistics tab on the main DXmanager screen. The change graphs display the amount of change from the last poll. For information on selecting the SNMP counters you want to see about each DSA, see Decide what information to Di (see page 474)splay about Each DSA. View Alarm Logs DXmanager can display the alarm log files of all of the DSAs it monitors. To view the alarm log files for all of the DSAs DXmanager monitors, select the Logs tab. Using DXmanager 485 Working with DXmanager Create Reports DXmanager lets you create reports that you can use to analyze the activity of all of your DSAs on any of your distributed eTrust Directory environment hosts. Creating a report lets you capture all of the DXmanager information for distributing, printing, storing, or sending to CA Customer Support. DXmanager produces web reports, created as a single HTML page. To create a report From the DXmanager menu, choose Reports, and select the report and host you want. A new browser window opens with the selected report displayed. 486 Administrator Guide Troubleshooting Troubleshooting This section describes how to deal with some problems that may occur while you use DXmanager. Connectivity The main area to investigate is usually connectivity. If DXmanager cannot connect to the DXadmind on the server being scanned, then no information can be returned. If this is the case, use the following steps: 1. Use the ping command to ping the target DSA from the host running DXmanager. 2. If this succeeds, log in to the target server and ensure that DXadmind is running. On Windows it appears in the Service Manager. On UNIX it appears as a process named dxadmind start. On either system the command dxadmind status should return: master is running 3. Find the DXadmind configuration file DXHOME\config\dxadmind.ldif. 4. Ensure this contains the line: dxadminURL: ldaps://hostname:2125/ where hostname is the name of the computer on which DXserver is running. Using DXmanager 487 Troubleshooting DXwebserver Port Numbers DXwebserver uses a set of ports. These default ports may conflict with existing ports on the machine on which DXwebserver is being installed. For a list of the default ports used by DXwebserver and other components, see Port Numbers Used by eTrust Directory in the eTrust Directory Reference Guide. If DXwebserver Does Not Start Check the logs under the DXwebserver installation directory for port conflicts. Look for this file in: Windows: %DXHOME%\..\dxwebserver\logs UNIX: $DXHOME/../dxwebserver/logs If there is a port number conflict, modify the DXwebserver configuration file. By default, DXwebserver is set to use the port 8080. To change the port number, you will need to modify the DXwebserver configuration file server.xml: 1. Install DXwebserver as usual. 2. Look for this file in the following locations: Windows: %DXHOME%\..\dxwebserver\conf UNIX: $DXHOME/../dxwebserver/conf 3. In the server.xml file, look for the Connector section: 4. Change the port number from 8080 to another port number. 5. Restart DXwebserver to pick up the new port number. 488 Administrator Guide Troubleshooting If the Main HTTP Connection Port Number Is Modified The main HTTP connection port number is set to 8080 by default. If this port number is modified, then some of the web applications may not work correctly, and on Windows computers, the Start menu shortcuts to Management and Samples will be affected. Note the new port number for future HTTP connections. Using DXmanager 489 Chapter 15: Using The UDDI Server and UDDI Client This section contains the following topics: About the UDDI Server (see page 492) About UDDI Registries (see page 493) Sample Data (see page 494) Work with the UDDI Client (see page 495) Use the UDDI Client in Languages Other Than English (see page 500) Using tModels (see page 501) Using The UDDI Server and UDDI Client 491 About the UDDI Server About the UDDI Server A Universal Description, Discovery and Integration or UDDI server is a 'yellow pages' for web services. It's a place where web services can register their details, and other web services can look those details up when required. In a UDDI registry, all the information is presented in a well-defined manner so that it can be used by automated components and by humans. This lets the repository be used, for example, as a means for an application to locate a replacement service, should the service it is using become unavailable. Web Services use UDDI to look up other web services, and extract information such as contact addresses and WSDL (Web Services Description Language) details. A UDDI server allows you to make complex searches of large numbers of web services. The eTrust Directory UDDI server offers these advantages: Support for UDDI versions 1, 2 and 3 for easy upgrade paths and support of existing legacy systems Guaranteed schema compliance - the raw data types are automatically built from the XML schema Intuitive GUI for both browsing and administration Proven interoperabiliy with standards-based UDDI clients such as Sun's JAX-R API toolkit In addition, the UDDI server derives certain advantages from being Directory- based: Scalable - there is no practical limit to the amount of data that you can store, more than 100 million UDDI entries Distributed - you can run multiple UDDI servers from the same directory backbone in geographically separated locations for high performance Secure - the data is protected through directory access controls Reliability - the directory provides for built-in failover and recovery Performance - CA's patented architecture allows support for high-load applications using the directory's rapid read and search ability The UDDI standard is constantly being extended to allow for the storage of new types of data, and for new usages of the standard. The full details of the UDDI specification can be found at the UDDI home page: http://www.uddi.org/specification.html 492 Administrator Guide About UDDI Registries About UDDI Registries A UDDI registry is a directory of all the Web services in an organization, be it a single business enterprise or a globe-spanning multinational conglomerate. The UDDI registry provides a central point for recording all the details about each Web service, enabling the developers in the organization to locate other Web services to use as building blocks to construct an application, thus saving time and effort. What a UDDI Registry Can Do Because the UDDI registry contains all the details about the interfaces, developers can more easily combine or present services developed by disparate groups, possibly in different locations. Moreover, the UDDI protocol provides for recovery-if a needed service fails and is replaced by another at a different location, all those services that depend on it can recover automatically by reloading the location and connection parameters from the UDDI registry. About the eTrust Directory UDDI Server The eTrust Directory UDDI Server provides repository services. It functions as a business directory, permitting searches based upon categorizations and relationships between businesses. It provides authentication and authorization of users for inquiry and publishing. The UDDI Server responds to requests in UDDI Version 1, Version 2, and Version 3 formats. For more information about the UDDI APIs, see the eTrust Directory Developer Guide. About the eTrust Directory UDDI Client The web-based UDDI Client enables users to: Publish services to the repository. Search for specific entries in the repository. Using The UDDI Server and UDDI Client 493 Sample Data Sample Data If you install the UDDI Server and the UDDI Flight Demo, you will have the following sample data: TModels The UDDI Server includes the TModel keys specified in the UDDI standards. You can use these keys with your own data. These TModel keys start with uddi:uddi.org. Sample business data The UDDI Server includes some sample business data, which represents some of the organizationUnits in the sample Democorp DSA. Do not use these keys for your own data. These business, TModel, service, and binding keys start with uddi:etdir.etrust.ca.com:democorp. UDDI Flight Demo data The UDDI Flight Demo installs some sample airline businesses. Do not use these keys for your own data. These business, TModel, service, and binding keys start with uddi:ca.com:demo. For more information, see Sample Use of UDDI: uddiv3-demo (see page 515). 494 Administrator Guide Work with the UDDI Client Work with the UDDI Client This section describes how to connect to a UDDI server, and how to edit the data. The instructions describe how to connect to the sample UDDI data that comes with eTrust Directory. Start the UDDI Client Because the UDDI Client is a web application, you can run it on a Windows or UNIX computer. Start the UDDI Client on Windows only 1. Open Management and Samples. See the Management and Samples section for instructions. 2. Click on the UDDI Client link. The Connect page opens in your Internet browser: 3. Click Connect. The UDDI Client opens. You can now browse the sample data. Start the UDDI Client on all platforms (including Windows) 1. Open a web browser. 2. Go to the following URL: http://servername:8080 where servername is the name of the computer on which the UDDI Client is installed. 3. Click on the UDDI Client link. The Connect page opens in your Internet browser (as shown previously). 4. Click Connect. The UDDI Client opens: You can now browse the sample data. Using The UDDI Server and UDDI Client 495 Work with the UDDI Client Connect to the Sample UDDI Server To start the UDDI Client 1. Click Start, Programs, Computer Associates, eTrust, eTrust Directory, UDDI Client. The connection page opens: 2. To connect to the sample UDDI data that comes with eTrust Directory, click Connect. The UDDI Client opens: You can now browse the sample data. 496 Administrator Guide Work with the UDDI Client Log In to a UDDI Repository Before you can edit data in a UDDI repository, you must be logged in to the UDDI server. To log in to a UDDI repository 1. Start the UDDI Client, then connect to the UDDI repository. 2. Click the Log In button in the top right of the page. The login page opens: 3. Log in to the repository. To log in to the sample repository that comes with eTrust Directory, use the following details: User Name: travel Password: secret The Registered Information Result(s) page opens: You can now edit the data in the sample UDDI repository. Using The UDDI Server and UDDI Client 497 Work with the UDDI Client Display Your Registered Information If you are logged in to the UDDI Client, you may be able to edit some businesses, TModels, or other information. When you log in, the UDDI Client displays a list of the information that you can edit. You can also return to this page later. To display the information that is registered to your login Click the Registered Info button. The Registered Information Result(s) page opens, displaying the information that you can edit. Search for a Business, Service, TModel, or Binding The UDDI Client lets you search for any of the following: Business Service TModel Binding For each of these, you can run a quick search or an advanced search. A quick search lets you choose from a list of keys. It returns the items that match the keys you selected. An advanced search lets you enter or select 498 Administrator Guide Work with the UDDI Client Wildcards for UDDI Searches The UDDI Client lets you use wildcards in searches. Standard Wildcards The UDDI standard (section 5.1.6) specifies the following wildcard characters: % (Percentage sign) Represents zero or more characters _ (Underscore) Represents exactly one character You can use these wildcard characters when you search for names, descriptions, and key names and key values in keyed references. You cannot use these characters in key fields, such as business keys, service keys, binding keys, and tModel keys. Wildcards for eTrust Directory UDDI Server The eTrust Directory UDDI Server has an extension that lets you use the following wildcard character: * (Asterisk) Represents zero or more characters You can use this character in names, descriptions, and keyed references, and key fields. The following image shows the asterisk used in an advanced search for a binding. The Service Key field does not accept the use of the % wildcard character. Using The UDDI Server and UDDI Client 499 Use the UDDI Client in Languages Other Than English Use the UDDI Client in Languages Other Than English eTrust Directory is language certified for the following nine languages: Brazilian Portuguese French German Italian Japanese Korean Simplified Chinese Spanish Traditional Chinese This means that all eTrust Directory components run on operating systems in those languages. Display Non-English Characters in Internet Explorer By default Internet Explorer detects the language encoding automatically. However, if there are problems with displaying non-English characters, you can change an Internet Explorer setting to fix the problem. To fix language encoding problems in Internet Explorer In Internet Explorer, select View, Encoding, Auto-Select has a check mark. Display Non-English Characters in Mozilla Browsers Web browsers based on the Mozilla engine (including Netscape and Firefox) do not auto-detect the character encoding correctly. To fix language encoding problems in Mozilla 1. In the Mozilla browser, select View, Character Coding, Auto-Detect, Off. 2. Select View, Character Coding, Unicode (UTF-8). 500 Administrator Guide Using tModels Using tModels A tModel is a data structure representing a service type (a generic representation of a registered service) in the UDDI Server. Each tModel consists of a name, an explanatory description, and a Universal Unique Identifier (UUID). It can also provide a URL that enables users to get further information. A tModel may represent a technical specification. Services that are compliant with the specification may reference the tModel. This facilitates the searching of services that are compliant with a particular specification. You can also use a tModel to provide meaning to data. For example, a tModel can give structure to the following address line: 12 Montgomery Street, where 12 has the meaning of street number and Montgomery Street has the meaning of street name. Using The UDDI Server and UDDI Client 501 Chapter 16: Using the DSML Server This section contains the following topics: About DSML (see page 503) What Is the DSML Server? (see page 503) How the DSML Server Works (see page 504) Connect to the DSML Server (see page 506) Change the DSML Properties (see page 507) About DSML DSML is an XML protocol that permits directory structural information to be represented in XML. The DSML protocol is an almost direct mapping of LDAP. The purpose of the language is to allow XML-based applications to use directory information. JXplorer and JXweb both support DSML. You can use these clients to connect to a directory using DSML. DSML can be used anywhere LDAP is used. However, it is usually best to use LDAP. This is because LDAP is the more established protocol and slightly more efficient. What Is the DSML Server? The purpose of this DSML Server is to convert requests and responses between DSML and LDAP. This allows client applications that use DSML (including web services) to communicate with eTrust Directory without using LDAP directly. The URL for the DSML Server is: http://localhost:8080/dsml/services/DSML. Using the DSML Server 503 How the DSML Server Works How the DSML Server Works The following happens when a DSML client uses DSML to communicate with a DSA through the DSML Server: 1. The DSML client sends a DSML request to the DSML Server. 2. The DSML Server translates the DSML request into LDAP and passes it on to the DSA. 3. The DSA responds using LDAP. 4. The DSML Server translates the DSA response from LDAP to DSML and sends it back to the DSML client. Server DN and Base DN When you connect to the DSML Server, you can specify the server DN. This is the root DN to which you will be connected. For example, if you connect to the Democorp DSA using DSML and you set the server DN to c=AU, c=AU is not displayed in the tree (in JXplorer), and the top node is o=DEMOCORP. If you use JXplorer or JXweb to connect to the DSML Server, you can also specify the base DN. This is the DN of the entry in the tree that you want displayed. The base DN is relative to the server DN. The base DN is not set by the DSML Server: instead, it is set by the client that connects to the server. For example, if you connect to the Democorp DSA using DSML and you set the server DN to c=AU, you could then also set the base DN to ou=National,ou=Customer,o=DEMOCORP. Because the base DN is relative to the server DN, you could not set the base DN to ou=National,ou=Customer,o=DEMOCORP,c=AU. 504 Administrator Guide How the DSML Server Works How the DSML Server Determines the LDAP URL To connect to an LDAP server, the DSML Server has to work out the LDAP URL of the DSA. The DSML Server does this in the following way: 1. The DSML Server checks the POST parameters of the HTTP request: ldapHost and ldapPort. 2. If these parameters aren't supplied, the DSML Server checks the configuration file dsml.properties for a server URL. For example, the server URL could look like this: ldap://computer27:19289 3. If the configuration file is not available, the DSML Server uses the default URL. If the DSML Server can determine the name of the local machine, this default URL will be: ldap://hostname:19289 If the DSML Server cannot determine the name of the local machine, this default URL will be: ldap://localhost:19289 Using the DSML Server 505 Connect to the DSML Server Connect to the DSML Server To connect to a DSML Server through JXplorer For information, see Connect to a Directory through DSML (see page 377). To connect to a DSML Server Connect to the server using the following URL: dsml/services/DSML If you use a URL of this form, the DSML client will look for connection details in the dsml.properties file. To connect to a DSML Server on a particular host and port Connect to the server using the following URL: dsml/services/DSML?ldapHost=computername&ldapPort=port-number where: computername Specifies the name of the computer on which the DSML service is running port-number Specifies the port number of the DSML service To connect to a DSML Server on a particular host and port with a server DN Connect to the server using the following URL: dsml/services/DSML?ldapHost=computername&ldapPort=port-number&ldapDN=DN where: computername Specifies the name of the computer on which the DSML service is running port-number Specifies the port number of the DSML service DN Specifies the server DN, where: %3d Represents the equal-to character ( = ) 506 Administrator Guide Change the DSML Properties %2c Represents the comma character ( , ) For example, use the following to represent the DN o=DEMOCORP,c=AU: o%3dDEMOCORP%2cc%3dAU. Change the DSML Properties The DSML properties are stored in a text file. At present, the only property you can control with this file is the URL for the LDAP server. To change the DSML properties 1. Open the following file in a text editor: Windows: %DXHOME%\..\dxwebserver\webapps\dsml\WEB- INF\dsml.properties UNIX: $DXHOME/../dxwebserver/webapps/dsml/WEB- INF/dsml.properties 2. Change the URL, then save the properties file. Using the DSML Server 507 Chapter 17: Using the Sample DSAs, Applications, and Tools These samples are not covered by your usual CA Support. However, your feedback is very welcome. Please see the Readme files in each sample directory for how to let us know about your comments or questions. This section contains the following topics: Implementing the Samples (see page 509) The Sample DSAs (see page 510) Sample Web Applications (see page 515) Sample Configuration Files (see page 520) Sample Tools (see page 521) Implementing the Samples In a default installation, these samples are installed but not set up. You need to install each sample you want to work with. By default, the sample directories and sample tools are installed under the following directory: Windows: %DXHOME%\samples UNIX: $DXHOME/samples By default, the web applications are installed under the following directory: Windows: %DXHOME%\..\dxwebserver\samples UNIX: $DXHOME/../dxwebserver/samples The sample configuration files are installed into the main configuration file directories. The default location is: Windows: %DXHOME%\config UNIX: $DXHOME/config For more information about setting up these samples, see Installing eTrust Directory for Windows (see page 571) and Installing eTrust Directory for UNIX (see page 601), and also the Readme files in each of the sample directories. Using the Sample DSAs, Applications, and Tools 509 The Sample DSAs The Sample DSAs This section describes the sample directories, and explains how to install them manually. What the Sample DSAs Are Useful For eTrust Directory provides a number of sample directories, which contain different DSA configurations and show different methods of populating a directory. You can also use these samples to explore the eTrust Directory features before setting up your own directory. When the Sample DSAs Are Installed When you run a default installation of eTrust Directory, the three sample directories are automatically installed, configured, and started. If you run a customer installation, you can choose whether to install the sample directories. How the Sample DSAs Work Together Together, the Democorp, Router, and UNSPSC sample directories form a single logical view of all of the directory information. It does not matter which directory you connect to. You see the same data because the DSAs cooperate to resolve a query or update through X.500 distribution. Router DSA DSP DSP Democorp UNSPSC DSA DSA 510 Administrator Guide The Sample DSAs The Democorp DSA The Democorp DSA models a fictitious company called Democorp. There are about 100 organizational units in the data, with approximately 1200 employees in total. The Democorp script demonstrates a front-end load of the directory using the DXmodify tool. The Democorp Directory Setup Script The setup script creates a DSA called democorp using an Ingres database called democorp. The directory is loaded using the DXmodify tool with the prefix O=DEMOCORP, C=AU. This is a demonstration of a front-end load in a directory. Front-end loads are useful for loading fewer than a few thousand entries and for loading data in already populated directories. The data is converted from comma-separated value (CSV) format to LDAP lightweight directory interchange format(LDIF) by using the csv2ldif tool. The resulting LDIF file is loaded in the directory by using the DXmodify tool. After loading, the democorp Ingres database is tuned. The setup script performs the following steps: 1. Creates the Democorp Ingres database called democorp. 2. Configures the Democorp initialization file, database file, knowledge file, and knowledge group file, and start the Democorp DXserver DSA. 3. Converts the Democorp CSV data to LDIF. 4. Loads the LDIF data in the Democorp directory. 5. Tunes the democorp Ingres database. Using the Sample DSAs, Applications, and Tools 511 The Sample DSAs The UNSPSC DSA The United Nations Development Program and Dun & Bradstreet merged their separate commodity classification coding schemes in 1999 to form the Universal Standard Products and Services Classification (UNSPSC). The levels let you search products more precisely because you confine the searches to logical categories, thus eliminating irrelevant hits. The levels also let managers perform expenditure analysis on categories relevant to the company's situation. The UNSPSC directory contains more than 10,000 entries. 512 Administrator Guide The Sample DSAs The UNSPSC Directory Setup Script The UNSPSC sample demonstrates a back-end load of the directory using the DXloaddb tool. The setup script creates a DXserver called unspsc using Ingres. This is an example of a back-end or bulk load by using the DXloaddb tool. Bulk loads are very fast because they bypass the DSA and load the data directly in the database. They are used for initial data loads or updating the entire contents of a directory. The data is converted from CSV format to LDIF by using the csv2ldif tool. The resulting LDIF file is loaded in the directory by using the DXloaddb tool. The UNSPSC setup script performs the following steps: 1. The script creates the UNSPSC Ingres database named unspsc. 2. The script configures the UNSPSC initialization file, database file, knowledge file, and the knowledge group file. 3. The script converts the UNSPSC CSV data to LDIF. 4. The script loads more than 10,000 LDIF entries in the UNSPSC directory. 5. The script starts the UNSPSC DXserver DSA. Use the bulk load tools ldifsort and DXloaddb to achieve a high-performance load of the UNSPSC data by directly loading the Ingres UNSPSC database. Using the Sample DSAs, Applications, and Tools 513 The Sample DSAs The Router DSA The Router sample demonstrates a router DSA configuration, where the DSA has no database, but has knowledge of two subordinate DSAs. This sample demonstrates how a router DSA does not require a database of its own. It also acts as a single point of entry into multiple directories as demonstrated with Democorp and UNSPSC. The Router Directory Setup Script The setup script creates a DXserver called Router with no database and starts it. The setup script performs the following steps: 1. Configures the Router initialization file, knowledge file, and knowledge group file. 2. Starts the Router DXserver DSA. 514 Administrator Guide Sample Web Applications Sample Web Applications eTrust Directory comes with some sample web applications. You can open the democorp and uddi applications from the Management and Samples page. For information about the sample web applications, see the Readme files in each of the sample tools directories. For a list of all ports in a default installation of eTrust Directory, see Port Numbers Used by eTrust Directory in the eTrust Directory Reference Guide. Sample Use of UDDI: uddiv3-demo This is a demonstration of a typical application of a UDDI server. The UDDI Flight Demo is a web site that searches for the cheapest flights between destinations. The web site queries a UDDI registry for a list of the web services it should connect to. Using the Sample DSAs, Applications, and Tools 515 Sample Web Applications Use the UDDI Demonstration These instructions describe how to immediately remove information from the dynamic web site by removing the name of a web services from a UDDI server. To set up the demonstration 1. Open your a web browser, and go to the following page: http://localhost:8080/uddiv3-demo 2. Choose an origin and destination from the dropdown lists, and click Go. 3. Open another copy of your web browser and go to the following page: http://localhost:8080/uddi-client 4. Click Connect. You should now have two browser windows: one page shows the UDDI Flight Demo, and the other shows the UDDI Client. To run a demonstration: Delete the Dirt Cheap Airline 1. In the UDDI Client, click the Log In button. The Login page opens. 2. Enter the following details: User name: Dirt Cheap Discount Airlines Password: secret 3. Leave the Info Selection list unchanged. 4. Click Log In. The Registered Information page for the Dirt Cheap airline opens. 5. From the Business menu, select Delete. The Delete Business page opens. 6. Select the uddi:ca.com:demo:DirtCheap business key, then click the Add button to add the business to list of business to be deleted. 7. Click OK to delete this business from the registry. 8. Click OK in the warning dialog. 9. If the business was successfully deleted, the following message appears near the top of the UDDI Client page: Confirmation: Successfully deleted the business: uddi:ca.com:demo:DirtCheap Owned By Dirt Cheap Discount Airlines. 10. In the UDDI Flight Demo, click Go. The panel refreshes, and the Dirt Cheap airline details no longer appear. 516 Administrator Guide Sample Web Applications To reset the demonstration Click the Refresh Demo link at the bottom of the page. This reloads the entire demo directory back to the original state. Using the Sample DSAs, Applications, and Tools 517 Sample Web Applications Data in the UDDI Flight Demo You can use the UDDI Client to browse and edit the data in the UDDI Flight Demo. You do not need to log in to browse, but if you want to edit data, you must log in. Each business is owned by a different user, and you must log in as the correct user to edit a business. The UDDI Flight Demo data includes the following users (the password for all of the businesses is secret): Air Standards Commission Arctic Airlines Banana Republic Air Cheap and Nasty Discount Air Dirt Cheap Discount Airlines Elbonia Airlines Fantasy Airlines Gedmeoudda Here Airlines Heretics Express Imcominghome Charters Jumbo Jetways KattleKlass Air Luxury Landing Air Merikan Airlines Nasty and Cheap Airlines Overpriced Airlines Passenger Panic Air QuickStop Airways Random Destination Air Sweet Air Transit Lounge Trips Upper Class Airlines Vermicelli Air WetLanding Airways XRay Everything Air 518 Administrator Guide Sample Web Applications Yellowbelly Air ZeroCrash Charters For example, to edit the data under the key uddi:ca.com:demo:TransitLounge, log in with the following details: User name: Transit Lounge Trips Password: secret Sample SAML Server The SAML server is a lightweight SAML attribute server. This sample implements some of the SAML Standard 1.0. The SAML server lets you use a SAML attribute query to ask the directory for the value of particular attribute in a particular entry. The SAML attribute server returns a SAML attribute assertion that states the value of the attribute for that entry. This allows client applications that use SAML (including web services) to communicate with eTrust Directory without using LDAP directly. This is usually done as part of a security request. For example, the request might be "What is the group attribute for John Citizen?', and the response might be "John Citizen has the group attribute 'payroll' ". Access the SAML Server 1. Install the SAML server. For instructions on Windows, see Install the Sample Web Applications (see page 587). For instructions on UNIX, see Install the Sample Web Applications (see page 623). The file saml.properties points to Router on the current computer. 2. Connect using a SAML client to the web servers port. Test the SAML Server For testing you can use the 'samlping' command line program that allows for arbitrary SAML attribute requests to be sent to the server. Run 'samlping -?' for more details. Using the Sample DSAs, Applications, and Tools 519 Sample Configuration Files Sample SPML Server The SPML sample server receives add, modify and delete user requests and changes the underlying directory appropriately. In this way one can add users to the directory, modify the attributes of existing users, or delete users. The SPML sample server operates with the existing directory data, so direct LDAP queries can be made on the same data. This is a useful way of checking that the SPML queries are performing as expected. In effect, SPML is simply another way to modify user data, and is conceptually very similar to LDAP. The SPML server sample uses the SPML 1.0 standard. Access The SPML Sample 1. Install the SPML server. For instructions on Windows, see Install the Sample Web Applications (see page 587). For instructions on UNIX, see Install the Sample Web Applications (see page 623). The file spml.properties points to Router on the current computer. 2. Connect using a SPML client to the web servers port. Sample Configuration Files The sample DSAs use sample configuration files. You can use these configuration files as templates for your own files. For information about the sample configuration files, see the Readme files in each of the sample DSA directories. 520 Administrator Guide Sample Tools Sample Tools The sample tools are some extra tools for managing eTrust Directory. These tools are provided for testing and demonstration purposes. The tools are installed into the following subdirectories in ../dxserver/samples: cmip A management client which retrieves management information from an Computer Associates DXserver using the CMIP protocol. democorp A setup script that automatically configures the Democorp DSA and populates it with data. This data is the staff directory for the fictional company, Democorp. This DSA is automatically set up during a default installation. dua A sample text-based Directory User Agent (DUA) that runs over DAP This can be used to execute scripts to add, modify or remove entries from the directory. This can also be used to perform searches. gateway Files in this directory that create the database tables for eTrust Directory for either Oracle or MS Sql server databases. Access to DBMS other than Ingres can be provided by the Ingres Gateway product (licensed separately). While using other DMBS is not yet officially supported, it has been tested as a proof-of-concept. languages Language certification sample files. These language files have been provided so that the user can test eTrust Directory operating systems other than English. Please only use the language files that relate to your operating system. ldua The LDAP directory client scripting DUA. This can be used to execute scripts to add, modify or remove entries from the directory. This can also be used to perform searches. router A setup script that automatically configures the Router DSA. This DSA does not use a database, has the prefix c = AU, and is aware of the Democorp and UNSPSC DSAs. This DSA is automatically set up during a default installation. schema Using the Sample DSAs, Applications, and Tools 521 Sample Tools A Perl script that translates a custom schema file to producing updated versions of the following files: schema.txt for the DXtools dxtype.txt and dxobject.txt for DXplorer snmp A management client which retrieves management information from an eTrust Directory DSA using the SNMP protocol. soak A tool 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. The DAP and LDAP script DUAs connect to the Democorp DXserver using SSL encryption or SSL authentication. trap A management application which receives SNMP traps from an eTrust Directory DSA. unspsc A setup script that automatically configures the UNSPSC DSA and populates it with data. This data is the United Nations Standard Product and Services Classification (UNSPSC) Code System. This DSA is automatically set up during a default installation. 522 Administrator Guide Sample Tools The DXcmip Tool An executable to request CMIP counters from the directory. The dxcmip program is a management client which retrieves management information from an Computer Associates DXserver using the CMIP protocol. The management information retrieved is defined in ISO 9594-10 (Committee Draft April 1995). Usage The dxcmip tool has the following command line format: dxcmip [-r[n]] host[:port] [psel] where: -r[n] refresh every n seconds. Default: 5 seconds host the hostname or IP address to contact port the CMIP port. Default: 19389 psel the OSI P-SELECTOR. Default: CMIP Using the Sample DSAs, Applications, and Tools 523 Sample Tools The dua Tool Sample text-based Directory User Agent (DUA) that runs over DAP This directory contains the DAP directory client scripting DUA. This can be used to execute scripts to add, modify or remove entries from the directory. This can also be used to perform searches. Example test scripts reside in the samples/test directory. These can be executed either by running the setup script from that directory. See the eTrust Directory Developer Guide for more details. Usage The general syntax for the dua client is: dua