Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

ldapclient


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 enableShadowUpdate=true | false]
          [-a adminDN=adminDN]
          [-a adminPassword=adminPassword]
          [-a certificatePath=path] LDAP_server[:port_number]
          [-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 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 pro-
     file  allows for easy installation of LDAP client and propa-
     gation  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  Direc-
     tory 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 mod
     option 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=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 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)

         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  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 read-
     able. LDAP configuration files  are  not  guaranteed  to  be
     human readable. Note that the attributes proxyDN, proxyPass-
     word,   certificatePath,   domainName,   enableShadowUpdate,
     adminDN, and adminPassword are not part of the configuration
     profile and thus are not permitted.


     The uninit form of the ldapclient utility is used to  unini-
     tialize 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 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 attributes
     proxyDN, proxyPassword, certificatePath, and domainName  are
     not  part of the configuration profile and thus are not per-
     mitted.


     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 unau-
     thenticated 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  direc-
     tory. In the second case, client authenticates to the direc-
     tory using a proxy identity for read  access,  and  using  a
     administrator  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 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  con-
     figure  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  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:

     adminDN

         Specify 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  is
         required  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 be
         used 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  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  employ-
         eeNumber 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 serviceAuthentication-
         Method 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 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  credential
         level is specified, then the authenticationMethod attri-
         bute 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. 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  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.


     objectclassMap

         Specify 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=unixAccount


         the LDAP client would use the LDAP objectclass of  unix-
         Account rather than the posixAccount for the passwd ser-
         vice. 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 attri-
         bute. If you specify server names, be sure that the LDAP
         client 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.


     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 informa-
         tion.  This is only relevant if the machine was initial-
         ized  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 expira-
         tion) or a positive  integer  in  seconds.  The  default
         value is 12 hours.


     proxyDN

         Specify 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  service
         in  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  authentication
         method  to be used by the chkey(1) and newkey(1M) utili-
         ties. 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. 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. At
         present, 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  value
         for  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

         Specify attrName and its value.


     -q

         Quiet mode. No output is generated.


     -v

         Verbose output.


     -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,    thepreferredServerList   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 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 \
       -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.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  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 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
         nsswitch.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  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWnisu                    |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|


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)





Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments