Using the DirX Directory Administration Tools

This chapter summarizes the features and functions of the DirX Directory administration tools and explains when and why a DirX Directory administrator will want to use each one.

On Windows Server, you need to run the DirX Directory administration tools with administrator rights. Use Run as…​ from the context-sensitive menu to run the command prompt as Administrator.

Using DirX Directory Manager

DirX Directory Manager is a DirX Directory administration tool that you can use on Windows or Linux systems to access the DirX directory service through a DirX Directory LDAP server that is running on a local or remote Windows or Linux system.DirX Directory Manager is an LDAP client written in the Java programming language.It is capable of accessing any directory service that runs an LDAP server, not just DirX Directory.

For DirX Directory, you can use DirX Directory Manager to:

  • Manage the directory entries in the service’s Directory Information Tree (DIT)

  • Manage the directory schema

  • Manage shadowing and LDIF agreements

  • View and edit the Attribute Indices

  • View and edit the collective attribute subentries

  • View and edit the LDAP configuration subentries

  • View and edit the password policy subentry

  • View and edit the proxied authorization control subentry

  • View and edit the access control subentries

  • Perform SSL authentication

  • Create, edit, and run Tcl scripts in a convenient way

  • View audit log files

  • View LDAP and DSA Monitoring Information

The sections that follow briefly describe DirX Directory Manager’s graphical user interface and its functions. The DirX Directory Manager online help provides detailed usage information. The DirX Directory Manager release notes for DirX Directory provides information on how to start DirX Directory Manager on Windows and Linux systems.

When to Use DirX Directory Manager

Although DirX Directory Manager is intended for use mainly as a directory administration tool, both directory users and DirX Directory administrators can use it to browse and search the DirX Directory database. For DirX Directory administrators, DirX Directory Manager can be used as a dialog-based alternative to the dirxmodify command-line tool for performing small-scale schema administration. DirX Directory Manager also allows DirX Directory administrators to model a schema from an easy-to-use, dialog-based interface, and then export the schema to an LDIF file for future loading to an LDAP server via DirX Directory Manager, the dirxload or dirxmodify command line tools or an installation procedure.

Using the DirX Directory Manager Welcome View

When you start DirX Directory Manager, it displays its Welcome view. This view displays a list of LDAP servers to which you can connect. DirX Directory LDAP servers are identified by the text "DirX" in the Server Type field. To connect to an LDAP server, double-click it in the list, or select it and then click Open. If the selected LDAP server requires authenticated connection, DirX Directory Manager next displays a login dialog. Enter your distinguished name (DN) and password in the fields provided. When you have successfully connected to the LDAP server (anonymously or authenticated), DirX Directory Manager’s main window appears.

You can also use the Welcome view to:

  • Manage LDAP server profiles; the section "Adding LDAP Servers to DirX Directory Manager" describes this task in more detail

  • View the documentation that is available with DirX Directory Manager

  • Manage scripts with the script manager (the online help describes this task in more detail)

Using the DirX Directory Manager Main Window

DirX Directory Manager’s main window represents LDAP servers as "view groups". The main window’s view bar displays the DirX directory service view group and the view groups of any other LDAP directories that you (or another administrator) have added to DirX Directory Manager. You can click a view group to display its views or use the DirX Directory Manager menu bar to display them.

From the DirX Directory view group, you can select from four different views:

  • The Directory Entries view, which allows you to view and edit user directory entries and their attributes and perform simple and complex searches on entries and attributes

  • The Quick Search view, which allows you to search for user directory entries using selected search filters and display the results of the search (entry name and a subset of its attributes)

  • The Configuration view, which allows you to view and edit administrative directory entries and their attributes, such as LDAP server configuration subentries, access control, collective attribute subentries, proxied authorization control subentries, the password policy subentry, and context prefixes

  • The Schema view, which allows you to view and edit the object classes and attribute types defined in the DirX Directory schema using a hierarchical tree view, and manage attribute indexes (Database)

  • The Replication view, which allows you to view and edit all shadowing and LDIF agreements and to perform the switch operation

  • The Monitoring view, which allows you to display statistics and network management information (NMI) data collected by the DirX Directory DSA and LDAP server.

The following figure shows the DirX Directory view group with the Directory Entries view open.

DirX Directory Manager View Group
Figure 1. DirX Directory Manager View Group

By default, authenticated users (users who have connected to the DirX Directory LDAP server with a distinguished name and password) are permitted to use any of these views, while anonymous users can only use the directory entries and quick search views. DirX Directory administrators can use DirX Directory Manager to change this default.

Using the Directory Entries View

The DirX Directory Entries view consists of a browse pane and a search pane. The browse pane displays a hierarchical tree view of the directory entries in the DIT on the left, and the attributes of a selected entry in the tree on the right. This view of the DIT displays only those entries that are typically visible to users, such as directory users and groups; administrative entries are not displayed. From the Browse pane, you can:

  • Browse the directory entries in the DIT

  • Create, copy, rename and delete individual directory entries and subtrees of entries

  • Modify the attributes of directory entries

  • Move individual directory entries and subtrees of entries to different locations in the DIT

The search pane consists of two windows: a window with fields that permit you to perform both simple and complex searches on entries and attributes in the DIT, and a window that displays the search results.

You can configure DirX Directory Manager’s search function to:

  • Set limits on the amount of time a search can take and the number of entries that can be returned

  • Ignore or automatically follow referrals returned by the LDAP server

  • De-reference all aliases (entries that refer to other entries), de-reference only those aliases encountered in search bases, de-reference only those aliases returned in a search result, or perform no de-referencing at all

You make these settings on a per-server basis via a DirX Directory Manager server profile, which permits you to maintain different settings for each LDAP server with which DirX Directory Manager communicates.

Using the Quick Search View

The DirX Directory Quick Search view displays a window from which you can perform searches on user directory entries in the DIT using simple search filters such as "begins with" or "ends with". The following figure shows an example of this view.

DirX Directory Manager Quick Search View
Figure 2. DirX Directory Manager Quick Search View

When you make a search from this view, DirX Directory Manager displays in column format in the quick search window the names of the users returned by the search and a small subset of their attributes, including their office telephone number, their mobile phone number, their email address, and the number of their department, as illustrated in the following example.

DirX Directory Manager Quick Search Results
Figure 3. DirX Directory Manager Quick Search Results

To manage the columns that are displayed in the quick search window, right-click a column in the display and use the pop-up menu that appears.

Using the Configuration View

The DirX Directory Configuration view displays a hierarchical tree view of all directories in the DIT, including all administration-related entries such as access control subentries, collective attribute subentries, proxied authorization control subentries, password policy subentry, and LDAP configuration, SSL, and audit subentries. The following figure shows an example of the configuration view.

DirX Directory Manager Configuration View

DirX Directory Manager Configuration View

You can use the Configuration view to:

  • View and edit collective attribute subentries

  • View and edit password policy subentries

  • View and edit proxied authorization control subentries

  • View and edit access control subentries. An ACI wizard helps you to specify new access control items

  • Create and manage LDAP configuration, logging, auditing, and caching

You can also view the attributes of an LDAP server’s LDAP root entry by displaying its server profile or clicking the root node in the tree.

Using the Schema View

When you start DirX Directory Manager, it reads the directory schema of the LDAP server you have specified in the startup dialog. The schema view displays a hierarchical tree view of the object classes and attribute types contained in the "read-in" schema, as shown in the following example.

DirX Directory Manager Schema View
Figure 4. DirX Directory Manager Schema View

You can use the Schema view to:

  • Create new object classes and attribute types.

  • View the properties of object classes and attribute types.

  • Delete object classes and attribute types. Note that the delete operation is a "logical" delete: the syntax definition of the deleted object remains in the schema and you can re-create the object using an "undelete" operation.

  • Compare two schemas.

  • Export the complete directory schema or the differences between two schemas to an LDIF content file.

  • Import all or part of a schema contained in an LDIF file into the directory schema (note that DirX Directory Manager does not perform any schema checking on the imported data). DirX Directory Manager displays a list of the object classes and attribute types contained in the file, and you can select which schema elements you want to import from this list.

  • View and edit the indices maintained for attributes in the DirX Directory DSA database.

Using the Replication View

The DirX Directory Replication view displays a hierarchical tree view of all shadowing and LDIF agreements. The Shadowing Graph area displays a graph of all shadowing agreements. The following figure shows an example of the Configuration view.

DirX Directory Manager Replication View

DirX Directory Manager Replication View

You can use the replication view to:

  • Create new shadowing and LDIF agreements

  • Delete shadowing and LDIF agreements

  • Manage, that means establish, enable, disable or terminate, shadowing and LDIF agreements

  • Display the status of shadowing and LDIF agreements

  • Switch the supplier DSA of shadowing agreements

Using the Monitoring View

