Annotation of src/usr.bin/ldap/ldap.1, Revision 1.7
1.7 ! jmc 1: .\" $OpenBSD: ldap.1,v 1.6 2018/06/26 09:47:20 reyk 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.7 ! jmc 17: .Dd $Mdocdate: June 26 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
41: program is a simple LDAP client program.
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.3 jmc 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.1 reyk 236: .Sh AUTHORS
237: .An -nosplit
238: The
239: .Nm
240: program was written by
241: .An Reyk Floeter Aq Mt reyk@openbsd.org .
242: .Sh CAVEATS
243: The
244: .Nm
1.3 jmc 245: tool does not support SASL authentication.
246: Authentication should be performed using simple authentication over a
1.1 reyk 247: TLS connection.