| blob | d56e09fed5f8a09516da9eeb56178d20ef0efefa |
1 '\" te
2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LDAPCLIENT 1M "Feb 25, 2017"
7 .SH NAME
8 ldapclient \- initialize LDAP client machine or output an LDAP client profile
9 in LDIF format
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] init [\fB-a\fR profileName=\fIprofileName\fR]
14 [\fB-a\fR domainName=\fIdomain\fR] [\fB-a\fR proxyDN=\fIproxyDN\fR]
15 [\fB-a\fR proxyPassword=\fIpassword\fR]
16 [\fB-a\fR authenticationMethod=\fIauthenticationMethod\fR]
17 [\fB-a\fR enableShadowUpdate=true | false]
18 [\fB-a\fR adminDN=\fIadminDN\fR]
19 [\fB-a\fR adminPassword=\fIadminPassword\fR]
20 [\fB-a\fR certificatePath=\fIpath\fR] [\fB-d\fR \fIbindDN\fR] [\fB-w\fR \fIbindPassword\fR]
21 [\fB-j\fR \fIpasswdFile\fR] [\fB-y\fR \fIpasswdFile\fR]
22 [\fB-z\fR \fIadminrPasswdFile\fR] \fILDAP_server\fR[:\fIport_number\fR]
23 .fi
25 .LP
26 .nf
27 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] manual [\fB-a\fR attrName=\fIattrVal\fR]
28 .fi
30 .LP
31 .nf
32 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] mod [\fB-a\fR attrName=\fIattrVal\fR]
33 .fi
35 .LP
36 .nf
37 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] list
38 .fi
40 .LP
41 .nf
42 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] uninit
43 .fi
45 .LP
46 .nf
47 \fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] genprofile \fB-a\fR profileName=\fIprofileName\fR
48 [\fB-a\fR attrName=\fIattrVal\fR]
49 .fi
51 .SH DESCRIPTION
52 .LP
53 The \fBldapclient\fR utility can be used to:
54 .RS +4
55 .TP
56 .ie t \(bu
57 .el o
58 initialize LDAP client machines
59 .RE
60 .RS +4
61 .TP
62 .ie t \(bu
63 .el o
64 restore the network service environment on LDAP clients
65 .RE
66 .RS +4
67 .TP
68 .ie t \(bu
69 .el o
70 list the contents of the LDAP client cache in human readable format.
71 .RE
72 .sp
73 .LP
74 The \fBinit\fR form of the \fBldapclient\fR utility is used to initialize an
75 LDAP client machine, using a profile stored on an LDAP server specified by
76 \fBLDAP_server\fR. The LDAP client will use the attributes in the specified
77 profile to determine the configuration of the LDAP client. Using a
78 configuration profile allows for easy installation of LDAP client and
79 propagation of configuration changes to LDAP clients. The
80 \fBldap_cachemgr\fR(1M) utility will update the LDAP client configuration when
81 its cache expires by reading the profile. For more information on the
82 configuration profile refer to IETF document \fIA Configuration Schema for LDAP
83 Based Directory User Agents\fR.
84 .sp
85 .LP
86 The \fBmanual\fR form of the \fBldapclient\fR utility is used to initialize an
87 LDAP client machine manually. The LDAP client will use the attributes specified
88 on the command line. Any unspecified attributes will be assigned their default
89 values. At least one server must be specified in the \fBdefaultServerList\fR or
90 the \fBpreferredServerList\fR attributes.The \fBdomainName\fR attribute must be
91 specified if the client's \fBdomainName\fR is not set.
92 .sp
93 .LP
94 The \fBmod\fR form of the \fBldapclient\fR utility is used to modify the
95 configuration of an LDAP client machine that was setup manually. This option
96 modifies only those LDAP client configuration attributes specified on the
97 command line. The \fBmod\fR option should only be used on LDAP clients that
98 were initialized using the \fBmanual\fR option.
99 .sp
100 .LP
101 Regardless of which method is used for initialization, if a client is to be
102 configured to use a proxy \fBcredentialLevel\fR, proxy credentials must be
103 provided using \fB-a\fR \fBproxyDN=\fIproxyDN\fR\fR and \fB-a\fR
104 \fBproxyPassword=\fIproxyPassword\fR\fR options. However, if \fB-a\fR
105 \fBproxyPassword=\fIproxyPassword\fR\fR is not specified, \fBldapclient\fR will
106 prompt for it. Note that \fINULL\fR passwords are not allowed in LDAP. If a
107 self \fBcredentialLevel\fR is configured, \fBauthenticationMethod\fR must be
108 \fBsasl/GSSAPI\fR.
109 .sp
110 .LP
111 Similarily, if a client is to be configured to enable shadow information update
112 and use a proxy credentialLevel, administrator credentials must be provided
113 using \fB-a\fR \fBadminDN=\fR\fIadminDN\fR and \fB-a\fR
114 \fBadminPassword=\fR\fIadminPassword\fR. However, the shadow information update
115 does not need the administrator credentials if a self \fBcredentialLevel\fR is
116 configured.
117 .sp
118 .LP
119 If any file is modified during installation, it will be backed up to
120 \fB/var/ldap/restore\fR. The files that are typically modified during
121 initialization are:
122 .RS +4
123 .TP
124 .ie t \(bu
125 .el o
126 \fB/etc/nsswitch.conf\fR
127 .RE
128 .RS +4
129 .TP
130 .ie t \(bu
131 .el o
132 \fB/etc/defaultdomain\fR (if it exists)
133 .RE
134 .RS +4
135 .TP
136 .ie t \(bu
137 .el o
138 \fB/var/yp/binding/`domainname`\fR (for a NIS(YP) client)
139 .RE
140 .RS +4
141 .TP
142 .ie t \(bu
143 .el o
144 \fB/var/ldap/ldap_client_file\fR (for an existing LDAP client)
145 .RE
146 .RS +4
147 .TP
148 .ie t \(bu
149 .el o
150 \fB/var/ldap/ldap_client_cred\fR (for an existing LDAP client)
151 .RE
152 .sp
153 .LP
154 \fBldapclient\fR does not set up a client to resolve hostnames using DNS. It
155 simply copies \fB/etc/nsswitch.ldap\fR to \fB/etc/nsswitch.conf\fR. If you
156 prefer to use DNS for host resolution, please refer to the DNS documentation
157 for information on setting up DNS. See \fBresolv.conf\fR(4). If you want to use
158 \fBsasl/GSSAPI\fR as the authentication method, you have to use DNS for
159 \fBhosts\fR and \fBipnodes\fR resolution.
160 .sp
161 .LP
162 The \fBlist\fR form of the \fBldapclient\fR utility is used to list the LDAP
163 client configuration. The output will be human readable. LDAP configuration
164 files are not guaranteed to be human readable. Note that for security reason,
165 the values for adminDN and adminPassword will not be displayed.
166 .sp
167 .LP
168 The \fBuninit\fR form of the \fBldapclient\fR utility is used to uninitialize
169 the network service environment, restoring it to the state it was in prior to
170 the last execution of \fBldapclient\fR using \fBinit\fR or \fBmanual\fR. The
171 restoration will succeed only if the machine was initialized with the
172 \fBinit\fR or \fBmanual\fR form of \fBldapclient\fR, as it uses the backup
173 files created by these options.
174 .sp
175 .LP
176 The \fBgenprofile\fR option is used to write an LDIF formatted configuration
177 profile based on the attributes specified on the command line to standard
178 output. This profile can then be loaded into an LDAP server to be used as the
179 client profile, which can be downloaded by means of the \fBldapclient init\fR
180 command. Loading the LDIF formatted profile to the directory server can be done
181 through \fBldapadd\fR(1), or through any server specific import tool. Note that
182 the attributes \fBproxyDN\fR, \fBproxyPassword\fR, \fBcertificatePath\fR,
183 \fBdomainName\fR, \fBenableShadowUpdate\fR, \fBadminDN\fR, and
184 \fBadminPassword\fR are not part of the configuration profile and thus are not
185 permitted.
186 .sp
187 .LP
188 You must have superuser privileges to run the \fBldapclient\fR command, except
189 with the \fBgenprofile\fR option.
190 .sp
191 .LP
192 To access the information stored in the directory, clients can either
193 authenticate to the directory, or use an unauthenticated connection. The LDAP
194 client is configured to have a credential level of either \fBanonymous\fR or
195 \fBproxy\fR. In the first case, the client does not authenticate to the
196 directory. In the second case, client authenticates to the directory using a
197 proxy identity for read access, and using a administrator identity for write
198 access if \fBenableShadowUpdate\fR is configured. In the third case, client
199 authenticates to the directory using a Kerberos principal that is mapped to an
200 LDAP identity by the LDAP server. Refer to the chapter on implementing security
201 in the \fISystem Administration Guide: Naming and Directory Services (DNS, NIS,
202 and LDAP)\fR or your appropriate directory server documentation for identity
203 mapping details.
204 .sp
205 .LP
206 If a client is configured to use an identity, you can configure which
207 authentication method the client will use. The LDAP client supports the
208 following authentication methods:
209 .br
210 .in +2
211 \fBnone\fR
212 .in -2
213 .br
214 .in +2
215 \fBsimple\fR
216 .in -2
217 .br
218 .in +2
219 \fBsasl/CRAM-MD5\fR
220 .in -2
221 .br
222 .in +2
223 \fBsasl/DIGEST-MD5\fR
224 .in -2
225 .br
226 .in +2
227 \fBsasl/GSSAPI\fR
228 .in -2
229 .br
230 .in +2
231 \fBtls:none\fR
232 .in -2
233 .br
234 .in +2
235 \fBtls:simple\fR
236 .in -2
237 .br
238 .in +2
239 \fBtls:sasl/CRAM-MD5\fR
240 .in -2
241 .br
242 .in +2
243 \fBtls:sasl/DIGEST-MD5\fR
244 .in -2
245 .sp
246 .LP
247 Note that some directory servers may not support all of these authentication
248 methods. For \fBsimple\fR, be aware that the bind password will be sent in the
249 clear to the LDAP server. For those authentication methods using TLS (transport
250 layer security), the entire session is encrypted. You will need to install the
251 appropriate certificate databases to use TLS. Note that the \fBtls:none\fR
252 authentication method requires a \fBcredentialLevel\fR of \fBproxy\fR to
253 take effect.
254 .SS "Commands"
255 .LP
256 The following commands are supported:
257 .sp
258 .ne 2
259 .na
260 \fB\fBinit\fR\fR
261 .ad
262 .sp .6
263 .RS 4n
264 Initialize client from a profile on a server.
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBmanual\fR\fR
271 .ad
272 .sp .6
273 .RS 4n
274 Manually initialize client with the specified attribute values.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBmod\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Modify attribute values in the configuration file after a manual initialization
285 of the client.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBlist\fR\fR
292 .ad
293 .sp .6
294 .RS 4n
295 Write the contents of the LDAP client cache to standard output in human
296 readable form.
297 .RE
299 .sp
300 .ne 2
301 .na
302 \fB\fBuninit\fR\fR
303 .ad
304 .sp .6
305 .RS 4n
306 Uninitialize an LDAP client, assuming that \fBldapclient\fR was used to
307 initialize the client.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fB\fBgenprofile\fR\fR
314 .ad
315 .sp .6
316 .RS 4n
317 Generate a configuration profile in LDIF format that can then be stored in the
318 directory for clients to use, with the \fBinit\fR form of this command.
319 .RE
321 .SS "Attributes"
322 .LP
323 The following attributes are supported:
324 .sp
325 .ne 2
326 .na
327 \fB\fBadminDN\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 Specify the Bind Distinguished Name for the administrator identity that is used
332 for shadow information update. This option is required if the credential level
333 is \fBproxy\fR, and \fBenableShadowUpdate\fR is set to \fBtrue\fR. There is no
334 default value.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fBadminPassword\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 Specify the administrator password. This option is required if the credential
345 level is \fBproxy\fR, and \fBenableShadowUpdate\fR is set to \fBtrue\fR. There
346 is no default value.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBattributeMap\fR\fR
353 .ad
354 .sp .6
355 .RS 4n
356 Specify a mapping from an attribute defined by a service to an attribute in an
357 alternative schema. This can be used to change the default schema used for a
358 given service. The syntax of \fBattributeMap\fR is defined in the profile IETF
359 draft. This option can be specified multiple times. The default value for all
360 services is \fINULL\fR. In the example,
361 .sp
362 .in +2
363 .nf
364 attributeMap: passwd:uid=employeeNumber
365 .fi
366 .in -2
367 .sp
369 the LDAP client would use the LDAP attribute \fBemployeeNumber\fR rather than
370 \fBuid\fR for the \fBpasswd\fR service. This is a multivalued attribute.
371 .sp
372 To use rfc2307bis style groups (with a DN rather than username as the
373 attribute value), map the \fBmemberUid\fR attribute to the group attribute
374 being used (typically either \fBuniqueMember\fR or \fBmember\fR), for example:
375 .sp
376 .in +2
377 .nf
378 attributeMap: group:memberUid=uniqueMember
379 .fi
380 .in -2
381 .sp
383 Group membership in a given directory is expected to be maintained with
384 either username format member attributes, or DN format member attributes. If
385 both are present they must describe identical memberships or unexpected
386 results may be obtained. For DN format attributes, the username is required
387 to be the RDN of the entry. Note that nested groups are not currently
388 supported, and unexpected results may be obtained if they are used.
390 .RE
392 .sp
393 .ne 2
394 .na
395 \fB\fBauthenticationMethod\fR\fR
396 .ad
397 .sp .6
398 .RS 4n
399 Specify the default authentication method used by all services unless
400 overridden by the \fBserviceAuthenticationMethod\fR attribute. Multiple values
401 can be specified by using a semicolon-separated list. The default value is
402 \fBnone\fR. For those services that use \fBcredentialLevel\fR and
403 \fBcredentialLevel\fR is \fBanonymous\fR, this attribute is ignored. Services
404 such as \fBpam_ldap\fR will use this attribute, even if \fBcredentialLevel\fR
405 is anonymous. The supported authentication methods are described above. If the
406 authenticationMethod is \fBsasl/GSSAPI\fR, the \fBhosts\fR and \fBipnodes\fR of
407 \fB/etc/nsswitch.conf\fR must be configured with DNS support, for example:
408 .sp
409 .in +2
410 .nf
411 hosts: dns files
412 ipnodes: dns files
413 .fi
414 .in -2
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fBbindTimeLimit\fR\fR
422 .ad
423 .sp .6
424 .RS 4n
425 The maximum time in seconds that a client should spend performing a bind
426 operation. Set this to a positive integer. The default value is 30.
427 .RE
429 .sp
430 .ne 2
431 .na
432 \fB\fBcertificatePath\fR\fR
433 .ad
434 .sp .6
435 .RS 4n
436 The certificate path for the location of the certificate database. The value is
437 the path where security database files reside. This is used for TLS support,
438 which is specified in the \fBauthenticationMethod\fR and
439 \fBserviceAuthenticationMethod\fR attributes. The default is \fB/var/ldap\fR.
440 .RE
442 .sp
443 .ne 2
444 .na
445 \fB\fBcredentialLevel\fR\fR
446 .ad
447 .sp .6
448 .RS 4n
449 Specify the credential level the client should use to contact the directory.
450 The credential levels supported are either \fBanonymous\fR or \fBproxy\fR. If a
451 \fBproxy\fR credential level is specified, then the \fBauthenticationMethod\fR
452 attribute must be specified to determine the authentication mechanism. Also, if
453 the credential level is \fBproxy\fR and at least one of the authentication
454 methods require a bind DN, the \fBproxyDN\fR and \fBproxyPassword\fR attribute
455 values must be set. In addition, if \fBenableShadowUpdate\fR is set to
456 \fBtrue\fR, the \fBadminDN\fR and \fBadminPassword\fR values must be set. If a
457 self credential level is specified, the \fBauthenticationMethod\fR must be
458 \fBsasl/GSSAPI\fR.
459 .RE
461 .sp
462 .ne 2
463 .na
464 \fB\fBdefaultSearchBase\fR\fR
465 .ad
466 .sp .6
467 .RS 4n
468 Specify the default search base DN. There is no default. The
469 \fBserviceSearchDescriptor\fR attribute can be used to override the
470 \fBdefaultSearchBase\fR for given services.
471 .RE
473 .sp
474 .ne 2
475 .na
476 \fB\fBdefaultSearchScope=one | sub\fR\fR
477 .ad
478 .sp .6
479 .RS 4n
480 Specify the default search scope for the client's search operations. This
481 default can be overridden for a given service by specifying a
482 \fBserviceSearchDescriptor\fR. The default is one level search.
483 .RE
485 .sp
486 .ne 2
487 .na
488 \fB\fBdefaultServerList\fR\fR
489 .ad
490 .sp .6
491 .RS 4n
492 A space separated list of server names or server addresses, either IPv4 or
493 IPv6. If you specify server names, be sure that the LDAP client can resolve the
494 name without the LDAP name service. You must resolve the LDAP servers' names by
495 using either \fBfiles\fR or \fBdns\fR. If the LDAP server name cannot be
496 resolved, your naming service will fail.
497 .sp
498 The port number is optional. If not specified, the default LDAP server port
499 number 389 is used, except when TLS is specified in the authentication method.
500 In this case, the default LDAP server port number is 636.
501 .sp
502 The format to specify the port number for an IPv6 address is:
503 .sp
504 .in +2
505 .nf
506 [ipv6_addr]:port
507 .fi
508 .in -2
510 To specify the port number for an IPv4 address, use the following format:
511 .sp
512 .in +2
513 .nf
514 ipv4_addr:port
515 .fi
516 .in -2
518 If the host name is specified, use the format:
519 .sp
520 .in +2
521 .nf
522 host_name:port
523 .fi
524 .in -2
526 If you use TLS, the LDAP server's hostname must match the hostname in the TLS
527 certificate. Typically, the hostname in the TLS certificate is a fully
528 qualified domain name. With TLS, the LDAP server host addresses must resolve to
529 the hostnames in the TLS certificate. You must use \fBfiles\fR or \fBdns\fR to
530 resolve the host address.
531 .RE
533 .sp
534 .ne 2
535 .na
536 \fB\fBdomainName\fR\fR
537 .ad
538 .sp .6
539 .RS 4n
540 Specify the DNS domain name. This becomes the default domain for the machine.
541 The default is the current domain name. This attribute is only used in client
542 initialization.
543 .RE
545 .sp
546 .ne 2
547 .na
548 \fB\fBenableShadowUpdate=true | false\fR\fR
549 .ad
550 .sp .6
551 .RS 4n
552 Specify whether the client is allowed to update shadow information. If set to
553 \fBtrue\fR and the credential level is \fBproxy\fR, \fBadminDN\fR and
554 \fBadminPassword\fR must be specified.
555 .RE
557 .sp
558 .ne 2
559 .na
560 \fB\fBfollowReferrals=true | false\fR\fR
561 .ad
562 .sp .6
563 .RS 4n
564 Specify the referral setting. A setting of true implies that referrals will be
565 automatically followed and false would result in referrals not being followed.
566 The default is true.
567 .RE
569 .sp
570 .ne 2
571 .na
572 \fB\fBobjectclassMap\fR\fR
573 .ad
574 .sp .6
575 .RS 4n
576 Specify a mapping from an \fBobjectclass\fR defined by a service to an
577 \fBobjectclass\fR in an alternative schema. This can be used to change the
578 default schema used for a given service. The syntax of \fBobjectclassMap\fR is
579 defined in the profile IETF draft. This option can be specified multiple times.
580 The default value for all services is \fINULL\fR. In the example,
581 .sp
582 .in +2
583 .nf
584 objectclassMap=passwd:posixAccount=unixAccount
585 .fi
586 .in -2
587 .sp
589 the LDAP client would use the LDAP \fBobjectclass\fR of \fBunixAccount\fR
590 rather than the \fBposixAccount\fR for the \fBpasswd\fR service. This is a
591 multivalued attribute.
592 .RE
594 .sp
595 .ne 2
596 .na
597 \fB\fBpreferredServerList\fR\fR
598 .ad
599 .sp .6
600 .RS 4n
601 Specify the space separated list of server names or server addresses, either
602 IPv4 or IPv6, to be contacted before servers specified by the
603 \fBdefaultServerList\fR attribute. If you specify server names, be sure that
604 the LDAP client can resolve the name without the LDAP name service. You must
605 resolve the LDAP servers' names by using either \fBfiles\fR or \fBdns\fR. If
606 the LDAP server name cannot be resolved, your naming service will fail.
607 .sp
608 The port number is optional. If not specified, the default LDAP server port
609 number 389 is used, except when TLS is specified in the authentication method.
610 In this case, the default LDAP server port number is 636.
611 .sp
612 The format to specify the port number for an IPv6 address is:
613 .sp
614 .in +2
615 .nf
616 [ipv6_addr]:port
617 .fi
618 .in -2
620 To specify the port number for an IPv4 address, use the following format:
621 .sp
622 .in +2
623 .nf
624 ipv4_addr:port
625 .fi
626 .in -2
628 If the host name is specified, use the format:
629 .sp
630 .in +2
631 .nf
632 host_name:port
633 .fi
634 .in -2
636 If you use TLS, the LDAP server's hostname must match the hostname in the TLS
637 certificate. Typically, the hostname in the TLS certificate is a fully
638 qualified domain name. With TLS, the LDAP server host addresses must resolve to
639 the hostnames in the TLS certificate. You must use \fBfiles\fR or \fBdns\fR to
640 resolve the host address.
641 .RE
643 .sp
644 .ne 2
645 .na
646 \fB\fBprofileName\fR\fR
647 .ad
648 .sp .6
649 .RS 4n
650 Specify the profile name. For \fBldapclient init\fR, this attribute is the name
651 of an existing profile which may be downloaded periodically depending on the
652 value of the \fBprofileTTL\fR attribute. For \fBldapclient genprofile\fR, this
653 is the name of the profile to be generated. The default value is \fBdefault\fR.
654 .RE
656 .sp
657 .ne 2
658 .na
659 \fB\fBprofileTTL\fR\fR
660 .ad
661 .sp .6
662 .RS 4n
663 Specify the TTL value in seconds for the client information. This is only
664 relevant if the machine was initialized with a client profile. If you do not
665 want \fBldap_cachemgr\fR(1M) to attempt to refresh the LDAP client
666 configuration from the LDAP server, set \fBprofileTTL\fR to 0 (zero). Valid
667 values are either zero 0 (for no expiration) or a positive integer in seconds.
668 The default value is 12 hours.
669 .RE
671 .sp
672 .ne 2
673 .na
674 \fB\fBproxyDN\fR\fR
675 .ad
676 .sp .6
677 .RS 4n
678 Specify the Bind Distinguished Name for the proxy identity. This option is
679 required if the credential level is \fBproxy\fR, and at least one of the
680 authentication methods requires a bind DN. There is no default value.
681 .RE
683 .sp
684 .ne 2
685 .na
686 \fB\fBproxyPassword\fR\fR
687 .ad
688 .sp .6
689 .RS 4n
690 Specify client proxy password. This option is required if the credential level
691 is \fBproxy\fR, and at least one of the authentication methods requires a bind
692 DN. There is no default.
693 .RE
695 .sp
696 .ne 2
697 .na
698 \fB\fBsearchTimeLimit\fR\fR
699 .ad
700 .sp .6
701 .RS 4n
702 Specify maximum number of seconds allowed for an LDAP search operation. The
703 default is 30 seconds. The server may have its own search time limit.
704 .RE
706 .sp
707 .ne 2
708 .na
709 \fB\fBserviceAuthenticationMethod\fR\fR
710 .ad
711 .sp .6
712 .RS 4n
713 Specify authentication methods to be used by a service in the form
714 \fIservicename\fR:\fBauthenticationmethod\fR, for example:
715 .sp
716 .in +2
717 .nf
718 pam_ldap:tls:simple
719 .fi
720 .in -2
722 For multiple authentication methods, use a semicolon-separated list. The
723 default value is no service authentication methods, in which case, each service
724 would default to the \fBauthenticationMethod\fR value. The supported
725 authentications are described above.
726 .sp
727 Three services support this feature: \fBpasswd-cmd\fR, \fBkeyserv\fR, and
728 \fBpam_ldap\fR. The \fBpasswd-cmd\fR service is used to define the
729 authentication method to be used by \fBpasswd\fR(1) to change the user's
730 password and other attributes. The \fBkeyserv\fR service is used to identify
731 the authentication method to be used by the \fBchkey\fR(1) and \fBnewkey\fR(1M)
732 utilities. The \fBpam_ldap\fR service defines the authentication method to be
733 used for authenticating users when \fBpam_ldap\fR(5) is configured. If this
734 attribute is not set for any of these services, the \fBauthenticationMethod\fR
735 attribute is used to define the authentication method. This is a multivalued
736 attribute.
737 .RE
739 .sp
740 .ne 2
741 .na
742 \fB\fBserviceCredentialLevel\fR\fR
743 .ad
744 .sp .6
745 .RS 4n
746 Specify credential level to be used by a service. Multiple values can be
747 specified in a space-separated list. The default value for all services is
748 \fINULL\fR. The supported credential levels are: \fBanonymous\fR or
749 \fBproxy\fR. At present, no service uses this attribute. This is a multivalued
750 attribute.
751 .RE
753 .sp
754 .ne 2
755 .na
756 \fB\fBserviceSearchDescriptor\fR\fR
757 .ad
758 .sp .6
759 .RS 4n
760 Override the default base DN for LDAP searches for a given service. The format
761 of the descriptors also allow overriding the default search scope and search
762 filter for each service. The syntax of \fBserviceSearchDescriptor\fR is defined
763 in the profile IETF draft. The default value for all services is \fINULL\fR.
764 This is a multivalued attribute. In the example,
765 .sp
766 .in +2
767 .nf
768 serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one
769 .fi
770 .in -2
771 .sp
773 the LDAP client would do a one level search in
774 \fBou=people,dc=a1,dc=acme,dc=com\fR rather than
775 \fBou=people,\fIdefaultSearchBase\fR\fR for the \fBpasswd\fR service.
776 .RE
778 .SH OPTIONS
779 .LP
780 The following options are supported:
781 .sp
782 .ne 2
783 .na
784 \fB\fB-a\fR \fBattrName=\fR\fIattrValue\fR\fR
785 .ad
786 .sp .6
787 .RS 4n
788 Specify \fBattrName\fR and its value. See \fBSYNOPSIS\fR for a complete list of
789 possible attribute names and values.
790 .RE
792 .sp
793 .ne 2
794 .na
795 \fB\fB-D\fR \fIbindDN\fR\fR
796 .ad
797 .sp .6
798 .RS 4n
799 Specifies an entry that has read permission for the requested database.
800 .RE
802 .sp
803 .ne 2
804 .na
805 \fB\fB-j\fR \fIpasswdFile\fR\fR
806 .ad
807 .sp .6
808 .RS 4n
809 Specify a file containing the password for the bind DN or the password for the
810 SSL client's key database. To protect the password, use this option in scripts
811 and place the password in a secure file. This option is mutually exclusive of
812 the \fB-w\fR option.
813 .RE
815 .sp
816 .ne 2
817 .na
818 \fB\fB-q\fR\fR
819 .ad
820 .sp .6
821 .RS 4n
822 Quiet mode. No output is generated.
823 .RE
825 .sp
826 .ne 2
827 .na
828 \fB\fB-v\fR\fR
829 .ad
830 .sp .6
831 .RS 4n
832 Verbose output.
833 .RE
835 .sp
836 .ne 2
837 .na
838 \fB\fB-w\fR \fIbindPassword\fR\fR
839 .ad
840 .sp .6
841 .RS 4n
842 Password to be used for authenticating the bind DN. If this parameter is
843 missing, the command will prompt for a password. \fBNULL\fR passwords are not
844 supported in LDAP.
845 .sp
846 When you use \fB-w\fR \fIbindPassword\fR to specify the password to be used for
847 authentication, the password is visible to other users of the system by means
848 of the \fBps\fR command, in script files, or in shell history.
849 .sp
850 If you supply "\fB-\fR" (hyphen) as a password, the command will prompt for a
851 password.
852 .RE
854 .sp
855 .ne 2
856 .na
857 \fB\fB-y\fR \fIpasswdFile\fR\fR
858 .ad
859 .sp .6
860 .RS 4n
861 Specify a file containing the password for the proxy DN. To protect the
862 password, use this option in scripts and place the password in a secure file.
863 This option is mutually exclusive of the \fB-a\fR \fIproxyPassword\fR option.
864 .RE
866 .sp
867 .ne 2
868 .na
869 \fB\fB-z\fR \fIadminrPasswdFile\fR\fR
870 .ad
871 .sp .6
872 .RS 4n
873 Specify a file containing the password for the \fBadminDN\fR. To protect the
874 password, use this option in scripts and place the password in a secure file.
875 This option is mutually exclusive of the \fB-a\fR \fIadminPassword\fR option.
876 .RE
878 .SH OPERANDS
879 .LP
880 The following operand is supported:
881 .sp
882 .ne 2
883 .na
884 \fB\fILDAP_server\fR\fR
885 .ad
886 .sp .6
887 .RS 4n
888 An address or a name for the LDAP server from which the profile will be loaded.
889 The current naming service specified in the \fBnsswitch.conf\fR file is used.
890 Once the profile is loaded, the \fBpreferredServerList\fR and
891 \fBdefaultServerList\fR specified in the profile are used.
892 .RE
894 .SH EXAMPLES
895 .LP
896 \fBExample 1 \fRSetting Up a Client By Using the Default Profile Stored on a
897 Specified LDAP Server
898 .sp
899 .LP
900 The following example shows how to set up a client using the default profile
901 stored on the specified LDAP server. This command will only be successful if
902 either the credential level in the profile is set to \fBanonymous\fR or the
903 authentication method is set to \fBnone\fR.
905 .sp
906 .in +2
907 .nf
908 example# \fBldapclient init 172.16.100.1\fR
909 .fi
910 .in -2
911 .sp
913 .LP
914 \fBExample 2 \fRSetting Up a Client By Using the \fBsimple\fR Profile Stored on
915 a Specified LDAP Server
916 .sp
917 .LP
918 The following example shows how to set up a client using the \fBsimple\fR
919 profile stored on the specified LDAP server. The domainname is set to
920 \fBxyz.mycompany.com\fR and the proxyPassword is \fBsecret\fR.
922 .sp
923 .in +2
924 .nf
925 example# \fBldapclient init -a profileName=simple \e
926 -a domainName=xyz.mycompany.com \e
927 -a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=mycompany,dc=com \e
928 -a proxyPassword=secret '['fe80::a00:20ff:fea3:388']':386\fR
929 .fi
930 .in -2
931 .sp
933 .LP
934 \fBExample 3 \fRSetting Up a Client Using Only One Server
935 .sp
936 .LP
937 The following example shows how to set up a client using only one server. The
938 authentication method is set to \fBnone\fR, and the search base is
939 \fBdc=mycompany,dc=com\fR.
941 .sp
942 .in +2
943 .nf
944 example# \fBldapclient manual -a authenticationMethod=none \e
945 -a defaultSearchBase=dc=mycompany,dc=com \e
946 -a defaultServerList=172.16.100.1\fR
947 .fi
948 .in -2
949 .sp
951 .LP
952 \fBExample 4 \fRSetting Up a Client Using Only One Server That Does Not Follow
953 Referrals
954 .sp
955 .LP
956 The following example shows how to set up a client using only one server. The
957 credential level is set to \fBproxy\fR. The authentication method of is
958 \fBsasl/CRAM-MD5\fR, with the option not to follow referrals. The domain name
959 is \fBxyz.mycompany.com\fR, and the LDAP server is running on port number 386
960 at IP address \fB172.16.100.1\fR.
962 .sp
963 .in +2
964 .nf
965 example# \fBldapclient manual \e
966 -a credentialLevel=proxy \e
967 -a authenticationMethod=sasl/CRAM-MD5 \e
968 -a proxyPassword=secret \e
969 -a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=mycompany,dc=com \e
970 -a defaultSearchBase=dc=xyz,dc=mycompany,dc=com \e
971 -a domainName=xyz.mycompany.com \e
972 -a followReferrals=false \e
973 -a defaultServerList=172.16.100.1:386\fR
974 .fi
975 .in -2
976 .sp
978 .LP
979 \fBExample 5 \fRUsing \fBgenprofile\fR to Set Only the \fBdefaultSearchBase\fR
980 and the Server Addresses
981 .sp
982 .LP
983 The following example shows how to use the \fBgenprofile\fR command to set the
984 \fBdefaultSearchBase\fR and the server addresses.
986 .sp
987 .in +2
988 .nf
989 example# \fBldapclient genprofile -a profileName=myprofile \e
990 -a defaultSearchBase=dc=eng,dc=sun,dc=com \e
991 -a "defaultServerList=172.16.100.1 172.16.234.15:386" \e
992 > myprofile.ldif\fR
993 .fi
994 .in -2
995 .sp
997 .LP
998 \fBExample 6 \fRCreating a Profile on IPv6 servers
999 .sp
1000 .LP
1001 The following example creates a profile on IPv6 servers
1003 .sp
1004 .in +2
1005 .nf
1006 example# \fBldapclient genprofile -a profileName=eng \e
1007 -a credentialLevel=proxy \e
1008 -a authenticationMethod=sasl/DIGEST-MD5 \e
1009 -a defaultSearchBase=dc=eng,dc=acme,dc=com \e
1010 -a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one"\e
1011 -a preferredServerList= '['fe80::a00:20ff:fea3:388']' \e
1012 -a "defaultServerList='['fec0::111:a00:20ff:fea3:edcf']' \e
1013 '['fec0::111:a00:20ff:feb5:e41']'" > eng.ldif\fR
1014 .fi
1015 .in -2
1016 .sp
1018 .LP
1019 \fBExample 7 \fRCreating a Profile That Overrides Every Default Value
1020 .sp
1021 .LP
1022 The following example shows a profile that overrides every default value.
1024 .sp
1025 .in +2
1026 .nf
1027 example# \fBldapclient genprofile -a profileName=eng \e
1028 -a credentialLevel=proxy -a authenticationMethod=sasl/DIGEST-MD5 \e
1029 -a bindTimeLimit=20 \e
1030 -a defaultSearchBase=dc=eng,dc=acme,dc=com \e
1031 -a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one"\e
1032 -a serviceAuthenticationMethod=pam_ldap:tls:simple \e
1033 -a defaultSearchScope=sub \e
1034 -a attributeMap=passwd:uid=employeeNumber \e
1035 -a objectclassMap=passwd:posixAccount=unixAccount \e
1036 -a followReferrals=false -a profileTTL=6000 \e
1037 -a preferredServerList=172.16.100.30 -a searchTimeLimit=30 \e
1038 -a "defaultServerList=172.16.200.1 172.16.100.1 192.168.5.6" > eng.ldif\fR
1039 .fi
1040 .in -2
1041 .sp
1043 .SH EXIT STATUS
1044 .LP
1045 The following exit values are returned:
1046 .sp
1047 .ne 2
1048 .na
1049 \fB0\fR
1050 .ad
1051 .RS 5n
1052 The command successfully executed.
1053 .RE
1055 .sp
1056 .ne 2
1057 .na
1058 \fB1\fR
1059 .ad
1060 .RS 5n
1061 An error occurred. An error message is output.
1062 .RE
1064 .sp
1065 .ne 2
1066 .na
1067 \fB2\fR
1068 .ad
1069 .RS 5n
1070 \fBproxyDN\fR and \fBproxyPassword\fR attributes are required, but they are not
1071 provided.
1072 .RE
1074 .SH FILES
1075 .ne 2
1076 .na
1077 \fB\fB/var/ldap/ldap_client_cred\fR\fR
1078 .ad
1079 .br
1080 .na
1081 \fB\fB/var/ldap/ldap_client_file\fR\fR
1082 .ad
1083 .sp .6
1084 .RS 4n
1085 Contain the LDAP configuration of the client. These files are not to be
1086 modified manually. Their content is not guaranteed to be human readable. Use
1087 \fBldapclient\fR to update them.
1088 .RE
1090 .sp
1091 .ne 2
1092 .na
1093 \fB\fB/etc/defaultdomain\fR\fR
1094 .ad
1095 .sp .6
1096 .RS 4n
1097 System default domain name, matching the domain name of the data in the LDAP
1098 servers. See \fBdefaultdomain\fR(4).
1099 .RE
1101 .sp
1102 .ne 2
1103 .na
1104 \fB\fB/etc/nsswitch.conf\fR\fR
1105 .ad
1106 .sp .6
1107 .RS 4n
1108 Configuration file for the name-service switch. See \fBnsswitch.conf\fR(4).
1109 .RE
1111 .sp
1112 .ne 2
1113 .na
1114 \fB\fB/etc/nsswitch.ldap\fR\fR
1115 .ad
1116 .sp .6
1117 .RS 4n
1118 Sample configuration file for the name-service switch configured with LDAP and
1119 files.
1120 .RE
1122 .SH ATTRIBUTES
1123 .LP
1124 See \fBattributes\fR(5) for descriptions of the following attributes:
1125 .sp
1127 .sp
1128 .TS
1129 box;
1130 c | c
1131 l | l .
1132 ATTRIBUTE TYPE ATTRIBUTE VALUE
1133 _
1134 Interface Stability Evolving
1135 .TE
1137 .SH SEE ALSO
1138 .LP
1139 \fBchkey\fR(1), \fBldap\fR(1), \fBldapadd\fR(1), \fBldapdelete\fR(1),
1140 \fBldaplist\fR(1), \fBldapmodify\fR(1), \fBldapmodrdn\fR(1),
1141 \fBldapsearch\fR(1), \fBidsconfig\fR(1M), \fBldapaddent\fR(1M),
1142 \fBldap_cachemgr\fR(1M), \fBdefaultdomain\fR(4),
1143 \fBnsswitch.conf\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5)
1144 .SH CAUTION
1145 .LP
1146 Currently \fBStartTLS\fR is not supported by \fBlibldap.so.5\fR, therefore the
1147 port number provided refers to the port used during a TLS open, rather than the
1148 port used as part of a \fBStartTLS\fR sequence. To avoid timeout delays, mixed
1149 use of TLS and non-TLS authentication mechanisms is not recommended.
1150 .sp
1151 .LP
1152 For example:
1153 .sp
1154 .in +2
1155 .nf
1156 -h foo:1000 -a authenticationMethod=tls:simple
1157 .fi
1158 .in -2
1159 .sp
1161 .sp
1162 .LP
1163 \&...or:
1164 .sp
1165 .in +2
1166 .nf
1167 defaultServerList= foo:1000
1168 authenticationMethod= tls:simple
1169 .fi
1170 .in -2
1171 .sp
1173 .sp
1174 .LP
1175 The preceding refers to a raw TLS open on host \fBfoo\fR port 1000, not an
1176 open, StartTLS sequence on an unsecured port 1000. If port 1000 is unsecured
1177 the connection will not be made.
1178 .sp
1179 .LP
1180 As a second example, the following will incur a significant timeout delay while
1181 attempting the connection to \fBfoo:636\fR with an unsecured bind.
1182 .sp
1183 .in +2
1184 .nf
1185 defaultServerList= foo:636 foo:389
1186 authenticationMethod= simple
1187 .fi
1188 .in -2
1189 .sp