Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
System Administration Commandsldapclient(1M)


NAME

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

SYNOPSIS

 /usr/sbin/ldapclient [ -v | -q] init [ -a proxyName=profile] [ -adomainName=domain] [ -a proxyDN=proxyDN] [ -a proxyPassword=password] [ -a certificatePath=path] LDAP_server_addr [: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:

  • initialize LDAP client machines
  • restore the network service environment on LDAP clients
  • 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_addr. 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(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 specified on the command line. Any unspecified attributes will be assigned their default values. The defaultSearchBase and defaultServerList attributes must be specified, and 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=proxyD 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 any file is modified during installation, it will be backed up to /var/ldap/restore. The files that are typically modified during initialization are:

  • /etc/nsswitch.conf
  • /etc/defaultdomain (if it exists)
  • /var/yp/binding/`domainname` (for a NIS(YP) client)
  • /var/nis/NIS_COLD_START (for a NIS+ client)
  • /var/ldap/ldap_client_file (for an existing LDAP client)
  • /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).

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 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, and domainName 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.

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
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.
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, using a comma-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.
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. 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.
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.
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 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 preferred server IP addresses to be contacted before servers specified by the defaultServerList attribute. 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.

Fully qualified hostnames may also be used. If fully qualified hostnames are used, you must configure nsswitch.conf to use files or dns, not ldap, to resolve hosts lookup. If you fail to configure nsswitch.conf properly, then your system or certain processes can hang if you use a hostname value.

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(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 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. Multiple values can be specified by a comma-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(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 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=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
Specify attrName and its value.
-q
Quiet mode. No output is generated.
-v
Verbose output.

OPERANDS

 

The following operand is supported:

defaultServerList
A space separated list of server IP addresses. 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 which case the default LDAP server port number is 636.

Fully qualified hostnames may be used. If you use fully qualified hostnames, you must configure nsswitch.conf to use files or dns, not ldap, to resolve hosts lookup. If you fail to configure nsswitch.conf properly, then your system or certain processes can hang if you use a hostname value.

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 129.100.100.1
Example 2. 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=129.100.100.1
Example 3. 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.mycompany.com, and the LDAP server is running on port number 386 at IP address 129.100.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=129.100.100.1:386
Example 4. 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=129.100.100.1 129.100.234.15:386" \
> myprofile.ldif
Example 5. 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=129.100.100.30 -a searchTimeLimit=30 \
-a "defaultServerList=29.100.200.1 129.100.100.1 204.34.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.
/etc/nsswitch.conf
Configuration file for the name-service switch.
/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 TYPEATTRIBUTE VALUE
AvailabilitySUNWnisu
Interface StabilityEvolving

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), resolv.conf(4), attributes(5)


SunOS 5.9Go To TopLast Changed 21 Dec 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.