LDAPCLIENT(8) Maintenance Commands and Procedures LDAPCLIENT(8)

NAME

ldapclient - initialize LDAP client machine or output an LDAP client
profile in LDIF format

SYNOPSIS

/usr/sbin/ldapclient [-v | -q] init [-a profileName=profileName]
[-a domainName=domain] [-a proxyDN=proxyDN]
[-a proxyPassword=password]
[-a authenticationMethod=authenticationMethod]
[-a enableShadowUpdate=true | false]
[-a adminDN=adminDN]
[-a adminPassword=adminPassword]
[-a certificatePath=path] [-d bindDN] [-w bindPassword]
[-j passwdFile] [-y passwdFile]
[-z adminrPasswdFile] LDAP_server[:port_number]


/usr/sbin/ldapclient [-v | -q] manual [-a attrName=attrVal]


/usr/sbin/ldapclient [-v | -q] mod [-a attrName=attrVal]


/usr/sbin/ldapclient [-v | -q] list


/usr/sbin/ldapclient [-v | -q] uninit


/usr/sbin/ldapclient [-v | -q] genprofile -a profileName=profileName
[-a attrName=attrVal]

DESCRIPTION

The ldapclient utility can be used to:

o initialize LDAP client machines

o restore the network service environment on LDAP clients

o list the contents of the LDAP client cache in human
readable format.


The init form of the ldapclient utility is used to initialize an LDAP
client machine, using a profile stored on an LDAP server specified by
LDAP_server. 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
ldap_cachemgr(8) 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 A Configuration
Schema for LDAP Based Directory User Agents.


The manual form of the ldapclient 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 defaultServerList or the preferredServerList attributes.The
domainName attribute must be specified if the client's domainName is
not set.


The mod form of the ldapclient 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 mod option should only be used on
LDAP clients that were initialized using the manual option.


Regardless of which method is used for initialization, if a client is
to be configured to use a proxy credentialLevel, proxy credentials
must be provided using -a proxyDN=proxyDN and -a
proxyPassword=proxyPassword options. However, if -a
proxyPassword=proxyPassword is not specified, ldapclient will prompt
for it. Note that NULL passwords are not allowed in LDAP. If a self
credentialLevel is configured, authenticationMethod must be
sasl/GSSAPI.


Similarly, if a client is to be configured to enable shadow
information update and use a proxy credentialLevel, administrator
credentials must be provided using -a adminDN=adminDN and -a
adminPassword=adminPassword. However, the shadow information update
does not need the administrator credentials if a self credentialLevel
is configured.


If any file is modified during installation, it will be backed up to
/var/ldap/restore. The files that are typically modified during
initialization are:

o /etc/nsswitch.conf

o /etc/defaultdomain (if it exists)

o /var/yp/binding/`domainname` (for a NIS(YP) client)

o /var/ldap/ldap_client_file (for an existing LDAP client)

o /var/ldap/ldap_client_cred (for an existing LDAP client)


ldapclient does not set up a client to resolve hostnames using DNS.
It simply copies /etc/nsswitch.ldap to /etc/nsswitch.conf. If you
prefer to use DNS for host resolution, please refer to the DNS
documentation for information on setting up DNS. See resolv.conf(5).
If you want to use sasl/GSSAPI as the authentication method, you have
to use DNS for hosts and ipnodes resolution.


The list form of the ldapclient 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.


The uninit form of the ldapclient utility is used to uninitialize the
network service environment, restoring it to the state it was in
prior to the last execution of ldapclient using init or manual. The
restoration will succeed only if the machine was initialized with the
init or manual form of ldapclient, as it uses the backup files
created by these options.


The genprofile 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 ldapclient init command. Loading the LDIF
formatted profile to the directory server can be done through
ldapadd(1), or through any server specific import tool. Note that the
attributes proxyDN, proxyPassword, certificatePath, domainName,
enableShadowUpdate, adminDN, and adminPassword are not part of the
configuration profile and thus are not permitted.


