Sun Directory Server Enterprise Edition 7.0 Man Page Reference

User Commands

authrate(1)

Name

authrate– measure rate of authentication to an LDAP directory

Synopsis

install-path/dsrk/bin/authrate 
 [options]

Description

The authrate command measures the rate at which a given bind DN can authenticate to an LDAP directory. As with all measures of performance, results depend on many factors, including what options you pass to the authrate command, and also how the directory service itself is tuned.

The command uses LDAP v3, and cannot be used to authenticate to an LDAP v2 directory not supporting LDAP v3.

Options

The authrate command supports the following options:

-C messages

Display the specified number of results messages before exiting. Results messages appear by default as output on standard out, similar to the following:

Avg r=2584.00/thr (516.80/sec), total=  7752

This shows output for three threads authenticating for five seconds. The average bind rate per thread is 516.80 per thread per second for the interval measured. The total shown for all threads is 7752.

Default is to continue iterating until the command is interrupted.

-D bindDN

Use the specified bind DN to authenticate to the directory.

If the bind DN is not specified, the authrate command attempts anonymous authentication.

You can use %d and %s placeholders in the —D option in the authrate command. Refer to Extended Description for more details.

-h hostname

Connect to the directory on the specified host.

Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

Default is to connect to the local host on the loopback address, 127.0.0.1.

-i filename

Use the file specified to read bind DNs and passwords at random.

Refer to Random Bind DN Syntax and Random Bind DN Substitution for details.

-j seconds

Display results each specified number of seconds.

Default is to display results every 5 seconds.

-k

Keep connections open, measuring only the time required to perform the bind operation.

Default is to measure both the bind and unbind time as part of the authentication sequence.

-m maxAuth

Perform no more than the specified number of binds per thread.

Default is for each thread to continue iterating until the command is interrupted.

-p port

Connect to the directory on the specified port.

Default is to connect to the default simple authentication port for LDAP, 389.

-q

Run in quiet mode, not displaying results.

Default is to display results every 5 seconds, which you can adjust using the -j option.

-r maxRand

Use the specified maximum to determine the range for random numbers replacing %d formatting specifications when authenticating with random bind DNs and passwords.

When you use this option twice, the first occurrence generates random numbers in the range [0,maxRand1–1] for the first %d, the second [1,maxRand2] for the second %d.

-S randSeed

Use the specified seed, an unsigned int, for random number generation.

Default seed is 0.

-t threads

Use the specified number of the threads to connect to the server.

Default is to use one thread.

-u

Do not unbind as part of the authentication sequence.

Default is to unbind as part of the authentication sequence.

-v

Display verbose output.

-W filename

Read the bind password from the specified file.

-w password

Use the specified bind password to authenticate to the directory.

-w –

Prompt for the bind password so it does not appear on the command line or in a file.

Extended Description

The authrate command repeatedly initializes a connection and binds to a directory server, without performing any other operation. Threads may be configured to keep open connections and perform LDAP binds repeatedly. The command-line options let you specify the bind credentials.

The command uses LDAP v3, and cannot be used to authenticate to an LDAP v2 directory not supporting LDAP v3. Furthermore, the authrate command uses simple authentication, not secure binding.

By default, the authrate command attempts to bind indefinitely, displaying results periodically, and displaying any errors encountered as well without interrupting operation.

To simulate real use conditions and reduce any artifacts due to the repetitive nature of the tests, the authrate command provides a mechanism for generating a random bind DN for authentication.

Random Bind DN Syntax

Include randomly generated numbers by specifying %d and %s placeholders in the bind DN and the bind password. These placeholders are then replaced according to the following rules:

%d

Replace this placeholder with random integer values depending on the maxRand parameter to the -r option.

The -r option may be used at most two times to generate random bind DNs. When used in the bind DN, replacement values for the %d placeholder range over [0,maxRand1-1] for the first use of the -r option, and over [1,maxRand2] for the second.

The %d may be used up to eight times to generate a random password. When used in the bind password, replacement values for the %d placeholder range over [0,maxRand1-1] for each use of the -r option.

When the the number of %d placeholders exceeds the number of -r options, only one value for each use of the -r option is generated. Each %d placeholder is replaced with a generated value.

%s

Replace this placeholder with random strings from the file specified using the -i option.

Replacement values for this placeholder are randomly selected lines of the file specified.

Random Bind DN Substitution

The authrate command requires that you apply the following rules for substitutions, displaying an error message when the used incorrectly:

Use only one type of placeholder, either %d or %s, per invocation of the authrate command.
Use %%d and %%s to specify literal strings %d and %s, respectively.

In order to use this random authentication mechanism, you must populate your directory accordingly. For example, you can measure the authentication rate using the following command:

$ authrate -D "uid=test%d,ou=test,dc=example,dc=com" -w "auth%d%d" -r 100

In order for the authrate command to bind effectively, your directory must contain entries corresponding to the following LDIF excerpt:

dn: uid=test0,ou=test,dc=example,dc=com
userPassword: auth00

dn: uid=test1,ou=test,dc=example,dc=com
userPassword: auth11

dn: uid=test2,ou=test,dc=example,dc=com
userPassword: auth22
…

dn: uid=test10,ou=test,dc=example,dc=com
userPassword: auth1010
…

dn: uid=test99,ou=test,dc=example,dc=com
userPassword: auth9999

Examples

Examples in this section use the following conventions:

The authrate command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port 389, the default for non-SSL connections.

Example 1 `authrate`: Sample Output

The following command performs anonymous binds until it has displayed five results messages. Notice that each line concerns only the elapsed interval.

$ authrate -C 5
Avg r=1952.00/thr (390.40/sec), total=  1952
Avg r=1937.00/thr (387.40/sec), total=  1937
Avg r=1938.00/thr (387.60/sec), total=  1938
Avg r=1921.00/thr (384.20/sec), total=  1921
Avg r=1921.00/thr (384.20/sec), total=  1921
All threads exited

Notice also that a result message provides the following items of information:

The average rate of authentication per thread of execution
The average rate of authentication per second
The total number of authentication operations performed during the interval the results message concerns

Example 2 `authrate`: Two Threads

The following command performs anonymous binds until it has displayed five results messages, using three threads to bind. Notice that each line concerns only the elapsed interval.

$ authrate -C 5 -t 3
Avg r= 300.00/thr (180.00/sec), total=   900
Avg r= 300.00/thr (180.00/sec), total=   900
Avg r= 299.67/thr (179.80/sec), total=   899
Avg r= 298.00/thr (178.80/sec), total=   894
Avg r= 299.33/thr (179.60/sec), total=   898
All threads exited

Here the average per thread, approximate 300 binds, is shown for each interval of three seconds. The averages given in parentheses, approximately 180 per second, represent the average bind rate over the interval. The totals shown represent the total number of binds over the interval.

Example 3 `authrate`: Full Authentication Rate

The following command applies the mechanism described in Random Bind DN Substitution, performing full authentication (open, bind, unbind, close) with randomly generated bind DNs and passwords.

$ authrate -D "uid=test%d,ou=test,dc=example,dc=com" -w "auth%d%d" -r 100 -C 5
Avg r=1301.00/thr (260.20/sec), total=  1301
Avg r=1307.00/thr (261.40/sec), total=  1307
Avg r=1281.00/thr (256.20/sec), total=  1281
Avg r=1316.00/thr (263.20/sec), total=  1316
Avg r=1313.00/thr (262.60/sec), total=  1313
All threads exited

Example 4 `authrate`: Bind Rate Alone

The following command applies the mechanism described in Random Bind DN Substitution, keeping the connection open and binding repeatedly with randomly generated bind DNs and passwords.

$ authrate -D "uid=test%d,ou=test,dc=example,dc=com" -w "auth%d%d" -r 100 -k -C 5
Avg r=2584.00/thr (516.80/sec), total=  2584
Avg r=2603.00/thr (520.60/sec), total=  2603
Avg r=2592.00/thr (518.40/sec), total=  2592
Avg r=2613.00/thr (522.60/sec), total=  2613
Avg r=2560.00/thr (512.00/sec), total=  2560
All threads exited

Exit Status

The authrate command returns the following exit status codes.

0: Successful completion.
non-zero: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

dsmlmodify(1)

Name

dsmlmodify– add, modify, rename, move, or delete directory entries

Synopsis

install-path/dsrk/bin/dsmlmodify 
-h hostURL [options] -f filename

Description

The dsmlmodify command requests the addition, modification, rename, move, or deletion of entries stored in a directory accessible through Directory Services Markup Language (DSML) v2.

You must specify additions and modifications in the proper order, because the directory performs the updates in the order you request them. For example, to add entries to a subtree that does not yet exist, you must first update the base entry at the root of the subtree before adding entries under the base entry.

Options

The dsmlmodify command supports the following options:

-D user-identifier

Use the specified user identifier to authenticate.

The user identifier is the HTTP-layer identifier. The HTTP-layer identifier is typically mapped to an account in the directory. For example, if the uid value is used for HTTP-layer authentication, which maps in the directory to bind DN dn:uid=user-identifier,ou=people,dc=example,dc=com, then the dsmlmodify -D bjensen command would end up using permissions for directory operations based on the permissions for the account with entry DN uid=bjensen,ou=people,dc=example,dc=com. The user-identifier thus depends closely on the identity mapping between the HTTP layer and the LDAP layer.

If the user identifier and its password are omitted, the dsmlmodify command binds anonymously. The user identifier determines what entries and attributes the user can modify, according to the permissions for the user.

-f filename

Read the modifications from a file using DSML syntax.

The following content for example allows modification of Barbara Jensen's password:

<modifyRequest dn="uid=bjensen,ou=people,dc=example,dc=com">
<modification name="userpassword" operation="replace">
<value>newpassword</value>
</modification>
</modifyRequest>

-h hostURL

Use the specified URL to access the directory.

The host URL takes the form http://host:port where host represents the host on which the directory runs, and port is the port on which the directory listens for DSML requests.

-j filename

Read the bind password for simple HTTP authentication from the specified file.

-w –

Prompt for the bind password for simple HTTP authentication.

-w password

Use the specified bind password for simple HTTP authentication.

Examples

Examples in this section use the following conventions:

The dsmlmodify command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory server listens for DSML requests over HTTP on port 8080.

Example 1 `dsmlmodify`: Adding an Entry

The following commands demonstrate adding an entry:

$ cat add.dsml
<addRequest dn="uid=ajohnson,ou=people,dc=example,dc=com">
   <attr name="objectclass"><value>top</value></attr>
   <attr name="objectclass"><value>person</value></attr>
   <attr name="objectclass"><value>organizationalPerson</value></attr>
   <attr name="objectclass"><value>inetOrgPerson</value></attr>
   <attr name="uid"><value>ajohnson</value></attr>
   <attr name="sn"><value>Johnson</value></attr>
   <attr name="cn"><value>Alice</value></attr>
   <attr name="mail"><value>alice.johnson@example.com</value></attr>
   <attr name="userPassword"><value>weakness</value></attr>
</addRequest>
$ dsmlmodify -h http://host:8080 -D hmiller -w - -f add.dsml
Enter bind password:
…

If you read Example.ldif, you see that hmiller's password is hillock.

Example 2 `dsmlmodify`: Modifying an Entry

The following commands demonstrate modifying an entry:

$ cat mod.dsml
<modifyRequest dn="uid=bjensen,ou=people,dc=example,dc=com">
<modification name="userpassword" operation="replace">
<value>newpassword</value>
</modification>
</modifyRequest>
$ dsmlmodify -h http://host:8080 -D bjensen -w - -f mod.dsml
Enter bind password:
…

If you read Example.ldif, you see that the bjensen's password is hifalutin.

Example 3 `dsmlmodify`: Deleting an Entry

The following commands demonstrate deleting an entry:

$ cat del.dsml
<delRequest dn="uid=ajohnson,ou=people,dc=example,dc=com" />
$ dsmlmodify -h http://host:8080 -D hmiller -w - -f del.dsml
Enter bind password:
…

If you read Example.ldif, you see that hmiller's password is hillock.

Example 4 `dsmlmodify`: Renaming an Entry

The following commands demonstrate renaming an entry:

$ cat rdn.dsml
<modDNRequest
  dn="uid=ajohnson,ou=people,dc=example,dc=com"
  newrdn="uid=aweiss"
  deleteoldrdn="true"
  newSuperior="ou=people,dc=example,dc=com"/>
$ dsmlmodify -h http://host:8080 -D hmiller -w - -f rdn.dsml
Enter bind password:
…

If you read Example.ldif, you see that hmiller's password is hillock.

Exit Status

Exit status values are returned as part of the response, including both the code and the description as described in the DSML v2 standard. Common exit status codes follow:

0: Successful completion; success.
1: Server encountered errors while processing the request; operationsError.
2: Server encountered errors while processing the request; protocolError.
10: Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; referral.
16: Attribute to be modified does not exist; noSuchAttribute.
19: Attribute modification requested is not a proper modification. For example, a requested change to userpassword would result in a user password shorter than the minimum length allowed; constraintViolation.
20: Attribute to add already exists with specified value; attributeOrValueExists.
21: In response to a request to modify directory schema, the requested modification includes no object class or attribute type specification; invalidAttributeSyntax.
32: Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; noSuchObject.
50: Bind DN user does not have permission to read the entry from the directory; insufficientAccessRights.
53: Directory is read-only; unwillingToPerform.
65: Requested modification would cause the entry not to comply with the schema; objectClassViolation.
67: Requested modification would cause the entry to be missing attributes that are components of the entry DN; notAllowedOnRDN.
68: An entry already exists with the same DN as the entry to add; entryAlreadyExists.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

dsmlsearch(1)

Name

dsmlsearch– find directory entries

Synopsis

install-path/dsrk/bin/dsmlsearch 
-h hostURL -b baseDN [options] [attribute]...

Description

The dsmlsearch command searches for entries stored in a directory accessible through Directory Services Markup Language (DSML) v2, and displays the results in DSML format, including the specified attributes or all attributes returned if none are specified.

Filter files contain filters in DSML format. The dsmlsearch command does not support LDAP-style filters.

Options

The dsmlsearch command supports the following options:

-a deref

Dereference aliases as specified during a search. Possible values for the deref argument include:

derefAlways: Dereference aliases both when finding the base DN, and when searching below it.
derefFindingBaseObj: Dereference aliases when finding the base DN.
neverDerefAliases: Never dereference aliases (default).

This option has no effect when used with directories that do not support alias dereferencing.

-b baseDN

Use the entry with the specified distinguished name (DN) as the base entry for the search scope.

-D user-identifier

Use the specified user identifier to authenticate.

The user identifier is the HTTP-layer identifier. The HTTP-layer identifier is typically mapped to an account in the directory. For example, if the uid value is used for HTTP-layer authentication, which maps in the directory to bind DN dn:uid=user-identifier,ou=people,dc=example,dc=com, then the dsmlsearch -D bjensen command would end up using permissions for directory operations based on the permissions for the account with entry DN uid=bjensen,ou=people,dc=example,dc=com. The user-identifier thus depends closely on the identity mapping between the HTTP layer and the LDAP layer.

If the user identifier and its password are omitted, the dsmlsearch command binds anonymously. The user identifier determines what entries and attributes the user can read, according to the permissions for the user.

-f filename

Read the search filter or filters from the specified file.

-h hostURL

Use the specified URL to access the directory.

The host URL takes the form http://host:port where host represents the host on which the directory runs, and port is the port on which the directory listens for DSML requests.

-j filename

Read the bind password for simple HTTP authentication from the specified file.

-l timelimit

Interrupt the search if the time limit specified in seconds is exceeded.

-s scope

Use the specified search scope.

The following values are supported for scope:

