obj (metacp)

[obj] bind
    [-bindid bid]
    [-authentication auth_method]
    [-password password]
    [-user username]
    [-protocol protocol]
    [-server ldap_server_name | -address ldap_server_address]
    [-ssl]
    [-sasl]
    [-cert7path cert8_pathname]
    [-key3path key3_pathname]
    [-certsubject nickname]
    [-key3password key3_password]
    [-mechanism mechanism]
    [-status [-bindid bid1 [bid2 …​]]]

[obj] compare distinguished_name
    -attribute attribute
    [-bindid bid]

[obj] create distinguished_name
    -attribute attribute_list
    [-bindid bid]

[obj] delete distinguished_name
    [-bindid bid]

[obj] help [operation | -verbose]

[obj] list distinguished_name
    [-bindid bid]
    [-pretty]

[obj] moddn distinguished_name
    [-bindid bid]
    -rdn name_part
    [-dontdeleteoldrdn]
    [-newsuperior new_superior]

[obj] modify distinguished_name
    [-bindid bid]
    {-addattr attribute_list |
    -changeattr old_attribute new_attribute |
    -removeattr attribute_list |
    -replaceattr attribute_list}

[obj] nextpage
    [-bindid bid]
    [-conn connection_handle]
    [-exactaction]
    [-pretty]
    [-result result_handle]
    [-terminate]
    [-vafter after_count]
    [-vbefore before_count]
    [-vcontentcount content_count]
    [-voffset offset]
    [-vpagesize page_size]
    [-vvalue attribute_value]

[obj] operations

[obj] search distinguished_name
    [-bindid bid]
    [-conn connection_handle]
    [-exactaction]
    [-result result_handle]
    [-allattr |
    -alluserattr |
    -attribute abbreviation …​]
    {-baseobject |
    -onelevel |
    -subtree}
    [-filter filter]
    [-matchedvaluesonly]
    [-pretty]
    [-types]
    [-vafter after_count]
    [-vbefore before_count]
    [-vcontentcount content_count]
    [-voffset offset]
    [-vpagesize page_size]
    [-vsortkey sort_keys]
    [-vtype {SUBENTRY | SIMPLE | VLV}]
    [-vvalue attribute_value]

[obj] show distinguished_name
    [-bindid bid]
    [-allattr |
    -alluserattr |
    -attribute abbreviation …​]
    [-pretty]
    [-types]

[obj] unbind
    [-bindid bid]

A metacp object that manages entries in the directory information tree (DIT) of a Identity store via the Lightweight Directory Access Protocol (LDAP) protocol.

distinguished_name

The name of an entry to act on. Supply the complete distinguished name as follows:

distinguished_name

For example:

See the String Representation for LDAP Binds chapter for complete information on distinguished name format.

operation

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

Establishes a binding between metacp and an Identity store. The syntax depends upon the protocol type (-protocol option) and the security level to be used.

For LDAPv2 binds (-protocol LDAPv2) the following syntax must be used:

For LDAPv3 binds (-protocol LDAPv3) the following syntax must be used:

To display the status of currently established binds the following syntax must be used:

Multiple binds are supported using bind IDs and the concept of a default bind. A bind ID is a string specified in the option -bindid associated with an LDAP bind. A bind ID can be used in other metacp commands to refer to a specific LDAP bind.

A bind operation (or any other obj operation) that does not specify a bind ID opens (or refers to) a default bind. There is only one default bind at a time.

Use the -server or -address options to bind to a specific Identity store. If a Identity store is not specified with the -server or -address options, the obj bind operation searches the directory client configuration file dirxcl.cfg for the first line that matches the protocol type specified in the -protocol option. The address from this line is used to establish a bind. If the directory client configuration file dirxcl.cfg does not contain a Identity store address line, the operation performs a bind to the local Identity store.

Use the -authentication option to establish a specific authentication method. If you specify simple authentication, you must supply the -user option and the -password option. The password you supply for simple authentication is sent as clear text.

Use the -ssl option to establish Secure Socket Layer (SSL)/Transport Layer Security (TLS) for the bind operation when the -protocol option specifies LDAPv2 or LDAPv3. When you specify this option, the obj bind operation authenticates the Identity store using the certificate information in the file specified in the DIRX_TRUSTED_CA environment variable or in the install_path*/client/conf/cert8.db* certificate database, if the environment variable is not set. See SSL/TLS Certificate Database in the DirX Identity Program Files chapter for more information about SSL/TLS certificate authentication.

