ldapexop

The LDAP extended operation command line utility.

Synopsis

ldapexop [-C charset] [-d debuglevel][-D binddn][-e] [-G realm] 
[-h ldaphost][-help][-K keyfile] [-m mechanism] [-N certificatename]
[-p ldapport] [-P keyfilepw] [-?] [-U] [-v] [-w passwd | ?]  [-x] [-y proxyDN]
[-Y] [-Z]
-op {acctstatus | cascrepl | clearlog |controlqueue | controlrepl | 
 controlreplerr | evaluategroups | effectpwdpolicy |  getAttributes | 
 getlogsize |  getusertype | locateEntry | onlineBackup | 
quiesce | readconfig | readlog | repltopology | resumerole | stopserver | unbind | 
uniqueattr}

Description

The ldapexop utility is a command-line interface that provides the capability to bind to a directory server and issue a single extended operation along with any data that makes up the extended operation value.

The ldapexop utility supports the standard host, port, SSL, and authentication options used by all of the LDAP client utilities. In addition, a set of options is defined to specify the operation to be performed, and the arguments for each extended operation.

To display syntax help for ldapexop, type:

ldapexop -?

or

ldapexop -help

Options

The options for the ldapexop command are divided into two categories:

  1. General options that specify how to connect to the directory server. These options must be specified before operation specific options.
  2. Extended operation option that identifies the extended operation to be performed.

General Options

These options specify the methods of connecting to the server and must be specified before the -op option.

-C charset
Specifies that the DNs supplied as input to the ldapexop utility are represented in a local character set, as specified by charset. Use the -C charset ption if the input string codepage is different from the job codepage value. Refer to the ldap_set_iconv_local_charset() API to see supported charset values.
-d debuglevel
Set the LDAP debugging level to debuglevel.
-D binddn
Use binddn to bind to the LDAP directory. binddn is a string-represented DN. When used with -m DIGEST-MD5, it is used to specify the authorization ID. It can either be a DN, or an authzId string starting with "u:" or "dn:".
-e
Displays the LDAP library version information and then exits.
-G
Specify the realm. This parameter is optional. When used with -m DIGEST-MD5, the value is passed to the server during the bind.
-h ldaphost
Specify an alternate host on which the LDAP server is running.
-help
Displays the command syntax and usage information.
-K keyfile
Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename.

If the utility cannot locate a key database, the system key database is used. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots.

This parameter effectively enables the -Z switch. For Directory Server on if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.

-m mechanism
Use mechanism to specify the SASL mechanism to be used to bind to the server. The ldap_sasl_bind_s() API is used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used. Valid mechanisms are:
  • CRAM-MD5 - protects the password sent to the server.
  • EXTERNAL - uses the SSL certificate. Requires -Z.
  • GSSAPI - uses the user's Kerberos credentials.
  • DIGEST-MD5 - requires that the client send a username value to the server. Requires -U. The -D parameter (usually the bind DN) is used to specify the authorization ID. It can be a DN, or an authzId string starting with u: or dn:.
  • OS400_PRFTKN - authenticates to the local LDAP server as the current user using the DN of the user in the system projected backend. The -D (bind DN) and -w (password) parameters should not be specified.
-N certificatename
Specify the label associated with the client certificate in the key database file. If the LDAP server is configured to perform server authentication only, a client certificate is not required. If the LDAP server is configured to perform client and server authentication, a client certificate might be required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K is specified. For Directory Server on if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.
-p ldapport
Specify an alternate TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.
-P keyfilepw
Specify the key database password. This password is required to access the encrypted information in the key database file, which can include one or more private keys. If a password stash file is associated with the key database file, the password is obtained from the password stash file, and the -P parameter is not required. This parameter is ignored if neither -Z nor -K is specified.
-?
Displays the command syntax and usage information.
–U
Specify the username. Required with -m DIGEST-MD5 and ignored with any other mechanism.
-v
Use verbose mode, with many diagnostics written to standard output.
-w passwd | ?
Use passwd as the password for authentication. Use the ? to generate a password prompt.
-x
Use FIPS mode processing (SSL/TLS only).
–y <proxyDN>
Sets a proxied ID for proxied authorization operation.
–Y
Use a secure LDAP connection (TLS).
-Z
Use a secure SSL connection to communicate with the LDAP server. For Directory Server on if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.

Extended operations option