The Monitoring view displays a hierarchical tree view for the monitoring of LDAP server- and DSA-related data. For the LDAP server, a number of MIBs can be retrieved as well as information about the environment, audit and configuration default settings. From the DSA, output and detailed statistic data concerning the DBAM database are displayed. The Monitoring view is retrieved via extended LDAP operations from the server processes.

DirX Directory Manager Monitoring View

image7

Modifying User Passwords

DirX Directory Manager provides menu selections and dialogs that permit you to change the password you use to authenticate to an LDAP server. You can also use DirX Directory Manager to create, change or delete the password of any user directory entry in the DIT, if you have the appropriate access rights to the entry.

DirX Directory Manager is a password policy-aware application; that is, it supports all management operations with respect to password expiration, aging, and account locking.

Adding LDAP Servers to DirX Directory Manager

When you have set up multiple DirX Directory LDAP servers (or other LDAP directories), you can make them available for management via DirX Directory Manager by adding them to DirX Directory Manager’s view bar.To add an LDAP server to DirX Directory Manager’s view bar, you create a server profile for it in DirX Directory Manager’s Welcome view.A server profile provides DirX Directory Manager with connection and capabilities information about an LDAP server.Connection information includes the server’s host name or IP address, the port on which it listens for LDAP requests, and whether or not authentication is required.Capabilities information includes the supported LDAP protocol version, whether or not the server supports SSL connections, and the name of the topmost entry in the DIT from which DirX Directory Manager is to display entries.DirX Directory Manager uses the information in a server profile during startup to connect to the correct LDAP server.DirX Directory Manager provides menu selections and dialogs to create new server profiles and to copy, edit, and delete existing server profiles.

Importing and Exporting LDAP Directory Contents

DirX Directory Manager provides menu selections and dialogs that permit you to:

  • Import data from an LDIF file (content or change) or a DSML file (v1 or v2) into the LDAP server to which it is connected

  • Export directory entries into an LDIF content file or a DSML v1 file

Using dirxcp

The dirxcp program is a DUA that communicates directly with DSAs over DAP and with LDAP servers over LDAP.It provides a command-line interface designed for use in scripts; directory administration with scripts provides a reliable way to perform the same task across many different servers and a method for ensuring reproducible results when compared to administration with a dialog-based tool.The DirX Directory Administration Reference provides a detailed description of dirxcp command-line syntax.

The dirxcp program is the primary tool for performing directory service administration and is intended for use by both system administrators and directory service end users.System administrators must use dirxcp over LDAP and also DAP to perform their tasks; users should only use dirxcp over LDAP.All dirxcp operations are subject to access control and schema rules: you can only perform an operation if access rights are granted to the object or the action itself is granted, and if the operation is consistent with the schema definition.

Use dirxcp to:

  • Manage entries and subentries in the DIT, that is, manage DSEs whose DSE-type (DSET) attribute value is ENTRY or SUBENTRY.This includes the following tasks:

    • Creating subentries, including access control subentries, collective attribute subentries, and LDAP configuration subentries

    • Populating the DIT

    • Creating, modifying, and deleting entries and subentries

    • Browsing on entries in the DIT

  • Manage administrative points in the DIT, that is, manage DSEs whose DSE-type attribute value is ADM_POINT. This includes the following tasks:

    • Modifying and browsing autonomous administrative points

    • Creating, modifying, browsing and deleting non-autonomous administrative points

  • Manage the service control settings for directory operations; these settings control how directory operations are performed

  • Return the values of the following operational attributes (operational attributes whose usage attribute value is DIRECTORY-OPERATION):

    • create-timestamp

    • modify-timestamp

    • creators-name

    • modifiers-name

    • administrative-role

    • subtree-specification

    • attribute-types

    • object-classes

    • structural-object-class

    • access-control-scheme

    • prescriptive-ACI

    • subentry-ACI

    • entry-ACI

You cannot use dirxcp to:

  • Manage entries whose DSE-types are not ENTRY, SUBENTRY or ADM_POINT. These entries are:

    • The root DSE

    • Glues

    • Knowledge references (subordinate, superior and cross references)

  • Create autonomous administrative points

  • Return the values of the following operational attributes:

    • DSE-type

    • my-access-point

    • superior-knowledge

    • specific-knowledge

    • supplier-knowledge

    • consumer-knowledge

    • secondary-shadows

    • supported-application-context

  • Return information about or manage:

    • Shadowing operational bindings (stored in the cooperating-DSA attribute)

    • LDIF operational bindings (stored in the cooperating-DSA attribute)

    • User policies

    • DSA policies

    • Other global policies

  • Activate and deactivate logging

  • Activate, deactivate and configure auditing

  • Start and stop the DSA and LDAP server

  • Optimize the database configuration file