Use the -sasl option to establish Simple Authentication and Security Layer (SASL) client authentication and SSL/TLS for the bind operation when the -protocol option specifies LDAPv3. See the recommendations made in the document Authentication Methods for LDAP (RFC 2829) and Lightweight Directory Access Protocol (v3): Extensions for Transport Layer Security (RFC 2830) for details. The -sasl option includes the -ssl option.

When an obj bind operation is called with a specific bind ID, the operation sets the service controls for the bind to the default values; see the ldapargs modify operation for a list of default values. When an obj bind operation is called without a bind ID (a default bind), the operation sets the service controls to the default values when the LDAP protocol to be used changes. For example, the operation sets the service controls to their default values when the last default bind used LDAPv2 protocol and the default bind to be performed uses LDAPv3 protocol.

The command output is as follows:

Compares an attribute name and value with the attribute names and values of an entry in the DIT. The syntax is as follows:

[obj] compare distinguished_name
    -attribute attribute
    [-bindid bid]

-attribute attribute A required option that specifies the attribute and attribute value to compare. See the String Representation for LDAP Binds chapter for a description of attribute type and value syntax.

Use the obj compare operation to determine whether an attribute in the entry specified by distinguished_name contains a specific value. If the specified attribute contains the specified value, the operation returns the text M=TRUE (meaning Matched=TRUE); if the value is not present, it returns M=FALSE.

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

[obj] create distinguished_name
    -attribute attribute_list
    [-bindid bid]

The create operation creates a new entry in the directory information tree. The distinguished_name argument is the name of the entry to be created and must be specified as a complete distinguished name. See the String Representation for LDAP Binds chapter for a description of distinguished name syntax.

Use the -attribute option to specify the attributes to be applied to the newly created entry. You must specify the ObjectClass (objectClass) attribute as an attribute_list element; specifying additional attributes is optional. See the String Representation for LDAP Binds chapter for a complete list of the supported attribute types and attribute list formats. By default, the metacp program creates the operational attributes creation-time, creators-name, structural-object-class, and governing-structure-rule.

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

[obj] delete distinguished_name
    [-bindid bid]

The following example deletes the entry cn=Miller,ou=engineering,o=sni,c=us

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

[obj] help [operation | -verbose]

The output of the sample command is as follows:

Lists the distinguished names of the children of an entry. The syntax is as follows:

[obj] list distinguished_name
    [-bindid bid]
    [-pretty]

The obj list operation returns a Tcl list that contains the complete distinguished names of the immediate subordinates of the entry specified in distinguished_name. Use the -pretty option to return the results of the operation in a tabular, more readable format.

The following sample command lists the distinguished names of the object ou=ap11,o=sni,c=de:

The output of the sample command as follows:

Changes the last RDN of an entry or a subtree or moves an entry or subtree to a new superior. The syntax is as follows:

[obj] moddn distinguished_name
    [-bindid bid]
    -rdn name_part
    [-dontdeleteoldrdn]
    [-newsuperior new_superior]

The moddn operation changes the last relative distinguished name of an object or subtree or moves an object or subtree to a new superior. The distinguished_name argument specifies the entry or subtree to modify. See the String Representation for LDAP Binds chapter for a description of distinguished name syntax. By default, the operation removes the attributes and attribute values that do not exist in the new RDN.

When the obj moddn operation modifies a distinguished name, it automatically updates all references to the complete name that exist within a single Identity store.

In the following sample command, the entry is renamed but the old name (zahn) is kept in the new entry. The resulting cn attribute has two values: zahn and soeder, where soeder is the naming value of cn.

Changes the attribute values of an entry. The syntax is as follows:

[obj] modify distinguished_name
    [-bindid bid]
    {-addattr attribute_list |
    -changeattr old_attribute new_attribute |
    -removeattr attribute_list |
    -replaceattr attribute_list}

The modify operation changes attributes and attribute values of entries. The distinguished_name argument specifies the entry to modify. See the String Representation for LDAP Binds chapter for a description of distinguished name syntax.

Use the -addattr option to add new attributes and their attribute values to an entry or add new attribute values to an existing attribute.

Use the -changeattr option to modify values of an existing attribute. You must specify the option name and the desired values for each attribute you want to change. For example, to modify attr1 and attr2 for an entry, enter the -changeattr option twice as follows: -changeattr attr1_old attr1_new -changeattr attr2_old attr2_new

Use the -removeattr option to remove existing attribute values or remove existing attributes.

Use the -replaceattr option to replace all existing attribute values by the new attribute values.

