1LDAP_SYNC(3)               Library Functions Manual               LDAP_SYNC(3)
2
3
4

NAME

6       ldap_sync_init,     ldap_sync_init_refresh_only,     ldap_sync_init_re‐
7       fresh_and_persist, ldap_sync_poll - LDAP sync routines
8

LIBRARY

10       OpenLDAP LDAP (libldap, -lldap)
11

SYNOPSIS

13       #include <ldap.h>
14
15       int ldap_sync_init(ldap_sync_t *ls, int mode);
16
17       int ldap_sync_init_refresh_only(ldap_sync_t *ls);
18
19       int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls);
20
21       int ldap_sync_poll(ldap_sync_t *ls);
22
23       ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls);
24
25       void ldap_sync_destroy(ldap_sync_t *ls, int freeit);
26
27       typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls,
28              LDAPMessage *msg, struct berval *entryUUID,
29              ldap_sync_refresh_t phase);
30
31       typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls,
32              LDAPMessage *msg);
33
34       typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls,
35              LDAPMessage *msg, BerVarray syncUUIDs,
36              ldap_sync_refresh_t phase);
37
38       typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls,
39              LDAPMessage *msg, int refreshDeletes);
40

DESCRIPTION

42       These routines provide an interface to the LDAP Content Synchronization
43       operation  (RFC 4533).  They require an ldap_sync_t structure to be set
44       up with parameters required for various phases of the  operation;  this
45       includes setting some handlers for special events.  All handlers take a
46       pointer to the ldap_sync_t structure  as  the  first  argument,  and  a
47       pointer to the LDAPMessage structure as received from the server by the
48       client library, plus, occasionally, other specific arguments.
49
50       The members of the ldap_sync_t structure are:
51
52       char *ls_base
53              The search base; by default, the BASE option in ldap.conf(5).
54
55       int ls_scope
56              The search scope (one of  LDAP_SCOPE_BASE,  LDAP_SCOPE_ONELEVEL,
57              LDAP_SCOPE_SUBORDINATE or LDAP_SCOPE_SUBTREE; see ldap.h for de‐
58              tails).
59
60       char *ls_filter
61              The filter (RFC 4515); by default, (objectClass=*).
62
63       char **ls_attrs
64              The requested attributes; by default NULL, indicating  all  user
65              attributes.
66
67       int ls_timelimit
68              The requested time limit (in seconds); by default 0, to indicate
69              no limit.
70
71       int ls_sizelimit
72              The requested size limit (in entries); by default 0, to indicate
73              no limit.
74
75       int ls_timeout
76              The  desired  timeout  during polling with ldap_sync_poll(3).  A
77              value of -1 means that polling is blocking, so ldap_sync_poll(3)
78              will  not return until a message is received; a value of 0 means
79              that polling returns immediately, no matter if any  response  is
80              available  or  not;  a positive value represents the timeout the
81              ldap_sync_poll(3) function will wait for response before return‐
82              ing,   unless   a   message   is   received;   in   that   case,
83              ldap_sync_poll(3) returns as soon as the message is available.
84
85       ldap_sync_search_entry_f ls_search_entry
86              A function that is called whenever an entry  is  returned.   The
87              msg  argument  is the LDAPMessage that contains the searchResul‐
88              tEntry; it can be parsed using the regular client API  routines,
89              like  ldap_get_dn(3),  ldap_first_attribute(3),  and so on.  The
90              entryUUID argument contains the entryUUID  of  the  entry.   The
91              phase   argument   indicates  the  type  of  operation:  one  of
92              LDAP_SYNC_CAPI_PRESENT, LDAP_SYNC_CAPI_ADD,  LDAP_SYNC_CAPI_MOD‐
93              IFY, LDAP_SYNC_CAPI_DELETE; in case of LDAP_SYNC_CAPI_PRESENT or
94              LDAP_SYNC_CAPI_DELETE, only the DN is contained in the  LDAPMes‐
95              sage;  in case of LDAP_SYNC_CAPI_MODIFY, the whole entry is con‐
96              tained in the LDAPMessage, and the application is responsible of
97              determining  the  differences  between the new view of the entry
98              provided by the caller and the data already known.
99
100       ldap_sync_search_reference_f ls_search_reference
101              A function that is called whenever a  search  reference  is  re‐
102              turned.   The  msg argument is the LDAPMessage that contains the
103              searchResultReference; it can be parsed using the regular client
104              API routines, like ldap_parse_reference(3).
105
106       ldap_sync_intermediate_f ls_intermediate
107              A  function  that  is  called whenever something relevant occurs
108              during the refresh phase of the search, which is  marked  by  an
109              intermediateResponse  message  type.   The  msg  argument is the
110              LDAPMessage that contains the intermediate response; it  can  be
111              parsed   using   the   regular   client   API   routines,   like
112              ldap_parse_intermediate(3).  The syncUUIDs argument contains  an
113              array  of  UUIDs of the entries that depends on the value of the
114              phase  argument.   In  case  of   LDAP_SYNC_CAPI_PRESENTS,   the
115              "present"  phase is being entered; this means that the following
116              sequence of results will consist in entries  in  "present"  sync
117              state.   In  case of LDAP_SYNC_CAPI_DELETES, the "deletes" phase
118              is being entered; this means that the following sequence of  re‐
119              sults  will  consist in entries in "delete" sync state.  In case
120              of LDAP_SYNC_CAPI_PRESENTS_IDSET, the message contains a set  of
121              UUIDs  of  entries  that  are  present; it replaces a "presents"
122              phase.  In case  of  LDAP_SYNC_CAPI_DELETES_IDSET,  the  message
123              contains  a  set  of UUIDs of entries that have been deleted; it
124              replaces a "deletes" phase.  In case of  LDAP_SYNC_CAPI_DONE,  a
125              "presents"  phase  with "refreshDone" set to "TRUE" has been re‐
126              turned to indicate that the refresh phase  of  refreshAndPersist
127              is  over,  and  the client should start polling.  Except for the
128              LDAP_SYNC_CAPI_PRESENTS_IDSET  and  LDAP_SYNC_CAPI_DELETES_IDSET
129              cases, syncUUIDs is NULL.
130
131       ldap_sync_search_result_f ls_search_result
132              A  function  that  is  called whenever a searchResultDone is re‐
133              turned.  In refreshAndPersist  this  can  only  occur  when  the
134              server decides that the search must be interrupted.  The msg ar‐
135              gument is the LDAPMessage that contains the response; it can  be
136              parsed   using   the   regular   client   API   routines,   like
137              ldap_parse_result(3).  The refreshDeletes argument is not  rele‐
138              vant in this case; it should always be -1.
139
140       void *ls_private
141              A  pointer  to  private  data.   The  client may register here a
142              pointer to data the handlers above may need.
143
144       LDAP *ls_ld
145              A pointer to a LDAP structure that is used  to  connect  to  the
146              server.   It  is  the responsibility of the client to initialize
147              the structure and to provide appropriate authentication and  se‐
148              curity in place.
149
150

