modules: readme files regenerated - permissions ... [skip ci]

src/modules/permissions/README

@@ -12,6 +12,8 @@ Juha Heinanen
 
 Emmanuel Schmidbauer
 
+Donat Zenichev
+
    Copyright © 2003 Miklos Tirpak
 
    Copyright © 2006-2008 Juha Heinanen
@@ -70,12 +72,14 @@ Emmanuel Schmidbauer
               4.3. allow_routing(allow_file, deny_file)
               4.4. allow_register(basename)
               4.5. allow_register(allow_file, deny_file)
-              4.6. allow_uri(basename, pvar)
-              4.7. allow_address(group_id, ip_addr_pvar, port_pvar)
-              4.8. allow_source_address([group_id])
-              4.9. allow_source_address_group()
-              4.10. allow_address_group(addr, port)
-              4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
+              4.6. allow_register_include_port(basename)
+              4.7. allow_register_include_port(allow_file, deny_file)
+              4.8. allow_uri(basename, pvar)
+              4.9. allow_address(group_id, ip_addr_pvar, port_pvar)
+              4.10. allow_source_address([group_id])
+              4.11. allow_source_address_group()
+              4.12. allow_address_group(addr, port)
+              4.13. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
 
         5. RPC Commands
 
@@ -89,6 +93,7 @@ Emmanuel Schmidbauer
               5.8. permissions.trustedDump
 
         6. Address File Format
+        7. Register File Format
 
    List of Examples
 
@@ -123,13 +128,16 @@ Emmanuel Schmidbauer
    1.29. allow_routing(allow_file, deny_file) usage
    1.30. allow_register(basename) usage
    1.31. allow_register(allow_file, deny_file) usage
-   1.32. allow_uri(basename, pvar) usage
-   1.33. allow_address() usage
-   1.34. allow_source_address(group_id) usage
-   1.35. allow_source_address_group() usage
-   1.36. allow_source_address_group() usage
-   1.37. allow_trusted() usage
-   1.38. Address File Sample
+   1.32. allow_register_include_port(basename) usage
+   1.33. allow_register_include_port(allow_file, deny_file) usage
+   1.34. allow_uri(basename, pvar) usage
+   1.35. allow_address() usage
+   1.36. allow_source_address(group_id) usage
+   1.37. allow_source_address_group() usage
+   1.38. allow_source_address_group() usage
+   1.39. allow_trusted() usage
+   1.40. Address File Sample
+   1.41. Register File Sample
 
 Chapter 1. Admin Guide
 
@@ -184,12 +192,14 @@ Chapter 1. Admin Guide
         4.3. allow_routing(allow_file, deny_file)
         4.4. allow_register(basename)
         4.5. allow_register(allow_file, deny_file)
-        4.6. allow_uri(basename, pvar)
-        4.7. allow_address(group_id, ip_addr_pvar, port_pvar)
-        4.8. allow_source_address([group_id])
-        4.9. allow_source_address_group()
-        4.10. allow_address_group(addr, port)
-        4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
+        4.6. allow_register_include_port(basename)
+        4.7. allow_register_include_port(allow_file, deny_file)
+        4.8. allow_uri(basename, pvar)
+        4.9. allow_address(group_id, ip_addr_pvar, port_pvar)
+        4.10. allow_source_address([group_id])
+        4.11. allow_source_address_group()
+        4.12. allow_address_group(addr, port)
+        4.13. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
 
    5. RPC Commands
 
@@ -203,6 +213,7 @@ Chapter 1. Admin Guide
         5.8. permissions.trustedDump
 
    6. Address File Format
+   7. Register File Format
 
 1. Overview
 
@@ -272,7 +283,8 @@ Chapter 1. Admin Guide
    The function for registration checking is called allow_register and the
    algorithm is very similar to the algorithm described in Section 1.1,
    “Call Routing”. The only difference is in the way how pairs are
-   created.
+   created. Additionally one can use allow_register_include_port function
+   in order to include the port value of the Contact into the check.
 
    Instead of the From header field the function uses the To header field
    because the To header field in REGISTER messages contains the URI of
@@ -458,7 +470,7 @@ modparam("permissions", "check_all_branches", 0)
 
    Suffix to be appended to basename to create filename of the allow file
    when version with one parameter of either allow_routing or
