metacp

Synopsis

metacp [script_name [arg1 [arg2 …​]]
    [-noaudittrail]
    [-Enc encryption_mode
    -Timeout timeout_value
    -Audit audit_level
    -CryptLogLevel crypt_level] |
    -c command |
    -V

Purpose

Provides a set of operations for directory synchronization and manages entries in an Identity store. The meta controller (metacp) supports the following objects:

ats

Manages the asynchronous transport service

ldapargs

Manages service controls associated with an LDAP directory operation

meta

Performs directory synchronization operations

obj

Manages Identity store entries

The meta controller also supports the utilities described in the util page.

Arguments

script_name

Filename of a user-defined script containing metacp commands.

The given Tcl script will be loaded using the utf-8 encoding as default. If the Tcl script holds data in a different encoding, then the following additional arguments must be passed:

-encoding encoding

-encoding encoding is part of arg[n]. It is passed along to the Tcl script as global Tcl variables. In order to write compatible Tcl scripts, it is recommended to pass these two arguments at the end of the argument list.
arg[n]

Argument to the user-defined script specified in script_name. Script arguments are stored in global Tcl variables and can be evaluated in Tcl scripts. See the Tcl Variables section in this chapter for more information.

Options

-c command

Executes the metacp or Tcl commands specified by command.

-V

Displays the metacp build version, in the format:

'metacp' build version: product_version build_id date time

For example:

'metacp' build version: 5.0B 19 1999:05:05 13:14

The metacp initialize operation also writes the build version to the metacp trace file.

-noaudittrail

Usuaally metacp evaluates the audit policies to decide whether or not audit information should be supplied. If -noaudittrail is specified no audit information is generated (even if the audit policies would allow to create audit information).

When running metacp in a security environment, the following options can be used:

-ENC encryption_mode

Specifies the security mode. Valid modes are ATTRIB_ADMIN_PW or ADMIN_PW.

ATTRIB_ADMIN_PW - bind passwords and attributes that are marked as encrypted (in the corresponding attribute configuration file) are decrypted.

ADMIN_PW - only bind passwords are decrypted.

If metacp processes several LDAP directories in parallel (e.g. in case of an LDAPtoLDAP workflow) and it runs with one of the encryption modes described above, then the bind credentials for all the bind connections need to be provided as encrypted values. It’s not possible to send encrypted bind credentials to one of the directories and to send clear text (or scrambled) bind credentials to the other directory.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

-Timeout timeout_value

Specifies the timeout value for the security mode. Values have to be given in microseconds.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide for details.)

-AuditLevel audit_level

Specifies the audit level value for the security mode. Valid values are in the range of 0 and 4.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

-CryptLogLevel crypt_level

Specifies the logging level of the crypt library for the security mode. Valid values are greater or equal to 0.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

Description

The meta controller is a command-line tool that system administrators can use to perform directory synchronization. Use it to perform the following tasks:

  • Initialize and clean up the metacp workspace

  • Open connections to directories

  • Create and manage metacp handles

  • Read attribute configuration files

  • Perform entry management during directory synchronization

  • Create and manage directory search results lists

  • Perform string-handling operations

  • Create trace files that record directory synchronization progress

  • Create and manage index lists

You can also use metacp as a command-line entry administration tool to communicate with a Identity store and manage the entries contained within it.

Auditing Update Operation

metacp generates audit record information and stores it internally in the attribute dxrHistory of the current object whenever there are attribute changes (for a modify operation) or new objects with attributes that are relevant for auditing.

Therefore metacp reads the audit policies at startup time. It uses the bind DN and extracts the DirX Identity domain from that information. Once a valid domain name can be evaluated, it checks whether auditing is enabled at the domain (attribute dxrWriteHistory is set to TRUE). If auditing is enabled, it reads all the relevant audit policies that are defined in that domain; it therefore performs a search operation with base object cn=Audit Policies,cn=Audit Trail,cn=domain and filter (&(objectClass=dxrAuditTrailPolicy)(dxrWriteHistory=TRUE))

Note that the attribute dxrHistory is only filled when calling meta addentry or meta modifyentry; it’s not filled when calling obj create or obj modify as these two operations are basic operations that have the same functionality as DirX Directory dirxcp.

Sending JMS Messages

metacp can send JMS messages when new objects are created and when existing objects are modified, deleted or moved. It uses information that is available in change event policies; it therefore knows the relevant LDAP object classes of the objects for which such JMS events (messages) should be generated. This feature enables the DirX Identity product to run other workflows that should process the information about the changes of the objects.

Therefore metacp reads the change event policies at startup time. It uses the bind DN and extracts the DirX Identity domain from that information. Once a valid domain name can be evaluated, it looks for the relevant change event policies; it therefore performs a search operation

with base object cn=domain
and filter (&(objectClass= dxrChangeEventPolicy)(dxrIsActive=TRUE))

Tcl Command Language

The meta controller 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 directory synchronization and structured file I/O. The program also includes task scripts to help directory users and system administrators perform some routine management functions.

