Annotation of src/usr.bin/ldap/ldap.1, Revision 1.6
1.6 ! reyk 1: .\" $OpenBSD: ldap.1,v 1.5 2018/06/17 23:12:48 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.6 ! reyk 17: .Dd $Mdocdate: June 17 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
25: .Ar command
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
36: .Op Ar arguments ...
37: .Sh DESCRIPTION
38: The
39: .Nm
40: program is a simple LDAP client program.
41: It queries an LDAP server to perform a command and outputs the results
42: in the LDAP Data Interchange Format (LDIF).
43: .Pp
44: The command is as follows:
45: .Bl -tag -width Ds
1.5 jmc 46: .It Cm search Ar options Oo Ar filter Oc Op Ar attribute ...
1.1 reyk 47: Perform a directory search request.
48: The optional
49: .Ar filter
50: argument specifies the LDAP filter for the directory search.
51: The default is
52: .Ar (objectClass=*)
53: and the format must comply to the
54: .Dq String Representation of Search Filters
55: as described in RFC 4515.
56: If one or more
57: .Ar attribute
58: options are specified,
59: .Nm
60: restricts the output to the specified attributes.
61: .El
62: .Pp
63: The options are as follows:
64: .Bl -tag -width Ds
65: .It Fl b Ar basedn
66: Use the specified distinguished name (dn) as the starting point for
67: directory search requests.
68: .It Fl c Ar CAfile
69: When TLS is enabled, load the CA bundle for certificate verification
70: from the specified file.
71: The default is
72: .Pa /etc/ssl/cert.pem .
73: If the LDAP server uses a self-signed certificate,
74: use a file that contains the server certificate in PEM format, e.g.
75: .Pa /etc/ssl/ldapserver.example.com.crt .
76: .It Fl D Ar binddn
77: Use the specified distinguished name to bind to the directory.
78: .It Fl H Ar host
79: The hostname of the LDAP server or an LDAP URL.
80: The LDAP URL is described in RFC 4516 with the following format:
81: .Pp
82: .Sm off
83: .Op Ar protocol No ://
84: .Ar host Op : Ar port
1.4 jmc 85: .Oo / basedn
1.6 ! reyk 86: .Oo ? Op Ar attribute , ...
! 87: .Oo ? Op Ar scope
! 88: .Op ? Op Ar filter
! 89: .Oc
! 90: .Oc
1.1 reyk 91: .Oc
92: .Sm on
93: .Pp
94: The following protocols are supported:
95: .Pp
96: .Bl -tag -width "ldap+tls" -compact
97: .It ldap
98: Connect with TCP in plain text.
99: This is the default.
100: .It ldaps
101: Connect with TLS.
102: The default port is 636.
103: .It ldap+tls
104: Connect with TCP and enable TLS using the StartTLS operation.
105: This is the same as the
106: .Fl Z
107: option.
108: .It ldapi
109: Connect to a UNIX-domain socket.
1.3 jmc 110: The host argument is required to be a URL-encoded path, for example
1.1 reyk 111: .Ar ldapi://%2fvar%2frun%2fldapi
112: for
113: .Pa /var/run/ldapi .
114: .El
115: .Pp
116: The default is
117: .Ar ldap://localhost:389/ .
118: .It Fl L
119: Output the directory search result in a standards-compliant version of
120: the LDAP Data Interchange Format (LDIF).
121: This encodes attribute values that include non-printable or UTF-8
122: characters in the Base64 format and wraps lines at a 79-character limit.
123: If this option is not specified,
124: .Nm
125: encodes
126: .Dq unsafe
127: characters and newlines in a visual format using
128: .Xr vis 3
129: instead.
130: .It Fl l Ar timelimit
131: Request the server to abort the search request after
132: .Ar timelimit
133: seconds.
1.3 jmc 134: The default value is 0.
1.1 reyk 135: for no limit.
136: .It Fl s Ar scope
137: Specify the
138: .Ar scope
139: to be either
140: .Ic base ,
141: .Ic one ,
142: or
143: .Ic sub .
144: The default is
145: .Ic sub
146: for subtree searches.
147: .It Fl v
148: Product more verbose output.
149: .It Fl W
150: Prompt for the bind secret with echo turned off.
151: .It Fl w Ar secret
152: Specify the bind secret on the command line.
153: .It Fl x
154: Use simple authentication.
155: This is the default as
156: .Nm
157: does not support SASL authentication.
1.6 ! reyk 158: .It Fl y Ar secretfile
! 159: Read the bind secret from the first line of the specified file or from
! 160: standard input if the
! 161: .Ar secretfile
! 162: argument is
! 163: .Sq - .
! 164: The file must not be world-readable if it is a regular file.
1.1 reyk 165: .It Fl Z
166: Enable TLS using the StartTLS operation.
167: .It Fl z Ar sizelimit
168: Request the server to limit the search result to a maximum number of
169: .Ar sizelimit
170: entries.
1.3 jmc 171: The default value is 0.
1.1 reyk 172: for no limit.
173: .El
1.3 jmc 174: .Sh FILES
175: .Bl -tag -width "/etc/ssl/cert.pemXXX" -compact
176: .It Pa /etc/ssl/cert.pem
177: Default CA file.
178: .El
1.1 reyk 179: .Sh EXAMPLES
180: The following script can be used with the
181: .Ar AuthorizedKeysCommand
182: option of
183: .Xr sshd 8 :
184: .Bd -literal -offset indent
185: #!/bin/sh
186: ldap search -D cn=Reader,dc=example,dc=com -w mypass123 \e
187: -b ou=People,dc=example,dc=com \e
188: -H ldapserver -c /etc/ssl/ldapserver.crt -Z \e
189: "(&(objectClass=bsdAccount)(uid=$1))" sshPublicKey | \e
1.2 reyk 190: sed 's/^sshPublicKey: //p;d;'
1.1 reyk 191: exit 0
192: .Ed
193: .Pp
194: And the related configuration in
195: .Xr sshd_config 5 :
196: .Bd -literal -offset indent
197: Match Group ldapusers
198: AuthorizedKeysCommand /etc/ssh/ldap-authorized_keys.sh
199: AuthorizedKeysCommandUser _ldap
200: .Ed
201: .Sh SEE ALSO
202: .Xr sshd_config 5 ,
203: .Xr ldapd 8 ,
204: .Xr sshd 8
205: .Sh STANDARDS
206: .Rs
207: .%A G. Good
208: .%D June 2000
209: .%R RFC 2849
210: .%T The LDAP Data Interchange Format (LDIF) - Technical Specification
211: .Re
212: .Pp
213: .Rs
214: .%A M. Smith, Ed.
215: .%A T. Howes
216: .%D June 2006
217: .%R RFC 4515
218: .%T Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters
219: .Re
220: .Pp
221: .Rs
222: .%A M. Smith, Ed.
223: .%A T. Howes
224: .%D June 2006
225: .%R RFC 4516
226: .%T Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
1.3 jmc 227: .Re
1.1 reyk 228: .Sh AUTHORS
229: .An -nosplit
230: The
231: .Nm
232: program was written by
233: .An Reyk Floeter Aq Mt reyk@openbsd.org .
234: .Sh CAVEATS
235: The
236: .Nm
1.3 jmc 237: tool does not support SASL authentication.
238: Authentication should be performed using simple authentication over a
1.1 reyk 239: TLS connection.