baseObject: Examine only the entry specified by the argument to the -b option.
singleLevel: Examine only to the entry specified by the argument to the -b option and its immediate children.
wholeSubtree: (Default) Examine the subtree whose root is the entry specified by the argument to the -b option.

-w –

Prompt for the bind password for simple HTTP authentication.

-w password

Use the specified bind password for simple HTTP authentication.

-z maxEntries

Return no more than the specified number of entries.

Examples

Examples in this section use the following conventions:

The dsmlsearch command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens for DSML requests over HTTP on port 8080.

Example 1 `dsmlsearch`: Returning All Entries

The following command returns all entries in the suffix under the base DN. Use this only when you need to retrieve all entries and attributes:

$ cat filter
<filter>
<present name="objectclass"/>
</filter>
$ dsmlsearch -h http://host:8080 -b dc=example,dc=com -f filter

Example 2 `dsmlsearch`: Narrowing a Search

The following command employs a more specific filter to narrow the search:

$ cat filter
<filter>
<equalityMatch name="uid">
<value>bjensen</value>
</equalityMatch>
</filter>
$ dsmlsearch -h http://host:8080 -b dc=example,dc=com -f filter

Example 3 `dsmlsearch`: Searching the Root DSE

The following command searches the root DSE entry, which contains the list of suffixes supported by the directory and potentially other information. Notice you specify the scope as only the base entry:

$ cat filter
<filter>
<present name="objectclass"/>
</filter>
$ dsmlsearch -h http://host:8080 -b "" -s baseObject -f filter

Example 4 `dsmlsearch`: Searching the Schema Entry

The following command searches the schema entry, which contains the directory schema. Notice you specify the scope as only the base entry:

$ cat filter
<filter>
<present name="objectclass"/>
</filter>
$ dsmlsearch -h http://host:8080 -b cn=schema -s baseObject -f filter

Example 5 `dsmlsearch`: Filter Examples

The following list shows LDAP search filters with corresponding DSML search filters.

LDAP filter: (cn=Barbara Francis)

DSML filter:

<filter>
<equalityMatch name="cn">
<value>Barbara Francis</value>
</equalityMatch>
</filter>

LDAP filter: (cn=*Barb*)

DSML filter:

<filter>
<substrings name="cn">
<any>Barb</any>
</substrings>
</filter>

LDAP filter: (cn~=Barbare)

DSML filter:

<filter>
<approxMatch name="cn">
<value>Barbare</value>
</approxMatch>
</filter>

LDAP filter: (!(cn=*Barbara*))

DSML filter:

<filter>
 <not>
  <substrings name="cn">
   <any>Barbara</any>
  </substrings>
 </not>
</filter>

LDAP filter: (&(cn=*Barbara*)(cn=*Francis*))

DSML filter:

<filter>
 <and>
  <substrings name="cn">
   <any>Barbara</any>
  </substrings>
  <substrings name="cn">
   <any>Francis</any>
  </substrings>
 </and>
</filter>

LDAP filter: (|(cn=*Barbara*)(cn=*Jensen*))

DSML filter:

<filter>
 <or>
  <substrings name="cn">
   <any>Barbara</any>
  </substrings>
  <substrings name="cn">
   <any>Jensen</any>
  </substrings>
 </or>
</filter>

Exit Status

Exit status values are returned as part of the response, including both the code and the description as described in the DSML v2 standard. Common exit status codes follow:

0: Successful completion; success.
1: Server encountered errors while processing the request; operationsError.
2: Server encountered errors while processing the request; protocolError.
3: Search exceeded the time limit for operations on the server; timeLimitExceeded.
4: Search returned more results than the maximum number allowed by the server; sizeLimitExceeded.
10: Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; referral.
11: Search returned more results than the maximum number a client application is allowed by the server to retrieve; adminLimitExceeded.
32: Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; noSuchObject.
50: Bind DN user does not have permission to read the entry from the directory; insufficientAccessRights.
53: Directory is read-only; unwillingToPerform.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

entrycmp(1)

Name

entrycmp– compare the same entry on two or more different servers

Synopsis

install-path/bin/entrycmp 
 [-D bindDN] [-w password] [-n] [-p port] [-j file] [-T timeout]
 [-J file] [-W keypassword] [-K keydbpath] [-N certname]
 [-P certdbpath] [-e SSL port]  ServerSpec entryDN

Description

The entrycmp command compares the same entry on two or more different servers. An entry is retrieved from the master and the nsuniqueid of the entry is used to retrieve the same entry from a specified consumer. All the attributes and values of the two entries are compared. If they are identical, the entries are considered to be the same.

Options

The following options are supported:

-D

The distinguished name with which to bind to the server. This parameter is optional if the server is configured to support anonymous access. If a DN is specified in the ServerSpec, this overrides the -D option.

-j

If specifying the default password at the command-line poses a security risk, the password can be stored in a file. The -j option specifies this file.

-n

Specifies that entrycmp should not run in interactive mode. Running in interactive mode allows you to re-enter the bindDN, password, host and port, if a bind error occurs.

-p

The TCP port used by Directory Server. The default port is 389. If a port is specified in the ServerSpec, this overrides the -p option.

-T

Specifies the number of seconds after which entrycmp will time out if the server connection goes down.

-w

The password associated with the distinguished name specified by the -D option. If a password is specified in the ServerSpec, this overrides the -w option.

entryDN

The DN of the entry that you wish to compare.

ServerSpec

The server specification. The server specification is of one of the following forms.

-s|-S HostSpec [-c|-C HostSpec ...]

-c|-C HostSpec [-s|-S HostSpec ...]

Here, -s refers to the supplier replica. -c refers to the consumer replica. Lower case specifies non-SSL options. Upper case specifies SSL options.

Host Spec

The host specification, which takes the form [bindDN:[password]]@]host[:port]. The following is an example:

cn=admin,cn=Administrators,cn=config:mypword@myserver:1389

If you are using SSL, use -S and -C in the server specification. In this case, HostSpec specifies the certificate name and key password, rather than the bindDN and password. Specifying both more than one -s, and also more than one -c generates an error. If no -c option is specified, the -s HostSpec may refer to any server, either a consumer or a supplier.

SSL OPTIONS

You can use the following options to specify that entrycmp uses LDAPS when communicating with the Directory Server. You can also use these options if you want to use certificate-based authentication. These options are valid only when LDAPS has been turned on and configured.

-e: Default SSL port, 636.
-J: This option has the same function as the -j option, for the key password.
-K: Specifies the name of the certificate key used for certificate-based client authentication. For example, -K Server-Key.
-N: Specifies the certificate name to use for certificate-based client authentication. For example, - N Server-Cert. If this option is specified, the -W option is required.
-P: Specifies the location of the certificate database.
-W: Specifies the password for the certificate database identified by the -P option. For example, -W serverpassword.

Examples

Example 1 Specifying an entry DN

$ entrycmp -D cn=admin,cn=Administrators,cn=config -w mypword \
 -s myserver:1389 "uid=csmith,ou=people,dc=example,dc=com"

Exit Status

The following exit values are returned:

0: Successful completion, that is a match was found.
1: An error occurred, and no match was found.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Stable

Notes

The node on which you are running the entrycmp, insync, and repldisc tools must be able to reach all the specified hosts. If these hosts are unavailable due to a firewall, VPN, or other network setup reasons, you will encounter difficulties using these tools. For the same reason ensure that all servers are up and running before using these tools.

When identifying hosts, you must use either symbolic names or IP addresses for all hosts since the replication monitoring commands do not address resolution between symbolic names and IP addresses. Using a combination of the two can cause problems. Moreover, on multi-homed hosts, referring to the same Directory Server instance using different names may cause unexpected results.

When SSL is enabled, the directory server on which you are running the tools must have a copy of all the certificates used by the other servers in the topology.

The replication monitoring tools rely on access to cn=config to obtain the replication status. This should be taken into account particularly when replication is configured over SSL.

DSEE 7.0 Last Revised August 9, 2006

fildif(1)

Name

fildif– creates a filtered version of an LDIF input file

Synopsis

install-path/bin/fildif 
-i input-file [-o output-file] [-f ] -b repl-agmt-dn
 -p instance-path

Description

The fildif command creates a filtered version of an LDIF input file. fildif takes a configuration file as an input parameter. This configuration file must conform to the configuration rules of the filtering service included as part of Directory Server, and must contain the specific set and element entries that define these rules. The configuration rules can be defined by using Directory Service Control Center or at the command-line.

fildif does not require the Directory Server instance to be running.

A filtering service configuration is accessed through a replication agreement. The replication agreement entry DN is provided to fildif with the -b option.

Note –

fildif does not support the LDIF input file bigger than 2GB.

Options

The following options are supported:

-b repl-agmt-dn: The DN of the replication agreement used as the filtering service configuration entry point. The entry specified must exist in the configuration of the Directory Server instance.
-f: Force fildif to overwrite the contents of the specified output file, if it exists.
-i input-file: The input LDIF file whose contents are filtered.
-o output-file: The output LDIF file in which the filtered results are stored. If no output file is specified, the default output file is ./output.ldif.
-p: The full path to the Directory Server instance whose configuration contains the replication agreement specified as a parameter of the -b option.

Examples

Example 1 Using All Options

The following example shows the fildif command to generate an output file filt_data.ldif that overwrites the file if it exists already.

$ fildif -i data.ldif -o filt_data.ldif -f \
-b "cn=ds.example.com:389,cn=replica,cn=dc=example\,dc=com,\
cn=mapping tree,cn=config"
-p /local/dsInst

Exit Status

The following exit values are returned:

0: Successful completion.
1: An error occurred.

On error, verbose error messages are output to standard output.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Stable

insync(1)

Name

insync– indicate the synchronization state between a supplier replica and one or more consumer replicas

Synopsis

install-path/bin/insync 
 [-D bindDN] [-w password] [-t] [-n] [-d] [-j file] [-p port]
 [-T timeout] [-J file] [-W keypassword] [-K keydbpath]
 [-N certname] [-P certdbpath] [-e SSL port] [-b ReplicaRoot]
  ServerSpec [interval]

Description

The insync command indicates the synchronization state between a supplier replica and one or more consumer replicas. insync compares the RUVs of replicas and displays the time difference or delay (in seconds) between the servers.

Options

The following options are supported:

-b

The suffix (replica root) that has been specified for replication. If -b is not specified, the delay for all suffixes is displayed.

-d

Displays the date of the last change recorded on the master. Using the -d option twice (-d -d) displays the time difference (in days, minutes and seconds) between the time of the last change and the current time.

-D

-j

If specifying the default password at the command-line poses a security risk, the password can be stored in a file. The -j option specifies this file.

-n

Specifies that insync should not run in interactive mode. Running in interactive mode allows you to re-enter the bindDN, password, host and port, if a bind error occurs.

-p

The TCP port used by Directory Server. The default port is 389. If a port is specified in the ServerSpec, this overrides the -p option.

-t

Displays the mode of transport (SSL or CLEAR)

-T

Specifies the number of seconds after which insync will time out if the server connection goes down.

-w

The password associated with the distinguished name specified by the -D option. If a password is specified in the ServerSpec, this overrides the -w option.

ServerSpec

The server specification. The server specification is of one of the following forms.

-s|-S HostSpec [-c|-C HostSpec ...]

-c|-C HostSpec [-s|-S HostSpec ...]

Here, -s refers to the supplier replica. -c refers to the consumer replica. Lower case specifies non-SSL options. Upper case specifies SSL options.

Host Spec

The host specification, which takes the form [bindDN:[password]]@]host[:port]. The following is an example:

cn=admin,cn=Administrators,cn=config:mypword@myserver:1389

interval

The amount of time (in seconds) after which the synchronization query will start again (in an infinite loop). If no interval is specified, the synchronization query will run only once.

SSL OPTIONS

You can use the following options to specify that insync uses LDAPS when communicating with the Directory Server. You can also use these options if you want to use certificate-based authentication. These options are valid only when LDAPS has been turned on and configured.

-e: Default SSL port, 636.
-J: This option has the same function as the -j option, for the key password.
-K: Specifies the name of the certificate key used for certificate-based client authentication. For example, -K Server-Key.
-N: Specifies the certificate name to use for certificate-based client authentication. For example, - N Server-Cert. If this option is specified, the -W option is required.
-P: Specifies the location of the certificate database.
-W: Specifies the password for the certificate database identified by the -P option. For example, -W serverpassword.

Examples

Example 1 Single Server, Repeat Each 30 Seconds

Note that the delay changes to 5, indicating that the consumer is 5 seconds behind the supplier.

$ insync -D cn=admin,cn=Administrators,cn=config -w mypword \
 -s portugal:1389 30

ReplicaDn         Consumer                Supplier        Delay      

dc=example,dc=com france.example.com:2389 portugal:1389   0         

dc=example,dc=com france.example.com:2389 portugal:1389   5         

dc=example,dc=com france.example.com:2389 portugal:1389   0

Example 2 Getting Date of Last Change

$ insync -D cn=admin,cn=Administrators,cn=config -w mypword \
 -s portugal:1389 -b o=rtest -d

Exit Status

The following exit values are returned:

0: Successful completion.
1: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Stable

Notes

When SSL is enabled, the directory server on which you are running the tools must have a copy of all the certificates used by the other servers in the topology.

If a delay of -1 is returned, insync was unable to obtain any replication information. This may indicate that a Total Update has just been run, or that no changes have been sent to the supplier server.

The replication monitoring tools rely on access to cn=config to obtain the replication status. This should be taken into account particularly when replication is configured over SSL.

DSEE 7.0 Last Revised November 19, 2008

ldapcmp(1)

Name

ldapcmp– compare LDAP entries from two directories

Synopsis

install-path/dsrk/bin/ldapcmp 
 [-h host1 -p port1 [-h host2 -p port2]] [options] -b basedn

Description

The ldapcmp command compares a Lightweight Directory Access Protocol (LDAP) entry or subtree of entries from one directory with the an entry or subtree of entries from another directory. It detects entries that do not appear in both directories and detects attribute differences in entries that do appear in both directories.

The ldapcmp command reports comparison results using the following output syntax:

1only: DN

Entry appears only in the first directory specified.

2only: DN

Entry appears only in the second directory specified.

DN

Entry appears in both directories, attributes differ. The ldapcmp command then explains the differences found:

different: attrname: Entries differed by attribute value.
different: attrname(*): Specified attribute found only in one directory.
1: attrvalue: Specified value found in first directory.
2: attrvalue: Specified value found in second directory.

Options

Although the -h (host) and -p (port) options are not required, you generally use these options to specify how to access the two directories. If you do not specify any -h or -p options, the ldapcmp command compares the content of the directory listening on the default port of the localhost system with itself.

Unless the LDAP_BASEDN environment variable is set, you must at minimum provide a basedn argument to the -b option. The basedn argument specifies the distinguished name (DN) of the LDAP entry at the base of the search scope.

The following additional options are supported:

-0

Ignore LDAP library version mismatches.

When this option is omitted, the default behavior is to assert that the revision number of the LDAP API be greater than or equal to that used to compile the tool. Also, if the library and the tool have the same vendor name, the tool will assert that the vendor version number of the API be greater than or equal to that used to compile the tool. Revision and version numbers are based on the contents of the LDAPAPIInfo structure defined in <ldap.h> or header files included by<ldap.h>.

-3

Check host names in SSL certificates.

-B

Allow binary values to be printed, even if the -o option is used.

-D binddn

Use the specified bind DN for accessing both directories, usually enclosed in double quotes ("") for the shell.

If the bind DN and its password are omitted, the ldapcmp command binds anonymously. The bind DN determines what entries and attributes appear in the comparison results, according to the search permissions for the bind DN.

-E

Request that the directories expose (report) bind identities.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality is false by default.