-   allow_register is used.
+   allow_register_include_port or allow_register is used.
 
 Note
 
@@ -475,7 +487,7 @@ modparam("permissions", "allow_suffix", ".allow")
 
    Suffix to be appended to basename to create filename of the deny file
    when version with one parameter of either allow_routing or
-   allow_register is used.
+   allow_register_include_port or allow_register is used.
 
 Note
 
@@ -771,12 +783,14 @@ modparam("permissions", "trusted_cleanup_interval", 120)
    4.3. allow_routing(allow_file, deny_file)
    4.4. allow_register(basename)
    4.5. allow_register(allow_file, deny_file)
-   4.6. allow_uri(basename, pvar)
-   4.7. allow_address(group_id, ip_addr_pvar, port_pvar)
-   4.8. allow_source_address([group_id])
-   4.9. allow_source_address_group()
-   4.10. allow_address_group(addr, port)
-   4.11. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
+   4.6. allow_register_include_port(basename)
+   4.7. allow_register_include_port(allow_file, deny_file)
+   4.8. allow_uri(basename, pvar)
+   4.9. allow_address(group_id, ip_addr_pvar, port_pvar)
+   4.10. allow_source_address([group_id])
+   4.11. allow_source_address_group()
+   4.12. allow_address_group(addr, port)
+   4.13. allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
 
 4.1.  allow_routing()
 
@@ -900,7 +914,65 @@ if (method=="REGISTER") {
 };
 ...
 
-4.6.  allow_uri(basename, pvar)
+4.6.  allow_register_include_port(basename)
+
+   The function does exacty the same thing as allow_register(basename)
+   apart that it tells the module to include the port value of Contact
+   into the check. No additional function parameters required.
+
+   Meaning of the parameters is as follows:
+     * basename - Basename from which allow and deny filenames will be
+       created by appending contents of allow_suffix and deny_suffix
+       parameters.
+       If the parameter doesn't contain full pathname then the function
+       expects the file to be located in the same directory as the main
+       configuration file of the server.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+   Example 1.32. allow_register_include_port(basename) usage
+...
+if (method=="REGISTER") {
+        if (allow_register_include_port("register")) {
+                save("location");
+                exit;
+        } else {
+                sl_send_reply("403", "Forbidden");
+        };
+};
+...
+
+4.7.  allow_register_include_port(allow_file, deny_file)
+
+   The function does exacty the same thing as allow_register(allow_file,
+   deny_file) apart that it tells the module to include the port value of
+   Contact into the check. No additional function parameters required.
+
+   Meaning of the parameters is as follows:
+     * allow_file - File containing allow rules.
+       If the parameter doesn't contain full pathname then the function
+       expects the file to be located in the same directory as the main
+       configuration file of the server.
+     * deny_file - File containing deny rules.
+       If the parameter doesn't contain full pathname then the function
+       expects the file to be located in the same directory as the main
+       configuration file of the server.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+   Example 1.33. allow_register_include_port(allow_file, deny_file) usage
+...
+if (method=="REGISTER") {
+        if (allow_register_include_port("register.allow", "register.deny")) {
+                save("location");
+                exit;
+        } else {
+                sl_send_reply("403", "Forbidden");
+        };
+};
+...
+
+4.8.  allow_uri(basename, pvar)
 
    Returns true if the pair constructed as described in Section 1.3, “URI
    Permissions” have appropriate permissions according to the