Including New Tcl Packages

The meta controller provides a few Tcl packages that are located in the following folder:

install_path/lib/tcl8.3

The packages are:

  • encoding

  • http1.0

  • http2.3

  • msgcat1.1

To include more Tcl packages perform the following steps:

  • Copy the new Tcl package as a subfolder below install_path/lib/tcl8.3

  • Rename all occurrences of the Tcl “list” command to “llist”

    metacp has defined an own command “list” that returns all LDAP entries below a given base node. Therefore, the original Tcl command “list” has been renamed to “llist”.

    Check the packages listed above to see what changes have been done; for example check the usage of the following statements:

if {[info commands llist] != ""} then {
     # DIR.X version with usage of “llist”
} else {
      # original version with usage of “list”
}

The Directory Client Configuration File

The meta controller uses the directory client configuration file (dirxcl.cfg) to convert symbolic names of Identity stores to network addresses and to determine network addresses of default servers. See the DirX Identity Program Files chapter for details about this file.

Bind Types and Bind IDs

The meta controller supports multiple binds by using bind IDs and-for compatibility reasons-the concept of a default bind. A bind ID is a string associated with an LDAP bind (a connection to a Identity store through the LDAP v2 or LDAP v3 protocol). Specify the string value of a bind ID in an obj bind operation. (See the obj bind operation for details.) Use the bind ID in other operations to refer to a particular bind.

An obj bind command that does not specify a bind ID establishes a default bind. A command that does not specify a bind ID refers to the default bind. Only one default bind can exist at a time.

Synchronization Profiles and Synchronization Templates

A synchronization profile is a Tcl script (or a collection of Tcl scripts) that contains Tcl statements and meta controller commands that implement a specific synchronization scenario to be carried out by the meta controller. The synchronization profile is the mechanism that drives the meta controller’s directory synchronization functions. It consists of three sections:

  • The variable section

  • The mapping section

  • The control logic section

The contents of these sections are specific to a given synchronization scenario. The next sections describe their general content.

The directory synchronization templates supplied in the Samples/metacp subdirectory of the DirX Identity installation include sample synchronization profiles. See the Directory Synchronization Templates chapter for more details about these templates.

The Variable Section

The variable section provides a way to configure the synchronization profile using Tcl variables. Each Tcl variable defined in this section acts as a "profile switch" and is used to establish parameters for the synchronization process. Configurable information that can be set up with a profile switch includes:

  • The names of the source and target attribute configuration files to be used

  • The name of the meta controller trace file and the trace level to be set

  • The Identity store bind and search parameters

The Mapping Section

The mapping section of a synchronization profile specifies rules for:

  • Entry mapping

  • Entry inclusion and exclusion

  • Entry ownership

  • Attribute mapping

  • Attribute inclusion and exclusion

  • Attribute value manipulation

  • Attribute ownership

The Control Logic Section

The control logic section is the main body of the synchronization profile. It contains the Tcl script code and metacp operations that perform the directory synchronization.

Attribute Configuration Files

An attribute configuration file defines the attributes that are present in a particular connected directory and supplies formatting information that the meta controller is to use when processing import and export data files associated with the connected directory. An attribute configuration file must exist for each connected directory to be synchronized by the meta controller (that is, a corresponding attribute configuration file must exist for each DirX Identity agent present in DirX Identity). The attribute configuration file contains one record for each attribute in the connected directory.

During a directory synchronization operation, the meta controller reads source and target directory attribute configuration files (via a meta controller "read attribute configuration file" operation specified in the synchronization profile) to obtain attribute and data file formatting information about the directories it is synchronizing.

The meta controller uses attribute configuration files to determine connected directory attribute abbreviations. Chapter 2 describes attribute configuration file format.

Invoking metacp

You can invoke metacp commands in interactive and command mode

Interactive Mode

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

% metacp
metacp> set home_dir /home/lionel
metacp> meta initialize -file $home_dir/tracefile -tracelevel 2
metacp>

Command Mode

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

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

    % metacp my_sync_profile.tcl

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

    % metacp -c "bind; modify ou=Sales/o=pqr -addattr telephoneNumber=00498912312312"

    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:

    % metacp -c "bind; puts [obj show C=de -allattr]; puts [ldapargs show]"

Terminating metacp

Terminate an interactive metacp session by using the exit and 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:

metacp> exit 56

Exit Codes

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

Code Type Description

1

Error

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

2

Error

The specified file does not exist (for example, you specified metacp zz.tcl, and zz.tcl does not exist)

3

Error

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

4

Error

The evaluation of the command failed (for example, you specified an incorrect command on the metacp -c command line)

5

Error

Tcl initialization failed

6

Error

The initialization of the logging component failed.

7

Error

The shared libraries (or one of it’s internal functions) used for Password Synchronisation couldn’t be loaded.

8

Error

Setting up the environment for Password Synchronisation failed (e.g. initialization of crypt library; retrieval of private keys)

9

Error

