-
Notifications
You must be signed in to change notification settings - Fork 564
/
README
319 lines (240 loc) · 9.7 KB
/
README
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
cachedb_mongodb Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Advantages
1.3. Limitations
1.4. Dependencies
1.4.1. OpenSIPS Modules
1.4.2. External Libraries or Applications
1.5. Exported Parameters
1.5.1. cachedb_url (string)
1.5.2. exec_threshold (int)
1.5.3. compat_mode_2.4 (int)
1.5.4. compat_mode_3.0 (int)
1.6. Exported Functions
1.7. Raw Query Syntax
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors
List of Tables
2.1. Top contributors by DevScore^(1), authored commits^(2) and
lines added/removed^(3)
2.2. Most recently active contributors^(1) to this module
List of Examples
1.1. Runtime requirements for "cachedb_mongodb"
1.2. Compilation requirements for "cachedb_mongodb"
1.3. Set cachedb_url parameter
1.4. Reference MongoDB connections
1.5. Set exec_threshold parameter
1.6. Setting the compat_mode_2.4 parameter
1.7. Setting the compat_mode_3.0 parameter
1.8. MongoDB Raw Insert
1.9. MongoDB Raw Update
Chapter 1. Admin Guide
1.1. Overview
This module is an implementation of a cache system designed to
work with MongoDB servers. It implements the Key-Value
interface exposed by the OpenSIPS core.
The underlying client library is compatible with any of the
following MongoDB server versions: 2.4, 2.6, 3.0, 3.2 and 3.4,
as stated in the MongoDB documentation.
1.2. Advantages
* memory costs are no longer on the server
* many servers can be used inside a cluster, so the memory is
virtually unlimited
* the cache is 100% persistent. A restart of OpenSIPS server
will not affect the DB. The MongoDB is also persistent so
it can also be restarted without loss of information.
* MongoDB is an open-source project so it can be used to
exchange data with various other applications
* By creating a MongoDB Cluster, multiple OpenSIPS instances
can easily share key-value information
* This module also implements the CacheDB Raw query
capability, thus you can run whatever query that the
MongoDB back-end supports, taking full advatange of it.
1.3. Limitations
* keys (in key:value pairs) may not contain spaces or control
characters
1.4. Dependencies
1.4.1. OpenSIPS Modules
None.
1.4.2. External Libraries or Applications
The following packages must be installed before running
OpenSIPS with this module loaded:
Example 1.1. Runtime requirements for "cachedb_mongodb"
# Debian / Ubuntu
sudo apt-get install libjson-c2 libmongoc-1.0
# Red Hat / CentOS
sudo yum install json-c mongo-c-driver
The following packages are required in order to compile this
module:
Example 1.2. Compilation requirements for "cachedb_mongodb"
# Debian / Ubuntu
sudo apt-get install libjson-c-dev libmongoc-dev libbson-dev
# Red Hat / CentOS
sudo yum install json-c-devel mongo-c-driver-devel
1.5. Exported Parameters
1.5.1. cachedb_url (string)
The URLs of the server groups that OpenSIPS will connect to in
order to allow the cache_store(), cache_fetch(), etc. functions
to be used from the OpenSIPS script. It can be set more than
one time. The prefix part of the URL will be the identifier
that will be used from the script.
The URL syntax is identical to the one used by MongoDB,
including connect string options. For more info, please refer
to the official MongoDB connect string documentation.
Example 1.3. Set cachedb_url parameter
...
# Connect to a single mongod instance
modparam("cachedb_mongodb", "cachedb_url",
"mongodb://localhost:27017/opensipsDB.dialog")
# Connect to a mongod replica set
modparam("cachedb_mongodb", "cachedb_url",
"mongodb://10.0.0.10,10.0.0.11:27017/opensipsDB.dialog?replicaS
et=my-set")
# Connect to a mongos instance (routes to a sharded cluster)
modparam("cachedb_mongodb", "cachedb_url",
"mongodb://localhost/opensipsDB.dialog")
# Example of multiple connections:
# * to a main mongos, with failover to a backup mongos
# * to a single mongod
modparam("cachedb_mongodb", "cachedb_url",
"mongodb:cluster://localhost,10.0.0.10:27017/opensipsDB.dialog"
)
modparam("cachedb_mongodb", "cachedb_url",
"mongodb://localhost:27017/opensipsDB.userlocation")
...
Example 1.4. Reference MongoDB connections
...
cache_store("mongodb", "key", "$ru value");
cache_remove("mongodb:cluster", "key");
cache_fetch("mongodb:instance1", "key", $avp(10));
...
1.5.2. exec_threshold (int)
The maximum number of microseconds that a mongodb query can
last. Anything above the threshold will trigger a warning
message to the log
Default value is “0 ( unlimited - no warnings )”.
Example 1.5. Set exec_threshold parameter
...
modparam("cachedb_mongodb", "exec_threshold", 100000)
...
1.5.3. compat_mode_2.4 (int)
Switch the module into compatibility mode for MongoDB 2.4
servers. Specifically, this allows "insert/update/delete" raw
queries to not fail, since they were introduced in MongoDB 2.6.
The module will interpret the raw query JSON, convert it to its
corresponding command and run it.
Caveat: only the minimally required raw query options are
supported in this mode.
Default value is “0 (disabled)”.
Example 1.6. Setting the compat_mode_2.4 parameter
...
modparam("cachedb_mongodb", "compat_mode_2.4", 1)
...
1.5.4. compat_mode_3.0 (int)
Switch the module into compatibility mode for MongoDB 2.6/3.0
servers. Specifically, this allows "find" raw queries to not
fail, since they were introduced in MongoDB 3.2. The module
will interpret the "find" raw query JSON, convert it to its
corresponding command and run it.
Caveat: only the minimally required options for "find" raw
queries are supported in this mode.
Default value is “0 (disabled)”.
Example 1.7. Setting the compat_mode_3.0 parameter
...
modparam("cachedb_mongodb", "compat_mode_3.0", 1)
...
1.6. Exported Functions
The module does not export functions to be used in
configuration script.
1.7. Raw Query Syntax
The cachedb_mongodb module supports raw queries, thus taking
full advantage of the capabilities of the back-end, including
query-specific options such as read/write preference, timeouts,
filtering options, etc.
The query syntax is identical to the mongo cli. Documentation
for it can be found on the MongoDB website. Query results are
returned as JSON documents, that one can further process in the
OpenSIPS script by using the JSON module.
Some example raw queries:
Example 1.8. MongoDB Raw Insert
...
cache_raw_query("mongodb:cluster", "{ \
\"insert\": \"ip_blacklist\", \
\"documents\": [{ \
\"username\": \"$fU\", \
\"ip\": \"$si\", \
\"attempts\": 1 \
}]}",
"$avp(out)");
xlog("INSERT RAW QUERY returned $rc, output: '$avp(out)'\n");
...
Example 1.9. MongoDB Raw Update
...
cache_raw_query("mongodb:cluster", "{ \
\"update\": \"ip_blacklist\", \
\"updates\": [{ \
\"q\": { \
\"username\": \"$fU\", \
\"ip\": \"$si\" \
}, \
\"u\": { \
\"$$inc\": {\"attempts\": 1} \
} \
}]}",
"$avp(out)");
xlog("UPDATE RAW QUERY returned $rc, output: '$avp(out)'\n");
...
Chapter 2. Contributors
2.1. By Commit Statistics
Table 2.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Liviu Chircu (@liviuchircu) 148 77 2827 2673
2. Vlad Paiu (@vladpaiu) 34 9 2964 50
3. Razvan Crainea (@razvancrainea) 13 11 31 28
4. Ovidiu Sas (@ovidiusas) 10 8 92 16
5. Vlad Patrascu (@rvlad-patrascu) 5 3 87 2
6. Bogdan-Andrei Iancu (@bogdan-iancu) 5 3 2 5
7. @jalung 4 1 97 56
8. Julián Moreno Patiño 3 1 1 1
9. Alessio Garzi (@Ozzyboshi) 2 1 1 0
(1) DevScore = author_commits + author_lines_added /
(project_lines_added / project_commits) + author_lines_deleted
/ (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding
merge commits. Regarding imported patches/code, we do our best
to count the work on behalf of the proper owner, as per the
"fix_authors" and "mod_renames" arrays in
opensips/doc/build-contrib.sh. If you identify any
patches/commits which do not get properly attributed to you,
please submit a pull request which extends "fix_authors" and/or
"mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated
files
2.2. By Commit Activity
Table 2.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Razvan Crainea (@razvancrainea) Aug 2015 - Dec 2020
2. Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2014 - Jun 2020
3. Vlad Patrascu (@rvlad-patrascu) May 2017 - Jun 2020
4. Liviu Chircu (@liviuchircu) Mar 2014 - Feb 2020
5. Alessio Garzi (@Ozzyboshi) Nov 2019 - Nov 2019
6. @jalung Aug 2017 - Aug 2017
7. Julián Moreno Patiño Feb 2016 - Feb 2016
8. Vlad Paiu (@vladpaiu) Jan 2013 - May 2015
9. Ovidiu Sas (@ovidiusas) Mar 2013 - Feb 2014
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei
Iancu (@bogdan-iancu), Julián Moreno Patiño, Vlad Paiu
(@vladpaiu).
doc copyrights:
Copyright © 2013-2017 www.opensips-solutions.com