dirxadm

Synopsis

dirxadm [script_name [arg1] [arg2 …]] | -c command | -V]

Purpose

Manages a directory system agent (DSA). The dirxadm program supports the following objects:

abbr

Displays valid abbreviations for object classes, attributes, and structured attributes

audit

Manages audit logging

db

Manages database configuration

dse

Manages DSE and policy administration that cannot be performed by using dirxcp

ldap

Performs LDAP server administration

lob

Manages LDIF agreements

nmi

Displays network management information from the DSA management information base (MIB)

progsvr

Manages the Progsvr

sob

Manages shadowing agreements

sys

Performs directory system administration

There are some utilities also which are described in the util (dirxadm) page. A complete list of these utilities is displayed when performing a dse commands operation.

Arguments

script_name

  • Filename of a user-defined script containing dirxadm commands.

arg1 … argn

  • Specify arguments to the user-defined script specified in script_name.

Options

-c command

  • Executes the dirxadm or Tcl commands or commands specified by command.

-V

  • Displays the DirX Directory product version, in the format:
    product_version build_id date time
    For example:
    DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit
    The dirxadm initialize operation also writes the build version to the dirxadm trace file.

Description

The dirxadm program is a command-line interface that system administrators can use to manage the DSA. You can use it to:

  • Administer the DSEs and DSA policies using operations such as create, modify, delete, list, and show.

  • Administer the operational bindings (LDIF agreements and shadowing agreements) using operations that permit you to create an operational binding, modify an existing binding, display the details of operational bindings, and so on.

  • Configure the database used by the DSA.

  • Display the abbreviations that it uses for attributes.

  • Display network management information contained in the DSA’s management information base.

  • Activating, deactivation and configuring audit logging.

  • Perform system administration tasks, such as starting and stopping the DSA, activating and deactivating logging.

The DSA and the LDAP server save all update operations issued by dirxadm in the file ADM*process_id.number. This file is located in the server’s directory for log files. (See section *Logging Configuration Files for details.)

Note that every operation stops after 25 seconds except the dse list and the dse search operation (see dse (dirxadm) page for details), the lob and sob operations, the db attrconfig operation. The lob and sob operations stop after 5 minutes, the db attrconfig operation after 3 days.

Tcl Command Language

The DirX Directory administration program is built on a portable command language called the tool command language (Tcl). Tcl permits the use of variables, if statements, list-processing functions, loop functions, and many other features commonly found in command languages. The program extends these features to provide a set of commands for manipulating DirX Directory administration objects. The program also includes task scripts to help administrators perform some routine DirX Directory management functions.

Escaping in Distinguished Names and Attribute Values

