Skip to content

Commit

Permalink
modules: readme files regenerated - permissions ... [skip ci]
Browse files Browse the repository at this point in the history
  • Loading branch information
@kamailio-dev
kamailio-dev committed May 27, 2024
1 parent 534a359 commit 6a8eb98
Showing 1 changed file with 151 additions and 41 deletions.
192 changes: 151 additions & 41 deletions src/modules/permissions/README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Juha Heinanen

Emmanuel Schmidbauer

Donat Zenichev

Copyright © 2003 Miklos Tirpak

Copyright © 2006-2008 Juha Heinanen
Expand Down Expand Up @@ -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

Expand All @@ -89,6 +93,7 @@ Emmanuel Schmidbauer
5.8. permissions.trustedDump

6. Address File Format
7. Register File Format

List of Examples

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -203,6 +213,7 @@ Chapter 1. Admin Guide
5.8. permissions.trustedDump

6. Address File Format
7. Register File Format

1. Overview

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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()

Expand Down Expand Up @@ -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
Expand All @@ -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();
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -974,15 +1046,15 @@ 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
value 0 in cached address and group table matches any port.

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();
Expand All @@ -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
Expand All @@ -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");
Expand All @@ -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
Expand All @@ -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();
Expand Down Expand Up @@ -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
Expand All @@ -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"
...

0 comments on commit 6a8eb98

Please sign in to comment.