Internal memory allocation problem.

10

Error

A serious error occurred during the execution of a script; a meta operation failed.

11

Error

A serious error while running the workflow occurred. The error will be returned if illegal parameter combinations are specified in control.tcl.

12

Error

The minimum required number of source directory entries is not available.

59

Error

An error occurred while sending the notification file.

60

Warning

A workflow terminated with warnings (e.g. because an entry to be deleted belongs to another master, etc.)

61

Warning

A directory update operation failed.

200

Warning

Some operations could not be performed correctly (for example a join retrieved more than one hit). Manual intervention is necessary.
Scripts delivered with metacp use exit codes between 0 and 79 (exit codes 1 to 8 are generated by metacp itself, the remaining ones are generated by script logic of the standard script). Exit codes between 80 and 199 can be used in customer scripts. The use of exit codes lower than 80 or higher than 199 is prohibited in customer scripts.

Startup Scripts

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

[info library]/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.

$metacp_library/init.metacp
Contains the initialization scripts that implement the metacp commands and tasks. The implementation sets the Tcl variable metacp_library to install_path/client/conf on Unix and install_path\bin on Windows.

$HOME/.metacprc
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 metacp command has the following syntax:

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

where:

object

specifies the name of one of the following metacp administration objects:

ats

Manages the asynchronous transport service

ldapargs

Manages service controls associated with an LDAP directory operation

meta

Performs directory synchronization operations

obj

Manages directory objects

Specifying an administration object is optional. If you do not specify an object on the command line, the default object is obj for operations that exist in both the meta and the obj objects (like help and operations).

Refer to the individual object reference pages for complete descriptions of these administration objects.

operation

Specifies the name of an action such as readattrconf, getentry, or gethandle, 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 metacp object. Common operations for all metacp objects are help and operations.

argument

Specifies the name of one or more specific objects to operate on. Most, but not all, metacp objects take an argument. 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 metacp command. Most, but not all, metacp commands take options. Some options take an argument, opt_arg, that can be a name or a value.

Line Continuation

meta controller 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 metacp command supports the Tcl built-in commands as well as its own commands. A command unknown to metacp is passed to the unknown command, which evaluates it as follows:

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

  • If unknown finds that the command is an executable UNIX or Windows program, metacp runs it. Consequently, you can invoke any UNIX or Windows command from the metacp prompt, for example,

ls -l.

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

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

Abbreviations

The metacp command uses two mechanisms to allow all object names, operation names, and options to be abbreviated to the shortest unique string in interactive commands.

The first mechanism relies on the unknown command, whose behavior is described in the Command Processing section of this reference page.

The second mechanism is built into the individual metacp 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 metacp commands:

metacp> meta getentry -source
metacp> meta operations

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

metacp> meta getentry -s
metacp> meta op

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 metacp commands set several 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 metacp. Thus, you can trigger variable substitution by placing a dollar sign ($) before the name of the variable. Alternatively, you can trigger substitution by using set. You can set the Tcl variables only by using the metacp program.

The metacp program defines the following variables:

_allowpartialresult

Specifies whether incomplete results are accepted as a result of a search operation.

If this variable is not specified or its value is 0 the synchronization profile script aborts subsequent processing if it receives an incomplete result.

Specify the following values:

  • 0 - Do not accept incomplete results.

  • 1 - Accept incomplete results that have been received due to a SIZE-LIMIT problem.

  • 2 - Accept incomplete results that have been received due to a TIME-LIMIT problem.

  • 4 - Accept incomplete results that have been received due to an ADMINISTRATIVE-LIMIT problem.

  • 8 - Accept incomplete results that have been received due to the presence of referrals.

  • 16 - For LDAPv2 protocol only: Accept incomplete results that have been received due to the presence of referrals.

If incomplete results due to several problems should be accepted you must combine the values by a logical OR. A value of 9 for example specifies that incomplete results due to a TIME-LIMIT problem and / or due to the presence of referrals should be accepted.

_entry_line

Specifies the current entry read from a datafile.

The meta addentry, modifyentry, removeentries use the last entry read from a data file as additional trace information in the tracefile. That makes sense, if an object read from a data file directly results in one of the operations just listed before.

But there are new synchronization scripts available (e.g. LDAP to LDAP synchronization) where update operations are invoked without having read a record from the data file.

Therefore the last record read from the data file should be cleared using the following command:

set entry_line ""

Otherwise the tracefile contains misleading trace information because the data record listed there has no relation to the operation that has been invoked.

_errormsg

--Specifies whether the LDAP server should return additional information both in case of errors and success:

  • TRUE - Provide additional information from LDAP server.

  • FALSE - Don’t provide additional information from the LDAP server.

On startup, metacp behaves as if _errormsg has been set to FALSE.

The additional information either starts with “LDAP-Result” or “LDAP-ERROR”.

Samples:

metacp> set _errormsg TRUE
metacp> bind -prot ldapv3
             {{LDAP-Result: Bind succeeded}}