The following special characters must be escaped in distinguished names and attribute values:

  • a SPACE or # character at the beginning of a string

  • a SPACE character at the end of a string

  • the characters comma (,), plus sign (+), minus sign (-), quotation mark ("), backslash (\), lower than (<), greater than (>), equal (=), semicolon (;), dollar ($), quote ('), colon (:), or brackets ((, ), \{, })

To escape these characters

  • prefix the character by a backslash, for example O=Sue\, Grabbit and Runn

  • enclose the distinguished name or attribute in curly brackets (\{}), for example \{O=Sue, Grabbit and Runn}

  • enclose the distinguished name or attribute in quotation marks (""), for example "O=Sue, Grabbit and Runn". You must use quotation marks if your string contains a Tcl variable.

See also section Reserved Characters in chapter DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes.

Escaping in Filenames

The backslash character (\) is a reserved character in Tcl. A backslash in a file name must therefore be escaped, for example tmp\\config.out.

Tcl provides a command that converts the specified file name into the plattform dependent file name. The syntax of this command is as follows:

  • [file nativename filename]

Here is an example how to use this command in dirxadm:

dirxadm> import_dbconfig [file nativename tmp/config.out]

The Abbreviation Files

The DirX Directory administration program uses the DirX Directory abbreviation files (dirxabbr and dirxabbr-ext*) to convert attribute abbreviations and object identifier strings to ASN.1 object identifiers. The program also uses these files to determine the attribute syntax, the full name of the attribute, and other information.

System Administrators and dirxcp

Because the dirxadm program can bypass access control information and schema rules, it is intended for use by system administrators who possess a thorough understanding of the directory information database (DIB) and its maintenance. It is not intended for end users. Directory service end users can use the dirxcp command to access the DSA, since this program performs access control.

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

Invoking dirxadm

You can invoke dirxadm commands in interactive mode and command mode.

Interactive Mode

Activate interactive mode by entering the dirxadm command without any arguments. At the dirxadm prompt, enter a dirxadm or Tcl command; dirxadm runs the command, displays the result, and is ready to accept another command.

% dirxadm
dirxadm> dse show /O=my-company/OU=Sales/CN=Tinker
dirxadm>

Instead of entering a dirxadm or Tcl command enter the keyword source followed by the filename of a script that contains dirxadm commands, other valid Tcl commands, or both, for example

dirxadm> source myown.tcl

dirxadm then runs the script, displays the result, and is ready to accept another command.

Command Mode

Activate command mode from the system prompt by using one of the following methods:

  • Enter the dirxadm command with the filename of a script that contains dirxadm commands, other valid Tcl commands, or both, as follows:

    % dirxadm myown.tcl

  • Enter the dirxadm command with the -c option followed by a list that contains one or more dirxadm commands or Tcl commands, for example:

    % dirxadm -c “dse search -onelevel -p;dse show -p”

    Enter multiple commands by separating them with a semicolon (;) and enclosing the commands in quotation marks (“”). Remember to escape shell metacharacters (for example, by enclosing them in quotation marks). Multiple commands must be on a single line.

    When you use the -c option, operation results return to the interpreter, not to the shell. if you enter multiple operations, the output of only the last operation is returned to the shell. You can solve this problem by using the following workaround:

    % dirxadm -c “puts [dse show /C=de -allattr]; puts [dse show -p]”

Terminating dirxadm

Terminate an interactive dirxadm session by using the exit or quit commands. Use the following syntax:

  • exit n

  • quit n

Use the n argument to specify the exit value returned to the shell. The following example terminates a session and returns an exit value of 56 to the shell:

dirxadm> exit 56

Exit Codes

By default, dirxadm returns zero (0) on success and a non-zero value if a command fails. The exit codes for failure are:

1

An invalid command line was specified, for example, an invalid option (for example, you specified dirxadm -z)

2

The specified file does not exist (for example, dirxadm zz.tcl)

3

The evaluation of the file failed (for example, because of an incorrect command in the file)

4

The evaluation of the command failed (for example, because of an incorrect command in the dirxadm -c command line)

5

Tcl initialization failed

8

Initialization of the thread environment failed

Startup Scripts

When you invoke dirxadm, the following script files are run in the order shown:

/init.tcl

  • Contains the standard Tcl initialization scripts with definitions for the unknown command and the auto_load facility. The Tcl command info library returns the location of the file init.tcl.

$dirxadm_library/init.dirxadm

  • Contains the initialization scripts that implement the dirxadm commands and tasks. The implementation sets the Tcl variable dirxadm_library to install_path/client/conf.

$HOME/.dirxadmrc

  • Contains user customizations.

$TCL_PATH/user_script.tcl

  • Contains user-defined scripts within one or more user-specified directories defined with the TCL_PATH environment variable.

Command Syntax

A dirxadm command has the following syntax:

  • [object] operation [argument] [-option [opt_arg]] …​

where:

object

  • Specifies the name of a dirxadm administration object. The dirxadm program supports the following objects:

    abbr

    Displays valid abbreviations for object classes, attributes, and structured attributes

    audit

    Manages audit logging

    db

    Manages database configuration

    dse

    Manages DSE and policy administration that cannot be performed by using dirxcp

    ldap

    Performs LDAP server administration

    lob

    Manages LDIF agreements

    nmi

    Displays network management information from the DSA management information base (MIB)

    progsvr

    Manages the Progsvr

    sob

    Manages shadowing agreements

    sys

    Performs directory system administration

    Specifying an administration object is optional; if you do not specify an object on the command line, the specified operation is performed on either the dse or the sys administration object. For ambiguous operations, the default object is dse.

    For complete descriptions of these administration objects, refer to the individual object reference pages, for example, the abbr reference page.

operation

  • Specifies the name of an action such as create, show, or delete, that is to be performed on an administration object. Refer to the individual object reference pages for complete descriptions of the operations supported by each dirxadm object. Common operations for each object are help and operations.

argument

  • Specifies the name of one or more specific objects to operate on. Refer to the individual object reference pages for descriptions of the arguments supported by various objects.

-option

  • Specifies a qualifier that controls the precise behavior of a dirxadm command. Most, but not all, dirxadm commands take options. Some options take an argument, opt_arg, which can be a name or a value.

Line Continuation

dirxadm commands in scripts can use the backslash character (\) as the line continuation character. In interactive mode, there is no continuation character. Instead, you must continue typing. The line automatically wraps if your characters extend beyond the line end. If you press the Enter/Return key, the information you have typed is sent to the system for processing. You should press the Enter/Return key only when you have typed all information required for the command to process.

Command Processing

The dirxadm command supports the Tcl built-in commands as well as its own commands. A command unknown to dirxadm is passed to the unknown command, which evaluates it as follows:

  • If unknown finds the command is in a dirxadm script file, dirxadm runs it.

  • If unknown finds that the command is an executable Linux program, dirxadm runs it. Consequently, you can invoke any Linux command from the dirxadm prompt, for example, ls -l.

  • If unknown finds that you invoked the command at the top level of the dirxadm shell and that the command requests C-shell like history substitution (such as !!, !*number or *^*old\^new), *dirxadm emulates the C shell’s history substitution.

  • If unknown finds that you invoked the command at the top level of the dirxadm shell and the command is a unique abbreviation for another command, dirxadm runs that command.

Abbreviations

The dirxadm command uses two mechanisms to abbreviate object names, operation names, and options to the shortest unique string in interactive commands.

The first mechanism relies on the unknown command (described in the Command Processing section of this reference page).

The second mechanism is built into the individual dirxadm commands themselves. This mechanism allows the operation name to be abbreviated to the shortest unique string supported by the object, and the option names to be abbreviated to the shortest unique string representing an option supported by an object and operation. For example, consider the following dirxadm commands:

show -pretty
abbr operations

In the abbreviated form, the same operation can be entered as follows:

show -p
abbr o

Although abbreviating commands is a good way to save keystrokes in typing interactive commands, abbreviations are not recommended for use in scripts. New procedures in scripts can cause abbreviations to become ambiguous. Furthermore, abbreviations are not always portable. When scripts move to other machines, some definitions may be left behind so scripts will not work correctly. Always spell out complete names in scripts.

Tcl Variables

All dirxadm commands set several Tcl variables on invocation. The variables contain the name of the directory in which startup scripts are stored, the return value of the last command, and so on. To avoid unnecessary typing, you can substitute the value of these variables into the next command.

Tcl variables behave just like other variables in dirxadm. Thus, you can trigger variable substitution by prepending a dollar sign ($) before the name of the variable. Alternatively, you can trigger substitution by using set. The Tcl variables can only be set using the dirxadm program.

The dirxadm program defines the following variables:

_cwo

  • Holds the current DSA-specific entry (DSE). (The abbreviation “cwo” stands for “current working object”.) The following command sets the current working DSE:

    dirxadm> set _cwo /O=my-company

    The _cwo variable then contains the following value:

    dirxadm> puts $_cwo
/O=my-company

    Note that the variable is set to the specified value only if it exists in the directory information tree (DIT); if the value does not exist, the command returns an error. The default current working DSE is the root DSE.

dirxadm_library

  • Holds the name of the directory in which the dirxadm startup scripts are stored. The user cannot set this variable.

_t61

  • Holds a flag that indicates whether user-specified strings are represented in T61 format. By default, dirxadm assumes that strings are specified in local format (ISO8859-1), and that conversion to T61 format must be performed. If this variable is set to TRUE, dirxadm does not convert user-specified strings.

_localcode

  • Specifies the character set, with one of the following keywords:

    • Latin1 - Default Windows character set (only used in data files). This is the default value.

    • UTF8 - LDAP / Tcl character set (only used in data files).

    • PC850 - PC DOS character set only (only used in DOS windows).

    This variable is supported only on Windows systems.
    You can specify attribute values in different code sets independent of the value of this variable by using Tcl operations. For example the value
    sn=k[encoding convertfrom utf-8 "\xc3\xcb"]bel
    specifies the value of the surname (sn) attribute in UTF-8 code.

Line Recall and Editing

You can edit a line before it is sent to dirxadm by using control characters and escape sequences. To use a control character, press and hold down the Ctrl key while pressing the appropriate character key. To use an escape sequence, press and release the Esc key and then press and release one or more character keys. Escape sequences are case sensitive; control characters are not.

You can enter an editing command anywhere on a line. In addition, you can press the RETURN key anywhere on the line.

To indicate that an action should be repeated a desired number of times, precede the escape or control characters with Esc n, where n is the number of times to repeat the action. For example ESC 4 Ctrl-d (pressing the Esc key and the number 4 key and then pressing and holding down the Ctrl key while pressing the d key) deletes the next four characters on a line. ESC 4 Esc DEL deletes the previous four words on a line.

Control Characters for Editing

Use the control characters shown in the following table for line editing. For example to move to the beginning of a line, press and hold down the Ctrl while pressing the A key.

Control Character Action Performed

Ctrl a

Move to the beginning of the line.

Ctrl b

Move left (backward) one character. You can repeat this action by preceding the control characters with Esc n.

Ctrl d

Delete the character highlighted by the cursor. You can repeat this action by preceding the control characters with Esc n.

Ctrl e

Move to the end of the line.

Ctrl f

Move right (forward) one character. You can repeat this action by preceding the control characters with Esc n.

Ctrl g

Sound the terminal bell.

Ctrl h

Delete character before the cursor. You can repeat this action by preceding the control characters with Esc n.

Ctrl i

Complete the filename. (The TAB key performs the same function.) (See Filename Completion.)

Ctrl j
Ctrl m

Send the completed line to dirxadm. (The RETURN key performs the same function.)

Ctrl k

Delete to the end of the line (or column). You can repeat this action by preceding the control characters with Esc n.

Ctrl l

Redisplay the line.

Ctrl n

Get the next line from history You can repeat this action by preceding the control characters with Esc n.

Ctrl p

Get previous line from history You can repeat this action by preceding the control characters with Esc n.

Ctrl r

Search backward (or forward if n) through history for text; start line if text begins with an up arrow.

Ctrl t

Transpose characters.

Ctrl v

Insert next character even if it is an edit command.

Ctrl w

Delete to the mark. See Esc SPC in the table of escape characters.

Ctrl x Ctrl x

Exchange the current location and mark. See Esc SPC in the table of escape characters.

Ctrl y

Restore the last deleted text to the current cursor location.

Ctrl [

Start an escape sequence (The Esc key performs the same function.)

Ctrl ]c

Move forward to the character indicated by c.

Ctrl ?

Delete the character before the cursor You can repeat this action by preceding the control characters with Esc n.

Escape Characters for Editing

To use an escape character, press the Esc key, release it, and then press the appropriate character key. For example to delete the previous word, press the Esc key, then the Ctrl key while pressing the H (capital H) key. Escape characters are case sensitive, so follow the capitalization in the table.

Escape Sequence Action Performed

ESC Ctrl H
ESC DEL

Delete the previous word. (The action can also be performed by the BACKSPACE key.) You can repeat this action by preceding the escape characters with Esc n.

ESC SPC

Set the mark. (This action can also be performed by the SPACE BAR.) Refer to the Ctrl x Ctrl x and Ctrl w control characters in the control character table

ESC .

Get the last word from the previous line. You can repeat this action by preceding the escape characters with Esc n.

ESC ?

Show possible filename completions. (See Filename Completion.)

ESC <

Move to the start of history.

ESC >

Move to the end of history.

ESC b

Move backward one word. You can repeat this action by preceding the escape characters with Esc n.

ESC d

Delete the word highlighted by the cursor. You can repeat this action by preceding the escape characters with Esc n.

ESC f

Move forward one word. You can repeat this action by preceding the escape characters with Esc n.

ESC l

Make the highlighted word lowercase. You can repeat this action by preceding the escape characters with Esc n.

ESC u

Make the highlighted word uppercase. You can repeat this action by preceding the escape characters with Esc n.

ESC y

Restore the last deleted text to the current cursor location.

ESC w

Copy the text from the cursor position up to the up to mark.

ESC nn

Set repeat count to the number indicated by nn.

Filename Completion

The dirxadm command supports filename completion. For example, suppose the root directory has the following files in it:

  • readme

  • readme.txt

If you type a command and characters and then press the TAB key, dirxadm completes as much of the filenames as possible given the characters supplied by characters. For example, if you type ls and then press the TAB key, dirxadm completes the filename the name as far as readme. However, because readme could be the file named readme or the file named readme.txt, dirxadm cannot complete the filenames, so it beeps to signal the conflict. If you then press Esc-?, dirxadm displays the two possible names: readme and readme.txt and prompts you with ls readme. You can then complete the entire filename or enough of the filename for dirxadm to complete it.

Performing Operating System Commands

On Linux, operating system commands of the shell cannot be called directly from within dirxadm. They can be called in the following way:

dirxadm> exec operating_system_command

For example, to issue a Linux "join" command, you must type

dirxadm> exec join file1 file2

On Windows, operating system commands of the command interpreter cannot be called directly from within dirxadm. They be called in the following way:

dirxadm> cmd /c operating_system_command

For example, to issue a Windows "time" command, you must type

dirxadm> cmd /c time /t

Predefined procedures for listing a directory are provided that allow you to type the following commands directly:

  • dir options

  • ls

  • ls -l

Example

The following command sequence illustrates the use of dirxadm and Tcl commands to create an entry on the country level. In this example, dirxadm has already been invoked.

puts "create /C=DE"
catch { create /C=DE -attr _attribute_list_ } status

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

Return Values

All dirxadm operations return either a NULL to indicate the successful completion of an operation or a list of information requested by the user (such as the results of a search operation). If an error occurs, dirxadm returns an error message string. The program uses the Tcl native error handling facility to log additional error information returned from commands. This information is stored in two global variables:

  • The errorInfo variable, which contains the stack trace of the error messages.

  • The errorCode variable, which is a Tcl list that contains two elements, DIRXADM (which identifies the program) and the numeric value of the error code.

The following table lists the error codes specific to dirxadm and the meanings of those error codes. Some dirxcp error codes may also be returned by dirxadm. Refer to the dirxcp reference page for a description of dirxcp errors.

Error Code

Error Message

DSA errors

1400

Unknown error received from the DSA.

1401

IDB: Object was not found.

1402

IDB: access denied.
(e.g. Modify operation to a DSA with operation mode READONLY)

1409

Modify request was rejected by the DSA.

DSA schema errors

3700

Unknown Error received by Directory Server.

3701

Schema Information already exists.

3702

Operation rejected by Directory Server.
(e.g. Deletion of an operational attribute; modification of the schema element information -info is not supported by the DSA, e.g. MV=FALSE)

3703

Attribute not found.

3704

Object Class not found.

3705

Name Form not found.

3706

Matching Rule not found.

3707

Attribute Syntax not found.

3708

Invalid Object Identifier in command or abbreviation file.

3709

Maximum number of ldap names exceeded.
(E.g. Adding 3 LDAP names to an attribute with 3 LDAP names.)

3710

LDAP name already used.
(E.g. The specified LDAP name is not unique over all attribute types or object classes.)

3711

The attribute type that has been specified as a supertype does not exist.

3712

Attribute syntaxes of attribute type and its supertype must be compatible.
(E.g. It is prohibited to specify an attribute type with syntax INTEGER when the syntax of the suptertype is Printable String.)

3713

A matching rule of attribute type is incompatible with its attribute syntax.
(e.g. It is prohibited to specify the matching rule octet string match for an attribute with syntax Directory String.)

Syntax errors on Command Line

4439

Cooperative-Status not specified.

4440

Own-Role not specified.

4441

Binding-Type not specified.

4442

Agreement not specified.

4443

File-Name not specified.

4444

Operational Binding Identifier not specified.

4445

Object Identifier not specified.

4446

Schema Information not specified.

4447

Invalid argument argument_value.

4448

Index flag not specified.

4449

Optimized storage flag not specified.

4451

Requested information not specified.

4452

Hostname not specified.

4453

Portnumber not specified.

4454

Portnumber is not allowed.
(Invalid port number was specified on command-line or in environment)

4455

Illegal parameter combination - Combination of “%s” and “%s” not allowed.
(where %s is replaced by the parameter names)

4457

Master-DSA not specified.

4458

Master Binding Identifier not specified.

4459

Update Mode not specified.

4460

Ldap name not specified.
(e.g. The -ldapname option is not followed by at least one value.)

4461

Too many ldap names.
(e.g. Adding 2 LDAP names to an object class.)

4462

Ldap names not allowed for Name Forms.
(e.g. Create a name form (NF) with LDAP names.)

4463

Conflicting Argument - %s.
(where %s denotes the argument)

Errors of the nmi object

4480

Missing Management Information Base name.

4481

Missing Management Information Base table name.

4482

Invalid Management Information Base name “%s”.
(where %s denotes the argument value)

4483

Invalid Management Information Base Table name “%s”.
(where %s denotes the argument value)

4484

The DSA MIB is not available.

4485

The Entries Table of the DSA MIB is not available.

4486

The Interaction Table of the DSA MIB is not available.

4487

The Operation Table of the DSA MIB is not available.

4488

The Association Table of the Application MIB is not available.

Errors of the ldap mib operation

4489

The STATIC LDAP MIB is not available.

4490

The TOTAL LDAP MIB is not available.

4491

The CURRENT LDAP MIB is not available.

4492

The ASSOC LDAP MIB is not available.

4493

Unknown LDAP MIB table name.

4494

Error returned from LDAP server.

4495

This name is not supported for the specified table.

Internal errors

4538

Failed to process file.

5001

Internal problem (VTHREADCREATEDATAKEY).

5002

Cannot encode RDN-Sequence.

5003

Cannot decode RDN-Sequence.

5004

Cannot encode attribute.

5005

Cannot decode attribute.

5006

Cannot encode Distinguished Name.

5007

Cannot decode Distinguished Name.

5008

The DSE DSE_DN already exists.

5009

The DSE DSE_DN does not exist.

5010

The superior of DSE_DN does not exist.

5011

Deletion of DSE_DN is not possible. There are still subordinate entries.

5012

Syntax error in Operational Binding Identifier.

5015

DSE-Type is a mandatory attribute.

5016

Object-class missing for this DSE-Type.

5017

For Administrative Points, Administrative-Role is a mandatory attribute.

5019

Error in UT_DELETE_IN_N_LIST has occurred.

5020

Note: The following message is returned if there is a problem with the request sent by dirxadm.

  • Error in lob and sob-operation (Operational Binding Error Parameter).

Note: One of the following messages can be returned if error is not with the dirxadm request.

  • Syntax error. (The parameter combination is not allowed by the DSA.)

  • Not supported. (The parameter combination is not supported.)

  • Cooperating Dsa not found. (No shadowing agreement has been defined for the specified DSA )

  • Operational binding already exists.

  • Operational binding already enabled.

  • Operational binding already disabled.

  • State of Agreement does not allow the operation to be performed. (e.g., sob established has already been performed on the agreement; or sob terminate has already been performed on the agreement; or sob enable or sob disable has been performed on an agreement with status non-cooperative).

  • One or more slave shadowing agreements refers to this agreement.

  • Begin time already passed.

  • PSAP-Address missing.

  • Overlapping replicated areas not supported.

  • No such operational binding.

  • No such binding-type. (No operational binding exists for the specified type.)

  • DB problem. (DSA database problem.)

  • Communication problem. (Internal communication problem in the DSA.)

  • Memory problem. (DSA internal memory problem.)

  • Threads problem. (DSA internal threads problem.)

  • Encoding problem. (DSA encoding problem.)

  • Decoding problem. (DSA decoding problem.)

5023

Internal problem (cannot initialize OSS).

5026

Internal Problem (Setting portnumber and hostname failed).
(Indicates memory allocation problems in dirxadm.)

5028

The attribute value already exists.

RPC Communication Problems

5031

Communication problem (Cannot encode request).
(Local RPC-Problem in dirxadm during encoding the RPC-request.)

5032

Communication problem (Cannot decode result).
(Local RPC-Problem in dirxadm during decoding the RPC-result, but may be also an encoding problem on server side.)

5033

Communication problem (Cannot send request).
(RPC-connection has been established, but the server did not receive the request.)

5034

Communication problem (Cannot receive result).
(RPC-connection has been established, the server has received the request but the server returned no result.)

5035

Communication problem (Time out).
(Connection timed out, e.g. a big search was initiated with low timeout value - in this case the search should be repeated with a sufficient timeout value.)

5036

RPC-Version not compatible to Directory Server.

5037

The following message format is used for reporting authentication problems coming via RPC:

Communication problem.
message

where message is an RPC generated error message indicating the authentication problem. The following messages can be returned:

  • : RPC: Authentication error; why = Invalid client credential
    (The credentials supplied are invalid. Try to bind again using correct credentials )

  • : RPC: Authentication error; why = Server rejected credential
    (The credentials are rejected by the Directory Server due to the policies being administered there. Try to bind again using correct authentication method (and credentials if necessary).)

  • : RPC: Authentication error; why = Invalid client verifier

  • : RPC: Authentication error; why = Server rejected verifier
    (Current connection cannot be used because the verifier sent by dirxadm has expired. Try to bind again.)

  • : RPC: Authentication error; why = Failed (unspecified error)
    (Internal DSA problem during authentication)

  • : RPC: Authentication error; why = (unknown authentication error - error_code)
    (Generic error where error_code indicates the internal problem)

5038

Communication problem (Program not available).

5039

Communication problem (Program Version mismatched).
(e.g., dirxadm of DirX Directory V4.0 A20 tries to connect to a DSA of DirX Directory V4.0 B00).

5040

Communication problem (Procedure not available).

5041

Communication problem (Cannot decode arguments).
(e.g., data transfer incorrect).

5042

Communication problem (Unknown Host).

5043

Communication problem (Unknown Network Protocol).

5044

Communication problem (RPC-Port mapper call failed).

5045

Communication problem (remote program not registered).

5046

Unknown Communication problem.

5061

DSA name must be different from ROOT DN.

5062

Neither cooperating DSA nor -ldif switch specified.

5063

Neither master DSA name nor -masterldif switch specified.

5100

Note: The following message is displayed if an operation system command fails (e.g., copy, remove, link) for an unknown reason:

Operation not successful: errno = error.h_error_number

Note: The following message is displayed if the DSA returns an unknown error (which normally cannot occur):

Operation not successful: value = DSA_error_number

5101

Permission denied.

5102

File system busy.

5103

Directory Server not available.

5105

Bad file name - “%s”.
(where %s denotes the filename)

5106

Bad Schema Info Type “AA” - must be AT or OC (case insensitive).
(For example “AA” was specified for schema_element.)

5107

LDAP Server not available.

5110

DB operation rejected by the DSA - %s
where %s denotes one of the following reasons:

  • Memory Problem. (DSA internal memory problem)

  • DB problem. (DSA database problem)

  • Threads problem. (DSA internal threads problem)

  • CONTAINS not allowed here. (CONTAINS is permitted only for attributes with string syntax.)

  • A supertype of the given attribute is still indexed.
    Reason unknown.

5111

Parameter combination not supported by Directory Server.

5112

No such DB configuration.

5114

File already exists.

5115

No such file or directory.

5116

Cannot move files between different devices.

5121

No Audit configuration.

5122

Memory problem in DSA during Audit operation.

5123

DB problem in DSA during Audit operation.

5124

Threads problem in DSA during Audit operation.

5125

Encoding problem in DSA.

5126

Initialization problem in DSA.

5127

Problem during Audit move operation.

5128

Time problem in DSA.

5129

Cannot open file.

5130

File too large.

5131

Unknown component used in logging specification.

5132

Bad logging routing specification.

5133

Set logging failed.

Local problems due to authentication

5140

Authentication Mechanism not supported.

5141

Illegal parameter combination (user/password/authentication-method) for authentication.

5142

Internal Problem (local RPC-runtime problem during authentication).

5143

Invalid credentials.

5144

Inappropriate authentication.

5145

Unknown error during authentication.

Error Codes from Directory Service-start

5160

Cannot setup transport connection for starting the Directory Service.

5161

Cannot send request for starting the Directory Service.

5162

Request for starting the Directory Service was sent, but no result was received.

5163

Transport connection timed out.
(Timeout value for starting the dsa was exceeded.)

5164

Invalid Protocol version used for starting the Directory Service.

5165

Directory Service is already running.

5166

Initialization problem (on Server side) while starting the Directory Service.

5167

Cannot start the Directory Service for unknown reasons.

The program also provides a catch command to help scripts catch errors and invoke error handlers.

Viewing Output

In interactive mode, Tcl lists are written to stdout. However, in command-line mode, the Tcl lists are not displayed. To display them, use the Tcl command puts. For example, the following commands:

% dirxadm -c “puts [dse show /O=my-company/OU=ap11/CN=naik]”
% dirxadm -c “catch {dse show /O=my-company/OU=ap11/CN=naik} result;
puts $result”

print the results of a dse show operation to stdout.

Many dirxadm operations take a -pretty option, which causes the results of the operation to be formatted into tables. Each page of -pretty output is 23 lines in length. Use the following dirxadm scrolling commands to view multiple pages of output:

n

View the nth page

-n

Skip n pages backward

+n

Skip n pages forward

$

View the last page

q

Exit viewing

SPACE

Advance to the next page

CR

Advance one line

Note that if you specify the -pretty option, the return value is NULL, not a Tcl list.

See Also

abbr (Chapter 1), audit (Chapter 1), Abbreviation Files (Chapter 2), db (Chapter 1),
dse (Chapter 1), ldap (Chapter 1), lob (Chapter 1), nmi (Chapter 1), sob (Chapter 1),
sys (Chapter 1)

abbr (dirxcp, dirxadm)

Synopsis

abbr help [operation | -verbose]

abbr operations

abbr show [-pretty]

Purpose

A dirxcp and dirxadm object that provides information about abbreviations for directory service attributes.

Arguments

operation

  • The name of the abbr operation for which to display help information.

Operations

abbr help

Returns help information about the abbr object and its operations. The syntax is as follows:

  • abbr help [operation | -verbose]

Options
-verbose

Displays information about the abbr object.

Used without an argument or option, the abbr help command returns brief information about each abbr operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the abbr object itself.

Example
abbr help

The sample command output is:

show

Displays the attribute abbreviations.

help

Displays help text for the ‘abbr’ object and its operations.

operations

Lists the operations that can be performed on the ‘abbr’ object.

abbr operations

Returns a list of operations that can be performed on the abbr object. The syntax is as follows:

  • abbr operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example
abbr operations

The command output is:

show help operations

abbr show

Shows the following information:

  • Abbreviations, full names, and object identifiers of object classes, schema object classes, matching rules, knowledge matching rules, supported application contexts, administrative roles, access control schemes and attributes

  • Abbreviations, full names, and structured attribute class names of structured attribute components.

The syntax is as follows:

  • abbr show [-pretty]

Options

-pretty

  • Displays the results of the operation in tabular format.

By default, the results of the show operation are displayed as a Tcl list, which is composed of the following elements:

{OIDAbbrList} {AttributeAbbrList} {ComponentAbbrList}

where:

OIDAbbrList

  • Is a Tcl list that represents the abbreviations for object classes, schema object classes, matching rules, knowledge matching rules, supported application contexts, administrative roles and access control schemes. Each item in the list is composed of the abbreviation, the full name, and the object identifier. For example:

    ... {C Country 2.5.6.2} …​ {ORG Organization 2.5.6.4} …​

AttributeAbbrList

  • Is a Tcl list that represents the attribute abbreviations. Each item in the list is composed of the attribute abbreviation, full name, and object identifier. For example:

    ... {C Country-Name 2.5.4.6} …​ {CN Common-Name 2.5.4.3} …​

ComponentAbbrList

  • Is a Tcl list that represents the abbreviations of structured attribute components. Each item in the list is composed of the structured attribute class name, the component abbreviation, and the full name. For example:

    ... {TELEX_N {AB Answerback} {CC Country-Code} {TN Telex-Number} …​

Use the -pretty option to display the results in a tabular, more readable format.

Example
abbr show -pretty

The command output follows:

OID Abbreviations (for object classes, etc.):

AA

Autonomous-Area

2.5.23.1

ACIA

Access-Control-Inner-Area

2.5.23.3

ACS

Access-Control-Subentry

2.5.17.1

ACSA

Access-Control-Specific-Area

2.5.23.2

ALI

Alias

2.5.6.1

…​

…​

…​

Attribute Abbreviations:

AA

Alternate-Address

1.3.22.2.1.2.1.1

ACS

Access-Control-Scheme

2.5.24.1

AON

Aliased-Object-Name

2.5.4.1

AR

Administrative-Role

2.5.18.5

ARL

Authority-Revocation-List

2.5.4.38

AT

Attribute-Types

2.5.21.5

BC

Business-Category

2.5.4.15

C

Country

2.5.4.6

…​

…​

…​

Component Abbreviations for …​

See Also

Abbreviation Files (Chapter 2), dirxadm (Chapter 1), dirxcp (Chapter 1).

attr (dirxadm)

Synopsis

attr help [operation]

attr operations

attr outsourcing -add attr_name | -rem attr_name | -show

Purpose

A dirxadm object that manages the storage of attribute types.

Arguments

operation

  • The name of the attr operation for which to display help information.

Operations

attr help

Returns help information about the attr object and its operations. The syntax is as follows:

  • attr help [operation]

Used without an argument or option, the attr help command returns brief information about each attr operation. Use the operation argument to return a description of the options associated with the operation you specify.

Example

attr help

The sample command output is:

help

Displays the help text for the ‘attr‘ object and its operations.

operations

Lists the operations that can be performed on the ‘attr‘ object.

outsourcing

Manages the configuration of the storage of attribute types.

attr operations

Returns a list of operations that can be performed on the attr object. The syntax is as follows:

  • attr operations

The list of available operations is in alphabetical order.

Example
attr operations

The command output is:

help operations outsourcing

attr outsourcing

Manages the configuration of the attribute types to be stored in extra DBAM blocks. The syntax is as follows:

  • attr outsourcing -add attr_name | -rem attr_name | -show

Options

-add attr_name

  • Adds the attribute type attr_name to the list of outsourced attributes. For attr_name, specify an abbreviation, an object identifier or an LDAP name. You can use the abbr show operation to determine the abbreviation that corresponds to the attribute name you want to add. See the abbr reference page for information about the abbr show operation.

-rem attr_name

  • Removes the attribute type attr_name from the list of outsourced attributes. For attr_name, specify an abbreviation, an object identifier or an LDAP name. You can use the abbr show operation to determine the abbreviation that corresponds to the attribute name you want to remove. See the abbr reference page for information about the abbr show operation.

-show

  • Shows the current list of the outsourced attribute types. For each attribute type the abbreviation is displayed if it is contained in the abbreviation files. The object identifier is displayed if the attribute type is not contained in the abbreviation files.

The maximum size of an entry is limited to 8193 * REAL BLOCK size, which is 8193KB for 1KB real blocks. This size is large enough for most of the entries in your directory and applies the best block use rate. If for any reason some entries exceed this limit, we recommend applying attribute outsourcing instead of reloading the entire database with a larger real block size.

Attribute outsourcing stores the values of outsourced attributes in extra blocks in the DBAM GENERAL device without any logical limits; the only limit is the size of the device. Evaluate which attributes require a large amount of memory in your directory. The size consumed in a single entry is relevant here. For example, the values of the attribute certificateRevocationList can be very large (larger than 8 Mbyte). Once you have identified these attributes, add them to the list of outsourced attributes.

When a create or modify operation is performed, the DirX Directory DSA evaluates the size of the outsourced attribute(s) in the affected entry and then restructures them in an appropriate way; that is if an outsourced attribute exceeds the predefined minimum size of 64980 bytes, the values are stored in extra blocks. If the size goes below the predefined minimum size, the values are stored in normal following blocks. Use the environment variable DIRX_DSA_OUTSOURCED_ATTR_MIN_LENGTH to adjust the minimum size.

For outsourcing of attribute types the following rules apply:

  • The attribute type must be a user application attribute.

  • The attribute syntax must not require any formatting for DSA internal representation. Typically, this applies to the attributes Certificate, CertificateList and string syntaxes like Directory String, Octet String, Bit String and so on.

  • The attribute type must not have any relevance to internal processing in the DSA.

Trying to configure an inappropriate attribute type for outsourcing fails. For details, see the schema file in the install_path*/server/log* directory which is created at DSA startup time. There is a table in this file that lists the permitted configuration for attribute indices and outsourcing.

Removing an attribute type from the list of outsourced attributes does not restructure the affected attributes and entries immediately. Instead, the values of the reconfigured attribute are stored back into normal following blocks at modification time if they do not exceed the maximum entry size. That is, as long as the sizes of all attribute values are large enough they remain outsourced.

To get a storage status about outsourced attributes, invoke a dirxadm db check -rob operation. This creates an entry-check file under install_path*/server/log*. This file contains statistics about outsourced attributes and affected entries.

Make sure that you configure all outsourced attributes identically on all involved DSAs within a replication scenario. If you do not, you may see fatal errors on a consumer DSA because the maximum entry size is exceeded.

Examples

  1. The following sample command adds the attribute certificateRevocationList (abbreviation CRL) to the list of outsourced attributes:

    attr outsourcing -add CRL

  2. The following sample command removes attribute userPKCS12 (abbreviation UPK) from the list of outsourced attributes:

    attr outsourcing -rem UPK

  3. The following sample command shows the current list of outsourced attributes:

    attr outsourcing -show

    The sample command output is as follows:

    JPT CRL

audit (dirxadm)

Synopsis

audit help [operation | -verbose]

audit modify [-status {ON | OFF}]
    [-move [-destination filename]]
    [-size size]
    [-overflow {STOP | STOP-DSA | WRAP | MOVE}]
    [-level {ENTRY | ATTR | ATTRVAL}]

audit operations

audit show [-pretty]

Purpose

A dirxadm object that enables, configures, and manages auditing DirX Directory DSA’s transactions. The audit information can be used for things such as internal billing and accounting.

Note that the LDAP server provides an own set of operations for managing LDAP server auditing. (See the ldap audit operations in this chapter for details.)

Arguments

operation

  • The name of the audit operation for which to display help information.

Operations

audit help

Returns help information about the audit object and its operations. The syntax is as follows:

  • audit help [operation | -verbose]

Options
-verbose

Displays information about the audit object.

Used without an argument or option, the audit help command returns brief information about each audit operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the audit object itself.

Example
audit help

The command output is:

modify

Sets the audit related information within the DSA.

show

Displays the status of the DSA audit.

help

Displays the help text for the "audit" object and its operations.

operations

Lists the operations that can be performed on the "audit" object.

audit modify

Configures and enable/disables auditing.

audit modify [-status {ON | OFF}]
    [-move [-destination filename]]
    [-size size]
    [-overflow {STOP | STOP-DSA | WRAP | MOVE}]
    [-level {ENTRY | ATTR | ATTRVAL}]

Options

-status {ON | OFF}

  • Turns auditing off and on. The default is OFF. The DSA must be running when you execute this command.

-move [-destination filename]

  • Moves the default audit log file (install_path/server/audit/audit.log) to another location and/or name. filename is the full path name or the relative path name of the new file. If a relative path name is specified the default audit log file is moved relative to the directory install_path/server/audit. If filename is omitted, the audit file currently in use is renamed by appending the current UTC time in ZULU format and a counter from 000 to 999; for example audit.log.20010510104511Z_001.

-size size

  • An integer that specifies the maximum number of audit records per audit log file. Each DSA operation for the DAP/DSP/DISP protocol generates one or more audit records. More than one record per operation is created usually when a DAP operation must chain to other DSAs via DSP in order to resolve the request remotely. The default size is 50000 records. The maximum number of audit records must be greater than 100. Otherwise the default value is used.

    Independent of the setting of this option the size of the DSA audit log file is limited to 256 MB by default. The dirxauddecode command must be used to evaluate the binary audit log files. Due to the 32-bit I/O mechanism dirxauddecode is not able to handle files greater than 2GB, neither as input nor as output. dirxauddecode may run into a deadlock. The administrator can specify another maximum file size than 256 MB in the DIRX_AUD_FILE_SIZE environment variable.

    If either the maximum number of audit records (-size option) or the maximum size in MB of the audit file (DIRX_AUD_FILE_SIZE environment variable) is exceeded the -overflow option specifies the action to take.

-overflow {STOP | STOP-DSA | WRAP | MOVE }

  • Sets the action to take when the maximum log file size set with the -size option is reached. The overflow action keywords have the following meanings:

    • STOP—Cease auditing when the maximum log file size is reached.

    • STOP-DSA—Shut down the DSA when the maximum log file size is reached.

    • WRAP—When the maximum log file size is reached, begin writing at the top of the log file, overwriting the entries there.

    • MOVE—When the maximum log file size is reached, the audit file currently in use is closed and renamed by appending the current UTC time in ZULU format and a counter from 000 to 999, for example audit.log.20010510104511Z_001. This renamed file can be evaluated by using the dirxauddecode command. A new audit log file is created. Auditing is continued using the current configuration settings.

    The default is WRAP.

-level {ENTRY | ATTR | ATTRVAL}

  • Set the level of audit information. The level keywords have the following meanings:

    • ENTRY—Audit transactions that affect entries.

    • ATTR—Audit transactions that affect attributes.

    • ATTRVAL— Audit transactions that affect attributes and attribute values.

    The default is ENTRY.

The audit modify -status command turns auditing on and off.

The audit modify command also sets auditing configuration parameters. Use the -size option to set the maximum size of the log file and the -overflow option to set the actions to take when maximum file size is reached.

Use the -level option to set the level of auditing to entries, attributes, or attribute values. This option is useful to limit the size of the audit information.

Note that you can also use the LDAP extended operations for DSA auditing available through the dirxextop command and the DirX Directory Manager’s Monitor view.

The Audit Log File

When auditing is enabled, audit information is collected in the file named install_path*/server/audit/audit.log*. (For Linux systems: Read and Write permissions are assigned to the file’s owner and group.) Use the audit modify -move command to rename and save the file. When auditing continues, the file install_path*/server/audit/audit.log* is re-created and used to store audit information.

Use the -destination filename option of the audit modify -move command to specify a new name for the file. Without this option the file is renamed to audit.log.datennn, where _date is the current UTC time in ZULU format in the form YYYYMMDDhhmmssZ and nnn is a counter from 000 to 999, for example audit.log.20010510104511Z_001.

A new audit log file is created when the DSA is started. In the event that an audit log file already exists this existing audit log file is renamed by appending the current UTC time in ZULU format and a counter from 000 to 999, for example audit.log.20010510104511Z_001. This renamed file can be evaluated by using the dirxauddecode command.

audit.log File Contents

The audit.log file contains one entry with general information (header information) on the audit file and an entry for each operation that occurs. As produced by the audit command the audit.log file contains records in binary format. Use the dirxauddecode command to display the contents of the log file and convert them to a form that can be read and manipulated. Use the dirxaudstatistics command to evaluate multiple audit log files.

The audit.log file general information (header) includes:

  • The command line.

  • Input and output file name.

  • The audit version.

  • The audit start time.

  • The content type (always DSA).

  • Additional server specific information, for example the server version.

Here is an example for header information:

#################  DIR.X AUDIT TRAIL (c) Eviden  ################################
Cmd-Line: -i audit.log -a dsa_audit.txt
=================================================================================
Audit  File #             :1
Input  File               :audit.log
Output File               :dsa_audit.txt
Audit Version             :8.8
Server UUID               :a5857937-1caa-4b72-80b4-722dc5db0cd0
Audit Start Time (local)  :Thu Nov 29 10:21:13 2012
Audit Start Time (GMT)    :Thu Nov 29 09:21:13 2012
Content Type              :DSA
DB Master-Entries         :0
DB Copy-Entries           :1573
Server Version            :DirX Directory V8.2 B 8.8.98 2012:11:28 20:10
Host Name                 :baumg03

The audit.log file information for each entry includes:

  • The bind ID

  • The start and end time of operation

  • The operation duration.

  • The protocol used (DAP, DSP, DISP, DOP, or local)

  • A unique DSA internal operation name (note that this internal operation name does not match the unique LDAP name of an LDAP operation in the LDAP audit log file)

  • The operation type.

  • Additional operation-specific information.

Here is an example for a bind and a search operation:

############# RECORD NUMBER 000226 #############
Bind-Id:             0x00100007
Start Time:             Thu Nov 29 10:38:00.971999 2012
End Time:               Thu Nov 29 10:38:00.971999 2012
Concurrency:            1
BT Usage:               8 Conns, 1 Ops
Duration:               0.000000 sec
Protocol:            DAP (Responder)
OP-Name:             Con16_Op0
Operation:           BIND
Role:                Responder
AuthMech:            Simple
Bind-Requestor:       /O=my-company/CN=admin
IP-address:           10.93.25.149
OpResCTXSize:         32 kB
TotalCTXSize:         7 MB  (HWM: 9 MB)
Result:              Successful (Size 0 Bytes)

########## END RECORD NUMBER 000226 ############

############# RECORD NUMBER 000227 #############
OpUUID:              e792d1c7-7090-483d-b759-ae8afadfefbc
Bind-Id:             0x00100007
Start Time:             Thu Nov 29 10:38:07.190000 2012
End Time:               Thu Nov 29 10:38:07.377000 2012
Concurrency:            1
BT Usage:               8 Conns, 1 Ops
Duration:               0.187000 sec
Protocol:            DAP (Responder)
OP-Name:             Con16_Op1
Operation:           SEARCH
Base-Object:            /O=My-Company
Scope:                  subtree
Filter:                 (cn=*bel*)
Options:                PrefCh CopyShallDo
Found Entries:          16 (16 local, 0 remote)
OpResCTXSize:         144 kB
TotalCTXSize:         7 MB  (HWM: 9 MB)
Result:              Successful (Size 1412 Bytes)

########## END RECORD NUMBER 000227 ############

The audit.log file summary information includes statistical information, for example the total number of records processed or the number of successful performed operations.

Here is an example for summary information:

=================================================================================
  DSA Audit Summary     :
    Records Processed   : 233
  Log Time              : 1391 sec
  Avrg Traffic          : 0.2 Ops/sec
  Concurrency Max       : 2 (5 times) (Op# 000096)
  CtxSize Min/Max       : 7 / 9 MB
  CtxSize HWM Min/Max   : 7 / 9 MB
  Protocol Ops          :
    DAP Ops             : 229
      Search            : 196
      Modify            : 1
      Bind              : 16 (0 Init, 16 Resp)
      Unbind            : 4
      ExtendedOp        : 6
      Abort             : 6
    DSP Ops             : 1
      Abort             : 1
    DISP Ops            : 0
    DOP Ops             : 0
    LOCAL Ops           : 0
    RPC Ops             : 0
    PagingCookieExpired : 0
    UNKNOWN Ops         : 0

  DAP Op Statistics      :     tot |    err |     % |      t Avrg |       t Max |       t Min
    Search               :     196 |      0 |  85.2 |    0.007959 |    0.187000 |    0.000000
    Modify               :       1 |      0 |   0.4 |    0.046999 |    0.046999 |    0.046999
    Bind                 :      16 |      0 |   7.0 |    0.002938 |    0.016000 |    0.000000
    Unbind               :       4 |      0 |   1.7 |    0.000000 |    0.000000 |    0.000000
    Abort                :       6 |      0 |   2.6 |    0.000000 |    0.000000 |    0.000000
    Extended             :       6 |      0 |   2.6 |    0.002500 |    0.015001 |    0.000000

  DSP Op Statistics      :     tot |    err |     % |      t Avrg |       t Max |       t Min
    Abort                :       1 |      0 |   0.4 |    0.000000 |    0.000000 |    0.000000

  DISP Op Statistics     :     tot |    err |     % |      t Avrg |       t Max |       t Min

  RPC Op Statistics      :     tot |    err |     % |      t Avrg |       t Max |       t Min


    Top 100 Durations:
      Duration    StartTime        EndTime           Op#      CC   CTXSize  Prot   Type/Info
      0.187000 | 10:38:07.190000 | 10:38:07.377000 | 000227 |   1 |    7 | DAP   | SEARCH     n/a
      0.109999 | 10:38:23.782000 | 10:38:23.891999 | 000229 |   1 |    8 | DAP   | SEARCH     n/a
      0.046999 | 10:35:21.003000 | 10:35:21.049999 | 000203 |   1 |    7 | DAP   | SEARCH     n/a
      0.046999 | 10:39:18.496000 | 10:39:18.542999 | 000230 |   1 |    7 | DAP   | MODIFY     n/a
...
Examples

  1. The following sample command sets the following audit configuration parameters by default:

    • Auditing is enabled

    • The audit file size limit is 50000 records

    • The audit level is set to ENTRY

    • The action to take when maximum log file size is reached is set WRAP

audit modify –status ON

  1. The following sample command sets the following audit configuration parameters:

    • Auditing is enabled

    • The audit file size limit is set to 100000 records

    • The audit level is set to ATTRVAL

    • The action to take when maximum log file size is reached is set STOP

audit modify -status ON \
-size 100000 \
-overflow STOP \
-level ATTRVAL

  1. The following sample command disables auditing:

audit modify -status OFF

audit operations

Returns a list of operations that can be performed on the audit object. The syntax is as follows:

  • audit operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example

*audit operations*

The command output is as follows:

modify show help operations

audit show

Displays the auditing configuration parameters set with the audit modify command.

The syntax is as follows:

  • audit show [-pretty]

Options

-pretty
Displays the results in tabular format.

The show operation displays the audit configuration parameters. By default, the results of the audit operation are displayed as Tcl list. Use the -pretty option to display the results in a tabular, more readable format.

Example

*audit show -p*

The command output is as follows:

    Audit-Policy
      Audit                   : ON
      Audit-Size-Limit        : 50000
      Audit-Overflow-Strategy : WRAP
      Audit-Level             : ENTRY [#audit_show]##

See Also

dirxadm (Chapter 1), dirxauddecode (Chapter 1), dirxaudstatistics (Chapter 1), dirxextop (Chapter 1)

db (dirxadm)

Synopsis

db attrconfig type
    -index {FALSE |
        TRUE [{CONTAINS | NO-CONTAINS}] [{ANY | NO-ANY}] [{APPROXIMATE | NO-APPROXIMATE}] [{UNIQUE | NO-UNIQUE}] |
        BUILD [INITIAL] [FINAL] [CONTAINS] [ANY] [APPROXIMATE] |
        [{INITIAL | NO-INITIAL} {UNIQUE | NO-UNIQUE}]
        [{FINAL | NO-FINAL}]
        [{CONTAINS | NO-CONTAINS}]
        [{ANY | NO-ANY}]
        [{APPROXIMATE | NO-APPROXIMATE}] }
    [-optread {TRUE | FALSE}]

db check
    -bs {ATTRIBUTE [-attribute attr_type] | SUBORDINATE [-base distinguished_name]}
    [-repair] |
    -rob

db dirxque3
    -setlevel {IDB | DIRXQUE3} |
    -getlevel

db help [operation | -verbose]

db operations

db purge
    -info |
    -analyse [-verbose] |
    -pob [-progressive] [-verbose]

db show -attribute attr_type

db statistics
    -add -base distinguished_name
        -attr {INITIAL | FINAL | CONTAINS | ANY} attr_type
        [-maxbucket bucket_count]
        [-maxvariance variance] |
    -delete -base distinguished_name
        [-attr {INITIAL | FINAL | CONTAINS | ANY} attr_type] |
    -test -base distinguished_name
        -attr {INITIAL | FINAL | CONTAINS | ANY} attr_type |
    -create |
    -update |
    -list |
    -dump

Purpose

A dirxadm object that manages a DSA database.

Arguments

operation

  • The name of the db operation for which to display help information.

type

  • A list of abbreviations or object identifiers that represents attribute types. You can use the abbr show operation to determine the abbreviation that corresponds to the attribute type you want to specify. The abbreviations or object identifiers are separated by the SPACE character. See the abbr reference page for information about the abbr show operation.

Operations

db attrconfig

Configures, indexes, and optimizes access for attribute types. The syntax is as follows:

  • db attrconfig type
        -index {FALSE |
            TRUE [{CONTAINS | NO-CONTAINS}] [{ANY | NO-ANY}] [{APPROXIMATE | NO-APPROXIMATE}] [{UNIQUE | NO-UNIQUE}] |
            BUILD [INITIAL] [FINAL] [CONTAINS] [ANY] [APPROXIMATE] |
            [{INITIAL | NO-INITIAL} {UNIQUE | NO-UNIQUE}]
            [{FINAL | NO-FINAL}]
            [{CONTAINS | NO-CONTAINS}]
            [{ANY | NO-ANY}]
            [{APPROXIMATE | NO-APPROXIMATE}] }
        [-optread {TRUE | FALSE}]

Options

-index {FALSE |
        TRUE [{CONTAINS | NO-CONTAINS}] [{ANY | NO-ANY}] [{APPROXIMATE | NO-APPROXIMATE}] [{UNIQUE | NO-UNIQUE}] |
        BUILD [INITIAL] [FINAL] [CONTAINS] [ANY] [APPROXIMATE] |
        [{INITIAL | NO-INITIAL} {UNIQUE | NO-UNIQUE}]
        [{FINAL | NO-FINAL}]
        [{CONTAINS | NO-CONTAINS}]
        [{ANY | NO-ANY}]
        [{APPROXIMATE | NO-APPROXIMATE}]
    }

  • A required option that specifies whether or not an index for the attribute types specified in type should be created or deleted. An index for an attribute type optimizes the performance of a search query with a filter that contains an equality, greater or equal, less or equal; or approximate match item, an initial or final substring, or a NOT filter item. (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.)

    A value of FALSE deletes all configured index-types of an index.

    A value of TRUE creates an initial- and final-index. If the index already exists the operation has no effect.

    A value of BUILD re-creates an index as configured. After the index has been re-created the old index is deleted. Additional not yet configured index-types can be specified. If there is no index at least one index-type keyword INITIAL, FINAL, CONTAINS, ANY, or APPROXIMATE must be specified.

    Instead of specifying the values TRUE, BUILD or FALSE you can administer each index-type separately. Specify at least one of the following keywords:

    INITIAL

    to create an additional initial index. An initial-index optimizes the performance of a search operation with equality match of the entire attribute value or with a filter that contains substrings that can be positioned at the beginning in the target attribute value. (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.) The unique attribute type value constraints check apply when specifying INITIAL UNIQUE. NO_UNIQUE (default value) disables the unique constraints check. (See section Unique Constraints Configuration Management in a Shadow Configuration in the Administration Guide for details.) NO-INITIAL deletes the initial-index.

    FINAL

    to create an additional final index. A final-index optimizes the performance of a search operation with a filter that contains substrings that can be positioned at the end in the target attribute value. (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.) NO-FINAL deletes the final-index.

    CONTAINS

    to create an additional contains-index. A contains-index optimizes the performance of a search operation with a filter that contains substrings that can be positioned anywhere in the target attribute value. (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.) NO-CONTAINS deletes the contains-index.

    Note that the CONTAINS index has no effect when searching for a single character contained in an attribute value. A contains filter searching for a single character contained in an attribute value, for example cn=*a*, is always - independent from the presence of a CONTAINS index - performed as a sequential scan. It is rejected if the user policy denies sequential searches. (See section User-Policies in DirX Directory Syntaxes and Attributes for details.)

    ANY

    to create an additional any-index. An any-index optimizes the performance of a search operation with a filter that contains checks for the presence of attribute types or NOT filter items. (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.) NO-ANY deletes the any-index.

    APPROXIMATE

    to create an additional approximate-index.An approximate-index optimizes the performance of a search operation with a filter that contains sounds-like filter items (phonetic matching). (See dirxcp obj search operation and section Search Filters in DirX Directory Syntaxes and Attributes for details.) NO-APPROXIMATE deletes the approximate-index.

    An approximate-index supports phonetic matching according the SOUNDEX algorithm. An approximate-index can be applied to attributes with the syntaxes Directory String, IA5 String and Printable String.

    If an index-type already exists and is to be created the keyword has no effect. If an index-type is to be deleted and does not exist the keyword has no effect.

-optread {TRUE | FALSE}

  • Specifies whether or not access to the attributes specified in type and their values is to be optimized. A value of TRUE enables access optimization and a value of FALSE disables access optimization. The default value is TRUE.

Searching just for indexed attributes guarantees best DSA performance. A suitable set of attributes is indexed by default, that is ObjectClass, CN, SN, C, Organization, collectiveOrganizationName, OrganizationalUnit, collectiveOrganizationalUnitName.

Specify a value of TRUE, BUILD or index-type keyword INITIAL, FINAL, CONTAINS, and / or ANY to the -index option to create an index for the attribute types specified in type. Note that DirX Directory by default creates indexes for a number of attribute types.

The maximum number of indexed attributes is 800.

Specify a value of FALSE to the -index option to delete an index for the attribute types. Deleting an index is useful only for attribute types that will not be used in search filters.

An index for an attribute type consumes extra disk space for every entry in the database and decreases the performance of update operations. Configuring the indexes carefully helps in disk space optimization.

It is recommended to create a contains-index for optimizing substring searches (keyword CONTAINS) only for attributes like surname or given name but not for attribute types that may have very large attribute values like description. It is strongly recommended not to create a contains-index for multi-valued attributes with a huge number of values. This avoids inperformant modify operations for such attributes.

When an index for a supertype is created, for example name, also the indexes for all subtypes are created, that are common name, surname, and given name.

When an index for a supertype is deleted, only the index of the supertype is deleted; the indexes of the subtypes are preserved. For example deleting the index for name does not delete the indexes of the subtypes common name, surname, and given name. It is prohibited to delete an index of a subtype when the supertype has an index.

The UNIQUE constraint proves uniqueness of attribute type values. In this context uniqueness is given if a distinct value is referenced by at most one entry. Uniqueness is also given if an entry has more than one value and for each value the first rule applies too. Also if an entry has no attribute value this is considered to be unique. Proving uniqueness is enforced by using the initial attribute index. Consider that the configured matching rule has significant impact to the result of the uniqueness check. For example, a directory string case ignore matching rule configured for a certain attribute type may bring another result in uniqueness check then a case exact matching rule. If post indexing detects non unique values the operation is returned with error and the UNIQUE flag is not set while the INITIAL index remains set. All non unique values are reported in the DSA’s logging file. A unique constraint can be applied to attributes with syntax Bit String, Directory String, IA5 String, Numeric String, Octet String, Printable String and Integer. Note that some restrictions apply. The encoded string may not exceed 1024 bytes and may not include non ASCII characters in case of Directory String syntax.

Once post indexing has been performed without error the UNIQUE constraint flag is set and all subsequent modifications are subject to a uniqueness check. Every time an attribute value is added by an add entry or modify entry operation uniqueness is proved through the index. If uniqueness is not given the operation is rejected with LDAP error LDAP_TYPE_OR_VALUE_EXISTS (code 20).

To disable unique constraints checks apply the NO-UNIQUE keyword. Once the UNIQUE flag is removed all uniqueness checks are disabled for the specific attribute type.

To apply the unique constraint check, you need to enable this feature explicitly by creating attibute enableUniqueIndex (value TRUE) in the root DSE. Also this must be performed on all consumer DSAs.

Another important aspect is to assure uniqueness within certain replication scenarios. In case the UNIQUE constraint is to be enabled on a switchable consumer DSA then it reads the database configuration from the supplier DSA and proves if the UNIQUE flag is set there. If it is not set or the supplier DSA is not online then the operation is rejected. In case the UNIQUE constraint is to be disabled on the supplier DSA then it reads the database configuration of all switchable consumer DSAs and proves if the UNIQUE flag is unset. If this is not true or any of the switchable consumer DSAs is not online then the operation is rejected. One exception build switchable consumer DSAs which are not online and their agreement is disabled. They are excluded from the check and the operation is not rejected. (See also the dirxadm sob switch operation and section Unique Constraints Configuration Management in a Shadow Configuration in the Administration Guide.)

By default, new attributes are created without indexing. To check if a given attribute is indexed, you can use the db show operation or read the attribute index subentry. (See section Attribute Index Definition in DirX Directory Syntaxes and Attributes for details.)

Specify a value of TRUE to the -optread option to enable access optimization. When optimized access is enabled, DirX Directory stores an entry’s attributes and their values in the same database record as the distinguished name of the entry. This storage method permits the DSA to read the attributes and their values within the same database read operation as the name of the entry. By default, optimized access is enabled for all attributes of the default schema and all attributes newly created.

Specify a value of FALSE to the -optread option to disable access optimization. Disabling access optimization is especially useful for attribute types with very large attribute values that are also not accessed frequently. Attributes with a value of FALSE to the -optread option cannot be indexed.

While the db attrconfig command is in progress the operation mode of the DSA is POSTINDEXING. (See the dirxadm sys opmode operation for details.)

Example

  • In the following example an initial- and any-index are created for the attribute given name:

    db attrconfig gn -index INITIAL ANY

    If one of the specified index-types (initial and / or any) already exists the operation has no effect on this index-type. dirxadm does not display an error message.

    If other index-types, for example a contains- and / or final-index, exist the operation has no effect on these index-types. dirxadm does not delete them.

  • In the following example an any-index is created and the final- and contains-index are deleted for the attributes given name and telephone number:

    db attrconfig gn TN -index NO-FINAL ANY NO-CONTAINS

  • In the following example an approximate-index is created for the attribute surname:

    db attrconfig sn -index APPROXIMATE

    If there is already an approximate-index for the surname attribute dirxadm performs no operation and prompts without an error message.

  • In the following example the approximate-indexes are deleted for the attributes surname and given name:

    db attrconfig sn gn -index NO-APPROXIMATE

    If there there are no approximate-indexes for the surname and the given name attributes dirxadm performs no operation and prompts without an error message.

  • In the following example the initial index for attribute USID (userid) is created and UNIQUE constraints are specified:

    *db attrconfig usid -index INITIAL UNIQUE*

db check

Checks the consistency of attribute indexes, subordinates, or DSEs (Directory Specific Entry). The syntax is as follows:

  • db check
        -bs {ATTRIBUTE [-attribute attr_type] | SUBORDINATE [-base distinguished_name]}
        [-repair] |
        -rob

Options

-bs {ATTRIBUTE | SUBORDINATE}

  • Specifies whether attribute indexes (keyword ATTRIBUTE) or subordinates (keyword SUBORDINATES) are checked.

-attribute attr_type

  • Specifies the attribute types that indexes are checked. Specify the abbreviation or the OID of the attribute types. Use the abbr show operation to determine attribute abbreviations. A SPACE character separates the attribute types. The default is that all indexed attribute types are checked.

-base distinguished_name

  • Specifies the distinguished name of the base of the subtree to be checked. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a complete description of distinguished name formats. The default is the root DSE, that is the entire DIT is checked.

-repair

  • Specifies that detected inconsistencies are repaired automatically.

-rob

  • Specifies that the consistency of DSEs is checked.

The check operation checks the consistency of the saved internal database information.

Use the -bs option to specify whether attribute indexes or subordinates are to be checked. Use the -base option to specify the base object of a particular subtree in the DIT.

While the db check -bs command is in progress the operation mode of the DSA is POSTINDEXING. (See the dirxadm sys opmode operation for details.)

Use the -attribute option to limit the check to a specific list of attribute types. Only the indexes of the specified attribute types are checked. If you specify a supertype the index of a subtype is checked only if the subtype is contained in the attribute list, for example if you specify the name attribute the common name, surname, and given name attributes are checked only if they are specified in the attribute list. If the attribute type list contains an attribute type that is not indexed the operation is aborted. None of the specified attribute type indexes is checked.

Use the -repair option to specify that detected inconsistencies should be repaired automatically.

While the operation is in progress the DSA rejects any update operation. It returns the error Unwilling to Perform.

In the event of detecting inconsistencies an error message is displayed.

Detailed results are saved in the file

  • install_path*/server/log/aidxcheck*pid*.txt* (attribute index check)

  • install_path*/server/log/subcheck*pid*.txt* (subordinate check)

where pid specifies the PID of the check process.

Use the -rob option to check the consistency of DSEs. Unlike to the other consistency checks above it is possible to perform update operations while the check process is performed. The DNs of inconsistent DSEs are saved in the file install_path*/server/log/entrycheck*pid*.txt* where pid specifies the PID of the check process. The check process reads each DSE and performs the following consisteny checks:

  • DBAM low level

    One real object block represents one DSE. If the attributes of this DSE cannot be stored in this one real object block one or more follow blocks are allocated in the GENERAL DBAM device. This check verifies the correct linkage of the follow blocks.

  • Entry low level

    This check verifies the correct attribute type sequence, attribute value length, and attribute value counts within an entry.

  • ASN.1 encoding

    This check verifies the correct ASN.1 encoding for each attribute value.

  • Tree location

    This check verifies the correct linkage of the entry in the tree.

  • Reference consistency

    This check proofs all distinguished name references for validity.

  • Schema consistency

    This check verifies object classes and attribute types of the entry for schema consistency.

  • Attribute index consistency

    This check verifies for all indexed attributes if the values are stored correctly in the attribute index.

Example

  1. In the following example the indexes of the attribute types common name (cn) and surname (sn). In the event of inconsistencies the indexes are repaired automatically.

    db check –bs ATTRIBUTE -attribute cn sn -repair

  1. In the following example the subordinates of the subtree o=my-company are checked. In the event of inconsistencies the subordinates information is repaired automatically.

    db check –bs SUBORDINATE -base /o=my-company/ou=sales -repair

db dirxque3

Manages the DirXQue3 optimization level. The syntax is as follows:

  • db dirxque3
        -setlevel {IDB | DIRXQUE3} |
        -getlevel

Options

-setlevel {IDB | DIRXQUE3}

  • Sets the optimization level of DirXQue3. Specify one of the following keywords:

    IDB

    to enable the DirX Directory IDB search engine.

    DIRXQUE3

    to enable the DirXQue3 search engine.

    The default value is IDB.

    + Before enabling DirXQue3 it is required to create histograms. DirXQue3 uses these histograms to optimize search operations. See the db statistics operation how to create histograms.

-getlevel

  • Displays the optimization level in use.

The dirxque3 operation manages the DirXQue3 optimization level. Use the -setlevel option to specify the search engine to use. Use the -getlevel option to display the optimization level in use.

Example

db dirxque3 –setlevel DIRXQUE3
db dirxque3 –getlevel

The command output is as follows:

OptimizerLevel=DIRXQUE3

db help

Returns help information about the db object and its operations. The syntax is as follows:

  • db help [operation | -verbose]

Options

-verbose

  • Displays information about the db object.

Used without an argument or option, the help command returns brief information about each db operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the db object itself.

Example

db help

The command output is as follows:

attrconfig

Establishes optimized access to attributes and creates indexes for an attribute type.

check

Checks either the attribute index bit strings of indexed attributes or subordinate bit strings

purge

Analyses or deletes unreferenced objects.

statistics

Creates, updates, adds, deletes or tests histograms for the query optimizer.

dirxque3

Shows and changes the options of the query optimizer.

show

Displays information about the database configuration in the DSA.

help

Displays the help text for the “db” object and its operations.

operations

Lists the operations that can be performed on the “db” object.

db operations

Returns a list of operations that can be performed on the db object. The syntax is as follows:

  • db operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example

db operations

The command output is as follows:

attrconfig check purge statistics dirxque3 show help operations

db purge

Manages the purge operations in the DSA database. The syntax is as follows:

  • db purge
        -info |
        -analyse [-verbose] |
        -pob [-progressive] [-verbose]

Options

-info

  • Scans the DBAM tree and displays statistical information about pseudo objects and pseudo references.

-analyse [-verbose]

  • Scans the DBAM database and writes statistical information about pseudo objects and pseudo references to the log file install_path*/server/log/purge*pid*.txt*. If the -verbose option is specified all pseudo objects and references are written to the log file.

-pob [-progressive] [-verbose]

  • Scans the DBAM database and deletes all unused pseudo references. The DSA writes a log file install_path*/server/log/purge*pid*.txt* that records statistical information about pseudo objects and pseudo references.

    If the -progressive option is specified then simultaneous update operations are allowed while the purge operation cleans up the database. Otherwise the DSA changes its operation mode to POSTINDEXING, that is, update operations are rejected.

    If the -verbose option is specified detailed information about all pseudo objects and pseudo references are written to the log file.

The purge operation records statistical information about pseudo objects and references and cleans up unused pseudo references in the DSA database.

A pseudo object is an object in the DBAM tree that is referenced by one or more other objects. The pseudo object just points to the DSE (DSE - Directory Specific Entry) that contains the attributes of the referenced object. That is the pseudo object contains only one attribute: the reference to the DSE that contains all other attributes of this object, for example the attributes postal address, description, employee number, phone-number and so on.

A pseudo reference is an object in the DBAM tree that is referenced by one or more other objects. The pseudo reference does not point to a DSE.

For example, the objects cn=Smith, ou=Sales, o=My-Company and cn=Jones, ou=Sales, o=My-Company have got the See-Also attribute cn=Hohner, ou=Sales, o=My-Company. Both DSEs (for Smith and Jones) refer the pseudo object cn=Hohner, ou=Sales, o=My-Company. This pseudo object points to the DSE of cn=Hohner, ou=Sales, o=My-Company that contains all attributes of Hohner. The following figure illustrates this example:

image1

If the DSE Hohner is deleted for example because the employee Hohner has left My-Company the pseudo object Hohner converts to a pseudo reference. After an administrator has deleted all See-Also attributes referring Hohner the purge operation deletes the unused pseudo reference Hohner.

Use the -info option to display statistical information about pseudo objects and pseudo references. This information does not provide whether there are unused pseudo references but it helps to decide whether to perform a purge or not. It is recommended to perform a purge if there are a high number of pseudo references together with a high pseudo reference ratio; for example 80000 pseudo references or more and a ratio of 40% or higher. Another indicator for performing a purge operation is the fragmentation ratio of a DBAM logical device. Perform a dbamdevinfo command and evaluate the fragmentation of the DBAM logical devices. If one of the devices has a fragmention ratio of 50% or higher then a purge operation is recommended.

Use the -analyse option to check whether there are unused pseudo references. Use the -verbose option to get detailed information about pseudo objects and references. The operation records all information in the log file install_path*/server/log/purge*pid*.txt* where pid is the process id of the process performing the purge analysis.

Use the -pob option to perform the clean up of the DSA database. While performing the clean up process the DSA changes its operation mode to POSTINDEXING if the option -progressive is not specified; that is update operations are rejected. Use the -verbose option to get detailed information about the clean up process. The operation records all information in the log file install_path*/server/log/purge*pid*.txt* where pid is the process id of the process performing the clean up process.

Example

dbamdevinfo

The command output is as follows:

Logical device:  GENERAL | BITSTR | PSEUDO | TREE
    In use:        29.21 %  (  3.504 GB of   11.997 GB)
    Fragmentation: 99.96 %
Logical device:  REAL
    In use:         0.15 %  ( 60.049 MB of   38.990 GB)
    Fragmentation:  0.00 %
Logical device:  AVIDX
    In use:         0.37 %  ( 90.688 MB of   24.000 GB)
    Fragmentation:  0.00 %

In this example, the logical DBAM device which stores GENERAL, BITSTR, TREE and PSEUDO block types has a fragmentation ratio of 99.96%. It is highly recommended to perform a purge operation.

db purge -info

The command output is as follows:

{Total 6 pseudo objects, 2 pseudo references (25%)}

In this example, there are 6 pseudo objects that point to a DSE and 2 pseudo objects that do not point to a DSE so-called pseudo references. You do not know whether there are objects in your database that point to the pseudo references. It is not necessary to perform a purge operation.

db purge –analyse –verbose

On success, the command finishes with an empty command prompt. The log file contains the following information:

Tue Mar 06 11:25:51 2007 Start purge analyse operation
Tue Mar 06 11:25:51 2007 Cmdline : db purge -analyse -verbose
Tue Mar 06 11:25:51 2007 Purge analyse phase 1 : retrieve all links to pseudo objects and pseudo references
Tue Mar 06 11:25:51 2007 Highest allocated real block number : 24
Tue Mar 06 11:25:51 2007 24 real entries parsed in 1 seconds : 24 entries/second
Tue Mar 06 11:25:51 2007 30 links to pseudo objects and pseudo references detected
Tue Mar 06 11:25:51 2007 Purge analyse phase 2 : retrieve all allocated pseudo objects and pseudo references

Tue Mar 06 11:25:51 2007 List of allocated, referenced and unreferenced slots :
POBN=   327  ALLOCATED_SLOTS=0.......  REFERENCED_SLOTS=0.......
POBN=   331  ALLOCATED_SLOTS=0123....  REFERENCED_SLOTS=0123....
POBN=   401  ALLOCATED_SLOTS=0123....  REFERENCED_SLOTS=012.....  UNREFERENCED_SLOTS=...3....
POBN=   409  ALLOCATED_SLOTS=01234567  REFERENCED_SLOTS=........  UNREFERENCED_SLOTS=01234567
POBN=   410  ALLOCATED_SLOTS=01......  REFERENCED_SLOTS=........  UNREFERENCED_SLOTS=01......

Tue Mar 06 11:25:51 2007 5 blocks allocated
Tue Mar 06 11:25:51 2007 11 unused pseudo references detected

In this example, the database contains 24 DSEs and 30 references to pseudo objects. There are 5 blocks containing a number of pseudo objects and references. There are 11 unused pseudo references. It is not necessary to perform a purge operation.

db purge –pob –verbose

On success, the command finishes with an empty command prompt. The log file contains the following information:

Tue Mar 06 11:25:51 2007 Start purge analyse operation
Tue Mar 06 11:25:51 2007 Cmdline : db purge -analyse -verbose
Tue Mar 06 11:25:51 2007 Purge analyse phase 1 : retrieve all links to pseudo objects and pseudo references
Tue Mar 06 11:25:51 2007 Highest allocated real block number : 24
Tue Mar 06 11:25:51 2007 24 real entries parsed in 1 seconds : 24 entries/second
Tue Mar 06 11:25:51 2007 30 links to pseudo objects and pseudo references detected
Tue Mar 06 11:25:51 2007 Purge analyse phase 2 : retrieve all allocated pseudo objects and pseudo references

Tue Mar 06 11:25:51 2007 List of allocated, referenced and unreferenced slots :
POBN=   327  ALLOCATED_SLOTS=0.......  REFERENCED_SLOTS=0.......
POBN=   331  ALLOCATED_SLOTS=0123....  REFERENCED_SLOTS=0123....
POBN=   401  ALLOCATED_SLOTS=0123....  REFERENCED_SLOTS=012.....  UNREFERENCED_SLOTS=...3....
POBN=   409  ALLOCATED_SLOTS=01234567  REFERENCED_SLOTS=........  UNREFERENCED_SLOTS=01234567
POBN=   410  ALLOCATED_SLOTS=01......  REFERENCED_SLOTS=........  UNREFERENCED_SLOTS=01......

Tue Mar 06 11:25:51 2007 5 blocks allocated
Tue Mar 06 11:25:51 2007 11 unused pseudo references detected

In this example, the database contains 24 DSEs and 30 references to pseudo objects. There are 5 blocks containing a number of pseudo objects and references. There are 11 unused pseudo references. The purge operation deleted all 11 unused pseudo references. It also deleted 2 blocks that no longer contain any pseudo object or reference.

db show

Shows configuration information for a specific attribute type. The syntax is as follows:

  • db show -attribute attr_type

Options

-attribute attr_type

  • Shows information on attribute index and read optimization associated with the specified attribute type.

The show operation displays database configuration information. Use the -attribute option to show configuration information associated with an attribute type. See the db attrconfig operation for detailed information about index-types INITIAL, FINAL, CONTAINS, ANY, and APPROXIMATE. In combination with the INITIAL index type the UNIQUE flag is printed if unique constraint check is enabled and all attribute values are unique. If no index is specified for an attribute the value FALSE is displayed for the INDEX component.

Example

  • In the following example the detailed information about the common name attribute is displayed:

    db show -attribute cn

    The command output is as follows:
    ATTR=CN,INDEX=INITIAL;FINAL;CONTAINS;ANY,OPTR=TRUE

  • In the following example the detailed information about the description attribute is displayed:

    db show -attribute dsc

    The command output is as follows:
    ATTR=DSC,INDEX=FALSE,OPTR=TRUE

  • In the following example the detailed information about the userid attribute is displayed:

    db show -attribute usid

    The command output is as follows:
    ATTR=USID,INDEX=INITIAL;UNIQUE,OPTR=TRUE

db statistics

Manages the histograms for DirXQue3. The syntax is as follows:

  • db statistics
        -add -base distinguished_name
            -attr {INITIAL | FINAL | CONTAINS | ANY} attr_type
            [-maxbucket bucket_count]
            [-maxvariance variance] |
        -delete -base distinguished_name
            [-attr {INITIAL | FINAL | CONTAINS | ANY} attr_type] |
        -test -base distinguished_name
            -attr {INITIAL | FINAL | CONTAINS | ANY} attr_type |
        -create |
        -update |
        -list |
        -dump

Options

-add

  • Adds a new specific histogram defined by its distinguished name, attribute type and attribute type index to the histogram configuration.

-delete

  • Deletes a specific histogram defined by its distinguished name, attribute type and attribute type index.

-test

Tests a specific histogram defined by its distinguished name, attribute type and attribute type index.

-create

  • Creates all configured histograms.

-update

  • Updates all configured histograms.

-list

  • Writes the actual histogram configurations into a XML file. The full pathname of the file is printed to standard output.

-dump

  • Dumps all histograms into a XML file. The full pathname of the file is printed to standard output.

-base distinguished_name

  • Specifies the distinguished name of the base of the subtree for which the histogram is configured, deleted, or tested. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a complete description of distinguished name formats.

-attr {INITIAL | FINAL | CONTAINS | ANY} attr_type

  • Specifies the attribute type index for which the histogram is configured, deleted, or tested. attr_type specify the abbreviation or the OID of the attribute type. Use the abbr show operation to determine attribute abbreviations. Specify one of the following keywords for the index:

    • INITIAL - for the initial-index

    • FINAL - for the final-index

    • CONTAINS - for the contains-index

    • ANY - for the any-index

See the db attrconfig operation for information about indexes and how to create them.

-maxbucket bucket_count

  • Specifies the maximum bucket number of the histogram in bucket_count. It specifies the width of the histogram.

    Attribute values are grouped together according to their frequency (matches in the directory) into buckets. Buckets are composed to keep the overall variance as low as possible.

    Specify a value between 100 (for a small number of different attribute values) and 800 for a large number of different attribute values). The default is 100 for the object class attribute type and 300 for all other attribute types.

    The x-axis of the histogram represents the buckets. The y-axis represents the average frequencies of the values in one bucket.

    For example, there are 120 Jones, 100 Smith, 8 Soeder, and 12 Zahn. Jones and Smith are grouped to bucket_1, and Soeder and Zahn are grouped to bucket_2. The average frequency is 110 for bucket_1 and 10 for bucket_2.

-maxvariance variance

  • Specifies the maximum variance of the buckets in variance that should not be exceeded.

    The variance is a measure of the spread of the frequencies of the values in one bucket. Numerically, the variance equals the average of the several squared deviations from the mean.

    Specify a value between 0 and 100. The default is 0 for the object class attribute type and 100 for all other attribute types.

The statistics operation manages the histograms that the DirXQue3 search engine uses to optimize search queries. Configuring and creating histograms is a requirement for performing search operations with the DirXQue3 search engine.

Use the -add option to specify the configuration data for a histogram. The -base option specifies the base of the subtree and the -attr option specifies the index for which the histogram is configured. Use the -maxbucket and the -maxvariance options to specify the histogram properties. Adding a histogram configuration is only possible if the search engine is set to IDB. (See the db dirxque3 operation for details.) After finishing histogram configuration create the histograms by performing a db statistics -create operation.

Histograms should be configured for the most frequently used attribute types in the –filter option of search operations. Use the LDAP audit log file to analyze the search requests that your applications perform. Based on this information configure histograms for following attribute indexes:

  • Configure a histogram for the INITIAL attribute type index if your applications submit search requests with an initial substring filter or equal filter, for example cn=Adam* or cn=Adams. It is recommended to configure histograms always for the object class attribute type.

  • Configure a histogram for the FINAL attribute type index if your applications submit search requests with an ends substring filter, for example cn=*worth.

  • Configure a histogram for the CONTAINS attribute type index if your applications submit search requests with a contains substring filter, for example dsc=*manager*.

  • Configure a histogram for the ANY attribute type index if you applications submit search requests with a present filter, for example cn=*.

  • It is mandatory to configure all histograms for the root DSE. All other histograms for different search bases are optionally. However it is necessary that a histogram for a search base below the root DSE is also configured for the root DSE. To get best performance it might be beneficial to create histograms for each context prefix and for very frequently used search bases below the context prefixes.

Ensure that the attribute type indexes have already been created before you configure histograms. See the db attrconfig operation how to create indexes.

Use the -delete option to delete a specific histogram. The -base option specifies the base of the subtree and the -attr option specifies the index for which the histogram is deleted. If the -attr option is omitted all histograms for the specified subtree are deleted. Deleting a histogram is only possible if the search engine is set to IDB. (See the db dirxque3 operation for details.) Perform a db statistics -update operation to apply the changes in the histogram.

Use the -create option to create all configured histograms. Creating histograms is only possible if the search engine is set to IDB. (See the db dirxque3 operation for details.) While performing the statistics –create operation the DSA is set to READONLY mode, that is all update operations are rejected. After you have created all histograms perform a db dirxque3 –setlevel DIRXQUE3 to enable search request optimization.

Use the –update option to update all configured histograms. Updating histograms is only possible if the search engine is set to IDB. (See the db dirxque3 operation for details.) While performing the statistics -update operation the DSA is set to READONLY mode, that is all update operations are rejected. The DirXQue3 search engine may start to work inefficient after several modify requests have been performed. Therefore, it is necessary to update the histograms. After you have updated all histograms perform a db dirxque3 -setlevel DIRXQUE3 to enable search request optimization.

Use the -test option to a specific histogram. The -base option specifies the base of the subtree and the -attr option specifies the index for which the histogram is tested. If the result of the test operation is that the histogram no longer matches the ratios in the database (because too many modify requests were performed) you should update your histograms by performing a db statistics -update operation to avoid that the DirXQue3 search engine works inefficient.

The test operation retrieves all attribute values for the specified attribute type, calculates their frequencies, and compares it with the histogram. The result is written to a file that lists the differences in the following order:

  • Percent difference ⇐ 1

  • Percent difference ⇐ 10

  • Percent difference ⇐ 50

  • Percent difference ⇐ 100

  • Percent difference ⇐ 500

  • Percent difference > 500

  • Average difference

The full pathname of the file is printed to standard output.

While the db statistics -create or -update command is in progress the operation mode of the DSA is POSTINDEXING. (See the dirxadm sys opmode operation for details.)

Examples

  1. There are two context prefixes o=my-company and o=my-application and a total number of 4000000 entries in your database. Evaluating the LDAP audit log file provides the following information:

    • Additionally to the two context prefixes the most used search base is ou=UserBase, o=my-application.

    • Initial substring filter and equal filter are applied to the attribute types objectClass, businessCategory, description, title, cn, l and ou.

    • Contains substring filter are applied to the attribute type description, title, cn and ou.

    Before configuring the histograms it is necessary to make sure that there are indexes of the applied attribute types. If not yet done perform this task with the following dirxadm db attrconfig operations:
    db attrconfig ocl bc dsc tit l cn ou –optread true –index true
    db attrconfig dsc tit cn ou –optread true –index true contains

    + Then add the histogram configurations for the root DSE:
    db statistics -add -base / -attr INITIAL ocl
    db statistics -add -base / -attr INITIAL bc
    db statistics -add -base / -attr INITIAL cn
    db statistics -add -base / -attr INITIAL dsc
    db statistics -add -base / -attr INITIAL tit
    db statistics -add -base / -attr INITIAL l
    db statistics -add -base / -attr INITIAL ou
    db statistics -add -base / -attr CONTAINS cn
    db statistics -add -base / -attr CONTAINS tit
    db statistics -add -base / -attr CONTAINS ou
    db statistics -add -base / -attr CONTAINS dsc

    + Add the histogram configurations for the context prefixes and the subtree ou=UserBase, o=my-application in the same way as you did for the root DSE:
    db statistics -add -base /O=My-Company -attr INITIAL ocl
    db statistics -add -base /O=My-Company

    + … and so on
    db statistics -add -base /O=My-Application –attr INITIAL ocl
    db statistics -add -base /O=My-Application

    + … and so on
    db statistics -add -base /O=My-Application/OU=UserBase –attr INITIAL ocl
    db statistics -add -base /O=My-Application/OU=UserBase

    + … and so on

    + Create all histograms:
    db statistics -create

    + Finally enable the DirXQue3 search engine:
    db dirxque3 –setlevel DIRXQUE3

  2. After a while perform test operations to find out whether you should update your histograms:
    db statistics –test –base / -attr INITIAL cn

    The sample output is as follows:
    {Result in C:\Program Files\DirX\Directory\client\log\dirxque3statisticTest3140.txt}

    The sample output file C:\Program Files\DirX\Directory\client\log\dirxque3statisticTest3140.txt is as follows:
    {100.000 0.000 0.000 0.000 0.000 0.000 0.000}

    … and so on

  3. The following sample command writes all histogram configurations into a XML file:
    db statistics –list

    The sample output is as follows:
    {Result in C:\Program Files\DirX\Directory\client\log\dirxque3statisticList2000.xml}

    The sample output file C:\Program Files\DirX\Directory\client\log\dirxque3statisticList2000.xml is as follows:

    <?xml version="1.0" encoding="ISO-8859-1"?>
<DirXStatistics>
      <DNNode dn="" dseid="1">
             <AttrNode name="objectClass" oid="2.5.4.0">
                   <Histogram type="Initial" selected="true" built="true">
                          <BuildRestriction maxBuckets="100" maxVariance="0" enforce="Variance"/>
                   </Histogram>
                   <Histogram type="Final" selected="false"/>
                   <Histogram type="Contains" selected="false"/>
                   <Histogram type="Any" selected="false"/>
             </AttrNode>
             <AttrNode name="cn" oid="2.5.4.3">
                   <Histogram type="Initial" selected="true" built="true">
                          <BuildRestriction maxBuckets="300" maxVariance="100" enforce="Space"/>
                   </Histogram>
                   <Histogram type="Final" selected="false"/>
                   <Histogram type="Contains" selected="false"/>
                   <Histogram type="Any" selected="false"/>
             </AttrNode>
      </DNNode>
</DirXStatistics>

  4. The following sample command dumps all histograms into a XML file:
    db statistics –dump

    The sample output is as follows:
    {Result in C:\Program Files\DirX\Directory\client\log\dirxque3statisticDump2000.xml}

    The sample output file C:\Program Files\DirX\Directory\client\log\dirxque3statisticDump2000.xml is as follows:

    <?xml version="1.0" encoding="ISO-8859-1"?>
<DirXStatistics>
<DNNode dn="" dseid="1">
<LocalStat>
<SubEntryCount>24</SubEntryCount>
<SubEntryLength>8</SubEntryLength>
<OneLevelEntryCount>6</OneLevelEntryCount>
<OneLevelEntryLength>8</OneLevelEntryLength>
</LocalStat>
<AttrNode name="objectClass" oid="2.5.4.0">
<Histogram type="Initial" selected="true" built="true">
<BuildRestriction maxBuckets="100" maxVariance="0" enforce="Variance"/>
<EntryCount>23</EntryCount>
<DomainCount>15</DomainCount>
<MultiValue>2</MultiValue>
<Bucket>
<StartValue>KwYBBAEqAhsIAgEA</StartValue>
<EntryCount>1</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAwZk</StartValue>
<EntryCount>2</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAwZl</StartValue>
<EntryCount>3</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAwZm</StartValue>
<EntryCount>4</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAwZo</StartValue>
<EntryCount>5</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAwZt</StartValue>
<EntryCount>6</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>KwwCiFMBAxFk</StartValue>
<EntryCount>7</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VQYE</StartValue>
<EntryCount>8</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VQYF</StartValue>
<EntryCount>10</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VQYG</StartValue>
<EntryCount>21</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VQYH</StartValue>
<EntryCount>32</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VREA</StartValue>
<EntryCount>41</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VREB</StartValue>
<EntryCount>42</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>VREC</StartValue>
<EntryCount>43</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
<Bucket>
<StartValue>YIZIAYb4QgMCAgAA</StartValue>
<EntryCount>53</EntryCount>
<DomainCount>1</DomainCount>
</Bucket>
</Histogram>
<Histogram type="Final" selected="false"/>
<Histogram type="Contains" selected="false"/>
<Histogram type="Any" selected="false"/>
</AttrNode>
<AttrNode name="cn" oid="2.5.4.3">
<Histogram type="Initial" selected="true" built="true">
<BuildRestriction maxBuckets="300" maxVariance="100" enforce="Space"/>
<EntryCount>19</EntryCount>
<DomainCount>19</DomainCount>
<MultiValue>1</MultiValue>
<Bucket>
<StartValue>QUJFTEUA</StartValue>
<EntryCount>19</EntryCount>
<DomainCount>19</DomainCount>
</Bucket>
</Histogram>
<Histogram type="Final" selected="false"/>
<Histogram type="Contains" selected="false"/>
<Histogram type="Any" selected="false"/>
</AttrNode>
</DNNode>
</DirXStatistics>

dse (dirxadm)

Synopsis

[dse] bind
    [-authentication auth_method]
    [-host hostname]
    [-port portnumber]
    [-password password | -pwdfile password_file]
    [-user username]

[dse] commands

[dse] create distinguished_name
    attribute attribute_list

[dse] delete distinguished_name

[dse] help [operation | -verbose]

[dse] modify [distinguished_name]
    [-addattr attribute_list]
    [-removeattr attribute_list]

[dse] operations

[dse] search [distinguished_name]
    [-allattr | -attribute abbreviation […​]]
    [-dsetype dsetype]
    {-onelevel | -subtree}
    [-pretty]
    [-timeout timeout]]

[dse] show [distinguished_name]
    [-allattr | -attribute abbreviation […​]]
    [-pretty]

Purpose

A dirxadm object that manages a DSA-specific entry (DSE) in the directory information tree. Use the dse object to manage DSA and user policies.

Arguments

distinguished_name

  • The name of a DSE to act on. Supply a DSE name as follows:

    • Complete distinguished name, in the form

      /distinguished_name

      For example: {/O=my-company/OU=board/CN=mueller, peter}

    • Relative distinguished name, in the form

      distinguished_name

      This name refers to a distinguished name that is relative to the current working DSE identified in the _cwo Tcl variable. For example:

      {CN=mueller peter}

      is relative to the current working DSE

      dirxadm> set _cwo \{O=my-company/OU=board}
      /O=my-company/OU=board

      dirxadm> show \{CN=mueller peter} -attr SN -p
      1) /O=my-company/OU=board/CN=mueller peter
      Surname: Mueller

See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for complete information on distinguished name format.

If no distinguished_name argument is specified, the operation acts on the current working DSE.

operation

  • The name of the dse operation for which to display help information.

Operations

dse bind

Establishes a binding between dirxadm and a DSA. The syntax is as follows:

  • [dse] bind [-authentication auth_method]
        [-host hostname]
        [-port portnumber]
        [-password password | -pwdfile password_file ]
        [-user username]

Options

-authentication auth_method

  • The authentication method to be applied. Supply one of the following keywords:

    • simple—Simple unprotected authentication

    • simple_pr1—Simple-protected authentication (password is encrypted)

-port portnumber
The port number of the DSA. Use the -port option only if there is a conflict with the default port number on your system. (See also environment variable DIRX_PMAP_PORT in chapter DirX Directory Environment Variables.)

-host hostname

  • The hostname or IP address of the machine hosting the DSA to be administered. The default is localhost.

-password password

  • The password associated with the user on whose behalf the bind request is being made.

-pwdfile password_file

  • The path to a file containing the password for bind (see the -password option). The password must be the only content of this file. When creating the file, the password must be specified in plain ASCII format. After the first successful reading by the application, the password is symmetrically encrypted and the file is rewritten to provide protected local storage.

-user username

  • The name of the user on whose behalf the bind request is being made. Specify the complete distinguished name of the user. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The username must be contained in the DSA as value of the DirX Directory-Administrators (DADM) attribute. This attribute is stored as an operational attribute of the root DSE. It defines the entries that the DSA will recognize as authorized users of dirxadm (see DirX Directory Syntaxes and Attributes and DirX Directory Default DSA Schema for details).

The bind operation must be performed before any other operation can be executed in dirxadm. Only the sys start operation can be performed without performing the bind operation first.

When used without options, the bind operation creates an anonymous bind to the default DSA. Administrators should normally disable anonymous binds except during the DSA bootstrapping phase.

Use the -host and/or -port options to bind to a specific DSA.

Use the -authentication option to establish a specific authentication method. If you specify simple or simple-protected authentication, you must supply the -user option and one of the following options: -password or -pwdfile. The password you supply for simple authentication is sent as clear text even if the password_file is used. The password you supply for simple-protected authentication is sent encrypted.

If the DirX Directory-Administrators attribute exists, the DSA rejects anonymous binds and binds from users not contained in the DirX Directory-Administrators attribute. If the DirX Directory-Administrators attribute does not exist, the DSA allows anonymous binds (that is everyone is able to administer the DSA). (See DirX Directory-Administrators in DirX Directory Syntaxes and Attributes for details.)

To increase security, use the DirX Directory-Administrators attribute (DADM attribute) to disable anonymous binds after bootstrapping the DSA and creating an entry that allows the administrator to log in. If it is not possible to use one of the values of the DirX Directory-Administrators attribute to bind to the DSA (because, for example, the entries or the passwords are deleted), you must reinstall DirX Directory.

If more than one bind is performed, the most recent bind is used.

Example
bind -user /o=my-company/CN=admin \
     -passw dirx \
     -auth simple_pr1
bind -user /o=my-company/CN=admin \
     -pwdfile \{c:\dirx\tmp\adp.txt} \
     -auth simple

dse commands

Lists all internal Tcl procedures installed with DirX Directory. The syntax is as follows:

  • [dse] commands

Use the command to list all Tcl procedures installed with DirX Directory that can be performed.

Use the [dse] help commands to display a list providing detailed information how to perform the internal procedures. (See the util (dirxadm) reference page for details about the listed procedures.)

Example

  1. The following example lists all internal procedures:

    dse commands

    The sample command output is as follows:

    create_total_ldif delete_total_ldif ldif_dump export_dbconfig import_dbconfig

  1. The following example provides detailed information about all internal procedures:

    dse help commands

    The sample command output is as follows:

    create_total_ldif [ID] [subtree]    Create total LDIF-File with
                                    agreementID ‘ID’
                                    or default agreementID ‘1111’
delete_total_ldif [ID]              Delete total LDIF-Agreement with
                                    agreementID 'ID'
                                    or default agreementID '1111'
ldif_dump [subtree]                 Perform a one-time total LDIF dump
                                    without creating an agreement
export_dbconfig [filename]          Write all indexed attributes to
                                    configuration file 'filename'.
import_dbconfig [filename]          Create attribute indices as in
                                    configuration file 'filename'
                                    described.
dirximport_all [dirname]            Import of LDAPSchema.ldif,
                                    DirXDBconfig.out and CONTENT-
                                    FILE(s) from the directory
                                    'dirname'..

dse create

Creates a new DSE in the DIT. The syntax is as follows:

  • [dse] create distinguished_name
        -attribute attribute_list

Options

-attribute attribute_list

  • Specifies one or more attributes to be applied to the DSE. See the DirX Directory Default DSA Schema chapter for a complete description of directory service attribute types and DirX Directory Syntaxes and Attributes for a complete description of the format of the attributes that can be specified in attribute_list.

    The create operation creates a new DSA-specific entry in the directory information tree. The distinguished_name argument is the name of the DSE to be created and can be specified as a complete distinguished name or a relative distinguished name. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a complete description of distinguished name formats.

Use the -attribute option to specify the directory service attributes to be applied to the newly created DSE. Note the following when creating DSEs:

  • The DSE-type (DSET) attribute type is required. If the value of the DSET attribute type is ENTRY, SUBENTRY or ALIAS, the object class attribute type (OCL) is also required. If the value of DSET is ADM_POINT, the administrative role attribute type (AR) is also required.

  • You cannot use dirxadm to create a DSE with the DSET value ROOT (the root DSE, represented by the slash (/)). The root DSE is created during the DirX Directory installation procedure and can only be modified and displayed.

The following command creates an autonomous administrative point:

create /C=de -attr {OCL=top;c} \
       DSET=ENTRY+ADM_POINT+CP \
       {AR=AA}

dse delete

Deletes DSEs from the DIT. The syntax is as follows:

  • [dse] delete distinguished_name

The delete operation deletes DSA-specific entries from the directory information tree.

Example

  1. The following sample command sets the current working DSE

    set _cwo \{/O=my-company/OU=board}

  1. The following sample command deletes the DSE /O=my-company/OU=board/CN=mueller peter

    delete \{CN=mueller peter}

dse help

Returns help information about the dse object and its operations. The syntax is as follows:

  • [dse] help [operation | -verbose]

Options

-verbose

  • Displays information about the dse object.

Used without an argument or option, the help command returns brief information about each dse operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the dse object itself.

Example
help

The command output is as follows:

bind

Binds to the specified directory server.

create

Creates a DSE under an existing superior.

delete

Deletes a DSE.

modify

Modifies a DSE.

search

Performs a search operation starting from a specified DSE.

show

Displays a DSE and its attributes.

help

Displays help text for the dse object and its operations.

operations

Lists the operations that can be performed on the dse object.

commands

Lists all built-in commands that can be performed.

dse modify

Changes the attribute values of a DSE. The syntax is as follows:

  • [dse] modify [distinguished_name]
        [-addattr attribute_list]
        [-removeattr attribute_list]

Options

-addattr attribute_list

  • Adds the attributes and attribute values specified in the attribute_list argument to a DSE. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of attribute type and value syntax.

-removeattr attribute_list

  • Removes the attributes and attributes values specified in the attribute_list argument from a DSE. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of attribute type and value syntax

The modify operation changes attributes and attribute values of DSEs. The distinguished_name argument specifies the DSE to modify; if no distinguished_name argument is specified, the operation acts on the current working DSE. Refer to DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a complete description of distinguished name format.

Use the -addattr option to add new attributes to a DSE or add new values to an existing attribute. The value of the -addattr option is an attribute list that describes the attributes or values to be added. Use the -removeattr option to remove existing attribute values or remove existing attributes. The value of the -removeattr option is an attribute list that describes the attributes or attribute values to be removed. The -addattr option, the -removeattr option, or both can be specified on the command line.

Examples

  1. The following sample command adds the User Policy (USP) attribute:

    dse modify -addattr {USP={USN={/},OPT=MODIFY};{USN={/c=xxx},OPT=CHAINING}}

  1. The following sample command removes the value /c=xxx of the User Policy (USP) attribute:

    dse modify -removeattr USP={/c=xxx}

dse operations

Returns a list of operations that can be performed on the dse object. The syntax is as follows:

  • [dse] operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example
dse operations

The command output is as follows:

bind create delete modify search show help operations

dse search

Searches for objects. The syntax is as follows:

  • [dse] search [distinguished_name]
        [-attribute abbreviation …​ | -allattr]
        [-dsetype dsetype]
        {-onelevel | -subtree}
        [-pretty]
        [-timeout timeout]

Options

-attribute abbreviation

  • Returns the attributes that correspond to the specified attribute abbreviations. Use the abbr show operation to determine attribute abbreviations.

-allattr

  • Shows information about all of the attributes of a DSE.

-dsetype dsetype

  • The type of DSE. dsetype can be one or more of the following keywords:

    • ALIAS - A DSE that represents an alias entry.

    • ADM_POINT - A DSE that represents an administrative point.

    • CP - A DSE that represents the context prefix of a naming context.

    • GLUE - A DSE that represents a name only. A DSA uses glue DSEs to hold the names of the superiors of the context prefixes and cross references where there is no other knowledge associated with them. You cannot assign any other DSE types to a DSE typed as GLUE.

    • IMM_SUPR - A DSE that represents an immediate superior reference, and holds a corresponding knowledge attribute.

    • NSSR - A DSE that represents a non-specific subordinate reference, and holds a corresponding knowledge attribute.

    • RHOB - A DSE that holds policy information (either administrative point or subentry information), which has been received from a superior DSA as the result of a hierarchical operational binding.

    • ROOT - Used exclusively by the DSE that represents the root of the DIT in a particular DSA.

    • SA - An additional characteristic of a subordinate reference DSE (i.e., of type SUBR), which is used to indicate that the context prefix pointed to by the reference is an alias and not a normal entry.

    • SUBENTRY - A DSE that represents a subentry.

    • SUBR - A DSE that represents a specific subordinate reference, and holds a corresponding knowledge attribute.

    • SUPR - Used to mark a root DSE that holds a knowledge attribute that represents a specific superior reference. (See the ROOT keyword.)

    • XR - A DSE that represents a cross-reference, and holds a corresponding knowledge attribute.

If you enter more than one dsetype, separate each keyword with a plus sign (+).

-onelevel

  • Limits the search scope to the children of the base object.

-pretty

  • Displays the results of the operation in a tabular format.

-timeout timeout

  • The operation stops after timeout seconds. The default is 180 seconds.

-subtree

  • Limits the search scope to the subtree below the base object.

The search operation searches for DSEs starting from the specified distinguished name or the current working DSE. You must specify either the -onelevel, or -subtree to define the scope of the search.

Use the -dsetype option to specify search conditions that limit the search to specified DSE types.

If you do not specify -dsetype, the search operation searches for all types of DSEs

Note that entries with a DSE type of 0, which are held by the DSA internally, are not visible with the search function. Use the show operation to examine those entries.

By default, the search operation does not search for attribute information. Use the -attribute option to return selected attribute information, or use the -allattr option to return information about all attributes.

By default, the search operation returns results as Tcl lists. Use the -pretty option to return formatted results.

Examples

The following sample search operation uses the -dsetype option to return the DNs and all administrative points and all subentries below /C=DE.

 search /C=de \
        -subtree \
        -dsetype ADM_POINT+SUBENTRY -p

The sample command output is as follows:

 1) /C=DE/CN=AC-Subentry
 2) /C=DE/CN=SSCH-Subentry

