935620c0df37f7f7d2de8e731a220ab4f2e59d01
[sip-router] / src / modules / permissions / doc / permissions_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 The Permissions module provides functions for handling
20                 IP based access control lists (ACL) in a number of ways.
21                 <itemizedlist>
22                 <listitem><para>
23                         Call Routing
24                 </para></listitem>
25                 <listitem><para>
26                         Registration permissions
27                 </para></listitem>
28                 <listitem><para>
29                         URI permissions
30                 </para></listitem>
31                 <listitem><para>
32                         Address permissions
33                 </para></listitem>
34                 <listitem><para>
35                         Trusted Requests
36                 </para></listitem>
37                 </itemizedlist>
38                 The Address permissions and Trusted request handling supports
39                 using a database to load ACLs into RAM for fast processing.
40         </para>
41         <section id="sec-call-routing">
42                 <title>Call Routing</title>
43                 <para>
44                 The module can be used to determine if a call has appropriate
45                 permission to be established. Permission rules are stored in
46                 plaintext configuration files similar to
47                 <filename moreinfo="none">hosts.allow</filename> and <filename
48                 moreinfo="none">hosts.deny</filename> files used by tcpd.
49                 </para>
50                 <para>
51                 When <function moreinfo="none">allow_routing</function> function is
52                 called it tries to find a rule that matches selected fields of the
53                 message.
54                 </para>
55                 <para>
56                 &kamailio; is a forking proxy and therefore a single message can be sent
57                 to different destinations simultaneously. When checking permissions
58                 all the destinations must be checked and if one of them fails, the
59                 forwarding will fail.
60                 </para>
61                 <para>
62                 The matching algorithm is as follows, first match wins:
63                 </para>
64                 <itemizedlist>
65                 <listitem>
66                         <para>
67                         Create a set of pairs of form (From, R-URI of branch 1),
68                         (From, R-URI of branch 2), etc.
69                         </para>
70                 </listitem>
71                 <listitem>
72                         <para>
73                         Routing will be allowed when all pairs match an entry in the
74                         allow file.
75                         </para>
76                 </listitem>
77                 <listitem>
78                         <para>
79                         Otherwise routing will be denied when one of pairs matches an
80                         entry in the deny file.
81                         </para>
82                 </listitem>
83                 <listitem>
84                         <para>
85                         Otherwise, routing will be allowed.
86                         </para>
87                 </listitem>
88                 </itemizedlist>
89                 <para>
90                 A non-existing permission control file is treated as if it were an
91                 empty file. Thus, permission control can be turned off by providing
92                 no permission control files.
93                 </para>
94                 <para>
95                 From header field and Request-URIs are always compared with regular
96                 expressions! For the syntax see the sample file:
97                 <filename moreinfo="none">config/permissions.allow</filename>.
98                 </para>
99         </section>
100         <section id="sec-registration-permissions">
101                 <title>Registration Permissions</title>
102                 <para>
103                 In addition to call routing it is also possible to check REGISTER
104                 messages and decide--based on the configuration files--whether the
105                 message should be allowed and the registration accepted or not.
106                 </para>
107                 <para>
108                 Main purpose of the function is to prevent registration of "prohibited"
109                 IP addresses. One example, when a malicious user registers a contact
110                 containing IP address of a PSTN gateway, he might be able to bypass
111                 authorization checks performed by the SIP proxy. That is undesirable
112                 and therefore attempts to register IP address of a PSTN gateway should
113                 be rejected. Files <filename
114                 moreinfo="none">config/register.allow</filename> and <filename
115                 moreinfo="none">config/register.deny</filename> contain an example
116                 configuration.
117                 </para>
118                 <para>
119                 The function for registration checking is called <function
120                 moreinfo="none">allow_register</function> and the algorithm is very
121                 similar to the algorithm described in
122                 <xref linkend="sec-call-routing"/>. The only difference is in the way
123                 how pairs are created.
124                 </para>
125                 <para>
126                 Instead of the From header field the function uses the To header field because
127                 th To header field in REGISTER messages contains the URI of the person
128                 being registered. Instead of the Request-URI of branches the function
129                 uses the Contact header field.
130                 </para>
131                 <para>
132                 Thus, the pairs used in matching will look like this: (To, Contact 1),
133                 (To, Contact 2), (To, Contact 3), and so on..
134                 </para>
135                 <para>
136                 The algorithm of matching is the same as described in
137                 <xref linkend="sec-call-routing"/>.
138                 </para>
139         </section>
140         <section id="sec-uri-permissions">
141                 <title>URI Permissions</title>
142                 <para>
143                 The module can be used to determine if a request to a destination
144                 is allowed, based on an URI stored in a pvar. Permission rules are
145                 stored in plaintext configuration files similar to
146                 <filename moreinfo="none">hosts.allow</filename> and
147                 <filename moreinfo="none">hosts.deny</filename> used by tcpd.
148                 </para>
149                 <para>
150                 When the <function moreinfo="none">allow_uri</function>
151                 function is called, it tries to find a rule that matches
152                 selected fields of the message.
153                 The matching algorithm is as follows, where the first match wins:
154                 </para>
155                 <itemizedlist>
156                 <listitem>
157                         <para>
158                         Create a pair &lt;From URI, URI stored in pvar&gt;.
159                         </para>
160                 </listitem>
161                 <listitem>
162                         <para>
163                         Request will be allowed when the pair matches
164                         an entry in the allow file.
165                         </para>
166                 </listitem>
167                 <listitem>
168                         <para>
169                         Request will be denied when the pair
170                         matches an entry in the deny file.
171                         </para>
172                 </listitem>
173                 <listitem>
174                         <para>
175                         Otherwise, request will be allowed.
176                         </para>
177                 </listitem>
178                 </itemizedlist>
179                 <para>
180                 A non-existing permission control file is treated as if it were an
181                 empty file. Thus, permission control can be turned off by providing
182                 no permission control files.
183                 </para>
184                 <para>
185                 The From URI and the URI stored in pvar are always compared with regular
186                 expressions! For the syntax see the sample file:
187                 <filename moreinfo="none">config/permissions.allow</filename>.
188                 </para>
189         </section>
190         <section id="sec-address-permissions">
191                 <title>Address Permissions</title>
192                 <para>
193                 The module can be used to determine if an address (IP
194                 address and port or DNS domain name) matches any of the
195                 addresses stored in a cached &kamailio; database table.
196                 IP addresses in the database table can be subnet addresses.
197                 Port 0 in cached database table matches any port. The
198                 address and port to be matched can be either taken from
199                 the request (allow_source_address) or given as pvar
200                 arguments (allow_address).
201                 </para>
202                 <para>
203                 Addresses stored in the database table can be grouped
204                 together into one or more groups specified by a group
205                 identifier (positive integer value, i.e., equal or greater than 1).
206                 The group identifier is given as an argument to the allow_address() and
207                 allow_source_address() functions.
208                 One group can contain all of the three types of addresses: exact
209                 IP address, subnet IP address or DNS domain name.
210                 </para>
211                 <para>
212                 When the argument is an IP address, it is tried to be matched with the
213                 records from that group that are of type exact IP or subnet. If the
214                 argument is not an IP it is tried to be matched
215                 with the records that are DNS domain names. No DNS lookup is performed,
216                 only strict matching.
217                 </para>
218                 <para>
219                 As a side effect of matching the address, non-NULL tag
220                 (see tag_col module parameter) is added as value to
221                 peer_tag AVP if peer_tag_avp module parameter has been defined.
222                 </para>
223         </section>
224         <section id="sec-trusted-requests">
225                 <title>Trusted Requests</title>
226                 <para>
227                 The module can be used to determine if an incoming
228                 request can be trusted without authentication.
229                 </para>
230                 <para>
231                 When the <function moreinfo="none">allow_trusted</function>
232                 function is called, it tries to find a rule that matches
233                 the request.  Rules contain the following fields:
234                 &lt;source address, transport protocol, regular
235                 expression&gt;.
236                 </para>
237                 <para>
238                 A requests is accepted if there exists a rule, where
239                 </para>
240                 <itemizedlist>
241                 <listitem>
242                         <para>
243                         source address is equal to the source address of
244                         the request or the source address given in pvar,
245                         </para>
246                 </listitem>
247                 <listitem>
248                         <para>
249                         transport protocol is either "ANY" or equal to
250                         the transport protocol of request or the transport
251                         protocol given in pvar, and
252                         </para>
253                 </listitem>
254                 <listitem>
255                         <para>
256                         regular expression is either empty (NULL in
257                         database) or matches the request's From (or optionally provided) URI.
258                         </para>
259                 </listitem>
260                 </itemizedlist>
261                 <para>
262                 Otherwise the request is rejected.
263                 </para>
264                 <para>
265                 As a side effect of accepting the request, the peer's
266         non-NULL tag (see tag_col module parameter) is added as value to
267         peer_tag AVP if the peer_tag_avp module parameter has been defined.
268                 </para>
269                 <para>
270                 Rules are stored in a database table specified by the module
271                 parameters.  There is a module parameter called
272                 <varname>db_mode</varname> that
273                 determines if the rules are cached into memory for faster
274                 matching or if the database is consulted for each invocation
275                 of the allow_trusted() function call.
276                 </para>
277         </section>
278         </section>
279
280         <section>
281         <title>Dependencies</title>
282         <section>
283                 <title>&kamailio; Modules</title>
284                 <para>
285                 The following modules must be loaded before this module:
286                         <itemizedlist>
287                         <listitem>
288                         <para>
289                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
290                         </para>
291                         </listitem>
292                         </itemizedlist>
293                 </para>
294         </section>
295         <section>
296                 <title>External Libraries or Applications</title>
297                 <para>
298                 The following libraries or applications must be installed before running
299                 &kamailio; with this module loaded:
300                         <itemizedlist>
301                         <listitem>
302                         <para>
303                                 <emphasis>None</emphasis>.
304                         </para>
305                         </listitem>
306                         </itemizedlist>
307                 </para>
308         </section>
309         </section>
310
311         <section>
312         <title>Parameters</title>
313         <section id ="permissions.p.default_allow_file">
314                 <title><varname>default_allow_file</varname> (string)</title>
315                 <para>
316                 Default allow file used by the functions with no parameters. If you
317                 don't specify a full pathname then the directory in which is the main
318                 config file is located will be used.
319                 </para>
320                 <para>
321                 <emphasis>
322                         Default value is <quote>permissions.allow</quote>.
323                 </emphasis>
324                 </para>
325                 <example>
326                 <title>Set <varname>default_allow_file</varname> parameter</title>
327                 <programlisting format="linespecific">
328 ...
329 modparam("permissions", "default_allow_file", "/etc/permissions.allow")
330 ...
331 </programlisting>
332                 </example>
333         </section>
334         <section id ="permissions.p.default_deny_file">
335                 <title><varname>default_deny_file</varname> (string)</title>
336                 <para>
337                 Default file containing deny rules. The file is used by functions
338                 with no parameters. If you don't specify a full pathname then the
339                 directory in which the main config file is located will be used.
340                 </para>
341                 <para>
342                 <emphasis>
343                         Default value is <quote>permissions.deny</quote>.
344                 </emphasis>
345                 </para>
346                 <example>
347                 <title>Set <varname>default_deny_file</varname> parameter</title>
348                 <programlisting format="linespecific">
349 ...
350 modparam("permissions", "default_deny_file", "/etc/permissions.deny")
351 ...
352 </programlisting>
353                 </example>
354         </section>
355         <section id ="permissions.p.check_all_branches">
356                 <title><varname>check_all_branches</varname> (integer)</title>
357                 <para>
358                 If set then allow_routing functions will check Request-URI of all
359                 branches (default). If disabled then only Request-URI of the first
360                 branch will be checked.
361                 </para>
362                 <warning>
363                 <para>
364                 Do not disable this parameter unless you really know what you
365                 are doing.
366                 </para>
367                 </warning>
368                 <para>
369                 <emphasis>
370                         Default value is 1.
371                 </emphasis>
372                 </para>
373                 <example>
374                 <title>Set <varname>check_all_branches</varname> parameter</title>
375                 <programlisting format="linespecific">
376 ...
377 modparam("permissions", "check_all_branches", 0)
378 ...
379 </programlisting>
380                 </example>
381         </section>
382         <section id ="permissions.p.allow_suffix">
383                 <title><varname>allow_suffix</varname> (string)</title>
384                 <para>
385                 Suffix to be appended to basename to create filename of the allow
386                 file when version with one parameter of either
387                 <function moreinfo="none">allow_routing</function> or
388                 <function moreinfo="none">allow_register</function> is used.
389                 </para>
390                 <note>
391                 <para>
392                         Including leading dot.
393                 </para>
394                 </note>
395                 <para>
396                 <emphasis>
397                         Default value is <quote>.allow</quote>.
398                 </emphasis>
399                 </para>
400                 <example>
401                 <title>Set <varname>allow_suffix</varname> parameter</title>
402                 <programlisting format="linespecific">
403 ...
404 modparam("permissions", "allow_suffix", ".allow")
405 ...
406 </programlisting>
407                 </example>
408         </section>
409         <section id ="permissions.p.deny_suffix">
410                 <title><varname>deny_suffix</varname> (string)</title>
411                 <para>
412                 Suffix to be appended to basename to create filename of the deny file
413                 when version with one parameter of either
414                 <function moreinfo="none">allow_routing</function> or
415                 <function moreinfo="none">allow_register</function> is used.
416                 </para>
417                 <note>
418                 <para>
419                         Including leading dot.
420                 </para>
421                 </note>
422                 <para>
423                 <emphasis>
424                         Default value is <quote>.deny</quote>.
425                 </emphasis>
426                 </para>
427                 <example>
428                 <title>Set <varname>deny_suffix</varname> parameter</title>
429                 <programlisting format="linespecific">
430 ...
431 modparam("permissions", "deny_suffix", ".deny")
432 ...
433 </programlisting>
434                 </example>
435         </section>
436         <section id ="permissions.p.db_url">
437                 <title><varname>db_url</varname> (string)</title>
438                 <para>
439                 This is URL of the database to be used to store rules used by
440                 <function moreinfo="none">allow_trusted</function> function.
441                 </para>
442                 <para>
443                 <emphasis>
444                         Default value is <quote>NULL</quote>.
445                 </emphasis>
446                 </para>
447                 <example>
448                 <title>Set <varname>db_url</varname> parameter</title>
449                 <programlisting format="linespecific">
450 ...
451 modparam("permissions", "db_url", "&exampledb;")
452 ...
453 </programlisting>
454                 </example>
455         </section>
456         <section id ="permissions.p.address_table">
457                 <title><varname>address_table</varname> (string)</title>
458                 <para>
459                 The name of the database table containing IP subnets and DNS domain names used by
460                 <function moreinfo="none">allow_address</function> and
461                 <function moreinfo="none">allow_source_address</function>
462                 functions.
463                 </para>
464                 <para>
465                 <emphasis>
466                 Default value is <quote>address</quote>.
467                 </emphasis>
468                 </para>
469                 <example>
470                 <title>Set <varname>address_table</varname> parameter</title>
471                 <programlisting format="linespecific">
472 ...
473 modparam("permissions", "address_table", "addr")
474 ...
475 </programlisting>
476                 </example>
477         </section>
478         <section id ="permissions.p.grp_col">
479                 <title><varname>grp_col</varname> (string)</title>
480                 <para>
481                 Name of address table column containing the group
482                 identifier of the address.
483                 </para>
484                 <para>
485                 <emphasis>
486                 Default value is <quote>grp</quote>.
487                 </emphasis>
488                 </para>
489                 <example>
490                 <title>Set <varname>grp_col</varname> parameter</title>
491                 <programlisting format="linespecific">
492 ...
493 modparam("permissions", "grp_col", "group_id")
494 ...
495 </programlisting>
496                 </example>
497         </section>
498         <section id ="permissions.p.ip_addr_col">
499                 <title><varname>ip_addr_col</varname> (string)</title>
500                 <para>
501                 Name of address table column containing the IP address
502                 part of the address.
503                 </para>
504                 <para>
505                 <emphasis>
506                 Default value is <quote>ip_addr</quote>.
507                 </emphasis>
508                 </para>
509                 <example>
510                 <title>Set <varname>ip_addr_col</varname> parameter</title>
511                 <programlisting format="linespecific">
512 ...
513 modparam("permissions", "ip_addr_col", "ip_address")
514 ...
515 </programlisting>
516                 </example>
517         </section>
518         <section id ="permissions.p.mask_col">
519                 <title><varname>mask_col</varname> (string)</title>
520                 <para>
521                 Name of address table column containing the network mask of
522                 the address.  Possible values are 0-32 for IPv4 and 0-128 for
523                 IPv6 addresses.
524                 </para>
525                 <para>
526                 <emphasis>
527                 Default value is <quote>mask</quote>.
528                 </emphasis>
529                 </para>
530                 <example>
531                 <title>Set <varname>mask_col</varname> parameter</title>
532                 <programlisting format="linespecific">
533 ...
534 modparam("permissions", "mask_col", "subnet_length")
535 ...
536 </programlisting>
537                 </example>
538         </section>
539         <section id ="permissions.p.port_col">
540                 <title><varname>port_col</varname> (string)</title>
541                 <para>
542                 Name of address table column containing the port
543                 part of the address.
544                 </para>
545                 <para>
546                 <emphasis>
547                 Default value is <quote>port</quote>.
548                 </emphasis>
549                 </para>
550                 <example>
551                 <title>Set <varname>port_col</varname> parameter</title>
552                 <programlisting format="linespecific">
553 ...
554 modparam("permissions", "port_col", "port")
555 ...
556 </programlisting>
557                 </example>
558         </section>
559         <section id ="permissions.p.db_mode">
560                 <title><varname>db_mode</varname> (integer)</title>
561                 <para>
562                 Database mode. 0 means non-caching, 1 means caching.
563                 Valid only for the <function moreinfo="none">allow_trusted</function> function.
564                 </para>
565                 <para>
566                 <emphasis>
567                         Default value is 0 (non-caching).
568                 </emphasis>
569                 </para>
570                 <example>
571                 <title>Set <varname>db_mode</varname> parameter</title>
572                 <programlisting format="linespecific">
573 ...
574 modparam("permissions", "db_mode", 1)
575 ...
576 </programlisting>
577                 </example>
578         </section>
579         <section id ="permissions.p.trusted_table">
580                 <title><varname>trusted_table</varname> (string)</title>
581                 <para>
582                 Name of database table containing the matching rules used by
583                 the <function moreinfo="none">allow_trusted</function> function.
584                 </para>
585                 <para>
586                 <emphasis>
587                 Default value is <quote>trusted</quote>.
588                 </emphasis>
589                 </para>
590                 <example>
591                 <title>Set <varname>trusted_table</varname> parameter</title>
592                 <programlisting format="linespecific">
593 ...
594 modparam("permissions", "trusted_table", "pbx")
595 ...
596 </programlisting>
597                 </example>
598         </section>
599         <section id ="permissions.p.source_col">
600                 <title><varname>source_col</varname> (string)</title>
601                 <para>
602                 Name of column in the <quote>trusted</quote> table containing the source IP
603                 address that is matched against source IP address of
604                 received request.
605                 </para>
606                 <para>
607                 <emphasis>
608                 Default value is <quote>src_ip</quote>.
609                 </emphasis>
610                 </para>
611                 <example>
612                 <title>Set <varname>source_col</varname> parameter</title>
613                 <programlisting format="linespecific">
614 ...
615 modparam("permissions", "source_col", "source_ip_address")
616 ...
617 </programlisting>
618                 </example>
619         </section>
620         <section id ="permissions.p.proto_col">
621                 <title><varname>proto_col</varname> (string)</title>
622                 <para>
623                 Name of column in the <quote>trusted</quote> table containing the transport
624                 protocol that is matched against transport protocol of
625                 the received request.  Possible values that can be stored in
626                 proto_col are <quote>any</quote>, <quote>udp</quote>,
627                 <quote>tcp</quote>, <quote>tls</quote>,
628                 <quote>sctp</quote>, <quote>ws</quote>, <quote>wss</quote>,
629                 and <quote>none</quote>.  Value
630                 <quote>any</quote> matches always and value
631                 <quote>none</quote> never.
632                 </para>
633                 <para>
634                 <emphasis>
635                         Default value is <quote>proto</quote>.
636                 </emphasis>
637                 </para>
638                 <example>
639                 <title>Set <varname>proto_col</varname> parameter</title>
640                 <programlisting format="linespecific">
641 ...
642 modparam("permissions", "proto_col", "transport")
643 ...
644 </programlisting>
645                 </example>
646         </section>
647         <section id ="permissions.p.from_col">
648                 <title><varname>from_col</varname> (string)</title>
649                 <para>
650                 Name of the column trusted table containing a regular
651                 expression that is matched against the From URI.
652                 </para>
653                 <para>
654                 <emphasis>
655                 Default value is <quote>from_pattern</quote>.
656                 </emphasis>
657                 </para>
658                 <example>
659                 <title>Set <varname>from_col</varname> parameter</title>
660                 <programlisting format="linespecific">
661 ...
662 modparam("permissions", "from_col", "regexp")
663 ...
664 </programlisting>
665                 </example>
666         </section>
667         <section id ="permissions.p.ruri_col">
668                 <title><varname>ruri_col</varname> (string)</title>
669                 <para>
670                 Name of the column trusted table containing a regular
671                 expression that is matched against the Request URI.
672                 </para>
673                 <para>
674                 <emphasis>
675                 Default value is <quote>ruri_pattern</quote>.
676                 </emphasis>
677                 </para>
678                 <example>
679                 <title>Set <varname>ruri_col</varname> parameter</title>
680                 <programlisting format="linespecific">
681 ...
682 modparam("permissions", "ruri_col", "regexp")
683 ...
684 </programlisting>
685                 </example>
686         </section>
687         <section id ="permissions.p.tag_col">
688                 <title><varname>tag_col</varname> (string)</title>
689                 <para>
690                 Name of the column in the <quote>address</quote> or
691                 <quote>trusted</quote> table containing a string
692                 that is added as value to peer_tag AVP if peer_tag AVP
693                 has been defined and if the address or peer matches.
694                 </para>
695                 <para>
696                 <emphasis>
697                 Default value is <quote>tag</quote>.
698                 </emphasis>
699                 </para>
700                 <example>
701                 <title>Set <varname>tag_col</varname> parameter</title>
702                 <programlisting format="linespecific">
703 ...
704 modparam("permissions", "tag_col", "peer_tag")
705 ...
706 </programlisting>
707                 </example>
708         </section>
709         <section id ="permissions.p.priority_col">
710                 <title><varname>priority_col</varname> (string)</title>
711                 <para>
712                 The column name used to store the priority of the corresponding rule from the database
713                 row. Priority values should be integer. When db_mode is set to 1 (caching), priorities
714                 are ordered from highest to lowest. In non-caching mode, priority order (ASC vs DESC)
715                 is determined by database.
716                 </para>
717                 <para>
718                 <emphasis>
719                 Default value is <quote>priority</quote>.
720                 </emphasis>
721                 </para>
722                 <example>
723                 <title>Set <varname>priority_col</varname> parameter</title>
724                 <programlisting format="linespecific">
725 ...
726 modparam("permissions", "priority_col", "column_name")
727 ...
728 </programlisting>
729                 </example>
730         </section>
731         <section id ="permissions.p.peer_tag_avp">
732                 <title><varname>peer_tag_avp</varname> (AVP string)</title>
733                 <para>
734                 If defined, the AVP will be
735                 set as a side effect of <function moreinfo="none">allow_trusted</function>
736                 call to not NULL tag column value of the matching peer.
737                 </para>
738                 <para>
739                 <emphasis>
740                 Default value is <quote>undefined</quote>.
741                 </emphasis>
742                 </para>
743                 <example>
744                 <title>Set <varname>peer_tag_avp</varname> parameter</title>
745                 <programlisting format="linespecific">
746 ...
747 modparam("permissions", "peer_tag_avp", "$avp(i:707)")
748 ...
749 </programlisting>
750                 </example>
751         </section>
752         <section id ="permissions.p.peer_tag_mode">
753                 <title><varname>peer_tag_mode</varname> (integer)</title>
754                 <para>
755                 Tag mode for <function moreinfo="none">allow_trusted</function>.
756                 <quote>0</quote> sets only the tag of the first match.
757                 <quote>1</quote> adds the tags of all matches to the avp. In addition
758                 the return value of <function moreinfo="none">allow_trusted</function>
759                 is the number of matches. This parameter is not used for address table matching functions.
760                 </para>
761                 <para>
762                 <emphasis>
763                 Default value is <quote>0</quote>.
764                 </emphasis>
765                 </para>
766                 <example>
767                 <title>Set <varname>peer_tag_mode</varname> parameter</title>
768                 <programlisting format="linespecific">
769 ...
770 modparam("permissions", "peer_tag_mode", 1)
771 ...
772 </programlisting>
773                 </example>
774         </section>
775         <section id ="permissions.p.max_subnets">
776                 <title><varname>max_subnets</varname> (int)</title>
777                 <para>
778                         The maximum number of subnet addresses to be loaded from
779                         address table.
780                 </para>
781                 <para>
782                 <emphasis>
783                 Default value is <quote>512</quote>.
784                 </emphasis>
785                 </para>
786                 <example>
787                 <title>Set <varname>max_subnets</varname> parameter</title>
788                 <programlisting format="linespecific">
789 ...
790 modparam("permissions", "max_subnets", 1024)
791 ...
792 </programlisting>
793                 </example>
794         </section>
795         <section id ="permissions.p.load_backends">
796                 <title><varname>load_backends</varname> (int)</title>
797                 <para>
798                         Control what backends should be loaded: 1 - address table;
799                         2 - trusted table; 4 - allow file; 8 - deny file.
800                 </para>
801                 <para>
802                         It can be a combination (sum) of the options to load many backends
803                         (e.g., 3 - loads address and trusted tables).
804                 </para>
805                 <para>
806                 <emphasis>
807                 Default value is <quote>0xffff</quote> (load all backends).
808                 </emphasis>
809                 </para>
810                 <example>
811                 <title>Set <varname>load_backends</varname> parameter</title>
812                 <programlisting format="linespecific">
813 ...
814 modparam("permissions", "load_backends", 1)
815 ...
816 </programlisting>
817                 </example>
818         </section>
819         </section>
820
821         <section>
822         <title>Functions</title>
823         <section id ="permissions.f.allow_routing">
824                 <title>
825                 <function moreinfo="none">allow_routing()</function>
826                 </title>
827                 <para>
828                 Returns true if all pairs constructed as described in <xref
829                         linkend="sec-call-routing"/> have appropriate permissions according to
830                 the configuration files. This function uses default configuration
831                 files specified in <varname>default_allow_file</varname> and
832                 <varname>default_deny_file</varname>.
833                 </para>
834                 <para>
835                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
836                 </para>
837                 <example>
838                 <title><function>allow_routing</function> usage</title>
839                 <programlisting format="linespecific">
840 ...
841 if (allow_routing()) {
842         t_relay();
843 };
844 ...
845 </programlisting>
846                 </example>
847         </section>
848         <section id ="permissions.f.allow_routing_basename">
849                 <title>
850                 <function moreinfo="none">allow_routing(basename)</function>
851                 </title>
852                 <para>
853                 Returns true if all pairs constructed as described in <xref
854                         linkend="sec-call-routing"/> have appropriate permissions according
855                 to the configuration files given as parameters.
856                 </para>
857                 <para>Meaning of the parameters is as follows:</para>
858                 <itemizedlist>
859                 <listitem>
860                         <para><emphasis>basename</emphasis> - Basename from which allow
861                         and deny filenames will be created by appending contents of
862                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
863                         parameters.
864                         </para>
865                         <para>
866                         If the parameter doesn't contain full pathname then the function
867                         expects the file to be located in the same directory as the main
868                         configuration file of the server.
869                         </para>
870                 </listitem>
871                 </itemizedlist>
872                 <para>
873                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
874                 </para>
875                 <example>
876                 <title><function>allow_routing(basename)</function> usage</title>
877                 <programlisting format="linespecific">
878 ...
879 if (allow_routing("basename")) {
880         t_relay();
881 };
882 ...
883 </programlisting>
884                 </example>
885         </section>
886         <section id ="permissions.f.allow_routing_fileargs">
887                 <title>
888                 <function moreinfo="none">allow_routing(allow_file,deny_file)</function>
889                 </title>
890                 <para>
891                 Returns true if all pairs constructed as described in
892                 <xref linkend="sec-call-routing"/> have appropriate permissions
893                 according to the configuration files given as parameters.
894                 </para>
895                 <para>Meaning of the parameters is as follows:</para>
896                 <itemizedlist>
897                 <listitem>
898                         <para><emphasis>allow_file</emphasis> - File containing allow rules.
899                         </para>
900                         <para>
901                         If the parameter doesn't contain full pathname then the function
902                         expects the file to be located in the same directory as the main
903                         configuration file of the server.
904                         </para>
905                 </listitem>
906                 <listitem>
907                         <para><emphasis>deny_file</emphasis> - File containing deny rules.
908                         </para>
909                         <para>
910                         If the parameter doesn't contain full pathname then the function
911                         expects the file to be located in the same directory as the main
912                         configuration file of the server.
913                         </para>
914                 </listitem>
915                 </itemizedlist>
916                 <para>
917                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
918                 </para>
919                 <example>
920                 <title><function>allow_routing(allow_file, deny_file)</function> usage</title>
921                 <programlisting format="linespecific">
922 ...
923 if (allow_routing("rules.allow", "rules.deny")) {
924         t_relay();
925 };
926 ...
927 </programlisting>
928                 </example>
929         </section>
930         <section id ="permissions.f.allow_register">
931                 <title>
932                 <function moreinfo="none">allow_register(basename)</function>
933                 </title>
934                 <para>
935                 The function returns true if all pairs constructed as described in <xref
936                         linkend="sec-registration-permissions"/> have appropriate permissions
937                 according to the configuration files given as parameters.
938                 </para>
939                 <para>Meaning of the parameters is as follows:</para>
940                 <itemizedlist>
941                 <listitem>
942                         <para><emphasis>basename</emphasis> - Basename from which allow
943                         and deny filenames will be created by appending contents of
944                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
945                         parameters.
946                         </para>
947                         <para>
948                         If the parameter doesn't contain full pathname then the function
949                         expects the file to be located in the same directory as the main
950                         configuration file of the server.
951                         </para>
952                 </listitem>
953                 </itemizedlist>
954                 <para>
955                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
956                 </para>
957                 <example>
958                 <title><function>allow_register(basename)</function> usage</title>
959                 <programlisting format="linespecific">
960 ...
961 if (method=="REGISTER") {
962         if (allow_register("register")) {
963                 save("location");
964                 exit;
965         } else {
966                 sl_send_reply("403", "Forbidden");
967         };
968 };
969 ...
970 </programlisting>
971                 </example>
972         </section>
973         <section id ="permissions.f.allow_register_fileargs">
974                 <title>
975                 <function moreinfo="none">allow_register(allow_file, deny_file)</function>
976                 </title>
977                 <para>
978                 The function returns true if all pairs constructed as described in
979                 <xref linkend="sec-registration-permissions"/> have appropriate
980                 permissions according to the configuration files given as parameters.
981                 </para>
982                 <para>Meaning of the parameters is as follows:</para>
983                 <itemizedlist>
984                 <listitem>
985                         <para><emphasis>allow_file</emphasis> - File containing allow rules.
986                         </para>
987                         <para>
988                         If the parameter doesn't contain full pathname then the function
989                         expects the file to be located in the same directory as the main
990                         configuration file of the server.
991                         </para>
992                 </listitem>
993                 <listitem>
994                         <para><emphasis>deny_file</emphasis> - File containing deny rules.
995                         </para>
996                         <para>
997                         If the parameter doesn't contain full pathname then the function
998                         expects the file to be located in the same directory as the main
999                         configuration file of the server.
1000                         </para>
1001                 </listitem>
1002                 </itemizedlist>
1003                 <para>
1004                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1005                 </para>
1006                 <example>
1007                 <title><function>allow_register(allow_file, deny_file)</function> usage</title>
1008                 <programlisting format="linespecific">
1009 ...
1010 if (method=="REGISTER") {
1011         if (allow_register("register.allow", "register.deny")) {
1012                 save("location");
1013                 exit;
1014         } else {
1015                 sl_send_reply("403", "Forbidden");
1016         };
1017 };
1018 ...
1019 </programlisting>
1020                 </example>
1021         </section>
1022         <section id ="permissions.f.allow_uri">
1023                 <title>
1024                 <function moreinfo="none">allow_uri(basename, pvar)</function>
1025                 </title>
1026                 <para>
1027                 Returns true if the pair constructed as described in <xref
1028                         linkend="sec-uri-permissions"/> have appropriate permissions
1029                 according to the configuration files specified by the parameter.
1030                 </para>
1031                 <para>Meaning of the parameter is as follows:</para>
1032                 <itemizedlist>
1033                 <listitem>
1034                         <para><emphasis>basename</emphasis> - Basename from which allow
1035                         and deny filenames will be created by appending contents of
1036                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
1037                         parameters.
1038                         </para>
1039                         <para>
1040                         If the parameter doesn't contain full pathname then the function
1041                         expects the file to be located in the same directory as the main
1042                         configuration file of the server.
1043                         </para>
1044                 </listitem>
1045                 <listitem>
1046                         <para><emphasis>pvar</emphasis> - Any
1047                         pseudo-variable defined in &kamailio;.
1048                         </para>
1049                 </listitem>
1050                 </itemizedlist>
1051                 <para>
1052                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1053                 </para>
1054                 <example>
1055                 <title><function>allow_uri(basename, pvar)</function> usage</title>
1056                 <programlisting format="linespecific">
1057 ...
1058 if (allow_uri("basename", "$rt")) {  // Check Refer-To URI
1059         t_relay();
1060 };
1061 if (allow_uri("basename", "$avp(i:705)") {  // Check URI stored in $avp(i:705)
1062         t_relay();
1063 };
1064 ...
1065 </programlisting>
1066                 </example>
1067         </section>
1068         <section id ="permissions.f.allow_address">
1069                 <title>
1070                 <function moreinfo="none">allow_address(group_id, ip_addr_pvar, port_pvar)</function>
1071                 </title>
1072                 <para>
1073                 Returns true if the address and port given as values of pvar
1074                 arguments belonging to a group given as group_id argument
1075                 matches an IP subnet or a DNS domain name found in cached
1076                 address table.
1077                 </para>
1078                 <para>
1079                 When matching is done if the argument is an IP address, it is
1080                 matched with the records from that group that are of type exact
1081                 IP or subnet. If the argument is not an IP it is tried to be matched
1082                 with the records that are DNS domain names. No DNS lookup is performed,
1083                 only strict matching.
1084                 Cached address table entry containing port value <quote>0</quote>
1085                 matches any port. The <quote>group_id</quote> argument can be an integer
1086                 string or a pseudo variable.
1087                 </para>
1088                 <para>
1089                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1090                 </para>
1091                 <example>
1092                 <title><function>allow_address()</function> usage</title>
1093                 <programlisting format="linespecific">
1094 ...
1095
1096 // Check if source address/port is in group 1
1097 if (!allow_address("1", "$si", "$sp")) {
1098         sl_send_reply("403", "Forbidden");
1099 };
1100 // Check address/port stored in AVPs src_adr/src_port is in group 2
1101 $avp(dst_adr) = "sipdomain.com";
1102 $avp(dst_port) = "0";
1103 if (!allow_address("2", "$avp(dst_adr)", "$avp(dst_port)") {
1104         sl_send_reply("403", "Forbidden");
1105 };
1106 ...
1107 </programlisting>
1108                 </example>
1109         </section>
1110         <section id ="permissions.f.allow_source_address">
1111                 <title>
1112                 <function moreinfo="none">allow_source_address([group_id])</function>
1113                 </title>
1114                 <para>
1115                 Equal to <quote>allow_address(group_id, "$si", "$sp")</quote>. If 'group_id' is
1116                 missing, the function is equal to allow_address("1", "$si", "$sp").
1117                 </para>
1118                 <para>
1119                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1120                 </para>
1121                 <example>
1122                 <title><function>allow_source_address(group_id)</function> usage</title>
1123                 <programlisting format="linespecific">
1124 ...
1125
1126 // Check source address/port of request
1127 if (!allow_source_address("1")) {
1128         sl_send_reply("403", "Forbidden");
1129 };
1130 ...
1131 </programlisting>
1132                 </example>
1133         </section>
1134         <section id ="permissions.f.allow_source_address_group">
1135                 <title>
1136                 <function moreinfo="none">allow_source_address_group()</function>
1137                 </title>
1138                 <para>
1139                 Checks if source address/port is found in cached address or
1140                 subnet table in any group. If yes, returns that group.
1141                 If not returns -1.  Port value 0 in cached address and
1142                 group table matches any port.
1143                 </para>
1144                 <para>
1145                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1146                 </para>
1147                 <example>
1148                 <title><function>allow_source_address_group()</function> usage</title>
1149                 <programlisting format="linespecific">
1150 ...
1151
1152 $var(group) = allow_source_address_group();
1153 if ($var(group) != -1) {
1154    # do something with $var(group)
1155 };
1156 ...
1157 </programlisting>
1158                 </example>
1159         </section>
1160         <section id ="permissions.f.allow_address_group">
1161                 <title>
1162                 <function moreinfo="none">allow_address_group(addr, port)</function>
1163                 </title>
1164                 <para>
1165                 Checks if address/port is found in cached address or
1166                 subnet table in any group. If yes, returns that group.
1167                 If not returns -1.  Port value 0 in cached address and
1168                 group table matches any port. The parameters can be pseudo-variables.
1169                 </para>
1170                 <para>
1171                 This function can be used from ANY_ROUTE.
1172                 </para>
1173                 <example>
1174                 <title><function>allow_source_address_group()</function> usage</title>
1175                 <programlisting format="linespecific">
1176 ...
1177
1178 $var(group) = allow_address_group("1.2.3.4", "5060");
1179 if ($var(group) != -1) {
1180    # do something with $var(group)
1181 };
1182 ...
1183 </programlisting>
1184                 </example>
1185         </section>
1186         <section id ="permissions.f.allow_trusted">
1187                 <title>
1188                 <function moreinfo="none">allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])</function>
1189                 </title>
1190                 <para>
1191                 Checks based either on request's source address and transport
1192                 protocol or source address and transport protocol given
1193                 in pvar arguments, and From URI of request (or furi_pvar if provided)
1194                 if request can be trusted without
1195                 authentication.  Returns <quote>1</quote> if a match is found
1196                 as described in <xref linkend="sec-trusted-requests"/>
1197                 and <quote>-1</quote> otherwise.  If a match is found
1198                 and <varname>peer_tag_avp</varname> has been defined, adds a
1199                 non-NULL tag column value of the
1200                 matching peer to AVP peer_tag_avp.
1201                 </para>
1202                 <para>
1203                 NOTE: source IP is matched using string comparison. Be careful if the
1204                 IP can have different forms, for a safer alternative for matching IP
1205                 addresses, look at allow_source_address or allow_address().
1206                 </para>
1207                 <para>
1208                 Source address, transport protocol and uri given in the
1209                 arguments must be in string format and they can contain script variables.
1210                 Valid transport protocol values are (ignoring case) "any", "udp, "tcp", "tls",
1211                 "ws", "wss" and "sctp".
1212                 </para>
1213                 <para>
1214                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1215                 </para>
1216                 <example>
1217                 <title><function>allow_trusted()</function> usage</title>
1218                 <programlisting format="linespecific">
1219 ...
1220 if (allow_trusted()) {
1221         t_relay();
1222 }
1223 ...
1224 if (allow_trusted("$si", "$proto")) {
1225         t_relay();
1226 }
1227 ...
1228 if (allow_trusted("$si", "any", "$ai")) {
1229         t_relay();
1230 }
1231 ...
1232 </programlisting>
1233                 </example>
1234         </section>
1235         </section>
1236
1237         <section>
1238         <title>RPC Commands</title>
1239         <section id ="permissions.r.addressReload">
1240                 <title>
1241                 <function moreinfo="none">permissions.addressReload</function>
1242                 </title>
1243                 <para>
1244                         Causes the permissions module to re-read the contents of
1245                         address database table into cache
1246                         memory.  In cache memory the entries are
1247                         for performance reasons stored in two
1248                         different tables:  address table and
1249                         subnet table depending on the value of
1250                         the mask field (IPv6: 64 or smaller, IPv4: 32 or smaller).
1251                 </para>
1252                 <para>Parameters: <emphasis>none</emphasis></para>
1253         </section>
1254
1255         <section id ="permissions.r.addressDump">
1256                 <title>
1257                 <function moreinfo="none">permissions.addressDump</function>
1258                 </title>
1259                 <para>
1260                         Causes the permissions module to dump
1261                         the contents of cache memory address table.
1262                         (Not the subnet table).
1263
1264                 </para>
1265                 <para>Parameters: <emphasis>none</emphasis></para>
1266         </section>
1267
1268         <section id ="permissions.r.subnetDump">
1269                 <title>
1270                 <function moreinfo="none">permissions.subnetDump</function>
1271                 </title>
1272                 <para>
1273                         Causes permissions module to dump
1274                         contents of cache memory subnet table.
1275                 </para>
1276                 <para>Parameters: <emphasis>none</emphasis></para>
1277         </section>
1278
1279         <section id ="permissions.r.domainDump">
1280                 <title>
1281                 <function moreinfo="none">permissions.domainDump</function>
1282                 </title>
1283                 <para>
1284                         Causes permissions module to dump
1285                         contents of cache memory domain table.
1286                 </para>
1287                 <para>Parameters: <emphasis>none</emphasis></para>
1288         </section>
1289
1290         <section id ="permissions.r.testUri">
1291                 <title>
1292                 <function moreinfo="none">permissions.testUri</function>
1293                 </title>
1294                 <para>
1295                         Tests if the (URI, Contact) pair is allowed according to
1296                         allow/deny files.  The files must already have been
1297                         loaded by &kamailio;.
1298                 </para>
1299                 <para>Parameters: </para>
1300                 <itemizedlist>
1301                         <listitem><para>
1302                                 <emphasis>basename</emphasis> -
1303                                 Basename from which allow and deny filenames will be created by
1304                                 appending contents of the allow_suffix and deny_suffix
1305                                 parameters.
1306                         </para></listitem>
1307                         <listitem><para>
1308                                 <emphasis>URI</emphasis> - URI to be tested
1309                         </para></listitem>
1310                         <listitem><para>
1311                                 <emphasis>Contact</emphasis> - Contact to be tested
1312                         </para></listitem>
1313                 </itemizedlist>
1314
1315         </section>
1316
1317         <section id ="permissions.r.allowUri">
1318                 <title>
1319                 <function moreinfo="none">permissions.allowUri</function>
1320                 </title>
1321                 <para>
1322                 </para>
1323         </section>
1324
1325         <section id ="permissions.r.trustedReload">
1326                 <title>
1327                 <function moreinfo="none">permissions.trustedReload</function>
1328                 </title>
1329                 <para>
1330                         Causes the permissions module to re-read the contents of
1331                         the trusted database table into cache memory.
1332                 </para>
1333                 <para>Parameters: <emphasis>none</emphasis></para>
1334         </section>
1335         <section id ="permissions.r.trustedDump">
1336                 <title>
1337                 <function moreinfo="none">permissions.trustedDump</function>
1338                 </title>
1339                 <para>
1340                         Causes the permissions module to dump contents of the trusted
1341                         database table from cache memory.
1342                 </para>
1343                 <para>Parameters: <emphasis>none</emphasis></para>
1344         </section>
1345
1346         </section> <!-- RPC commands -->
1347
1348 </chapter>