You must have superuser privileges to run the ldapclient command,
except with the genprofile option.


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
anonymous or proxy. 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
enableShadowUpdate 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 System Administration Guide: Naming
and Directory Services (DNS, NIS, and LDAP) or your appropriate
directory server documentation for identity mapping details.


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:
none
simple
sasl/CRAM-MD5
sasl/DIGEST-MD5
sasl/GSSAPI
tls:none
tls:simple
tls:sasl/CRAM-MD5
tls:sasl/DIGEST-MD5


Note that some directory servers may not support all of these
authentication methods. For simple, 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 tls:none
authentication method requires a credentialLevel of proxy to take
effect.

Commands

The following commands are supported:

init

Initialize client from a profile on a server.


manual

Manually initialize client with the specified attribute values.


mod

Modify attribute values in the configuration file after a manual
initialization of the client.


list

Write the contents of the LDAP client cache to standard output in
human readable form.


uninit

Uninitialize an LDAP client, assuming that ldapclient was used to
initialize the client.


genprofile

Generate a configuration profile in LDIF format that can then be
stored in the directory for clients to use, with the init form of
this command.

Attributes

The following attributes are supported:

adminDN

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 proxy, and
enableShadowUpdate is set to true. There is no default value.


adminPassword

Specify the administrator password. This option is required if
the credential level is proxy, and enableShadowUpdate is set to
true. There is no default value.


attributeMap

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
attributeMap is defined in the profile IETF draft. This option
can be specified multiple times. The default value for all
services is NULL. In the example,

attributeMap: passwd:uid=employeeNumber


the LDAP client would use the LDAP attribute employeeNumber
rather than uid for the passwd service. This is a multivalued
attribute.

To use rfc2307bis style groups (with a DN rather than username as
the attribute value), map the memberUid attribute to the group
attribute being used (typically either uniqueMember or member),
for example:

attributeMap: group:memberUid=uniqueMember


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.


authenticationMethod

Specify the default authentication method used by all services
unless overridden by the serviceAuthenticationMethod attribute.
Multiple values can be specified by using a semicolon-separated
list. The default value is none. For those services that use
credentialLevel and credentialLevel is anonymous, this attribute
is ignored. Services such as pam_ldap will use this attribute,
even if credentialLevel is anonymous. The supported
authentication methods are described above. If the
authenticationMethod is sasl/GSSAPI, the hosts and ipnodes of
/etc/nsswitch.conf must be configured with DNS support, for
example:

hosts: dns files
ipnodes: dns files


bindTimeLimit

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.


certificatePath

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
authenticationMethod and serviceAuthenticationMethod attributes.
The default is /var/ldap.


credentialLevel

Specify the credential level the client should use to contact the
directory. The credential levels supported are either anonymous
or proxy. If a proxy credential level is specified, then the
authenticationMethod attribute must be specified to determine the
authentication mechanism. Also, if the credential level is proxy
and at least one of the authentication methods require a bind DN,
the proxyDN and proxyPassword attribute values must be set. In
addition, if enableShadowUpdate is set to true, the adminDN and
adminPassword values must be set. If a self credential level is
specified, the authenticationMethod must be sasl/GSSAPI.


defaultSearchBase

Specify the default search base DN. There is no default. The
serviceSearchDescriptor attribute can be used to override the
defaultSearchBase for given services.


defaultSearchScope=one | sub

Specify the default search scope for the client's search
operations. This default can be overridden for a given service by
specifying a serviceSearchDescriptor. The default is one level
search.


defaultServerList

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
files or dns. If the LDAP server name cannot be resolved, your
naming service will fail.

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.

The format to specify the port number for an IPv6 address is:

[ipv6_addr]:port

To specify the port number for an IPv4 address, use the following
format:

ipv4_addr:port

If the host name is specified, use the format:

host_name:port

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 files or dns to resolve the host
address.


domainName

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.


enableShadowUpdate=true | false

Specify whether the client is allowed to update shadow
information. If set to true and the credential level is proxy,
adminDN and adminPassword must be specified.


followReferrals=true | false

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.


objectclassMap

Specify a mapping from an objectclass defined by a service to an
objectclass in an alternative schema. This can be used to change
the default schema used for a given service. The syntax of
objectclassMap is defined in the profile IETF draft. This option
can be specified multiple times. The default value for all
services is NULL. In the example,