The -op extended-op option identifies the extended operation to be performed. The extended operation can be one of the following values:

  • acctstatus: Account status extended operation. Displays the status of the specified account.
    ldapexop –op acctstatus –d <DN>
    -d DN

    Identifies the DN of the entry for which the account status is to be retrieved.

    The account status can be open, locked or expired.

  • cascrepl: cascading control replication extended operation. The requested action is applied to the specified server and also passed along to all replicas of the given subtree. If any of these are forwarding replicas, they pass the extended operation along to their replicas. The operation cascades over the entire replication topology.
    -action quiesce | unquiesce | replnow | wait
    This is a required attribute that specifies the action to be performed.
    quiesce
    No further updates are allowed, except by replication.
    unquiesce
    Resume normal operation, client updates are accepted.
    replnow
    Replicate all queued changes to all replica servers as soon as possible, regardless of schedule.
    wait
    Wait for all updates to be replicated to all replicas.
    -rc contextDn
    This is a required attribute that specifies the root of the subtree.
    -timeout secs
    This is an optional attribute that if present, specifies the timeout period in seconds. If not present, or 0, the operation waits indefinitely.

    Example:

    ldapexop -op cascrepl -action -quiesce -rc "o=acme,c=us" -timeout 60
  • clearlog | getlogsize | readlog -log ...

    These three operations support a new log file:

    LostAndFound

    These operations can be used with the directory server ( 6.1 and later), but only certain log files are supported:

    LostAndFound – the replication conflict log file

  • controlqueue: control queue replication extended operation. This operation allows you to delete or remove pending changes from the list of replication changes that have queued up and were not run because of replication failures. This operation is useful when the replica data is manually fixed. You would then use this operation to skip doing some of the queued up failures.
    -skip all | change-id
    This is a required attribute.
    • -skip all indicates to skip all pending changes for this agreement.
    • change-id identifies the single change to be skipped. If the server is not currently replicating this change, the request fails.
    -ra agreementDn
    This is a required attribute that specifies the DN of the replication agreement.

    Examples:

    ldapexop -op controlqueue -skip all -ra "cn=server3,
             ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,
             o=acme,c=us"

ldapexop -op controlqueue -skip 2185 -ra "cn=server3,
             ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,
             o=acme,c=us"
  • controlrepl: control replication extended operation
    -action suspend | resume | replnow
    This is a required attribute that specifies the action to be performed.
    -rc contextDn | -ra agreementDn
    The -rc contextDn is the DN of the replication context. The action is performed for all agreements for this context. The -ra agreementDn is the DN of the replication agreement. The action is performed for the specified replication agreement.

    Example:

    ldapexop -op controlrepl -action suspend -ra "cn=server3,
             ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,
             o=acme,c=us"
  • controlreplerr

    The controlreplerr extended operation allows you to manage the replication error table on an i5/OS 6.1(or IBM® Tivoli® Directory Server v6.0) or later server. The options are:

    ldapexop -op controlreplerr –show <failure_ID> -ra <agreementDN>

    It allows you to view entries in the replication error table

    <failure_ID>
    The ID of the failure. Specify 0 to show all entries.
    <agreementDN>
    The replication agreement which the entry is associated with.
    ldapexop -op controlreplerr –delete <failure_ID> -ra <agreementDN>

    It allows you to delete entries from the replication error table

    <failure_ID>
    The ID of the failure. Specify 0 to show all entries.
    <agreementDN>
    The replication agreement which the entry is associated with.
    ldapexop -op controlreplerr –retry <failure_ID> -ra <agreementDN>

    It allows you to retry an entry in the replication error table

    <failure_ID>
    The ID of the failure. Specify 0 to show all entries.
    <agreementDN>
    The replication agreement which the entry is associated with.
  • • effectpwdpolicy

    A new effectpwdpolicy operation is supported by the ldapexop utility:

    ldapexop –op effectpwdpolicy –d < user DN or a group DN>

    This extended operation queries the effective password policy of a user or a group.

    Examples:

    ldapexop -D  <adminDN> -w <adminPW> -op effectpwdpolicy -d cn=Bob Garcia,ou=austin,
o=sample
  • evaluateGroups

    A new evaluateGroups operation is supported by the ldapexop utility:

    ldapexop –op evaluateGroups –d userDN –a <list of attribute and value pairs each 
separated by a space>

    It displays a list of groups the specified userDN belongs to.

    The "–a" option is used to specify attribute values for the entry and retrieve dynamic groups which match this entry. If the "–a" option is not specified the request will be sent to the server for only the static groups. This extended operation is used to retrieve group membership information for a userDN which does not exist on the server (For example, the userDN represents a remote group member). The ibm-allGroups operational attribute should be used to list group memberships for the server containing the userDN.

    Example:

    To evaluate the group membership for entry uid=sample,cn=users,o=ibm based on the departmentnumber and objectclass attribute values of the entry:

    ldapexop -op evaluateGroups -d uid=sample,cn=users,o=ibm -a objectclass=person 