An LDAP control can be associated with a value. Proxy authorization takes a proxy authorization ID, for example, passed with the control OID, and criticality. If a value is necessary you specify it using value, base64value, or <fileurl.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, returning the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Directory-Cert".

Both directories must recognize the specified certificate to perform the comparison.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P filename

Use the certificate database located in filename, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-Y proxydn

Use the specified proxy DN for accessing both directories, usually enclosed in double quotes ("") for the shell.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

Use the sum of the levels to specify more than one debug level. For example, to set the debug level to display both verbose debugging messages, and messages about the content of network packets, specify -d 3.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address.

The default is localhost.

Specify the host twice to specify hosts for each of the two directories. When you specify the host twice, the first host specified corresponds to the first directory, and the second host corresponds to the second, regardless of the order of other options.

-i charset

Use the specified character set to override the value of the LANG environment variable. This option is useful, as the command converts certain arguments you specify to UTF-8 before sending the request to the server. The following arguments are converted: base DN, bind DN, LDAP filter, and password.

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-l timelimit

Interrupt the comparison if the specified time limit is exceeded.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

Specify the port twice to specify ports for each of the two directories. When you specify the port twice, the first port specified corresponds to the first directory, and the second port corresponds to the second, regardless of the order of other options.

-s scope

Use the specified search scope.

The following values are supported for scope:

base: Examine only the entry specified by the argument to the -b option.
one: Examine only to the entry specified by the argument to the -b option and its immediate children.
sub: (Default) Examine the subtree whose root is the entry specified by the argument to the -b option.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

-z sizelimit

Interrupt the comparison if the specified maximum number of entries returned is exceeded.

Examples

All examples in this section use the following conventions:

All entries to compare are stored under dc=example,dc=com.
The directories have been configured to support anonymous access for search and read. Therefore, you do not have to specify any bind information.
The directory servers are located on systems named host1 and host2.
The servers both listen on port number 389, the default.

Example 1 Comparing Two Suffixes

When you specify the root DN of the suffix as the base DN, ldapcmp compares all entries of the entire suffix in both directories.

$ ldapcmp -h host1 -h host2 -b "dc=example,dc=com"

You should have some idea of the size and differences between your directories before comparing them. Comparing two directories is useful for finding small difference between directories. When comparing completely different subtrees, the output can be very large. Narrow your comparison by specifying the base DN of a similar subtree in both directories.

Example 2 Comparing Two Entries

The following command compares a single user entry in both directories:

$ ldapcmp -h host1 -h host2 -s base \
-b "uid=bjensen,ou=People,dc=example,dc=com"

Example 3 Setting the Base DN

The following commands set the LDAP_BASEDN environment variable, and then compare all entries of the entire base suffix in both directories, running in verbose mode. The syntax of the first command may not work for your shell. Refer to the documentation about your shell for instructions on setting environment variables.

$ LDAP_BASEDN="dc=example,dc=com"; export LDAP_BASEDN
$ ldapcmp -v -h host1 -h host2

Example 4 Comparing Directory Configurations

The following command compares root DSE entries for both directories:

$ ldapcmp -h host1 -h host2 -s base -b ""

Example 5 Comparing Directory Schema

The following command compares schema entries for both directories:

$ ldapcmp -h host1 -h host2 -b "cn=schema"

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. The return values are defined through <ldap.h> files both on the client side and on the server side. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
3: Search exceeded the time limit for operations on the server; LDAP_TIMELIMIT_EXCEEDED; 0x03.
4: Search returned more results than the maximum number allowed by the server; LDAP_SIZELIMIT_EXCEEDED; 0x04.
10: Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
11: Search returned more results than the maximum number a client application is allowed by the server to retrieve; LDAP_ADMINLIMIT_EXCEEDED; 0x0b.
32: Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
81: One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
85: The search exceeded the time limit specified using the -l option; LDAP_TIMEOUT; 0x55.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: At least one server supports only LDAPv2, and the -V 2 option was not used; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldapcompare(1)

Name

ldapcompare– compare a value with an LDAP entry attribute value

Synopsis

install-path/dsrk/bin/ldapcompare 
 [options] attrtype:attrvalue [dn]...

install-path/dsrk/bin/ldapcompare 
 [options] attrtype::base64value [dn]...

install-path/dsrk/bin/ldapcompare 
 [options] attrtype:<fileurl [dn]...

Description

The ldapcompare command asserts that a value you specify is the same as an entry attribute value stored by the directory server.

Specify the attribute type, followed by the attribute value, either as a string, a base64–encoded value, or a URL to a file containing the attribute value, such as a photo or certificate. You typically enclose the attribute type/value pair in single quotes ('') for the shell.

Also specify one or more entry DNs, separated by space, and typically enclosed in double quotes ("") for the shell. The ldapcompare command then compares the specified attribute value to that of attributes on each of the entries indicated by the DNs you provide.

Options

The following options are supported:

-0

Ignore LDAP library version mismatches.

-3

Check host names in SSL certificates.

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldapcompare command binds anonymously. The bind DN determines what entries and attributes appear in the comparison results, according to the search permissions for the bind DN.

-E

Request that the directories expose (report) bind identities.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, comparing the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P pathname

Use the certificate database located in pathname, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-Y proxydn

Use the rights of the entry having the specified DN for performing LDAP operations. When using this option, you must also specify how to bind before you assume the rights of the proxy. Thus, when using simple authentication, you would also use the -D and -w options with this option.

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use Start TLS to provide certificate-based client authentication.

The -ZZ option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-c

Run in continuous mode, not stopping on errors.

In continuous mode, errors are reported but the ldapcompare command continues performing comparisons. When not running in continuous mode, the ldapcompare command quits after the first error.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

-f filename

Read DNs from the specified file.

The file format is one DN per line without quotes around DNs. The ldapcompare command reads each line as one literal DN, performing the comparison for each entry whose DN is specified.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

When using GSSAPI with Directory Server, specify the host as a fully-qualified host name which matches the value of the nsslapd-localhost attribute on the cn=config entry. The GSSAPI authentication process requires that the host name provided by the client match the one provided by the server.

The default is localhost.

-i charset

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-q

Run in quiet mode, displaying no information about results of comparisons, but only about LDAP errors.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

Examples

Examples in this section use the following conventions:

The directory server is located on a system named host.
The directory server has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port number 389, the default.

Example 1 Comparing String Values

The following command compares a specified string with an attribute value:

$ ./ldapcompare -h host 'givenname:Barbara' \
"uid=bjensen,ou=People,dc=example,dc=com"
comparing type: "givenname" value: "Barbara" 
 in entry "uid=bjensen,ou=People,dc=example,dc=com"
compare TRUE

Example 2 Comparing Base 64 Encoded Values

The following command compares a base64–encoded value with an attribute value:

$ ./ldapcompare -h host 'cn::QmFicyBKZW5zZW4=' \
"uid=bjensen,ou=People,dc=example,dc=com"
comparing type: "cn" value: "Babs Jensen" 
 in entry "uid=bjensen,ou=People,dc=example,dc=com"
compare TRUE

Example 3 Comparing Binary Values in Files

The following command compares an image with an attribute value:

$ ./ldapcompare -h host 'jpegphoto:<file:///home/bjensen/bjensen.jpg' \
"uid=bjensen,ou=People,dc=example,dc=com"
comparing type: "jpegphoto" value: "NOT ASCII (3674 bytes)" 
 in entry "uid=bjensen,ou=People,dc=example,dc=com"
compare TRUE

Exit Status

The exit status returned either corresponds to 5 (LDAP_COMPARE_FALSE) or 6 (LDAP_COMPARE_TRUE), or reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
3: Search exceeded the time limit for operations on the server; LDAP_TIMELIMIT_EXCEEDED; 0x03.
5: Operation was successful but the values did not match; LDAP_COMPARE_FALSE; 0x05.
6: Operation was successful and the values match; LDAP_COMPARE_TRUE; 0x06.
10: DN of the entry to compare belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
32: DN of the entry to compare belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
34: DN of the entry to compare is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
81: One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: At least one server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldapdelete(1)

Name

ldapdelete– delete LDAP entries

Synopsis

install-path/dsrk/bin/ldapdelete 
 [options] [dn]...

install-path/dsrk/bin/ldapdelete 
 [options] < filename

Description

The ldapdelete command requests deletion of entries stored by a directory server. You must bind as a user having access to delete the entries specified.

Specify one or more entry DNs, separated by space, and typically enclosed in double quotes ("") for the shell. Alternatively, include DNs in a file, one per line without quotes around DNs. The ldapdelete command reads each line as one literal DN.

When deleting a subtree, you must delete child entries before you delete their parent entries.

Options

The following options are supported:

-0

Ignore LDAP library version mismatches.

-3

Check host names in SSL certificates.

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldapdelete command binds anonymously. The bind DN determines whether the delete operation can complete, according to the user permissions.

-E

Request that the directories expose (report) bind identities.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, deleting the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P pathname

Use the certificate database located in pathname, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-Y proxydn

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use Start TLS to provide certificate-based client authentication.

The -ZZ option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-c

Run in continuous mode, not stopping on errors.

In continuous mode, errors are reported but the ldapdelete command continues. When not running in continuous mode, the ldapdelete command quits after the first error.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

-f filename

Read DNs from the specified file.

The file format is one DN per line without quotes around DNs. The ldapdelete command reads each line as one literal DN.

This option has no effect when you also specify DNs on standard input.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

The default is localhost.

-i charset

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

Examples

Examples in this section use the following conventions:

The bind DN given corresponds to a user with permission to delete entries.
The directory server is located on a system named host.
The directory server listens on port number 389, the default for non-SSL traffic.
The directory server listens on port number 636, the default for SSL traffic. SSL is enabled.

Example 1 Deleting an Entry

The following command deletes a single entry from the directory:

$ ./ldapdelete -h host -D uid=kvaughan,ou=people,dc=example,dc=com \
-w - uid=scarter,ou=People,dc=example,dc=com
Enter bind password: 
$

Example 2 Deleting an Entry Interactively

The following commands demonstrate deleting an entry whose DN is specified on standard input:

$ ./ldapdelete -h host -D uid=kvaughan,ou=People,dc=example,dc=com \
-w - -c -v
Enter bind password: 
ldapdelete: started Tues Oct 18 08:31:14 2005

ldap_init( host, 389 )

uid=scarter, ou=People, dc=example,dc=com
deleting entry uid=scarter, ou=People, dc=example,dc=com
entry removed
^D
$

Example 3 Deleting Multiple Entries Specified in a File

The following commands demonstrate reading DNs of entries to delete from a file. Notice that the -c option is used to continue if an error occurs.

$ cat DNfile
uid=scarter, ou=People, dc=example,dc=com
uid=bjensen, ou=People, dc=example,dc=com
$ ./ldapdelete -h host -D uid=kvaughan,ou=People,dc=example,dc=com \
-c -f DNfile -w -
Enter bind password: 
$

Example 4 Using Server Authentication

The following command uses server authentication during the bind, where the server only accepts binds by clients with trusted certificates. Notice only the -P option is used without other SSL-related options.

$ ./ldapdelete -h host -p 636 -c -f DNfile -P /home/kvaughan/security \
-D uid=kvaughan,ou=People,dc=example,dc=com -w -
Enter bind password:

Example 5 Using Client Authentication

The following command uses client authentication during the bind, where the server only accepts binds by clients with trusted certificates, and the client must sign the certificate with a password-protected private key. Notice the options used in this example.

$ ./ldapdelete -h host -p 636 -c -f DNfile -Z -P /home/kvaughan/security \
-N "kvscert" -K /home/kvaughan/security -W keypassword

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
10: DN of the entry to delete belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
32: DN of the entry to delete belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
34: DN of the entry to delete is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
53: Directory is read-only; LDAP_UNWILLING_TO_PERFORM; 0x35.
66: Entry specified has child-entries that must be deleted first; LDAP_NOT_ALLOWED_ON_NONLEAF; 0x42.
81: One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: At least one server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldapmodify(1)

Name

ldapmodify– add, modify, rename, move, or delete LDAP entries

Synopsis

install-path/dsrk/bin/ldapmodify 
 [options]

Description

The ldapmodify command requests the addition, modification, rename, move, or deletion of entries stored by a directory server.

You must bind as a user having access to perform the requested operation.

The directory server may check all modifications against its schema, and reject updates that cause entries not to conform to the schema.

You must specify additions and modifications in the proper order, because the directory server performs the updates in the order you request them. For example, to add entries to a subtree that does not yet exist, you must first update the base entry at the root of the subtree before adding entries under the base entry. When a requested operation fails, the ldapmodify command stops processing further input unless you use the -c option. The ldapmodify command does not save rejected entries unless you use the -e option.

Options

The following options are supported:

-0

Ignore LDAP library version mismatches.

-3

Check host names in SSL certificates.

-A

Display non-ASCII values when the -v option is used.

-B baseDN

Bulk import entries into the suffix under the specified DN.

Note –

Bulk import using the ldapmodify command erases the existing entries under the target suffix.

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldapmodify command binds anonymously. The bind DN determines what entries and attributes appear in the comparison results, according to the search permissions for the bind DN.

-E

Request that the directories expose (report) bind identities.

-F

Force application of all modifications, even if some lines are duplicates.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, modifying the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P filename

Use the certificate database located in filename, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-Y proxydn

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use Start TLS to provide certificate-based client authentication.

The -ZZ option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use a start TLS request .

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-a

Add LDAP entries, rather than modifying existing entries.

-b

Handle binary files.

Note –

This option is deprecated. Use standard LDIF notation as described in RFC 2849 instead.

When you use the -b option, the ldapmodify command scans every attribute value to determine whether it specifies a valid file reference, such as /home/bjensen/bjensen.jpg. If so, the ldapmodify command uses the content of the specified file as the attribute value.

-c

Run in continuous mode, not stopping on errors.

In continuous mode, errors are reported but the ldapmodify command continues performing comparisons. When not running in continuous mode, the ldapmodify command quits after the first error.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

-e filename

Save rejected entries in the specified file.

-f filename

Read modifications from the specified file.

The file format is standard LDIF notation as described in RFC 2849.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

The default is localhost.

-i charset

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-q

Run in quiet mode, not displaying information about the operations performed.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

Examples

Examples in this section use the following conventions:

The bind DN given corresponds to a user with permission to update entries.
The directory server is located on a system named host.
The directory server listens on port number 389, the default for non-SSL traffic.
The directory server listens on port number 636, the default for SSL traffic. SSL is enabled.

Example 1 Adding an Entry

The following commands demonstrate adding a single entry to the directory:

$ cat add.ldif
dn: uid=bcubbins,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: bcubbins
givenName: Bartholomew
sn: Cubbins
cn: Bartholomew Cubbins
mail: bcubbins@example.com
userPassword: bcubbins
facsimiletelephonenumber: +1 234 567 8910

$ ldapmodify -a -h host -D uid=bjensen,ou=people,dc=example,dc=com \
-w - -f add.ldif
Enter bind password: 
adding new entry uid=bcubbins,ou=People,dc=example,dc=com

$

Example 2 Modifying an Entry

The following commands demonstrate modifying an entry. Notice a line with a single dash (-) separates multiple modifications to a single entry.

$ cat modify.ldif 
dn: uid=bcubbins,ou=People,dc=example,dc=com
changetype: modify
add: description
description: Added with ldapmodify
-
replace: mail
mail: bart@example.com

$ ./ldapmodify -h host -c -v \
-D uid=bjensen,ou=People,dc=example,dc=com -w - -f modify.ldif
Enter bind password: 
modifying entry uid=bcubbins,ou=People,dc=example,dc=com

$

Example 3 Deleting an Entry Interactively

The following commands delete the entry added and modified in previous examples.