metacp> modify cn=DomainAdmin,cn=my-company -replaceattr xxx=1234
             Error: Undefined attribute type passed in operation.
             (LDAP-ERROR: Cannot handle modification for attribute type 'xxx')
_errormsgonly

Specifies whether the LDAP server should return additional information in case of errors.

  • TRUE - Provide additional information from LDAP server.

  • FALSE - Don’t provide additional information from the LDAP server.

On startup, metacp behaves as if _errormsgonly has been set to FALSE.

The additional information starts with “LDAP-ERROR”.

In case of errors the output is the same as described for TCL variable _errormsg.

_escapebackslash

Specifies whether the escape character backslash (\) is escaped by an additional backslash in requests and results. Specify one of the following keywords:

  • TRUE - Backslashes are escaped.

  • FALSE - Backslashes are not escaped.

_localcode

Specifies the character set that can be chosen from the character set table.

For compatibility reasons the following keywords are still valid:

  • LATIN1 - Default Windows character set (only used in data files). This is the default value if no _localcode variable is defined.

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

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

See Code Conversion appendix for details.

_md_req_attr_limit (defined in init.metacp)

Specifies the maximum number of attributes that is passed in a search request as requested attributes. It is used to decide whether to pass the attribute list explicitly or whether to use the -allattr option. (For details see the obj search command.)

_partialresulttype

Specifies the reason for an incomplete result returned by a search operation. This variable is an output parameter of the search operation.

The search operation returns the following values:

  • 1 - Incomplete results due to a SIZE-LIMIT problem.

  • 2 - Incomplete results due to a TIME-LIMIT problem.

  • 4 - Incomplete results due to an ADMINISTRATIVE-LIMIT problem.

  • 8 - Incomplete results due to the presence of referrals.

  • 16 - For LDAPv2 protocol only: Incomplete results due to the presence of referrals.

If incomplete results due to several problems are returned the return value is the combination of a logical OR. A value of 9 for example specifies that incomplete results due to a TIME-LIMIT problem and due to the presence of referrals are returned.

_sendchangeevents

Specifies whether change events shall be sent. Specify one of the following keywords:

  • TRUE - send change events if change event policies are present.

  • FALSE - disable the triggering of events even if event policies are enabled.

_trimSpaces

Specifies whether leading and trailing SPACE characters of attribute values are ignored when reading records from a data file. If _trimSpaces is not defined, metacp ignores leading and trailing SPACE characters. Specify one of the following keywords:

  • TRUE - leading and trailing SPACE characters are ignored. (Default value.)

  • FALSE - leading and trailing SPACE characters are not ignored.

If _trimSpaces is FALSE SPACE characters between the attribute prefix and the attribute value in the data file are considered as part of the attribute value. However, if the attribute prefix definition in the attribute configuration file contains for example trailing SPACE characters these spaces are not considered as part of the attribute value. (See section "Prefix" in chapter "Attribute Configuration File Format" for details.)

Example:

  • The attribute prefix definition in the attribute configuration file is 'TelephoneNumber: '. (Attend to the SPACE character at the end of the prefix definition.)

  • _trimSpaces is FALSE.

  • The data file contains the following records. (The " character is not part of the record.):

    one space behind the attribute prefix but no value
    "TelephoneNumber: "
    (one space between attribute prefix and value, two trailing spaces behind the attribute value)
    "TelephoneNumber: 12345  "

metacp evaluates the following attributes and values:

  • attribute TelephoneNumber and no TelephoneNumber value

  • attribute TelephoneNumber and the value 12345 (plus two trailing spaces)

metacp_library

Holds the name of the directory in which the metacp startup scripts are stored. This variable cannot be set by the user.

When you specify script arguments on the metacp command line, the following Tcl global variables are set to the following values:

argv0

script_name

argc

number of script arguments

argv

Tcl list of script arguments

When you specify the -c option on the metacp command line, or when you do not specify any arguments or options, these Tcl global variables are set as follows:

argv0

program name of metacp as specified on the command line

argc

0

argv

An empty Tcl list (\{ })

Line Recall and Editing

You can edit a line before it is sent to metacp 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 below for line editing. For example, press and hold down the Ctrl key while pressing the A key to move to the beginning of a line.

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 the Filename Completion section.)

Ctrl j | Ctrl m

Send the completed line to metacp. (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 a 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.

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 the Filename Completion section in this chapter).

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 metacp 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, metacp 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, metacp completes the filename the name as far as readme. However, because readme could be the file named readme or the file named readme.txt, metacp cannot complete the filenames, so it beeps to signal the conflict. If you then press Esc-?, metacp 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 metacp to complete it.

Example

The following command sequence illustrates the use of metacp and Tcl commands to create an entry in a connected directory. In this example, metacp has already been invoked.

puts "create new entry"
catch { meta addentry -entry rh_LDAP } status

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

Return Values

All metacp 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, metacp returns an error message. 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, METACP (which identifies the program) and the numeric value of the error code. The following table lists the metacp error codes and error messages that can be returned