departmentnumber=abc
    Note: Typically this extended operation would be given all the attribute values for the entry of interest.
  • getattributes -attrType<type> -matches bool<value>
    -attrType {operational | language_tag | attribute_cache | unique | configuration}
    This is a required attribute that specifies type of attribute being requested.
    -matches bool {true | false}
    Specifies whether the list of attributes returned matches the attribute type specified by the -attrType< option.

    Example:

    ldapexop -op getattributes -attrType unique -matches bool true

    Returns a list of all attributes that have been designated as unique attributes.

    ldapexop -op getattributes -attrType unique -matches bool false

    Returns a list of all attributes that have been not been designated as unique attributes.

  • getusertype: request user type extended operation

    This extended operation returns the user type based on the bound DN.

    Example:

    ldapexop -D <AdminDN> -w <Adminpw> -op

    getusertype returns:

    User : root_administrator
Role(s) : audit_administrator directory_data_administrator password_administrator 
          replication_administrator schema_administrator server_config_administrator 
          server_start_stop_administrator

    For an administrative group member who is assigned "ReplicationAdmin" and "ServerStartStopAdmin" roles , the output of the extended operation will be:

    User : admin_group_member
Role(s) : replication_administrator server_start_stop_administrator
    If "No Administrator" role is assigned for an administrative group member, the output of this extended operation will be: 
    User    : admin_group_member
Role(s) : no_administrator
  • locateEntry

    A new locateEntry operation is supported by the ldapexop utility: ldapexop –op locateEntry -d "DN" | -f "<file Name containing DN list> " [ -c ] This extended operation is used to extract the back-end server details of a given set of entry DNs and provide the details to the client. To extract the details of a single entry DN the -d option is used. To extract details of a set of DNs, place the entire set of DNs in a file and use the -f option to pass the file to ldapexop operation.

    Example
    ldapexop -D <binddn> -w <bindpw> -op locateEntry -d "cn=user,o=sample"
  • onlineBackup
    A new onlineBackup operation is supported by the ldapexop utility:
    ldapexop –op onlineBackup -path <directoryPath>
    This extended operation performs an online backup of the directory server instance's DB2 database.
    Example
    ldapexop -D <bindDN> -w <bindpw> -op onlineBackup -path <directoryPath>
    Note: This operation is supported by the command line utility on IBM i, but are not supported by the Directory Server on IBM i
  • resumerole
    A new resumerole operation is supported by the ldapexop utility:
    ldapexop –op resumerole -type <typeValue>
    This extended operation enables the proxy server to resume the configured role of a back-end server in the distributed directory environment. 
    -type {all | partition <partitionName> | server <serverName> | 
serverinapartition <serverName> <partitionName>}
    Options are:
    all
    resumes roles for all back-end servers
    partition <partitionName>
    resumes the role of all back-end servers in the partition
    server <serverName>
    resumes the role of the back-end server for all partitions that it is in
    serverinapartition <serverName> <partitionName>
    resumes the role of the back-end server in the specified partition

    Example:

    ldapexop -op resumerole -type all
    Note: This operation is supported by the command line utility on IBM i, but are not supported by the Directory Server on IBM i
  • stopserver
    A new stopserver operation is supported by the ldapexop utility:
    ldapexop –op stopserver -type <typeValue>
    Example:
    ldapexop -D <admindn> -w <adminpw> -op stopserver
    Note: This operation is supported by the command line utility on IBM i, but is not supported by the Directory Server on IBM i
  • quiesce: quiesce or unquiesce subtree replication extended operation
    -rc contextDn
    This is a required attribute that specifies the DN of the replication context (subtree) to be quiesced or unquiesced.
    -end
    This is an optional attribute that if present, specifies to unquiesce the subtree. If not specified the default is to quiesce the subtree.

    Examples:

    ldapexop -op quiesce -rc "o=acme,c=us"

ldapexop -op quiesce -end -rc "o=ibm,c=us"
  • readconfig: reread configuration file extended operation
    -scope entire | single<entry DN><attribute>
    This is a required attribute.
    • entire indicates to reread the entire configuration file.
    • single means to read the single entry and attribute specified.

    Examples:

    ldapexop -op readconfig -scope entire