dse show

Shows the contents of a DSE. The syntax is as follows:

  • [dse] show [distinguished_name]
        [-allattr | -attribute abbreviation […​]]
        [-pretty]

Options

-allattr

  • Shows information about all of the attributes of a DSE, including user and operational attributes.

-attribute abbreviation …​

  • Shows information about the attributes that correspond to the specified attribute abbreviations. Use the abbr show operation to determine attribute abbreviations.

-pretty

  • Displays the results of the operation in a tabular format.

Used without arguments or options, the show operation returns the complete distinguished name of the current working DSE.

Use the distinguished_name argument to specify a DSE; see DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name format.

You can use the -attribute option to return information about specific attributes. Alternatively, you can use the -allattr option to return information about all of the DSE’s attributes. The show operation does not return information about a DSE’s collective attributes.

By default, the results of the show operation are displayed as a Tcl list; use the -pretty option to return the results in a tabular, more readable format.

Examples

  1. The following sample command displays the attributes locality and telephone number:

    dse show \{/O=my-company} -attribute L TN –p

    The sample command output is as follows:

     1) /O=my-company
    Locality         : Munich
    Telephone-Number : +49-999-1234567

  1. The following sample command displays the User-Policy of the root-DSE in pretty format:

    dse show / -attribute USP –p

    The sample command output is as follows:

    1) /
    User-Policy
      User-Subtree-Name : /C=xxx
      Options           : CHAINING
    User-Policy
      User-Subtree-Name : /
      Options           : MODIFY

  1. The following sample command displays the User-Policy of the root-DSE:

    dse show / -attribute USP

    The sample command output is as follows:

    / USP={USN={/},OPT=MODIFY}

