Annotation of src/usr.bin/ldap/ldap.1, Revision 1.5
1.5 ! jmc 1: .\" $OpenBSD: ldap.1,v 1.4 2018/06/13 18:26:03 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.2 reyk 17: .Dd $Mdocdate: June 13 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
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
1.5 ! jmc 45: .It Cm search Ar options Oo Ar filter Oc Op Ar attribute ...
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.4 jmc 84: .Oo / basedn
85: .Op ? Ar attribute , ...
86: .Op ? Ar scope
87: .Op ? Ar filter
1.1 reyk 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.
1.3 jmc 107: The host argument is required to be a URL-encoded path, for example
1.1 reyk 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.
1.3 jmc 131: The default value is 0.
1.1 reyk 132: for no limit.
133: .It Fl s Ar scope
134: Specify the
135: .Ar scope
136: to be either
137: .Ic base ,
138: .Ic one ,
139: or
140: .Ic sub .
141: The default is
142: .Ic sub
143: for subtree searches.
144: .It Fl v
145: Product more verbose output.
146: .It Fl W
147: Prompt for the bind secret with echo turned off.
148: .It Fl w Ar secret
149: Specify the bind secret on the command line.
150: .It Fl x
151: Use simple authentication.
152: This is the default as
153: .Nm
154: does not support SASL authentication.
155: .It Fl Z
156: Enable TLS using the StartTLS operation.
157: .It Fl z Ar sizelimit
158: Request the server to limit the search result to a maximum number of
159: .Ar sizelimit
160: entries.
1.3 jmc 161: The default value is 0.
1.1 reyk 162: for no limit.
163: .El
1.3 jmc 164: .Sh FILES
165: .Bl -tag -width "/etc/ssl/cert.pemXXX" -compact
166: .It Pa /etc/ssl/cert.pem
167: Default CA file.
168: .El
1.1 reyk 169: .Sh EXAMPLES
170: The following script can be used with the
171: .Ar AuthorizedKeysCommand
172: option of
173: .Xr sshd 8 :
174: .Bd -literal -offset indent
175: #!/bin/sh
176: ldap search -D cn=Reader,dc=example,dc=com -w mypass123 \e
177: -b ou=People,dc=example,dc=com \e
178: -H ldapserver -c /etc/ssl/ldapserver.crt -Z \e
179: "(&(objectClass=bsdAccount)(uid=$1))" sshPublicKey | \e
1.2 reyk 180: sed 's/^sshPublicKey: //p;d;'
1.1 reyk 181: exit 0
182: .Ed
183: .Pp
184: And the related configuration in
185: .Xr sshd_config 5 :
186: .Bd -literal -offset indent
187: Match Group ldapusers
188: AuthorizedKeysCommand /etc/ssh/ldap-authorized_keys.sh
189: AuthorizedKeysCommandUser _ldap
190: .Ed
191: .Sh SEE ALSO
192: .Xr sshd_config 5 ,
193: .Xr ldapd 8 ,
194: .Xr sshd 8
195: .Sh STANDARDS
196: .Rs
197: .%A G. Good
198: .%D June 2000
199: .%R RFC 2849
200: .%T The LDAP Data Interchange Format (LDIF) - Technical Specification
201: .Re
202: .Pp
203: .Rs
204: .%A M. Smith, Ed.
205: .%A T. Howes
206: .%D June 2006
207: .%R RFC 4515
208: .%T Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters
209: .Re
210: .Pp
211: .Rs
212: .%A M. Smith, Ed.
213: .%A T. Howes
214: .%D June 2006
215: .%R RFC 4516
216: .%T Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
1.3 jmc 217: .Re
1.1 reyk 218: .Sh AUTHORS
219: .An -nosplit
220: The
221: .Nm
222: program was written by
223: .An Reyk Floeter Aq Mt reyk@openbsd.org .
224: .Sh CAVEATS
225: The
226: .Nm
1.3 jmc 227: tool does not support SASL authentication.
228: Authentication should be performed using simple authentication over a
1.1 reyk 229: TLS connection.