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