ldap (dirxadm)

Synopsis

ldap audit {-info |
    -start |
    -stop |
    -config [LDAP_Audit_Configuration_subentry] |
    -move [destination_filename]}

ldap binding [-host hostname] [-port portnumber]

ldap cache {-start |
    -stop |
    -clear |
    -invalid |
    -dump |
    -dumpall |
    -info}

ldap help [operation | -verbose]

ldap mib {-all |
    {-static | -total | -current} [attribute_name] |
    -assoc | -env |
    -dump}
    [-pretty]

ldap log

ldap nolog

ldap operations

ldap restart

Purpose

A dirxadm object that manages the LDAP server. It is not necessary to perform a dse bind operation before performing ldap operations. (See also chapter Setting Up an LDAP Server in the Administration Guide.)

Note that you can also use the LDAP extended operations available through the dirxextop command and the DirX Directory Manager’s Monitor view to manage and monitor the LDAP server.

Arguments

operation

  • The name of the ldap operation for which to display help information.

Operations

ldap audit

Provides a set of operations for managing LDAP server auditing. Note that the DSA provides an own set of operations for managing DSA auditing. (See the audit (dirxadm) section in this chapter for details.) The syntax is as follows:

ldap audit \{-info |
_ -start _|
_ -stop _|
_ -config [_LDAP_Audit_Configuration_subentry] |
-move [destination_filename]}

Options

-info

  • Displays current audit status and configuration.

-start

  • Starts the recording of LDAP server audit information using the most recently read values of the LDAP audit configuration subentry. This operation has no effect on the value of the LDAP Audit On attribute of the LDAP audit configuration subentry that is evaluated at LDAP server’s start-up time and when you perform an ldap audit –config operation.

-stop

  • Stops the recording of LDAP server audit information. This operation has no effect on the value of the LDAP Audit On attribute of the LDAP audit configuration subentry that is evaluated at LDAP server’s start-up time and when you perform an ldap audit –config operation.

-config [LDAP_Audit_Configuration_subentry]

  • Forces the LDAP server to re-read the LDAP server audit configuration subentry. LDAP_Audit_Configuration_subentry specifies the name of the LDAP server audit configuration subentry to be read. Auditing is continued using the audit control values read from the specified subentry. If an LDAP server audit configuration subentry name is not specified, the LDAP server re-reads the subentry that is currently in use. If the LDAP server read operation of the LDAP audit configuration subentry fails, for example, because an invalid subentry name was specified, default values are used. (See section Attributes for LDAP Server Audit Configuration of chapter DirX Directory Attributes in DirX Directory Syntaxes and Attributes for details on the LDAP server audit configuration subentry and the default values.) The LDAP client connections are not affected.

-move [destination_filename]

  • Moves the audit file currently in use to another location and/or name. destination_filename is the full path name of the new file. If destination_filename is omitted, the audit file currently in use is renamed by appending the current UTC time in ZULU format and a counter from 000 to 999; for example audit.log.20010510104511Z_001.

The audit operation controls LDAP server auditing. Use the ldap audit -start command to enable LDAP server auditing. If auditing has already been enabled, issuing the ldap audit -start command has no effect. If LDAP auditing has been disabled, the ldap audit -start command:

  • closes any audit file that already exists and renames it by appending the current UTC time in ZULU format and a counter from 000 to 999; for example audit.log.20010510104511Z_001

  • creates a new audit file

The audit -start operation displays a message that indicates whether or not it was able to start LDAP server auditing. If startup is successful, the operation also displays the full pathname of the new audit file.

Use the ldap audit -stop command to disable LDAP server auditing. The operation closes the audit file that is currently in use and renames it by appending the current UTC time in ZULU format and a counter from 000 to 999, for example audit.log.20010510104511Z_001. Use the dirxauddecode command to evaluate this file.

Use the ldap audit -config command to set LDAP server auditing functions to the values in an LDAP server audit configuration subentry. See the section Attributes for LDAP Server Audit Configuration of chapter DirX Directory Attributes in DirX Directory Syntaxes and Attributes for details on the LDAP server audit configuration subentry and the default values.

The LDAP Audit Log File

When LDAP server auditing is enabled, audit information is collected in the file named audit.log. (For Linux systems: Read and Write permissions are assigned to the file’s owner and group.) Use the ldap audit -move command to rename and save the file. When auditing continues, the file audit.log is re-created and used to store audit information.

Use the destination_filename option of the ldap audit -move command to specify a new name for the file. Without this option the file is renamed to audit.log.*date**_nnn, where date is the current UTC time in ZULU format in the form YYYYMMDDhhmmssZ and nnn is a counter from 000 to 999, for example *audit.log.20010510104511Z_001. Use the dirxauddecode command to evaluate this file.

LDAP audit.log File Contents

The audit.log file contains one entry with general information (header information) on the audit file, an entry for each operation that occurs, and summary information. As produced by the ldap audit command the audit.log file contains records in binary format. Use the dirxauddecode command to display the contents of the log file and convert them to a form that can be read and manipulated. Use the dirxaudstatistics command to evaluate multiple audit log files.

The audit.log file general information (header) includes:

  • The command line.

  • The audit version.

  • The input file.

  • The output file.

  • The audit start time.

  • The audit end time.

  • The content type (always LDAP).

  • Evaluation-specific information, for example audit level, filtered user, or audit encryption.

  • The LDAP port.

  • The host.

  • Additional server specific information (similar to the information provided in the LDAP MIB static table).

Here is an example for some header information:

#################  DIR.X AUDIT TRAIL (c) Eviden  ################################
Cmd-Line: -i audit.log -vv -a ldap_audit.txt
=================================================================================
Audit  File #             :1
Input  File               :audit.log
Output File               :ldap_audit.txt
Audit Version             :8.8
Server UUID               :8360a2ac-b7e2-407a-aca9-0450d9e98ec9
Audit Start Time (local)  :Thu Nov 29 10:25:50 2012
Audit Start Time (GMT)    :Thu Nov 29 09:25:50 2012
Audit Close Time (local)  :not closed (still in use!)
Content Type              :LDAP
OpSelection               :all
OpErrors                  :yes
Audit Level               :max
Audit Encryption          :none
Overflow Action:          :wrap around (default)
Max Records per File      :10000
Value Limit               :256
DB Master-Entries         :0
DB Copy-Entries           :1573
...

The audit.log file information for each entry includes:

  • The create, start, and end time of the operation.

  • The concurrency of the operation.

  • The operation duration.

  • The user and the IP address of the user.

  • The operation name.

  • The operation type.

  • The protocol version used (2 or 3).

  • The message identifier.

  • Number of bytes received and sent.

  • Operation’s result code.

  • Additional operation-specific information, for example input parameters.

Here is an example for a bind and a search operation:

----------------- OPERATION 000031 ----------------
  Create Time    :Thu Nov 29 10:38:00.908999 2012
  Start Time     :Thu Nov 29 10:38:00.908999 2012
  End Time       :Thu Nov 29 10:38:00.986999 2012
  PoolThread#    :28 (0x15bc)
  OpUUID         :6c940e2c-8969-427e-aaf4-cb772088291f
  Concurrency    :1
  OpStackSize    :1
  OpFlow In/Out  :0/0
  Duration       :0.078000 sec
   LDAP QTime    :0.000000 sec
   LDAP Prep Time:0.000000 sec
   LDAP Resp Time:0.000000 sec
    LDAP Snd Time:0.000000 sec (1 Calls, 0 Wouldblocks, WouldblockTime:0.000000 sec)
    LDAP Enc Time:0.000000 sec
  API Time       :0.078000 sec
   API-Send      :0.000000 sec
   API-ICOM Wait :0.062999 sec
    IDM Time     :0.062999 sec
    DSA Time     :0.000000 sec
   API-Recv      :0.015000 sec
    API-Dec      :0.000000 sec
  User           :cn=admin,o=my-company
  IP+Port+Sd     :[127.0.0.1]+4709+556
  Op-Name        :LDAP_Con2_Op0
  UniqueOpID     :31
  Operation      :BIND
  Version        :3
  MessageID      :1
  Bind-Type      :simple
  Security       :normal
  DAP-Share-Count:1
  Bytes Received :39
  Bytes Returned :29
  Socket I/O     :plain
  Abandoned      :no
  Result Code    :0 (success)
  Error Message  :Bind succeeded.

----------------- OPERATION 000032 ----------------
  Create Time    :Thu Nov 29 10:38:07.190000 2012
  Start Time     :Thu Nov 29 10:38:07.190000 2012
  End Time       :Thu Nov 29 10:38:07.392999 2012
  PoolThread#    :30 (0x1460)
  OpUUID         :e792d1c7-7090-483d-b759-ae8afadfefbc
  Concurrency    :1
  OpStackSize    :1
  OpFlow In/Out  :0/0
  Duration       :0.202999 sec
   LDAP QTime    :0.000000 sec
   LDAP Prep Time:0.000000 sec
   LDAP Resp Time:0.000000 sec
    LDAP Snd Time:0.000000 sec (17 Calls, 0 Wouldblocks, WouldblockTime:0.000000 sec)
    LDAP Enc Time:0.000000 sec
  API Time       :0.202999 sec
   API-Send      :0.000000 sec
   API-ICOM Wait :0.202999 sec
    IDM Time     :0.015999 sec
    DSA Time     :0.187000 sec
   API-Recv      :0.000000 sec
    API-Dec      :0.000000 sec
  User           :cn=admin,o=my-company
  IP+Port+Sd     :[127.0.0.1]+4709+556
  Op-Name        :LDAP_Con2_Op1
  UniqueOpID     :32
  Operation      :SEARCH
  Version        :3
  MessageID      :2
  Base Obj       :o=My-Company
  Scope          :subtree
  Filter         :(cn=ANY(bel))
  Size Limit     :0
  Time Limit     :0
  Deref Alias    :always
  Types Only     :no
  Req Attr #     :1
    Req Attr     :1.1 (no attributes)
  Found Entries  :16
  Found Attrs    :0
  Found Values   :0
  Op  Ctx Size   :114688 Bytes
  API Ctx Size   :81920 Bytes
  All Ctx Size   :8 MB
  Bytes Received :56
  Bytes Returned :992
  Socket I/O     :plain
  Cached Result  :no
  Abandoned      :no
  Result Code    :0 (success)
  Error Message  :Search succeeded. Found 16 Entries (0 Aliases), 0 Attributes, 0 Values.

(ChainedResult=no)

The audit.log file summary information includes:

  • The total number of records processed.

  • The total number of operations.

  • The number of bytes received and sent.

  • The number of operations that performed successfully.

  • The number of operations that failed.

  • The number of abandoned operations.

  • The number of search results of specific sizes.

  • The number of entries, attributes, and values found.

  • The duration of operations.

  • The concurrency of operations.

  • Operation specific statitics providing for example information about number, success, average duration, maximum duration.

  • Result statitics, for example 35 times success.

  • The top durations.