The dirxcp program requires that you first bind to the DirX Directory service before you can use it to perform user and administrative tasks.When you issue the dirxcp bind command, you can specify which protocol (DAP or LDAP) you want to use for subsequent dirxcp operations.You can (and should) use dirxcp over LDAP for all user and most administrative operations.However, some structured attributes—for example, the subtree specification (SS) attribute—and attributes with ACL syntax (prescriptive, subentry and entry ACI attributes)—are very difficult to specify in LDAP syntax.You must use dirxcp over DAP when you are working with these types of attributes.For example, because the SS attribute is a mandatory attribute of a subentry, you must use DAP when creating subentries.However, you can use LDAP to modify the attributes of subentries, especially the LDAP attributes of LDAP subentries.The DirX Directory Syntaxes and Attributes describes the DAP and LDAP syntax for DirX Directory attributes.

Using dirxadm

The dirxadm program is a DSA management tool that administrators can use to communicate directly with DSAs using an internal management API.Directory administrators must use dirxadm to perform directory administration operations that cannot be carried out by dirxcp over DAP or LDAP (because these protocols do not support the operations).The DirX Directory Administration Reference provides a detailed description of dirxadm command-line syntax.

The dirxadm program is a powerful program intended only for directory service system administrators.The dirxadm program is a DIB manipulation tool that communicates directly with the DSA using an internal management interface.It is not a DUA, cannot send LDAP or DAP requests, and cannot initiate distributed operations.

Because the dirxadm program can bypass access control information and schema consistency checks, it is intended for use by system administrators who have a thorough understanding of the directory information database (DIB) and its maintenance, and is not intended for end users.Use dirxadm only when dirxcp cannot perform the operation.

Use dirxadm to:

  • Manage the entries that dirxcp cannot manage; these tasks include:

    • modifying the root DSE (the root DSE is created automatically during installation and cannot be deleted)

    • creating autonomous administrative points

    • creating glues

    • creating, modifying, browsing and deleting knowledge references (subordinate, superior and cross-references)

  • Display the operational attributes that dirxcp cannot display:

    • DSE-type

    • my-access-point (this attribute is managed by the DIRX_OWN_PSAP and DIRX_DSA_NAME environment variables; see the DirX Directory Administration Reference for details)

    • superior-knowledge

    • specific-knowledge

    • supplier-knowledge

    • consumer-knowledge

    • supported-application-context

  • Manage:

    • Shadowing operational bindings (stored in the cooperating-DSA attribute)

    • LDIF operational bindings (stored in the cooperating DSA attribute)

    • User policies

    • DSA policies

    • Other global policies

  • Activate and deactivate logging

  • Activate, deactivate and configure auditing

  • Start and stop the DSA on Linux systems; on Windows, you can use dirxadm to stop the DSA and LDAP server, but you must use the Administration Tool Services to start it.

  • Optimize the database configuration file

  • Add “custom” attribute types and object classes to the standard DSA schema

System administrators using dirxadm should take care that they do not:

  • create entries that are inconsistent with the schema in force, because clients such as dirxcp will not be able to access these entries

  • create attributes that do not belong to the entry’s object class

  • omit mandatory object class attributes

  • create erroneous references

  • omit operational attributes managed by the DSA

Unless you are using it to start the DirX Directory service, the dirxadm program requires that you first bind to the DirX Directory service before you can use it to perform administrative tasks.Unlike dirxcp, the dirxadm bind command does not offer a selection of protocols to use for subsequent dirxcp operations; dirxadm communicates with the DirX Directory service over an internal management API.

Using Tcl Scripts with dirxadm and dirxcp

Both dirxcp and dirxadm are built on a portable command language called the Tool Command Language (Tcl 8.3).Tcl permits the use of variables, if statements, list-processing functions, loop functions, and many other well-known command-language features.These features allow you to create Tcl scripts to perform customized batch processing of directory administration tasks.

We strongly recommend that you develop Tcl scripts that you can use to perform complex administration tasks.Putting complex dirxadm and dirxcp commands into scripts saves you time, since you only type the commands once and avoids the hazard of making typographical errors each time you give the commands.

For example, the following script contains the dirxadm command necessary to establish the default password for the DSA.In the following script:

  • The dirxadm command is identified by a text string that is displayed online with the Tcl puts command.

  • The Tcl catch command is used to place the results of each command into the status variable.

  • The Tcl if statement is used to test whether or not the command is successful.If the command fails, the puts command is used to display the contents of the status variable.

    # This script is a dirxadm script that establishes
