ldapexop

The LDAP extended operation tool

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 | ?] [-Y] [-Z]
-op {cascrepl | controlqueue | controlrepl | getAttributes | 
getusertype | quiesce | readconfig | 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 option 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 i5/OS 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 i5/OS 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 i5/OS 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.

-Y

Use a secure LDAP connection (TLS).

-Z

Use a secure SSL connection to communicate with the LDAP server. For Directory Server on i5/OS 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:

• 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

• 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"

• 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) : server_config_administrator directory_administrator

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

  • ¹ take effect immediately after a readconfig
  • ² take effect on new operations
  • ³ take effect as soon as the password is changed (no readconfig required)
  • ⁴ are supported by the command line utility on i5/OS, but are not supported by the Directory Server on i5/OS

  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

• 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 /bin/libback-rdbm.dll 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.