/
cachedb_local_admin.xml
305 lines (286 loc) · 10.3 KB
/
cachedb_local_admin.xml
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
<!-- Module User's Guide -->
<chapter>
<title>&adminguide;</title>
<section id="overview" xreflabel="Overview">
<title>Overview</title>
<para>
This module is an implementation of a local cache system designed as
a hash table. It uses the Key-Value interface exported by OpenSIPS core.
Starting with version 2.3, the module can have multiple hash tables,
called collections. Each url for cachedb_local module points to one
collection. One collection can be shared between multiple urls.
</para>
<para>
</para>
</section>
<section id="clustering" xreflabel="clustering">
<title>Clustering</title>
<para>
Cachedb_local clustering is a mechanism used to mirror local cache changes
taking place in one OpenSIPS instance to one or multiple other instances without
the need of third party dependencies.
The process is simplified by using the clusterer module which facilitates the
management of a cluster of OpenSIPS noeds and the sending of replication-related
BIN packets (binary-encoded, using proto_bin). This might be usefull for implementing
a hot stand-by system, where the stand-by instance can take over without the need
of filling the cache by its own.
</para>
<para>
The following cache operations will be distributet within the cluster:
<itemizedlist>
<listitem><para>cache_store</para></listitem>
<listitem><para>cache_remove</para></listitem>
<listitem><para>cache_add</para></listitem>
<listitem><para>cache_sub</para></listitem>
</itemizedlist>
</para>
<para>
In addition to the event-driven replication, an OpenSIPS instance will first
try to learn all the local cache information from antoher node in the cluster at startup.
The data synchronization mechanism requires defining one of the nodes in the cluster
as a "<emphasis role='bold'>seed</emphasis>" node.
See the <ulink url="https://opensips.org/docs/modules/3.0.x/clusterer.html#capabilities">clusterer</ulink>
module for details on how to do this and why is it needed.
</para>
<para>
<emphasis role='bold'>Limitations:</emphasis> The clustering operations are not atomic
and constistency over the cluster nodes is not guaranteed.
</para>
</section>
<section id="dependencies" xreflabel="Dependencies">
<title>Dependencies</title>
<section>
<title>&osips; Modules</title>
<para>
The following modules must be loaded before this module:
<itemizedlist>
<listitem>
<para>
<emphasis>clusterer, if <xref linkend="param_cluster_id"/>
is set.</emphasis>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>External Libraries or Applications</title>
<para>
The following libraries or applications must be installed before running
&osips; with this module loaded:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>none</emphasis>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section id="exported_parameters" xreflabel="Exported Parameters">
<title>Exported Parameters</title>
<section id="param_cachedb_url" xreflabel="cachedb_url">
<title><varname>cachedb_url</varname> (string)</title>
<para>
URL parameter used to define cachedb_local collections. One collection
can belong to multiple URLs, but one URL can have only one collection.
Redefining an URL with the same schema and group name will result in overwriting
that URL. Each collection used in URL definition must be defined using
<emphasis>cachedb_collection</emphasis> parameter. The collection shall be defined
as a normal database, at the end of the URL as in the examples. In the script the
collection shall be identified using the schema and, if exists, the group name.
</para>
<para>
<emphasis><quote>If no URL defined, the url with no group name and collection "default"
will be used.</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>cachedb_url</varname> parameter</title>
<programlisting format="linespecific">
...
### for this example, if no collection is defined, the default collection named
### "default" shall be used
modparam("cachedb_local", "cachedb_url", "local://")
### this URL will use the collection named collection1; it will overwrite the
### previous url definition which was using the "default" collection
modparam("cachedb_local", "cachedb_url", "local:///collection1")
### this URL will use collection2; it will be referenced from the script
### with "local:group2"
modparam("cachedb_local", "cachedb_url", "local:group2:///collection2")
## how to use the URLs from the script
## as defined above, this call will use collection1
cache_store("local", ...)
## as defined above, this call will use collection2
cache_store("local:group2", ...)
...
</programlisting>
</example>
</section>
<section id="param_cache_collections" xreflabel="cache_collections">
<title><varname>cache_collections</varname> (string)</title>
<para>
Using this parameter collections(hash tables) and their sizes can be defined. Each
collection definition must be separated one from another using ';'. Default size
for a hash is 512. The size must be separated from the name of the collection using
'='. Every collection that is defined in this parameter <emphasis>SHOULD</emphasis> be
used in at least one URL, else you'll receive a WARNING.
</para>
<para>
The <emphasis>"default"</emphasis> collection always gets created, even when
not included in this list of collections.
</para>
<example>
<title>Set <varname>cache_collections</varname> parameter</title>
<programlisting format="linespecific">
...
## creating collection1 with default size (512) and collection2 with custom size
## 2^5 (32); we also changed the size of the default collection, which would have been
## created anyway from 2^9 - 512 (default value) to 2^4 - 16
modparam("cachedb_local", "cache_collections", "collection1; collection2 = 5; default = 4")
...
</programlisting>
</example>
</section>
<section id="param_cache_clean_period" xreflabel="cache_clean_period">
<title><varname>cache_clean_period</varname> (int)</title>
<para>
The time interval in seconds at which to go through all the
records and delete the expired ones.
</para>
<para>
<emphasis>Default value is <quote>600 (10 minutes)</quote>.
</emphasis>
</para>
<example>
<title>Set <varname>cache_clean_period</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("cachedb_local", "cache_clean_period", 1200)
...
</programlisting>
</example>
</section>
<section id="param_cluster_id" xreflabel="cluster_id">
<title><varname>cluster_id</varname> (int)</title>
<para>
Specifies the cluster ID which this instance will send to and receive
cache data.
</para>
<para>
Default value is 0 (replication disabled).
</para>
<example>
<title>Setting the <varname>cluster_id</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("cachedb_local", "cluster_id", 1)
...
</programlisting>
</example>
</section>
<section id="param_cluster_persistency" xreflabel="cluster_persistency">
<title><varname>cluster_persistency</varname> (string)</title>
<para>
Controls the behavior of the OpenSIPS local cachedb clustering following a restart.
</para>
<para>
This parameter may take the following values:
</para>
<itemizedlist>
<listitem>
<para><emphasis>"none"</emphasis> - no explicit data
synchronization following a restart. The node starts empty.
</para>
</listitem>
<listitem>
<para><emphasis>"sync-from-cluster"</emphasis> - enable
cluster-based restart persistency. Following a restart,
an OpenSIPS cluster node will search for a healthy "donor" node
from which to mirror the entire user location dataset via
direct cluster sync (TCP-based, binary-encoded data transfer).
This will require the configuration of one or multiple "seed"
nodes in the cluster.
</para>
</listitem>
</itemizedlist>
<para>
<emphasis>
Default value is
<emphasis>"sync-from-cluster"</emphasis>.
</emphasis>
</para>
<example>
<title>Set <varname>cluster_persistency</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("cachedb_local", "cluster_persistency", "sync-from-cluster")
...
</programlisting>
</example>
</section>
</section>
<section id="exported_functions" xreflabel="exported_functions">
<title>Exported Functions</title>
<section id="func_cache_remove_chunk" xreflabel="cache_remove_chunk()">
<title>
<function moreinfo="none">cache_remove_chunk([collection,] glob)</function>
</title>
<para>
Remove all keys from local cache that match the <emphasis>glob</emphasis> pattern
corresponding to a certain <emphasis>collection</emphasis> or the 'default' collection
if none defined. Keep in mind that collection name is different than group name,
which identifies the engine in cachedb operations.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>collection</emphasis> (string, optional)
</para></listitem>
<listitem><para>
<emphasis>glob</emphasis> (string)
</para></listitem>
</itemizedlist>
<para>
This function can be used from all routes
</para>
<example>
<title><function>cache_remove_chunk</function> usage</title>
<programlisting format="linespecific">
...
cache_remove_chunk("myinfo_*");
cache_remove_chunk("collection1", "myinfo_*");
...
</programlisting>
</example>
</section>
</section>
<section id="exported_mi_functions" xreflabel="Exported MI Functions">
<title>Exported MI Functions</title>
<section id="mi_cache_remove_chunk" xreflabel="cache_remove_chunk">
<title>
<function moreinfo="none">cache_remove_chunk</function>
</title>
<para>
Removes all local cache entries that match the provided glob param.
</para>
<para>Parameters :</para>
<itemizedlist>
<listitem><para>
<emphasis>glob</emphasis> - keys that match glob will be removed
</para></listitem>
<listitem><para>
<emphasis>collection(optional)</emphasis> - collection from which the keys shall
be removed; if no collection set, the default collection will be used;
</para></listitem>
</itemizedlist>
<para>
MI FIFO Command Format:
</para>
<programlisting format="linespecific">
opensips-cli -x mi cache_remove_chunk "keyprefix*" collection
</programlisting>
</section>
</section>
</chapter>