Unix/Linux Go Back    


CentOS 7.0 - man page for ldap_sync (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LDAP_SYNC(3)									     LDAP_SYNC(3)

NAME
       ldap_sync_init,	    ldap_sync_init_refresh_only,      ldap_sync_init_refresh_and_persist,
       ldap_sync_poll - LDAP sync routines

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       #include <ldap.h>

       int ldap_sync_init(ldap_sync_t *ls, int mode);

       int ldap_sync_init_refresh_only(ldap_sync_t *ls);

       int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);

       int ldap_sync_poll(ldap_sync_t *ls);

       ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);

       void ldap_sync_destroy(ldap_sync_t *ls, int freeit);

       typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
	      LDAPMessage *msg, struct berval *entryUUID,
	      ldap_sync_refresh_t phase);

       typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
	      LDAPMessage *msg);

       typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
	      LDAPMessage *msg, BerVarray syncUUIDs,
	      ldap_sync_refresh_t phase);

       typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
	      LDAPMessage *msg, int refreshDeletes);

DESCRIPTION
       These routines provide an interface to the LDAP	Content  Synchronization  operation  (RFC
       4533).	They  require  an ldap_sync_t structure to be set up with parameters required for
       various phases of the operation; this includes setting some handlers for  special  events.
       All  handlers  take  a  pointer	to the ldap_sync_t structure as the first argument, and a
       pointer to the LDAPMessage structure as received from the server by  the  client  library,
       plus, occasionally, other specific arguments.

       The members of the ldap_sync_t structure are:

       char *ls_base
	      The search base; by default, the BASE option in ldap.conf(5).

       int ls_scope
	      The  search scope (one of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_SUBORDI-
	      NATE or LDAP_SCOPE_SUBTREE; see ldap.h for details).

       char *ls_filter
	      The filter (RFC 4515); by default, (objectClass=*).

       char **ls_attrs
	      The requested attributes; by default NULL, indicating all user attributes.

       int ls_timelimit
	      The requested time limit (in seconds); by default 0, to indicate no limit.

       int ls_sizelimit
	      The requested size limit (in entries); by default 0, to indicate no limit.

       int ls_timeout
	      The desired timeout during polling with ldap_sync_poll(3).  A  value  of	-1  means
	      that  polling  is blocking, so ldap_sync_poll(3) will not return until a message is
	      received; a value of 0 means that polling returns immediately,  no  matter  if  any
	      response	is  available  or  not;  a  positive  value  represents  the  timeout the
	      ldap_sync_poll(3) function will wait for response before returning, unless  a  mes-
	      sage is received; in that case, ldap_sync_poll(3) returns as soon as the message is
	      available.

       ldap_sync_search_entry_f ls_search_entry
	      A function that is called whenever an entry is returned.	The msg argument  is  the
	      LDAPMessage that contains the searchResultEntry; it can be parsed using the regular
	      client API routines, like ldap_get_dn(3), ldap_first_attribute(3), and so on.   The
	      entryUUID  argument  contains the entryUUID of the entry.  The phase argument indi-
	      cates the type of operation:  one  of  LDAP_SYNC_CAPI_PRESENT,  LDAP_SYNC_CAPI_ADD,
	      LDAP_SYNC_CAPI_MODIFY,  LDAP_SYNC_CAPI_DELETE; in case of LDAP_SYNC_CAPI_PRESENT or
	      LDAP_SYNC_CAPI_DELETE, only the DN is contained in  the  LDAPMessage;  in  case  of
	      LDAP_SYNC_CAPI_MODIFY,  the  whole  entry  is contained in the LDAPMessage, and the
	      application is responsible of determining the differences between the new  view  of
	      the entry provided by the caller and the data already known.

       ldap_sync_search_reference_f ls_search_reference
	      A  function  that is called whenever a search reference is returned.  The msg argu-
	      ment is the LDAPMessage that contains the searchResultReference; it can  be  parsed
	      using the regular client API routines, like ldap_parse_reference(3).

       ldap_sync_intermediate_f ls_intermediate
	      A  function  that  is  called whenever something relevant occurs during the refresh
	      phase of the search, which is marked by an intermediateResponse message type.   The
	      msg  argument is the LDAPMessage that contains the intermediate response; it can be
	      parsed using the regular client API routines, like ldap_parse_intermediate(3).  The
	      syncUUIDs  argument  contains  an array of UUIDs of the entries that depends on the
	      value of the phase argument.  In case  of  LDAP_SYNC_CAPI_PRESENTS,  the	"present"
	      phase is being entered; this means that the following sequence of results will con-
	      sist in entries in "present" sync state.	In case  of  LDAP_SYNC_CAPI_DELETES,  the
	      "deletes" phase is being entered; this means that the following sequence of results
	      will   consist   in   entries   in   "delete"   sync    state.	 In    case    of
	      LDAP_SYNC_CAPI_PRESENTS_IDSET,  the message contains a set of UUIDs of entries that
	      are    present;	 it    replaces    a	"presents"    phase.	 In    case    of
	      LDAP_SYNC_CAPI_DELETES_IDSET,  the  message contains a set of UUIDs of entries that
	      have been deleted; it replaces a "deletes" phase.  In case of  LDAP_SYNC_CAPI_DONE,
	      a  "presents"  phase with "refreshDone" set to "TRUE" has been returned to indicate
	      that the refresh phase of refreshAndPersist is over, and the  client  should  start
	      polling.	     Except	 for	  the	   LDAP_SYNC_CAPI_PRESENTS_IDSET      and
	      LDAP_SYNC_CAPI_DELETES_IDSET cases, syncUUIDs is NULL.

       ldap_sync_search_result_f ls_search_result
	      A function that is called whenever a searchResultDone is returned.  In  refreshAnd-
	      Persist  this can only occur when the server decides that the search must be inter-
	      rupted.  The msg argument is the LDAPMessage that contains the response; it can  be
	      parsed  using  the  regular  client  API	routines, like ldap_parse_result(3).  The
	      refreshDeletes argument is not relevant in this case; it should always be -1.

       void *ls_private
	      A pointer to private data.  The client may register here a pointer to data the han-
	      dlers above may need.

       LDAP *ls_ld
	      A  pointer  to  a  LDAP structure that is used to connect to the server.	It is the
	      responsibility of the client to initialize the structure and to provide appropriate
	      authentication and security in place.

