Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ldapclient(1M)		System Administration Commands		ldapclient(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]  [	 -ado-
       mainName=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:

	  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 for-
	     mat.

       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	speci-
       fied  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	speci-
       fied  on	the command  line. Any unspecified attributes will be assigned
       their default values. The defaultSearchBase and	defaultServerList  at-
       tributes	must be	specified,  and	the domainName attribute must be spec-
       ified 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=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  al-
       lowed 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	  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 pre-
       fer  to use DNS for host	resolution, please refer to the	DNS documenta-
       tion 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 configu-
       ration 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	 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 di-
       rectory	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, ex-
       cept 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  authenti-
       cate 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 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 at-
	     tributeMap	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 at-
	     tribute.

       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 creden-
	     tialLevel and credentialLevel is anonymous, this attribute	is ig-
	     nored. Services such as pam_ldap will use this attribute, even if
	     credentialLevel is	anonymous. The supported authentication	 meth-
	     ods 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 data-
	     base. The value is	the path where security	database files reside.
	     This is used for TLS support, which is specified in the authenti-
	     cationMethod and serviceAuthenticationMethod attributes. The  de-
	     fault 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 au-
	     thenticationMethod	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 ser-
	     viceSearchDescriptor  attribute  can  be used to override the de-
	     faultSearchBase 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
	     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	attri-
	     bute is only used in client initialization.

       followReferrals=true | false
	     Specify  the referral setting. A setting of true implies that re-
	     ferrals 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 ob-
	     jectclassMap is defined in	the profile IETF draft.	  This	option
	     can  be specified multiple	times.	The default value for all ser-
	     vices 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 de-
	     fault  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 config-
	     ure 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  periodi-
	     cally  depending  on  the	value of the profileTTL	attribute. For
	     ldapclient	genprofile, this is the	name of	the profile to be gen-
	     erated. 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 re-
	     fresh 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  op-
	     eration.	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 authenti-
	     cation method to be used by passwd(1) to  change the user's pass-
	     word  and other attributes. The keyserv  service is used to iden-
	     tify the authentication method to be used	by  the	 chkey(1)  and
	     newkey(1M)	 utilities.  The  pam_ldap service defines the authen-
	     tication  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	attri-
	     bute.

       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  ser-
	     vice. The format of the descriptors also allow overriding the de-
	     fault 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=peo-
	     ple,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  nss-
	     witch.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 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 do-
       main 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	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWnisu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

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

SunOS 5.9			  21 Dec 2001			ldapclient(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | EXAMPLES | EXIT STATUS | FILES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ldapclient&sektion=1m&manpath=SunOS+5.9>

home | help