4401

error while reading abbreviation file or syntax error with respect to abbreviations, e.g. abbreviation unknown

4402

errors while converting string to internal structures and vice versa e.g. invalid attribute value

4403

Conflicting option …​

4404

Unknown option …​

4405

Missing RDN.

4406

Missing new superior.

4407

Missing object name.

4408

Missing attribute information.

4409

Missing information for the new attribute values.

4410

Missing Directory Service Agent name.

4411

Missing Presentation Service Access Point address.

4412

Missing user name.

4413

Missing password.

4414

Missing filter value.

4415

Missing scope of search.

4416

Missing time limit.

4417

Missing size limit.

4418

Missing target system.

4419

Missing arguments.

4420

Invalid time limit …​

4421

Invalid size limit …​

4422

Unknown argument …​

4423

Unable to initialize workspace.

4424

Perform bind operation first.

4425

Missing value.

4426

Format error - …​

4427

Mismatched quotes - …​

4428

Invalid parameter passed as an argument.

4429

Too many arguments.

4430

Entry not found.

4431

Subordinates not found.

4432

Insufficient memory to perform operation.

4435

Ambiguous option …​

4436

Too many values.

4437

Missing authentication type.

4438

Unknown error.

4447

Invalid argument argument_value.

4501

Wrong bind session type. (Session type is DAP session whereas LDAP session is required (or vice versa).)

4502

Missing bind id.

4503

Invalid bind id …​

4504

Latin.1/UTF8 conversion failed.

4505

Bind session identifier already in use.

4506

Missing server name.

4507

Missing server address.

4509

Missing protocol.

4510: Invalid protocol …​

4511

Cannot set "_cwo": _cwo is supported for a default DAP bind only.

4513

A structured attribute can’t be used in the sort keys of paged results. (Only relevant for DAP protocol.)

4514

Wrong syntax for sortkey(s).

4515

Paging is not possible in this state.

4517

Invalid value (either for page size or paging type PAGING (for LDAP)).

4518

Missing path name for Certificate-DB.

4519

SSL/SASL connections not supported (on SVR4).

4520

ASN.1 BER encoding failed.

4521

ASN.1 BER initialization failed.

4522

ASN.1 BER decoding failed.

4523

LDAP result control not found.

4524

Base64-decoding/encoding failed.

4525

Missing mechanism.

4526

Missing Key3DB - file name.

4527

Missing 'key3password' value.

4528

Missing 'certsubject' value.

4529

Missing parameter '-sasl'.

4601

Unknown option.

4602

Unknown argument.

4603

Invalid argument …​

4605

Unknown operation …​

4606

Missing operation.

4607

Too many arguments.

4608

Ambiguous operation.

4609

Error: Cannot unset …​

4610

Insufficient memory.

4611

Missing bind id.

4615

Conflicting option …​

4801

Operation affects multiple DSAs.

4802

An alias is encountered where an alias is not permitted.

4803

An alias is dereferenced that names an object that does not exist.

4804

ASN.1 decoding failed.

4805

ASN.1 encoding failed.

4806

Initialization of ASN.1 utility failed.

4807

Attribute or attribute value already exists.

4808

Bad argument.

4809

Bad class.

4810

Bad context.

4811

Bad name.

4812

Bad session.

4813

Bad workspace.

4814

Directory system is busy.

4815

Operation can’t be abandoned.

4816

Operation requires chaining operation mode.

4817

Problem with communication stack.

4818

DUA configuration file missing.

4819

DUA configuration file corrupted.

4820

Connection is busy.

4821

Constraint violation.

4822

DIT is inconsistent.

4823

Object already exists.

4824

Credentials expired.

4825

Fatal error.

4826

The function does not apply to the object to which it is addressed.

4827

The function was aborted by an external force.

4828

Communication problem (ICOM-attach failed).

4829

Communication problem (ICOM-detach failed).

4830

Communication problem (ICOM-receive failed).

4831

Communication problem (ICOM-send failed).

4832

Inappropriate authentication.

4833

Inappropriate matching.

4834

Initialization failed.

4835

Insufficient access rights.

4836

Operation interrupted.

4837

Invalid attribute syntax.

4838

Invalid attribute value.

4839

Invalid credentials.

4840

Invalid memory reference.

4841

Invalid signature.

4842

Invalid workspace.

4843

Loop detected while performing operation.

4844

Insufficient memory to perform operation.

4845

Fatal error.

4846

The attribute type is not included in the AVA.

4847

An attempt was made to start a synchronous operation with outstanding asynchronous operations.

4848

Naming violation.

4849

Network problems.

4850

Security error with no other information being available.

4851

Attribute or attribute value doesn’t exist.

4852

The object doesn’t exist.

4853

Operation to be abandoned doesn’t exist.

4854

Workspace doesn’t exist.

4855

Operation not allowed on non-leaf entries.

4856

Operation not allowed on RDN.

4857

Unsupported feature.

4858

Object class modification prohibited.

4859

Object class violation.

4860