# - the default password of the DSA
#
#
# This dirxadm command modifies the default password of your
# local DSA
puts "modify own default password"
catch { modify / -addattr {DSAP={DSA={/},
                                  OPT=CHAINING,
                                  AP={PWD=MY_NEW_PASSWORD}
                                 }
                          }
      } status

if {$status == ""}   \
   then {puts "operation ok"}   \
   else {puts "$status"}

Note the presence of the line continuation character “\”.In scripts it is needed if Tcl commands stretch over several lines and the line break is not enclosed in curly braces { }.In interactive mode, you cannot use the line continuation character when you want to continue a dirxcp command on a new line.You can issue a dirxcp command that is longer than will fit on a line simply by continuing to type the command line without typing an ENTER or RETURN.Although the resulting command line will appear to be “wrapped” on the display, internally it is a single line.

You can find more examples of Tcl scripts in the directory install_path/scripts, which is installed on your system when you install DirX Directory.Refer to a book about Tcl for instructions on developing Tcl scripts; for example, Practical Programming in Tcl and Tk, by Brent B. Welch, or Tcl and the Tk Toolkit, by John K. Ousterhout.

Using dirxload

The dirxload program is a command-line tool that you can use to bulk-load very large amounts of data very quickly into the DirX Directory database.The tool can load 1,000 entries per second—one million entries in twenty minutes.

Before you run dirxload, Meta The data to be loaded must be contained in one or more LDIF content files; you specify the pathnames of these files on the dirxload command line.

You can run dirxload in "simulation" mode, where it processes the content file(s), but does not actually create the data in the DirX Directory database.You can also specify a dirxload command line option that saves LDIF entries that dirxload rejects into a file, which allows you to evaluate and fix any problems in the LDIF content file(s) before you perform the actual loading operation.

See the DirX Directory Administration Reference for complete details about dirxload command-line syntax.

Using dirxmodify

The dirxmodify program is a command-line tool that permits you to load LDIF content and LDIF change files into any LDAP directory—not just DirX Directory—over LDAP v3. You can use dirxmodify to:

  • Load an empty LDAP directory with entries in an LDIF content file

  • Synchronize an LDAP directory with directory entry modifications in an LDIF change file

  • Update an LDAP server schema with modifications in an LDIF change file

  • Perform off-line processing and checking of LDIF files

When you invoke dirxmodify, it binds to an LDAP server; you can use command line options to specify the LDAP server to which you want to connect.You can bind as an anonymous user or you can provide simple authentication credentials (distinguished name and password) as command-line options.The user represented by the distinguished name must have the permissions that are necessary to perform modifications to the target directory.

You can run dirxmodify in "simulation" mode, where it processes the content or change file(s), but does not actually create or modify the data in the DirX Directory database.You can also specify a dirxmodify command line option that saves LDIF entries that dirxmodify rejects into a file, which allows you to evaluate and fix any problems in the LDIF content file(s) before you perform the actual load operation.

The dirxmodify tool provides command line options that allow you to make changes to the LDIF content or change files "on the fly" during the loading process.The tool makes the updates internally to the read-in files; the files themselves are not changed.You can also specify attributes in the files that should not be loaded into the database, and you can use a command line option to position dirxmodify so that it reads from a specific entry in a content or change file.

The dirxmodify program performs its directory loading operations over LDAP.As a result, its bulk-loading operation is slower than dirxload, which can perform bulk loading at 10 to 20 times the speed of a protocol-initiated operation.

See the DirX Directory Administration Reference for complete details about dirxmodify command-line syntax.

Using dirxbackup

The dirxbackup program is a command-line tool that you can use to perform normal daily backup operations on the DirX Directory database in conjunction with file compress/uncompress tools such as gzip.The dirxbackup program allows you to:

  • Save the active DirX Directory (DBAM) database to a database archive file (or to standard output)

  • Restore a saved DirX Directory database in an archive file (or from standard input) to the active DirX Directory database

  • Verify a database archive file for consistency

Do not use non-DirX backup tools to back up the DBAM database.Only dirxbackup performs the necessary synchronization with other DirX processes using the database.Using non-DirX backup tools that access DBAM database files or devices can produce inconsistencies in the database and / or in the dirxbackup archive file.

See the DirX Directory Administration Reference for complete details about dirxbackup command-line syntax and operation.