Here is an example for summary information:

=================================================================================
  LDAP Audit Summary:
    Records Processed : 39
    Total Ops Written : 39
    Out-Of-Time Ops   : 0
    Ldap Bytes In     : 9906
    Ldap Bytes Out    : 940342
    Successful Ops    : 35
    Failed Ops        : 4
    Abandoned Ops     : 3
    SrchRes 0kB-1kB   : 19
    SrchRes 1kB-10kB  : 4
    SrchRes 10kB-100kB: 2
    SrchRes 100kB-1MB : 1
    SrchRes > 1MB     : 0
    Srch Scope Base   : 12
    Srch Scope Onelvl : 11
    Srch Scope Subtree: 3
    Paged Searches    : 11
    Found Entries     : 362
    Found Attributes  : 253
    Found Values      : 873
    Log Time          : 337 sec
    Avrg Traffic      : 0.1 Ops/sec
    Duration 0-1ms    : 10 Ops
    Duration 1-10ms   : 0 Ops
    Duration 10-100ms : 19 Ops
    Duration 100ms-1s : 4 Ops
    Duration >1s      : 6 Ops
    Duration Max      : 7.201999 sec (Op# 000010)
    Concurrency Max   : 3 (1 times) (Op# 000013)
    Avrg Concurrency  : 1

    Op Statistics     :  tot |    ok |   err |     % |       t Avrg |        t Max |        t
Min |  Std-Dev
      Binds           :    4 |     4 |     0 |  10.3 | 0.074250 sec | 0.218999 sec | 0.000000
sec | 0.103267
      Searches        :   26 |    26 |     0 |  66.7 | 0.544346 sec | 7.201999 sec | 0.000000
sec | 1.562088
      Modifys         :    1 |     1 |     0 |   2.6 | 0.062000 sec | 0.062000 sec | 0.062000
sec | 0.000000
      Unbinds         :    2 |     2 |     0 |   5.1 | 0.000000 sec | 0.000000 sec | 0.000000
sec | 0.000000
      Abandons        :    3 |     0 |     3 |   7.7 | 2.109000 sec | 2.796000 sec | 1.358999
sec | 0.720569
      Ext Ops         :    2 |     2 |     0 |   5.1 | 0.023500 sec | 0.030999 sec | 0.016000
sec | 0.010606
      Unknowns        :    1 |     0 |     1 |   2.6 | 0.000000 sec | 0.000000 sec | 0.000000
sec | 0.000000

    Error/ResultCode Statistics:
       35 times success (0).
        3 times other (80).
        1 times unexpectedSocketCloseByClient (97).

    Top 100 Durations:
      Duration   CreateTime        EndTime           Op#      CC   Type/Info
      0.281000 | 10:35:19.862999 | 10:35:20.143999 | 000003 |  1 | SEARCH
(objectclass=subschema)
      0.265000 | 10:38:23.766999 | 10:38:24.031999 | 000034 |  1 | SEARCH
(UserCertificate:2.5.13.34:=30$cn=admin,o=pqrupmann02)
      0.218999 | 10:35:19.581000 | 10:35:19.799999 | 000001 |  1 | BIND
cn=admin,o=my-company
      0.202999 | 10:38:07.190000 | 10:38:07.392999 | 000032 |  1 | SEARCH
...
Examples

  1. The following sample command displays current LDAP audit status and configuration:

    ldap audit –info

    The output of the sample command is as follows:

    {
==================== LDAP Audit Info  ===========================
Server            : DirX Directory V8.2 B 8.8.103 2012:12:05 20:10 32-Bit
Copyright (c) 2012 Eviden
Hostname          : xyz.net
Current Local Time: Mon Dec 10 11:26:14 2012
Status            : ON
Audit Version     : 8.8
Destination File  : C:\Program Files\DirX\Directory\ldap\audit\ldapConfiguration\audit.log
Audited Bytes     : 5400
Record Limit      : 50000 records
Max File Size     : 256 MB
Records in File   : 0 records
Overall Records   : 0 records
Overflow Policy   : multiWrap
Max Wrap Files    : 4
Next Wrap File    : audit.log.4948.01
Wrap Count        : 0
Move Count        : 0
Detail Level      : max
Value Limit       : 128
Op Selection      : none  (errors included)
Buffer Size       : 0
Start Time        : none
Stop Time         : none
Cron Job          : no
unlink() errors   : 0
rename() errors   : 0
Encryption        : none
SessTracking      : on
SessTrackingLen   : 64
}

  2. The following sample command starts LDAP auditing:

    ldap audit -start

    The output of the sample command is as follows:

    LDAP Audit started.
Destination File  : C:\Program Files\DirX\Directory\ldap\audit\ldapConfiguration\audit.log

  3. The following sample command stops LDAP auditing:

    ldap audit –stop

    The output of the sample command is as follows:

    LDAP Audit stopped.

  4. The following sample command enables the configuration settings of the LDAP audit configuration subentry with the name ldapAudit2:

    ldap audit –config ldapAudit2

    The output of the sample command is as follows:

    Audit file successfully closed+renamed.
New audit configuration successfully read from subentry:ldapAudit2.
New audit file successfully opened.
Audit is ON.

  5. The following sample command moves the audit file currently in use (install_path/ldap/audit/audit.log) to install_path/ldap/audit/audit.log.20010510104511Z_001 using the default rules for renaming:

    ldap audit -move

    The output of the sample command is as follows:

    Audit file successfully moved.
New audit file successfully created.

  6. The following sample move command fails:

    ldap audit –move /opt/dirx/foo/aud.log

    The output of the sample command is as follows:

    ERROR! Failed to move audit file (No such file or directory).

ldap binding

Specifies the LDAP server to be administered. This operation must be performed when administering an additional LDAP server or a remote LDAP server. To administer a remote LDAP server the -host option must be specified. (See also environment variable DIRX_ADDITIONAL_LDAP_SERVERS in chapter DirX Directory Environment Variables and section Setting Up Multiple LDAP Servers in the Administration Guide.) The syntax is as follows:

  • ldap binding [-host hostname] [-port portnumber]

Options

-host hostname

  • The hostname or IP address of the machine hosting the LDAP server to be administered. The default is localhost.

-port portnumber

  • The RPC port number of the LDAP server. If you have established additional LDAP servers you must specify here the proper RPC port from the DIRX_ADDITIONAL_LDAP_SERVERS environment variable. (See also environment variable DIRX_LDAP_PMAP_PORT in chapter DirX Directory Environment Variables.)

Example
ldap binding -host 123.456.78.99 -port 6666

ldap cache

Provides a set of operations for dynamic administration of the LDAP cache independent of the settings in the LDAP server configuration subentry. The syntax is as follows:

  • ldap cache {-start |
        -stop |
        -clear |
        -invalid |
        -dump |
        -dumpall |
        -info    }

Options

-start

  • Starts caching of LDAP search results. All subsequent LDAP search operations query the LDAP cache first. The request is only directed to the DSA if the search result cannot be found in the LDAP cache.

-stop

  • Stops caching of LDAP search results. All subsequent LDAP search operations are directed to the DSA.

-clear

  • Clears the LDAP cache immediately. All LDAP search results are removed from the cache.

-invalid

  • Sets the status of all LDAP search results in the cache to invalid without removing them. This operation is used by the DSA to notify database modifications.

-dump

  • Dumps configuration information, statistical information, and all saved results in internal cache format to the file install_path*/ldap/log/cache*process_id*.txt* where process_id is the process ID of the LDAP server. In the event that the file already exists it is overwritten.

-dumpall

  • Dumps configuration information, statistical information, and all saved results in full readable format to the file install_path*/ldap/log/cache*process_id*.txt* where process_id is the process ID of the LDAP server. In the event that the file already exists it is overwritten.

-info

  • Displays configuration information and statistical information.

Examples

  1. The following command enables the LDAP cache:

    ldap cache –start

  2. The following command disables the LDAP cache:

    ldap cache –stop

  3. The following command removes all LDAP search results from the LDAP cache:

    ldap cache –clear

  4. The following command sets the status of the content of the LDAP cache to invalid:

    ldap cache –invalid

  5. The following command generates an informal dump of the LDAP cache content:

    ldap cache –info

    The command output is as follows:

    ==================== LDAP Cache Info  ===========================
HostName          : host1.my-company.net        name of the host machine
Current Local Time: Fri Mar 07 14:58:40 2008    current time
Cache Table Size  : 4096          size of the internal hash table to store the results
Min Cache Time    : 0 sec.        min time a result remains in the cache
Max Cache Time    : 86400 sec.    max time a result remains in the cache
Min Cached Entries: 0             min # of entries a result must have to be cached
Max Cached Entries: 2000          max # of entries a result may have to be cached
Min Cached Attrs  : 0             min # of attributes a result must have to be cached
Max Cached Attrs  : 2200          max # of attributes a result may have to be cached
Min Cached Values : 0             min # of values a result must have to be cached
Max Cached Values : 5000          max # of values a result may have to be cached
Max Cached Results: 10000         may # of results in cache
Max Cache Size    : 13 MB         max memory usage for entire cache
Case Sensitive    : no            whether request params are handled case sensitive
Update Strategy   : DN/Scope+Attributes    type of strategy applied when modifications +
                                           happen
Thread Pool Size  : 32            # of started pool threads
Pool Threads Idle : 32            # of pool threads waiting for requests
OpStack Size      : 1             # requests enqueued for processing
Cache-Status      : ON (valid)    main status of cache content
-----------------------------------------------------------
Cached Results             : 1520       total # of results currently in cache
Cached Entries             : 3040       total # of entries (across all results)
Memory Used                : 13312 KB   memory currently in use by cache
Cache-Tries                : 2095       # of LDAP searches that tried to find the +
                                        result in the cache
Cache-Hits                 : 314 (Ratio: 14 %)  # of LDAP searches that found their +
                                                result in the cache
Cache-Fails                : 1781    # of LDAP searches that failed to find their +
                                     result in the cache
Results in use             : 0       # of results in use by a pool thread +
                                       (in return to client)
Results outdated           : 0       # of results that were in use while they +
                                       should be removed by a modification operation
Saving Time                : 9.496483 sec   time saved by avoiding querying the DSA
Update Costs               : 0.000000 sec   time wasted by performing updates to the +
                                            result cache
Cache Timer Count          : 0      counts how many times the time-driven cache +
                                    updater-thread was running +
                                    (max-cache-time handler)
Last Cache Timer           : never  timestamp of last cache updater run
Last Cache Timer Removed   : 0      # of results removed by last cache updater run
Last Cache Timer Inuse     : 0      # of results that could not be removed because +
                                      they were in use in last updater run
Last Cache Timer Young     : 0      # of results that could not be removed because +
                                      they were too young in last updater run
Last Add Time              : Fri Mar 7 14:58:39.911016 2008  timestamp of last +
                                                             addition to cache
Last Hit Time              : Fri Mar 7 14:58:40.116437 2008  timestamp of last hit
Last SelUpd Time           : never  timestamp of last selective update to the +
                                    results in cache
Last Add                   : (idx:1041,key:302826513)   index and key of last added +
                                                        result
Last Hit                   : (idx:3668,key:1315683924)  index and key of last hit
Oldest Result              : 7.451905 sec. (idx:2662,key:1640270438) age, index and +
                                               key of oldest stored result in cache
Newest Result              : 1.303702 sec. (idx:1041,key:302826513)  age, index and +
                                               key of newest stored result in cache
Biggest Result             : 8 KB. (idx:7,key:786763783)   largest single result +
                                                           stored
Results Size 0-2kB         : 0      # of results in the range 0-2kB
Results Size 2-10kB        : 1520   # of results in the range 2-10kB
Results Size 10-100kB      : 0      # of results in the range 10-100kB
Results Size 100-1000kB    : 0      # of results in the range 100kB-1MB
Results Size >1MB          : 0      # of results larger than 1MB
Scope Base, One, Sub       : 0, 0, 1520    # of results for queries with scope +
                                           baselevel, onelevel and subtree
Min Hit                    : 0 (idx=1214)  lowest hit count of any result +
                                           (only 1st is listed)
Max Hit                    : 3 (idx=1)     highest hit count of any result +
                                           (only 1st is listed)
Lowest SeqNo               : 1      lowest internal seqNo of any result
Max Chain Len              : 4      longest linked list used for storing results +
                                    (less is better)
 Chain Len 0: 2819                  # of results stored in linked lists of length N
 Chain Len 1: 1067
 Chain Len 2: 178
 Chain Len 3: 31
 Chain Len 4: 1
Total Search Count         : 2095   # of searches performed in the cache
Total Add    Count         : 1781   # of elements ever added to the cache
Long Term Ratio            : 14 %   hit ration since server start (across resets)
UpdateStackSize            : 0      # of cache updates enqueued for processing +
                                    (RPC updates from DSA)
UpdateStackHWM             : 0      high-water-mark of cache update stack
Total Key Collisions       : 0      # of results that led to hash key collision +
                                    (not stored)
Total Rejected Adds        : 261    # of results that were not cached because of +
                                    the following reasons
  ReqErrors                : 0         -> result was an error
  KeyErrors                : 0         -> no legal hashkey could be calculated
    PPO Attrs              : 0         -> request contained password policy relevant +
                                          attributes
  NotCacheable             : 0      # of results that were marked as not-cacheable by +
                                    the DSA for one of the follwoing reasons
    Chaining               : 0         -> result contains entries from other DSA +
                                          (chaining involved)
    Alias                  : 0         -> result was built vial aliases
    NumSubAttr             : 0         -> result contains number-of-subordinate +
                                          attributes
  CriticalControl          : 0      # of results not cached because request contained +
                                    critical controls (e.g. simple paging)
  NoDAPSearchResult        : 0      # of results with no DAP result
  MaxResultLimit           : 0      # of results not cached because max limit was +
                                    exceeded
  TooLessEntries           : 0      # of results not cached because they contained too +
                                    less entries
  TooMuchEntries           : 0      # of results not cached because they contained too +
                                    many entries
  TooLessAttrs             : 0      # of results not cached because they contained too +
                                    less attributes
  TooMuchAttrs             : 0      # of results not cached because they contained too +
                                    many attributes
  TooLessValues            : 0      # of results not cached because they contained too +
                                    less values
  TooMuchValues            : 0      # of results not cached because they contained too +
                                    many values
  SameKeyInUse             : 0      # results not cached because the same hashkey was +
                                    in use
  CtxError                 : 0      # results not cached because of out-of-memory +
                                    errors
  MaxCacheSizeExceeded     : 261    # results not cached because they would exceed the +
                                    max mem size limit
Total Remove All Calls     : 0      # of entire cleanup calls (e.g. after schema has +
                                    changed)
Total Remove Sel Calls RPC : 0      # of selective cache update calls received from +
                                    DSA
Total Remove Sel Calls LDAP: 0      # of selective cache update calls initiated by +
                                    LDAPServer
Total Remove Min Calls     : 0      # of calls to remove results with minimum hits
Total Remove Old Calls     : 0      # of calls to remove old results (used by cache +
                                    update timer)
Total Invalid Calls        : 0      # of calls that have invalidated the entire +
                                    content
Total Non-Cacheable Results: 0      # of non cacheable results
Total Out-Of-Bounds Results: 0      # of results not cached because too many/too less +
                                    items
Total Sel-Del Results      : 0      # of results that were deleted by selective +
                                    updates
Total LDAP TCP Bytes In    : 112 KB   # of bytes received from LDAP clients
Total LDAP TCP Bytes Out   : 1858 KB  # of bytes sent back to LDAP clients
-----------------------------------------------------------

  6. The following command generates dump of the total LDAP cache content in internal cache format:

    ldap cache –dump

    The command output is as follows:

    ================ Cache Info (RPC-CacheDump) ====================
Hostname: john02
Current Local Time: Thu Jun 17 09:47:08 2004
Cache Table Size: 4096
Min Cache Time: 0 sec.
Max Cache Time: 43200 sec.
Min Cached Entries: 0
Max Cached Entries: 2000
Min Cached Attrs : 0
Max Cached Attrs : 2200
Min Cached Values : 0
Max Cached Values : 2500
Max Cached Results: 10000
Case Sensitive : no
Update Strategy: DN/Scope+Attributes
Thread Pool Size: 32
Pool Threads Idle: 32
OpStack Size: 0
Cache-Status: ON (valid)
[idx:count:tries:hits]+(key,version,hits,entries,inusecount,seqno,size)+...
----------------------------------------------------------------
[4:1:2:1]+(2006376452,2,1,2,0,1718,4)
[7:1:3:2]+(786763783,2,2,2,0,874,4)
[10:1:3:2]+(3284357130,2,2,2,0,1042,4)
[16:1:3:2]+(3152842768,2,2,2,0,1612,4)
[23:1:3:2]+(3538710551,2,2,2,0,442,4)
[27:1:2:1]+(4252475419,2,1,2,0,1776,4)
[29:2:5:3]+(3152060445,2,1,2,0,1207,4)+(3867717661,2,2,2,0,71,4)
[31:1:3:2]+(3911106591,2,2,2,0,590,4)
[37:2:5:3]+(1924628517,2,2,2,0,1249,4)+(1759916069,2,1,2,0,1008,4)
[38:1:2:1]+(2582659110,2,1,2,0,1053,4)
[42:1:3:2]+(1607364650,2,2,2,0,606,4)
[47:1:3:2]+(63844399,2,2,2,0,1459,4)
[51:1:3:2]+(1143046195,2,2,2,0,296,4)
[57:1:2:1]+(3718492217,2,1,2,0,717,4)
[60:1:3:2]+(2639933500,2,2,2,0,1090,4)
[64:1:3:2]+(1072439360,2,2,2,0,1134,4)
[71:1:2:1]+(2103390279,2,1,2,0,1278,4)
[74:1:2:1]+(740675658,2,1,2,0,1499,4)
[76:1:3:2]+(3154894924,2,2,2,0,945,4)
[78:1:3:2]+(873377870,2,2,2,0,17,4)
[80:1:3:2]+(2572693584,2,2,2,0,158,4)
[81:1:2:1]+(1075593297,2,1,2,0,470,4)
[84:1:3:2]+(4090605652,2,2,2,0,1268,4)
[85:1:2:1]+(2178023509,2,1,2,0,400,4)
[87:1:2:1]+(3610521687,2,1,2,0,1437,4)
[90:1:2:1]+(351764570,2,1,2,0,1409,4)
[98:3:8:5]+(898678882,2,2,2,0,890,4)+(1089175650,2,1,2,0,545,4)+(207970402,2,2,2,0,415,4)
[102:2:6:4]+(475557990,2,2,2,0,1198,4)+(617570406,2,2,2,0,444,4)
[107:1:2:1]+(1042862187,2,1,2,0,1610,4)
[111:1:3:2]+(3295166575,2,2,2,0,423,4)
[112:2:5:3]+(297373808,2,1,2,0,1571,4)+(2887319664,2,2,2,0,1168,4)
[116:1:3:2]+(3838820468,2,2,2,0,722,4)
[117:1:3:2]+(3597672565,2,2,2,0,561,4)
[122:1:3:2]+(887083130,2,2,2,0,280,4)
.....
.....
[4083:1:2:1]+(2893672435,2,1,2,0,957,4)
[4084:2:5:3]+(4102500340,2,1,2,0,1251,4)+(287105012,2,2,2,0,295,4)
[4088:1:2:1]+(2683502584,2,1,2,0,1086,4)
[4090:1:3:2]+(3455864826,2,2,2,0,410,4)
[4091:1:3:2]+(2929549307,2,2,2,0,1563,4)
[4092:1:2:1]+(3788476412,2,1,2,0,1096,4)
[4093:1:2:1]+(261189629,2,1,2,0,446,4)
[4094:2:5:3]+(3725135870,2,2,2,0,1580,4)+(492785662,2,1,2,0,1374,4)
[4095:1:3:2]+(1471160319,2,2,2,0,887,4)
-------------------------------------------------------
Cached Results : 1782
Cached Entries : 3564
Memory Used : 8088 KB
Cache-Tries: 4969
Cache-Hits : 3187 (Ratio: 64 %)
Cache-Fails: 1782
Results in use : 0
Results outdated : 0
Last Add Time: Thu Jun 17 09:43:48 2004
Last Add : (idx:1582,key:2666776110)
Last Hit : (idx:1309,key:2315064605)
Oldest Result: 567 sec. (idx:3074,key:2029218818)
Newest Result: 200 sec. (idx:27,key:4252475419)
Biggest Result: 4 KB. (idx:4,key:2006376452)
Results Size 0-2kB : 0
Results Size 2-10kB : 1782
Results Size 10-100kB : 0
Results Size 100-1000kB: 0
Results Size >1MB : 0
Min Hit: 0 (idx=1)
Max Hit: 7 (idx=1)
Lowest SeqNo: 1
Scope Base, One, Sub : 1, 0, 1781
Max Chain Len: 4
Chain Len 0: 2641
Chain Len 1: 1178
Chain Len 2: 230
Chain Len 3: 44
Chain Len 4: 3
Total Search Count: 4969
Total Add Count: 1782
Long Term Ratio : 64 %
Total Remove All Calls : 0
Total Remove Sel Calls RPC : 0
Total Remove Sel Calls LDAP: 0
Total Remove Min Calls : 0
Total Remove Old Calls : 0
Total Invalid Calls : 0
Total Non-Cacheable Results: 0
Total Out-Of-Bounds Results: 0
Total Sel-Del Results : 0
Total LDAP TCP Bytes In : 265 KB
Total LDAP TCP Bytes Out : 4406 KB
=======================================================

  7. The following command generates a detailed dump of the total LDAP cache content:

    ldap cache –dumpall

    The command output is as follows:

    ==================== Cache Info (RPC-CacheDumpAll) ===========================
Hostname: john02
Current Local Time: Thu Jun 17 09:49:22 2004
Cache Table Size: 4096
Min Cache Time: 0 sec.
Max Cache Time: 43200 sec.
Min Cached Entries: 0
Max Cached Entries: 2000
Min Cached Attrs  : 0
Max Cached Attrs  : 2200
Min Cached Values : 0
Max Cached Values : 2500
Max Cached Results: 10000
Case Sensitive    : no
Update Strategy: DN/Scope+Attributes
Thread Pool Size: 32
Pool Threads Idle: 32
OpStack Size: 0
Cache-Status: ON (valid)
----------------------------------------------------------------
Slot: [idx=4,count=1,tries=2,hits=1]
++++++++++++++++++ Result #1 +++++++++++++++++++
key:2006376452
keystr:<CN=ONIDA FERLAND, OU=PRODUCT DEVELOPMENT, O=My-Company>O=My-Company:V2:2:0:0:0:(UID=TILDIE_BULMANIS)
rdncount:1
baseObjRDN(1):
 31 80 30 80 06 03 55 04 0a 13 03 70 71 72 00 00  : 1.0...U....pqr..
 00 00                                            : ..
allattr:yes
scope:subtree
version:2
hits:1
creattime:Thu Jun 17 09:43:47 2004
age:335 sec.
outdated:no
seqno:1718
size:4 KB
entries:1
inusecount:0
--- #1 (Entry) ---
messageID:196
objectName:cn=Tildie Bulmanis,ou=McJahn2,o=my-company
objectClass:top,person,organizationalPerson,inetOrgPerson
cn:Tildie Bulmanis
sn:Bulmanis
l:Cambridge
ou:McJahn2
title:Associate McJahn2 Consultant
description:This is Tildie Bulmanis's description
postalAddress:my-company$McJahn2$Dept # 298
telephoneNumber:+1 303 683-1849
facsimileTelephoneNumber:+1 408 683-5109
givenName:Tildie
initials:T. B.
userPassword:sinamluBei
mail:Tildie_Bulmanis@my-company.com
carLicense:SZWI92O
departmentNumber:7513
employeeType:Employee
homePhone:+1 206 442-4655
manager:cn=Levent Robins
mobile:+1 804 587-6490
pager:+1 71 968-5331
roomNumber:4315
secretary:cn=Brear Elhamahmy
uid:Tildie_Bulmanis
collectiveTelephoneNumber:+12 34 567 0
--- #2 (ResultCode) ---
messageID:196
resultCode:0
errorMessage:Search operation succeeded
++++++++++++++++++++++++++++++++++++++++++++++++
Slot: [idx=7,count=1,tries=3,hits=2]
++++++++++++++++++ Result #1 +++++++++++++++++++
key:786763783
keystr:<CN=KAT MITALAS, OU=PRODUCT TESTING, O=My-Company>O=My-Company:V2:2:0:0:0:(UID=FANCY_CADZOW)
rdncount:1
baseObjRDN(1):
 31 80 30 80 06 03 55 04 0a 13 03 70 71 72 00 00  : 1.0...U....pqr..
 00 00                                            : ..
allattr:yes
scope:subtree
version:2
hits:2
creattime:Thu Jun 17 09:43:40 2004
age:342 sec.
outdated:no
seqno:874
size:4 KB
entries:1
inusecount:0
--- #1 (Entry) ---
messageID:99
objectName:cn=Fancy Cadzow,ou=Product Testing,o=my-company
objectClass:top,person,organizationalPerson,inetOrgPerson
cn:Fancy Cadzow
sn:Cadzow
l:San Francisco
ou:Product Testing
title:Master Product Testing Fellow
description:This is Fancy Cadzow's description
postalAddress:my-company$Product Testing$Dept # 177
telephoneNumber:+1 213 344-4751
facsimileTelephoneNumber:+1 71 944-1379
givenName:Fancy
initials:F. C.
userPassword:wozdaCycna
mail:Fancy_Cadzow@my-company.com
carLicense:NOTKMH9
departmentNumber:7054
employeeType:Employee
homePhone:+1 408 735-8563
manager:cn=Aurea Ruel
mobile:+1 71 337-4872
pager:+1 408 426-7911
roomNumber:6845
secretary:cn=Rhianon Loghry
uid:Fancy_Cadzow
collectiveTelephoneNumber:+12 34 567 0
--- #2 (ResultCode) ---
messageID:99
resultCode:0
errorMessage:Search operation succeeded
......
......
++++++++++++++++++++++++++++++++++++++++++++++++
Slot: [idx=4095,count=1,tries=3,hits=2]
++++++++++++++++++ Result #1 +++++++++++++++++++
key:1471160319
keystr:<CN=SALINA DELF, OU=HUMAN RESOURCES, O=MY-COMPANY>O=MY-COMPANY:V2:2:0:0:0:(UID=NEENA_CHYTIL)
rdncount:1
baseObjRDN(1):
 31 80 30 80 06 03 55 04 0a 13 03 70 71 72 00 00  : 1.0...U....pqr..
 00 00                                            : ..
allattr:yes
scope:subtree
version:2
hits:2
creattime:Thu Jun 17 09:43:40 2004
age:342 sec.
outdated:no
seqno:887
size:4 KB
entries:1
inusecount:0
--- #1 (Entry) ---
messageID:104
objectName:cn=Neena Chytil,ou=Product Testing,o=my-company
objectClass:top,person,organizationalPerson,inetOrgPerson
cn:Neena Chytil
sn:Chytil
l:Redwood Shores
ou:Product Testing
title:Master Product Testing Developer
description:This is Neena Chytil's description
postalAddress:my-company$Product Testing$Dept # 103
telephoneNumber:+1 206 783-8159
facsimileTelephoneNumber:+1 415 548-4802
givenName:Neena
initials:N. C.
userPassword:lityhCanee
mail:Neena_Chytil@my-company.com
carLicense:YL6YTUW
departmentNumber:8434
employeeType:Employee
homePhone:+1 408 325-6557
manager:cn=Sandra Janes
mobile:+1 213 704-9995
pager:+1 510 391-4958
roomNumber:1949
secretary:cn=Jagjit Appleyard
uid:Neena_Chytil
collectiveTelephoneNumber:+12 34 567 0
--- #2 (ResultCode) ---
messageID:104
resultCode:0
errorMessage:Search operation succeeded
++++++++++++++++++++++++++++++++++++++++++++++++
-------------------------------------------------------
Cached Results : 1782
Cached Entries : 3564
Memory Used : 8088 KB
Cache-Tries: 4969
Cache-Hits : 3187 (Ratio: 64 %)
Cache-Fails: 1782
Results in use   : 0
Results outdated : 0
Last Add Time: Thu Jun 17 09:43:48 2004
Last Add : (idx:1582,key:2666776110)
Last Hit : (idx:1309,key:2315064605)
Oldest Result: 701 sec. (idx:3074,key:2029218818)
Newest Result: 334 sec. (idx:27,key:4252475419)
Biggest Result: 4 KB. (idx:4,key:2006376452)
Results Size 0-2kB     : 0
Results Size 2-10kB    : 0
Results Size 10-100kB  : 0
Results Size 100-1000kB: 0
Results Size >1MB      : 0
Min Hit: 0 (idx=1)
Max Hit: 7 (idx=1)
Lowest SeqNo: 1
Scope Base, One, Sub   : 0, 0, 0
Max Chain Len: 4
 Chain Len 0: 2641
 Chain Len 1: 1178
 Chain Len 2: 230
 Chain Len 3: 44
 Chain Len 4: 3
Total Search Count: 4969
Total Add    Count: 1782
Long Term Ratio   : 64 %
Total Remove All Calls     : 0
Total Remove Sel Calls RPC : 0
Total Remove Sel Calls LDAP: 0
Total Remove Min Calls     : 0
Total Remove Old Calls     : 0
Total Invalid Calls        : 0
Total Non-Cacheable Results: 0
Total Out-Of-Bounds Results: 0
Total Sel-Del Results      : 0
Total LDAP TCP Bytes In    : 265 KB
Total LDAP TCP Bytes Out   : 4406 KB
=======================================================

ldap help

Returns help information about the ldap object and its operations. The syntax is as follows:

  • ldap help [operation | -verbose]

Options

-verbose

  • Displays information about the ldap object.

Used without an argument or option, the ldap help operation returns brief information about each ldap operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the ldap object itself.

Example
ldap help

The output of the sample command follows:

audit

Manages LDAP Server auditing.

binding

Sets the LDAP Server to be administered.

cache

Administers the LDAP Server cache.

log

Switches on the diagnostic logging.

mib

Lists the details of the LDAP Server MIBs.

nolog

Switches off the diagnostic logging.

restart

Stops and restarts the LDAP Server.

help

Displays the help text for the “ldap” object and its operations.

operations

Lists the operations that can be performed on the “ldap” object.

ldap log

Starts LDAP server diagnostic logging. The syntax is as follows:

  • ldap log

LDAP server logging is initially controlled by the specifications in the configuration file install_path*/ldap/conf/dirxlog.cfg*. When an ldap log operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path*/ldap/conf/dirxlog.on*. To use these specifications when restarting the LDAP server, edit the file install_path*/ldap/conf/dirxlog.cfg* according to the settings in install_path*/ldap/conf/dirxlog.on*. By default, the log files are written to the directory install_path*/ldap/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

When the environment variable DIRX_LOGCFG_FILE (see chapter titled DirX Directory Environment Variables for details) is set, logging is controlled by the specifications in this file.

Example
ldap log

ldap mib

Provides a set of operations for managing of the LDAP server MIBs. (See appendix LDAP MIB Tables for a detailed description of the LDAP server MIBs.)

These operations will no longer be supported in future versions of DirX Directory. Instead use the LDAP extended operations ldap_mib_total, ldap_mib_current, ldap_mib_assoc, ldap_mib_env and ldap_mib_dump. (See the dirxextop reference page for details.)

The syntax is as follows:

  • ldap mib {-all |
        *{    -static | -total | -current*} [attribute_name] |
        -assoc | -env |
        -dump    } [-pretty]

Options

-all

  • Displays the information in all MIB tables except the MIB association table.

-static [attribute_name]

  • Displays the value of an attribute in the MIB static table. attribute_name must specify the exact name of a MIB attribute. The appendix LDAP MIB Tables lists the names of all MIB attributes. If attribute_name is not specified, the operation displays all of the information in the MIB static table.

-total [attribute_name]

  • Displays the value of an attribute in the MIB total table. attribute_name must specify the exact name of a MIB attribute. The appendix LDAP MIB Tables lists the names of all MIB attributes. If attribute_name is not specified, the operation displays the information in the MIB total table.

-current [attribute_name]

  • Displays the value of an attribute in the MIB current table. attribute_name must specify the exact name of a MIB attribute. The appendix LDAP MIB Tables lists the names of all MIB attributes. If attribute_name is not specified, the operation displays the information in the MIB current table.

-assoc

  • Displays the information in the MIB association table.

-env

  • Displays the currently known environment strings.

-dump

  • Writes the information in all MIB tables except the MIB association table to the file mib*pid.txt* where pid is the process ID of the LDAP server. This file is written to the same directory as the usual log files, by default to the directory install_path*/ldap/log*.

-pretty

  • Displays the results of the operation in tabular format.

Examples

  1. The following sample command displays all MIB tables except the MIB association table:

    ldap mib -all -pretty

    The output of the sample command is as follows:

    Static Infos:
    Operating System          : MS Windows 2000 5.0 (Workstation) Build 2195 (Service Pack 4)
    Host Name                 : john02
    Host IP                   : 123.45.678.90
    CPUs                      : 1
    Total Phys Memory         : 1014 MB
    Avail Phys Memory         : 462 MB
    Pagesize                  : 4096 Bytes
    Max Open Files soft       : unlimited
    Max Open Files hard       : unlimited
    Server Version            : DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit
    Server Type               : Frontend Server
    Server Mode               : Read/Write
    Backend Sharing           : enabled
    Contact DSA               : TS=DSA1,NA='TCP/IP_IDM!internet=127.0.0.1+port=21200'
    Anonymous Allowed         : yes
    SSL Encryption            : strong SSL
    Start Time                : Thu Jun 17 09:37:32 2004
    Current Time              : Thu Jun 17 09:53:17 2004
    Configuration Name        : ldapConfiguration
    ClCfg File                : C:\Program Files\DirX\Directory\ldap\conf\dirxldap.cfg
    PID                       : 2020
    Ldap Port                 : 8080
    SSL Port                  : 0
    RPC Port                  : 6999
    Max Conn                  : 1024
    Client Idle Time          : 1000
    Backend unbind delay time : 0
    Thread Pool Size          : 32
    Anonym DAP Pool Size      : 5
    TCP/IP Response Mode      : 24
    Black Box Size            : 0
    DN Escape Mode            : backslash
    Search Size Limit         : 0
    Search Time Limit         : 0
    Supported Controls        : PR SSS SUBE PP
    Allowed IPs               : all
    Denied IPs                : none
Total Infos:
    Operations                : 5029
    Cache Hit Ratio           : 64%
    PDU Errors                : 10
    Client Shutdowns          : 10
    Referral errors           : 0
    SSL Connections           : 0
    SSL Errors                : 0
    Binds                     : 30
    Bind Errors               : 0
      Binds V2                : 29
      Binds V3                : 1
      Binds anonym            : 6
      Binds simple            : 24
      Binds strong            : 0
    Unbinds                   : 20
    Searches                  : 4969
    Search Errors             : 0
      Searched Entries        : 8156
      Searched Attrs          : 203887
      Searched Referrals      : 0
      Searches Baselevel      : 1
      Searches Onelevel       : 0
      Searches Subtree        : 4968
    Adds                      : 0
    Add Errors                : 0
    Modifys                   : 0
    Modify Errors             : 0
    Modify RDNs               : 0
    Modify RDN Errors         : 0
    Deletes                   : 0
    Delete Errors             : 0
    Compares                  : 0
    Compare Errors            : 0
    Abandons                  : 0
    Extended Ops              : 0
    Extended Ops Errors       : 0
    TCP Bytes sent            : 4406 KB
    TCP Bytes received        : 265 KB
    DSA dropouts              : 0
    RPC Operations            : 0
    Untrusted IP Binds        : 0
    Schema AT adds            : 0
    Schema AT deletes         : 0
    Schema OC adds            : 0
    Schema OC deletes         : 0