Referral or partial outcome qualifier is outside the required scope.

4861

An invalid pointer supplied as a function argument.

4862

Protection required (signed operation required).

4863

Generation of signature failed.

4864

Validation of signature failed.

4865

System error.

4866

Temporary difficulty encountered.

4867

Time Limit Exceeded

4868

Abandon failed: too late.

4869

Too many outstanding operations.

4870

Too many sessions. No more session can be started.

4871

The DSA does not have the administrative authority over the particular naming context.

4872

Directory system unavailable.

4873

Critical service extension cannot be provided.

4874

Undefined attribute type passed in operation.

4875

Unexpected PDU passed/received in operation.

4876

Directory system is unwilling to perform the operation.

4877

Warning.

4878

Local abort received.

4879

Abandon received.

4880

Can’t invoke operation.

4881

Communication problem (Can’t create subscriber).

4882

Bind to DSA failed.

4883

Can’t convert DSA name of DUA configuration file.

4884

Can’t convert requestor name.

4885

Can’t convert target name of DUA configuration file.

4886

Can’t convert DSA address of DUA configuration file.

4887

Communication problem (Can’t enable binding).

4888

Communication problem (Can’t delete binding).

4889

(Unknown) error returned from DSA.

4890

Incoming authentication failed.

4891

Outgoing authentication failed.

4892

Remote abort received.

4893

(Unknown) service error.

4894

(Unknown) attribute error.

4895

(Unknown) name error.

4896

Referral returned.

4897

(Unknown) security error.

4898

Abandon failed.

4899

(Unknown) update error.

4900

Administrative Limit Exceeded

4901

Invalid query reference.

4902

Unknown error from DSA received.

4903

Reject received.

4904

Missing default DSA / LDAP server.

4905

Illegal LDAP filter.

4906

LDAP protocol error.

4907

Unknown DUA error.

4908

New superior object doesn’t exist.

4909

LDAP operation error.

4910

Offset range error.

4911

Missing sort control.

4912

Evaluation Copy expired.

Attribute Configuration File Errors

Attribute configuration file errors are returned in one of two formats:

  1. error - Error in line number number of attribute configuration file file

  2. error - Error in attribute configuration file file

The errors are listed below.

6001

Cannot open file (error format 2)

6002

Cannot read from file (error format 2)

6003

Missing quotes (error format 1)

6004

Missing attribute abbreviation (error format 1)

6005

Missing attribute name (error format 1)

6006

Missing attribute prefix (error format 1)

6007

Missing attribute suffix (error format 1)

6008

Missing structured information for an attribute (error format 1)

6009

Illegal structured information for an attribute (error format 1)

6010

Missing recurring separator (error format 1)

6011

Missing matching rule (error format 1)

6012

An abbreviation is used that is not yet defined in the attribute configuration file (error format 1)

6013

Illegal field length of an attribute (error format 1)

6014

Illegal matching rule of an attribute (error format 1)

6015

Illegal value for number of lines to be skipped (error format 1)

6016

Invalid octal value (error format 1)

6017

Duplicate abbreviation of an attribute. (error format 1)

6018

Duplicate attribute name of an attribute. (error format 1)

6019

Duplicate prefix of an attribute. (error format 1)

Command-Line Syntax Errors

The command-line syntax errors are listed below.

6050

Option option not specified (the option has not been specified, but is mandatory in this context)

6051

Attribute configuration file does not contain abbreviation abbreviation (an abbreviation has been used that is not defined in the related attribute configuration file)

6052

Unknown flag - "flag" (an invalid flag value has been specified)

6053

Invalid sort order - "order" (an invalid sort order has been specified)

6054

Invalid mark tag - "tag" (an invalid mark tag has been specified)

6055

Missing RDN (a required RDN argument has not been specified)

6056

Missing attribute information

6057

Conflicting argument - "argument"

6058

Illegal combination of flags - "string"

6059

Invalid initialization mode - "string"

Miscellaneous Error Conditions

The miscellaneous error conditions are listed below.

6100

Format error in TCL list - "list"

6101

Memory insufficient

6102

Please call meta initialize first

6103

Inappropriate file mode of handle "handle_name" (A connection handle of type FILE does not have the appropriate file mode for performing the operation)

6104

Superior information already exists (superior information has already been specified for the given DN)

6105

Superior information not found

6106

Inappropriate connected directory type of handle handle_name (the handle specified by handle_name is not of the correct subtype for performing the operation)

6107

'Add' operation failed (consult the trace file for the reason)

6108

'Remove' operation failed (consult the trace file for the reason)

6109

'Modify' operation failed (consult the trace file for the reason)

6110

'Modify-DN' operation failed (consult the trace file for the reason)

6111

Cannot write object into dump file (returned by meta writerecord)

6112

Unknown handle passed as input parameter - "handle_name"

6113

Handle is not the correct type - "handle_name"

6114

Cannot replace or delete handle. It is still used for handle "handle_name" (an attempt was made to overwrite or delete a handle that is used by one or more dependent handles)