@@ -917,7 +989,7 @@ if (method=="REGISTER") {
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.32. allow_uri(basename, pvar) usage
+   Example 1.34. allow_uri(basename, pvar) usage
 ...
 if (allow_uri("basename", "$rt")) {  // Check Refer-To URI
         t_relay();
@@ -927,7 +999,7 @@ if (allow_uri("basename", "$avp(i:705)") {  // Check URI stored in $avp(i:705)
 };
 ...
 
-4.7.  allow_address(group_id, ip_addr_pvar, port_pvar)
+4.9.  allow_address(group_id, ip_addr_pvar, port_pvar)
 
    Returns true if the address and port given as values of pvar arguments
    belonging to a group given as group_id argument matches an IP subnet or
@@ -943,7 +1015,7 @@ if (allow_uri("basename", "$avp(i:705)") {  // Check URI stored in $avp(i:705)
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.33. allow_address() usage
+   Example 1.35. allow_address() usage
 ...
 
 // Check if source address/port is in group 1
@@ -958,14 +1030,14 @@ if (!allow_address("2", "$avp(dst_adr)", "$avp(dst_port)") {
 };
 ...
 
-4.8.  allow_source_address([group_id])
+4.10.  allow_source_address([group_id])
 
    Equal to “allow_address(group_id, "$si", "$sp")”. If 'group_id' is
    missing, the function is equal to allow_address("1", "$si", "$sp").
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.34. allow_source_address(group_id) usage
+   Example 1.36. allow_source_address(group_id) usage
 ...
 
 // Check source address/port of request
@@ -974,7 +1046,7 @@ if (!allow_source_address("1")) {
 };
 ...
 
-4.9.  allow_source_address_group()
+4.11.  allow_source_address_group()
 
    Checks if source address/port is found in cached address or subnet
    table in any group. If yes, returns that group. If not returns -1. Port
@@ -982,7 +1054,7 @@ if (!allow_source_address("1")) {
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.35. allow_source_address_group() usage
+   Example 1.37. allow_source_address_group() usage
 ...
 
 $var(group) = allow_source_address_group();
@@ -991,7 +1063,7 @@ if ($var(group) != -1) {
 };
 ...
 
-4.10.  allow_address_group(addr, port)
+4.12.  allow_address_group(addr, port)
 
    Checks if address/port is found in cached address or subnet table in
    any group. If yes, returns that group. If not returns -1. Port value 0
@@ -1000,7 +1072,7 @@ if ($var(group) != -1) {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.36. allow_source_address_group() usage
+   Example 1.38. allow_source_address_group() usage
 ...
 
 $var(group) = allow_address_group("1.2.3.4", "5060");
@@ -1009,7 +1081,7 @@ if ($var(group) != -1) {
 };
 ...
 
-4.11.  allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
+4.13.  allow_trusted([src_ip_pvar, proto_pvar, furi_pvar])
 
    Checks based either on request's source address and transport protocol
    or source address and transport protocol given in pvar arguments, and
@@ -1030,7 +1102,7 @@ if ($var(group) != -1) {
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.37. allow_trusted() usage
+   Example 1.39. allow_trusted() usage
 ...
 if (allow_trusted()) {
         t_relay();
@@ -1148,7 +1220,7 @@ if (allow_trusted("$si", "any", "$ai")) {
    provided, the tag value has to be a single token, without whitespaces
    (other punctuation signs can be in its value, like ',', '=', ';', ...).
 
-   Example 1.38. Address File Sample
+   Example 1.40. Address File Sample
 ...
 # address file - records to match with allow_address(...) and variants
 # * file format details
@@ -1170,3 +1242,41 @@ if (allow_trusted("$si", "any", "$ai")) {
 
 3 [1:5ee::900d:c0de]
 ...
+
+7. Register File Format
+
+   It is a text file with one record per line. Lines 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.
+
+   Each record line has the format:
+...
+(from_list,str) (req_uri_list,str)
+...
+
+   The 'str' indicates that the value has to be a string compatible with
+   POSIX Extended Regular Expressions.
+
+   Example 1.41. Register File Sample
+...
+# Syntax:
+#       from_list [EXCEPT from_list] : req_uri_list [EXCEPT req_uri_list]
+#
+#       from_list and req_uri_list are comma separated expressions
+#       Expressions are treated as case insensitive POSIX Extended Regular Expre
+ssions.
+#       Keyword ALL matches any expression.
+#
+# Examples (requires a usage of allow_register() function):
+#       ALL : "^sip:361[0-9]*@abc\.com$" EXCEPT "^sip:361[0-9]*3@abc\.com$", "^s
+ip:361[0-9]*4@abc\.com$"
+#
+#       "^sip:3677[0-9]*@abc\.com$" :  "^sip:361[0-9]*@abc\.com$"
+#
+#       All : ALL
+#
+# Examples including port check (requires a usage of allow_register_include_port
+() function):
+#
+# ALL : "^sip:.*@192.168.0.1:5062"
+...