<?xml version="1.0" encoding="UTF-8"?>

<refentry xml:id="ldapsearch-1" xmlns="http://docbook.org/ns/docbook"

version="5.0" xml:lang="en"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"

xmlns:xlink="http://www.w3.org/1999/xlink"

xmlns:xi="http://www.w3.org/2001/XInclude">

<xi:include href="common.xml" xpointer='xpointer(//info[@name="info"])'/>

<refmeta>

<refentrytitle><application>ldapsearch</application></refentrytitle>

<xi:include href="common.xml" xpointer='xpointer(//manvolnum[@name="v1m"])'/>

</refmeta>

<refnamediv>

<refname><application>ldapsearch</application></refname>

<refpurpose>perform LDAP search operations</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>ldapsearch</command>

<arg>-b <replaceable class="parameter">baseDN</replaceable></arg>

<arg>-a <replaceable class="parameter">derefPolicy</replaceable></arg>

<arg>-t</arg>

<arg>-A</arg>

<arg>-C</arg>

<arg>-e <replaceable class="parameter">effRightsAttr</replaceable></arg>

<arg>-g <replaceable class="parameter">effRightsAuthzId</replaceable></arg>

<arg>-G <group choice="req"><replaceable

>before:after:index:count</replaceable> | <replaceable

>before:after:value</replaceable>

</group></arg>

<arg>-L <replaceable class="parameter">seconds</replaceable></arg>

<arg>--subEntries</arg>

<arg>-s <replaceable class="parameter">searchScope</replaceable></arg>

<arg>-S <replaceable class="parameter">order</replaceable></arg>

<arg>-z <replaceable>maxEntries</replaceable></arg>

<arg>--simplePageSize <replaceable class="parameter">entries</replaceable></arg>

<arg>--matchedValuesFilter <replaceable class="parameter">filter</replaceable></arg>