$ ./ldapmodify -h host -D uid=bjensen,ou=People,dc=example,dc=com -w -
Enter bind password: 
dn: uid=bcubbins,ou=People,dc=example,dc=com
changetype: delete
deleting entry uid=bcubbins,ou=People,dc=example,dc=com
^D

$

Example 4 Using Server Authentication

$ ./ldapmodify -h host -p 636 -c -f modify.ldif -P /home/bjensen/security \
-D "uid=bjensen,ou=People,dc=example,dc=com" -w -
Enter bind password:

Example 5 Using Client Authentication

$ ldapmodify -h host -p 636 -c -Z -P /home/bjensen/security \
 -N "bjscert" -K /home/bjensen/security -W keypassword -f modify.ldif

Example 6 Moving an Entry

The following command moves an entry from one branch of a suffix to another:

$./ldapmodify -h host -D uid=hmiller,ou=people,dc=example,dc=com -w -
Enter bind password: 
dn: uid=jwallace,ou=people,dc=example,dc=com
changetype: modrdn
newrdn: uid=jwallace
deleteoldrdn: 0
newsuperior: ou=special users,dc=example,dc=com
^D

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
10: DN of the entry to modify belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
16: Attribute to be modified does not exist; LDAP_NO_SUCH_ATTRIBUTE; 0x10.
19: Attribute modification requested is not a proper modification. For example, a requested change to userpassword would result in a user password shorter than the minimum length allowed; LDAP_CONSTRAINT_VIOLATION; 0x13.
20: Attribute to add already exists with the specified value; LDAP_TYPE_OR_VALUE_EXISTS; 0x14.
21: The value modified does not respect the syntax for the attribute type; LDAP_INVALID_SYNTAX; 0x15.
32: DN of the entry to modify belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
34: DN of the entry to modify is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
53: Directory is read-only; LDAP_UNWILLING_TO_PERFORM; 0x35.
65: Requested modification would cause the entry not to comply with the directory schema; LDAP_OBJECT_CLASS_VIOLATION; 0x41.
66: Entry specified has child-entries that must be deleted first; LDAP_NOT_ALLOWED_ON_NONLEAF; 0x42.
67: Requested modification would cause the entry to be missing attributes that are components of the entry DN; LDAP_NOT_ALLOWED_ON_RDN; 0x43.
68: An entry already exists with the same DN as the entry to add; LDAP_ALREADY_EXISTS; 0x44.
81: One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: At least one server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldappasswd(1)

Name

ldappasswd– change the password of an LDAP entry

Synopsis

install-path/dsrk/bin/ldappasswd 
 [options] [auth-id]

Description

The ldappasswd command changes the password of an LDAP entry, identified by an auth-id such as uid=bjensen,ou=people,dc=example,dc=com, stored by a directory server.

The ldappasswd command relies on the Password Modify Extended Operation (OID 1.3.6.1.4.1.4203.1.11.1).

Options

The following options are supported:

-0

Ignore LDAP library version mismatches.

-3

Check host names in SSL certificates.

-A

Prompt for old password.

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldappasswd command binds anonymously.

-E

Request that the directory expose (report) the bind identity.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, modifying the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based SSL client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops.

Default is 5.

-P pathname

Use the SSL certificate database located in the specified file system directory.

The default is to search for the certificate database file, cert8.db, in the current directory.

-R

Do not follow referrals automatically.

-S

Prompt for the new password.

-T filename

Read the new password from the specified file.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-Y proxydn

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use start TLS when possible to connect to the directory.

-a password

Use the specified old password.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

The default is localhost.

-i charset

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-m pathname

Use the security module database located in the specified file system directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-s password

Use the specified new password.

-t filename

Read the old password from the specified file.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

Examples

Examples in this section use the following conventions:

The directory server is located on a system named host.
The directory server supports the Password Modify Extended Operation (OID 1.3.6.1.4.1.4203.1.11.1)
The directory server listens on port number 389, the default for non-SSL traffic.
The directory server listens on port number 636, the default for SSL traffic. SSL is enabled.

Example 1 Changing Your User Password

The following command lets Barbara Jensen change her own user password, connecting over simple authentication:

$ ./ldappasswd -h host -D uid=bjensen,ou=people,dc=example,dc=com \
-j old.pwd -T new.pwd -t old.pwd uid=bjensen,ou=people,dc=example,dc=com
ldappasswd: password successfully changed
$

Example 2 Changing The Password For Another User

The following command lets Kirsten Vaughan change Barbara Jensen’s password, connecting over simple authentication:

$ ./ldappasswd -h host -D uid=kvaughan,ou=people,dc=example,dc=com \
-w - -A -S uid=bjensen,ou=people,dc=example,dc=com
Old Password: 
New Password: 
Re-enter new Password: 
Enter bind password:
ldappasswd: password successfully changed
$

Example 3 Using Server Authentication

$ ./ldappasswd -h host -p 636 -P /home/bjensen/security \
-D "uid=bjensen,ou=People,dc=example,dc=com" -w - -A -S -Z \
uid=bjensen,ou=People,dc=example,dc=com
Old Password: 
New Password: 
Re-enter new Password: 
Enter bind password:
ldappasswd: password successfully changed
$

Example 4 Using Client Authentication

$ ./ldappasswd -h host -p 636 -A -S -P /home/bjensen/security \
-N "bjscert" -W keypassword uid=bjensen,ou=People,dc=example,dc=com
Old Password:
New Password:
Re-enter new Password:
ldappasswd: password successfully changed
$

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
10: Entry to modify belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
32: Authentication ID belongs to an entry not handled by the server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
53: Directory does not allow this user to perform this operation; LDAP_UNWILLING_TO_PERFORM; 0x35.
81: One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: At least one server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldapsearch(1)

Name

ldapsearch– find LDAP entries

Synopsis

install-path/dsrk/bin/ldapsearch 
 -b baseDN [options] filter [attribute]...

install-path/dsrk/bin/ldapsearch 
 -b baseDN [options] -f filename [attribute]...

Description

The ldapsearch command searches for entries stored by a directory server based on the specified LDAP filter.

The ldapsearch command displays results found in LDIF format, including the specified attributes, or all attributes returned if none are specified.

Filter files, which are specified using the -f filename option, contain one filter per line. Specified LDAP filters must comply with RFC 2254.

Options

Unless the LDAP_BASEDN environment variable is set, you must at minimum provide a baseDN argument to the -b option. The baseDN argument specifies the distinguished name (DN) of the LDAP entry at the base of the search scope.

The following options are supported:

-0

Ignore LDAP library version mismatches.

-1

Omit leading version: 1 indication in LDIF output, meaning the output is not RFC 2849 compliant.

-3

Check host names in SSL certificates.

-A

Display non-ASCII values when the -v option is used.

-C ps:changetype[:changesonly[:entrychangecontrols]]

Perform a persistent search that stops when you type Control-C.

By default, when used with the -C option the ldapsearch command requests that the directory server return entry change controls with persistent search results. Adjust this behavior with the following arguments:

changetype

Determines which modifications to an entry are detected and displayed in the output. Possible values include:

add
any
delete
modify
moddn

changesonly

Determines when to display search results. Possible values include:

0 f false: Display initial search results immediately, not waiting for changes. Then display new changes as they occur.
1: Display changes when they occur (default).

entrychangecontrols

Determines whether to display entry change controls. Possible values include:

0 f false: Do not display entry change controls.
1: Display entry change controls (default).

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldapsearch command binds anonymously. The bind DN determines what entries and attributes appear in the search results, according to the search permissions for the DN.

-E

Request that the directories expose (report) bind identities.

-F sep

Print specified separator character instead of = between attribute types and values.

-G pattern

Retrieve a virtual list view displaying a portion of the total search results. Use this option with the -S and -x options to sort entries returned.

The specified pattern may take one of two forms to specify the size of the virtual list view around a target entry:

entriesbefore:entriesafter:value

Return the target entry, which is the first entry in the sorted results whose sort attribute is greater than or equal to the specified value, as well as the specified number of entries before the target entry and the specified number of entries after the target entry.

For example, -S sn -x -G 5:10:johnson returns 16 entries in alphabetical order of the surname attribute: 5 less than johnson, the entry equal to or following johnson, and the 10 subsequent entries.

entriesbefore:entriesafter:index:count

Return the target entry, as well as the specified number of entries before the target entry and the specified number of entries after the target entry. The target entry depends on the index and estimated count arguments.

The count argument may take the following values, with the following results:

count == 0

The target is the entry at the specified index position, starting from 1, and relative to the entire list of sorted results.

count == 1

The target is the first entry in the list of sorted results.

count > 1

The target is the first entry in the slice of the list represented by the fraction index/count.

Use an index argument greater than the count argument to target the last result in the list.

For example, -G 5:10:2:4 specifies the index closest to the beginning of the second quarter of the entire list. If the search yielded 100 entries, the target index would be 26, and this pattern would return entries 21 through 36.

The number of entries displayed before and after the target entry may be limited by the beginning and end of the virtual list. The ldapsearch command displays the control response, giving the count of entries in the virtual list and the index of the target entry. Use these values to refine index and count arguments.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, searching the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P filename

Use the certificate database located in filename, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-S attrtype

Sort the results based on the specified attribute.

-T

Do not break long lines within individual attribute values.

Default is to break long attribute values according to LDIF rules.

-U

When generating temporary file output using the -t option, include URLs as attribute types whose value is a file, such as a photo or certificate.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-X attrlist

When performing a search to get effective rights using the -c option, use the list of attributes provided.

-Y proxydn

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use Start TLS to provide certificate-based client authentication.

The -ZZ option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-a deref

Dereference aliases as specified during a search. Possible values for the deref argument include the following values:

always: Dereference aliases both when finding the base DN, and when searching below it.
find: Dereference aliases when finding the base DN.
never: Never dereference aliases (default).
search: Dereference aliases when searching below the base DN, but not when finding the base DN.

This option has no effect when used with directories that do not support alias dereferencing.

-c authzid

Use the specified authorization ID when to perform a get effective rights search. The following authorization IDs are supported:

"": "" represents an empty string, meaning use the authorization ID already specified for the operation.
"bindDN": Use the specified bind DN, such as uid=bjensen,ou=People,dc=example,dc=com.
"dn:": Use anonymous as the authorization ID.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

-e

Minimize base64–encoding of resulting attribute values.

-f filename

Read the search filters from the specified file.

File format is one search filter per line, where search filters conform to RFC 2254.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

The default is localhost.

-i charset

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-l timelimit

Interrupt the search if the specified time limit is exceeded.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-s scope

Use the specified search scope.

The following values are supported for scope:

base: Examine only the entry specified by the argument to the -b option.
one: Examine only to the entry specified by the argument to the -b option and its immediate children.
sub: (Default) Examine the subtree whose base is the entry specified by the argument to the -b option.

-t

Write a temporary file as output for each attribute of each entry in the search results. Such files are written to the system temporary directory, typically /tmp. On standard output, write file names in place of attribute values.

When the -t option is used, no base64 encoding is performed on any attribute values, regardless of their content.

-u

Include user friendly entry names (ufn: userfriendly) in the results returned.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

-x

Have the directory server sort results based on entry DNs before returning the results.

-z sizelimit

Interrupt the search if the specified maximum number of entries returned is exceeded.

INTERNATIONAL SEARCHES

This section focuses on international searches, and in particular the matching rule filter portion of the ldapsearch command.

When you perform search operations, you can request that the directory sort the results based on any language for which the server has a supported collation order.

A matching rule provides special guidelines for how the directory compares strings during a search operation. In an international search, the matching rule tells the system what collation order and operator to use when performing the search operation. The syntax of the matching rule filter is as follows.

attr:matchingRule:=value

Here attr, matchingRule, and value mean the following.

attr is an attribute belonging to entries you're searching for, such as cn or mail.
matchingRule is a string that identifies either the collation order or the collation order and a relational operator, depending on the format you prefer.
value is either the attribute value for which you want to search or a relational operator plus the attribute value for which you want to search. The syntax of the value portion of the filter depends on the matching rule format you use.

The matching rule portion of a search filter can be represented in one of the following ways.

Use an OID for the matching rule.

Each locale supported by Directory Server has an associated collation order OID. Locales supported for Directory Server are listed in the reference documentation on Identifying Supported Locales in Sun Directory Server Enterprise Edition 7.0 Reference. When you use this approach, the matching rule filter has the following form.
```
attr:OID:=relational-operator value
```
The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search for all departmentNumber attributes that are at or after N4709 in the Swedish collation order, use the following filter.
```
departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709
```
Use a language tag for the matching rule.

Each locale supported by Directory Server has an associated language tag. When you use this approach, the matching rule filter has the following form.
```
attr:language-tag:=relational-operator value
```
The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search the directory for all description attributes with a value of estudiante using the Spanish collation order, use the following filter.
```
cn:es:== estudiante
```
Use an OID and suffix for the matching rule.

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the OID in the matching rule portion of the filter. Combine the OID and suffix.
```
attr:OID+suffix:=value
```
For example, to search for businessCategory attributes with the value Softwareprodukte in the German collation order, use the following filter.
```
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte
```
The .3 in the previous example is the equality suffix.
Use a language tag and suffix for the matching rule.

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the language tag in the matching rule portion of the filter. Combine the language tag and suffix.
```
attr:language-tag+suffix:=value
```
For example, to search for all surnames that come at or after La Salle in the French collation order, use the following filter.
```
sn:fr.4:=La Salle
```

Directory Server supports the following types of international searches, designated in your search filter by adding either the search operator, or the search suffix to the OID or language code specifying the appropriate, collation dependent, matching rule.

equality

Search operator: =

Suffix operator: .1

less than

Search operator: <

Suffix operator: .2

less than or equal to

Search operator: <=

Suffix operator: .3

greater than or equal to

Search operator: >=

Suffix operator: .4

greater than

Search operator: >

Suffix operator: .5

substring

Search operator: =*

Suffix operator: .6

Approximate, or phonetic, and presence searches are supported only in English.

Examples

Examples in this section use the following conventions:

The directory server is located on a system named host.
The directory server has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port number 389, the default for non-SSL traffic.
The directory server listens on port number 636, the default for SSL traffic. SSL is enabled.

Example 1 Returning All Entries

The following command returns all entries in the suffix under the base DN. Use this only when you need to retrieve all entries and attributes:

$ ldapsearch -h host -b "dc=example,dc=com" "(objectclass=*)"

Example 2 Narrowing a Search

The following command employs a more specific filter to narrow the search:

$ ldapsearch -h host -b "dc=example,dc=com" "(cn=Babs Jensen)"

Example 3 Searching the Root DSE Entry

The following command searches the root DSE entry, requesting supported naming contexts and supported LDAP versions. Notice you specify the scope as only the base entry:

$ ldapsearch -h host -b "" -s base "(objectclass=*)" \
 namingContexts supportedLDAPVersion
version: 1
dn:
namingContexts: dc=example,dc=com
supportedLDAPVersion: 2
supportedLDAPVersion: 3

Example 4 Searching the Schema Entry

The following command searches the schema entry, which contains the directory schema. Notice that you can request the operational attribute subSchemaSubEntry on any entry to determine which entry holds the schema attributes, in this case cn=schema. Then you specify the scope as only the base entry:

$ ldapsearch -h host -b "" -s base "(objectclass=*)" subSchemaSubEntry
version: 1
dn:
subSchemaSubEntry: cn=schema
$ ldapsearch -h host -b "cn=schema" -s base "(objectclass=*)"
version: 1
dn: cn=schema
…

Example 5 Setting the Base DN

The following commands set the LDAP_BASEDN environment variable, and then use it when searching the directory. The syntax of the first command may not work for your shell. Refer to the documentation about your shell for instructions on setting environment variables.

