ldapcompare utility

Purpose

The ldapcompare utility provides an interface to the ldap_compare() API.

The ldapcompare utility opens a connection to an LDAP server, binds, and does one or more compares for an attribute value in an entry. The input consists of a distinguished name (DN) and an attribute type and value to compare. For each set of input, a comparison is performed for the specified attribute in the entry with that DN. If the DN and attribute type and value are not provided, the input is read from standard input or from file if the -f option is used, and two lines of input are read for each comparison. The first line contains the DN and the second line contains the attribute type and value.

Format

ldapcompare [options] [dn attr=value]...

Parameters

options

Table 1 shows the options you can use for the ldapcompare utility:

Table 1. ldapcompare options
Option	Description
-?	Print this text.
-c	Continuous operation mode. Errors are reported, but ldapcompare continues with comparisons. The return code from the utility is determined by the last comparison. The default is to exit after reporting an error.
-d debugLevel	Specify the level of debug messages to be created. The debug level is specified in the same fashion as the debug level for the LDAP server. See Table 1 for the possible values for debugLevel. The default is no debug messages.
-D bindDN	Use bindDN to bind to the LDAP directory. This option should be a string-represented DN. The default is a `NULL` string. If the -S or -m option is equal to `DIGEST-MD5` or `CRAM-MD5`, this option is the authorization DN that is used for making access checks. This directive is optional when used in this manner.
-f file	Read the compare input from file instead of from standard input or the command line (by specifying dn and attr=value). An LDAP compare is performed for every set of two lines in the file. The first line in the set specifies the DN of the entry to compare. The second line contains the attr=value specification, indicating the attribute and value to compare. Do not put double quotation marks around the DN or attribute values in the file. You can specify a partitioned or sequential data set for file on the -f option. See Specifying a value for a file name for more information.
-g realmName	Specify the realm name to use when doing a `DIGEST-MD5` bind. This option is required when multiple realms are passed from an LDAP server to a client as part of a `DIGEST-MD5` challenge; otherwise, it is optional.
-h ldapHost	Specify the host name or IP address on which the LDAP server is running. The default is the local host.
-K keyFile	Specify the name of the System SSL key database file, RACF® key ring, or PKCS #11 token. If this option is not specified, this utility looks for the presence of the `SSL_KEYRING` environment variable with an associated name. If keyFile is specified as `TOKEN/NAME`, then System SSL uses the specified PKCS #11 token. Otherwise, System SSL uses a key database file or a RACF key ring. In this case, System SSL first assumes that keyFile is a key database file name and tries to locate the file. If keyFile is not a fully-qualified z/OS® UNIX System Services file name, the current directory is assumed to contain the key database file. The name cannot be a partitioned or sequential data set. If System SSL cannot locate the file, it then assumes that keyFile is a RACF key ring name. See SSL/TLS information for LDAP client utilities for information about System SSL key databases, RACF key rings, and PKCS #11 tokens. This option is ignored if -Z is not specified.
-m mechanism	See the description of the -S option.
-M	Manage referral objects as normal entries. This requires a protocol level of 3.
-n	Show what would be done, but do not actually compare entries. Useful for debugging with -v.
-N keyFileDN	Specify the label associated with the certificate in the System SSL key database, RACF key ring, or PKCS #11 token. This option is ignored if -Z is not specified
-p ldapPort	Specify the TCP port where the LDAP server is listening. The default LDAP non-secure port is 389 and the default LDAP secure port is 636.
-P keyFilePW	Specify either the key database file password or the file specification for a System SSL password stash file. When the stash file is used, it must be in the form `file://` followed immediately (no blanks) by the file system file specification (for example, `file:///etc/ldap/sslstashfile`). The stash file must be a z/OS UNIX System Services file and cannot be a partitioned or sequential data set. This option is ignored if -Z is not specified.
-R	Do not automatically follow referrals.
-S mechanism or -m mechanism	Specify the bind method to use. You can use either -m or -S to indicate the bind method. Specify `GSSAPI` to indicate a Kerberos Version 5 bind is requested, `EXTERNAL` to indicate that a certificate (SASL external) bind is requested, `CRAM-MD5` to indicate that a SASL Challenge Response Authentication Mechanism bind is requested, or `DIGEST-MD5` to indicate a SASL digest hash bind is requested. The `GSSAPI` method requires a protocol level of 3 and the user must have a valid Kerberos Ticket Granting Ticket in their credentials cache by using the Kerberos kinit command line utility. The `EXTERNAL` method requires a protocol level of 3. You must also specify -Z, -K, and -P to use certificate bind. If there is no default certificate in the key database file, RACF key ring, or PKCS #11 token or a certificate other than the default must be used, use the -N option to specify the label of the certificate. The `CRAM-MD5` method requires a protocol level of 3. The -D or -U option must be specified. The `DIGEST-MD5` method requires a protocol level of 3. The -U option must be specified. Optionally, the -D option can be used to specify the authorization DN. If -m or -S is not specified, a simple bind is performed.
-U userName	Specify the user name for `CRAM-MD5` or `DIGEST-MD5` binds. The userName is a short name (for example, the uid attribute value) that is used to perform bind authentication. This option is required if the -S or -m option is set to `DIGEST-MD5`.
-v	Use verbose mode, with many diagnostics written to standard output.
-V version	Specify the LDAP protocol level the client should use. The value for version can be 2 or 3. The default is 3.
-w passwd	Use passwd as the password for simple, `CRAM-MD5`, and `DIGEST-MD5` authentication. The default is a `NULL` string.
-x `sslFipsMode`	Specify FIPS mode for SSL/TLS protected connections. The supported FIPS modes are `LEVEL1, LEVEL2, LEVEL3,` and `OFF`. When FIPS mode is enabled, it is more restrictive regarding cryptographic algorithms, protocols, and key sizes that can be supported. If this option is not specified, the FIPS mode is set to `OFF`. This option is ignored if -Z is not specified.
-Z	Use a secure connection to communicate with the LDAP server. Secure connections expect the communication to begin with the SSL/TLS handshake. The -K keyFile option or equivalent environment variable is required when the -Z option is specified. The -P keyFilePW option is required when the -Z option is specified and the key file specifies a file system key database file. Unless you want to use the default certificate in the key database file, RACF key ring, or PKCS #11 token, use the -N option to specify the label of the certificate.

