ldapclient(1M) System Administration Commands ldapclient(1M)NAMEldapclient - 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 certificatePath=path] [-d bindDN] [-w bindPassword]
[-j passwdFile] [-y passwdFile] 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 con‐
figuration profile allows for easy installation of LDAP client and
propagation of configuration changes to LDAP clients. The
ldap_cachemgr(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 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 speci‐
fied 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 configura‐
tion 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.
If any file is modified during installation, it will be backed up to
/var/ldap/restore. The files that are typically modified during ini‐
tialization are:
o /etc/nsswitch.conf
o /etc/defaultdomain (if it exists)
o /var/yp/binding/`domainname` (for a NIS(YP) client)
o /var/nis/NIS_COLD_START (for a NIS+ 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(4). 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.
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 restora‐
tion 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 stan‐
dard 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, and domainName are not part of the configuration pro‐
file 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. In the third case, client authenti‐
cates 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 Sun ONE Directory Server Administration Guide 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:simple
tls:sasl/CRAM-MD5
tls:sasl/DIGEST-MD5
Note that some directory servers may not support all of these authenti‐
cation 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.
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:
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.
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 cre‐
dentialLevel 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 authentication‐
Method 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 authenti‐
cationMethod attribute must be specified to determine the authenti‐
cation mechanism. Further, 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. 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 ser‐
viceSearchDescriptor attribute can be used to override the default‐
SearchBase for given services.
defaultSearchScope=one | sub
Specify the default search scope for the client's search opera‐
tions. This default can be overridden for a given service by speci‐
fying 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 certifi‐
cate is a fully qualified domain name. With TLS, the LDAP server
host addresses must resolve to the hostnames in the TLS certifi‐
cate. 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.
followReferrals=true | false
Specify the referral setting. A setting of true implies that refer‐
rals 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 object‐
classMap 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 mul‐
tivalued 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 certifi‐
cate is a fully qualified domain name. With TLS, the LDAP server
host addresses must resolve to the hostnames in the TLS certifi‐
cate. 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 periodi‐
cally depending on the value of the profileTTL attribute. For ldap‐
client 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 pro‐
file. If you do not want ldap_cachemgr(1M) 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 cre‐
dential 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 opera‐
tion. 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 authentica‐
tion 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(1M)
utilities. The pam_ldap service defines the authentication method
to be used for authenticating users when pam_ldap(5) is configured.
If this attribute is not set for any of these services, the authen‐
ticationMethod 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: anony‐
mous 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 ser‐
viceSearchDescriptor 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=acme,dc=com?one
the LDAP client would do a one level search in ou=peo‐
ple,dc=a1,dc=acme,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 data‐
base.
-j passwdFile
Specify a file containing the password for the bind DN or the pass‐
word 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 parame‐
ter is missing, the command will prompt for a password. NULL pass‐
words 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 sys‐
tem by means of the ps command, in script files, or in shell his‐
tory.
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 proxy‐
Password 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 nss‐
witch.conf file is used. Once the profile is loaded, the preferred‐
ServerList 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.mycompany.com and the proxyPassword is secret.
example# ldapclient init -a profileName=simple \
-a domainName=xyz.mycompany.com \
-a proxyDN=cn=proxyagent,ou=profile,dc=xyz,dc=mycompany,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=mycompany,dc=com.
example# ldapclient manual -a authenticationMethod=none \
-a defaultSearchBase=dc=mycompany,dc=com \
-a defaultServerList=172.16.100.1
Example 4 Setting Up a Client Using Only One Server That Does Not Fol‐
low 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.mycompany.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=mycompany,dc=com \
-a defaultSearchBase=dc=xyz,dc=mycompany,dc=com \
-a domainName=xyz.mycompany.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=acme,dc=com \
-a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,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=acme,dc=com \
-a "serviceSearchDescriptor=passwd:ou=people,dc=a1,dc=acme,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(4).
/etc/nsswitch.conf
Configuration file for the name-service switch. See nss‐
witch.conf(4).
/etc/nsswitch.ldap
Sample configuration file for the name-service switch configured
with LDAP and files.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWnisu │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOchkey(1), ldap(1), ldapadd(1), ldapdelete(1), ldaplist(1), ldapmod‐
ify(1), ldapmodrdn(1), ldapsearch(1), idsconfig(1M), ldapaddent(1M),
ldap_cachemgr(1M), suninstall(1M), defaultdomain(4), nsswitch.conf(4),
resolv.conf(4), attributes(5)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 recom‐
mended.
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
SunOS 5.10 11 Jun 2008 ldapclient(1M)