6115

Handle name used for input and result handle - "handle_name"

6116

Operation code must be defined if only new entry is specified (a meta modifyentry operation was attempted without specifying the -oldentry option

6117

Cannot set Tcl variable array "handle___name" (consult the exception log file for the reason)

6118

Cannot get Tcl variable array "handle_name" (consult the exception log file for the reason)

6119

Cannot locate record with the given file offset

6120

Cannot determine file offset of the input data record

6121

Illegal file offset provided for index list

6122

Cannot append new elements to the already sorted index list

6123

Index list has already been sorted

6124

Invalid record (entry in data file is not in the required format)

6125

Error while skipping lines at the beginning of file "file_name"

6126

Unknown operation code "string" encountered

6127

Unknown attribute modification "string" encountered

6128

Handling of LDIF changes is not enabled

6129

Old entry must not be specified if new entry represents LDIF changes

6130

Tag specification not supported for the type of the given handle - "handle_name". (gethandle with -reset on a handle whose type is different from RESULT)

6131

Operation not supported for unsorted results

6132

Operation not supported for input handles with the LDIF change property

6133

Error while parsing LDAP name "DN-string"

6134

Name specification not supported for the type of the given handle - "handle_name"

6135

Index list is not sorted.

6136

Names have not been kept in index list.

6137

No values available for attribute 'attribute_value'

6138

Invalid component in last RDN value.

6139

Base64-decoding/encoding failed.

6141

Data file is locked.

6142

Incomplete search result returned.

6143

Sorting criteria is not a single valued attribute.

6144

Unknown encoding.

6149

Sort modes are different.

6150

Sort keys are different.

6151

Bound connections are different.

6152

Exact action flags are different.

6400

'ats initialize' has to be called first.

6402

Error while opening the protocol file.

6403

Error while reading the protocol file.

6405

Error while writing the protocol file.

6405

Illegal timeout value.

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

Logging

The meta controller uses the DirX Identity client logging configuration files dirxlog.on, dirxlog.off and dirxlog.cfg. To set up these files to log information for the meta controller, insert the following line after the tracing specification of component dir in the file install_path/client/conf/dirxlog.cfg or in the file specified in the DIRX_LOGCFG_FILE environment variable:

mdi:meta.1.9:GOESTO:dir

Supported logging levels are:

  • 0 - Disable trace logging

  • 1 - Perform entry and exit logging; at this level, all metacp functions except those which are frequently called are logged

  • 2 - Log frequently-called metacp functions as well as performing entry and exit logging

  • 9 - Log structures of functions

Here is an example of a dirxlog.cfg file; the metacp logging line is highlighted in boldface text:

dir:sys.1,sock.1,vthr.1,icom.1,shr.0,ctx.0,\
osi.1,rpc.1,ros.1,adm.1,\
sec.1,api.1,daspp.1,\
bth.1,norm.0,match.0,\
conf.1,asn1.0,util.1:BINFILE.6.2000:%s/client/log/LOG%d
mdi:meta.1.2:GOESTO:dir
FATAL:GOESTO:dir
ERROR:TEXTFILE.1.100:%s/client/log/USR%d
NOTICE:GOESTO:ERROR
WARNING:GOESTO:FATAL
NOTICE_VERBOSE:GOESTO:FATAL

Use the metacpdump program to view the contents of the generated log file.

For complete information about the logging components discussed here, see:

  • The DirX Identity Program Files chapter for a description of logging configuration file format.

  • The Environment Variables chapter for a description of the directory client program environment variables.

  • The description of metacpdump in this chapter for program usage information.

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 commands:

% metacp -c "bind; puts [show cn=naik,ou=Sales,o=pqr,c=de]"
% metacp -c "bind; catch {show cn=naik,ou=Sales,o=pqr,c=de}
result; puts $result"

print the results of a obj show operation to stdout.

Many of the metacp 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 metacp 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

If you specify the -pretty option, the return value is empty (not a Tcl list).

LDAP Session Tracking

Session Tracking was introduced to improve LDAP audit logging. For each LDAP operation, it enables the user to identify the DirX Identity component, the directory user and the client address of the computer where DirX Identity is running.

metacp supports LDAP session tracking.

If the LDAP server of the DirX Directory installation supports the Session Tracking Control, metacp provides the following information in the LDAP audit record for each operation:

  • Controls # :1
    Ctrl Type :1.3.6.1.4.1.21008.108.63.1 (Session Tracking Control)
    Critical :no
    SID-IP :IP_address_of_computer_where_metacp_is_running
    SID-Name :DXI metacp [process_ID_of_metacp_process]
    SID-Oid :1.3.6.1.4.1.21008.108.63.1.3 (Sasl-Auth-Username)
    SID-Info :user name_of_connected_user

SID-Name :DXI metacp [process_ID_of_metacp_process] helps you to identify all LDAP operations that metacp invoked. The process_ID_of_metacp_process and SID-IP :IP_address_of_computer_where_metacp_is_running identifies a single metacp process that invoked the LDAP operation.

In the following excerpt of an LDAP audit logfile the user with the common name cn=DomainAdmin,cn=MyCompany performed a bind operation over the metacp process with the process id 7596 from the computer with the IP address 10.93.25.163. Then the user performed a search and finally an unbind operation. The session tracking information identifies the user and the metacp process involved:

----------------- OPERATION 000002 ----------------
 Create Time    :Tue Sep 8 16:02:18.977999 2015
 Start Time     :Tue Sep 8 16:02:18.977999 2015
 End Time       :Tue Sep 8 16:02:18.977999 2015
 OpUUID         :400b39df-3c0e-4e74-baf8-545864b4a93a
 DapBindId      :00160008
 Concurrency    :1
 OpStackSize    :1
 OpFlow In/Out  :0/0
 Duration       :0.000000 sec
 User           :cn=DomainAdmin,cn=My-Company
 IP+Port+Sd     :[127.0.0.1]+52645+1568
 Op-Name        :LDAP_Con34_Op0
 Operation      :BIND
 Version        :3
 MessageID      :1
 Bind-Type      :simple
 Security       :normal
 DAP-Share-Count:1
 Controls #     :1
   Ctrl Type    :1.3.6.1.4.1.21008.108.63.1 (Session Tracking Control)
   Critical     :no
   SID-IP       :10.93.25.163
   SID-Name     :DXI metacp [7596]
   SID-Oid      :1.3.6.1.4.1.21008.108.63.1.3 (Sasl-Auth-Username)
   SID-Info     :cn=DomainAdmin,cn=My-Company
 Bytes Received :178
 Bytes Returned :29
 Socket Mode    :plain
 Abandoned      :no
 Result Code    :0 (success)
 Error Message  :Bind succeeded.

----------------- OPERATION 000003 ----------------
 Create Time    :Tue Sep 8 16:02:37.384999 2015
 Start Time     :Tue Sep 8 16:02:37.384999 2015
 End Time       :Tue Sep 8 16:02:37.384999 2015
 OpUUID         :ba682d7b-216e-452c-be18-ba266a70ca8e
 DapBindId      :00160008
 Concurrency    :1
 OpStackSize    :1
 OpFlow In/Out  :0/0
 Duration       :0.000000 sec
 User           :cn=DomainAdmin,cn=My-Company
 IP+Port+Sd     :[127.0.0.1]+52645+1568
 Op-Name        :LDAP_Con34_Op1
 Operation      :SEARCH
 Version        :3
 MessageID      :2
 Base Obj       :cn=My-Company
 Scope          :baselevel
 Filter         :(objectclass=PRES
 Size Limit     :0
 Time Limit     :0
 Deref Alias    :always
 Types Only     :no
 Req Attr #     :1
   Req Attr     :* (all user attributes)
 Found Entries  :1
 Found Attrs    :41
 Found Values   :50
 Controls #     :1
   Ctrl Type    :1.3.6.1.4.1.21008.108.63.1 (Session Tracking Control)
   Critical     :no
   SID-IP       :10.93.25.163
   SID-Name     :DXI metacp [7596]
   SID-Oid      :1.3.6.1.4.1.21008.108.63.1.3 (Sasl-Auth-Username)
   SID-Info     :cn=DomainAdmin,cn=My-Company
 Bytes Received :187
 Bytes Returned :1574
 Socket Mode    :plain
 Cached Result  :no
 Abandoned      :no
 Result Code    :0 (success)
 Error Message  :Search succeeded. Found 1 Entries (0 Aliases), 41 Attributes, 50 Values. (ChainedResult=no)

----------------- OPERATION 000004 ----------------
 Create Time    :Tue Sep 8 16:02:45.388000 2015
 Start Time     :Tue Sep 8 16:02:45.388000 2015
 End Time       :Tue Sep 8 16:02:45.388000 2015
 OpUUID         :873c7078-e9c1-4831-b470-e9bcbff7f153
 DapBindId      :00160008
 Concurrency    :1
 OpStackSize    :1
 OpFlow In/Out  :0/0
 Duration       :0.000000 sec
 User           :cn=DomainAdmin,cn=My-Company
 IP+Port+Sd     :[127.0.0.1]+52645+1568
 Op-Name        :LDAP_Con34_Op2
 Operation      :UNBIND
 Version        :3
 MessageID      :3
 Controls #     :1
   Ctrl Type    :1.3.6.1.4.1.21008.108.63.1 (Session Tracking Control)
   Critical     :no
   SID-IP       :10.93.25.163
   SID-Name     :DXI metacp [7596]
   SID-Oid      :1.3.6.1.4.1.21008.108.63.1.3 (Sasl-Auth-Username)
   SID-Info     :cn=DomainAdmin,cn=My-Company
 Bytes Received :139
 Bytes Returned :0
 Socket Mode    :plain
 Abandoned      :no
 Result Code    :0 (success)

See Also

ats, ldapargs, meta, obj, util