summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/ldap_sync.3
blob: 8fb77f59d0f75d991d7a1b3930e8f71d6367618e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
.TH LDAP_SYNC 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 2006-2022 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines
.SH LIBRARY
OpenLDAP LDAP (libldap, \-lldap)
.SH SYNOPSIS
.nf
.B #include <ldap.h>
.LP
.BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ");"
.LP
.BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");"
.LP
.BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls  ");"
.LP
.BI "int ldap_sync_poll(ldap_sync_t *" ls ");"
.LP
.BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");"
.LP
.BI "void ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");"
.LP
.BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls ","
.RS
.BI "LDAPMessage *" msg ", struct berval *" entryUUID ","
.BI "ldap_sync_refresh_t " phase ");"
.RE
.LP
.BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls ","
.RS
.BI "LDAPMessage *" msg ");"
.RE
.LP
.BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls ","
.RS
.BI "LDAPMessage *" msg ", BerVarray " syncUUIDs ","
.BI "ldap_sync_refresh_t " phase ");"
.RE
.LP
.BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls ","
.RS
.BI "LDAPMessage *" msg ", int " refreshDeletes ");"
.RE
.SH DESCRIPTION
.LP
These routines provide an interface to the LDAP Content Synchronization 
operation (RFC 4533).
They require an
.BR 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 \fBldap_sync_t\fP structure as the first
argument, and a pointer to the \fBLDAPMessage\fP structure as received
from the server by the client library, plus, occasionally, other specific
arguments.

The members of the \fBldap_sync_t\fP structure are:
.TP
.BI "char *" ls_base
The search base; by default, the
.B BASE
option in
.BR ldap.conf (5).
.TP
.BI "int " ls_scope
The search scope (one of 
.BR LDAP_SCOPE_BASE ,
.BR LDAP_SCOPE_ONELEVEL ,
.BR LDAP_SCOPE_SUBORDINATE
or
.BR LDAP_SCOPE_SUBTREE ;
see
.B ldap.h
for details).
.TP
.BI "char *" ls_filter
The filter (RFC 4515); by default, 
.BR (objectClass=*) .
.TP
.BI "char **" ls_attrs
The requested attributes; by default
.BR NULL ,
indicating all user attributes.
.TP
.BI "int " ls_timelimit
The requested time limit (in seconds); by default
.BR 0 ,
to indicate no limit.
.TP
.BI "int " ls_sizelimit
The requested size limit (in entries); by default
.BR 0 ,
to indicate no limit.
.TP
.BI "int " ls_timeout
The desired timeout during polling with
.BR ldap_sync_poll (3).
A value of
.BR \-1
means that polling is blocking, so 
.BR ldap_sync_poll (3)
will not return until a message is received; a value of
.BR 0
means that polling returns immediately, no matter if any response
is available or not; a positive value represents the timeout the
.BR ldap_sync_poll (3)
function will wait for response before returning, unless a message
is received; in that case, 
.BR ldap_sync_poll (3)
returns as soon as the message is available.
.TP
.BI "ldap_sync_search_entry_f " ls_search_entry
A function that is called whenever an entry is returned.
The
.BR msg
argument is the
.BR LDAPMessage
that contains the searchResultEntry; it can be parsed using the regular 
client API routines, like 
.BR ldap_get_dn (3),
.BR ldap_first_attribute (3),
and so on.
The
.BR entryUUID
argument contains the entryUUID of the entry.
The
.BR phase
argument indicates the type of operation: one of
.BR LDAP_SYNC_CAPI_PRESENT ,
.BR LDAP_SYNC_CAPI_ADD ,
.BR LDAP_SYNC_CAPI_MODIFY ,
.BR LDAP_SYNC_CAPI_DELETE ;
in case of
.BR LDAP_SYNC_CAPI_PRESENT
or
.BR LDAP_SYNC_CAPI_DELETE ,
only the DN is contained in the 
.IR LDAPMessage ;
in case of 
.BR LDAP_SYNC_CAPI_MODIFY ,
the whole entry is contained in the 
.IR 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.
.TP
.BI "ldap_sync_search_reference_f " ls_search_reference
A function that is called whenever a search reference is returned.
The
.BR msg
argument is the
.BR LDAPMessage
that contains the searchResultReference; it can be parsed using 
the regular client API routines, like 
.BR ldap_parse_reference (3).
.TP
.BI "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 \fIintermediateResponse\fP message type.
The
.BR msg
argument is the
.BR LDAPMessage
that contains the intermediate response; it can be parsed using 
the regular client API routines, like 
.BR ldap_parse_intermediate (3).
The
.BR syncUUIDs
argument contains an array of UUIDs of the entries that depends
on the value of the
.BR phase
argument.
In case of
.BR LDAP_SYNC_CAPI_PRESENTS ,
the "present" phase is being entered;
this means that the following sequence of results will consist
in entries in "present" sync state.
In case of
.BR 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
.BR 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
.BR 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
.BR 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
.BR LDAP_SYNC_CAPI_PRESENTS_IDSET
and
.BR LDAP_SYNC_CAPI_DELETES_IDSET
cases,
.BR syncUUIDs
is NULL.
.BR
.TP
.BI "ldap_sync_search_result_f " ls_search_result
A function that is called whenever a searchResultDone is returned.
In refreshAndPersist this can only occur when the server decides
that the search must be interrupted.
The
.BR msg
argument is the
.BR LDAPMessage
that contains the response; it can be parsed using 
the regular client API routines, like 
.BR ldap_parse_result (3).
The
.BR refreshDeletes
argument is not relevant in this case; it should always be \-1.
.TP
.BI "void *" ls_private
A pointer to private data.  The client may register here
a pointer to data the handlers above may need.
.TP
.BI "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.

.SH "GENERAL USE"
A
.B ldap_sync_t
structure is initialized by calling
.BR ldap_sync_initialize(3).
This simply clears out the contents of an already existing
.B ldap_sync_t
structure, and sets appropriate values for some members.
After that, the caller is responsible for setting up the
connection (member
.BR 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
.B ldap_sync_t
structure.

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

.SH "REFRESH ONLY"
The
.BR refreshOnly
functionality is obtained by periodically calling
.BR ldap_sync_init (3)
with mode set to
.BR LDAP_SYNC_REFRESH_ONLY ,
or, which is equivalent, by directly calling
.BR 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 
.B ldap_sync_t
structure as left by the previous call.

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

A client may insert a call to 
.BR ldap_sync_poll (3)
into an external loop to check if any modification was returned;
in this case, it might be appropriate to set
.BR 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.

.SH 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.
.BR ldap_sync_poll (3) 
may return 
.BR LDAP_SYNC_REFRESH_REQUIRED
if a full refresh is requested by the server.
In this case, it is appropriate to call
.BR ldap_sync_init (3)
again, passing the same
.B ldap_sync_t
structure as resulted from any previous call.
.SH NOTES
.SH SEE ALSO
.BR ldap (3),
.BR ldap_search_ext (3),
.BR ldap_result (3) ;
.B RFC 4533
(http://www.rfc-editor.org),
.SH AUTHOR
Designed and implemented by Pierangelo Masarati, based on RFC 4533
and loosely inspired by syncrepl code in
.BR slapd (8).
.SH ACKNOWLEDGEMENTS
Initially developed by
.BR "SysNet s.n.c."
.B OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.