'\" te
.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH LDAPCLIENT 1M "Feb 14, 2009"
.SH NAME
ldapclient \- initialize LDAP client machine or output an LDAP client profile
in LDIF format
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] init [\fB-a\fR profileName=\fIprofileName\fR]
     [\fB-a\fR domainName=\fIdomain\fR] [\fB-a\fR proxyDN=\fIproxyDN\fR]
     [\fB-a\fR proxyPassword=\fIpassword\fR]
     [\fB-a\fR authenticationMethod=\fIauthenticationMethod\fR]
     [\fB-a\fR enableShadowUpdate=true | false]
     [\fB-a\fR adminDN=\fIadminDN\fR]
     [\fB-a\fR adminPassword=\fIadminPassword\fR]
     [\fB-a\fR certificatePath=\fIpath\fR] [\fB-d\fR \fIbindDN\fR] [\fB-w\fR \fIbindPassword\fR]
     [\fB-j\fR \fIpasswdFile\fR] [\fB-y\fR \fIpasswdFile\fR]
     [\fB-z\fR \fIadminrPasswdFile\fR] \fILDAP_server\fR[:\fIport_number\fR]
.fi

.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] manual [\fB-a\fR attrName=\fIattrVal\fR]
.fi

.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] mod [\fB-a\fR attrName=\fIattrVal\fR]
.fi

.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] list
.fi

.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] uninit
.fi

