permissions: docs for address_file param and address file format
[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 or file.
196                 IP addresses in the database table or file can be subnet addresses.
197                 Port 0 matches any port. The address and port to be matched can be
198                 either taken from the source of IP packet of the request
199                 (allow_source_address) or given as a variable argument (allow_address).
200                 </para>
201                 <para>
202                 Addresses stored in the database table or file can be grouped
203                 together into one or more groups specified by a group
204                 identifier (positive integer value, i.e., equal or greater than 1).
205                 The group identifier is given as an argument to the allow_address() and
206                 allow_source_address() functions.
207                 One group can contain all of the three types of addresses: exact
208                 IP address, subnet IP address or DNS domain name.
209                 </para>
210                 <para>
211                 When the argument is an IP address, it is tried to be matched with the
212                 records from that group that are of type exact IP or subnet. If the
213                 argument is not an IP it is tried to be matched
214                 with the records that are DNS domain names. No DNS lookup is performed,
215                 only strict matching.
216                 </para>
217                 <para>
218                 As a side effect of matching the address, non-NULL tag
219                 (see tag_col module parameter) is added as value to
220                 peer_tag AVP if peer_tag_avp module parameter has been defined.
221                 </para>
222         </section>
223         <section id="sec-trusted-requests">
224                 <title>Trusted Requests</title>
225                 <para>
226                 The module can be used to determine if an incoming
227                 request can be trusted without authentication.
228                 </para>
229                 <para>
230                 When the <function moreinfo="none">allow_trusted</function>
231                 function is called, it tries to find a rule that matches
232                 the request.  Rules contain the following fields:
233                 &lt;source address, transport protocol, regular
234                 expression&gt;.
235                 </para>
236                 <para>
237                 A requests is accepted if there exists a rule, where
238                 </para>
239                 <itemizedlist>
240                 <listitem>
241                         <para>
242                         source address is equal to the source address of
243                         the request or the source address given in pvar,
244                         </para>
245                 </listitem>
246                 <listitem>
247                         <para>
248                         transport protocol is either "ANY" or equal to
249                         the transport protocol of request or the transport
250                         protocol given in pvar, and
251                         </para>
252                 </listitem>
253                 <listitem>
254                         <para>
255                         regular expression is either empty (NULL in
256                         database) or matches the request's From (or optionally provided) URI.
257                         </para>
258                 </listitem>
259                 </itemizedlist>
260                 <para>
261                 Otherwise the request is rejected.
262                 </para>
263                 <para>
264                 As a side effect of accepting the request, the peer's
265         non-NULL tag (see tag_col module parameter) is added as value to
266         peer_tag AVP if the peer_tag_avp module parameter has been defined.
267                 </para>
268                 <para>
269                 Rules are stored in a database table specified by the module
270                 parameters.  There is a module parameter called
271                 <varname>db_mode</varname> that
272                 determines if the rules are cached into memory for faster
273                 matching or if the database is consulted for each invocation
274                 of the allow_trusted() function call.
275                 </para>
276         </section>
277         </section>
278
279         <section>
280         <title>Dependencies</title>
281         <section>
282                 <title>&kamailio; Modules</title>
283                 <para>
284                 The following modules must be loaded before this module:
285                         <itemizedlist>
286                         <listitem>
287                         <para>
288                                 <emphasis>No dependencies on other &kamailio; modules</emphasis>.
289                         </para>
290                         </listitem>
291                         </itemizedlist>
292                 </para>
293         </section>
294         <section>
295                 <title>External Libraries or Applications</title>
296                 <para>
297                 The following libraries or applications must be installed before running
298                 &kamailio; with this module loaded:
299                         <itemizedlist>
300                         <listitem>
301                         <para>
302                                 <emphasis>None</emphasis>.
303                         </para>
304                         </listitem>
305                         </itemizedlist>
306                 </para>
307         </section>
308         </section>
309
310         <section>
311         <title>Parameters</title>
312         <section id ="permissions.p.default_allow_file">
313                 <title><varname>default_allow_file</varname> (string)</title>
314                 <para>
315                 Default allow file used by the functions with no parameters. If you
316                 don't specify a full pathname then the directory in which is the main
317                 config file is located will be used.
318                 </para>
319                 <para>
320                 <emphasis>
321                         Default value is <quote>permissions.allow</quote>.
322                 </emphasis>
323                 </para>
324                 <example>
325                 <title>Set <varname>default_allow_file</varname> parameter</title>
326                 <programlisting format="linespecific">
327 ...
328 modparam("permissions", "default_allow_file", "/etc/permissions.allow")
329 ...
330 </programlisting>
331                 </example>
332         </section>
333         <section id ="permissions.p.default_deny_file">
334                 <title><varname>default_deny_file</varname> (string)</title>
335                 <para>
336                 Default file containing deny rules. The file is used by functions
337                 with no parameters. If you don't specify a full pathname then the
338                 directory in which the main config file is located will be used.
339                 </para>
340                 <para>
341                 <emphasis>
342                         Default value is <quote>permissions.deny</quote>.
343                 </emphasis>
344                 </para>
345                 <example>
346                 <title>Set <varname>default_deny_file</varname> parameter</title>
347                 <programlisting format="linespecific">
348 ...
349 modparam("permissions", "default_deny_file", "/etc/permissions.deny")
350 ...
351 </programlisting>
352                 </example>
353         </section>
354         <section id ="permissions.p.check_all_branches">
355                 <title><varname>check_all_branches</varname> (integer)</title>
356                 <para>
357                 If set then allow_routing functions will check Request-URI of all
358                 branches (default). If disabled then only Request-URI of the first
359                 branch will be checked.
360                 </para>
361                 <warning>
362                 <para>
363                 Do not disable this parameter unless you really know what you
364                 are doing.
365                 </para>
366                 </warning>
367                 <para>
368                 <emphasis>
369                         Default value is 1.
370                 </emphasis>
371                 </para>
372                 <example>
373                 <title>Set <varname>check_all_branches</varname> parameter</title>
374                 <programlisting format="linespecific">
375 ...
376 modparam("permissions", "check_all_branches", 0)
377 ...
378 </programlisting>
379                 </example>
380         </section>
381         <section id ="permissions.p.allow_suffix">
382                 <title><varname>allow_suffix</varname> (string)</title>
383                 <para>
384                 Suffix to be appended to basename to create filename of the allow
385                 file when version with one parameter of either
386                 <function moreinfo="none">allow_routing</function> or
387                 <function moreinfo="none">allow_register</function> is used.
388                 </para>
389                 <note>
390                 <para>
391                         Including leading dot.
392                 </para>
393                 </note>
394                 <para>
395                 <emphasis>
396                         Default value is <quote>.allow</quote>.
397                 </emphasis>
398                 </para>
399                 <example>
400                 <title>Set <varname>allow_suffix</varname> parameter</title>
401                 <programlisting format="linespecific">
402 ...
403 modparam("permissions", "allow_suffix", ".allow")
404 ...
405 </programlisting>
406                 </example>
407         </section>
408         <section id ="permissions.p.deny_suffix">
409                 <title><varname>deny_suffix</varname> (string)</title>
410                 <para>
411                 Suffix to be appended to basename to create filename of the deny file
412                 when version with one parameter of either
413                 <function moreinfo="none">allow_routing</function> or
414                 <function moreinfo="none">allow_register</function> is used.
415                 </para>
416                 <note>
417                 <para>
418                         Including leading dot.
419                 </para>
420                 </note>
421                 <para>
422                 <emphasis>
423                         Default value is <quote>.deny</quote>.
424                 </emphasis>
425                 </para>
426                 <example>
427                 <title>Set <varname>deny_suffix</varname> parameter</title>
428                 <programlisting format="linespecific">
429 ...
430 modparam("permissions", "deny_suffix", ".deny")
431 ...
432 </programlisting>
433                 </example>
434         </section>
435         <section id ="permissions.p.address_file">
436                 <title><varname>address_file</varname> (string)</title>
437                 <para>
438                 This is the name of full path to the file that store rules used by
439                 <function moreinfo="none">allow_address</function> function (and
440                 its variants). If it is only the file name, it is expected to be in the
441                 same folder as &kamailio;.cfg file.
442                 </para>
443                 <para>
444                 If set, this parameter has priority over the database backend, so the
445                 address matching records are loaded from the file, not from database.
446                 </para>
447                 <para>
448                 To see the format of the file see the section "Address File Format".
449                 </para>
450                 <para>
451                 <emphasis>
452                         Default value is <quote>NULL</quote>.
453                 </emphasis>
454                 </para>
455                 <example>
456                 <title>Set <varname>address_file</varname> parameter</title>
457                 <programlisting format="linespecific">
458 ...
459 modparam("permissions", "address_file", "address.list")
460 ...
461 </programlisting>
462                 </example>
463         </section>
464         <section id ="permissions.p.db_url">
465                 <title><varname>db_url</varname> (string)</title>
466                 <para>
467                 This is URL of the database to be used to store rules used by
468                 <function moreinfo="none">allow_trusted</function> or
469                 <function moreinfo="none">allow_address</function> functions.
470                 </para>
471                 <para>
472                 <emphasis>
473                         Default value is <quote>NULL</quote>.
474                 </emphasis>
475                 </para>
476                 <example>
477                 <title>Set <varname>db_url</varname> parameter</title>
478                 <programlisting format="linespecific">
479 ...
480 modparam("permissions", "db_url", "&exampledb;")
481 ...
482 </programlisting>
483                 </example>
484         </section>
485         <section id ="permissions.p.address_table">
486                 <title><varname>address_table</varname> (string)</title>
487                 <para>
488                 The name of the database table containing IP subnets and DNS domain names used by
489                 <function moreinfo="none">allow_address</function> and
490                 <function moreinfo="none">allow_source_address</function>
491                 functions.
492                 </para>
493                 <para>
494                 <emphasis>
495                 Default value is <quote>address</quote>.
496                 </emphasis>
497                 </para>
498                 <example>
499                 <title>Set <varname>address_table</varname> parameter</title>
500                 <programlisting format="linespecific">
501 ...
502 modparam("permissions", "address_table", "addr")
503 ...
504 </programlisting>
505                 </example>
506         </section>
507         <section id ="permissions.p.grp_col">
508                 <title><varname>grp_col</varname> (string)</title>
509                 <para>
510                 Name of address table column containing the group
511                 identifier of the address.
512                 </para>
513                 <para>
514                 <emphasis>
515                 Default value is <quote>grp</quote>.
516                 </emphasis>
517                 </para>
518                 <example>
519                 <title>Set <varname>grp_col</varname> parameter</title>
520                 <programlisting format="linespecific">
521 ...
522 modparam("permissions", "grp_col", "group_id")
523 ...
524 </programlisting>
525                 </example>
526         </section>
527         <section id ="permissions.p.ip_addr_col">
528                 <title><varname>ip_addr_col</varname> (string)</title>
529                 <para>
530                 Name of address table column containing the IP address
531                 part of the address.
532                 </para>
533                 <para>
534                 <emphasis>
535                 Default value is <quote>ip_addr</quote>.
536                 </emphasis>
537                 </para>
538                 <example>
539                 <title>Set <varname>ip_addr_col</varname> parameter</title>
540                 <programlisting format="linespecific">
541 ...
542 modparam("permissions", "ip_addr_col", "ip_address")
543 ...
544 </programlisting>
545                 </example>
546         </section>
547         <section id ="permissions.p.mask_col">
548                 <title><varname>mask_col</varname> (string)</title>
549                 <para>
550                 Name of address table column containing the network mask of
551                 the address.  Possible values are 0-32 for IPv4 and 0-128 for
552                 IPv6 addresses.
553                 </para>
554                 <para>
555                 <emphasis>
556                 Default value is <quote>mask</quote>.
557                 </emphasis>
558                 </para>
559                 <example>
560                 <title>Set <varname>mask_col</varname> parameter</title>
561                 <programlisting format="linespecific">
562 ...
563 modparam("permissions", "mask_col", "subnet_length")
564 ...
565 </programlisting>
566                 </example>
567         </section>
568         <section id ="permissions.p.port_col">
569                 <title><varname>port_col</varname> (string)</title>
570                 <para>
571                 Name of address table column containing the port
572                 part of the address.
573                 </para>
574                 <para>
575                 <emphasis>
576                 Default value is <quote>port</quote>.
577                 </emphasis>
578                 </para>
579                 <example>
580                 <title>Set <varname>port_col</varname> parameter</title>
581                 <programlisting format="linespecific">
582 ...
583 modparam("permissions", "port_col", "port")
584 ...
585 </programlisting>
586                 </example>
587         </section>
588         <section id ="permissions.p.db_mode">
589                 <title><varname>db_mode</varname> (integer)</title>
590                 <para>
591                 Database mode. 0 means non-caching, 1 means caching.
592                 Valid only for the <function moreinfo="none">allow_trusted</function> function.
593                 </para>
594                 <para>
595                 <emphasis>
596                         Default value is 0 (non-caching).
597                 </emphasis>
598                 </para>
599                 <example>
600                 <title>Set <varname>db_mode</varname> parameter</title>
601                 <programlisting format="linespecific">
602 ...
603 modparam("permissions", "db_mode", 1)
604 ...
605 </programlisting>
606                 </example>
607         </section>
608         <section id ="permissions.p.trusted_table">
609                 <title><varname>trusted_table</varname> (string)</title>
610                 <para>
611                 Name of database table containing the matching rules used by
612                 the <function moreinfo="none">allow_trusted</function> function.
613                 </para>
614                 <para>
615                 <emphasis>
616                 Default value is <quote>trusted</quote>.
617                 </emphasis>
618                 </para>
619                 <example>
620                 <title>Set <varname>trusted_table</varname> parameter</title>
621                 <programlisting format="linespecific">
622 ...
623 modparam("permissions", "trusted_table", "pbx")
624 ...
625 </programlisting>
626                 </example>
627         </section>
628         <section id ="permissions.p.source_col">
629                 <title><varname>source_col</varname> (string)</title>
630                 <para>
631                 Name of column in the <quote>trusted</quote> table containing the source IP
632                 address that is matched against source IP address of
633                 received request.
634                 </para>
635                 <para>
636                 <emphasis>
637                 Default value is <quote>src_ip</quote>.
638                 </emphasis>
639                 </para>
640                 <example>
641                 <title>Set <varname>source_col</varname> parameter</title>
642                 <programlisting format="linespecific">
643 ...
644 modparam("permissions", "source_col", "source_ip_address")
645 ...
646 </programlisting>
647                 </example>
648         </section>
649         <section id ="permissions.p.proto_col">
650                 <title><varname>proto_col</varname> (string)</title>
651                 <para>
652                 Name of column in the <quote>trusted</quote> table containing the transport
653                 protocol that is matched against transport protocol of
654                 the received request.  Possible values that can be stored in
655                 proto_col are <quote>any</quote>, <quote>udp</quote>,
656                 <quote>tcp</quote>, <quote>tls</quote>,
657                 <quote>sctp</quote>, <quote>ws</quote>, <quote>wss</quote>,
658                 and <quote>none</quote>.  Value
659                 <quote>any</quote> matches always and value
660                 <quote>none</quote> never.
661                 </para>
662                 <para>
663                 <emphasis>
664                         Default value is <quote>proto</quote>.
665                 </emphasis>
666                 </para>
667                 <example>
668                 <title>Set <varname>proto_col</varname> parameter</title>
669                 <programlisting format="linespecific">
670 ...
671 modparam("permissions", "proto_col", "transport")
672 ...
673 </programlisting>
674                 </example>
675         </section>
676         <section id ="permissions.p.from_col">
677                 <title><varname>from_col</varname> (string)</title>
678                 <para>
679                 Name of the column trusted table containing a regular
680                 expression that is matched against the From URI.
681                 </para>
682                 <para>
683                 <emphasis>
684                 Default value is <quote>from_pattern</quote>.
685                 </emphasis>
686                 </para>
687                 <example>
688                 <title>Set <varname>from_col</varname> parameter</title>
689                 <programlisting format="linespecific">
690 ...
691 modparam("permissions", "from_col", "regexp")
692 ...
693 </programlisting>
694                 </example>
695         </section>
696         <section id ="permissions.p.ruri_col">
697                 <title><varname>ruri_col</varname> (string)</title>
698                 <para>
699                 Name of the column trusted table containing a regular
700                 expression that is matched against the Request URI.
701                 </para>
702                 <para>
703                 <emphasis>
704                 Default value is <quote>ruri_pattern</quote>.
705                 </emphasis>
706                 </para>
707                 <example>
708                 <title>Set <varname>ruri_col</varname> parameter</title>
709                 <programlisting format="linespecific">
710 ...
711 modparam("permissions", "ruri_col", "regexp")
712 ...
713 </programlisting>
714                 </example>
715         </section>
716         <section id ="permissions.p.tag_col">
717                 <title><varname>tag_col</varname> (string)</title>
718                 <para>
719                 Name of the column in the <quote>address</quote> or
720                 <quote>trusted</quote> table containing a string
721                 that is added as value to peer_tag AVP if peer_tag AVP
722                 has been defined and if the address or peer matches.
723                 </para>
724                 <para>
725                 <emphasis>
726                 Default value is <quote>tag</quote>.
727                 </emphasis>
728                 </para>
729                 <example>
730                 <title>Set <varname>tag_col</varname> parameter</title>
731                 <programlisting format="linespecific">
732 ...
733 modparam("permissions", "tag_col", "peer_tag")
734 ...
735 </programlisting>
736                 </example>
737         </section>
738         <section id ="permissions.p.priority_col">
739                 <title><varname>priority_col</varname> (string)</title>
740                 <para>
741                 The column name used to store the priority of the corresponding rule from the database
742                 row. Priority values should be integer. When db_mode is set to 1 (caching), priorities
743                 are ordered from highest to lowest. In non-caching mode, priority order (ASC vs DESC)
744                 is determined by database.
745                 </para>
746                 <para>
747                 <emphasis>
748                 Default value is <quote>priority</quote>.
749                 </emphasis>
750                 </para>
751                 <example>
752                 <title>Set <varname>priority_col</varname> parameter</title>
753                 <programlisting format="linespecific">
754 ...
755 modparam("permissions", "priority_col", "column_name")
756 ...
757 </programlisting>
758                 </example>
759         </section>
760         <section id ="permissions.p.peer_tag_avp">
761                 <title><varname>peer_tag_avp</varname> (AVP string)</title>
762                 <para>
763                 If defined, the AVP will be
764                 set as a side effect of <function moreinfo="none">allow_trusted</function>
765                 call to not NULL tag column value of the matching peer.
766                 </para>
767                 <para>
768                 <emphasis>
769                 Default value is <quote>undefined</quote>.
770                 </emphasis>
771                 </para>
772                 <example>
773                 <title>Set <varname>peer_tag_avp</varname> parameter</title>
774                 <programlisting format="linespecific">
775 ...
776 modparam("permissions", "peer_tag_avp", "$avp(i:707)")
777 ...
778 </programlisting>
779                 </example>
780         </section>
781         <section id ="permissions.p.peer_tag_mode">
782                 <title><varname>peer_tag_mode</varname> (integer)</title>
783                 <para>
784                 Tag mode for <function moreinfo="none">allow_trusted</function>.
785                 <quote>0</quote> sets only the tag of the first match.
786                 <quote>1</quote> adds the tags of all matches to the avp. In addition
787                 the return value of <function moreinfo="none">allow_trusted</function>
788                 is the number of matches. This parameter is not used for address table matching functions.
789                 </para>
790                 <para>
791                 <emphasis>
792                 Default value is <quote>0</quote>.
793                 </emphasis>
794                 </para>
795                 <example>
796                 <title>Set <varname>peer_tag_mode</varname> parameter</title>
797                 <programlisting format="linespecific">
798 ...
799 modparam("permissions", "peer_tag_mode", 1)
800 ...
801 </programlisting>
802                 </example>
803         </section>
804         <section id ="permissions.p.max_subnets">
805                 <title><varname>max_subnets</varname> (int)</title>
806                 <para>
807                         The maximum number of subnet addresses to be loaded from
808                         address table.
809                 </para>
810                 <para>
811                 <emphasis>
812                 Default value is <quote>512</quote>.
813                 </emphasis>
814                 </para>
815                 <example>
816                 <title>Set <varname>max_subnets</varname> parameter</title>
817                 <programlisting format="linespecific">
818 ...
819 modparam("permissions", "max_subnets", 1024)
820 ...
821 </programlisting>
822                 </example>
823         </section>
824         <section id ="permissions.p.load_backends">
825                 <title><varname>load_backends</varname> (int)</title>
826                 <para>
827                         Control what backends should be loaded: 1 - address table;
828                         2 - trusted table; 4 - allow file; 8 - deny file.
829                 </para>
830                 <para>
831                         It can be a combination (sum) of the options to load many backends
832                         (e.g., 3 - loads address and trusted tables).
833                 </para>
834                 <para>
835                 <emphasis>
836                 Default value is <quote>0xffff</quote> (load all backends).
837                 </emphasis>
838                 </para>
839                 <example>
840                 <title>Set <varname>load_backends</varname> parameter</title>
841                 <programlisting format="linespecific">
842 ...
843 modparam("permissions", "load_backends", 1)
844 ...
845 </programlisting>
846                 </example>
847         </section>
848         </section>
849
850         <section>
851         <title>Functions</title>
852         <section id ="permissions.f.allow_routing">
853                 <title>
854                 <function moreinfo="none">allow_routing()</function>
855                 </title>
856                 <para>
857                 Returns true if all pairs constructed as described in <xref
858                         linkend="sec-call-routing"/> have appropriate permissions according to
859                 the configuration files. This function uses default configuration
860                 files specified in <varname>default_allow_file</varname> and
861                 <varname>default_deny_file</varname>.
862                 </para>
863                 <para>
864                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
865                 </para>
866                 <example>
867                 <title><function>allow_routing</function> usage</title>
868                 <programlisting format="linespecific">
869 ...
870 if (allow_routing()) {
871         t_relay();
872 };
873 ...
874 </programlisting>
875                 </example>
876         </section>
877         <section id ="permissions.f.allow_routing_basename">
878                 <title>
879                 <function moreinfo="none">allow_routing(basename)</function>
880                 </title>
881                 <para>
882                 Returns true if all pairs constructed as described in <xref
883                         linkend="sec-call-routing"/> have appropriate permissions according
884                 to the configuration files given as parameters.
885                 </para>
886                 <para>Meaning of the parameters is as follows:</para>
887                 <itemizedlist>
888                 <listitem>
889                         <para><emphasis>basename</emphasis> - Basename from which allow
890                         and deny filenames will be created by appending contents of
891                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
892                         parameters.
893                         </para>
894                         <para>
895                         If the parameter doesn't contain full pathname then the function
896                         expects the file to be located in the same directory as the main
897                         configuration file of the server.
898                         </para>
899                 </listitem>
900                 </itemizedlist>
901                 <para>
902                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
903                 </para>
904                 <example>
905                 <title><function>allow_routing(basename)</function> usage</title>
906                 <programlisting format="linespecific">
907 ...
908 if (allow_routing("basename")) {
909         t_relay();
910 };
911 ...
912 </programlisting>
913                 </example>
914         </section>
915         <section id ="permissions.f.allow_routing_fileargs">
916                 <title>
917                 <function moreinfo="none">allow_routing(allow_file,deny_file)</function>
918                 </title>
919                 <para>
920                 Returns true if all pairs constructed as described in
921                 <xref linkend="sec-call-routing"/> have appropriate permissions
922                 according to the configuration files given as parameters.
923                 </para>
924                 <para>Meaning of the parameters is as follows:</para>
925                 <itemizedlist>
926                 <listitem>
927                         <para><emphasis>allow_file</emphasis> - File containing allow rules.
928                         </para>
929                         <para>
930                         If the parameter doesn't contain full pathname then the function
931                         expects the file to be located in the same directory as the main
932                         configuration file of the server.
933                         </para>
934                 </listitem>
935                 <listitem>
936                         <para><emphasis>deny_file</emphasis> - File containing deny rules.
937                         </para>
938                         <para>
939                         If the parameter doesn't contain full pathname then the function
940                         expects the file to be located in the same directory as the main
941                         configuration file of the server.
942                         </para>
943                 </listitem>
944                 </itemizedlist>
945                 <para>
946                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
947                 </para>
948                 <example>
949                 <title><function>allow_routing(allow_file, deny_file)</function> usage</title>
950                 <programlisting format="linespecific">
951 ...
952 if (allow_routing("rules.allow", "rules.deny")) {
953         t_relay();
954 };
955 ...
956 </programlisting>
957                 </example>
958         </section>
959         <section id ="permissions.f.allow_register">
960                 <title>
961                 <function moreinfo="none">allow_register(basename)</function>
962                 </title>
963                 <para>
964                 The function returns true if all pairs constructed as described in <xref
965                         linkend="sec-registration-permissions"/> have appropriate permissions
966                 according to the configuration files given as parameters.
967                 </para>
968                 <para>Meaning of the parameters is as follows:</para>
969                 <itemizedlist>
970                 <listitem>
971                         <para><emphasis>basename</emphasis> - Basename from which allow
972                         and deny filenames will be created by appending contents of
973                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
974                         parameters.
975                         </para>
976                         <para>
977                         If the parameter doesn't contain full pathname then the function
978                         expects the file to be located in the same directory as the main
979                         configuration file of the server.
980                         </para>
981                 </listitem>
982                 </itemizedlist>
983                 <para>
984                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
985                 </para>
986                 <example>
987                 <title><function>allow_register(basename)</function> usage</title>
988                 <programlisting format="linespecific">
989 ...
990 if (method=="REGISTER") {
991         if (allow_register("register")) {
992                 save("location");
993                 exit;
994         } else {
995                 sl_send_reply("403", "Forbidden");
996         };
997 };
998 ...
999 </programlisting>
1000                 </example>
1001         </section>
1002         <section id ="permissions.f.allow_register_fileargs">
1003                 <title>
1004                 <function moreinfo="none">allow_register(allow_file, deny_file)</function>
1005                 </title>
1006                 <para>
1007                 The function returns true if all pairs constructed as described in
1008                 <xref linkend="sec-registration-permissions"/> have appropriate
1009                 permissions according to the configuration files given as parameters.
1010                 </para>
1011                 <para>Meaning of the parameters is as follows:</para>
1012                 <itemizedlist>
1013                 <listitem>
1014                         <para><emphasis>allow_file</emphasis> - File containing allow rules.
1015                         </para>
1016                         <para>
1017                         If the parameter doesn't contain full pathname then the function
1018                         expects the file to be located in the same directory as the main
1019                         configuration file of the server.
1020                         </para>
1021                 </listitem>
1022                 <listitem>
1023                         <para><emphasis>deny_file</emphasis> - File containing deny rules.
1024                         </para>
1025                         <para>
1026                         If the parameter doesn't contain full pathname then the function
1027                         expects the file to be located in the same directory as the main
1028                         configuration file of the server.
1029                         </para>
1030                 </listitem>
1031                 </itemizedlist>
1032                 <para>
1033                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1034                 </para>
1035                 <example>
1036                 <title><function>allow_register(allow_file, deny_file)</function> usage</title>
1037                 <programlisting format="linespecific">
1038 ...
1039 if (method=="REGISTER") {
1040         if (allow_register("register.allow", "register.deny")) {
1041                 save("location");
1042                 exit;
1043         } else {
1044                 sl_send_reply("403", "Forbidden");
1045         };
1046 };
1047 ...
1048 </programlisting>
1049                 </example>
1050         </section>
1051         <section id ="permissions.f.allow_uri">
1052                 <title>
1053                 <function moreinfo="none">allow_uri(basename, pvar)</function>
1054                 </title>
1055                 <para>
1056                 Returns true if the pair constructed as described in <xref
1057                         linkend="sec-uri-permissions"/> have appropriate permissions
1058                 according to the configuration files specified by the parameter.
1059                 </para>
1060                 <para>Meaning of the parameter is as follows:</para>
1061                 <itemizedlist>
1062                 <listitem>
1063                         <para><emphasis>basename</emphasis> - Basename from which allow
1064                         and deny filenames will be created by appending contents of
1065                         <varname>allow_suffix</varname> and <varname>deny_suffix</varname>
1066                         parameters.
1067                         </para>
1068                         <para>
1069                         If the parameter doesn't contain full pathname then the function
1070                         expects the file to be located in the same directory as the main
1071                         configuration file of the server.
1072                         </para>
1073                 </listitem>
1074                 <listitem>
1075                         <para><emphasis>pvar</emphasis> - Any
1076                         pseudo-variable defined in &kamailio;.
1077                         </para>
1078                 </listitem>
1079                 </itemizedlist>
1080                 <para>
1081                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1082                 </para>
1083                 <example>
1084                 <title><function>allow_uri(basename, pvar)</function> usage</title>
1085                 <programlisting format="linespecific">
1086 ...
1087 if (allow_uri("basename", "$rt")) {  // Check Refer-To URI
1088         t_relay();
1089 };
1090 if (allow_uri("basename", "$avp(i:705)") {  // Check URI stored in $avp(i:705)
1091         t_relay();
1092 };
1093 ...
1094 </programlisting>
1095                 </example>
1096         </section>
1097         <section id ="permissions.f.allow_address">
1098                 <title>
1099                 <function moreinfo="none">allow_address(group_id, ip_addr_pvar, port_pvar)</function>
1100                 </title>
1101                 <para>
1102                 Returns true if the address and port given as values of pvar
1103                 arguments belonging to a group given as group_id argument
1104                 matches an IP subnet or a DNS domain name found in cached
1105                 address table.
1106                 </para>
1107                 <para>
1108                 When matching is done if the argument is an IP address, it is
1109                 matched with the records from that group that are of type exact
1110                 IP or subnet. If the argument is not an IP it is tried to be matched
1111                 with the records that are DNS domain names. No DNS lookup is performed,
1112                 only strict matching.
1113                 Cached address table entry containing port value <quote>0</quote>
1114                 matches any port. The <quote>group_id</quote> argument can be an integer
1115                 string or a pseudo variable.
1116                 </para>
1117                 <para>
1118                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1119                 </para>
1120                 <example>
1121                 <title><function>allow_address()</function> usage</title>
1122                 <programlisting format="linespecific">
1123 ...
1124
1125 // Check if source address/port is in group 1
1126 if (!allow_address("1", "$si", "$sp")) {
1127         sl_send_reply("403", "Forbidden");
1128 };
1129 // Check address/port stored in AVPs src_adr/src_port is in group 2
1130 $avp(dst_adr) = "sipdomain.com";
1131 $avp(dst_port) = "0";
1132 if (!allow_address("2", "$avp(dst_adr)", "$avp(dst_port)") {
1133         sl_send_reply("403", "Forbidden");
1134 };
1135 ...
1136 </programlisting>
1137                 </example>
1138         </section>
1139         <section id ="permissions.f.allow_source_address">
1140                 <title>
1141                 <function moreinfo="none">allow_source_address([group_id])</function>
1142                 </title>
1143                 <para>
1144                 Equal to <quote>allow_address(group_id, "$si", "$sp")</quote>. If 'group_id' is
1145                 missing, the function is equal to allow_address("1", "$si", "$sp").
1146                 </para>
1147                 <para>
1148                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1149                 </para>
1150                 <example>
1151                 <title><function>allow_source_address(group_id)</function> usage</title>
1152                 <programlisting format="linespecific">
1153 ...
1154
1155 // Check source address/port of request
1156 if (!allow_source_address("1")) {
1157         sl_send_reply("403", "Forbidden");
1158 };
1159 ...
1160 </programlisting>
1161                 </example>
1162         </section>
1163         <section id ="permissions.f.allow_source_address_group">
1164                 <title>
1165                 <function moreinfo="none">allow_source_address_group()</function>
1166                 </title>
1167                 <para>
1168                 Checks if source address/port is found in cached address or
1169                 subnet table in any group. If yes, returns that group.
1170                 If not returns -1.  Port value 0 in cached address and
1171                 group table matches any port.
1172                 </para>
1173                 <para>
1174                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1175                 </para>
1176                 <example>
1177                 <title><function>allow_source_address_group()</function> usage</title>
1178                 <programlisting format="linespecific">
1179 ...
1180
1181 $var(group) = allow_source_address_group();
1182 if ($var(group) != -1) {
1183    # do something with $var(group)
1184 };
1185 ...
1186 </programlisting>
1187                 </example>
1188         </section>
1189         <section id ="permissions.f.allow_address_group">
1190                 <title>
1191                 <function moreinfo="none">allow_address_group(addr, port)</function>
1192                 </title>
1193                 <para>
1194                 Checks if address/port is found in cached address or
1195                 subnet table in any group. If yes, returns that group.
1196                 If not returns -1.  Port value 0 in cached address and
1197                 group table matches any port. The parameters can be pseudo-variables.
1198                 </para>
1199                 <para>
1200                 This function can be used from ANY_ROUTE.
1201                 </para>
1202                 <example>
1203                 <title><function>allow_source_address_group()</function> usage</title>
1204                 <programlisting format="linespecific">
1205 ...
1206
1207 $var(group) = allow_address_group("1.2.3.4", "5060");
1208 if ($var(group) != -1) {
1209    # do something with $var(group)
1210 };
1211 ...
1212 </programlisting>
1213                 </example>
1214         </section>
1215         <section id ="permissions.f.allow_trusted">
1216                 <title>
1217                 <function moreinfo="none">allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])</function>
1218                 </title>
1219                 <para>
1220                 Checks based either on request's source address and transport
1221                 protocol or source address and transport protocol given
1222                 in pvar arguments, and From URI of request (or furi_pvar if provided)
1223                 if request can be trusted without
1224                 authentication.  Returns <quote>1</quote> if a match is found
1225                 as described in <xref linkend="sec-trusted-requests"/>
1226                 and <quote>-1</quote> otherwise.  If a match is found
1227                 and <varname>peer_tag_avp</varname> has been defined, adds a
1228                 non-NULL tag column value of the
1229                 matching peer to AVP peer_tag_avp.
1230                 </para>
1231                 <para>
1232                 NOTE: source IP is matched using string comparison. Be careful if the
1233                 IP can have different forms, for a safer alternative for matching IP
1234                 addresses, look at allow_source_address or allow_address().
1235                 </para>
1236                 <para>
1237                 Source address, transport protocol and uri given in the
1238                 arguments must be in string format and they can contain script variables.
1239                 Valid transport protocol values are (ignoring case) "any", "udp, "tcp", "tls",
1240                 "ws", "wss" and "sctp".
1241                 </para>
1242                 <para>
1243                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1244                 </para>
1245                 <example>
1246                 <title><function>allow_trusted()</function> usage</title>
1247                 <programlisting format="linespecific">
1248 ...
1249 if (allow_trusted()) {
1250         t_relay();
1251 }
1252 ...
1253 if (allow_trusted("$si", "$proto")) {
1254         t_relay();
1255 }
1256 ...
1257 if (allow_trusted("$si", "any", "$ai")) {
1258         t_relay();
1259 }
1260 ...
1261 </programlisting>
1262                 </example>
1263         </section>
1264         </section>
1265
1266         <section>
1267         <title>RPC Commands</title>
1268         <section id ="permissions.r.addressReload">
1269                 <title>
1270                 <function moreinfo="none">permissions.addressReload</function>
1271                 </title>
1272                 <para>
1273                         Causes the permissions module to re-read the contents of
1274                         address database table into cache
1275                         memory.  In cache memory the entries are
1276                         for performance reasons stored in two
1277                         different tables:  address table and
1278                         subnet table depending on the value of
1279                         the mask field (IPv6: 64 or smaller, IPv4: 32 or smaller).
1280                 </para>
1281                 <para>Parameters: <emphasis>none</emphasis></para>
1282         </section>
1283
1284         <section id ="permissions.r.addressDump">
1285                 <title>
1286                 <function moreinfo="none">permissions.addressDump</function>
1287                 </title>
1288                 <para>
1289                         Causes the permissions module to dump
1290                         the contents of cache memory address table.
1291                         (Not the subnet table).
1292
1293                 </para>
1294                 <para>Parameters: <emphasis>none</emphasis></para>
1295         </section>
1296
1297         <section id ="permissions.r.subnetDump">
1298                 <title>
1299                 <function moreinfo="none">permissions.subnetDump</function>
1300                 </title>
1301                 <para>
1302                         Causes permissions module to dump
1303                         contents of cache memory subnet table.
1304                 </para>
1305                 <para>Parameters: <emphasis>none</emphasis></para>
1306         </section>
1307
1308         <section id ="permissions.r.domainDump">
1309                 <title>
1310                 <function moreinfo="none">permissions.domainDump</function>
1311                 </title>
1312                 <para>
1313                         Causes permissions module to dump
1314                         contents of cache memory domain table.
1315                 </para>
1316                 <para>Parameters: <emphasis>none</emphasis></para>
1317         </section>
1318
1319         <section id ="permissions.r.testUri">
1320                 <title>
1321                 <function moreinfo="none">permissions.testUri</function>
1322                 </title>
1323                 <para>
1324                         Tests if the (URI, Contact) pair is allowed according to
1325                         allow/deny files.  The files must already have been
1326                         loaded by &kamailio;.
1327                 </para>
1328                 <para>Parameters: </para>
1329                 <itemizedlist>
1330                         <listitem><para>
1331                                 <emphasis>basename</emphasis> -
1332                                 Basename from which allow and deny filenames will be created by
1333                                 appending contents of the allow_suffix and deny_suffix
1334                                 parameters.
1335                         </para></listitem>
1336                         <listitem><para>
1337                                 <emphasis>URI</emphasis> - URI to be tested
1338                         </para></listitem>
1339                         <listitem><para>
1340                                 <emphasis>Contact</emphasis> - Contact to be tested
1341                         </para></listitem>
1342                 </itemizedlist>
1343
1344         </section>
1345
1346         <section id ="permissions.r.allowUri">
1347                 <title>
1348                 <function moreinfo="none">permissions.allowUri</function>
1349                 </title>
1350                 <para>
1351                 </para>
1352         </section>
1353
1354         <section id ="permissions.r.trustedReload">
1355                 <title>
1356                 <function moreinfo="none">permissions.trustedReload</function>
1357                 </title>
1358                 <para>
1359                         Causes the permissions module to re-read the contents of
1360                         the trusted database table into cache memory.
1361                 </para>
1362                 <para>Parameters: <emphasis>none</emphasis></para>
1363         </section>
1364         <section id ="permissions.r.trustedDump">
1365                 <title>
1366                 <function moreinfo="none">permissions.trustedDump</function>
1367                 </title>
1368                 <para>
1369                         Causes the permissions module to dump contents of the trusted
1370                         database table from cache memory.
1371                 </para>
1372                 <para>Parameters: <emphasis>none</emphasis></para>
1373         </section>
1374
1375         </section> <!-- RPC commands -->
1376
1377         <section>
1378                 <title>Address File Format</title>
1379                 <para>
1380                 It is a text file with one record per line. Line starting with '#' are
1381                 considered comments and ignored. Comments can be also at the end of
1382                 records, by using '#' to start the comment part of the line.
1383                 </para>
1384                 <para>
1385                 Each record line has the format:
1386                 </para>
1387                 <programlisting format="linespecific">
1388 ...
1389 (groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o)
1390 ...
1391 </programlisting>
1392                 <para>
1393                 The groupid, address, netmask, port and tag are the names of the
1394                 attributes whose values are expected in the respective order. The 'int'
1395                 indicates that the value has to be an integer number. The 'str'
1396                 indicates that the value has to be a string. The 'o' indicates that
1397                 the attribute is optional. If netmask is not provided, it is set to 32
1398                 for IPv4 addresses and 128 for IPv6 addresses. If port is not provided,
1399                 it is set to 0. The tag attribute is not set, if not provided. When
1400                 provided, the tag value has to be a single token, without whitespaces
1401                 (other punctuation signs can be in its value, like ',', '=', ';', ...).
1402                 </para>
1403                 <example>
1404                 <title>Address File Sample</title>
1405                 <programlisting format="linespecific">
1406 ...
1407 # address file - records to match with allow_address(...) and variants
1408 # * file format details
1409 #   - comments start with # and go to end of line
1410 #   - each line corresponds to a record with following attributes:
1411 #
1412 #     (groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o)
1413 #
1414 # * description of the tokens used to describe line format
1415 #   - int: expected integer value
1416 #   - str: expected string value
1417 #   - o: optional field
1418
1419 1 127.0.0.1 32 0 tag1
1420 1 10.0.0.10
1421
1422 2 192.168.1.0 24 0 tag2
1423 2 192.168.2.0 24 0 tag3
1424
1425 3 [1:5ee::900d:c0de]
1426 ...
1427 </programlisting>
1428                 </example>
1429
1430         </section> <!-- Address File Format -->
1431
1432 </chapter>