permissions: docs for address_file param and address file format
authorDaniel-Constantin Mierla <miconda@gmail.com>
Wed, 29 Apr 2020 20:09:41 +0000 (22:09 +0200)
committerDaniel-Constantin Mierla <miconda@gmail.com>
Wed, 29 Apr 2020 20:09:41 +0000 (22:09 +0200)
src/modules/permissions/doc/permissions_admin.xml

index 935620c..4e003bc 100644 (file)
                <para>
                The module can be used to determine if an address (IP
                address and port or DNS domain name) matches any of the
-               addresses stored in a cached &kamailio; database table.
-               IP addresses in the database table can be subnet addresses.
-               Port 0 in cached database table matches any port. The
-               address and port to be matched can be either taken from
-               the request (allow_source_address) or given as pvar
-               arguments (allow_address).
+               addresses stored in a cached &kamailio; database table or file.
+               IP addresses in the database table or file can be subnet addresses.
+               Port 0 matches any port. The address and port to be matched can be
+               either taken from the source of IP packet of the request
+               (allow_source_address) or given as a variable argument (allow_address).
                </para>
                <para>
-               Addresses stored in the database table can be grouped
+               Addresses stored in the database table or file can be grouped
                together into one or more groups specified by a group
                identifier (positive integer value, i.e., equal or greater than 1).
                The group identifier is given as an argument to the allow_address() and
@@ -430,6 +429,35 @@ modparam("permissions", "allow_suffix", ".allow")
 ...
 modparam("permissions", "deny_suffix", ".deny")
 ...
+</programlisting>
+               </example>
+       </section>
+       <section id ="permissions.p.address_file">
+               <title><varname>address_file</varname> (string)</title>
+               <para>
+               This is the name of full path to the file that store rules used by
+               <function moreinfo="none">allow_address</function> function (and
+               its variants). If it is only the file name, it is expected to be in the
+               same folder as &kamailio;.cfg file.
+               </para>
+               <para>
+               If set, this parameter has priority over the database backend, so the
+               address matching records are loaded from the file, not from database.
+               </para>
+               <para>
+               To see the format of the file see the section "Address File Format".
+               </para>
+               <para>
+               <emphasis>
+                       Default value is <quote>NULL</quote>.
+               </emphasis>
+               </para>
+               <example>
+               <title>Set <varname>address_file</varname> parameter</title>
+               <programlisting format="linespecific">
+...
+modparam("permissions", "address_file", "address.list")
+...
 </programlisting>
                </example>
        </section>
@@ -437,7 +465,8 @@ modparam("permissions", "deny_suffix", ".deny")
                <title><varname>db_url</varname> (string)</title>
                <para>
                This is URL of the database to be used to store rules used by
-               <function moreinfo="none">allow_trusted</function> function.
+               <function moreinfo="none">allow_trusted</function> or
+               <function moreinfo="none">allow_address</function> functions.
                </para>
                <para>
                <emphasis>
@@ -1345,4 +1374,59 @@ if (allow_trusted("$si", "any", "$ai")) {
 
        </section> <!-- RPC commands -->
 
+       <section>
+               <title>Address File Format</title>
+               <para>
+               It is a text file with one record per line. Line starting with '#' are
+               considered comments and ignored. Comments can be also at the end of
+               records, by using '#' to start the comment part of the line.
+               </para>
+               <para>
+               Each record line has the format:
+               </para>
+               <programlisting format="linespecific">
+...
+(groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o)
+...
+</programlisting>
+               <para>
+               The groupid, address, netmask, port and tag are the names of the
+               attributes whose values are expected in the respective order. The 'int'
+               indicates that the value has to be an integer number. The 'str'
+               indicates that the value has to be a string. The 'o' indicates that
+               the attribute is optional. If netmask is not provided, it is set to 32
+               for IPv4 addresses and 128 for IPv6 addresses. If port is not provided,
+               it is set to 0. The tag attribute is not set, if not provided. When
+               provided, the tag value has to be a single token, without whitespaces
+               (other punctuation signs can be in its value, like ',', '=', ';', ...).
+               </para>
+               <example>
+               <title>Address File Sample</title>
+               <programlisting format="linespecific">
+...
+# address file - records to match with allow_address(...) and variants
+# * file format details
+#   - comments start with # and go to end of line
+#   - each line corresponds to a record with following attributes:
+#
+#     (groupid,int) (address,str) (netmask,int,o), (port,int,o) (tag,str,o)
+#
+# * description of the tokens used to describe line format
+#   - int: expected integer value
+#   - str: expected string value
+#   - o: optional field
+
+1 127.0.0.1 32 0 tag1
+1 10.0.0.10
+
+2 192.168.1.0 24 0 tag2
+2 192.168.2.0 24 0 tag3
+
+3 [1:5ee::900d:c0de]
+...
+</programlisting>
+               </example>
+
+       </section> <!-- Address File Format -->
+
 </chapter>