Annotation of src/usr.bin/ldap/ldap.1, Revision 1.11
1.11 ! jmc 1: .\" $OpenBSD: ldap.1,v 1.10 2018/08/01 10:42:55 rob Exp $
1.1 reyk 2: .\"
3: .\" Copyright (c) 2018 Reyk Floeter <reyk@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.11 ! jmc 17: .Dd $Mdocdate: August 1 2018 $
1.3 jmc 18: .Dt LDAP 1
1.1 reyk 19: .Os
20: .Sh NAME
21: .Nm ldap
1.3 jmc 22: .Nd simple LDAP client
1.1 reyk 23: .Sh SYNOPSIS
24: .Nm ldap
1.7 jmc 25: .Cm search
1.1 reyk 26: .Op Fl LvWxZ
27: .Op Fl b Ar basedn
28: .Op Fl c Ar CAfile
29: .Op Fl D Ar binddn
30: .Op Fl H Ar host
31: .Op Fl l Ar timelimit
32: .Op Fl s Ar scope
33: .Op Fl w Ar secret
1.6 reyk 34: .Op Fl y Ar secretfile
1.1 reyk 35: .Op Fl z Ar sizelimit
1.7 jmc 36: .Op Ar filter
37: .Op Ar attributes ...
1.1 reyk 38: .Sh DESCRIPTION
39: The
40: .Nm
1.9 jmc 41: utility is a simple LDAP client.
1.1 reyk 42: It queries an LDAP server to perform a command and outputs the results
43: in the LDAP Data Interchange Format (LDIF).
44: .Bl -tag -width Ds
1.7 jmc 45: .It Cm search Ar options Oo Ar filter Oc Op Ar attributes ...
1.1 reyk 46: Perform a directory search request.
47: The optional
48: .Ar filter
49: argument specifies the LDAP filter for the directory search.
50: The default is
51: .Ar (objectClass=*)
52: and the format must comply to the
53: .Dq String Representation of Search Filters
54: as described in RFC 4515.
55: If one or more
56: .Ar attribute
57: options are specified,
58: .Nm
59: restricts the output to the specified attributes.
60: .El
61: .Pp
62: The options are as follows:
63: .Bl -tag -width Ds
64: .It Fl b Ar basedn
65: Use the specified distinguished name (dn) as the starting point for
66: directory search requests.
67: .It Fl c Ar CAfile
68: When TLS is enabled, load the CA bundle for certificate verification
69: from the specified file.
70: The default is
71: .Pa /etc/ssl/cert.pem .
72: If the LDAP server uses a self-signed certificate,
73: use a file that contains the server certificate in PEM format, e.g.
74: .Pa /etc/ssl/ldapserver.example.com.crt .
75: .It Fl D Ar binddn
76: Use the specified distinguished name to bind to the directory.
77: .It Fl H Ar host
78: The hostname of the LDAP server or an LDAP URL.
79: The LDAP URL is described in RFC 4516 with the following format:
80: .Pp
81: .Sm off
82: .Op Ar protocol No ://
83: .Ar host Op : Ar port
1.7 jmc 84: .Oo
85: .Li / Ar basedn
86: .Li ?\& Ar attribute , ...
87: .Li ?\& Ar scope
88: .Li ?\& Ar filter
1.1 reyk 89: .Oc
90: .Sm on
91: .Pp
1.7 jmc 92: The default is
93: .Ar ldap://localhost:389/ .
94: Each of
95: .Ar basedn , attribute , scope
96: and
97: .Ar filter
98: may be omitted,
99: but the preceding
100: .Sq /
101: or
102: .Sq ?\&
103: is required if a subsequent field is non-empty.
104: .Pp
1.1 reyk 105: The following protocols are supported:
106: .Pp
107: .Bl -tag -width "ldap+tls" -compact
108: .It ldap
109: Connect with TCP in plain text.
110: This is the default.
111: .It ldaps
112: Connect with TLS.
113: The default port is 636.
114: .It ldap+tls
115: Connect with TCP and enable TLS using the StartTLS operation.
116: This is the same as the
117: .Fl Z
118: option.
119: .It ldapi
120: Connect to a UNIX-domain socket.
1.3 jmc 121: The host argument is required to be a URL-encoded path, for example
1.1 reyk 122: .Ar ldapi://%2fvar%2frun%2fldapi
123: for
124: .Pa /var/run/ldapi .
125: .El
126: .It Fl L
127: Output the directory search result in a standards-compliant version of
128: the LDAP Data Interchange Format (LDIF).
129: This encodes attribute values that include non-printable or UTF-8
130: characters in the Base64 format and wraps lines at a 79-character limit.
131: If this option is not specified,
132: .Nm
133: encodes
134: .Dq unsafe
135: characters and newlines in a visual format using
136: .Xr vis 3
137: instead.
138: .It Fl l Ar timelimit
139: Request the server to abort the search request after
140: .Ar timelimit
141: seconds.
1.11 ! jmc 142: The default value is 0 for no limit.
1.1 reyk 143: .It Fl s Ar scope
144: Specify the
145: .Ar scope
146: to be either
147: .Ic base ,
148: .Ic one ,
149: or
150: .Ic sub .
151: The default is
152: .Ic sub
153: for subtree searches.
154: .It Fl v
1.11 ! jmc 155: Produce more verbose output.
1.1 reyk 156: .It Fl W
157: Prompt for the bind secret with echo turned off.
158: .It Fl w Ar secret
159: Specify the bind secret on the command line.
160: .It Fl x
161: Use simple authentication.
162: This is the default as
163: .Nm
164: does not support SASL authentication.
1.6 reyk 165: .It Fl y Ar secretfile
166: Read the bind secret from the first line of the specified file or from
167: standard input if the
168: .Ar secretfile
169: argument is
170: .Sq - .
171: The file must not be world-readable if it is a regular file.
1.1 reyk 172: .It Fl Z
173: Enable TLS using the StartTLS operation.
174: .It Fl z Ar sizelimit
175: Request the server to limit the search result to a maximum number of
176: .Ar sizelimit
177: entries.
1.11 ! jmc 178: The default value is 0 for no limit.
1.1 reyk 179: .El
1.3 jmc 180: .Sh FILES
181: .Bl -tag -width "/etc/ssl/cert.pemXXX" -compact
182: .It Pa /etc/ssl/cert.pem
183: Default CA file.
184: .El
1.1 reyk 185: .Sh EXAMPLES
186: The following script can be used with the
187: .Ar AuthorizedKeysCommand
188: option of
189: .Xr sshd 8 :
190: .Bd -literal -offset indent
191: #!/bin/sh
192: ldap search -D cn=Reader,dc=example,dc=com -w mypass123 \e
193: -b ou=People,dc=example,dc=com \e
194: -H ldapserver -c /etc/ssl/ldapserver.crt -Z \e
195: "(&(objectClass=bsdAccount)(uid=$1))" sshPublicKey | \e
1.2 reyk 196: sed 's/^sshPublicKey: //p;d;'
1.1 reyk 197: exit 0
198: .Ed
199: .Pp
200: And the related configuration in
201: .Xr sshd_config 5 :
202: .Bd -literal -offset indent
203: Match Group ldapusers
204: AuthorizedKeysCommand /etc/ssh/ldap-authorized_keys.sh
205: AuthorizedKeysCommandUser _ldap
206: .Ed
207: .Sh SEE ALSO
208: .Xr sshd_config 5 ,
209: .Xr ldapd 8 ,
210: .Xr sshd 8
211: .Sh STANDARDS
212: .Rs
213: .%A G. Good
214: .%D June 2000
215: .%R RFC 2849
216: .%T The LDAP Data Interchange Format (LDIF) - Technical Specification
217: .Re
218: .Pp
219: .Rs
220: .%A M. Smith, Ed.
221: .%A T. Howes
222: .%D June 2006
223: .%R RFC 4515
224: .%T Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters
225: .Re
226: .Pp
227: .Rs
228: .%A M. Smith, Ed.
229: .%A T. Howes
230: .%D June 2006
231: .%R RFC 4516
232: .%T Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
1.3 jmc 233: .Re
1.8 rob 234: .Sh HISTORY
235: The
236: .Nm
1.9 jmc 237: utility first appeared in
1.8 rob 238: .Ox 6.4 .
1.1 reyk 239: .Sh AUTHORS
240: .An -nosplit
241: The
242: .Nm
1.9 jmc 243: utility was written by
1.1 reyk 244: .An Reyk Floeter Aq Mt reyk@openbsd.org .
245: .Sh CAVEATS
1.9 jmc 246: SASL authentication is not supported.
1.3 jmc 247: Authentication should be performed using simple authentication over a
1.1 reyk 248: TLS connection.