ldapexop -op readconfig -scope single "cn=configuration" ibm-slapdAdminPW
    Note: The following entries marked with:
    • 1 take effect immediately after a readconfig
    • 2 take effect on new operations
    • 3 take effect as soon as the password is changed (no readconfig required)
    • 4 are supported by the command line utility on , but are not supported by the Directory Server on 
    cn=Configuration
ibm-slapdadmindn2
ibm-slapdadminpw2, 3
ibm-slapderrorlog1, 4
ibm-slapdpwencryption1
ibm-slapdsizelimit1
ibm-slapdsysloglevel1, 4
ibm-slapdtimelimit1

cn=Front End, cn=Configuration
ibm-slapdaclcache1
ibm-slapdaclcachesize1
ibm-slapdentrycachesize1
ibm-slapdfiltercachebypasslimit1
ibm-slapdfiltercachesize1
ibm-slapdidletimeout1

cn=Event Notification, cn=Configuration
ibm-slapdmaxeventsperconnection2
ibm-slapdmaxeventstotal2

cn=Transaction, cn=Configuration
ibm-slapdmaxnumoftransactions2
ibm-slapdmaxoppertransaction2
ibm-slapdmaxtimelimitoftransactions2


cn=ConfigDB, cn=Config Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration
ibm-slapdreadonly2

cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration
ibm-slapdbulkloaderrors1, 4
ibm-slapdclierrors1, 4
ibm-slapdpagedresallownonadmin2
ibm-slapdpagedreslmt2
ibm-slapdpagesizelmt2
ibm-slapdreadonly2
ibm-slapdsortkeylimit2
ibm-slapdsortsrchallownonadmin2
ibm-slapdsuffix2
  • repltopology -rc [options]:

    The repltopology extended operation is used to make the replication topology information on a consumer server match the topology on the supplier server.

    ldapexop –op repltopology –rc  [-timeout secs] [-ra agreementDn]

    where

    -rc contextDn
    This is a required attribute that specifies the root of the subtree.
    -timeout secs
    This is an optional attribute that if present, specifies the timeout period in seconds. If not present, or 0, the operation waits indefinitely.
    -ra agreementDn
    The -ra agreementDn is the DN of the replication agreement. The action is performed for the specified replication agreement. If the -ra option is not specified, the action is performed for all the replication agreements defined under the context.

    Example:

    ldapexop -op repltopology -rc "o=acme,c=us" -ra "cn=server3,
          ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,
          o=acme,c=us"-timeout 60

    The supplier server binds to the consumer server using the configured replication credentials. Supplier DNs have authority to add suffixes to a consumer (replica) server's configuration supplier. This is used by a supplier server as part of the Replication Topology extended operation to add missing suffixes to the consumer server. For suffixes for which the contextDN entry does not yet exist, supplier DNs have authority to create a new replicated subtree. If the contextDN entry already exists, it must already be defined as the root of a replicated subtree; i.e. it must have the ibm-replicationcontext object class.

  • unbind {-dn<specificDN>| -ip<sourceIP> | -dn<specificDN> -ip<sourceIP> | all}:

    disconnect connections based on DN, IP, DN/IP or disconnect all connections. All connections without any operations and all connections with operations on the work queue are ended immediately. If a worker is currently working on a connection, it is ended as soon as the worker completes that one operation.

    -dn<specificDN>
    Issues a request to end a connection by DN only. This request results in the purging of all the connections bound on the specified DN.
    -ip<sourceIP>
    Issues a request to end a connection by IP only. This request results in the purging of all the connections from the specified IP source.
    -dn<specificDN> -ip<sourceIP>
    Issues a request to end a connection determined by a DN/IP pair. This request results in the purging of all the connections bound on the specified DN and from the specified IP source.
    -all
    Issues a request to end all the connections. This request results in the purging of all the connections except the connection from where this request originated. This attribute cannot be used with the -D or -IP. attributes

    Examples:

    ldapexop -op unbind -dn cn=john
ldapexop -op unbind -ip 9.182.173.43
ldapexop -op unbind -dn cn=john -ip 9.182.173.43
ldapexop -op unbind -all
  • uniqueattr -a <attributeType>: identify all nonunique values for a particular attribute.
    -a <attribute>
    Specify the attribute for which all conflicting values are listed.
    Note: Duplicate values for binary, operational, configuration attributes, and the objectclass attribute are not displayed. These attributes are not supported extended operations for unique attributes.

    Example:

    ldapexop -op uniqueattr -a "uid"
    The following line is added to the configuration file under the "cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=schema,cn=Configuration" entry for this extended operation: 
    ibm-slapdPlugin: extendedop /QSYS.LIB/QGLDRDBM.SRVPGM initUniqueAttr

Diagnostics

Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.