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