objectclassMap=passwd:posixAccount=unixAccount


the LDAP client would use the LDAP objectclass of unixAccount
rather than the posixAccount for the passwd service. This is a
multivalued attribute.


preferredServerList

Specify the space separated list of server names or server
addresses, either IPv4 or IPv6, to be contacted before servers
specified by the defaultServerList 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 files or dns. If the LDAP server name
cannot be resolved, your naming service will fail.

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.

The format to specify the port number for an IPv6 address is:

[ipv6_addr]:port

To specify the port number for an IPv4 address, use the following
format:

ipv4_addr:port

If the host name is specified, use the format:

host_name:port

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 files or dns to resolve the host
address.


profileName

Specify the profile name. For ldapclient init, this attribute is
the name of an existing profile which may be downloaded
periodically depending on the value of the profileTTL attribute.
For ldapclient genprofile, this is the name of the profile to be
generated. The default value is default.


profileTTL

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 ldap_cachemgr(8) to attempt to
refresh the LDAP client configuration from the LDAP server, set
profileTTL to 0 (zero). Valid values are either zero 0 (for no
expiration) or a positive integer in seconds. The default value
is 12 hours.


proxyDN

Specify the Bind Distinguished Name for the proxy identity. This
option is required if the credential level is proxy, and at least
one of the authentication methods requires a bind DN. There is no
default value.


proxyPassword

Specify client proxy password. This option is required if the
credential level is proxy, and at least one of the authentication
methods requires a bind DN. There is no default.


searchTimeLimit

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.


serviceAuthenticationMethod

Specify authentication methods to be used by a service in the
form servicename:authenticationmethod, for example:

pam_ldap:tls:simple

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
authenticationMethod value. The supported authentications are
described above.

Three services support this feature: passwd-cmd, keyserv, and
pam_ldap. The passwd-cmd service is used to define the
authentication method to be used by passwd(1) to change the
user's password and other attributes. The keyserv service is used
to identify the authentication method to be used by the chkey(1)
and newkey(8) utilities. The pam_ldap service defines the
authentication method to be used for authenticating users when
pam_ldap(7) is configured. If this attribute is not set for any
of these services, the authenticationMethod attribute is used to
define the authentication method. This is a multivalued
attribute.


serviceCredentialLevel

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 NULL. The supported credential levels are:
anonymous or proxy. At present, no service uses this attribute.
This is a multivalued attribute.


serviceSearchDescriptor

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 serviceSearchDescriptor is defined in the profile IETF
draft. The default value for all services is NULL. This is a
multivalued attribute. In the example,

serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=example,dc=com?one


the LDAP client would do a one level search in
ou=people,dc=a1,dc=example,dc=com rather than
ou=people,defaultSearchBase for the passwd service.

OPTIONS

The following options are supported:

-a attrName=attrValue

Specify attrName and its value. See SYNOPSIS for a complete list
of possible attribute names and values.


-D bindDN

Specifies an entry that has read permission for the requested
database.


-j passwdFile

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 -w option.


-q

Quiet mode. No output is generated.


-v

Verbose output.


-w bindPassword

Password to be used for authenticating the bind DN. If this
parameter is missing, the command will prompt for a password.
NULL passwords are not supported in LDAP.

When you use -w bindPassword to specify the password to be used
for authentication, the password is visible to other users of the
system by means of the ps command, in script files, or in shell
history.

If you supply "-" (hyphen) as a password, the command will prompt
for a password.


-y passwdFile

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 -a proxyPassword option.


-z adminrPasswdFile

Specify a file containing the password for the adminDN. To
protect the password, use this option in scripts and place the
password in a secure file. This option is mutually exclusive of
the -a adminPassword option.

OPERANDS

The following operand is supported:

LDAP_server

An address or a name for the LDAP server from which the profile
will be loaded. The current naming service specified in the
nsswitch.conf file is used. Once the profile is loaded, the
preferredServerList and defaultServerList specified in the
profile are used.

EXAMPLES

