Debian Codegraph @

src/modules/group/README

raw
1 group Module
2
3 Jan Janak
4
5 FhG FOKUS
6
7 Daniel-Constantin Mierla
8
9 <[email protected]>
10
11 Edited by
12
13 Jan Janak
14
15 Copyright © 2003 FhG FOKUS
16 __________________________________________________________________
17
18 Table of Contents
19
20 1. Admin Guide
21
22 1. Overview
23
24 1.1. Strict membership checking
25 1.2. Regular Expression based checking
26
27 2. Dependencies
28
29 2.1. Kamailio Modules
30 2.2. External Libraries or Applications
31
32 3. Parameters
33
34 3.1. db_url (string)
35 3.2. table (string)
36 3.3. user_column (string)
37 3.4. domain_column (string)
38 3.5. group_column (string)
39 3.6. use_domain (integer)
40 3.7. re_table (string)
41 3.8. re_exp_column (string)
42 3.9. re_gid_column (string)
43 3.10. multiple_gid (integer)
44
45 4. Functions
46
47 4.1. is_user_in(URI, group)
48 4.2. get_user_group(URI, AVP)
49
50 List of Examples
51
52 1.1. Set db_url parameter
53 1.2. Set table parameter
54 1.3. Set user_column parameter
55 1.4. Set domain_column parameter
56 1.5. Set group_column parameter
57 1.6. Set use_domain parameter
58 1.7. Set re_table parameter
59 1.8. Set re_exp_column parameter
60 1.9. Set re_gid_column parameter
61 1.10. Set multiple_gid parameter
62 1.11. is_user_in usage
63 1.12. get_user_group usage
64
65 Chapter 1. Admin Guide
66
67 Table of Contents
68
69 1. Overview
70
71 1.1. Strict membership checking
72 1.2. Regular Expression based checking
73
74 2. Dependencies
75
76 2.1. Kamailio Modules
77 2.2. External Libraries or Applications
78
79 3. Parameters
80
81 3.1. db_url (string)
82 3.2. table (string)
83 3.3. user_column (string)
84 3.4. domain_column (string)
85 3.5. group_column (string)
86 3.6. use_domain (integer)
87 3.7. re_table (string)
88 3.8. re_exp_column (string)
89 3.9. re_gid_column (string)
90 3.10. multiple_gid (integer)
91
92 4. Functions
93
94 4.1. is_user_in(URI, group)
95 4.2. get_user_group(URI, AVP)
96
97 1. Overview
98
99 1.1. Strict membership checking
100 1.2. Regular Expression based checking
101
102 This module provides functionality for two different methods of group
103 membership checking.
104
105 1.1. Strict membership checking
106
107 The module uses a database table that contains a list of users and
108 groups they belong to. The module provides the possibility to check if
109 a specific user belongs to a specific group.
110
111 There is no DB caching support, which means that each check involves a
112 DB query.
113
114 1.2. Regular Expression based checking
115
116 Another database table contains list of regular expressions and group
117 IDs. A matching occurs if the user URI match the regular expression.
118 This type of matching may be used to fetch the group ID(s) the user
119 belongs to (via RE matching) .
120
121 Due to performance reasons (regular expression evaluation), DB cache
122 support is available: the table content is loaded into memory at
123 startup and all regular expressions are compiled.
124
125 2. Dependencies
126
127 2.1. Kamailio Modules
128 2.2. External Libraries or Applications
129
130 2.1. Kamailio Modules
131
132 The following modules must be loaded before this module:
133 * A database module, like db_mysql, db_postgres or db_text
134
135 2.2. External Libraries or Applications
136
137 The following libraries or applications must be installed before
138 running Kamailio with this module loaded:
139 * None.
140
141 3. Parameters
142
143 3.1. db_url (string)
144 3.2. table (string)
145 3.3. user_column (string)
146 3.4. domain_column (string)
147 3.5. group_column (string)
148 3.6. use_domain (integer)
149 3.7. re_table (string)
150 3.8. re_exp_column (string)
151 3.9. re_gid_column (string)
152 3.10. multiple_gid (integer)
153
154 3.1. db_url (string)
155
156 URL of the database table to be used.
157
158 Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”.
159
160 Example 1.1. Set db_url parameter
161 ...
162 modparam("group", "db_url", "dbdriver://username:password@dbhost/dbname")
163 ...
164
165 3.2. table (string)
166
167 Name of the table holding strict definitions of groups and their
168 members.
169
170 Default value is “grp”.
171
172 Example 1.2. Set table parameter
173 ...
174 modparam("group", "table", "grp_table")
175 ...
176
177 3.3. user_column (string)
178
179 Name of the “table” column holding usernames.
180
181 Default value is “username”.
182
183 Example 1.3. Set user_column parameter
184 ...
185 modparam("group", "user_column", "user")
186 ...
187
188 3.4. domain_column (string)
189
190 Name of the “table” column holding domains.
191
192 Default value is “domain”.
193
194 Example 1.4. Set domain_column parameter
195 ...
196 modparam("group", "domain_column", "realm")
197 ...
198
199 3.5. group_column (string)
200
201 Name of the “table” column holding group names.
202
203 Default value is “grp”.
204
205 Example 1.5. Set group_column parameter
206 ...
207 modparam("group", "group_column", "grp")
208 ...
209
210 3.6. use_domain (integer)
211
212 If enabled (set to a non zero value) then the domain will be used also
213 used for strict group matching; otherwise only the username part will
214 be used.
215
216 Default value is 0 (disabled).
217
218 Example 1.6. Set use_domain parameter
219 ...
220 modparam("group", "use_domain", 1)
221 ...
222
223 3.7. re_table (string)
224
225 Name of the table holding definitions for regular-expression based
226 groups. If no table is defined, the regular-expression support is
227 disabled.
228
229 Default value is “NULL”.
230
231 Example 1.7. Set re_table parameter
232 ...
233 modparam("group", "re_table", "re_grp")
234 ...
235
236 3.8. re_exp_column (string)
237
238 Name of the “re_table” column holding the regular expression used for
239 user matching.
240
241 Default value is “reg_exp”.
242
243 Example 1.8. Set re_exp_column parameter
244 ...
245 modparam("group", "re_exp_column", "re")
246 ...
247
248 3.9. re_gid_column (string)
249
250 Name of the “re_table” column holding the group IDs.
251
252 Default value is “group_id”.
253
254 Example 1.9. Set re_gid_column parameter
255 ...
256 modparam("group", "re_gid_column", "grp_id")
257 ...
258
259 3.10. multiple_gid (integer)
260
261 If enabled (non zero value) the regular-expression matching will return
262 all group IDs that match the user; otherwise only the first will be
263 returned.
264
265 Default value is “1” (enabled).
266
267 Example 1.10. Set multiple_gid parameter
268 ...
269 modparam("group", "multiple_gid", 0)
270 ...
271
272 4. Functions
273
274 4.1. is_user_in(URI, group)
275 4.2. get_user_group(URI, AVP)
276
277 4.1. is_user_in(URI, group)
278
279 This function is to be used for script group membership. The function
280 returns true if username in the given URI is a member of the given
281 group and false if not.
282
283 Meaning of the parameters is as follows:
284 * URI - URI whose username and optionally domain to be used, this can
285 be one of:
286 + Request-URI - Use Request-URI username and (optionally)
287 domain.
288 + To - Use To username and (optionally) domain.
289 + From - Use From username and (optionally) domain.
290 + Credentials - Use digest credentials username.
291 + $avp(name) - Use the URI from the AVP specified by this
292 pseudo-variable.
293 * group - Name of the group to check.
294
295 This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
296
297 Example 1.11. is_user_in usage
298 ...
299 if (is_user_in("Request-URI", "ld")) {
300 ...
301 };
302 ...
303
304 4.2. get_user_group(URI, AVP)
305
306 This function is to be used for regular expression based group
307 membership. The function returns true if username in the given URI
308 belongs to at least one group; the group ID(s) are returned as AVPs.
309
310 Meaning of the parameters is as follows:
311 * URI - URI to be matched against the regular expressions:
312 + Request-URI - Use Request-URI
313 + To - Use To URI.
314 + From - Use From URI
315 + Credentials - Use digest credentials username and realm.
316 + $avp(name) - Use the URI from the AVP specified by this
317 pseudo-variable.
318 * AVP - $avp(name) - the matched group IDs are returned in this AVP.
319
320 This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
321
322 Example 1.12. get_user_group usage
323 ...
324 if (get_user_group("Request-URI", "$avp(i:10)")) {
325 xgdb("User $ru belongs to $(avp(i:10)[*]) group(s)\n");
326 ....
327 };
328 ...