dn

Specify the DN of the entry to compare.

attr=value

Specify the attribute type and the value to compare. An error is returned if the entry does not contain the attribute to be compared.

All other command line inputs result in a syntax error message, after which the correct syntax is displayed. If the same option is specified multiple times or if both -m and -S are specified, the last value specified is used.

Examples

Following are some ldapcompare examples:

The following command compares the sn attribute within the entry named cn=Compare Me, o=My Company, c=US. The command returns true if the sn attribute value is Smith and false if it is not.
```
ldapcompare "cn=Compare Me, o=My Company, c=US" sn=Smith
```
The following example uses file input to compare the telephonenumber attribute within the entry named cn=ken, o=My Company, c=US and to compare the description attribute within the entry named cn=jay, o=My Company, c=US. A separate result is returned for each comparison. Assume that /tmp/compareFile contains:
```
cn=ken, o=My Company, c=US
telephonenumber=123-456-7890
```
```
cn=jay, o=My Company, c=US
description=LDAP development
```
The following command performs the comparisons:
```
ldapcompare -f /tmp/compareFile
```
For z/OS LDAP support for RACF access, the following command determines if the OMVS UID of RACF user u1 is 123. It is assumed that the z/OS LDAP support for RACF access suffix is sysplex=sysplexa.
```
ldapcompare -D racfid=admin1,profiletype=user,sysplex=sysplexa -w passwd
    "racfid=u1,profiletype=user,sysplex=sysplexa" racfomvsuid=123
```

Notes

If no dn and attr=value arguments are provided and the -f option is not used, the ldapcompare command waits to read a list of DNs and attribute types and values from standard input. To break out of the wait, press the Ctrl+C keys or the Ctrl+D keys.

The LDAP_DEBUG environment variable can be used to set the debug level. For more information about specifying the debug level using keywords, decimal, hexadecimal, and plus and minus syntax, see Enabling tracing.

You can specify an LDAP URL for ldapHost on the -h option. See ldap_init() for more information.

For information about SSL/TLS, see SSL/TLS information for LDAP client utilities.

Diagnostics

Exit status is 5 (LDAP_COMPARE_FALSE) or 6 (LDAP_COMPARE_TRUE) if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.