git.sip-router.org Git - sip-router/blob - 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>