You may combine the options addattr, changeattr, removeattr and replaceattr in any order as often as you like.

In the following sample commands, the modify operation performs the following tasks on the entry represented by the distinguished name
cn=miller,ou=sales,o=ins CO,c=us:

In the following sample commands, the modify command performs the following tasks on the entry represented by the distinguished name

Returns the next page of a search result if Simple Paging or Virual List View (VLV) is used. The syntax is as follows:

[obj] nextpage
    [-bindid bid]
    [-conn connection_handle]
    [-exactaction]
    [-pretty]
    [-result result_handle]
    [-terminate]
    [-vafter after_count]
    [-vbefore before_count]
    [-vcontentcount content_count]
    [-voffset offset]
    [-vpagesize page_size]
    [-vvalue attribute_value]

In order to avoid huge search results you can either use the Simple Paging or the Virtual List View (VLV) mechanism. VLV allows a client to specify that the server returns a contiguous subset of the search result for a given LDAP search with associated sort keys. The subset is defined in terms of offsets into the ordered list or in terms of a greater than or equal comparison value.

obj nextpage is used to return the next page of a search result once the initial search with paging has already been performed.

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

When searching a connected directory the operation creates a result handle associated with the results list and assigns the name specified in the -result option to the handle. If the -result option is not specified the results list is output to the display as a Tcl list (unless the -pretty option has been specified). The -result option cannot be combined with the -pretty option.

If the -result option is specified the -conn option is required.

Supplying the -conn option causes the obj nextpage operation to return in the search results list the set of attributes to be synchronized (SSA) specified in the connection handle.

Use the option -vpagesize to specify the maximum number of objects that should be returned in a page.

The remaining options -vbefore, -vafter, -vvalue, -voffset, and -vcontentcount are only relevant for VLV.

The options -vbefore and -vafter are required if -vpagesize is absent. The option -vbefore specifies the maximum number of objects before a target object in the page and the option -vafter specifies the maximum number of objects after that object in the page.

If the options -vbefore and -vafter are used additionally one of the following options must be used:

Use -vvalue option if the target object is defined to be the first object in the list where the attribute type is greater or equal to attribute_value. The attribute type is taken from the first element of the sort keys. The -vvalue option can be used too if -vpagesize option is set (instead of -vbefore and -vafter).

Alternatively, the parameters -voffset and optionally -vcontentcount can be used for specifying a target object that should be contained in the page. If -vcontentcount is absent then its default value 0 is used. Because an LDAP server may not have an accurate estimate of the number of entries in the list and to take into account the cases where the list size changes during the time the user browses through the list, and because the client needs a way to indicate specific list targets beginning and end, offsets within the list are transmitted between the client and the LDAP server as ratios, offset to content count. The LDAP server sends its latest estimate of the number of entries in the list (content count) to the client. Using -vcontentcount metacp sends its assumed value of the content count to the server. The LDAP server examines the content count and offset that it receives and computes the corresponding offset within the list, based on its own idea of the content count.

Example:

There are the following special cases when using the -voffset and -vcontentcount option:

Use the option -terminate if you are no longer receiving search pages from the server. That option cannot be combined with any other option. The result of this command is that the LDAP server discards the search result.

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

[obj] operations

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

The output of the sample command is as follows:

bind compare create delete list modify moddn search show unbind help operations

Searches for entries. The syntax is as follows:

[obj] search distinguished_name
    [-bindid bid]
    [-conn connection_handle]
    [-exactaction]
    [-result result_handle]
    [-allattr |
    -alluserattr |
    -attribute abbreviation …​]
    {-baseobject |
    -onelevel |
    -subtree}
    [-filter filter]
    [-matchedvaluesonly]
    [-pretty]
    [-types]
    [-vafter after_count]
    [-vbefore before_count]
    [-vcontentcount content_count]
    [-voffset offset]
    [-vpagesize page_size]
    [-vsortkey sort_keys]
    [-vtype {SUBENTRY | SIMPLE | VLV}]
    [-vvalue attribute_value]

The search operation searches for entries starting from the specified distinguished name. You must specify one of the search scope options *
-baseobject*, -onelevel, or -subtree.

By default, the operation does not search for attribute information. Use the *
-attribute* or -alluserattr options 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.

When searching a connected directory the operation creates a result handle associated with the results list and assigns the name specified in the -result option to the handle. If the -result option is not specified the results list is output to the display as a Tcl list (unless the -pretty option has been specified). The -result option cannot be combined with the -pretty option.

