System Administration Commands ldapclient(1M)
NAME
ldapclient - initialize LDAP client machine or output an
LDAP client profile in LDIF formatSYNOPSIS
/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 initial-
ize an LDAP client machine, using a profile stored on anLDAP server specified by LDAP_server. The LDAP client will
use the attributes in the specified profile to determine theconfiguration of the LDAP client. Using a configuration pro-
file allows for easy installation of LDAP client and propa-
gation of configuration changes to LDAP clients. TheSunOS 5.11 Last change: 14 Feb 2009 1
System Administration Commands ldapclient(1M)
ldap_cachemgr(1M) utility will update the LDAP client confi-
guration 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 ini-
tialize 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 manu-
ally. This option modifies only those LDAP client configura-
tion attributes specified on the command line. The modoption should only be used on LDAP clients that were ini-
tialized 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 allowedin LDAP. If a self credentialLevel is configured, authenti-
cationMethod must be sasl/GSSAPI. Similarily, if a client is to be configured to enable shadow
information update and use a proxy credentialLevel, adminis-
trator credentials must be provided using -a adminDN=adminDN
and -a adminPassword=adminPassword. However, the shadow
information update does not need the administrator creden-
tials 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)SunOS 5.11 Last change: 14 Feb 2009 2
System Administration Commands ldapclient(1M)
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 reso-
lution, please refer to the DNS documentation for informa-
tion on setting up DNS. See resolv.conf(4). If you want touse 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 read-
able. 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 unini-
tialize the network service environment, restoring it to thestate 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 ofldapclient, 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 thenbe loaded into an LDAP server to be used as the client pro-
file, 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 attributesproxyDN, proxyPassword, certificatePath, domainName, ena-
bleShadowUpdate, 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.SunOS 5.11 Last change: 14 Feb 2009 3
System Administration Commands ldapclient(1M)
To access the information stored in the directory, clientscan either authenticate to the directory, or use an unau-
thenticated connection. The LDAP client is configured to have a credential level of either anonymous or proxy. In thefirst case, the client does not authenticate to the direc-
tory. In the second case, client authenticates to the direc-
tory using a proxy identity for read access, and using aadministrator identity for write access if enableShadowUp-
date 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 yourappropriate directory server documentation for identity map-
ping details.If a client is configured to use an identity, you can con-
figure which authentication method the client will use. The LDAP client supports the following authentication methods: none simplesasl/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 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. Commands The following commands are supported: init Initialize client from a profile on a server. manual Manually initialize client with the specified attribute values.SunOS 5.11 Last change: 14 Feb 2009 4
System Administration Commands ldapclient(1M)
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. uninitUninitialize 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: adminDNSpecify the Bind Distinguished Name for the administra-
tor 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 isrequired if the credential level is proxy, and ena-
bleShadowUpdate 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 beused to change the default schema used for a given ser-
vice. The syntax of attributeMap is defined in the pro-
file IETF draft. This option can be specified multipleSunOS 5.11 Last change: 14 Feb 2009 5
System Administration Commands ldapclient(1M)
times. The default value for all services is NULL. In the example, attributeMap: passwd:uid=employeeNumberthe LDAP client would use the LDAP attribute employ-
eeNumber rather than uid for the passwd service. This is a multivalued attribute. authenticationMethod Specify the default authentication method used by allservices unless overridden by the serviceAuthentication-
Method attribute. Multiple values can be specified byusing 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 authenti-
cation methods are described above. If the authentica-
tionMethod 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 serviceAuthen-
ticationMethod 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 credentialSunOS 5.11 Last change: 14 Feb 2009 6
System Administration Commands ldapclient(1M)
level is specified, then the authenticationMethod attri-
bute 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 authentica-
tionMethod 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:SunOS 5.11 Last change: 14 Feb 2009 7
System Administration Commands ldapclient(1M)
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 currentdomain name. This attribute is only used in client ini-
tialization. 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. objectclassMapSpecify a mapping from an objectclass defined by a ser-
vice 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=unixAccountthe LDAP client would use the LDAP objectclass of unix-
Account rather than the posixAccount for the passwd ser-
vice. This is a multivalued attribute.SunOS 5.11 Last change: 14 Feb 2009 8
System Administration Commands ldapclient(1M)
preferredServerList Specify the space separated list of server names or server addresses, either IPv4 or IPv6, to be contactedbefore servers specified by the defaultServerList attri-
bute. If you specify server names, be sure that the LDAPclient can resolve the name without the LDAP name ser-
vice. 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. profileNameSpecify 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 theprofileTTL attribute. For ldapclient genprofile, this is
the name of the profile to be generated. The default value is default. profileTTLSpecify the TTL value in seconds for the client informa-
tion. This is only relevant if the machine wasSunOS 5.11 Last change: 14 Feb 2009 9
System Administration Commands ldapclient(1M)
initialized with a client profile. If you do not wantldap_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 expira-
tion) or a positive integer in seconds. The default value is 12 hours. proxyDNSpecify the Bind Distinguished Name for the proxy iden-
tity. 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 servicein the form servicename:authenticationmethod, for exam-
ple:pam_ldap:tls:simple
For multiple authentication methods, use a semicolon-
separated list. The default value is no service authen-
tication 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 authenticationmethod to be used by the chkey(1) and newkey(1M) utili-
ties. The pam_ldap service defines the authentication
SunOS 5.11 Last change: 14 Feb 2009 10
System Administration Commands ldapclient(1M)
method to be used for authenticating users whenpam_ldap(5) 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. serviceCredentialLevelSpecify credential level to be used by a service. Multi-
ple values can be specified in a space-separated list.
The default value for all services is NULL. The sup-
ported credential levels are: anonymous or proxy. Atpresent, no service uses this attribute. This is a mul-
tivalued 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 valuefor all services is NULL. This is a multivalued attri-
bute. 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=people,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 com-
plete list of possible attribute names and values.-D bindDN
Specifies an entry that has read permission for the requested database.-j passwdFile
SunOS 5.11 Last change: 14 Feb 2009 11
System Administration Commands ldapclient(1M)
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 ismutually 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 ismutually 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 ismutually exclusive of the -a adminPassword option.
OPERANDS The following operand is supported:SunOS 5.11 Last change: 14 Feb 2009 12
System Administration Commands ldapclient(1M)
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 credentiallevel in the profile is set to anonymous or the authentica-
tion 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 \
SunOS 5.11 Last change: 14 Feb 2009 13
System Administration Commands ldapclient(1M)
-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. Theauthentication 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 AddressesThe following example shows how to use the genprofile com-
mand 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 serversexample# ldapclient genprofile -a profileName=eng \
-a credentialLevel=proxy \
-a authenticationMethod=sasl/DIGEST-MD5 \
SunOS 5.11 Last change: 14 Feb 2009 14
System Administration Commands ldapclient(1M)
-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 isnot guaranteed to be human readable. Use ldapclient to
update them.SunOS 5.11 Last change: 14 Feb 2009 15
System Administration Commands ldapclient(1M)
/etc/defaultdomain System default domain name, matching the domain name of the data in the LDAP servers. See defaultdomain(4). /etc/nsswitch.confConfiguration file for the name-service switch. See
nsswitch.conf(4). /etc/nsswitch.ldapSample configuration file for the name-service switch
configured with LDAP and files.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | system/network/nis ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
chkey(1), ldap(1), ldapadd(1), ldapdelete(1), ldaplist(1), ldapmodify(1), ldapmodrdn(1), ldapsearch(1), idsconfig(1M),ldapaddent(1M), ldap_cachemgr(1M), suninstall(1M), default-
domain(4), nsswitch.conf(4), resolv.conf(4), attributes(5) CAUTIONCurrently StartTLS is not supported by libldap.so.5, there-
fore 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 andnon-TLS authentication mechanisms is not recommended.
For example:-h foo:1000 -a authenticationMethod=tls:simple
SunOS 5.11 Last change: 14 Feb 2009 16
System Administration Commands ldapclient(1M)
...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= simpleSunOS 5.11 Last change: 14 Feb 2009 17