<arg>--countEntries</arg>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-ops"]/*)'/>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-proto"]/*)'/>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-remote"]/*)'/>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-auth"]/*)'/>

<arg>-r</arg>

<sbr/><sbr/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-props"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-misc"]/*[@name="sc-verbose"

or @name="sc-enc"])'/>

<arg>--version</arg>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="s-general"]/*[@name="sc-help"])'/>

<sbr/><sbr/>

<arg choice="opt">filter</arg>

<arg choice="opt" rep="repeat">attributes</arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsection>

<title>Description</title>

<para>

This utility can be used to perform LDAP search operations in the directory.

</para>

<variablelist>

<varlistentry>

<term>filter</term>

<listitem>

<para>

The filter argument is a string representation of an LDAP search filter as in

(cn=Babs Jensen), (&amp;(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))), or

(cn:caseExactMatch:=Fred Flintstone).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>attribute</term>

<listitem>

<para>

The optional attribute list specifies the attributes to return in the entries

found by the search. In addition to identifying attributes by name such as cn

sn mail and so forth, you can use the following notations, too.

</para>

<variablelist>

<varlistentry>

<term>*</term>

<listitem>

<para>

Return all user attributes such as cn, sn, and mail.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>+</term>

<listitem>

<para>

Return all operational attributes such as etag and pwdPolicySubentry.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>@<replaceable class="parameter">objectclass</replaceable></term>

<listitem>

<para>

Return all attributes of the specified object class, where <replaceable

>objectclass</replaceable> is one of the object classes on the entries returned

by the search.

</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

</varlistentry>

</variablelist>

</refsection>

<refsection>

<title>Options</title>

<para>The following options are supported.</para>

<variablelist>

<varlistentry>

<term><option>-b, --baseDN</option> <replaceable

class="parameter">baseDN</replaceable></term>

<listitem>

<para>

Base DN format string.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-a, --dereferencePolicy</option> <replaceable

class="parameter">policy</replaceable></term>

<listitem>

<para>

Alias dereference policy: 'never', 'always', 'search', or 'find' (Default: never)

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-A, --typesOnly</option></term>

<listitem>

<para>

Only retrieve attribute names but not their values.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-C, --persistentSearch</option> <replaceable

class="parameter">ps[:changetype[:changesonly[:entrychgcontrols]]]</replaceable></term>

<listitem>

<para>

Use the persistent search control.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--countEntries</option></term>

<listitem>

<para>

Count the number of entries returned by the server.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-e, --getEffectiveRightsAttribute</option> <replaceable

class="parameter">attribute</replaceable></term>

<listitem>

<para>

Specifies geteffectiverights control specific attribute list.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-g, --getEffectiveRightsAuthzid</option> <replaceable

class="parameter">authzID</replaceable></term>

<listitem>

<para>

Use geteffectiverights control with the provided authzid.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-G, --virtualListView</option> <replaceable

class="parameter">before:after:index:count</replaceable> | <replaceable

class="parameter">before:after:value</replaceable></term>

<listitem>

<para>

Use the virtual list view control to retrieve the specified results page.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--matchedValuesFilter</option> <replaceable

class="parameter">filter</replaceable></term>

<listitem>

<para>

Use the LDAP matched values control with the provided filter.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--subEntries</option></term>

<listitem>

<para>

Use subentries control to specify that subentries are visible and normal entries

are not.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-s, --searchScope</option> <replaceable

class="parameter">scope</replaceable></term>

<listitem>

<para>

Search scope: 'base', 'one', 'sub', or 'subordinate' (Default: sub).

<literal>subordinate</literal> is an LDAP extension that might not work with all

LDAP servers.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-S, --sortOrder</option> <replaceable

class="parameter">order</replaceable></term>

<listitem>

<para>

Sort the results using the provided sort order.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--simplePageSize</option> <replaceable

class="parameter">entries</replaceable></term>

<listitem>

<para>

Use the simple paged results control with the given page size (Default: 1000).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-L, --timeLimit</option> <replaceable

class="parameter">seconds</replaceable></term>

<listitem>

<para>

Maximum length of time in seconds to allow for the search (Default: 0).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-z, --sizeLimit</option> <replaceable

class="parameter">entries</replaceable></term>

<listitem>

<para>

Maximum number of entries to return from the search (Default: 0).

</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-ops"]/*)'/>

</variablelist>

<refsection>

<title>LDAP Connection Options</title>

<variablelist>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-proto"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-remote"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-auth"]/*)'/>

<varlistentry>

<term><option>-r, --useSASLExternal</option></term>

<listitem>

<para>

Use the SASL EXTERNAL authentication mechanism.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsection>

<refsection>

<title>Utility Input/Output Options</title>

<variablelist>

<varlistentry>

<term><option>-t, --dontWrap</option></term>

<listitem>

<para>

Do not wrap long lines.

</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-props"]/*)'/>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-misc"]/*[@name="lc-verbose"

or @name="lc-enc"])'/>

</variablelist>

</refsection>

<refsection>

<title>General Options</title>

<variablelist>

<varlistentry>

<term><option>--version</option></term>

<listitem>

<para>Display version information</para>

</listitem>

</varlistentry>

<xi:include href="common.xml"

xpointer='xpointer(//para[@name="l-general"]/*[@name="lc-help"])'/>

</variablelist>

</refsection>

</refsection>

<refsection>

<title>Examples</title>

<informalexample>

<para>

The following example searches for entries with UID containing

<literal>jensen</literal>, returning only DNs and uid values.

</para>

<literallayout><prompt

>$ </prompt><command>ldapsearch -p 1389 -b dc=example,dc=com "(uid=*jensen*)" uid</command></literallayout>

<screen>

dn: uid=ajensen,ou=People,dc=example,dc=com

uid: ajensen

dn: uid=bjensen,ou=People,dc=example,dc=com

uid: bjensen

dn: uid=gjensen,ou=People,dc=example,dc=com

uid: gjensen

dn: uid=jjensen,ou=People,dc=example,dc=com

uid: jjensen

dn: uid=kjensen,ou=People,dc=example,dc=com

uid: kjensen

dn: uid=rjensen,ou=People,dc=example,dc=com

uid: rjensen

dn: uid=tjensen,ou=People,dc=example,dc=com

uid: tjensen

Result Code: 0 (Success)

</screen>

</informalexample>

<informalexample>

<para>

You can also use @<replaceable>objectclass</replaceable> notation in the

attribute list to return the attributes of a particular object class. The

following example shows how to return attributes of the

<code>inetOrgPerson</code> object class.

</para>

<literallayout><prompt

>$ </prompt><command>ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" \

@inetorgperson</command></literallayout>

<screen>

dn: uid=bjensen,ou=People,dc=example,dc=com

givenName: Barbara

objectClass: person

objectClass: organizationalPerson

objectClass: inetOrgPerson

objectClass: posixAccount

objectClass: top

uid: bjensen

cn: Barbara Jensen

cn: Babs Jensen

telephoneNumber: +1 408 555 1862

sn: Jensen

roomNumber: 0209

mail: bjensen@example.com

l: Cupertino

ou: Product Development

ou: People

facsimileTelephoneNumber: +1 408 555 1992

</screen>

</informalexample>

<informalexample>

<para>

You can use <code>+</code> in the attribute list to return all operational

attributes, as in the following example.

</para>

<literallayout><prompt

>$ </prompt><command>ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" +</command></literallayout>

<screen>

dn: uid=bjensen,ou=People,dc=example,dc=com

numSubordinates: 0

structuralObjectClass: inetOrgPerson

etag: 0000000073c29972

pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config

subschemaSubentry: cn=schema

hasSubordinates: false

entryDN: uid=bjensen,ou=people,dc=example,dc=com

entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c

</screen>

</informalexample>

</refsection>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="env"])'/>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="exit-ops"])'/>

<xi:include href="common.xml" xpointer='xpointer(//refsection[@name="seeAlso"])'/>

</refentry>