GENERAL USE
       A  ldap_sync_t  structure  is initialized by calling ldap_sync_initialize(3).  This simply
       clears out the contents of an already existing ldap_sync_t structure, and sets appropriate
       values for some members.  After that, the caller is responsible for setting up the connec-
       tion (member ls_ld), eventually setting up transport security (TLS), for binding  and  any
       other  initialization.  The caller must also fill all the documented search-related fields
       of the ldap_sync_t structure.

       At the end of a session, the structure can be cleaned up by calling  ldap_sync_destroy(3),
       which  takes  care of freeing all data assuming it was allocated by ldap_mem*(3) routines.
       Otherwise, the caller should take care  of  destroying  and  zeroing  out  the  documented
       search-related  fields,	and call ldap_sync_destroy(3) to free undocumented members set by
       the API.

REFRESH ONLY
       The refreshOnly functionality is obtained by periodically calling  ldap_sync_init(3)  with
       mode  set  to  LDAP_SYNC_REFRESH_ONLY,  or,  which  is  equivalent,  by	directly  calling
       ldap_sync_init_refresh_only(3).	The state of the  search,  and	the  consistency  of  the
       search  parameters, is preserved across calls by passing the ldap_sync_t structure as left
       by the previous call.

REFRESH AND PERSIST
       The refreshAndPersist functionality is obtained by calling ldap_sync_init(3) with mode set
       to   LDAP_SYNC_REFRESH_AND_PERSIST,   or,   which   is  equivalent,  by	directly  calling
       ldap_sync_init_refresh_and_persist(3)  and,  after  a  successful  return,  by  repeatedly
       polling with ldap_sync_poll(3) according to the desired pattern.

       A client may insert a call to ldap_sync_poll(3) into an external loop to check if any mod-
       ification was returned; in this case, it might be appropriate to set ls_timeout to  0,  or
       to  set	it to a finite, small value.  Otherwise, if the client's main purpose consists in
       waiting for responses, a timeout of -1 is most suitable, so that the function only returns
       after some data has been received and handled.

ERRORS
       All  routines  return  any  LDAP error resulting from a lower-level error in the API calls
       they are based on, or LDAP_SUCCESS in  case  of	success.   ldap_sync_poll(3)  may  return
       LDAP_SYNC_REFRESH_REQUIRED if a full refresh is requested by the server.  In this case, it
       is appropriate to call ldap_sync_init(3) again, passing the same ldap_sync_t structure  as
       resulted from any previous call.

NOTES
SEE ALSO
       ldap(3), ldap_search_ext(3), ldap_result(3); RFC 4533 (http://www.rfc-editor.org),

AUTHOR
       Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by
       syncrepl code in slapd(8).

ACKNOWLEDGEMENTS
       Initially developed by SysNet s.n.c.  OpenLDAP is developed and maintained by The OpenLDAP
       Project	(http://www.openldap.org/).  OpenLDAP is derived from University of Michigan LDAP
       3.3 Release.

OpenLDAP 2.4.39 			    2014/01/26				     LDAP_SYNC(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:05 PM.