Annotation of src/usr.bin/ldap/ldap.1, Revision 1.10
1.10 ! rob 1: .\" $OpenBSD: ldap.1,v 1.9 2018/07/04 11:47:55 jmc 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.9 jmc 17: .Dd $Mdocdate: July 4 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.10 ! rob 142: The default value is 0
1.1 reyk 143: for no limit.
144: .It Fl s Ar scope
145: Specify the
146: .Ar scope
147: to be either
148: .Ic base ,
149: .Ic one ,
150: or
151: .Ic sub .
152: The default is
153: .Ic sub
154: for subtree searches.
155: .It Fl v
156: Product more verbose output.
157: .It Fl W
158: Prompt for the bind secret with echo turned off.
159: .It Fl w Ar secret
160: Specify the bind secret on the command line.
161: .It Fl x
162: Use simple authentication.
163: This is the default as
164: .Nm
165: does not support SASL authentication.
1.6 reyk 166: .It Fl y Ar secretfile
167: Read the bind secret from the first line of the specified file or from
168: standard input if the
169: .Ar secretfile
170: argument is
171: .Sq - .
172: The file must not be world-readable if it is a regular file.
1.1 reyk 173: .It Fl Z
174: Enable TLS using the StartTLS operation.
175: .It Fl z Ar sizelimit
176: Request the server to limit the search result to a maximum number of
177: .Ar sizelimit
178: entries.
1.3 jmc 179: The default value is 0.
1.1 reyk 180: for no limit.
181: .El
1.3 jmc 182: .Sh FILES
183: .Bl -tag -width "/etc/ssl/cert.pemXXX" -compact
184: .It Pa /etc/ssl/cert.pem
185: Default CA file.
186: .El
1.1 reyk 187: .Sh EXAMPLES
188: The following script can be used with the
189: .Ar AuthorizedKeysCommand
190: option of
191: .Xr sshd 8 :
192: .Bd -literal -offset indent
193: #!/bin/sh
194: ldap search -D cn=Reader,dc=example,dc=com -w mypass123 \e
195: -b ou=People,dc=example,dc=com \e
196: -H ldapserver -c /etc/ssl/ldapserver.crt -Z \e
197: "(&(objectClass=bsdAccount)(uid=$1))" sshPublicKey | \e
1.2 reyk 198: sed 's/^sshPublicKey: //p;d;'
1.1 reyk 199: exit 0
200: .Ed
201: .Pp
202: And the related configuration in
203: .Xr sshd_config 5 :
204: .Bd -literal -offset indent
205: Match Group ldapusers
206: AuthorizedKeysCommand /etc/ssh/ldap-authorized_keys.sh
207: AuthorizedKeysCommandUser _ldap
208: .Ed
209: .Sh SEE ALSO
210: .Xr sshd_config 5 ,
211: .Xr ldapd 8 ,
212: .Xr sshd 8
213: .Sh STANDARDS
214: .Rs
215: .%A G. Good
216: .%D June 2000
217: .%R RFC 2849
218: .%T The LDAP Data Interchange Format (LDIF) - Technical Specification
219: .Re
220: .Pp
221: .Rs
222: .%A M. Smith, Ed.
223: .%A T. Howes
224: .%D June 2006
225: .%R RFC 4515
226: .%T Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters
227: .Re
228: .Pp
229: .Rs
230: .%A M. Smith, Ed.
231: .%A T. Howes
232: .%D June 2006
233: .%R RFC 4516
234: .%T Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
1.3 jmc 235: .Re
1.8 rob 236: .Sh HISTORY
237: The
238: .Nm
1.9 jmc 239: utility first appeared in
1.8 rob 240: .Ox 6.4 .
1.1 reyk 241: .Sh AUTHORS
242: .An -nosplit
243: The
244: .Nm
1.9 jmc 245: utility was written by
1.1 reyk 246: .An Reyk Floeter Aq Mt reyk@openbsd.org .
247: .Sh CAVEATS
1.9 jmc 248: SASL authentication is not supported.
1.3 jmc 249: Authentication should be performed using simple authentication over a
1.1 reyk 250: TLS connection.