.LP
.nf
\fB/usr/sbin/ldapclient\fR [\fB-v\fR | \fB-q\fR] genprofile \fB-a\fR profileName=\fIprofileName\fR
     [\fB-a\fR attrName=\fIattrVal\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBldapclient\fR utility can be used to:
.RS +4
.TP
.ie t \(bu
.el o
initialize LDAP client machines
.RE
.RS +4
.TP
.ie t \(bu
.el o
restore the network service environment on LDAP clients
.RE
.RS +4
.TP
.ie t \(bu
.el o
list the contents of the LDAP client cache in human readable format.
.RE
.sp
.LP
The \fBinit\fR form of the \fBldapclient\fR utility is used to initialize an
LDAP client machine, using a profile stored on an LDAP server specified by
\fBLDAP_server\fR. The LDAP client will use the attributes in the specified
profile to determine the configuration of the LDAP client. Using a
configuration profile allows for easy installation of LDAP client and
propagation of configuration changes to LDAP clients. The
\fBldap_cachemgr\fR(1M) utility will update the LDAP client configuration when
its cache expires by reading the profile. For more information on the
configuration profile refer to IETF document \fIA Configuration Schema for LDAP
Based Directory User Agents\fR.
.sp
.LP
The \fBmanual\fR form of the \fBldapclient\fR utility is used to initialize an
LDAP client machine manually. The LDAP client will use the attributes specified
on the command line. Any unspecified attributes will be assigned their default
values. At least one server must be specified in the \fBdefaultServerList\fR or
the \fBpreferredServerList\fR attributes.The \fBdomainName\fR attribute must be
specified if the client's \fBdomainName\fR is not set.
.sp
.LP
The \fBmod\fR form of the \fBldapclient\fR utility is used to modify the
configuration of an LDAP client machine that was setup manually. This option
modifies only those LDAP client configuration attributes specified on the
command line. The \fBmod\fR option should only be used on LDAP clients that
were initialized using the \fBmanual\fR option.
.sp
.LP
Regardless of which method is used for initialization, if a client is to be
configured to use a proxy \fBcredentialLevel\fR, proxy credentials must be
provided using \fB-a\fR \fBproxyDN=\fIproxyDN\fR\fR and \fB-a\fR
\fBproxyPassword=\fIproxyPassword\fR\fR options. However, if \fB-a\fR
\fBproxyPassword=\fIproxyPassword\fR\fR is not specified, \fBldapclient\fR will
prompt for it. Note that \fINULL\fR passwords are not allowed in LDAP. If a
self \fBcredentialLevel\fR is configured, \fBauthenticationMethod\fR must be
\fBsasl/GSSAPI\fR.
.sp
.LP
Similarily, if a client is to be configured to enable shadow information update
and use a proxy credentialLevel, administrator credentials must be provided
using \fB-a\fR \fBadminDN=\fR\fIadminDN\fR and \fB-a\fR
\fBadminPassword=\fR\fIadminPassword\fR. However, the shadow information update
does not need the administrator credentials if a self \fBcredentialLevel\fR is
configured.
.sp
.LP
If any file is modified during installation, it will be backed up to
\fB/var/ldap/restore\fR. The files that are typically modified during
initialization are:
.RS +4
.TP
.ie t \(bu
.el o
\fB/etc/nsswitch.conf\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/etc/defaultdomain\fR (if it exists)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/yp/binding/`domainname`\fR (for a NIS(YP) client)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/nis/NIS_COLD_START\fR (for a NIS+ client)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/ldap/ldap_client_file\fR (for an existing LDAP client)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/ldap/ldap_client_cred\fR (for an existing LDAP client)
.RE
.sp
.LP
\fBldapclient\fR does not set up a client to resolve hostnames using DNS. It
simply copies \fB/etc/nsswitch.ldap\fR to \fB/etc/nsswitch.conf\fR. If you
prefer to use DNS for host resolution, please refer to the DNS documentation
for information on setting up DNS. See \fBresolv.conf\fR(4). If you want to use
\fBsasl/GSSAPI\fR as the authentication method, you have to use DNS for
\fBhosts\fR and \fBipnodes\fR resolution.
.sp
.LP
The \fBlist\fR form of the \fBldapclient\fR utility is used to list the LDAP
client configuration. The output will be human readable. LDAP configuration
files are not guaranteed to be human readable. Note that for security reason,
the values for adminDN and adminPassword will not be displayed.
.sp
.LP
The \fBuninit\fR form of the \fBldapclient\fR utility is used to uninitialize
the network service environment, restoring it to the state it was in prior to
the last execution of \fBldapclient\fR using \fBinit\fR or \fBmanual\fR. The
restoration will succeed only if the machine was initialized with the
\fBinit\fR or \fBmanual\fR form of \fBldapclient\fR, as it uses the backup
files created by these options.
.sp
.LP
The \fBgenprofile\fR option is used to write an LDIF formatted configuration
profile based on the attributes specified on the command line to standard
output. This profile can then be loaded into an LDAP server to be used as the
client profile, which can be downloaded by means of the \fBldapclient init\fR
command. Loading the LDIF formatted profile to the directory server can be done
through \fBldapadd\fR(1), or through any server specific import tool. Note that
the attributes \fBproxyDN\fR, \fBproxyPassword\fR, \fBcertificatePath\fR,
\fBdomainName\fR, \fBenableShadowUpdate\fR, \fBadminDN\fR, and
\fBadminPassword\fR are not part of the configuration profile and thus are not
permitted.
.sp
.LP
You must have superuser privileges to run the \fBldapclient\fR command, except
with the \fBgenprofile\fR option.
.sp
.LP
To access the information stored in the directory, clients can either
authenticate to the directory, or use an unauthenticated connection. The LDAP
client is configured to have a credential level of either \fBanonymous\fR or
\fBproxy\fR. In the first case, the client does not authenticate to the
directory. In the second case, client authenticates to the directory using a
proxy identity for read access, and using a administrator identity for write
access if \fBenableShadowUpdate\fR is configured. In the third case, client
authenticates to the directory using a Kerberos principal that is mapped to an
LDAP identity by the LDAP server. Refer to the chapter on implementing security
in the \fISystem Administration Guide: Naming and Directory Services (DNS, NIS,
and LDAP)\fR or your appropriate directory server documentation for identity
mapping details.
.sp
.LP
If a client is configured to use an identity, you can configure which
authentication method the client will use. The LDAP client supports the
following authentication methods:
.br
.in +2
\fBnone\fR
.in -2
.br
.in +2
\fBsimple\fR
.in -2
.br
.in +2
\fBsasl/CRAM-MD5\fR
.in -2
.br
.in +2
\fBsasl/DIGEST-MD5\fR
.in -2
.br
.in +2
\fBsasl/GSSAPI\fR
.in -2
.br
.in +2
\fBtls:none\fR
.in -2
.br
.in +2
\fBtls:simple\fR
.in -2
.br
.in +2
\fBtls:sasl/CRAM-MD5\fR
.in -2
.br
.in +2
\fBtls:sasl/DIGEST-MD5\fR
.in -2
.sp
.LP
Note that some directory servers may not support all of these authentication
methods. For \fBsimple\fR, be aware that the bind password will be sent in the
clear to the LDAP server. For those authentication methods using TLS (transport
layer security), the entire session is encrypted. You will need to install the
appropriate certificate databases to use TLS. Note that the \fBtls:none\fR
authentication method requires a \fBcredentialLevel\fR of \fBproxy\fR to
take effect.
.SS "Commands"
.sp
.LP
The following commands are supported:
.sp
.ne 2
.na
\fB\fBinit\fR\fR
.ad
.sp .6
.RS 4n
Initialize client from a profile on a server.
.RE

.sp
.ne 2
.na
\fB\fBmanual\fR\fR
.ad
.sp .6
.RS 4n
Manually initialize client with the specified attribute values.
.RE

.sp
.ne 2
.na
\fB\fBmod\fR\fR
.ad
.sp .6
.RS 4n
Modify attribute values in the configuration file after a manual initialization
of the client.
.RE

.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.sp .6
.RS 4n
Write the contents of the LDAP client cache to standard output in human
readable form.
.RE

.sp
.ne 2
.na
\fB\fBuninit\fR\fR
.ad
.sp .6
.RS 4n
Uninitialize an LDAP client, assuming that \fBldapclient\fR was used to
initialize the client.
.RE

.sp
.ne 2
.na
\fB\fBgenprofile\fR\fR
.ad
.sp .6
.RS 4n
Generate a configuration profile in LDIF format that can then be stored in the
directory for clients to use, with the \fBinit\fR form of this command.
.RE

.SS "Attributes"
.sp
.LP
The following attributes are supported:
.sp
.ne 2
.na
\fB\fBadminDN\fR\fR
.ad
.sp .6
.RS 4n
Specify the Bind Distinguished Name for the administrator identity that is used
for shadow information update. This option is required if the credential level
is \fBproxy\fR, and \fBenableShadowUpdate\fR is set to \fBtrue\fR. There is no
default value.
.RE

.sp
.ne 2
.na
\fB\fBadminPassword\fR\fR
.ad
.sp .6
.RS 4n
Specify the administrator password. This option is required if the credential
level is \fBproxy\fR, and \fBenableShadowUpdate\fR is set to \fBtrue\fR. There
is no default value.
.RE

.sp
.ne 2
.na
\fB\fBattributeMap\fR\fR
.ad
.sp .6
.RS 4n
Specify a mapping from an attribute defined by a service to an attribute in an
alternative schema. This can be used to change the default schema used for a
given service. The syntax of \fBattributeMap\fR is defined in the profile IETF
draft. This option can be specified multiple times. The default value for all
services is \fINULL\fR. In the example,
.sp
.in +2
.nf
attributeMap: passwd:uid=employeeNumber
.fi
.in -2
.sp

the LDAP client would use the LDAP attribute \fBemployeeNumber\fR rather than
\fBuid\fR for the \fBpasswd\fR service. This is a multivalued attribute.
.sp
To use rfc2307bis style groups (with a DN rather than username as the
attribute value), map the \fBmemberUid\fR attribute to the group attribute
being used (typically either \fBuniqueMember\fR or \fBmember\fR), for example:
.sp
.in +2
.nf
attributeMap: group:memberUid=uniqueMember
.fi
.in -2
.sp

Group membership in a given directory is expected to be maintained with
either username format member attributes, or DN format member attributes. If
both are present they must describe identical memberships or unexpected
results may be obtained. For DN format attributes, the username is required
to be the RDN of the entry. Note that nested groups are not currently
supported, and unexpected results may be obtained if they are used.

.RE

.sp
.ne 2
.na
\fB\fBauthenticationMethod\fR\fR
.ad
.sp .6
.RS 4n
Specify the default authentication method used by all services unless
overridden by the \fBserviceAuthenticationMethod\fR attribute. Multiple values
can be specified by using a semicolon-separated list. The default value is
\fBnone\fR. For those services that use \fBcredentialLevel\fR and
\fBcredentialLevel\fR is \fBanonymous\fR, this attribute is ignored. Services
such as \fBpam_ldap\fR will use this attribute, even if \fBcredentialLevel\fR
is anonymous. The supported authentication methods are described above. If the
authenticationMethod is \fBsasl/GSSAPI\fR, the \fBhosts\fR and \fBipnodes\fR of
\fB/etc/nsswitch.conf\fR must be configured with DNS support, for example:
.sp
.in +2
.nf
hosts: dns files
ipnodes: dns files
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fBbindTimeLimit\fR\fR
.ad
.sp .6
.RS 4n
The maximum time in seconds that a client should spend performing a bind
operation. Set this to a positive integer. The default value is 30.
.RE

.sp
.ne 2
.na
\fB\fBcertificatePath\fR\fR
.ad
.sp .6
.RS 4n
The certificate path for the location of the certificate database. The value is
the path where security database files reside. This is used for TLS support,
which is specified in the \fBauthenticationMethod\fR and
\fBserviceAuthenticationMethod\fR attributes. The default is \fB/var/ldap\fR.
.RE

.sp
.ne 2
.na
\fB\fBcredentialLevel\fR\fR
.ad
.sp .6
.RS 4n
Specify the credential level the client should use to contact the directory.
The credential levels supported are either \fBanonymous\fR or \fBproxy\fR. If a
\fBproxy\fR credential level is specified, then the \fBauthenticationMethod\fR
attribute must be specified to determine the authentication mechanism. Also, if
the credential level is \fBproxy\fR and at least one of the authentication
methods require a bind DN, the \fBproxyDN\fR and \fBproxyPassword\fR attribute
values must be set. In addition, if \fBenableShadowUpdate\fR is set to
\fBtrue\fR, the \fBadminDN\fR and \fBadminPassword\fR values must be set. If a
self credential level is specified, the \fBauthenticationMethod\fR must be
\fBsasl/GSSAPI\fR.
.RE

.sp
.ne 2
.na
\fB\fBdefaultSearchBase\fR\fR
.ad
.sp .6
.RS 4n
Specify the default search base DN. There is no default. The
\fBserviceSearchDescriptor\fR attribute can be used to override the
\fBdefaultSearchBase\fR for given services.
.RE

.sp
.ne 2
.na
\fB\fBdefaultSearchScope=one | sub\fR\fR
.ad
.sp .6
.RS 4n
Specify the default search scope for the client's search operations. This
default can be overridden for a given service by specifying a
\fBserviceSearchDescriptor\fR. The default is one level search.
.RE

.sp
.ne 2
.na
\fB\fBdefaultServerList\fR\fR
.ad
.sp .6
.RS 4n
A space separated list of server names or server addresses, either IPv4 or
IPv6. If you specify server names, be sure that the LDAP client can resolve the
name without the LDAP name service. You must resolve the LDAP servers' names by
using either \fBfiles\fR or \fBdns\fR. If the LDAP server name cannot be
resolved, your naming service will fail.
.sp
The port number is optional. If not specified, the default LDAP server port
number 389 is used, except when TLS is specified in the authentication method.
In this case, the default LDAP server port number is 636.
.sp
The format to specify the port number for an IPv6 address is:
.sp
.in +2
.nf
[ipv6_addr]:port
.fi
.in -2

To specify the port number for an IPv4 address, use the following format:
.sp
.in +2
.nf
ipv4_addr:port
.fi
.in -2

If the host name is specified, use the format:
.sp
.in +2
.nf
host_name:port
.fi
.in -2

If you use TLS, the LDAP server's hostname must match the hostname in the TLS
certificate. Typically, the hostname in the TLS certificate is a fully
qualified domain name. With TLS, the LDAP server host addresses must resolve to
the hostnames in the TLS certificate. You must use \fBfiles\fR or \fBdns\fR to
resolve the host address.
.RE

.sp
.ne 2
.na
\fB\fBdomainName\fR\fR
.ad
.sp .6
.RS 4n
Specify the DNS domain name. This becomes the default domain for the machine.
The default is the current domain name. This attribute is only used in client
initialization.
.RE

.sp
.ne 2
.na
\fB\fBenableShadowUpdate=true | false\fR\fR
.ad
.sp .6
.RS 4n
Specify whether the client is allowed to update shadow information. If set to
\fBtrue\fR and the credential level is \fBproxy\fR, \fBadminDN\fR and
\fBadminPassword\fR must be specified.
.RE

.sp
.ne 2
.na
\fB\fBfollowReferrals=true | false\fR\fR
.ad
.sp .6
.RS 4n
Specify the referral setting. A setting of true implies that referrals will be
automatically followed and false would result in referrals not being followed.
The default is true.
.RE

.sp
.ne 2
.na
\fB\fBobjectclassMap\fR\fR
.ad
.sp .6
.RS 4n
Specify a mapping from an \fBobjectclass\fR defined by a service to an
\fBobjectclass\fR in an alternative schema. This can be used to change the
default schema used for a given service. The syntax of \fBobjectclassMap\fR is
defined in the profile IETF draft. This option can be specified multiple times.
The default value for all services is \fINULL\fR. In the example,
.sp
.in +2
.nf
objectclassMap=passwd:posixAccount=unixAccount
.fi
.in -2
.sp

the LDAP client would use the LDAP \fBobjectclass\fR of \fBunixAccount\fR
rather than the \fBposixAccount\fR for the \fBpasswd\fR service. This is a
multivalued attribute.
.RE

.sp
.ne 2
.na
\fB\fBpreferredServerList\fR\fR
.ad
.sp .6
.RS 4n
Specify the space separated list of server names or server addresses, either
IPv4 or IPv6, to be contacted before servers specified by the
\fBdefaultServerList\fR attribute. If you specify server names, be sure that
the LDAP client can resolve the name without the LDAP name service. You must
resolve the LDAP servers' names by using either \fBfiles\fR or \fBdns\fR. If
the LDAP server name cannot be resolved, your naming service will fail.
.sp
The port number is optional. If not specified, the default LDAP server port
number 389 is used, except when TLS is specified in the authentication method.
In this case, the default LDAP server port number is 636.
.sp
The format to specify the port number for an IPv6 address is:
.sp
.in +2
.nf
[ipv6_addr]:port
.fi
.in -2

To specify the port number for an IPv4 address, use the following format:
.sp
.in +2
.nf
ipv4_addr:port
.fi
.in -2

If the host name is specified, use the format:
.sp
.in +2
.nf
host_name:port
.fi
.in -2

If you use TLS, the LDAP server's hostname must match the hostname in the TLS
certificate. Typically, the hostname in the TLS certificate is a fully
qualified domain name. With TLS, the LDAP server host addresses must resolve to
the hostnames in the TLS certificate. You must use \fBfiles\fR or \fBdns\fR to
resolve the host address.
.RE

.sp
.ne 2
.na
\fB\fBprofileName\fR\fR
.ad
.sp .6
.RS 4n
Specify the profile name. For \fBldapclient init\fR, this attribute is the name
of an existing profile which may be downloaded periodically depending on the
value of the \fBprofileTTL\fR attribute. For \fBldapclient genprofile\fR, this
is the name of the profile to be generated. The default value is \fBdefault\fR.
.RE

.sp
.ne 2
.na
\fB\fBprofileTTL\fR\fR
.ad
.sp .6
.RS 4n
Specify the TTL value in seconds for the client information. This is only
relevant if the machine was initialized with a client profile. If you do not
want \fBldap_cachemgr\fR(1M) to attempt to refresh the LDAP client
configuration from the LDAP server, set \fBprofileTTL\fR to 0 (zero). Valid
values are either zero 0 (for no expiration) or a positive integer in seconds.
The default value is 12 hours.
.RE

.sp
.ne 2
.na
\fB\fBproxyDN\fR\fR
.ad
.sp .6
.RS 4n
Specify the Bind Distinguished Name for the proxy identity. This option is
required if the credential level is \fBproxy\fR, and at least one of the
authentication methods requires a bind DN. There is no default value.
.RE

.sp
.ne 2
.na
\fB\fBproxyPassword\fR\fR
.ad
.sp .6
.RS 4n
Specify client proxy password. This option is required if the credential level
is \fBproxy\fR, and at least one of the authentication methods requires a bind
DN. There is no default.
.RE

.sp
.ne 2
.na
\fB\fBsearchTimeLimit\fR\fR
.ad
.sp .6
.RS 4n
Specify maximum number of seconds allowed for an LDAP search operation. The
default is 30 seconds. The server may have its own search time limit.
.RE

.sp
.ne 2
.na
\fB\fBserviceAuthenticationMethod\fR\fR
.ad
.sp .6
.RS 4n
Specify authentication methods to be used by a service in the form
\fIservicename\fR:\fBauthenticationmethod\fR, for example:
.sp
.in +2
.nf
pam_ldap:tls:simple
.fi
.in -2

For multiple authentication methods, use a semicolon-separated list. The
default value is no service authentication methods, in which case, each service
would default to the \fBauthenticationMethod\fR value. The supported
authentications are described above.
.sp
Three services support this feature: \fBpasswd-cmd\fR, \fBkeyserv\fR, and
\fBpam_ldap\fR. The \fBpasswd-cmd\fR service is used to define the
authentication method to be used by \fBpasswd\fR(1) to change the user's
password and other attributes. The \fBkeyserv\fR service is used to identify
the authentication method to be used by the \fBchkey\fR(1) and \fBnewkey\fR(1M)
utilities. The \fBpam_ldap\fR service defines the authentication method to be
used for authenticating users when \fBpam_ldap\fR(5) is configured. If this
attribute is not set for any of these services, the \fBauthenticationMethod\fR
attribute is used to define the authentication method. This is a multivalued
attribute.
.RE

.sp
.ne 2
.na
\fB\fBserviceCredentialLevel\fR\fR
.ad
.sp .6
.RS 4n
Specify credential level to be used by a service. Multiple values can be
specified in a space-separated list. The default value for all services is
\fINULL\fR. The supported credential levels are: \fBanonymous\fR or
\fBproxy\fR. At present, no service uses this attribute. This is a multivalued
attribute.
.RE

.sp
.ne 2
.na
\fB\fBserviceSearchDescriptor\fR\fR
.ad
.sp .6
.RS 4n
Override the default base DN for LDAP searches for a given service. The format
of the descriptors also allow overriding the default search scope and search
filter for each service. The syntax of \fBserviceSearchDescriptor\fR is defined
in the profile IETF draft. The default value for all services is \fINULL\fR.
This is a multivalued attribute. In the example,
.sp
.in +2
.nf
serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one
.fi
.in -2
.sp

the LDAP client would do a one level search in
\fBou=people,dc=a1,dc=acme,dc=com\fR rather than
\fBou=people,\fIdefaultSearchBase\fR\fR for the \fBpasswd\fR service.
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR \fBattrName=\fR\fIattrValue\fR\fR
.ad
.sp .6
.RS 4n
Specify \fBattrName\fR and its value. See \fBSYNOPSIS\fR for a complete list of
possible attribute names and values.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR \fIbindDN\fR\fR
.ad
.sp .6
.RS 4n
Specifies an entry that has read permission for the requested database.
.RE

.sp
.ne 2
.na
\fB\fB-j\fR \fIpasswdFile\fR\fR
.ad
.sp .6
.RS 4n
Specify a file containing the password for the bind DN or the password for the
SSL client's key database. To protect the password, use this option in scripts
and place the password in a secure file. This option is mutually exclusive of
the \fB-w\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.sp .6
.RS 4n
Quiet mode. No output is generated.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Verbose output.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR \fIbindPassword\fR\fR
.ad
.sp .6
.RS 4n
Password to be used for authenticating the bind DN. If this parameter is
missing, the command will prompt for a password. \fBNULL\fR passwords are not
supported in LDAP.
.sp
When you use \fB-w\fR \fIbindPassword\fR to specify the password to be used for
authentication, the password is visible to other users of the system by means
of the \fBps\fR command, in script files, or in shell history.
.sp
If you supply "\fB-\fR" (hyphen) as a password, the command will prompt for a
password.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR \fIpasswdFile\fR\fR
.ad
.sp .6
.RS 4n
Specify a file containing the password for the proxy DN. To protect the
password, use this option in scripts and place the password in a secure file.
This option is mutually exclusive of the \fB-a\fR \fIproxyPassword\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR \fIadminrPasswdFile\fR\fR
.ad
.sp .6
.RS 4n
Specify a file containing the password for the \fBadminDN\fR. To protect the
password, use this option in scripts and place the password in a secure file.
This option is mutually exclusive of the \fB-a\fR \fIadminPassword\fR option.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fILDAP_server\fR\fR
.ad
.sp .6
.RS 4n
An address or a name for the LDAP server from which the profile will be loaded.
The current naming service specified in the \fBnsswitch.conf\fR file is used.
Once the profile is loaded, the \fBpreferredServerList\fR and
\fBdefaultServerList\fR specified in the profile are used.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSetting Up a Client By Using the Default Profile Stored on a
Specified LDAP Server
.sp
.LP
The following example shows how to set up a client using the default profile
stored on the specified LDAP server. This command will only be successful if
either the credential level in the profile is set to \fBanonymous\fR or the
authentication method is set to \fBnone\fR.

.sp
.in +2
.nf
example# \fBldapclient init 172.16.100.1\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSetting Up a Client By Using the \fBsimple\fR Profile Stored on
a Specified LDAP Server
.sp
.LP
The following example shows how to set up a client using the \fBsimple\fR
profile stored on the specified LDAP server. The domainname is set to
\fBxyz.mycompany.com\fR and the proxyPassword is \fBsecret\fR.

.sp
.in +2
.nf
example# \fBldapclient init -a profileName=simple \e
-a domainName=xyz.mycompany.com \e
-a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=mycompany,dc=com \e
-a proxyPassword=secret '['fe80::a00:20ff:fea3:388']':386\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRSetting Up a Client Using Only One Server
.sp
.LP
The following example shows how to set up a client using only one server. The
authentication method is set to \fBnone\fR, and the search base is
\fBdc=mycompany,dc=com\fR.

.sp
.in +2
.nf
example# \fBldapclient manual -a authenticationMethod=none \e
-a defaultSearchBase=dc=mycompany,dc=com \e
-a defaultServerList=172.16.100.1\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRSetting Up a Client Using Only One Server That Does Not Follow
Referrals
.sp
.LP
The following example shows how to set up a client using only one server. The
credential level is set to \fBproxy\fR. The authentication method of is
\fBsasl/CRAM-MD5\fR, with the option not to follow referrals. The domain name
is \fBxyz.mycompany.com\fR, and the LDAP server is running on port number 386
at IP address \fB172.16.100.1\fR.

.sp
.in +2
.nf
example# \fBldapclient manual \e
-a credentialLevel=proxy \e
-a authenticationMethod=sasl/CRAM-MD5 \e
-a proxyPassword=secret \e
-a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=mycompany,dc=com \e
-a defaultSearchBase=dc=xyz,dc=mycompany,dc=com \e
-a domainName=xyz.mycompany.com \e
-a followReferrals=false \e
-a defaultServerList=172.16.100.1:386\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRUsing \fBgenprofile\fR to Set Only the \fBdefaultSearchBase\fR
and the Server Addresses
.sp
.LP
The following example shows how to use the \fBgenprofile\fR command to set the
\fBdefaultSearchBase\fR and the server addresses.

.sp
.in +2
.nf
example# \fBldapclient genprofile -a profileName=myprofile \e
-a defaultSearchBase=dc=eng,dc=sun,dc=com \e
-a "defaultServerList=172.16.100.1 172.16.234.15:386" \e
> myprofile.ldif\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRCreating a Profile on IPv6 servers
.sp
.LP
The following example creates a profile on IPv6 servers

.sp
.in +2
.nf
example# \fBldapclient genprofile -a profileName=eng \e
-a credentialLevel=proxy \e
-a authenticationMethod=sasl/DIGEST-MD5 \e
-a defaultSearchBase=dc=eng,dc=acme,dc=com \e
-a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one"\e
-a preferredServerList= '['fe80::a00:20ff:fea3:388']' \e
-a "defaultServerList='['fec0::111:a00:20ff:fea3:edcf']' \e
    '['fec0::111:a00:20ff:feb5:e41']'" > eng.ldif\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRCreating a Profile That Overrides Every Default Value
.sp
.LP
The following example shows a profile that overrides every default value.

.sp
.in +2
.nf
example# \fBldapclient genprofile -a profileName=eng \e
-a credentialLevel=proxy -a authenticationMethod=sasl/DIGEST-MD5 \e
-a bindTimeLimit=20 \e
-a defaultSearchBase=dc=eng,dc=acme,dc=com \e
-a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,dc=com?one"\e
-a serviceAuthenticationMethod=pam_ldap:tls:simple \e
-a defaultSearchScope=sub \e
-a attributeMap=passwd:uid=employeeNumber \e
-a objectclassMap=passwd:posixAccount=unixAccount \e
-a followReferrals=false -a profileTTL=6000 \e
-a preferredServerList=172.16.100.30 -a searchTimeLimit=30 \e
-a "defaultServerList=172.16.200.1 172.16.100.1 192.168.5.6" > eng.ldif\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB0\fR
.ad
.RS 5n
The command successfully executed.
.RE

.sp
.ne 2
.na
\fB1\fR
.ad
.RS 5n
An error occurred. An error message is output.
.RE

.sp
.ne 2
.na
\fB2\fR
.ad
.RS 5n
\fBproxyDN\fR and \fBproxyPassword\fR attributes are required, but they are not
provided.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/var/ldap/ldap_client_cred\fR\fR
.ad
.br
.na
\fB\fB/var/ldap/ldap_client_file\fR\fR
.ad
.sp .6
.RS 4n
Contain the LDAP configuration of the client. These files are not to be
modified manually. Their content is not guaranteed to be human readable. Use
\fBldapclient\fR to update them.
.RE

.sp
.ne 2
.na
\fB\fB/etc/defaultdomain\fR\fR
.ad
.sp .6
.RS 4n
System default domain name, matching the domain name of the data in the LDAP
servers. See \fBdefaultdomain\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.sp .6
.RS 4n
Configuration file for the name-service switch. See \fBnsswitch.conf\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.ldap\fR\fR
.ad
.sp .6
.RS 4n
Sample configuration file for the name-service switch configured with LDAP and
files.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBchkey\fR(1), \fBldap\fR(1), \fBldapadd\fR(1), \fBldapdelete\fR(1),
\fBldaplist\fR(1), \fBldapmodify\fR(1), \fBldapmodrdn\fR(1),
\fBldapsearch\fR(1), \fBidsconfig\fR(1M), \fBldapaddent\fR(1M),
\fBldap_cachemgr\fR(1M), \fBsuninstall\fR(1M), \fBdefaultdomain\fR(4),
\fBnsswitch.conf\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5)
.SH CAUTION
.sp
.LP
Currently \fBStartTLS\fR is not supported by \fBlibldap.so.5\fR, therefore the
port number provided refers to the port used during a TLS open, rather than the
port used as part of a \fBStartTLS\fR sequence. To avoid timeout delays, mixed
use of TLS and non-TLS authentication mechanisms is not recommended.
.sp
.LP
For example:
.sp
.in +2
.nf
-h foo:1000 -a authenticationMethod=tls:simple
.fi
.in -2
.sp

.sp
.LP
\&...or:
.sp
.in +2
.nf
defaultServerList= foo:1000
authenticationMethod= tls:simple
.fi
.in -2
.sp

.sp
.LP
The preceding refers to a raw TLS open on host \fBfoo\fR port 1000, not an
open, StartTLS sequence on an unsecured port 1000. If port 1000 is unsecured
the connection will not be made.
.sp
.LP
As a second example, the following will incur a significant timeout delay while
attempting the connection to \fBfoo:636\fR with an unsecured bind.
.sp
.in +2
.nf
defaultServerList= foo:636 foo:389
authenticationMethod= simple
.fi
.in -2
.sp