summaryrefslogtreecommitdiffstats
path: root/doc/man/man1/ldapsearch.1
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:32 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:32 +0000
commit5ea77a75dd2d2158401331879f3c8f47940a732c (patch)
treed89dc06e9f4850a900f161e25f84e922c4f86cc8 /doc/man/man1/ldapsearch.1
parentInitial commit. (diff)
downloadopenldap-5ea77a75dd2d2158401331879f3c8f47940a732c.tar.xz
openldap-5ea77a75dd2d2158401331879f3c8f47940a732c.zip
Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--doc/man/man1/ldapsearch.1495
1 files changed, 495 insertions, 0 deletions
diff --git a/doc/man/man1/ldapsearch.1 b/doc/man/man1/ldapsearch.1
new file mode 100644
index 0000000..2aec7c5
--- /dev/null
+++ b/doc/man/man1/ldapsearch.1
@@ -0,0 +1,495 @@
+.TH LDAPSEARCH 1 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.SH NAME
+ldapsearch \- LDAP search tool
+.SH SYNOPSIS
+.B ldapsearch
+[\c
+.BR \-V [ V ]]
+[\c
+.BI \-d \ debuglevel\fR]
+[\c
+.BR \-n ]
+[\c
+.BR \-v ]
+[\c
+.BR \-c ]
+[\c
+.BR \-u ]
+[\c
+.BR \-t [ t ]]
+[\c
+.BI \-T \ path\fR]
+[\c
+.BI \-F \ prefix\fR]
+[\c
+.BR \-A ]
+[\c
+.BR \-L [ L [ L ]]]
+[\c
+.BI \-S \ attribute\fR]
+[\c
+.BI \-b \ searchbase\fR]
+[\c
+.BR \-s \ { base \||\| one \||\| sub \||\| children }]
+[\c
+.BR \-a \ { never \||\| always \||\| search \||\| find }]
+[\c
+.BI \-l \ timelimit\fR]
+[\c
+.BI \-z \ sizelimit\fR]
+[\c
+.BI \-f \ file\fR]
+[\c
+.BR \-M [ M ]]
+[\c
+.BR \-x ]
+[\c
+.BI \-D \ binddn\fR]
+[\c
+.BR \-W ]
+[\c
+.BI \-w \ passwd\fR]
+[\c
+.BI \-y \ passwdfile\fR]
+[\c
+.BI \-H \ ldapuri\fR]
+[\c
+.BR \-P \ { 2 \||\| 3 }]
+[\c
+.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]]
+[\c
+.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]]
+[\c
+.BI \-o \ opt \fR[= optparam \fR]]
+[\c
+.BI \-O \ security-properties\fR]
+[\c
+.BR \-I ]
+[\c
+.BR \-Q ]
+[\c
+.BR \-N ]
+[\c
+.BI \-U \ authcid\fR]
+[\c
+.BI \-R \ realm\fR]
+[\c
+.BI \-X \ authzid\fR]
+[\c
+.BI \-Y \ mech\fR]
+[\c
+.BR \-Z [ Z ]]
+.I filter
+[\c
+.IR attrs... ]
+.SH DESCRIPTION
+.I ldapsearch
+is a shell-accessible interface to the
+.BR ldap_search_ext (3)
+library call.
+.LP
+.B ldapsearch
+opens a connection to an LDAP server, binds, and performs a search
+using specified parameters. The \fIfilter\fP should conform to
+the string representation for search filters as defined in RFC 4515.
+If not provided, the default filter, \fB(objectClass=*)\fP, is used.
+.LP
+If
+.B ldapsearch
+finds one or more entries, the attributes specified by
+\fIattrs\fP are returned. If \fB*\fP is listed, all user attributes are
+returned. If \fB+\fP is listed, all operational attributes are returned.
+If no \fIattrs\fP are listed, all user attributes are returned. If only
+1.1 is listed, no attributes will be returned.
+.LP
+The search results are displayed using an extended version of LDIF.
+Option \fI\-L\fP controls the format of the output.
+.SH OPTIONS
+.TP
+.BR \-V [ V ]
+Print version info.
+If \fB\-VV\fP is given, exit after providing version info. Otherwise proceed
+with the specified search
+.TP
+.BI \-d \ debuglevel
+Set the LDAP debugging level to \fIdebuglevel\fP.
+.B ldapsearch
+must be compiled with LDAP_DEBUG defined for this option to have any effect.
+.TP
+.B \-n
+Show what would be done, but don't actually perform the search. Useful for
+debugging in conjunction with \fB\-v\fP.
+.TP
+.B \-v
+Run in verbose mode, with many diagnostics written to standard output.
+.TP
+.B \-c
+Continuous operation mode. Errors are reported, but ldapsearch will continue
+with searches. The default is to exit after reporting an error. Only useful
+in conjunction with \fB\-f\fP.
+.TP
+.B \-u
+Include the User Friendly Name form of the Distinguished Name (DN)
+in the output.
+.TP
+.BR \-t [ t ]
+A single \fB\-t\fP writes retrieved non-printable values to a set of temporary
+files. This is useful for dealing with values containing non-character
+data such as jpegPhoto or audio. A second \fB\-t\fP writes all retrieved values to
+files.
+.TP
+.BI \-T \ path
+Write temporary files to directory specified by \fIpath\fP (default:
+\fB/var/tmp/\fP)
+.TP
+.BI \-F \ prefix
+URL prefix for temporary files. Default is \fBfile://\fIpath\fP where
+\fIpath\fP is \fB/var/tmp/\fP or specified with \fB\-T\fP.
+.TP
+.B \-A
+Retrieve attributes only (no values). This is useful when you just want to
+see if an attribute is present in an entry and are not interested in the
+specific values.
+.TP
+.B \-L
+Search results are display in LDAP Data Interchange Format detailed in
+.BR ldif (5).
+A single \fB\-L\fP restricts the output to LDIFv1.
+ A second \fB\-L\fP disables comments.
+A third \fB\-L\fP disables printing of the LDIF version.
+The default is to use an extended version of LDIF.
+.TP
+.BI \-S \ attribute
+Sort the entries returned based on \fIattribute\fP. The default is not
+to sort entries returned. If \fIattribute\fP is a zero-length string (""),
+the entries are sorted by the components of their Distinguished Name. See
+.BR ldap_sort (3)
+for more details. Note that
+.B ldapsearch
+normally prints out entries as it receives them. The use of the \fB\-S\fP
+option defeats this behavior, causing all entries to be retrieved,
+then sorted, then printed.
+.TP
+.BI \-b \ searchbase
+Use \fIsearchbase\fP as the starting point for the search instead of
+the default.
+.TP
+.BR \-s \ { base \||\| one \||\| sub \||\| children }
+Specify the scope of the search to be one of
+.BR base ,
+.BR one ,
+.BR sub ,
+or
+.B children
+to specify a base object, one-level, subtree, or children search.
+The default is
+.BR sub .
+Note:
+.I children
+scope requires LDAPv3 subordinate feature extension.
+.TP
+.BR \-a \ { never \||\| always \||\| search \||\| find }
+Specify how aliases dereferencing is done. Should be one of
+.BR never ,
+.BR always ,
+.BR search ,
+or
+.B find
+to specify that aliases are never dereferenced, always dereferenced,
+dereferenced when searching, or dereferenced only when locating the
+base object for the search. The default is to never dereference aliases.
+.TP
+.BI \-l \ timelimit
+wait at most \fItimelimit\fP seconds for a search to complete.
+A timelimit of
+.I 0
+(zero) or
+.I none
+means no limit.
+A timelimit of
+.I max
+means the maximum integer allowable by the protocol.
+A server may impose a maximal timelimit which only
+the root user may override.
+.TP
+.BI \-z \ sizelimit
+retrieve at most \fIsizelimit\fP entries for a search.
+A sizelimit of
+.I 0
+(zero) or
+.I none
+means no limit.
+A sizelimit of
+.I max
+means the maximum integer allowable by the protocol.
+A server may impose a maximal sizelimit which only
+the root user may override.
+.TP
+.BI \-f \ file
+Read a series of lines from \fIfile\fP, performing one LDAP search for
+each line. In this case, the \fIfilter\fP given on the command line
+is treated as a pattern where the first and only occurrence of \fB%s\fP
+is replaced with a line from \fIfile\fP. Any other occurrence of the
+the \fB%\fP character in the pattern will be regarded as an error.
+Where it is desired that the search filter include a \fB%\fP character,
+the character should be encoded as \fB\\25\fP (see RFC 4515).
+If \fIfile\fP is a single
+\fB\-\fP character, then the lines are read from standard input.
+.B ldapsearch
+will exit when the first non-successful search result is returned,
+unless \fB\-c\fP is used.
+.TP
+.BR \-M [ M ]
+Enable manage DSA IT control.
+.B \-MM
+makes control critical.
+.TP
+.B \-x
+Use simple authentication instead of SASL.
+.TP
+.BI \-D \ binddn
+Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory.
+For SASL binds, the server is expected to ignore this value.
+.TP
+.B \-W
+Prompt for simple authentication.
+This is used instead of specifying the password on the command line.
+.TP
+.BI \-w \ passwd
+Use \fIpasswd\fP as the password for simple authentication.
+.TP
+.BI \-y \ passwdfile
+Use complete contents of \fIpasswdfile\fP as the password for
+simple authentication.
+.TP
+.BI \-H \ ldapuri
+Specify URI(s) referring to the ldap server(s);
+a list of URI, separated by whitespace or commas is expected;
+only the protocol/host/port fields are allowed.
+As an exception, if no host/port is specified, but a DN is,
+the DN is used to look up the corresponding host(s) using the
+DNS SRV records, according to RFC 2782. The DN must be a non-empty
+sequence of AVAs whose attribute type is "dc" (domain component),
+and must be escaped according to RFC 2396.
+.TP
+.BR \-P \ { 2 \||\| 3 }
+Specify the LDAP protocol version to use.
+.TP
+.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]
+.TP
+.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]
+
+Specify general extensions with \fB\-e\fP and search extensions with \fB\-E\fP.
+\'\fB!\fP\' indicates criticality.
+
+General extensions:
+.nf
+ [!]assert=<filter> (an RFC 4515 Filter)
+ !authzid=<authzid> ("dn:<dn>" or "u:<user>")
+ [!]bauthzid (RFC 3829 authzid control)
+ [!]chaining[=<resolve>[/<cont>]]
+ [!]manageDSAit
+ [!]noop
+ ppolicy
+ [!]postread[=<attrs>] (a comma-separated attribute list)
+ [!]preread[=<attrs>] (a comma-separated attribute list)
+ [!]relax
+ sessiontracking[=<username>]
+ abandon,cancel,ignore (SIGINT sends abandon/cancel,
+ or ignores response; if critical, doesn't wait for SIGINT.
+ not really controls)
+.fi
+
+Search extensions:
+.nf
+ !dontUseCopy
+ [!]domainScope (domain scope)
+ [!]mv=<filter> (matched values filter)
+ [!]pr=<size>[/prompt|noprompt] (paged results/prompt)
+ [!]sss=[\-]<attr[:OID]>[/[\-]<attr[:OID]>...] (server side sorting)
+ [!]subentries[=true|false] (subentries)
+ [!]sync=ro[/<cookie>] (LDAP Sync refreshOnly)
+ rp[/<cookie>][/<slimit>] (LDAP Sync refreshAndPersist)
+ [!]vlv=<before>/<after>(/<offset>/<count>|:<value>) (virtual list view)
+ [!]deref=derefAttr:attr[,attr[...]][;derefAttr:attr[,attr[...]]]
+ [!]<oid>[=:<value>|::<b64value>]
+.fi
+.TP
+.BI \-o \ opt \fR[= optparam \fR]
+
+Specify any
+.BR ldap.conf (5)
+option or one of the following:
+.nf
+ nettimeout=<timeout> (in seconds, or "none" or "max")
+ ldif_wrap=<width> (in columns, or "no" for no wrapping)
+.fi
+
+.TP
+.BI \-O \ security-properties
+Specify SASL security properties.
+.TP
+.B \-I
+Enable SASL Interactive mode. Always prompt. Default is to prompt
+only as needed.
+.TP
+.B \-Q
+Enable SASL Quiet mode. Never prompt.
+.TP
+.B \-N
+Do not use reverse DNS to canonicalize SASL host name.
+.TP
+.BI \-U \ authcid
+Specify the authentication ID for SASL bind. The form of the ID
+depends on the actual SASL mechanism used.
+.TP
+.BI \-R \ realm
+Specify the realm of authentication ID for SASL bind. The form of the realm
+depends on the actual SASL mechanism used.
+.TP
+.BI \-X \ authzid
+Specify the requested authorization ID for SASL bind.
+.I authzid
+must be one of the following formats:
+.BI dn: "<distinguished name>"
+or
+.BI u: <username>
+.TP
+.BI \-Y \ mech
+Specify the SASL mechanism to be used for authentication. If it's not
+specified, the program will choose the best mechanism the server knows.
+.TP
+.BR \-Z [ Z ]
+Issue StartTLS (Transport Layer Security) extended operation. If you use
+\fB\-ZZ\fP, the command will require the operation to be successful.
+.SH OUTPUT FORMAT
+If one or more entries are found, each entry is written to standard
+output in LDAP Data Interchange Format or
+.BR ldif (5):
+.LP
+.nf
+ version: 1
+
+ # bjensen, example, net
+ dn: uid=bjensen,dc=example,dc=net
+ objectClass: person
+ objectClass: dcObject
+ uid: bjensen
+ cn: Barbara Jensen
+ sn: Jensen
+ ...
+.fi
+.LP
+If the \fB\-t\fP option is used, the URI of a temporary file
+is used in place of the actual value. If the \fB\-A\fP option
+is given, only the "attributename" part is written.
+.SH EXAMPLE
+The following command:
+.LP
+.nf
+ ldapsearch \-LLL "(sn=smith)" cn sn telephoneNumber
+.fi
+.LP
+will perform a subtree search (using the default search base and
+other parameters defined in
+.BR ldap.conf (5))
+for entries with a surname (sn) of smith. The common name (cn), surname
+(sn) and telephoneNumber values will be retrieved and printed to
+standard output.
+The output might look something like this if two entries are found:
+.LP
+.nf
+ dn: uid=jts,dc=example,dc=com
+ cn: John Smith
+ cn: John T. Smith
+ sn: Smith
+ sn;lang\-en: Smith
+ sn;lang\-de: Schmidt
+ telephoneNumber: 1 555 123\-4567
+
+ dn: uid=sss,dc=example,dc=com
+ cn: Steve Smith
+ cn: Steve S. Smith
+ sn: Smith
+ sn;lang\-en: Smith
+ sn;lang\-de: Schmidt
+ telephoneNumber: 1 555 765\-4321
+.fi
+.LP
+The command:
+.LP
+.nf
+ ldapsearch \-LLL \-u \-t "(uid=xyz)" jpegPhoto audio
+.fi
+.LP
+will perform a subtree search using the default search base for entries
+with user id of "xyz". The user friendly form of the entry's DN will be
+output after the line that contains the DN itself, and the jpegPhoto
+and audio values will be retrieved and written to temporary files. The
+output might look like this if one entry with one value for each of the
+requested attributes is found:
+.LP
+.nf
+ dn: uid=xyz,dc=example,dc=com
+ ufn: xyz, example, com
+ audio:< file:///tmp/ldapsearch\-audio\-a19924
+ jpegPhoto:< file:///tmp/ldapsearch\-jpegPhoto\-a19924
+.fi
+.LP
+This command:
+.LP
+.nf
+ ldapsearch \-LLL \-s one \-b "c=US" "(o=University*)" o description
+.fi
+.LP
+will perform a one-level search at the c=US level for all entries
+whose organization name (o) begins with \fBUniversity\fP.
+The organization name and description attribute values will be retrieved
+and printed to standard output, resulting in output similar to this:
+.LP
+.nf
+ dn: o=University of Alaska Fairbanks,c=US
+ o: University of Alaska Fairbanks
+ description: Naturally Inspiring
+ description: leaf node only
+
+ dn: o=University of Colorado at Boulder,c=US
+ o: University of Colorado at Boulder
+ description: No personnel information
+ description: Institution of education and research
+
+ dn: o=University of Colorado at Denver,c=US
+ o: University of Colorado at Denver
+ o: UCD
+ o: CU/Denver
+ o: CU\-Denver
+ description: Institute for Higher Learning and Research
+
+ dn: o=University of Florida,c=US
+ o: University of Florida
+ o: UFl
+ description: Warper of young minds
+
+ ...
+.fi
+.SH DIAGNOSTICS
+Exit status is zero if no errors occur.
+Errors result in a non-zero exit status and
+a diagnostic message being written to standard error.
+.SH "SEE ALSO"
+.BR ldapadd (1),
+.BR ldapdelete (1),
+.BR ldapmodify (1),
+.BR ldapmodrdn (1),
+.BR ldap.conf (5),
+.BR ldif (5),
+.BR ldap (3),
+.BR ldap_search_ext (3),
+.BR ldap_sort (3)
+.SH AUTHOR
+The OpenLDAP Project <http://www.openldap.org/>
+.SH ACKNOWLEDGEMENTS
+.so ../Project