Current Infos:
    Cache Status              : ON (valid)
    Cache Hit Ratio           : 64%
    LDAP Conns                : 0
    LDAP Conns Max            : 10
    DAP  Conns                : 6
    DAP  Conns Max            : 13
    Pool Threads Running      : 0
    Pool Threads Idle         : 32
    Op Stack Size             : 0
    Op Stack Size Max         : 9
    Highest Descriptor        : 2216
    # of Sockets              : 3
    Socket(1)
      Fd                      : 2252
      Ip                      : Ldap Port
      Port                    : 0
      State                   : listening
    Socket(2)
      Fd                      : -1
      Ip                      : Ldap SSL Port
      Port                    : 0
      State                   : invalid
    Socket(3)
      Fd                      : 2248
      Ip                      : UDP Coord Port
      Port                    : 0
      State                   : listening

  2. The following sample command displays the LDAP port number in the MIB static table:

    ldap mib –static ldap_port

    The output of the sample command is as follows:

    389

  3. The following sample displays the MIB current table:

    ldap mib –current -pretty

    The output of the sample command is as follows:

    Current Infos:
    Cache Status         : ON (valid)
    Cache Hit Ratio      : 64%
    LDAP Conns           : 0
    LDAP Conns Max       : 10
    DAP  Conns           : 6
    DAP  Conns Max       : 13
    Pool Threads Running : 0
    Pool Threads Idle    : 32
    Op Stack Size        : 0
    Op Stack Size Max    : 9
    Highest Descriptor   : 2216
    # of Sockets         : 3
    Socket(1)
      Fd                 : 2252
      Ip                 : Ldap Port
      Port               : 0
      State              : listening
    Socket(2)
      Fd                 : -1
      Ip                 : Ldap SSL Port
      Port               : 0
      State              : invalid
    Socket(3)
      Fd                 : 2248
      Ip                 : UDP Coord Port
      Port               : 0
      State              : listening

  4. The following sample displays the MIB static table:

    ldap mib –static -pretty

    The output of the sample command is as follows:

    Static Infos: +
    Operating System          : MS Windows 2000 5.0 (Workstation) Build 2195 (Service Pack 4)
    Host Name                 : john02
    Host IP                   : 123.45.678.90
    CPUs                      : 1
    Total Phys Memory         : 1014 MB
    Avail Phys Memory         : 462 MB
    Pagesize                  : 4096 Bytes
    Max Open Files soft       : unlimited
    Max Open Files hard       : unlimited
    Server Version            : DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit
    Server Type               : Frontend Server
    Server Mode               : Read/Write
    Backend Sharing           : enabled
    Contact DSA               : TS=DSA1,NA='TCP/IP_IDM!internet=127.0.0.1+port=21200'
    Anonymous Allowed         : yes
    SSL Encryption            : strong SSL
    Start Time                : Thu Jun 17 09:37:32 2004
    Current Time              : Thu Jun 17 09:57:00 2004
    Configuration Name        : ldapConfiguration
    ClCfg File                : C:\Program Files\DirX\Directory\ldap\conf\dirxldap.cfg
    PID                       : 2020
    Ldap Port                 : 8080
    SSL Port                  : 0
    RPC Port                  : 6999
    Max Conn                  : 1024
    Client Idle Time          : 1000
    Backend unbind delay time : 0
    Thread Pool Size          : 32
    Anonym DAP Pool Size      : 5
    TCP/IP Response Mode      : 24
    Black Box Size            : 0
    DN Escape Mode            : backslash
    Search Size Limit         : 0
    Search Time Limit         : 0
    Supported Controls        : PR SSS SUBE PP
    Allowed IPs               : all
    Denied IPs                : none

  5. The following sample displays the MIB total table:

    ldap mib –total -pretty

    The output of the sample command is as follows:

    Total Infos:
    Operations           : 5029
    Cache Hit Ratio      : 64%
    PDU Errors           : 10
    Client Shutdowns     : 10
    Referral errors      : 0
    SSL Connections      : 0
    SSL Errors           : 0
    Binds                : 30
    Bind Errors          : 0
      Binds V2           : 29
      Binds V3           : 1
      Binds anonym       : 6
      Binds simple       : 24
      Binds strong       : 0
    Unbinds              : 20
    Searches             : 4969
    Search Errors        : 0
      Searched Entries   : 8156
      Searched Attrs     : 203887
      Searched Referrals : 0
      Searches Baselevel : 1
      Searches Onelevel  : 0
      Searches Subtree   : 4968
    Adds                 : 0
    Add Errors           : 0
    Modifys              : 0
    Modify Errors        : 0
    Modify RDNs          : 0
    Modify RDN Errors    : 0
    Deletes              : 0
    Delete Errors        : 0
    Compares             : 0
    Compare Errors       : 0
    Abandons             : 0
    Extended Ops         : 0
    Extended Ops Errors  : 0
    TCP Bytes sent       : 4406 KB
    TCP Bytes received   : 265 KB
    DSA dropouts         : 0
    RPC Operations       : 0
    Untrusted IP Binds   : 0
    Schema AT adds       : 0
    Schema AT deletes    : 0
    Schema OC adds       : 0
    Schema OC deletes    : 0
      Searches Onelevel  : 0
      Searches Subtree   : 4968
    Adds                 : 0
    Add Errors           : 0
    Modifys              : 0
    Modify Errors        : 0
    Modify RDNs          : 0
    Modify RDN Errors    : 0
    Deletes              : 0
    Delete Errors        : 0
    Compares             : 0
    Compare Errors       : 0
    Abandons             : 0
    Extended Ops         : 0
    Extended Ops Errors  : 0
    TCP Bytes sent       : 4406 KB
    TCP Bytes received   : 265 KB
    DSA dropouts         : 0
    RPC Operations       : 0
    Untrusted IP Binds   : 0
    Schema AT adds       : 0
    Schema AT deletes    : 0
    Schema OC adds       : 0
    Schema OC deletes    : 0

  6. The following sample displays the MIB association table:

    ldap mib –assoc -pretty

    The output of the sample command is as follows:

    Assoc Info:
    Current Time          : Thu Jun 17 10:00:50.787 2004
    # of DAP Connections  : 13 (anonym=5,simple=7,sasl=1)
    # of LDAP Connections : 9
    # of LDAP Operations  : 8
    [DAPCon#0]
      CreateTime          : Thu Jun 17 09:37:32 2004
      Info                : Type:sasl, Shares:1, Rebinds:0, Auth:Special DAP Bind
    [DAPCon#1]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Ghassan Izzo, ou=Product Development, o=my-company
    [DAPCon#2]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Salina Delf, ou=Human Resources, o=my-company
    [DAPCon#3]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Dania Ohashi, ou=Product Development, o=my-company
    [DAPCon#4]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Joann Windom, ou=Product Testing, o=my-company
    [DAPCon#5]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Onida Ferland, ou=Product Development, o=my-company
    [DAPCon#6]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Wayne Pon, ou=Product Testing, o=my-company
    [DAPCon#7]
      CreateTime          : Thu Jun 17 10:00:47 2004
      Info                : Type:simple, Shares:1, Rebinds:0, Auth:cn=Kat Mitalas, ou=Product Testing, o=my-company
    [LDAPCon#0]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 2036
      Bind-Type           : simple
      Security            : normal
      User                : cn=Kat Mitalas, ou=Product Testing, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 87
      Bytes in            : 4716
      Bytes out           : 77131
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.756 2004
        Duration          : 0.038469 sec
        OpName            : LDAP_Con188_Op86
        UniqueOpId        : 34957
        Inuse             : yes
        State             : A
        MessageID         : 87
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Abigale_McSorley)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#1]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 1968
      Bind-Type           : anonym
      Security            : normal
      User                :
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 88
      Bytes in            : 4713
      Bytes out           : 77927
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.772 2004
        Duration          : 0.017273 sec
        OpName            : LDAP_Con187_Op87
        UniqueOpId        : 34961
        Inuse             : yes
        State             : A
        MessageID         : 88
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Lynda_Mototsune)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#2]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 2044
      Bind-Type           : simple
      Security            : normal
      User                : cn=Salina Delf, ou=Human Resources, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 90
      Bytes in            : 4882
      Bytes out           : 79950
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.772 2004
        Duration          : 0.011930 sec
        OpName            : LDAP_Con186_Op89
        UniqueOpId        : 34963
        Inuse             : yes
        State             : A
        MessageID         : 90
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Allyce_Varkey)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#3]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 1768
      Bind-Type           : anonym
      Security            : normal
      User                :
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 93
      Bytes in            : 4981
      Bytes out           : 82887
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.772 2004
        Duration          : 0.009000 sec
        OpName            : LDAP_Con185_Op92
        UniqueOpId        : 34964
        Inuse             : yes
        State             : A
        MessageID         : 93
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Ruchel_Tihanyi)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#4]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 2080
      Bind-Type           : simple
      Security            : normal
      User                : cn=Ghassan Izzo, ou=Product Development, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 87
      Bytes in            : 4736
      Bytes out           : 77441
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.756 2004
        Duration          : 0.039108 sec
        OpName            : LDAP_Con184_Op86
        UniqueOpId        : 34956
        Inuse             : yes
        State             : A
        MessageID         : 87
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Ketty_Menon)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#5]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 1972
      Bind-Type           : simple
      Security            : normal
      User                : cn=Wayne Pon, ou=Product Testing, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 90
      Bytes in            : 4870
      Bytes out           : 79992
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.756 2004
        Duration          : 0.029731 sec
        OpName            : LDAP_Con183_Op89
        UniqueOpId        : 34958
        Inuse             : yes
        State             : A
        MessageID         : 90
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Annamaria_Lukas)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#6]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 1728
      Bind-Type           : simple
      Security            : normal
      User                : cn=Dania Ohashi, ou=Product Development, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 88
      Bytes in            : 4792
      Bytes out           : 78878
      Current Ops         : 0
    [LDAPCon#7]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 2028
      Bind-Type           : simple
      Security            : normal
      User                : cn=Onida Ferland, ou=Product Development, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 87
      Bytes in            : 4700
      Bytes out           : 76961
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.756 2004
        Duration          : 0.029600 sec
        OpName            : LDAP_Con181_Op86
        UniqueOpId        : 34959
        Inuse             : yes
        State             : A
        MessageID         : 87
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Ragui_Babyak)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never
    [LDAPCon#8]
      Peer-IP             : 127.0.0.1
      Socket-FD           : 1964
      Bind-Type           : simple
      Security            : normal
      User                : cn=Joann Windom, ou=Product Testing, o=my-company
      SASL-User-Id        :
      CreateTime          : Thu Jun 17 10:00:47 2004
      LastActivity        : Thu Jun 17 10:00:50 2004
      Version             : 2
      Processed Ops       : 91
      Bytes in            : 4943
      Bytes out           : 80815
      Current Ops         : 1
      [Op#0]
        CreateTime        : Thu Jun 17 10:00:50.756 2004
        Duration          : 0.028931 sec
        OpName            : LDAP_Con180_Op90
        UniqueOpId        : 34960
        Inuse             : yes
        State             : A
        MessageID         : 91
        OpType            : SEARCH
        BaseObj           : o=my-company
        Scope             : subtree
        Filter            : (uid=Choon-Lin_Haroutounian)
        SizeLimit         : 0
        TimeLimit         : 30
        TypesOnly         : no
        DerefAlias        : never

ldap nolog

Stops LDAP server diagnostic logging. The syntax is as follows:

  • ldap nolog

LDAP server logging is initially controlled by the specifications in the configuration file install_path*/ldap/conf/dirxlog.cfg*. When an ldap nolog operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path*/ldap/conf/dirxlog.off*. To use these specifications when restarting the LDAP server, edit the file install_path*/ldap/conf/dirxlog.cfg* according to the settings in install_path*/ldap/conf/dirxlog.off*. By default, the log files are written to the directory install_path*/ldap/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

Example
ldap nolog

ldap operations

Returns a list of operations that can be performed on the ldap object. The syntax is as follows:

  • ldap operations

The list of available operations is in alphabetical order, except for help and operations, which are listed last.

Example
ldap operations

The output of the sample command follows:

audit binding cache log mib nolog restart help operations

ldap restart

Stops and restarts the LDAP server.

This operation must be performed to update the LDAP server configuration after the corresponding subentry or the schema has been modified. Note that the re-load process disconnects all LDAP client connections and causes the server to re-read the directory schema.

The syntax is as follows:

  • ldap restart

Example
ldap restart

lob (dirxadm)

Synopsis

lob create
    -agreement agreement
    [-agreementid agreementid]
    [-pol sob_policies]
    -status coop_status
    [-supplier dsa_name]
    [-supplierpsap psap_address]

lob delete
    -agreementid agreementid
    [-supplier dsa_name]

lob disable _
    -agreementid agreementid
    [-supplier dsa_name]

lob enable
    -agreementid agreementid
    [-supplier dsa_name]

lob establish
    -agreementid agreementid
    [-supplier dsa_name]

lob help [operation | -verbose]

lob operations

lob show
    [-agreementid agreementid]
    [-supplier dsa_name]
    [-pretty]

lob terminate
    -agreementid agreementid
    [-supplier dsa_name]

Purpose

A dirxadm object that manages LDIF agreements.

Arguments

operation

  • The name of the lob operation for which to display help information

Operations

lob create

Creates an LDIF agreement. The syntax is as follows:

  • lob create
        -agreement     agreement
        [-agreementid agreementid]
        [-pol sob_policies]
        -status coop_status
        [-supplier dsa_name]
        [-supplierpsap psap_address]

Options

-agreement agreement

  • A required option that specifies the LDIF agreement. Specify agreement in the Shadowing-Agreement-Info structured attribute syntax. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax.

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version.

    + The value for id must be between 1 and 9999. Values greater than 9999 are reserved for internal purposes. The DSA manages agreements with an id greater than 9999 automatically; it is prohibited to administer these agreements manually.

    + For the option -status STANDALONE this option is required. Specify a unique id. Note that the DSA does not check the uniqueness of the agreement id.

    + The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-pol sob_policies

  • Specifies the policies used for the LDIF agreement. Specify sob_policies in the SOB-Policies structured attribute syntax. For LDIF agreements only the components SUPP (sub-component MAXLOC) and LDSUPP are relevant. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax.

-status coop_status

  • A required option that specifies how the LDIF agreement are to cooperate. The coop_status argument consists of one of the following keywords:

    • COOPERATIVE - Indicates that the LDIF agreement is activated as part of the create operation.

    • NONCOOPERATIVE - Indicates that the LDIF agreement is not activated.

    • STANDALONE - Indicates that an LDIF content file of the bind DSA database is written immediately without creating an LDIF agreement.

    Use the lob establish operation to activate an LDIF agreement (to change from NONCOOPERATIVE to COOPERATIVE status). Use the lob terminate operation to deactivate an LDIF agreement (to change from COOPERATIVE to NONCOOPERATIVE status).

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-supplierpsap psap_address

  • Specifies the PSAP address of the supplier DSA. The specified value will be written to the corresponding DSA entry. Do not specify the PSAP address when this attribute already exists in the corresponding DSA entry. See the Presentation-Address syntax in DirX Directory Syntaxes and Attributes for a description of PSAP address format.

The create operation creates an LDIF agreement. The DSAs participating in LDIF agreements must have compatible system schemata. All LDIF agreements must be administered on the DSA that is the master of the cooperating DSAs subentry. (See Cooperating DSA in chapter titled DirX Directory Attributes in DirX Directory Syntaxes and Attributes for details.)

Use LDIF agreements to save parts of the DIT and modifications to them to local files. The data is saved in LDIF format, which is a printable file format. The files are saved in the directory install_path*/server/ldif*. The filename is agreementid[Standalone].*timestamp. The agreementid is used without the version. (See option *-agreementid for details.) The string Standalone is appended to the agreementid if the option -status STANDALONE was specified. The timestamp indicates the time when the DSA started to write the file.

You can control the size of the files by setting the DirX Directory environment variable DIRX_LDIF_SPLIT. You can export the files by moving them to an appropriate directory. If the file does not yet exist, poll for the filename. Note that the character p at the end of the filename indicates that the creation of the file is not yet finished.

You can pass the LDIF file to a specified external program. (See PROG component of LDSUPP component of SOB-Policies structured attribute syntax in DirX Directory Syntaxes and Attributes for details.) In this case it is not necessary to poll for the LDIF file or to check the p at the end of the filename. The operation passes the complete LDIF file to the external program. This file may have a p at the end of the filename but is complete. The external program takes over responsibility for the file. It is not available in the install_path*/server/ldif* directory after finishing or aborting the external program.

LDIF files may be useful for example to synchronize two different DSAs offline or to roll back a DSA. You can import the content of LDIF files to DirX Directory DSAs with the dirxmodify or dirxload command. When you want to import the saved data to non-DirX Directory DSAs or to LDAP servers, the LDIF file format supplies an easy-to-use format to write procedures that read the data and save them in that server. Passing the LDIF file to an external program gives you a means to parse the changes and to decide on further actions, for example propagating the changes to other directories.

If the create operation is performed with -status STANDALONE no further command is needed to activate, terminate or delete the agreement. The DSA does not create an LDIF agreement at all. It starts to write the specified replication area to an LDIF content file immediately. If the DSA was not set to read only before issuing this operation updates performed while this operation is in progress may not be reflected in the LDIF content file. (See the dirxadm sys opmode operation how to set the DSA to read only.) Unlike all other create operations this operation can also performed on DSAs that are not the master of the cooperating DSAs subentry.

Although it is required for the delete, disable, enable, establish, and terminate operations, the
-agreementid option is optional for the create operation, unless the option -status STANDALONE was specified. If you do not supply it, the create operation supplies one. If you specify an agreement ID that exists within another LDIF or shadowing agreement, the create operation returns an error, unless the option -status STANDALONE was specified.

The –supplierpsap option is required if there are no operational bindings within the specified DSAs. If operational bindings exist and a PSAP address is specified, the existing value is overwritten.

Example

  1. The following example creates an LDIF agreement with an LDIF-Supplier-SOB-Policy. The agreement is in the status NONCOOPERATIVE. The agreement can be activated by performing a lob establish operation.

    lob create \
       -status noncooperative       \
       -agreementid 100      \
       -supplier \{/cn=DirX-DSA-host1} \
       -pol \{LDSUPP=\{CRLF=TRUE,DELAT=TRUE}} \
       -agreement \{SS=\{AREA=\{CP=\{/O=My-Company}, \
                             RA=\{BAS=\{/OU=Sales} \
                                } \
                            }, \
                       KNO=\{EK=TRUE,KT=MASTER}, \
                       ATT=\{CA=\{ALL=TRUE}} \
                      }, \
                    UM=\{SI=\{S=\{PS=\{ WS=900, \
                                   UI=86400 \
                                  } \
                              } \
                           } \
                       }     \
                   }

  2. The following example creates an LDIF agreement on on-change basis. The LDIF file is passed to an external program:

    lob create  \
          -status noncooperative \
          -agreementid 12 \
          -supplier \{/cn=DirX-DSA-host1} \
          -agreement \
             \{SS=\{AREA=\{CP=\{/O=Air.com},RA=\{DEF=TRUE}},
                        ATT=\{DEF=TRUE}},
                 UM=\{SI=\{OC=TRUE}}} \
          -pol \{LDSUPP=\{ENTRYO=TRUE,
PROG='"C:\\\Multimedia Files\\\temp\\\trigger.bat" %F %U %L %S'}}

  3. The following example performs a standalone LDIF agreement. The DSA dumps all entries under the root (the total database content) to an LDIF content file without creating an LDIF agreement at all. The name of the resulting LDIF content file is *0000000011Standalone.*timestamp:

    lob create                                            \
          -status STANDALONE                          \
          -agreementid 11                             \
          -agreement \{SS=\{AREA=\{CP=\{/},RA=\{DEF=TRUE}},
                          ATT=\{DEF=TRUE}},
                      UM=\{SI=\{OC=TRUE}}}              \
          -pol \{SUPP=\{MAXLOC=128},
                LDSUPP=\{ENTRYO=FALSE,CS=UTF8}
          }

lob delete

Deletes an LDIF agreement. The syntax is as follows:

  • lob delete
        -agreementid agreementid
        [-supplier dsa_name]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

The delete operation removes an LDIF agreement. Before performing the lob delete operation it is recommended to deactivate the agreement with lob terminate. (See the lob terminate operation for details.)

Example
lob delete -supplier /cn=DirX-DSA-host1 \
           -agreementid 8

lob disable

Disables the execution of an LDIF agreement. This operation can only be performed on agreements with the status COOPERATIVE. The syntax is as follows:

  • lob disable
        -agreementid agreementid
        [-supplier _dsa_name    ]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

The disable operation disables the execution of an LDIF agreement. This operation can only be performed on agreements with the status COOPERATIVE. The status COOPERATIVE is not changed. Use the lob enable operation to activate the LDIF agreement. Then the supplier DSA saves incremental updates to the local LDIF file.

Example

lob disable -supplier /cn=DirX-DSA-host1 \
            -agreementid 8

lob enable

Enables the execution of an LDIF agreement which has been disabled by the DSA internally (e.g., because of previous recovery problems), or by the lob disable operation. This operation can only be performed on agreements with the status COOPERATIVE. The syntax is as follows:

  • lob enable
        -agreementid agreementid
        [-supplier dsa_name]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

The enable operation enables the execution of an LDIF agreement which has been disabled by the DSA internally (e.g., because of previous recovery problems), or by the lob disable operation. The supplier DSA saves incremental updates to the local LDIF file. This operation can only be performed on agreements with the status COOPERATIVE.

Example
lob enable -supplier /cn=DirX-DSA-host1 \
           -agreementid 8

lob establish

Changes the status of an operational binding to COOPERATIVE. The syntax is as follows:

  • lob establish
        -agreementid agreementid
        [-supplier dsa_name]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

The establish operation changes the status of an existing LDIF agreement to COOPERATIVE. It increases the version of the agreement by 1. (See the -agreementid option for details.) Use this operation to activate an LDIF agreement. The supplier DSA saves a local file in LDIF format.

Example
lob establish -supplier /cn=DirX-DSA-host1 \
              -agreementid 8

lob help

Returns help information about the lob object and its operations. The syntax is as follows:

  • lob help [operation | -verbose]

Options

-verbose

  • Displays information about the lob object.

Used without an argument or option, the help command returns brief information about each lob operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the lob object itself.

Example
lob help

The output of the sample command follows:

create

Creates an LDIF agreement.

delete

Deletes an LDIF agreement.

disable

Disables an LDIF agreement.

enable

Enables an LDIF agreement.

establish

Activates an LDIF agreement.

show

Displays an entry of an LDIF agreement.

terminate

Deactivates an LDIF agreement.

help

Displays the help text for the “lob” object and its operations.

operations

Lists the operations that can be performed on the “lob” object.

lob operations

Returns a list of operations that can be performed on the lob object. The syntax is as follows:

  • lob operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example
lob operations

The output of the sample command follows:

create delete disable enable establish show terminate help operations

lob show

Displays a DSA’s LDIF agreements. The syntax is as follows:

  • lob show
        [-agreementid agreementid]
        [-supplier dsa_name]
        [-pretty]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-pretty

  • Displays the results of the operation in a tabular format

The show operation displays the LDIF agreements that have been created for a DSA. When used without options, the operation returns the complete distinguished names of all supplier DSAs.

The following information is displayed:

  • Binding state—The status of the LDIF agreement (for example COOPERATIVE). (See OBS component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Validity—The time period during which the LDIF agreement is valid. (See -validity option of the dirxadm lob create command for details.)

  • Agreement—The information about the LDIF agreement. (See SAI component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Policies—The policies to be performed for the LDIF agreement. (See RPOL subcomponent of the SAI component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Update status—The update status of the LDIF agreement. (See Update-Status structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

Use the -supplier option alone to return all existing LDIF agreements within the specified DSA.

By default, the results of the show operation are displayed as a Tcl list; use the -pretty option to return the results in a tabular, more readable format.

Example

The following command displays the LDIF agreement with agreement ID 14057,3 in pretty format:

lob show -agreementid 14057 \
         -supplier \{/cn=DirX-DSA-host1} -p

The output of the sample command follows:

Validity-Agreement
    Operational-Binding-State : COOPERATIVE
OprBindMngmnt-Validity
  Validity-From               : 030228095720Z
Agreement
Shadow-Subject
Area-Specification
  Context-Prefix              : /O_DUTF8=My-Company
Replication-Area
  Subtree-Base                : /
Attribute-Selection
  Default-Value               : TRUE
Update-Mode
Supplier-Initiated
Scheduled
Periodic-Strategy
  Window-Size                 : 1000
  Update-Interval             : 1
Update-Status
  Disabled                    : FALSE
Update-Status
Supplier-Update-Status
  Area-Change-State           : CHANGED
Old-Updates
  Segment-ID                  : 8
  Update-Time                 : 20030311081115Z
  Area-Changes                : TRUE
Related-Policies
LDIF-Supplier
  Binary-Only-For             : NONE
  Max-Characters-per-Row      : 200
  Code-Set                    : UTF8
  Changes-Only                : FALSE

lob terminate

Changes the status of an LDIF agreement to NONCOOPERATIVE (deactivates saving data to a local file in LDIF format). The syntax is as follows:

  • lob terminate
        -agreementid agreementid
        [-supplier dsa_name]

Options

-agreementid agreementid

  • Specifies the LDIF agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm lob create); each time the agreement is established (with dirxadm lob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the supplier DSA of the LDIF agreement, that is the DSA writing the LDIF files. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

The terminate operation changes the status of an existing LDIF agreement to NONCOOPERATIVE. Use this operation to deactivate saving data to a local file in LDIF format. Use the lob establish operation to activate the LDIF agreement.

Example
lob terminate -supplier /cn=DirX-DSA-host1 \
              -agreementid 8

nmi (dirxadm)

Synopsis

nmi help [operation | -verbose]

nmi operations

nmi show
    [-mib mib_name [-table table_name]]
    [-pretty]

Purpose

A dirxadm object that manages the directory service MIBs.

Arguments

operation

  • The name of the nmi operation for which to display help information.

Operations

nmi help

Returns help information about the nmi object and its operations. The syntax is as follows:

nmi help [operation | -verbose]

Options

-verbose

  • Displays information about the nmi object.

Used without an argument or option, the help command returns brief information about each nmi operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the nmi object itself.

Example
nmi help

The command output is as follows:

show

Displays the details of the Management Information Base tables.

help

Displays the help text for the “nmi” object and its operations.

operations

Lists the operations that can be performed on the “nmi” object.

nmi operations

Returns a list of operations that can be performed on the nmi object. The syntax is as follows:

  • nmi operations

The list of available operations is in alphabetical order, except for help and operations, which are listed last.

Example
nmi operations

The command output is as follows:

show help operations

nmi show

Shows the directory MIBs. The syntax is as follows:

  • nmi show
        [-mib mib_name [-table table_name]]
        [-pretty]

Options

-mib mib_name

  • Specifies the name of the MIB to be displayed. Supply one of the following values as the MIB name:

    APP

    for the Application MIB. See RFC 1565 for a definition of the Application MIB (also called the Network Services Monitoring MIB).

    DSA

    for the DSA MIB. See RFC 1567 for a definition of the DSA MIB (also called the X.500 Directory Monitoring MIB).

-table table_name

  • Specifies the name of a MIB table. Supply one of the following values as the table name:

    • ASSOCIATION - Application MIB association table

    • APPLICATION - Application MIB application table

    • ENTRIES - DSA MIB entries table

    • INTERACTION - DSA MIB interaction table

    • OPERATIONS - DSA MIB operations table

-pretty

  • Displays the results of the operation in a tabular format

When used without options, the show operation displays the information in all MIB tables. Use the -mib option to display the tables associated with a specific MIB.

Use the -tables option to display a specific MIB table. If the -table option is not specified, the operation displays all tables associated with the specified MIB.

If the -tables option is specified, the -mib option is also required.

By default, the results of the operation are returned in Tcl lists. Use the -pretty option to return the results in a tabular, more readable format.

Note that you can also use the LDAP extended operations for DirX Directory MIB display available through the dirxextop command and the DirX Directory Manager’s Monitor view.

Examples
nmi show -pretty

The command output is as follows:

Entries table of the DSA MIB
    Master entries                    52
    Copy entries                      30
    Cache entries                     21
    Cache hits                        5
    Slave hits                        13
Interaction table of the DSA MIB
    Interaction index                 0
    DSA name                          /C=RE/O=IBM/CN=IBM-DSA
    Time of creation                  Wed Mar 19 09:56:26 1997
    Time of last attempt              Wed Mar 19 09:59:09 1997
    Time of last success              Wed Mar 19 09:58:33 1997
    Failures                          3
    Failures since last success       3
    Successes                         12
Operations table of the DSA MIB
    Anonymous binds                   6
    Unauthenticated binds             0
    Simple authenticated binds        10
    Strong authenticated binds        0
    Bind security errors              0
    Inbound operations                16
    Read operations                   6
    Compare operations                0
    Add entry operations              0
    Remove entry operations           0
    Modify entry operations           0
    Modify RDN operations             0
    List operations                   0
    Search operations                 0
    One-level search operations       0
    Whole-subtree search operations   0
    Referrals returned                3
    Chainings forwarded               12
    Security errors                   4
    DSA errors                        2
Association table of the application MIB
    Association index                 28
    Remote application name           /
    Application protocol              DAP
    Application type                  ua-responder
    Association duration              Wed Mar 19 10:23:24 1997
Application table of the application MIB
    Index                             0
    Name                              DirX
    DirName                           /C=RE/CN=SNI-DSA
    Version                           7.4.147 2005:01:23 20:10
    Uptime                            Wed Mar 19 09:45:15 1997
    Operational status                UP
    Last change                       NEVER
    Inbound associations              1
    Outbound associations             0
    Accumulated in-associations       16
    Accumulated out-associations      12
    Last inbound activity             Wed Mar 19 10:23:24 1997
    Last outbound activity            Wed Mar 19 09:58:33 1997
    Rejected inbound associations     0
    Failed outbound associations      3

progsvr (dirxadm)

Synopsis

progsvr binding [-host hostname] [-port portnumber]

progsvr help [operation | -verbose]

progsvr log

progsvr nolog

Purpose

A dirxadm object that manages the Progsvr. (See DirX Directory Progsvr in the DirX Directory Introduction.) It is not necessary to perform a dse bind operation before performing progsvr operations.

Arguments

operation

  • The name of the progsvr operation for which to display help information.

Operations

progsvr binding

Specifies the Progsvr to be administered. This operation must be performed when administering a remote Progsvr. To administer a remote Progsvr the -host option must be specified. The syntax is as follows:

progsvr binding [-host hostname] [-port portnumber]

Options

-host hostname

  • The hostname or IP address of the machine hosting the Progsvr to be administered. The default is localhost.

-port portnumber

  • The RPC port number of the Progsvr.

Example
progsvr binding -host 123.456.78.99 -port 6666

progsvr help

Returns help information about the progsvr object and its operations. The syntax is as follows:

  • progsvr help [operation | -verbose]

Options

-verbose

  • Displays information about the progsvr object.

Used without an argument or option, the progsvr help operation returns brief information about each progsvr operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the progsvr object itself.

Example
progsvr help

The output of the sample command follows:

binding

Sets the PROGSVR Server to be administered.

log

Switches on the diagnostic logging.

nolog

Switches off the diagnostic logging.

help

Displays the help text for the “progsvr” object and its operations.

progsvr log

Starts Progsvr diagnostic logging. The syntax is as follows:

  • progsvr log

Progsvr logging is initially controlled by the specifications in the configuration file install_path*/progsvr/conf/dirxlog.cfg*. When a progsvr log operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path*/progsvr/conf/dirxlog.on*. To use these specifications when restarting the Progsvr, edit the file install_path*/progsvr/conf/dirxlog.cfg* according to the settings in install_path*/progsvr/conf/dirxlog.on*. By default, the log files are written to the directory install_path*/progsvr/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

When the environment variable DIRX_LOGCFG_FILE (see chapter titled DirX Directory Environment Variables for details) is set, logging is controlled by the specifications in this file.

Example
progsvr log

progsvr nolog

Stops progsvr diagnostic logging. The syntax is as follows:

  • progsvr nolog

Progsvr logging is initially controlled by the specifications in the configuration file install_path*/progsvr/conf/dirxlog.cfg*. When a progsvr nolog operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path*/progsvr/conf/dirxlog.off*. To use these specifications when restarting the Progsvr, edit the file install_path*/progsvr/conf/dirxlog.cfg* according to the settings in install_path*/progsvr/conf/dirxlog.off*. By default, the log files are written to the directory install_path*/progsvr/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

Example
progsvr nolog

sob (dirxadm)

Synopsis

sob create
    [-agreement agreement]
    [-agreementid agreementid]
    [-supplier dsa_name]
    [-supplierkind X500]
    [-supplierpsap psap_address]
    [-supplierprotocol protocol_information]
    -consumer dsa_name
    -consumerkind disp_kind
    [-consumerpsap _psap_address]
    [-consumerprotocol protocol_information]
    -status coop_status
    [-pol sob_policies]
    [-validity validity]

sob delete
    -agreementid agreementid
    [-supplier dsa_name]
    -consumer dsa_name

sob disable
    -agreementid agreementid
    [-supplier dsa_name]
    -consumer dsa_name

sob enable
    -agreementid agreementid
    [-supplier dsa_name]
    -consumer dsa_name

sob establish
    -agreementid agreementid
    [-supplier dsa_name]
    -consumer dsa_name

sob help [operation | -verbose]

sob operations

sob show
    [-agreementid agreementid]
    [-supplier dsa_name]
    [-consumer dsa_name]
    [-pretty]

sob switch
    {-from dsa_name
    -to dsa_name |
    -emergency}

sob synchronize
    [-consumer dsa_name [-agreementID agreementidt]]

sob terminate
    -agreementid agreementid
    [-supplier dsa_name]
    -consumer dsa_name

Purpose

A dirxadm object that manages shadowing operational bindings between DSAs.

Arguments

operation

The name of the *sob operation for which to display help information

Operations

sob create

Creates a shadowing agreement between two DSAs. The syntax is as follows:

  • sob create
        [-agreement agreement]
        [-agreementid agreementid]
        [-supplier dsa_name]
        [-supplierkind X500]
        [-supplierpsap psap_address]
        [-supplierprotocol protocol_information]
        -consumer dsa_name
        -consumerkind disp_kind
        [-consumerpsap _psap_address    ]
        [-consumerprotocol protocol_information]
        -status coop_status
        [-pol sob_policies]
        [-validity validity]

Options

-agreement agreement

  • A required option for asynchronous shadowing (consumerkind value of CENTRALADMIN or X500) that specifies the shadowing agreement. Specify agreement in the Shadowing-Agreement-Info structured attribute syntax. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax. Typically this option is not required for synchronous shadowing (consumerkind value of SYNCHRON) because the master DSA’s complete DIT (all entries, all attributes) is always replicated and always on change. However, if you intend to specify a total update by media, then CHANGEO=TRUE must be specified.

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version.

    The value for id must be between 1 and 9999. Values greater than 9999 are reserved for internal use; for example, the replication of the cooperating DSA table. The DSA manages agreements with an id greater than 9999 automatically; do not administer these agreements manually.

    The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for display purposes.

-supplier dsa_name

  • Specifies the name of the DSA that is sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-supplierkind X500

  • Only specified if the DSA is part of an X.500-compliant shadowing configuration as a consumer. The DSA participates in a heterogeneous network of DirX Directory DSAs and other DSAs that support X.500-compliant shadowing. The administrators must manage the shadowing agreements on each participating DSA. This value can only be specified in a shadowing agreement on a consumer DSA that takes part in X.500-compliant shadowing.

-supplierpsap psap_address

  • Specifies the PSAP address of the supplier DSA. The specified value is written to the corresponding DSA entry. Do not specify this option when the PSAP attribute already exists in the corresponding DSA entry. See the Presentation-Address syntax in DirX Directory Syntaxes and Attributes for a description of PSAP address format.

-supplierprotocol protocol_information

  • Specifies the sequence of OIDs that identify the lower communication layers supported by the supplier DSA. Specify protocol_information in the ProtocolInformation structured attribute syntax. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax.

-consumer dsa_name

  • A required option that specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

-consumerkind disp_kind

  • A required option that specifies the type of DISP network in which the DSA participates: DirX Directory-compliant/asynchronous shadowing, DirX Directory-compliant/synchronous shadowing or X.500-compliant shadowing configuration. The disp_kind argument consists of one of the following keywords:

    • CENTRALADMIN—The DSA participates in a DirX Directory-compliant configuration that uses asynchronous shadowing protocol (version 7.0B00 and newer). A DirX Directory-compliant configuration consists of a homogeneous network of DirX Directory DSAs, in which a single DSA masters a centralized cooperating DSA table of shadowing agreements for the DSAs in the network and automatically propagates changes to this table to all participating consumer DSAs over DISP. In asynchronous shadowing, replication areas of the DIT can be configured and LDAP/DAP client update requests are returned immediately after they are committed by the master DSA.

    • SYNCHRON—The DSA participates in a DirX Directory-compliant configuration that uses synchronous shadowing protocol (version 8.2B00 and newer). In synchronous shadowing, the entire DIT is replicated “on change” and LDAP/DAP client update requests are returned only after they are committed by the master DSA and by all synchronous-configured consumer DSAs in the network.

    • X500—The DSA participates in a heterogeneous network of DirX Directory DSAs and other DSAs that support X.500-compliant shadowing as a supplier. The administrators must manage the shadowing agreements on each participating DSA. We recommend that you set the environment variable DIRX_X500_MODIFY; see the chapter Environment Variables for details. The X500 value can only be specified in a shadowing agreement on a supplier DSA that participates in X.500-compliant shadowing.

    This option is mandatory unless you create a shadowing agreement on a consumer DSA participating on a X.500-compliant shadowing or the attribute already exists in the corresponding DSA entry.

-consumerpsap psap_address

  • Specifies the PSAP address of the consumer DSA. The specified value is written to the corresponding DSA entry. Do not specify this option when the PSAP attribute already exists in the corresponding DSA entry. See the Presentation-Address syntax in DirX Directory Syntaxes and Attributes for a description of PSAP address format.

-consumerprotocol protocol_information

  • Specifies the sequence of OIDs that identify the lower communication layers supported by the consumer DSA. Specify protocol_information in the ProtocolInformation structured attribute syntax. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax.

-status coop_status

  • A required option that specifies how the DSAs are to cooperate. The coop_status argument consists of one of the following keywords:

    • COOPERATIVE—Indicates that the shadowing agreement is activated as part of the create operation.

    • NONCOOPERATIVE—Indicates that the shadowing agreement is not activated.

    Use the sob establish operation to activate a shadowing agreement (to change from NONCOOPERATIVE to COOPERATIVE status). Use the sob terminate operation to deactivate a shadowing agreement (to change from COOPERATIVE to NONCOOPERATIVE status).

-pol sob_policies

  • Specifies the policies used for the shadowing agreement. Specify sob_policies in the SOB-Policies structured attribute syntax. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax.

-validity validity

  • Specifies the time period during which the shadowing agreement is valid. Use the following format for the validity argument:

    • VF=valid_from, VU=valid_until

    where valid_from is the keyword NOW or a time and valid_until is the keyword TERMINATION or a time. Specify time values in Generalized Time attribute syntax; see DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of this syntax. The default values are NOW and TERMINATION.

The create operation creates a shadowing agreement between two DSAs. All shadowing agreements must be administered on the DSA that is the master of the cooperating DSAs subentry. (See the Cooperating DSA section in the DirX Directory Attributes chapter in DirX Directory Syntaxes and Attributes for details.)

When a DSA participates in a shadowing agreement, the DSA that masters the cooperating DSA table automatically creates the agreement and then propagates the cooperating DSA table to this DSA.

Although it is required for the delete, disable, enable, establish, and terminate operations, the -agreementid option is optional for the create operation. If you do not supply it, the create operation supplies one. If you specify an agreement ID that exists within another operational binding, the create operation returns an error.

The -supplierpsap and the -consumerpsap options are required if there are no operational bindings within the specified DSAs. If operational bindings exist and a PSAP address is specified, the existing value is overwritten.

Use the COOPERATIVE keyword in the -status option to activate shadowing with the partner DSA. Changing status to COOPERATIVE initiates DISP communication with the partner DSA, which permits shadow entries to be created.

By default, a shadowing agreement is valid from the time it is established, either with sob create, if -status COOPERATIVE is specified, or with sob establish until the time it is explicitly terminated with sob terminate. Use the -validity option to set a specific time limit for the agreement.

You may want to create a stand-by shadow: a DSA that contains a complete shadow of the DIT and can therefore assume the role of the master DSA in the event that the master breaks down. See the dirxadm sob switch operation and the section Switching Supplier DSAs in a Shadow Configuration in the chapter Creating a Shadow DSA in the Administration Guide for details. To keep a stand-by DSA’s data as up to date as possible, the replicated entries must be updated immediately after they are created or modified. (This action is the default. See Shadowing-Agreement-Info attribute syntax in DirX Directory Syntaxes and Attributes for details.) The REPLS subcomponent of the consumer policy must also be set to TRUE. See the SOB-Policies syntax in chapter titled DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for details.

You also need to decide whether to use asynchronous (CENTRALADMIN) or synchronous (SYNCHRON) shadowing.

In asynchronous shadowing, an LDAP/DAP client’s update operation returns immediately after the master DSA commits the operation and writes it to the journal. If the master DSA fails, this protocol can lead to loss of recent update operations at the consumer DSAs. Asynchronous shadowing allows a high rate of update operations between supplier and consumer DSAs and fast response time for LDAP/DAP clients, and provides full flexibility for defining the replication area.

In synchronous shadowing, an LDAP/DAP client’s update operation does not return until the master DSA and all synchronous consumer DSAs have committed the operation. If the master DSA fails, acknowledged update operations to the DAP/LDAP client are safely stored at the synchronous consumer DSAs and there is no data loss. Synchronous shadowing provides for high data integrity between master and shadow DSAs even in the event of a master failure, but supports a lower rate of update operations between supplier and consumer DSAs and slower response time for LDAP/DAP clients. It also replicates the complete DIT with one agreement without any options for customizing the replicated area, and the REPLS subcomponent must be set to TRUE.

Both asynchronous and synchronous shadowing allow for total updates via media or DISP.

You can mix asynchronous (CENTRALADMIN) and synchronous (SYNCHRON) shadowing agreements as long as different consumer DSAs are affected and the REPLS subcomponent of the asynchronous (CENTRALADMIN) agreement is always FALSE.

If the unique attribute type value constrains check is enabled, the -consumerkind option is CENTRALADMIN or SYNCHRON and the REPLS subcomponent of the consumer policy is TRUE, the consumer DSA must be online at shadow agreement creation time. The supplier DSA compares the unique constraint configuration against the consumer DSA for consistency. The unique index configuration on a consumer DSA must never exceed the supplier DSA’s configuration (a unique constraint setting for an attribute type must also be set on the supplier DSA; however, a unique constraint can be set on supplier DSA and not on the consumer DSA). The unique constraint configuration must be identical at switch time on both supplier and consumer DSA. If unique constraint checks are applied, they must be functionally compatible and the supplier and consumer DSAs must be DirX Directory v8.2 or newer.

Example

  1. In the following example, the administrator creates a shadowing agreement with central administration on the master DSA of the cooperating DSA table:

    sob create -supplier {/cn=DirX-DSA-host1}                          \
           -supplierpsap "TS=DSAUP,NA='TCP/IP!internet=123.26.171.123+port=21100'"          \
           -consumer {/cn=DirX-DSA-host2}                          \
           -consumerkind CENTRALADMIN                              \
           -consumerpsap "TS=DSALI,NA='TCP/IP!internet=134.27.161.145+port=21100'"          \
           -agreementid 5                                          \
           -status noncooperative                                  \
           -agreement "SS={AREA={CP={/O=My-Company01},             \
                           RA={BAS={/}}},                          \
                           ATT={DEF=TRUE}},                        \
               UM={SI={S={PS={WS=1000,UI=1,BT=20030101000000Z}}}}"

  2. In the following example, the administrator creates shadowing agreements in an X.500 DISP environment. He must create one agreement on the supplier DSA and one agreement on the consumer DSA. Here is the agreement on the supplier DSA:

    sob create                                                 \
           -consumerkind X500                              \
           -consumer     {/cn=DirX-DSA-host2}              \
           -consumerpsap "TS=DSALI,NA='TCP/IP!internet=134.27.161.145+port=21100'"  \
           -agreementid 5                                  \
           -status cooperative                             \
           -agreement {SS={AREA={CP={/O=My-Company01},
                                 RA={DEF=TRUE}
                                },
                           ATT={DEF=TRUE}
                          },
                       UM={SI={OC=TRUE}},
                       CHANGEO=FALSE
                      }                                    \
           -pol {SUPP={US=TOTAL-INCR,MAXLOC=0},
                 CONS={US=TOTAL-INCR,REPLS=FALSE},
                 INI={RI=90,ATU=FALSE}
                }

    Here is the agreement on the consumer DSA:+

    sob create                                                  \
           -supplierkind X500                               \
           -supplier     {/cn=DirX-DSA-host1}               \
           -supplierpsap "TS=DSAUP,NA='TCP/IP!internet=123.26.171.123+port=21100'"   \
           -consumer     {/cn=DirX-DSA-host2}               \
           -consumerpsap "TS=DSALI,NA='TCP/IP!internet=134.27.161.145+port=21100'"   \
           -agreementid 5                                   \
           -status cooperative                              \
           -agreement {SS={AREA={CP={/O=My-Company01},
                                 RA={DEF=TRUE}
                                },
                           ATT={DEF=TRUE}
                          },
                       UM={SI={OC=TRUE}},
                       CHANGEO=FALSE
                      }                                     \
           -pol {SUPP={US=TOTAL-INCR,MAXLOC=0},
                 CONS={US=TOTAL-INCR,REPLS=FALSE},
                 INI={RI=90,ATU=FALSE}
                }

  3. In the following example, the administrator creates a shadowing agreement with a synchronous shadowing consumer DSA on the master DSA of the cooperating DSA table

    sob create -supplier {/cn=DirX-DSA-host1}                          \
           -supplierpsap "TS=DSAUP,NA='TCP/IP!internet=123.26.171.123+port=21100'"          \
           -consumer {/cn=DirX-DSA-host2}                          \
           -consumerpsap "TS=DSALI,NA='TCP/IP!internet=134.27.161.145+port=21100'"          \
           -consumerkind SYNCHRON                                  \
           -agreementid 50                                         \
           -status cooperative                                     \
           -pol "INI={ATU=TRUE,RMR=3},SUPP={US=SEGM-TOTAL-INCR},CONS={REPLS=TRUE}"

  4. In the following example, the administrator creates a synchronous shadowing agreement and the total update is configured by media

    sob create -supplier {/cn=DirX-DSA-host1}                          \
           -supplierpsap "TS=DSAUP,NA='TCP/IP!internet=123.26.171.123+port=21100'"          \
           -consumer {/cn=DirX-DSA-host2}                          \
           -consumerpsap "TS=DSALI,NA='TCP/IP!internet=134.27.161.145+port=21100'"          \
           -consumerkind SYNCHRON                                  \
           -agreementid 60                                         \
           -agreement "CHANGEO=TRUE" \
           -status cooperative                                     \
           -pol "INI=\{ATU=TRUE,RMR=3},SUPP=\{US=SEGM-TOTAL-INCR},CONS=\{REPLS=TRUE}"

sob delete

Deletes a shadowing agreement. The syntax is as follows:

  • sob disable
        -agreementid     agreementid
        [-supplier dsa_name]
        -consumer dsa_name

Options

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • This required option specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

The delete operation removes a shadowing agreement. Before performing the sob delete operation it is recommended to deactivate the agreement with sob terminate. (See the sob terminate operation for details.)

If the last agreement to a DSA is deleted the master DSA of the cooperating DSA table automatically deletes the agreement that propagates the cooperating DSA table to this DSA. (See the dirxadm sob create operation for details.) If this DSA is not available the agreement is kept and the DSA tries to propagate the deletion in the error recovery procedures. If you are sure that this DSA will never return you may delete this agreement manually.

Example
sob delete -supplier {/cn=DirX-DSA-host1} \
           -consumer {/cn=DirX-DSA-host2} \
           -agreementid 5

sob disable

Disables the execution of a shadowing agreement. This operation can only be performed on agreements with the status COOPERATIVE of an operational binding. The syntax is as follows:

  • sob disable
        -agreementid     agreementid
        [-supplier dsa_name]
        -consumer dsa_name

Options

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • This required option specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

The disable operation disables the execution of a shadowing agreement. This operation can only be performed on agreements with the status COOPERATIVE of an operational binding. The status COOPERATIVE is not changed. The disabled flag is set to TRUE. (See section titled Update-Status of the DirX Directory String Representation for DAP Binds chapter in DirX Directory Syntaxes and Attributes for details.) Use the sob enable operation to activate the shadowing agreement. Then the supplier DSA sends incremental updates to the consumer DSA.

The disable operation can only be performed locally. It must be performed first on the consumer DSA and then on the supplier DSA.

Example
sob disable -supplier {/cn=DirX-DSA-host1} \
            -consumer {/cn=DirX-DSA-host2} \
            -agreementid 5

sob enable

Enables the execution of a shadowing agreement which has been disabled by the DSA internally (for example, because of previous recovery problems), or by the sob disable operation. This operation can only be performed on agreements with the status COOPERATIVE of an operational binding. The syntax is as follows:

  • sob enable
        -agreementid agreementid
        [-supplier dsa_name]
        -consumer dsa_name

Options

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • This required option specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

The enable operation enables the execution of a shadowing agreement which has been disabled by the DSA internally (for example, because of previous recovery problems), or by the sob disable operation. The supplier DSA sends incremental updates to the consumer DSA. This operation can only be performed on agreements with the status COOPERATIVE of an operational binding. The status COOPERATIVE is not changed. The disabled flag is set to FALSE. (See section titled Update-Status of the DirX Directory String Representation for DAP Binds chapter in DirX Directory Syntaxes and Attributes for details.)

The enable operation can only be performed locally. It must be performed first on the consumer DSA and then on the supplier DSA.

Example
sob enable -supplier {/cn=DirX-DSA-host1} \
           -consumer {/cn=DirX-DSA-host2} \
           -agreementid 5

sob establish

Changes the status of an operational binding to COOPERATIVE. The syntax is as follows:

  • sob establish
        -agreementid agreementid
        [-supplier dsa_name]
        -consumer dsa_name

Options

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • This required option specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

The establish operation changes the status of an existing operational binding to COOPERATIVE. It increases the version of the agreement by 1. (See the -agreementid option for details.) Use this operation to activate a shadowing agreement. The supplier DSA sends a total update to the consumer DSA if the ATU (automatic total update) subcomponent of the INI (initiator policy) component of the SOB-Policies is TRUE and the CHANGEO (changes only) component of the Shadowing-Agreement-Info is FALSE.

Example
sob establish -supplier {/cn=DirX-DSA-host1} \
              -consumer {/cn=DirX-DSA-host2} \
              -agreementid 5

sob help

Returns help information about the sob object and its operations. The syntax is as follows:

  • sob help [operation | -verbose]

Options

-verbose

  • Displays information about the sob object.

Used without an argument or option, the help command returns brief information about each sob operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the sob object itself.

Example
sob help

The output of the sample command follows:

create

Creates a shadowing operational binding.

delete

Deletes a shadowing operational binding

disable

Disables a shadowing operational binding

enable

Enables either a shadowing operational binding

establish

Activates either a shadowing operational binding

show

Displays an entry of an operational binding

switch

Switches a shadowing operational binding

synchronize

Initiates the replication of remaining updates to consumer DSAs immediately

terminate

Deactivates a shadowing operational binding

help

Displays the help text for the "sob" object and its operations.

operations

Lists the operations that can be performed on the "sob" object.

sob operations

Returns a list of operations that can be performed on the sob object. The syntax is as follows:

  • sob operations

The list of available operations is in alphabetical order except for help and operations, which are listed last.

Example
sob operations

The output of the sample command follows:

create delete disable enable establish show switch synchronize terminate help operations

sob show

Displays a DSA’s shadowing agreements. The syntax is as follows:

  • sob show
        [-agreementid agreementid]
        [-supplier dsa_name]
        [-consumer dsa_name]
        [-pretty]

Options

-agreementid agreementid

  • Specifies the shadowing agreement identifier. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • This required option specifies the name of the DSA receiving the directory information. Specify the complete distinguished name of the consumer DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

-pretty

  • Displays the results of the operation in a tabular format.

The show operation displays the shadowing agreements that have been created for a DSA.

When used without options, the operation returns the complete distinguished names and PSAP addresses of all supplier DSAs. (See Access-Point structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

When used with the -supplier option only, the operation returns the complete distinguished names and PSAP addresses of all consumer DSAs that get shadows from this supplier DSA.

When used with the -supplier and -consumer option only, the operation returns the list of all agreement IDs that describe operational bindings between these DSAs.

When used with all options, the following information is displayed:

  • Binding state - The status of the operational binding (e.g. COOPERATIVE). (See OBS component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Validity - The time period during which the shadowing agreement or LDIF agreement is valid. (See -validity option of the dirxadm sob create command for details.)

  • Agreement - The information about the shadowing agreement. (See SAI component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Policies - The policies to be performed for the shadowing agreement. (See RPOL subcomponent of the SAI component of Cooperating-DSA structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

  • Update status - The update status of the shadowing agreement. (See Update-Status structured attribute syntax in DirX Directory Syntaxes and Attributes for details.)

By default, the results of the show operation are displayed as a Tcl list; use the -pretty option to return the results in a tabular, more readable format.

Example

  1. The following command displays a list of all supplier DSAs:

    sob show -p

    The output of the sample command follows:

    Supplier-DSA
  AE-Title     : /CN=DirX-DSA-host1
PSAP-Address
  T-Selector   : DSA1
  NSAP-Address : TCP/IP!internet=123.26.171.123+port=21100
Supplier-DSA
  AE-Title     : /CN=DirX-DSA-host2
PSAP-Address
  T-Selector   : DSA2
  NSAP-Address : TCP/IP!internet=134.27.161.145+port=2110

  2. The following command displays shadowing agreement 5 between supplier DSA /CN=DirX-DSA-host1 and consumer DSA /CN=DirX-DSA-host2:

    sob show -agreementid 5 \
         -supplier {/cn=DirX-DSA-host1} \
         -consumer {/cn=DirX-DSA-host2} -p

    The output of the sample command illustrates sob show output that was generated while the DSA was sending a shadowing update. (See the displayed “Actual-Update” component.) The output of the sample command follows:

    Validity-Agreement
    Operational-Binding-State : COOPERATIVE
OprBindMngmnt-Validity
  Validity-From               : 060922071712Z
Agreement
Shadow-Subject
Area-Specification
  Context-Prefix              : /O_DUTF8=My-Company
Replication-Area
  Default-Value               : TRUE
Attribute-Selection
  Default-Value               : TRUE
Update-Mode
Supplier-Initiated
  On-Change                   : TRUE
Update-Status
  Disabled                    : FALSE
Update-Status
Supplier-Update-Status
  Area-Change-State           : NO-CHANGES
Old-Updates
  Segment-ID                  : 4
  Update-Time                 : 20060922075524Z
  Area-Changes                : TRUE
Actual-Update
  WaitingState                : WAIT_BIND_RESPONSE
  Segment-ID                  : 5
  Update-Time                 : 20060922080930Z
  Area-Changes                : TRUE
  Offset                      : 375
  ModCount                    : 67
  Last-Upd-Entry              : /o=my-company/ou=sales/cn=xyz

  3. The following command displays status of consumer DSAs:

    sob show -suppl {/CN=DirX-DSA-host1} -p

    The output of the sample shows the status of two consumer DSAs whose DISP type is SYNCHRON. The output of the sample command follows:

    Consumer-DSA
Cooperating-DSA
  AE-Title      : /CN=DirX-DSA-host2
PSAP-Address
  T-Selector    : DSA1
  NSAP-Address  : TCP/IP_IDM!internet=134.27.161.145+port=21200
  DISP-Kind     : SYNCHRON
Recent-MSN
  Recent-MSN    : 1001
Sync-Status
  Sync-Status   : TRUE
Cooperating-DSA
  AE-Title      : /CN=DirX-DSA-host3
PSAP-Address
  T-Selector    : DSA1
  NSAP-Address  : TCP/IP_IDM!internet=134.27.161.146+port=21200
  DISP-Kind     : SYNCHRON
Recent-MSN
  Recent-MSN    : 1001
Sync-Status
  Sync-Status   : TRUE

sob switch

Switches the supplier DSA (sender of shadowed information). The syntax is as follows:

  • sob switch
        {-from dsa_name
        -to dsa_name |
        -emergency}

Options

-from dsa_name

  • Specifies the name of the current supplier DSA (sender of the shadowed information). Specify the complete distinguished name of the DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

-to dsa_name

  • Specifies the name of the future supplier DSA. Specify the complete distinguished name of the DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

-emergency

  • Specifies an emergency switch. All other options are prohibited for this option.

If the bind DSA is a consumer of the cooperating DSA subentry it now becomes the supplier DSA of the cooperating DSA subentry and all shadowing agreements that it is a consumer DSA and that were supplied by the old master DSA of the cooperating DSA subentry. The old master DSA of the cooperating DSA subentry must not run that is the new supplier DSA of the cooperating DSA subentry rejects the operation when the current supplier DSA is running.

The switch operation switches the role of a supplier DSA to a consumer DSA. The participating DSAs specified in the -from and -to options must run while the operation is in progress. The roles are switched after all remaining updates had been sent. Therefore this operation may last some time.

Use the -emergency option to perform an emergency switch when one or more DSAs have broken down.

For synchronous shadowing configurations, the new supplier DSA’s database must have the most recent version compared to the database version of the other switchable consumer DSAs (emergency switch compares the value of the DirX Directory Recent MSN (dirxRecentMSN) attribute with that of the other switchable consumer DSAs and rejects the operation if this condition is not true). Once the old supplier DSA is online again, the new supplier DSA transmits a total update automatically to the old supplier DSA. For asynchronous shadowing configurations, you must ensure that the old supplier DSA’s data is transformed into shadow data before re-starting the DSA, for example, by restoring a backup from the new supplier DSA.

If a sob switch -emergency operation is performed after stopping the supplier while it is in the process of sending updates, the unsent updates are lost.

If the operation is performed while a lot of update operations are in progress, some of the update operations fail.

The REPLS subcomponent of the consumer policy must be TRUE. (See the SOB-Policies syntax in chapter titled DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for details.)

Another aspect is unique constraint configuration, if this feature is enabled. At non emergency switch time, unique constraint configuration must be identical on both DSAs or the operation is rejected. In case of an emergency switch this is not proved. It is on the behalf of the administrator to implement a consistent unique constraint configuration between the new supplier DSA and remaining switchable consumer DSAs. (See the dirxadm db attrconfig operation and section Unique Constraints Configuration Management in a Shadow Configuration in the DirX Directory Administration Guide for details.)

Before you perform the sob switch operation, you must ensure that all affected shadowing and LDIF agreements are in COOPERATIVE status and enabled. To check this perform sob show operations.

There may be a special LDIF agreement below the root DSE (/) that is intended especially for dumping the complete database (for example for migrating or reloading issues). If there is this LDIF agreement below root DSE and the DSE type of the root DSE does not contain the value CP (context prefix) you should delete this LDIF agreement before you switch the master. (See DSE Type Syntax in DirX Directory Syntaxes and Attributes for details.) In the event of an emergency switch, delete it immediately after performing the switch operation, for example, by performing a delete_total_ldif [agreementid] operation.

Note that in DirX Directory, local policies - the DSA policies and user policies - are stored in operational attributes of the root DSE. These policies are managed with the dirxadm tool; shadowing does not propagate modifications. Keep in mind that policy settings originally intended for a shadow DSA will apply to a master DSA after the switch operation is performed. Use dirxadm to re-administer policy values that no longer fit with the new role of a DSA.

You cannot perform a switch operation if any DSA with disp_kind X500 (see the sob create opration for details) takes part in the shadowing agreements to switch.

On a switch operation, all query references (cookies) are deleted in both DSAs that are involved in the switch operation. Query references generated by DSAs that are not participating in the switch operation are unaffected. If an LDAP application has an active paged search operation performed on one of the DSAs involved when the sob switch operation is executed, the next request of the paged search operation will result in an “unwilling to perform” operation error and the LDAP message [DSA]:Invalid query ref. If a query reference was generated by a DSA whose role did not change as a result of the switch operation, the paged search continuation will succeed for a next page call after the switch.

Example
sob switch -from {/cn=DirX-DSA-host1} \
           -to \{/cn=DirX-DSA-host2}

sob synchronize

Initiates the immediate transfer of remaining updates to consumer DSAs. The time interval of scheduled agreements is interrupted and transferring updates is started. Once the updates have been transmitted, the normal time interval for scheduled agreements takes effect again. The syntax is as follows:

  • sob synchronize
        [-consumer dsa_name [-agreementID agreementidt]]

Options

-consumer dsa_name

  • Specifies the name of the consumer DSA (receiver of the shadowed information). Specify the complete distinguished name of the DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

-agreementid agreementid

  • Specifies a shadowing agreement identifier. This option can only be specified together with the -consumer option. Specify agreementid in the format

    • id[,version]

    where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

The synchronize operation initiates transferring remaining updates to consumer DSAs immediately.

Use the -consumer option to perform data synchronizing for a specific consumer DSA.

Use the -agreementid option to perform data synchronizing for a specific shadowing agreement of a specific consumer DSA.

If the operation is performed without options the operation initiates transferring all remaining updates for all shadowing agreements to all consumer DSAs.

Before you perform the sob synchronize operation you must ensure that all affected shadowing and LDIF agreements are in COOPERATIVE status and enabled. To check this perform sob show operations.

Example
sob synchronize -consumer {/cn=DirX-DSA-host2} \ +
                -agreementid 5

sob terminate

Changes the status of an operational binding to NONCOOPERATIVE (deactivates shadowing). The syntax is as follows:

  • sob terminate
        -agreementid agreementid
        [-supplier dsa_name]
        -consumer dsa_name

Options

-agreementid agreementid
Specifies a shadowing agreement identifier. This option can only be specified together with the -consumer option. Specify agreementid in the format

+ id[*,*version]

+ where id is an integer that uniquely identifies the shadowing agreement and version is an optional integer that specifies the version. The version number is managed by the DSA. The DSA assigns the value 0 when the agreement is created (with dirxadm sob create); each time the agreement is established (with dirxadm sob establish), the DSA increments the version number by 1. It is only used for displaying.

-supplier dsa_name

  • Specifies the name of the DSA sending the directory information. Specify the complete distinguished name of the supplier DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax. The default value is the local DSA.

-consumer dsa_name

  • Specifies the name of the consumer DSA (receiver of the shadowed information). Specify the complete distinguished name of the DSA. See DirX Directory String Representation for DAP Binds in DirX Directory Syntaxes and Attributes for a description of distinguished name syntax.

The terminate operation changes the status of an existing operational binding to NONCOOPERATIVE. Use this operation to deactivate a shadowing agreement.

Use the sob establish operation to activate the shadowing agreement. If the CHANGEO component of the Shadowing Agreement Info (-agreement option of sob create) is set to FALSE then the supplier DSA sends a total update to the consumer DSA.

Example
sob terminate -supplier {/cn=DirX-DSA-host1} \
              -consumer {/cn=DirX-DSA-host2} \
              -agreementid 5

sys (dirxadm)

Synopsis

sys help [operation | -verbose]

[sys] log

[sys] nolog

sys operations

[sys] opmode [op_mode]

[sys] start [-host hostname] [-port portnumber]

[sys] status

[sys] stop

Purpose

A dirxadm object that manages the directory service.

Arguments

operation

  • The name of the sys operation for which to display help information.

op_mode

  • Specifies the operation mode of the DSA. Specify one of the following keywords:

    • READONLY—Specifies that the DSA allows only read operations, for example list, search or show operation. Update operations, for example add, delete or modify operation, are rejected.

    • READWRITE—Specifies that the DSA allows all operations.

Operations

sys help

Returns help information about the sys object and its operations. The syntax is as follows:

  • sys help [operation | -verbose]

Options

-verbose

  • Displays information about the sys object.

Used without an argument or option, the sys help operation returns brief information about each sys operation. Use the operation argument to return a description of the options associated with the operation you specify. Alternatively, you can use the -verbose option to return a description of the sys object itself.

Example
sys help

The output of the sample command follows:

log

Switches on the diagnostic logging.

nolog

Switches off the diagnostic logging.

opmode

Displays and sets the operation mode of the DSA.

start

Starts the Directory Service.

status

Displays the status of the DSA.

stop

Stops the Directory Service.

help

Displays the help text for the “sys” object and its operations.

operations

Lists the operations that can be performed on the “sys” object.

sys log

Starts server diagnostic logging. The syntax is as follows:

  • [sys] log

DSA logging is initially controlled by the specifications in the configuration file install_path/*server/conf/dirxlog.cfg*. When a sys log operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path/*server/conf/dirxlog.on*. To use these specifications when restarting the server, edit the file install_path/*server/conf/dirxlog.cfg* according to the settings in file install_path/*server/conf/dirxlog.on*. By default, the log files are written to the directory install_path*/server/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

Example
log

sys nolog

Stops server diagnostic logging. The syntax is as follows:

  • [sys] nolog

DSA logging is initially controlled by the specifications in the configuration file install_path/*server/conf/dirxlog.cfg*. When a sys nolog operation is performed, subsequent logging is controlled by the specifications in the configuration file install_path/*server/conf/dirxlog.off*. To use these specifications when restarting the server, edit the file install_path/*server/conf/dirxlog.cfg* according to the settings in install_path/*server/conf/dirxlog.off*. By default, the log files are written to the directory install_path*/server/log*. Use the dirxdumplog command to read the diagnostic information in the trace log files. The exception log files are readable files. (See Logging Configuration Files in chapter DirX Directory Files for details about the logging configuration files and how to enable, disable and modify logging.)

Example
nolog

sys operations

Returns a list of operations that can be performed on the sys object. The syntax is as follows:

  • sys operations

The list of available operations is in alphabetical order, except for help and operations, which are listed last.

Example
sys operations

The output of the sample command follows:

log nolog opmode start status stop help operations

sys opmode op_mode

Sets or displays the operation mode of the DSA. The syntax is as follows:

  • [sys] opmode [op_mode]

The opmode operation sets the operation mode of the DSA to the mode specified in op_mode. (See section Arguments above for details.) After the operation has been performed successfully the operation mode of the DSA is displayed. The change of the operation mode is persistent that is after a shutdown the DSA is restarted in the last op_mode in force.

If op_mode is not supplied, the operation displays the current operation mode of the DSA:

  • READONLY—The DSA allows only read operations, for example list, search or show operation. Update operations, for example add, delete or modify operation, are rejected.

  • READWRITE—The DSA allows all operations.

  • POSTINDEXING—Indicates that one of the following dirxadm operations is running:

    • db attrconfig

    • db check -bs

    • db purge -pob

    • db statistics [-create | -update]

    While these operations are in progress, update operations are rejected. After the operations have finished the operation mode is re-set to READWRITE.

  • VERIFY—Indicates that the dbamverify command is running. Update operations are rejected. After the dbamverify command has finished the operation mode is re-set to the mode last recently in force.

  • READONLYWAIT—Indicates that the dbamdevinfo command is running. Update operations are delayed until the command has finished. This may take several seconds. Then the operation mode is re-set to the mode last recently in force. Delayed update operations are performed.

Example

  1. Set the operation mode of the DSA to read only:

    opmode READONLY

    The output of the sample command follows:

    READONLY

  2. Display the current operation mode of the DSA:

    opmode

    The output of the sample command follows:

    READWRITE

sys start

Starts a Directory Service (DSA, LDAP server and progsvr). The syntax is as follows:

  • [sys] start [-host hostname] [-port portnumber]

Options

-host hostname

  • The hostname or IP address of the machine hosting the Directory Service to be administered. The default is localhost.

-port portnumber

  • The port number of the process that is starting the Directory Service. You should use the -port option only if there is a conflict with the default port number on your system. The default port is 5800.

Use the -host and/or -port options to start a specific Directory Service on a Linux system.

Unlike other operations, you must not perform a dse bind operation before performing the sys start operation.

On Windows systems, DirX Directory is started as a service by using the Administration Tool Services. The sys start operation is used to start a remote Directory Service on a Linux system. In this case the -host option must be specified.

In a client installation on Linux, start the LDAP server by performing the command
/etc/init.d/dirx start as root.

The start operation may take several seconds. An initdaemon process is loaded to start the progsvr, the LDAP server and the DSA. dirxadm waits for a result of the initdaemon.

Example
start

sys status

Shows the status of the connection to the DSA currently used. The syntax is as follows:

  • [sys] status

Example
status

Sample output from a status command follows:

Status Information
    Target Host    : localhost
    RPC-Portnumber : 5999
    Bind-Status    : NOT CONNECTED

sys stop

Stops a Directory Service (DSA, LDAP server and progsvr). The syntax is as follows:

  • [sys] stop

On Windows systems, DirX Directory is stopped by using the Administration Tool Services. It is recommended not to use the sys stop operation.

In a client installation on Linux, stop the LDAP server by performing the command
/etc/init.d/dirx stop as root.

The stop operation may take several seconds because the server must terminate outstanding update operations and cancel outstanding retrieval operations.

Example
stop

See Also

dirxdumplog (Chapter 1), Logging Configuration Files (Chapter 2)

util (dirxadm)

Synopsis

create_total_ldif [agreementid] [subtree]

delete_total_ldif [agreementid]

ldif_dump [subtree]

export_dbconfig [filename]

import_dbconfig [filename]

Purpose

Utilities for dirxadm.

Arguments

agreementid

  • The LDIF agreement identifier, in the format

    • id[,version]

    where id is an integer that uniquely identifies the LDIF agreement and version is an optional integer that specifies the version. The default value is 1111.

filename

  • The name of the file to write or to read the database configuration.

subtree

  • The distinguished name of the base object of the subtree at which the LDIF output is to be created.

Operations

create_total_ldif

Creates a cooperative LDIF agreement that saves the entire DIT or a subtree of the DIT to one or more local files in LDIF content and / or LDIF change format. This LDIF agreement is a special LDIF agreement below root (/) or the subtree specified in the command that is intended for dumping the complete DBAM database or a database subtree; for example, for migrating or reloading issues. It should not be a permanent LDIF agreement.

The syntax is as follows:

  • create_total_ldif [agreementid] [subtree]

The operation performs a lob create operation to create the LDIF agreement. See the lob create operation for details.

The generated LDIF files (agreementid.timestamp) are saved to the directory install_path*/server/ldif*. If no subtree is specified, they contain the entire DIT (all entries, subentries, the cooperating DSA table, and the schema). The agreementid in the filename indicates all LDIF files that belong together. The timestamp in the filename indicates the load sequence. All LDIF files must be opened to determine whether the files are LDIF content files or LDIF change files. Usually, the oldest file is an LDIF content file and the rest are LDIF change files.

When re-loading the LDIF files, all files generated by other LDIF agreements can be ignored. To re-load the database, perform the following steps:

  1. Stop the service.

  2. Load all generated LDIF content files with dirxload.

  3. Start the service.

  4. Load all generated LDIF change files with dirxmodify.

  5. If the entire DIT was restored, re-create additional indexes if necessary.

See also the dirxload and the dirxmodify command for details.

Example
create_total_ldif 2222
create_total_ldif 2222 /O=My-Company

delete_total_ldif

Deletes the specified LDIF agreement. The syntax is as follows:

  • delete_total_ldif [agreementid]

The operation performs a lob delete operation to delete the specified LDIF agreement. See the lob delete operation for details.

Example
delete_total_ldif 2222

ldif_dump

Performs a one-time total LDIF dump of the DBAM database. The syntax is as follows:

  • ldif_dump [subtree]

The operation creates one LDIF content file with the entire DIT (all entries, subentries, the cooperating DSA table, and the schema) of the bind DSA or the specifed subtree. The DSA can be a supplier DSA or a consumer DSA.

The operation does not create an LDIF agreement.

The operation does not lock the DSA for read or write access. Consequently, updates to the database that are made during the operation may not be contained in the resulting LDIF content file. To avoid this scenario, it is recommended to set the DSA to READONLY mode with the dirxadm sys opmode READONLY operation before performing the ldif_dump command.

The name of the resulting LDIF content file is 0000001112STANDALONE.*timestamp. It is located in the folder install_path/server/ldif*. For more information on files in LDIF format, see the dirxadm lob create operation.

Example
ldif_dump
ldif_dump /O=My-Company

export_dbconfig

Exports a database configuration. The syntax is as follows:

  • export_dbconfig [filename]

where filename specifies the name of the file to that the operation writes the database configuration. If no filename is specified the configuration is exported to the file install_path*/tmp/DirXDBconfig.out* or %DIRX_TMP%/DirXDBconfig.out on Windows and $DIRX_TMP/DirXDBconfig.out on Linux.

The operation exports the index description of all indexed attributes. The generated file can be used by the dirxadm import_dbconfig operation to import the same database configuration to another database.

Example
export_dbconfig C:/tmp/DirXDBconfig.out

The sample output is as follows:

# DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit
# Read abbreviations from dirxabbr
# operation ok
# Read Attributes of the DSA schema
# operation ok
# Read indexed Attributes of the DSA schema

# AttributeIndexDescription = "("
#   whsp  numericoid                   ; Object identifier of attribute
#   whsp ["NAME" whsp qdescr ]         ; LDAP attribute name
#   whsp ["INDEX" [whsp INITIAL] [whsp FINAL] [whsp CONTAINS] [whsp PRESENT] [whsp APPROXIMATE]]  ; type of indices present
#   whsp OPTREAD true|false
#   whsp ")"

# The following 12 attributes are indexed
dn: cn=dbconfig
# ObjectClass(es) have to be added (objectClass: <top>)
attributeIndex: ( 2.5.4.6 NAME 'c' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.3 NAME 'cn' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.13 NAME 'description' INDEX INITIAL FINAL CONTAINS OPTREAD true )
attributeIndex: ( 2.5.4.31 NAME 'member' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.10 NAME 'o' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.0 NAME 'objectClass' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.10.1 NAME 'collectiveOrganizationName' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.11 NAME 'ou' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.11.1 NAME 'collectiveOrganizationalUnitName' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.4 NAME 'sn' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.20 NAME 'telephoneNumber' INDEX INITIAL FINAL CONTAINS OPTREAD true )
attributeIndex: ( 2.5.4.20.1 NAME 'collectiveTelephoneNumber' INDEX INITIAL FINAL CONTAINS OPTREAD true )

import_dbconfig

Imports a database configuration. The syntax is as follows:

  • import_dbconfig [filename]

where filename specifies the name of the file that contains the database configuration. If no filename is specified the configuration is imported from the file install_path*/tmp/DirXDBconfig.out* or %DIRX_TMP%/DirXDBconfig.out on Windows and $DIRX_TMP/DirXDBconfig.out on Linux.

A configuration can be imported only if the schema contains all attributes in the configuration file. This file can be generated by exporting the database configuration by performing a dirxadm export_dbconfig operation or by editing the configuration file in the following format:

  • Blank lines and lines starting with the # character are ignored.

  • The file must be identified by the line dn: cn=dbconfig at the beginning of the file.

  • All information for one attribute index must be specified in a single line.

  • Each line is divided into fields separated by the SPACE character.

  • Each line starts with the keyword attributeIndex:.

  • The attribute index description must be enclosed in round brackets (" ( " and " ) ") followed or preceeded by a SPACE character.

  • The attribute index description is specified in the following syntax:

    • attribute_object_identifier
      [NAME '*ldap_name'* ]
      [INDEX [INITIAL ] [FINAL ] [CONTAINS ] [PRESENT ] [APPROXIMATE ]]
      OPTREAD {true|false}

    where

  • attribute_object_identifier

    • is a required field specifying the object identifier of the attribute, for example 1.2.3.4.5

  • NAME 'ldap_name'

    • is an optional field specifying the LDAP name of the attribute. The specified LDAP name must match one of the LDAP names specified for the attribute_object_identifier in the DSA schema.

  • INDEX [INITIAL ] [FINAL ] [CONTAINS ] [PRESENT ] APPROXIMATE ]

    • is an optional field specifying the index type(s):

      • INITIAL - An initial index.

      • FINAL - A final index.

      • CONTAINS - An index optimizing the search performance of substrings positioned anywhere in the attribute value.

      • PRESENT - An index optimizing the search performance checking for the presence of an attribute type.

      • APPROXIMATE - An index optimizing the search performance for phonetic match.

    • If the INDEX field is not specified and an index exists in the database for the attribute type specified in the attribute_object_identifier field the index in the database is deleted.

  • OPTREAD {true|false}

    • is a required field that specifies whether or not access to the attribute specified in the attribute_object_identifier field and its values is to be optimized. A value of true enables access optimization and a value of false disables access optimization.

See also the dirxadm db attrconfig operation for details on indexes.

Here is an example for a configuration file:

dn: cn=dbconfig
attributeIndex: ( 2.5.4.6 NAME 'c' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.3 NAME 'cn' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.13 NAME 'description' INDEX INITIAL FINAL CONTAINS OPTREAD true )
attributeIndex: ( 2.5.4.31 NAME 'member' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.10 NAME 'o' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.0 NAME 'objectClass' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.10.1 NAME 'collectiveOrganizationName' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.11 NAME 'ou' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.11.1 NAME 'collectiveOrganizationalUnitName' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.4 NAME 'sn' INDEX INITIAL FINAL OPTREAD true )
attributeIndex: ( 2.5.4.20 NAME 'telephoneNumber' INDEX INITIAL FINAL CONTAINS OPTREAD true )
attributeIndex: ( 2.5.4.20.1 NAME 'collectiveTelephoneNumber' INDEX INITIAL FINAL CONTAINS OPTREAD true )
Example
import_dbconfig C:/tmp/DirXDBconfig.out

The sample output is as follows:

 Indexing (2.5.4.6 - c) was successful
 Indexing (2.5.4.3 - cn) was successful
 Indexing (2.5.4.13 - description) was successful
 Indexing (2.5.4.31 - member) was successful
 Indexing (2.5.4.10 - o) was successful
 Indexing (2.5.4.0 - objectClass) was successful
 Indexing (2.5.4.10.1 - collectiveOrganizationName) was successful
 Indexing (2.5.4.11 - ou) was successful
 Indexing (2.5.4.11.1 - collectiveOrganizationalUnitName) was successful
 Indexing (2.5.4.4 - sn) was successful
 Indexing (2.5.4.20 - telephoneNumber) was successful
 Indexing (2.5.4.20.1 - collectiveTelephoneNumber) was successful
12 attributes are indexed (0 error(s))

See Also

dirxload (Chapter 1), dirxmodify (Chapter 1)