$ LDAP_BASEDN="dc=example,dc=com"; export LDAP_BASEDN
$ ldapsearch -h host "(givenname=Barbara)" cn uid
version: 1

dn: uid=bjablons, ou=People, dc=example,dc=com
cn: Barbara Jablonski
uid: bjablons

dn: uid=bhal2, ou=People, dc=example,dc=com
cn: Barbara Hall
uid: bhal2

dn: uid=bjensen, ou=People, dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
uid: bjensen

dn: uid=bmaddox, ou=People, dc=example,dc=com
cn: Barbara Maddox
uid: bmaddox

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis
$

Example 6 Using a Filter File

The following commands demonstrate use of a filter file. The results show the directory server responds to separate searches for each filter.

$ cat filters
sn=Francis
givenname=Barbara
$ ldapsearch -b "dc=example,dc=com" -h host -f filters cn uid
version: 1

dn: uid=rfrancis, ou=People, dc=example,dc=com
cn: Richard Francis
uid: rfrancis

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis

dn: uid=bjablons, ou=People, dc=example,dc=com
cn: Barbara Jablonski
uid: bjablons

dn: uid=bhal2, ou=People, dc=example,dc=com
cn: Barbara Hall
uid: bhal2

dn: uid=bjensen, ou=People, dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
uid: bjensen

dn: uid=bmaddox, ou=People, dc=example,dc=com
cn: Barbara Maddox
uid: bmaddox

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis
$

Example 7 Escaping Commas

The following command demonstrates use of the backslash (\) to escape a comma within a base DN.

$ ldapsearch -b "o=Example Company\, Inc.,dc=example,dc=com" \
 -h host "(givenname=Barbara)"

SSL Authentication Examples

The following examples demonstrate using SSL authentication for searches.

Example 8 Using Server Authentication

$ ldapsearch -h host -p 636 -b dc=example,dc=com \
 -P /home/bjensen/security -D uid=bjensen,ou=people,dc=example,dc=com \
 -w - "(givenname=Barbara)"
Enter bind password:

Example 9 Using Client Authentication

$ ldapsearch -h host -p 636 -b dc=example,dc=com \
 -P /home/bjensen/security -N "bjscert" -K /home/bjensen/security \
 -W keypassword "(givenname=Barbara)"

International Search Examples

The following examples show search filters used to perform international searches on directory data. Each example gives all the possible matching rule filter formats so that you can become familiar with the formats and select the one that works best for you.

Example 10 International Less Than Search

When you perform a locale-specific search using the less than operator (<) or suffix (.1), you search for all attribute values that come before the given attribute in a specific collation order.

Any of the following filters can be used to search for all surnames that come before the surname Marquez in the Spanish collation order.

sn:2.16.840.1.113730.3.3.2.15.1:=< Marquez
sn:es:=< Marquez
sn:2.16.840.1.113730.3.3.2.15.1.1:=Marquez
sn:es.1:=Marquez

Example 11 International Less Than or Equal To Search

When you perform a locale-specific search using the less than or equal to operator (<=) or suffix (.2), you search for all attribute values that come at or before the given attribute in a specific collation order.

Any of the following filters can be used to search for all room numbers that come at or before room number CZ422 in the Hungarian collation order.

roomNumber:2.16.840.1.113730.3.3.2.23.1:=<= CZ422
roomNumber:hu:=<= CZ422
roomNumber:2.16.840.1.113730.3.3.2.23.1.2:=CZ422
roomNumber:hu.2:=CZ422

Example 12 International Equality Search

When you perform a locale-specific search using the equal to operator (=) or suffix (.3), you search for all attribute values that match the given attribute in a specific collation order.

Any of the following filters can be used to search for all businessCategory attributes with the value Softwareprodukte in the German collation order.

businessCategory:2.16.840.1.113730.3.3.2.7.1:== Softwareprodukte
businessCategory:de:== Softwareprodukte
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte
businessCategory:de.3:=Softwareprodukte

Example 13 International Greater Than or Equal To Search

When you perform a locale-specific search using the greater than or equal to operator (>=) or suffix (.4), you search for all attribute values that come at or after the given attribute in a specific collation order.

Any of the following filters can be used to search for all localities that come at or after Québec in the French collation order.

locality:2.16.840.1.113730.3.3.2.18.1:=>= Québec
locality:fr:=>= Québec
locality:2.16.840.1.113730.3.3.2.18.1.4:=Québec
locality:fr.4:=Québec

Example 14 International Greater Than Search

When you perform a locale-specific search using the greater than operator (>) or suffix (.5), you search for all attribute values that come at or before the given attribute in a specific collation order.

Any of the following filters can be used to search for all mail hosts that come after host schranka4 in the Czech collation order.

mailHost:2.16.840.1.113730.3.3.2.5.1:=> schranka4
mailHost:cs:=> schranka4
mailHost:2.16.840.1.113730.3.3.2.5.1.5:=schranka4
mailHost:cs.5:=schranka4

Example 15 International Substring Search

When you perform an international substring search, you search for all values that match the given pattern in the specified collation order.

Any of the following filters can be used to search for all user IDs that end in ming in the Chinese collation order.

uid:2.16.840.1.113730.3.3.2.49.1:=* *ming
uid:zh:=* *ming
uid:2.16.840.1.113730.3.3.2.49.1.6*_:=*ming_*
uid:zh.6*_:=*ming_*

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
3: Search exceeded the time limit for operations on the server; LDAP_TIMELIMIT_EXCEEDED; 0x03.
4: Search returned more results than the maximum number allowed by the server; LDAP_SIZELIMIT_EXCEEDED; 0x04.
10: Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
11: Search returned more results than the maximum number a client application is allowed by the server to retrieve; LDAP_ADMINLIMIT_EXCEEDED; 0x0b.
32: Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
34: Base DN is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
53: Directory is read-only; LDAP_UNWILLING_TO_PERFORM; 0x35.
81: The directory server did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
85: The search exceeded the time limit specified using the -l option; LDAP_TIMEOUT; 0x55.
87: An error occurred while parsing and BER-encoding the specified filter; LDAP_FILTER_ERROR; 0x57.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: The directory server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving

ldapsubtdel(1)

Name

ldapsubtdel– recursively delete a subtree of LDAP entries

Synopsis

install-path/dsrk/bin/ldapsubtdel 
-b baseDN [options]

Description

The ldapsubtdel command attempts recursively to delete a subtree of LDAP entries under the entry having the distinguished name (DN) specified as a parameter to the -b option. You must bind as a user having access to delete the entries specified.

Options

The ldapsubtdel command supports the following options:

-b DN

Delete entries under the entry with the specified DN.

Default is to delete entries under the specified entry, but not to delete the specified entry itself. Use the -r option to delete the specified entry as well.

-D bindDN

Use the specified bind DN to authenticate to the directory.

If the bind DN is not specified, the ldapsubtdel command attempts anonymous authentication.

-H

Display a usage message.

-h hostname

Connect to the directory on the specified host.

Default is to connect to the local host on the loopback address, 127.0.0.1.

-j filename

Use the bind password in the specified file to authenticate to the directory.

-M

Manage referrals, deleting the entries containing referrals instead of the entries obtained by following referrals.

Default is to follow referrals and delete the entries to which the entries in the subtree refer.

-n

Display what would be done, but do not carry out any deletions.

Default is to carry out the deletions.

-p port

Connect to the directory on the specified port.

Default is to connect to the default simple authentication port for LDAP, 389.

-r

Also delete the entry having the DN specified as the parameter to the -b option.

Default is not to delete the entry specified.

-V LDAPVersion

Use the specified LDAP version, either 2 or 3.

Default is to use version 3.

-v

Display verbose output, including information about each deletion performed.

-w password

Use the specified bind password to authenticate to the directory.

-w -

Prompt for the bind password so it does not appear on the command line.

Examples

The example in this section uses the following conventions:

The ldapsubtdel command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory server listens on port 389, the default for non-SSL connections.

Example 1 `ldapsubtdel`: Deleting an Entire Subtree

The following command demonstrates deletion of an entire test subtree of LDAP entries:

$ ldapsubtdel -h host -D uid=hmiller,ou=people,dc=example,dc=com -w - \
-b ou=test,dc=example,dc=com -r -v
Enter bind password:
Processing subtree ou=test,dc=example,dc=com
Deleting entry uid=test0,ou=test,dc=example,dc=com
…
Deleting entry uid=test99,ou=test,dc=example,dc=com

Deleting entry ou=test,dc=example,dc=com

Successfully deleted subtree ou=test,dc=example,dc=com

If you read Example.ldif, you see that hmiller's password is hillock.

Exit Status

The ldapsubtdel command exits with status 0 if it completes successfully. Otherwise it exits with non-zero status.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

DSEE 7.0 Last Revised February 9, 2009

ldif(1)

Name

ldif– format input by adding base64 encoding to make it suitable for inclusion in an LDIF file

Synopsis

install-path/bin/ldif 
 [-b] attrtype

Description

The ldif command formats input by adding base64 encoding to make it suitable for inclusion in an LDIF file. This makes it easy to include binary data, such as JPEG images, along with other textual attribute values. In an LDIF file, base64 encoded attribute values are indicated as ::encoded data.

In addition to binary data, other values that must be base64 encoded include any value that begins with a semicolon (;) or a space, and any value that contains non-ASCII data, including newlines. The ldif command takes any input and formats it with the correct line continuation and appropriate attribute information.

Options

The following options are supported:

-b

Specifies that the ldif command should interpret the entire input as a single binary value.

As an alternative to the -b option, you can use the :<URL specifier notation, which is simpler to use. For example, jpegphoto:<file:///tmp/myphoto.jpg. Although the official notation requires three /// the use of one / is tolerated.

Exit Status

The following exit values are returned:

0: Successful completion.
1: An error occurred.

On error, verbose error messages are output to standard output.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Evolving

ldifxform(1)

Name

ldifxform– reformat LDIF text

Synopsis

install-path/dsrk/bin/ldifxform 
 [-h] [-i input.ldif] [-o output.ldif] -c command...

Description

The ldifxform command reformats LDAP Data Interchange Format (LDIF) text, converting between all of the most common character sets, extracting attribute values, modifying attribute names, ordering entries based on attribute values, or giving detailed statistics. In all cases, input LDIF is not changed.

Options

The ldifxform command supports the following options:

-c command

Apply the specified reformatting operation.

The ldifxform command supports the following reformatting operations:

Attribute Modification

The ldifxform command can replace attribute values and remove attribute. To modify attributes, use the following options:

-c suppressoptions

Remove all options other than binary from attribute types.

-c tcut=attribute

Remove the specified attribute from output.

Use this option once for each attribute to remove.

-c tpreserve=attribute

Remove all attributes except the specified attribute from output.

Use this option once for each attribute to retain.

-c treplace=old:new

Replace the old attributes with the new attribute type in output.

Use this option once for each attribute to rename.

Character Set Conversions

The ldifxform command can convert LDIF from one character set to another. To convert character sets, use the following options:

-c to=charSet: Convert to the specified character set to UTF-8.
-c from=charSet: Convert from the specified character set to UTF-8.

The following replacements for charSet are supported on all platforms:

88591

ISO-8859-1 character set

Conversions to this format strip characters not available in the character set.

ascii

ASCII character set

Non ASCII characters are replaced with ? when converting to this format.

mstxt

Windows Unicode Text character set

t61

T.61 character set used by X.500 and LDAP v2 servers

Conversions to this format strip characters not available in the character set.

Additional character sets may be supported for your platform. Use the -h option to display further character sets supported for your platform.

Directory Analysis

The ldifxform command can generate statistical information to help you analyze directory content. To generate statistical information, use the following options:

-c stats: Generate statistical information and append it to the output.
-c statsonly: Generate statistical information instead of other output.

Sorting and Ordering

Many directory servers return search results in the order that entries were loaded into the database. The ldifxform command can sort and order the entries before they are imported into the directory. To sort LDIF, use the following options:

-c order

Sort entries into hierarchical order.

-c sort=attribute

Sort entries in increasing order according to their values for the specified attribute. This is equivalent to alphabetical order for string-valued attributes.

-c sort=^attribute

Sort entries in decreasing order according to their values for the specified attribute. This is equivalent to reverse alphabetical order for string-valued attributes.

-c split=number

Generate the specified number of LDIF files, which can be loaded into the server by multiple clients in parallel. Each output file has a name of the form output_ldifxform_c_n, where

output: Reflects the file name passed to the -o option
c: Corresponds to the number of components in the root DN of the LDIF file
n: The number of the part from 1 to number, inclusive.

Text Transformations

The ldifxform command can perform a number of text transformations affecting the presentation and encoding of the LDIF text. To perform text transformations, use the following options:

-c cleanzero

Remove trailing zero bytes from attribute values.

Use this option when processing LDIF from a buggy encoder.

-c longlines

Do not wrap long lines at the 79th column.

The output can be parsed again, but common tools such as sed and grep on some platforms may not handle lines longer than 1024 characters.

-c nob64

Undo base64 encoding.

The output cannot be parsed again if any attributes have values that are binary or that begin with special characters.

-c nocomments

Remove comments from the output.

-c nodn

Remove DNs from the output.

The output is no longer LDIF.

-c notypes

Remove attribute types from the output.

The output is no longer LDIF.

-c sevenbit

Base64 encode any attribute values containing bytes not present in ASCII.

-h

Display a usage message briefly describing all options.

-i input.ldif

Read input from the file specified.

When this option is omitted, the ldifxform command reads from standard input.

-o output.ldif

Write output to the file specified.

When this option is omitted, the ldifxform command writes to standard output.

Extended Description

The ldifxform command acts as a stream filter, reading input from one file, performing transformations and writing the output to another file. Each transformation is specified by a command parameter to the -c option. Multiple compatible transformations may be performed simultaneously.

Some transformations produce LDIF output destined to be reloaded into a directory. For example, renaming an attribute can be more easily processed on an LDIF file than online through requests to a directory server.

Other transformations do not produce LDIF; they are intended to provide an analysis of directory contents. For example, you may extract all different values of a specific attribute and list them under the DN in which they occur. The statistical operations provide counts of entries and attributes.

Examples

The examples in this section use the following conventions:

The ldifxform command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port 389, the default for non-SSL connections.

Example 1 `ldifxform`: Transforming Search Results to a List

The following command reformats search results into a simple list of employees placed in order by their room number:

$ ldapsearch -h host -b dc=example,dc=com "(uid=*jensen)" | ldifxform \
-c "tpreserve=roomNumber" -c "tpreserve=cn" -c "sort=roomNumber" -c nodn -c notypes
version: 1
#:ordered: TRUE
 
 Barbara Jensen
 Babs Jensen
 0209
 
 Allison Jensen
 0784
 
 Kurt Jensen
 1944
 
 Richard Jensen
 2631
 
 Gern Jensen
 4609
 
 Ted Jensen
 4717
 
 Jody Jensen
 4882

Example 2 `ldifxform`: Generating Statistical Output

The following command generates statistical output from search results:

$ ldapsearch -h host -b dc=example,dc=com "(uid=*jensen)" | ldifxform -c statsonly
# Basic statistics
#:linecount: 121
#:entrycount: 7
# Number of nonleaf entries (at least one subordinate)
#:nonleafcount: 1
# Number of leaf entries (no subordinates)
#:leafcount: 7
# Largest number of entries immediately below a single nonleaf entry
#:maximmsubr: 7
# Number of levels in the DIT hierarchy
#:maxdepth: 4
# Largest number of AVAs in an RDN forming an entry's DN, normally 1.
#:maxrdns: 1
# Attribute types used in the LDIF file
# e is number entries containing this attr, v is total number of values,
# l is total length, m is max length of any one value, s is general syntax
# and x is extra encoding information.
#:attrstatsinfo: t=description e=1 v=1 l=49 m=49 i=1 s=cis x=ascii
#:attrstatsinfo: t=roomnumber e=7 v=7 l=28 m=4 i=1 s=int
#:attrstatsinfo: t=facsimiletelephonenumber e=7 v=7 l=105 m=15 i=1 s=tel
#:attrstatsinfo: t=telephonenumber e=7 v=7 l=105 m=15 i=1 s=tel
#:attrstatsinfo: t=mail e=7 v=7 l=130 m=19 i=1 s=cis x=mail
#:attrstatsinfo: t=uid e=7 v=7 l=49 m=7 i=1 s=cis x=alphanumeric
#:attrstatsinfo: t=l e=7 v=7 l=71 m=11 i=1 s=cis x=ascii
#:attrstatsinfo: t=ou e=7 v=14 l=144 m=19 i=2 s=cis x=ascii
#:attrstatsinfo: t=objectclass e=7 v=28 l=294 m=20 i=4 s=cis x=alphanumeric
#:attrstatsinfo: t=givenname e=7 v=7 l=36 m=7 i=1 s=cis x=alphanumeric
#:attrstatsinfo: t=sn e=7 v=7 l=42 m=6 i=1 s=cis x=alphanumeric
#:attrstatsinfo: t=cn e=7 v=8 l=96 m=14 i=2 s=cis x=ascii
# Counts of values of specific attribute types
#:attrdomaininfo: t=objectclass v=7 inetOrgPerson
#:attrdomaininfo: t=objectclass v=7 person
#:attrdomaininfo: t=objectclass v=7 top
#:attrdomaininfo: t=objectclass v=7 organizationalPerson

Exit Status

The ldifxform command exits with status 0 if it completes successfully. Otherwise, it exits with non-zero status.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

DSEE 7.0 Last Revised February 9, 2009

logconv(1)

Name

logconv– analyze Directory Server access logs

Synopsis

install-path/dsrk/bin/logconv 
 [options] logfile...

Description

The logconv command analyzes Directory Server access logs, specified as the logfile argument to the command, to extract usage statistics and count occurrences of significant events.

As the logconv command depends on the content of the access logs, output depends on the quantity of information present in the access logs. Refer to the Directory Server documentation for instructions on how adjust how much information Directory Server writes to the access logs.

The user running the logconv command must have at least read access to the Directory Server log files.

The logconv command ignores log files named access.rotationinfo.

Options

The logconv command supports the following options.

Options specified here without a preceding dash (-) may be specified in any order, but must be specified together as a single option such as -abcefgijlnrtux.

-A0 filename

Write statistics on client activity based on the number of operations to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-A1 filename

Write statistics on client activity based on the number of connections to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-a

List the most frequently used base DNs.

-B filename

Write statistics on the most frequently used bind DNs to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-b

List the most frequently used bind DNs.

-C filename

Write statistics on the number of operations performed per connection to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-c

List the number of occurrences for each type of connection code.

-DELIM

Generate a field-delimited, formatted report when using the -B or -R options.

You can import this report into a spreadsheet application.

-d rootDN

Use the specified DN to identify operations performed by Directory Manager.

Default is cn=Directory Manager.

-E errorCode

Generate statistics on occurrences of the specified error code.

This option overrides the use of options in the list -abcefgijlnrtux.

-e

List the most frequently occurring error and return codes.

-f

List the bind DNs with the most failed binds due to invalid credentials.

-g

List details of all abandoned operations.

-h

Display the usage message.

-I interval

Use the specified interval for reporting when generating a report using the -B or -R options. The interval may be MINUTE, HOUR, DAY, or MONTH.

-i

List the IP addresses and connection codes for clients opening the most connections.

This option helps detect clients that may attempt to compromise security.

-j

Generate recommendations based on the data collected.

-l

List the most frequently occurring search filters.

-N

Resolve IP addresses to host names.

Using this option may impact performance.

-n

List the largest and most frequent number of entries per result (nentries).

-P filename

Write a report on pending operations to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-R filename

Write a report on operations to the specified file.

This option overrides the use of options in the list -abcefgijlnrtux.

-r

List the most frequently requested attributes.

-s number

Return the specified number of results per category.

Default is 20.

-t

List the longest and most frequent operation times (etimes).

-u

List details about unindexed searches.

-V

Enable verbose output. Same as -abcefgijlnrtux.

-v

Display version information and exit.

-X IPAddress

Exclude operations originating from clients with the specified IP address, for example when repeated health check operations come from a load balancer.

Repeat this option to exclude multiple addresses.

-x

List the number and OID of all extended operations requested.

Extended Description

The logconv command generates three types of statistics useful for monitoring Directory Server use and optimizing Directory Server configuration:

Counts of events such as total binds and total searches performed
Lists of the most frequently occurring parameters in LDAP requests

For example, the logconv command generates lists of the top ten bind DNs, base DNs, filter strings, and attributes returned. As generating such lists is computation intensive, you must explicitly request their generation using the appropriate options.
Counts of occurrences for error codes such as those defined in <ldap.h>

Performance of the logconv command is affected by the volume of data in the access logs. To ensure acceptable performance, avoid running the logconv command on more than 1 GB of access logs at a time.

Furthermore, some of the data extracted depends on connection and operation numbers reset when you restart Directory Server. To obtain the most accurate counts, avoid analyzing logs that span a server restart.

Examples

Examples in this section use the following conventions:

The logconv command is found in a directory present in the PATH used for the examples.
Directory Server stores access logs in /var/ds/logs.
The current user has read access to the logs.

Example 1 `logconv`: Generating Statistics and Recommendations

The following command generates statistics on client connections, binds, abandoned operations, and unindexed searches, and generates recommendations for performance improvements and further investigation:

$ logconv -ibgju /var/ds/logs/access*

Example 2 `logconv`: Examining Binds with Invalid Credentials

The following command counts the number of times clients attempted to bind with invalid credentials, error 49 LDAP_INVALID_CREDENTIALS, resolving client IP addresses to host names:

$ logconv -N -E 49 /var/ds/logs/access*

Example 3 `logconv`: Generating a Report

The following command generates a field delimited report on operations, suitable for import into a spreadsheet application:

$ logconv -DELIM -R report.txt /var/ds/logs/access
$ cat report.txt
Year|Month|Day|Time|Operations|Results|Performance|Connections|
 Searches|Modifications|Adds|Deletes|Modrdns|Binds|Extended Ops|Compares
2009|Apr|05|07:51:04|18119|18129|100.1%|10|0|0|0|0|0|18119|0|0
2009|Apr|05|08:09:30|12875|12883|100.1%|12878|0|0|0|0|0|12875|0|0

Long lines in this example have been wrapped for readability.

Exit Status

The logconv command exits with status 0 if it completes successfully. Otherwise it exits with non-zero status.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

DSEE 7.0 Last Revised February 9, 2009

makeldif(1)

Name

makeldif– generate LDIF for import into a directory

Synopsis

install-path/dsrk/bin/makeldif 
 [options] -t template -o output.ldif

Description

The makeldif command generates LDAP Data Interchange Format (LDIF) files for import into a Lightweight Directory Access Protocol (LDAP) directory.

Options

The makeldif command supports the following options:

-b filename

Write bind information to this file when generating LDIF.

Lines of this file include a DN followed by a password, separated by a tab:

DN password

-C delimiter

Use the specified character instead of a comma when reading from a comma-separated format using the -c option.

-c filename

Use the specified comma-separated variable format file as input for generating LDIF.

-D

Run in debug mode, displaying additional information about errors.

-d filename

Write DNs to this file when generating LDIF.

-F filename

Write search filters constructed to find the entries generated to the specified file when generating search filters with the -T option.

-f filename

Use the specified file containing a list of first names to use when generating LDIF.

When this option is not used, the makeldif command uses the first.names file expected in the current directory.

-H

Display usage information and exit.

-I

Ignore the first line when reading from a comma-separated format using the -c option. Use this option when the initial line is a header not containing data.

-i attribute

Use values of the specified attribute as login IDs when writing login information using the -L option.

-L filename

Write login information to this file when generating LDIF.

Lines of this file include a login ID followed by a password, separated by a tab:

loginID	password

Specify the login ID attribute using the -i option. Default is uid.

-l filename

Use the specified file containing a list of last names to use when generating LDIF.

When this option is not used, the makeldif command uses the last.names file expected in the current directory.

-M

Generate a separate filter file for each relevant index type when generating search filters with the -T option.

-m maximum

Write no more than the specified maximum number of entries to a single file when generating LDIF.

Default is unlimited.

-o output.ldif

Create the specified file as output.

-N minimum

Only create filters that match at least the specified number of entries when generating substring search filters with the -T option.

Default is 1.

-n number

Create substring filters having the specified number of characters when generating substring search filters with the -T option.

Default is 3.

-S

Skip branch entries (parent entries) when generating LDIF.

-s number

Use the specified positive integer as a random number generator seed.

Default is to use a seed based on the current time.

You can consistently reproduce the same output by using the same random number generator seed and same templates.

-T attribute:types

Generate search filters of the specified types for the specified attributes.

The types is a comma-separated list of the following filter types:

eq: Filters matching for equality
sub: Filters matching substrings
subAny: Filters matching substrings anywhere within the string
subFinal: Filters matching substrings at the end of the attribute value
subInitial: Filters matching substrings at the beginning of the attribute value

-t template

Use the specified LDIF template file when generating LDIF.

Refer to EXTENDED DESCRIPTION for details.

-U

Always use UNIX-style newline characters (\n).

-V

Display version information and exit.

-w

Wrap long lines when generating LDIF.

Default is to write one attribute type and value per line, potentially resulting in very long lines for some values.

-X maximum

Only create filters that match no more than the specified number of entries when generating substring search filters with the -T option.

Default is unlimited.

-x maximum

Write no more than the specified maximum number of entries under each branch for each template when generating LDIF.

Default is unlimited.

Extended Description

The makeldif command relies on a template file to customize how entries in the generated LDIF are organized and what they contain. Template files may contain the following definitions:

Global Replacement Definitions: Define strings used to replace variables in the template file itself when generating LDIF
Branch Entry Definitions: Define branches in the directory information tree (DIT) structure
Template Definitions: Define how to generate leaf entries and attribute values

A sample you can customize, example.template, is installed with Directory Server Resource Kit.

Global Replacement Definitions

Replacement definitions define strings used to replace variables in the template itself. For example, the following line defines a variable called suffix having the value dc=example,dc=com:

define suffix=dc=example,dc=com

Given this definition, all subsequent occurrences of the string [suffix] in the template file are replaced with dc=example,dc=com. The replacement takes place when lines of the template file are read into memory, with the result that replacements happen even in branch definitions and like places where other tokens are not parsed. Notice that the variable is surrounded by brackets, []. When using brackets for purposes other than delimiting global replacement variables, escape them with a backslash, as in \[ or \]. The backslash characters are removed during LDIF generation.

Branch Entry Definitions

Branch entries are parents for other entries in a suffix. In other words, the branch entry at the root of the suffix for Example.com might be defined as:

branch: dc=example,dc=com

The makeldif command can then generate a corresponding branch entry represented in LDIF as follows:

dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc=example

The makeldif command determines which object classes to use by examining the RDN of the entry, recognizing attribute types c (country), dc (domain component), l (location), o (organization), and ou (organizational unit). When you use RDNs having other attribute types, the makeldif command uses the object class extensibleObject for the entry.

To customize the branch entry itself, define additional attributes directly below the branch definition. For example, add a description attribute for the branch entry as follows:

branch: dc=example,dc=com
description: This is the description.

The resulting entry generated in LDIF appears as follows:

dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc=example
description: This is the description.

To enable generation of entries below the branch entry, add subordinateTemplate definitions directly below the branch definition. For example, add a 1000 entries using the person template below ou=people,dc=example,dc=com as follows:

branch: ou=people,dc=example,dc=com
subordinateTemplate: person: 1000

You can add multiple subordinateTemplate definitions. For example, enable addition of 1000 entries using the person template and 500 entries using the personWithCertificate template below ou=people,dc=example,dc=com as follows:

branch: ou=people,dc=example,dc=com
subordinateTemplate: person: 1000
subordinateTemplate: personWithCertificate: 500

Template Definitions

Template definitions contain prototype entries with special tags allowing the makeldif command to generate many unique, custom entries. For example, a person template definition might appear as follows:

template: person
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
uid: {givenName}.{sn}
mail: {uid}@example.com
userPassword: <random:alphanumeric:8>
telephoneNumber: <random:telephone>

The first line of a template definition specifies the name of the template, here person. The makeldif command uses the name to identify the template when creating leaf entries under branch entries, based on subordinateTemplate definitions used with the branch entry definition. Each name must be unique.

A template entry may also have an rdnAttr line specifying the attribute type for the RDN of the generated entry. The rdnAttr takes a single value. Multi-valued RDNs are not supported. The default rdnAttr definition is cn if you do not provide one.

Other lines in a template definition reflect the attribute types and values to generate in the resulting LDIF. The makeldif command generates values for all recognized tokens.

Supported Attribute Value Tokens

The makeldif command support the following tokens:

<ancestordn:{depth}>

Replace this value with the DN of the entry's ancestor at the specified depth.

A depth of 1 specifies the parent entry; a depth of 2 specifies the grandparent, and so forth. If the entry does not have an ancestor at the specified depth, the makeldif command replaces the value with an empty string.

<base64:{value}>

Replace this value with a base64-encoded representation of the specified value.

The value is decoded to a byte array using the UTF-8 character set, and then the byte array is base64-encoded.

<base64:{charset}:{value}>

Replace this value with a base64-encoded representation of the specified value.

The value is decoded to a byte array using the specified character set, and then the byte array is base64-encoded.

<dn>

Replace this value with the DN of the current entry.

The RDN attribute for the entry must be assigned a value in the template before this token is used.

<exec:{command}>

Replace this value with the information sent to standard output when the specified command is executed on the system.

The replacement invokes a separate process each entry created using this template. Using this token can therefore slow LDIF generation considerably.

<exec:{command},{arg1},{arg2},…,{argN}>

Replace this value with the information sent to standard output when the specified command is executed on the system using the arguments provided.

The replacement invokes a separate process each entry created using this template. Using this token can therefore slow LDIF generation considerably.

<file:{filename}>

Replace this value with a randomly-chosen value from the specified file.

The file must contain one value per line. Weights cannot be assigned to the values in a file. To weight values, repeat their lines multiple times in the file.

<first>

Replace this value with a first name from the first name file specified using the -f option.

If both a first and last name are included in an entry, the combination of the first and last name is guaranteed to be unique. That is, no two entries in the generated LDIF file have the same combination of first and last name values. In order to guarantee uniqueness, the first and last names must be used in their entirety. You cannot use substrings of the form {givenName:5} for example.

<guid>

Replace this value with a GUID value in the containing hexadecimal digits in the form 12345678-90ab-cdef-1234-567890abcdef.

GUID values generated are unique within the LDIF generated.

<ifabsent:{attribute}>

Include this attribute only if the specified attribute is not present on the entry.

The specified attribute must be defined in the template file before it is referenced in the ifabsent tag.

<ifabsent:{attribute}:{value}>

Include this attribute only if the specified attribute is not present on the entry or if it does not have the specified value.

The specified attribute must be defined in the template file before it is referenced in the ifabsent tag. If the specified attribute has multiple values, the makeldif command checks only the first value.

<ifpresent:{attribute}>

Include this attribute only if the specified attribute is also present on the entry.

The specified attribute must be defined in the template file before it is referenced in the ifpresent tag.

<ifpresent:{attribute}:{value}>

Include this attribute only if the specified attribute is also present on the entry and has the specified value.