GENERAL USE

152       A  ldap_sync_t  structure  is initialized by calling ldap_sync_initial‐
153       ize(3).  This simply clears out the contents  of  an  already  existing
154       ldap_sync_t  structure,  and  sets appropriate values for some members.
155       After that, the caller is responsible for  setting  up  the  connection
156       (member  ls_ld),  eventually  setting  up transport security (TLS), for
157       binding and any other initialization.  The caller must  also  fill  all
158       the documented search-related fields of the ldap_sync_t structure.
159
160       At  the  end  of  a session, the structure can be cleaned up by calling
161       ldap_sync_destroy(3), which takes care of freeing all data assuming  it
162       was  allocated  by ldap_mem*(3) routines.  Otherwise, the caller should
163       take care of destroying and zeroing out the  documented  search-related
164       fields,  and call ldap_sync_destroy(3) to free undocumented members set
165       by the API.
166
167

REFRESH ONLY

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

REFRESH AND PERSIST

178       The    refreshAndPersist   functionality   is   obtained   by   calling
179       ldap_sync_init(3) with mode set to  LDAP_SYNC_REFRESH_AND_PERSIST,  or,
180       which   is   equivalent,   by   directly   calling   ldap_sync_init_re‐
181       fresh_and_persist(3) and, after  a  successful  return,  by  repeatedly
182       polling with ldap_sync_poll(3) according to the desired pattern.
183
184       A  client  may insert a call to ldap_sync_poll(3) into an external loop
185       to check if any modification was returned; in this case,  it  might  be
186       appropriate  to  set  ls_timeout  to 0, or to set it to a finite, small
187       value.  Otherwise, if the client's main purpose consists in waiting for
188       responses,  a timeout of -1 is most suitable, so that the function only
189       returns after some data has been received and handled.
190
191

ERRORS

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

NOTES

SEE ALSO

202       ldap(3),  ldap_search_ext(3), ldap_result(3); RFC 4533 (http://www.rfc-
203       editor.org),
204

AUTHOR

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

ACKNOWLEDGEMENTS

210       Initially  developed  by SysNet s.n.c.  OpenLDAP is developed and main‐
211       tained by The OpenLDAP Project (http://www.openldap.org/).  OpenLDAP is
212       derived from University of Michigan LDAP 3.3 Release.
213
214
215
216OpenLDAP                          2021/06/03                      LDAP_SYNC(3)
Impressum