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