Example 1: Setting Up a Client By Using the Default Profile Stored on

a Specified LDAP Server


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
anonymous or the authentication method is set to none.


example# ldapclient init 172.16.100.1

Example 2: Setting Up a Client By Using the simple Profile Stored on a

Specified LDAP Server


The following example shows how to set up a client using the simple
profile stored on the specified LDAP server. The domainname is set to
xyz.example.com and the proxyPassword is secret.


example# ldapclient init -a profileName=simple \
-a domainName=xyz.example.com \
-a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=example,dc=com \
-a proxyPassword=secret '['fe80::a00:20ff:fea3:388']':386

Example 3: Setting Up a Client Using Only One Server

The following example shows how to set up a client using only one
server. The authentication method is set to none, and the search base
is dc=example,dc=com.


example# ldapclient manual -a authenticationMethod=none \
-a defaultSearchBase=dc=example,dc=com \
-a defaultServerList=172.16.100.1

Example 4: Setting Up a Client Using Only One Server That Does Not

Follow Referrals


The following example shows how to set up a client using only one
server. The credential level is set to proxy. The authentication
method of is sasl/CRAM-MD5, with the option not to follow referrals.
The domain name is xyz.example.com, and the LDAP server is running on
port number 386 at IP address 172.16.100.1.


example# ldapclient manual \
-a credentialLevel=proxy \
-a authenticationMethod=sasl/CRAM-MD5 \
-a proxyPassword=secret \
-a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=example,dc=com \
-a defaultSearchBase=dc=xyz,dc=example,dc=com \
-a domainName=xyz.example.com \
-a followReferrals=false \
-a defaultServerList=172.16.100.1:386

Example 5: Using genprofile to Set Only the defaultSearchBase and the

Server Addresses


The following example shows how to use the genprofile command to set
the defaultSearchBase and the server addresses.


example# ldapclient genprofile -a profileName=myprofile \
-a defaultSearchBase=dc=eng,dc=sun,dc=com \
-a "defaultServerList=172.16.100.1 172.16.234.15:386" \
> myprofile.ldif

Example 6: Creating a Profile on IPv6 servers

The following example creates a profile on IPv6 servers


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

Example 7: Creating a Profile That Overrides Every Default Value

The following example shows a profile that overrides every default
value.


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

EXIT STATUS

The following exit values are returned:

0
The command successfully executed.


1
An error occurred. An error message is output.


2
proxyDN and proxyPassword attributes are required, but they are
not provided.

FILES

/var/ldap/ldap_client_cred
/var/ldap/ldap_client_file

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 ldapclient to update them.


/etc/defaultdomain

System default domain name, matching the domain name of the data
in the LDAP servers. See defaultdomain(5).


/etc/nsswitch.conf

Configuration file for the name-service switch. See
nsswitch.conf(5).


/etc/nsswitch.ldap

Sample configuration file for the name-service switch configured
with LDAP and files.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+

SEE ALSO

chkey(1), ldap(1), ldapadd(1), ldapdelete(1), ldaplist(1),
ldapmodify(1), ldapmodrdn(1), ldapsearch(1), defaultdomain(5),
nsswitch.conf(5), resolv.conf(5), attributes(7), idsconfig(8),
ldap_cachemgr(8), ldapaddent(8)

CAUTION

Currently StartTLS is not supported by libldap.so.5, therefore the
port number provided refers to the port used during a TLS open,
rather than the port used as part of a StartTLS sequence. To avoid
timeout delays, mixed use of TLS and non-TLS authentication
mechanisms is not recommended.


For example:

-h foo:1000 -a authenticationMethod=tls:simple


...or:

defaultServerList= foo:1000
authenticationMethod= tls:simple


The preceding refers to a raw TLS open on host foo port 1000, not an
open, StartTLS sequence on an unsecured port 1000. If port 1000 is
unsecured the connection will not be made.


As a second example, the following will incur a significant timeout
delay while attempting the connection to foo:636 with an unsecured
bind.

defaultServerList= foo:636 foo:389
authenticationMethod= simple


November 22, 2021 LDAPCLIENT(8)