If the -result option is specified the -conn option is required. If the -conn option is specified the obj search attribute selection options (-allattr, -alluserattr, -attribute) cannot be specified.

If the -result option is specified then the search operation usually expects a complete result returned by the directory server (unless paging or virtual list view mode is turned on). If the directory server returns an incomplete result the synchronization TCL script’s behavior is not predictable; for example due to missing entries in the search result, objects are deleted from the directory database. The directory server however may return incomplete results if a size limit or time limit has been encountered (see ldapargs command for details) or if referrals to other servers are returned. In the event of an incomplete result the search operation returns an error “Incomplete search result returned.” (errCode: METACP 6142). If you want to process such incomplete results you must specify the TCL variable _allowpartialresult to prevent the search operation from returning an error. Then the TCL variable _partialresulttype is returned and specifies the reason why the partial result has been received. (See the introduction to metacp for details about the TCL variables _allowpartialresult and _partialresulttype.)

Supplying the -conn option causes the obj search operation to return in the search results list the set of attributes to be synchronized (SSA) specified in the connection handle. To prevent obj search from returning SSA attributes you must create a connection handle that specifies only DDN in the -attribute option, and specify this handle in the -conn option. The obj search operation then returns only entry names. In this case, you must maintain two connection handles for the connected directory: one for the directory synchronization process, and one for returning entry names without attributes in obj search operations.

In order to avoid huge search results you can either use the Simple Paging or the Virtual List View (VLV) mechanism. VLV allows a client to specify that the server returns a contiguous subset of the search result for a given LDAP search with associated sort keys. The subset is defined in terms of offsets into the ordered list or in terms or in terms of a greater than or equal comparison value.

The following sections describe how to work with these two mechanisms:

Use the option -vpagesize to specify the maximum number of objects that should be returned in a page. (If -vpagesize is not used for VLV, alternatively -vbefore and -vafter must be used.)

Use the option -vsortkey to specify the sort criterias.

The remaining options -vbefore, -vafter, -vvalue, -voffset, and -vcontentcount are only relevant for VLV.

The options -vbefore and -vafter are required if -vpagesize is absent. The option -vbefore specifies the maximum number of objects before a target object in the page and the option -vafter specifies the maximum number of objects after that object in the page.

If the options -vbefore and -vafter are used additionally one of the following options must be used:

Use -vvalue option if the target object is defined to be the first object in the list where the attribute type is greater or equal to attribute_value. The attribute type is taken from the first element of the sort keys. The -vvalue option can be used too if -vpagesize option is set (instead of -vbefore and -vafter).

Alternatively, the parameters -voffset and optionally -vcontentcount can be used for specifying a target object that should be contained in the page. If -vcontentcount is absent then its default value 0 is used. Because an LDAP server may not have an accurate estimate of the number of entries in the list, and to take into account the cases where the list size changes during the time the user browses through the list, and because the client needs a way to indicate specific list targets beginning and end, offsets within the list are transmitted between the client and the LDAP server as ratios, offset to content count. The LDAP server sends its latest estimate of the number of entries in the list (content count) to the client. Using -vcontentcount metacp sends its assumed value of the content count to the server. The LDAP server examines the content count and offset that it receives and computes the corresponding offset within the list, based on its own idea of the content count.

Example:

There are the following special cases when using the -voffset and -vcontentcount option:

Shows an entry’s contents. The syntax is as follows:

[obj] show distinguished_name
    [-bindid bid]
    [-allattr |
    -alluserattr |
    -attribute abbreviation …​]
    [-pretty]
    [-types]

Use the distinguished_name argument to specify an object to show.

By default, the operation does not return attribute information. Use the -attribute
or -alluserattr options to return selected attribute information, or use the -allattr option to return information about all attributes. If you have selected to return attribute information, the obj show operation returns attribute types and values by default. Use the -types option to limit the results returned to attribute types only.

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

The following sample command shows all attributes associated with the object represented by the distinguished name cn=Miller,ou=engeneering,o=myCompany,c=de.

The output of the sample command is as follows:

The following sample command displays a Tcl list that contains all attributes associated with the object represented by the distinguished name cn=Miller,ou=engeneering,o=myCompany,c=de.

The output of the sample command is as follows:

The following sample command displays the telephone-number attribute associated with the object represented by the distinguished name cn=Miller,ou=engeneering,o=myCompany,c=de.

The output of the sample command is as follows:

Terminates a binding between metacp and a Identity store. The syntax is as follows:

[obj] unbind
    [-bindid bid]