The specified attribute must be defined in the template file before it is referenced in the ifpresent tag. If the specified attribute has multiple values, the makeldif command checks only the first value.

<last>

Replace this value with a last name from the last name file specified using the -l option.

<list:{value1},{value2},…,{valueN}>

Replace this value with a randomly-chosen value from the specified, comma-delimited list.

Each value has an equal chance of being chosen.

<list:{value1}:{weight1},{value2}:{weight2},…,{valueN}:{weightN}>

Replace this value with a randomly-chosen value from the specified, comma-delimited list.

The weight associated with each list item determines how likely that value is to be chosen. A list item with a weight of 2 is twice as likely to be chosen as an item with a weight of 1. Specified only positive integer weights.

<loop:{start}:{end}>

Process this definition (end - start + 1) times, replacing this token each time with a number beginning at {start} and incrementing by one until reaching {end}.

You may include multiple loop tokens on the same line and using different {start} values, but only the first {end} value is used to determine how many copies of the line to create.

<parentdn>

Replace this value with the DN of the parent entry.

<presence:{percent}>

Include the attribute on the specified percentage of entries generated from this template definition. The percentage value is a number between 0 and 100.

Use this token only with attributes not required by the entry's object classes, and include something in the value of the attribute to be generated on entries including the attribute.

<random:alpha:{length}>

Replace this value with a string of {length} randomly-chosen alphabetic characters.

<random:alpha:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen alphabetic characters.

<random:alphanumeric:{length}>

Replace this value with a string of {length} randomly-chosen alphanumeric characters.

<random:alphanumeric:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen alphanumeric characters.

<random:base64:{length}>

Replace this value with a string of {length} randomly-chosen base64 characters.

If the specified length is not a multiple of 4, then the base64 value produced is padded with equal signs so that the total length is a multiple of 4.

<random:base64:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen base64 characters.

<random:chars:{characters}:{length}>

Replace this value with a string of {length} characters that are randomly-selected from {characters}. {characters} may be any valid character other than the colon.

<random:hex:{length}>

Replace this value with a string of {length} randomly-chosen hexadecimal digits.

<random:hex:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen hexadecimal digits.

<random:month>

Replace this value with the name of a randomly-chosen month. That is, t

The value is one of January, February, March, April, May, June, July, August, September, October, November, or December.

<random:month:{length}>

Replace this value with the first {length} characters of the name of a randomly-chosen month.

<random:numeric:{length}>

Replace this value with a string of {length} randomly-chosen numeric digits.

<random:numeric:{min}:{max}>

Replace this value with a randomly-chosen number between {min} and {max}, inclusive.

<random:numeric:{min}:{max}:{length}>

Replace this value with a randomly-chosen number between {min} and {max}, inclusive.

The value is padded with leading zeros so that it has at least {length} digits.

<random:telephone>

Replace this value with a string of randomly-chosen numeric digits in the form 123-456-7890.

This uses a US-format telephone number. You can generate telephone numbers in the format used by other countries by combining other random tags. For example, to generate a telephone number in the UK format, use +44 <random:numeric:4> <random:numeric:6>.

<sequential>

Replace this value with a sequentially-increasing numeric value.

The first value is zero. Sequential counters are separate on a per-attribute basis, so it is possible to use multiple sequential counters in the different attributes of the same entry without impacting each other.

<sequential:{firstvalue}>

Replace this value with a sequentially-increasing numeric value, where the first number starts at the specified value.

Sequential counters are separate on a per-attribute basis, so it is possible to use multiple sequential counters in different attributes of the same entry without impacting each other.

In addition to supported tokens, you can cause the makeldif command to generate attribute values from the values of attributes on the entry previously defined in the template by constructing prototype values using those attribute types in braces. For example, the following excerpt reuses givenName and sn (surname) values to define cn (common name) values:

…
givenName: <first>
sn: <last>
cn: {givenName} {sn}
…

When generating values from multi-valued attributes, the makeldif command uses the first value in the list.

To use only the first few characters of an attribute value to generate a value, add a colon followed by the length of the substring to use. For example, use {givenName:1}{sn:1}{employeeNumber} to generate values taking the first letter of the first name, followed by the first letter of the last name, followed by the employee number.

Subordinate Template Definitions

To create entries generated from one template definition below those generated by another template definition, include one or more subordinateTemplate definitions in the upper template definition.

Use this functionality with caution, however, as the makeldif command does not prevent you from generating circular references throwing the LDIF generation process into an infinite loop.

Inheritance

Template definitions support inheritance, whereby you specify a template definition that builds on a previously defined template, using the extends definition.

For example, to generate 10000 entries using the person template and an additional 1000 entries having the same structure as those generated from the person but also including a value for the userCertificate attribute, you create a template definition extending the person template as follows:

template: certificatePerson
rdnAttr: uid
extends: person
userCertificate: <random:base64:1000>

Given the person template defined previously, the certificatePerson template then has the same effect as the following:

template: certificatePerson
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
uid: {givenName}.{sn}
mail: {uid}@example.com
userPassword: <random:alphanumeric:8>
telephoneNumber: <random:telephone>
userCertificate: <random:base64:1000>

You may use multiple levels of inheritance, but you must make sure both to specify the rdnAttr value for the inherited template as the parent's RDN attribute is not automatically used, and to avoid circular references that cause infinite loops in the LDIF generation process.

Examples

Examples in this section use the following conventions:

The makeldif command is found in a directory present in the PATH used for the examples.
The sample files are located in the current directory.

Example 1 `makeldif`: Generating LDIF

The following command generates LDIF using the sample template and other files delivered with Directory Server Resource Kit.

$ makeldif -t example.template -o sample.ldif
Processed 1000 entries
Processed 2000 entries
Processed 3000 entries
Processed 4000 entries
Processed 5000 entries
Processed 6000 entries
Processed 7000 entries
Processed 8000 entries
Processed 9000 entries
Processed 10000 entries
Processing complete.
10002 total entries written.

Example 2 `makeldif`: Generating Search Filters and LDIF

The following command generates LDIF and corresponding search filters base.

$ makeldif -T uid:eq -T cn:eq,sub -F filters.txt -t example.template -o sample.ldif
Processed 1000 entries
Processed 2000 entries
Processed 3000 entries
Processed 4000 entries
Processed 5000 entries
Processed 6000 entries
Processed 7000 entries
Processed 8000 entries
Processed 9000 entries
Processed 10000 entries
Processing complete.
10002 total entries written.
Writing filters to filters.txt
Wrote 10000 equality filters for uid
Wrote 10000 equality filters for cn
Wrote 1827 subInitial filters for cn
Wrote 7328 subAny filters for cn
Wrote 2099 subFinal filters for cn

Exit Status

The makeldif command exits with status 0 if it completes successfully. Otherwise it exits with non-zero status.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

DSEE 7.0 Last Revised February 9, 2009

mmldif(1)

Name

mmldif– combine multiple ldif files into a single, authoritative set of entries

Synopsis

install-path/bin/mmldif 
 [-c ] [-D ] [-o out.ldif] files

Description

The mmldif command combines multiple LDIF files into a single authoritative set of entries. Typically each LDIF file is from a master server cooperating in a multi-master replication environment (for example, masters that refuse to sync up). Optionally, the mmldif command can generate LDIF change files that could be applied to the original file to bring it up to date with the authoritative version. At least two input files must be specified.

Options

The following options are supported:

-c: Write a change file (.delta) for each input file.
-D: Print debugging information.
-o: Write authoritative data to this file. If not specified, the command compares the input files, but does not generate output LDIF files.
files: Two or more LDIF files to combine into a single set of entries. For example, in1.ldif in2.ldif.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Evolving

modrate(1)

Name

modrate– measure modification performance for an LDAP directory

Synopsis

install-path/dsrk/bin/modrate 
 [options] -b baseDN -M attribute:length:regexp

Description

The modrate command measures the rate at which an LDAP directory can perform random, user-defined modifications. As with all measures of performance, results depend on many factors, including what options you pass to the modrate command, and also how the directory service itself is tuned.

The command uses LDAP v3, and cannot be used to authenticate to an LDAP v2 directory not supporting LDAP v3.

Options

The modrate command supports the following options:

-a

Run in asynchronous mode, not waiting for results before requesting subsequent modifications. The maximum number of threads the modrate command can use is limited by the number of file descriptors the operating system allows the process to use. The time is measured starts when the request is sent and finishes when the result is received.

-b targetDN

Use the specified DN for the target entry.

Refer to Random Target Syntax and Random Target Substitution for details.

-C messages

Display the specified number of results messages before exiting. Results messages appear by default as output on standard out, similar to the following:

Avg r= 272.00/thr ( 54.40/sec), total=   816

This shows output for three threads requesting modifications for five seconds. The average modify rate per thread is 54.40 per thread per second for the interval measured. The total shown for all threads is 816.

Default is to continue iterating until the command is interrupted.

-D bindDN

Use the specified bind DN to authenticate to the directory.

If the bind DN is not specified, the modrate command attempts anonymous authentication.

-E

Display the bind DN of entries for which modifications did not complete successfully.

-e

Display the number of attempted modifications that did not complete successfully.

-h hostname

Connect to the directory on the specified host.

Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

Default is to connect to the local host on the loopback address, 127.0.0.1.

-i filename

Use the file specified to generate target entry base DNs at random.

Refer to Random Target Syntax and Random Target Substitution for details.

-j seconds

Display results each specified number of seconds.

Default is to display results every 5 seconds.

-K

Keep connections open and only bind once, measuring only the time required to perform the modify operation.

Default is to measure the duration the connection is active as the modification sequence.

-k

Keep connections open, measuring only the time required to perform the bind and modify operations.

Default is to measure the duration the connection is active as the modification sequence.

-M attribute:length:regexp

Generate random values for modifications on the specified attribute, having the specified integer length in characters. Generate the values from the specified regular expression, regexp, which has the form (c*(c-c)*)* where c represents an ASCII character.

For example, the regexp parameter could be [A-Z][a-z][0-9], or simply aString

If the attribute specified does not exist on the target entry, it is added, subject to schema checking.

-m maxIter

Perform no more than the specified number of modifications per thread.

Default is for each thread to continue iterating until the command is interrupted.

-O maxHops

Traverse no more than the specified number of hops when following referrals.

Default is 5.

-p port

Connect to the directory on the specified port.

Default is to connect to the default simple authentication port for LDAP, 389.

-q

Run in quiet mode, not displaying results.

Default is to display results every 5 seconds, which you can adjust using the -j option.

-R

Do not follow referrals.

Default is to follow referrals.

-r maxRand

Use the specified maximum to determine the range for random numbers replacing %d formatting specifications when modifying random target entries.

When you use this option twice, the first occurrence generates random numbers in the range [0,maxRand1-1] for the first %d, the second [1,maxRand2] for the second %d.

Refer to Random Target Syntax and Random Target Substitution for details.

-S randSeed

Use the specified seed, an unsigned int, for random number generation.

Default seed is 0.

-t threads

Use the specified number of the threads to connect to the server.

Default is to use one thread.

-v

Display verbose output.

-W filename

Read the bind password from the specified file.

-w password

Use the specified bind password to authenticate to the directory.

-w –

Prompt for the bind password so it does not appear on the command line or in a file.

Extended Description

The modrate command repeatedly requests modification operations of a directory server. Threads may be configured to keep open connections or perform LDAP bind with each operation. The command-line options let you specify the bind credentials.

The command uses LDAP v3, and cannot be used to authenticate to an LDAP v2 directory not supporting LDAP v3. Furthermore, the modrate command uses simple authentication, not secure binding.

The modrate command cannot set a time limit for operations.

By default, the modrate command continues its task indefinitely, displaying results periodically, and displaying any errors encountered as well without interrupting operation.

Random Target Syntax

Include randomly generated numbers by specifying %d and %s placeholders in the base DN. These placeholders are then replaced according to the following rules:

%d

Replace this placeholder with random integer values depending on the maxRand parameter to the -r option.

The -r option may be used at most two times to generate random target entries. Replacement values for the %d placeholder range over [0,maxRand1—1] for the first use of the -r option, and over [1,maxRand2] for the second.

%s

Replace this placeholder with random strings from the file specified using the -i option.

Replacement values for this placeholder are randomly selected lines of the file specified.

Random Target Substitution

The modrate command requires that you apply the following rules for substitutions, displaying an error message when the used incorrectly:

Use only one type of placeholder, either %d or %s, per invocation of the modrate command.
Specify at least as many uses of the -r as %d placeholders used in the base DN.
Use %%d and %%s to specify literal strings %d and %s, respectively.

In order to use this random modification mechanism, you must populate your directory accordingly. For example, you can measure the modification rate using the following command:

$ modrate -D uid=hmiller,ou=people,dc=example,dc=com -w hillock  \
-b "uid=test%d,ou=test,dc=example,dc=com"  -C 3 -r 100  -M 'description:7:astring'

If you read Example.ldif, you see that hmiller's password is hillock.

In order for the modrate command to work effectively, your directory should contain entries corresponding to the following LDIF excerpt:

dn: uid=test0,ou=test,dc=example,dc=com

dn: uid=test1,ou=test,dc=example,dc=com

dn: uid=test2,ou=test,dc=example,dc=com

dn: uid=test10,ou=test,dc=example,dc=com

dn: uid=test99,ou=test,dc=example,dc=com

Examples

Examples in this section use the following conventions:

The modrate command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory server listens on port 389, the default for non-SSL connections.

Example 1 `modrate`: Sample Output

The following command performs modifications until it has displayed five results messages. Notice that each line concerns only the elapsed interval.

$ modrate -h host -D uid=hmiller,ou=people,dc=example,dc=com -w hmiller \
-C 5 -b "uid=test%d,ou=test,dc=example,dc=com" -r 100 -M "description:7:aString"
Enter bind password:
Avg r=  74.00/thr ( 14.80/sec), total=    74
Avg r= 118.00/thr ( 23.60/sec), total=   118
Avg r=  68.00/thr ( 13.60/sec), total=    68
Avg r=  39.00/thr (  7.80/sec), total=    39
Avg r=  71.00/thr ( 14.20/sec), total=    71
All threads exited

If you read Example.ldif, you see that hmiller's password is hillock.

Notice also that a result message provides the following items of information:

The average rate of modification per thread of execution
The average rate of modification per second
The total number of modification operations performed during the interval the results message concerns

Example 2 `modrate`: Modification Rate Alone

The following command keeping the connection open and binds only once:

$ modrate -h host -D uid=hmiller,ou=people,dc=example,dc=com -w hmiller \
-C 5 -b "uid=test%d,ou=test,dc=example,dc=com" -r 100 -M "description:7:aString" -K
Enter bind password:
Avg r= 272.00/thr ( 54.40/sec), total=   272
Avg r= 183.00/thr ( 36.60/sec), total=   183
Avg r= 180.00/thr ( 36.00/sec), total=   180
Avg r= 257.00/thr ( 51.40/sec), total=   257
Avg r= 226.00/thr ( 45.20/sec), total=   226
All threads exited

If you read Example.ldif, you see that hmiller's password is hillock.

Exit Status

The modrate command returns the following exit status codes.

0: Successful completion.
non-zero: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

pwdhash(1)

Name

pwdhash– print the encrypted form of a password by using one of the server's encryption algorithms

Synopsis

install-path/bin/pwdhash 
-D instance-path [-H ] [-c comparepwd | -s scheme] password...

Description

The pwdhash command prints the encrypted form of a password using one of the encryption algorithms available to the server. If a user cannot log in, you can use this command to compare the user's password with the password stored in the directory.

Options

The following options are supported:

-c: Specifies the encrypted password with which the user password is to be compared. The result of this comparison is either OK or password does not match.
-D instance-path: Specifies where the Directory Server instance is located.
-H: Specifies that the passwords are hex-encoded.
password: The clear password from which the encrypted form should be generated (or against which the password in the directory should be compared).
-s: Generates the encrypted passwords according to the encryption scheme. The available schemes are SSHA, SHA, CRYPT, and CLEAR.

Examples

Example 1 Encrypting a Password

$ pwdhash -D /local/dsInst -s SSHA mypassword
{SSHA}mtHyZSHfhOZ4FHmvQe09FQjvLZpnW1wbmW05cw==

Example 2 Comparing Two Passwords

$ pwdhash -D /local/dsInst \
-c "{SSHA}mtHyZSHfhOZ4FHmvQe09FQjvLZpnW1wbmW05cw==" aPassword
pwdhash: password does not match

Exit Status

The following exit values are returned:

0: Successful completion.
1: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Stable

DSEE 7.0 Last Revised November 19, 2008

repldisc(1)

Name

repldisc– discover a replication topology

Synopsis

install-path/bin/repldisc 
 [-D bindDN] [-w password] [-j file ] [-t ] [-n ] [-a ]
 [-p port] [-T timeout] [-J file] [-W keypassword] [-K keydbpath]
 [-N certname] [-P certdbpath] [-e SSL port] [-b ReplicaRoot]
 -s |  -S  HostSpec

Description

The repldisc command enables the discovery of a replication topology. Topology discovery starts with one server and constructs a graph of all known servers (using the RUVs and Replication Agreements). repldisc then prints an adjacency matrix describing the topology.

Options

The following options are supported:

-a

Specifies that only the arcs between pairs of connected hosts are printed. For more information, see EXAMPLES.

Note –

If the total line length of the output exceeds 80 characters, symbolic host names are used, accompanied by a legend. Otherwise, full host names are printed. Using the -a option ensures that symbolic host names are not used.

-b

The suffix (replica root) that has been specified for replication. If -b is not specified, the delay for all suffixes is printed.

-D

Distinguished name with which to bind to the server. This parameter is optional if the server is configured to support anonymous access. If a DN is specified in the HostSpec option, this overrides the -D option.

-j

If specifying the default password at the command-line poses a security risk, the password can be stored in a file. The -j option specifies this file.

-n

Specifies that repldisc should not run in interactive mode. Running in interactive mode allows you to re-enter the bindDN, password, host and port, if a bind error occurs.

-p

The TCP port used by the instance. The default port is 389. If a port is specified in the HostSpec, this overrides the -p option.

-t

Prints the mode of transport (SSL or CLEAR).

-T

Specifies the number of seconds after which repldisc times out if the server connection goes down.

-w

Password associated with the distinguished name specified by the -D option. If a password is specified in the HostSpec, this overrides the -w option.

HostSpec

Host specification, which takes the form [binddn:[password]@] host[:port]. The following is an example:

cn=admin,cn=Administrators,cn=config:mypword@myserver:1389

If you are using SSL, use -S in the server specification. In this case, HostSpec specifies the certificate name and key password, rather than the bindDN and password.

SSL OPTIONS

You can use the following options to specify that repldisc uses LDAPS when communicating with Directory Server. You can also use these options if you want to use certificate-based authentication. These options are valid only when LDAPS has been turned on and configured.

-e: Default SSL port, 636.
-J: This option has the same function as the -j option, for the key password.
-K: Specifies the name of the certificate key used for certificate-based client authentication. For example, -K Server-Key.
-N: Specifies the certificate name to use for certificate-based client authentication. For example, - N Server-Cert. If this option is specified, the -W option is required.
-P: Specifies the location of the certificate database.
-W: Specifies the password for the certificate database identified by the -P option. For example, -W serverpassword.

Examples

Example 1 Single Replication Scenario

$ repldisc -D cn=admin,cn=Administrators,cn=config -w pwd \
 -b o=rtest -s myserver:1389

Topology for suffix: o=rtest

Legend:

^ : Host on row sends to host on column.

v : Host on row receives from host on column.

x : Host on row and host on column are in MM mode.

H1 : france.example.com:1389

H2 : spain:1389

H3 : portugal:389

   | H1 | H2 | H3 |

===+===============

H1 |    | ^  |    |

---+---------------

H2 | v  |    | ^  |

---+---------------

H3 |    | v  |    |

---+---------------

Example 2 Using the `-a` Option

Topology for suffix: o=rtest 

Legend: 

The direction of the replication is indicated with arrows. 

Single-master: suppliers appear on left, consumers on right (->). 

Multi-master : servers are shown linked by a double arrow (<->).


france.example.com:1389 -> spain:1389 

spain:1389 -> portugal:389

Exit Status

The following exit values are returned:

0: Successful completion.
1: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Stable

Notes

The node on which you are running the entrycmp, insync, and repldisc tools must be able to reach all the specified hosts. If these hosts are unavailable, you will encounter difficulties using these tools. Ensure that all servers are up and running before using these tools.

When you identify hosts, you must use either symbolic names or IP addresses for all hosts. The replication monitoring commands do not address resolution between symbolic names and IP addresses. Using a combination of symbolic names and IP addresses can cause problems. Moreover, on multi-homed hosts, referring to the same Directory Server instance using different names may cause unexpected results.

When SSL is enabled, the directory server on which you are running the tools must have a copy of all the certificates used by the other servers in the topology.

repldisc takes the host specification from the replication agreement, unless otherwise specified at the command line.

The replication monitoring tools rely on access to cn=config to obtain the replication status. This should be taken into account, particularly when replication is configured over SSL.

DSEE 7.0 Last Revised November 19, 2008

searchrate(1)

Name

searchrate– measure search performance for an LDAP directory

Synopsis

install-path/dsrk/bin/searchrate 
 [options] -b baseDN -f filter

Description

The searchrate command measures the rate at which an LDAP directory can perform random, user-defined searches. As with all measures of performance, results depend on many factors, including what options you pass to the searchrate command, and also how the directory service itself is tuned.

Options

The searchrate command supports the following options:

-A attribute

Retrieve only the specified attribute.

Repeat this option to specify multiple attributes.

-a

Run in asynchronous mode, not waiting for results before requesting subsequent searches. The maximum number of threads the searchrate command can use is limited by the number of file descriptors the operating system allows the process to use. The time is measured starts when the request is sent and finishes when the result is received.

-b baseDN

Use the specified base DN for the target entry.

Default is the root DSE, "".

Refer to Random Target Syntax and Random Target Substitution for details on number and string substitutions.

-C messages

Display the specified number of results messages before exiting. Results messages appear by default as output on standard out, similar to the following.

Avg r=2731.00/thr (1092.40/sec), total=  5462

This shows output for two threads searching for five seconds. The average search rate per thread is 2731 searches per thread for the interval measured, for 1092.40 searches per second on average. The total shown for both threads is 5462.

Default is to continue iterating until the command is interrupted.

-D bindDN

Use the specified bind DN to authenticate to the directory.

If the bind DN is not specified, the searchrate command attempts anonymous authentication.

-E

Display the bind DN and filter for searches that failed to retrieve an entry.

-e

Display the number of attempted searches that failed to retrieve an entry.

-f filter

Use the specified RFC 2254 conformant filter for all searches.

Refer to Random Target Syntax and Random Target Substitution for details on number and string substitutions.

-h hostname

Connect to the directory on the specified host.

Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

Default is to connect to the local host on the loopback address, 127.0.0.1.

-i filename

Use the file specified to generate target entry base DNs at random.

Refer to Random Target Syntax and Random Target Substitution for details.

-j seconds

Display results each specified number of seconds.

Default is to display results every 5 seconds.

-K

Keep connections open and only bind once, measuring only the time required to perform the search operation.

Default is to measure the duration the connection is active as the search sequence.

-k

Keep connections open, measuring only the time required to perform the bind and search operations.

Default is to measure the duration the connection is active as the search sequence.

-l seconds

Set the search time-out at the specified number of seconds for synchronous searches.

Default is 10 seconds.

-m maxIter

Perform no more than the specified number of searches per thread.

Default is for each thread to continue iterating until the command is interrupted.

-p port

Connect to the directory on the specified port.

Default is to connect to the default simple authentication port for LDAP, 389.

-q

Run in quiet mode, not displaying results.

Default is to display results every 5 seconds, which you can adjust using the -j option.

-r maxRand

Use the specified maximum to determine the range for random numbers replacing %d formatting specifications when searching random target entries.

When you use this option twice, the first occurrence generates random numbers in the range [0,maxRand1–1] for the first %d, the second [1,maxRand2] for the second %d.

Refer to Random Target Syntax and Random Target Substitution for details.

-S randSeed

Use the specified seed, an unsigned int, for random number generation.

Default seed is 0.

-s scope

Use the specified scope when searching.

The following values are supported for scope:

base: Examine only the entry specified by the argument to the -b option.
one: Examine only to the entry specified by the argument to the -b option and its immediate children.
sub: (Default) Examine the subtree whose root is the entry specified by the argument to the -b option.

-t threads

Use the specified number of the threads to connect to the server.

Default is to use one thread.

-v

Display verbose output.

-W filename

Read the bind password from the specified file.

-w password

Use the specified bind password to authenticate to the directory.

-w –

Prompt for the bind password so it does not appear on the command line or in a file.

Extended Description

The searchrate command repeatedly requests search operations of a directory server. Threads may be configured to keep open connections or perform LDAP binds with each operation. The command-line options let you specify the bind credentials.

The command uses LDAP v3, and cannot be used to authenticate to an LDAP v2 directory not supporting LDAP v3. Furthermore, the searchrate command uses simple authentication, not secure binding.

By default, the searchrate command continues its task indefinitely, displaying results periodically, and displaying any errors encountered as well without interrupting operation.

Random Target Syntax

Include randomly generated numbers by specifying %d and %s placeholders in the base DN and filters. These placeholders are then replaced according to the following rules:

%d

Replace this placeholder with random integer values depending on the maxRand parameter to the -r option.

The -r option may be used at most two times to generate random base DNs or filters. Replacement values for the %d placeholder range over [0,maxRand1–1].

%s

Replace this placeholder with random strings from the file specified using the -i option.

Replacement values for this placeholder are randomly selected lines of the file specified.

Multiple -r and -i options are matched to the %d and %s placeholders, respectively, in the order they are used.

Random Target Substitution

The searchrate command requires that you apply the following rules for substitutions, displaying an error message when the used incorrectly:

Use only one type of placeholder, either %d or %s, per invocation of the searchrate command.
Specify at least as many uses of the -r as %d placeholders used.
Use %%d and %%s to specify literal strings %d and %s, respectively.

In order to use this random mechanism, you must populate your directory accordingly. For example, you can measure the search rate using the following command:

$ searchrate -b "ou=test,dc=example,dc=com" -f "uid=test%d" -r 100

In order for the searchrate command to find entries, your directory must contain entries corresponding to the following LDIF excerpt:

dn: uid=test0,ou=test,dc=example,dc=com
userPassword: auth00

dn: uid=test1,ou=test,dc=example,dc=com
userPassword: auth11

dn: uid=test2,ou=test,dc=example,dc=com
userPassword: auth22
…

dn: uid=test10,ou=test,dc=example,dc=com
userPassword: auth1010
…

dn: uid=test99,ou=test,dc=example,dc=com
userPassword: auth9999

Examples

Examples in this section use the following conventions:

The searchrate command is found in a directory present in the PATH used for the examples.
The directory server is located on a system named host.
The directory has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port 389, the default for non-SSL connections.

Example 1 `searchrate`: Sample Output

The following command performs searches until it has displayed five results messages. Notice that each line concerns only the elapsed interval.

$ searchrate -h host -b dc=example,dc=com -f "(uid=bjensen)" -C 5
Avg r=1349.00/thr (269.80/sec), total=  1349
Avg r=1312.00/thr (262.40/sec), total=  1312
Avg r=1334.00/thr (266.80/sec), total=  1334
Avg r=1346.00/thr (269.20/sec), total=  1346
Avg r=1340.00/thr (268.00/sec), total=  1340
All threads exited

Notice also that a result message provides the following items of information:

The average search rate per thread of execution
The average search rate per second
The total number of search operations performed during the interval the results message concerns

Example 2 `searchrate`: Search Rate Alone

The following command keeping the connection open and binds only once:

$ searchrate -h host -b dc=example,dc=com -f "(uid=bjensen)" -C 5 -K
Avg r=2706.00/thr (541.20/sec), total=  2706
Avg r=2706.00/thr (541.20/sec), total=  2706
Avg r=2739.00/thr (547.80/sec), total=  2739
Avg r=2717.00/thr (543.40/sec), total=  2717
Avg r=2731.00/thr (546.20/sec), total=  2731
All threads exited

Example 3 `searchrate`: Using a Filter File

The following commands substitute filters from a file to perform searches:

$ cat filters
=Jen*
=Jensen
>=Jensen
<=Jensen
~=Jensen
$ searchrate -h host -b dc=example,dc=com -f "(sn%s)" -i filters -C 5 -K
Avg r=  59.00/thr ( 11.80/sec), total=    59
Avg r=  64.00/thr ( 12.80/sec), total=    64
Avg r=  63.00/thr ( 12.60/sec), total=    63
Avg r=  64.00/thr ( 12.80/sec), total=    64
Avg r=  61.00/thr ( 12.20/sec), total=    61
All threads exited

Exit Status

The searchrate command returns the following exit status codes.

0: Successful completion.
non-zero: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving

User Commands

authrate(1)

Name

Synopsis

Description

Options

Extended Description

Random Bind DN Syntax

Random Bind DN Substitution

Examples

Example 1 authrate: Sample Output

Example 2 authrate: Two Threads

Example 3 authrate: Full Authentication Rate

Example 4 authrate: Bind Rate Alone

Exit Status

Attributes

See Also

dsmlmodify(1)

Name

Synopsis

Description

Options

Examples

Example 1 dsmlmodify: Adding an Entry

Example 2 dsmlmodify: Modifying an Entry

Example 3 dsmlmodify: Deleting an Entry

Example 4 dsmlmodify: Renaming an Entry

Exit Status

Attributes

See Also

dsmlsearch(1)

Name

Synopsis

Description

Options

Examples

Example 1 dsmlsearch: Returning All Entries

Example 2 dsmlsearch: Narrowing a Search

Example 3 dsmlsearch: Searching the Root DSE

Example 4 dsmlsearch: Searching the Schema Entry

Example 5 dsmlsearch: Filter Examples

Exit Status

Attributes

See Also

entrycmp(1)

Name

Synopsis

Description

Options

SSL OPTIONS

Examples

Example 1 Specifying an entry DN

Exit Status

Attributes

See Also

Notes

fildif(1)

Name

Synopsis

Description

Options

Examples

Example 1 Using All Options

Exit Status

Attributes

See Also

insync(1)

Name

Synopsis

Description

Options

SSL OPTIONS

Examples

Example 1 Single Server, Repeat Each 30 Seconds

Example 2 Getting Date of Last Change

Exit Status

Attributes

See Also

Notes

ldapcmp(1)

Example 1 `authrate`: Sample Output

Example 2 `authrate`: Two Threads

Example 3 `authrate`: Full Authentication Rate

Example 4 `authrate`: Bind Rate Alone

Example 1 `dsmlmodify`: Adding an Entry

Example 2 `dsmlmodify`: Modifying an Entry

Example 3 `dsmlmodify`: Deleting an Entry

Example 4 `dsmlmodify`: Renaming an Entry

Example 1 `dsmlsearch`: Returning All Entries

Example 2 `dsmlsearch`: Narrowing a Search

Example 3 `dsmlsearch`: Searching the Root DSE

Example 4 `dsmlsearch`: Searching the Schema Entry

Example 5 `dsmlsearch`: Filter Examples