Kamailio module: Difference between revisions

From 탱이의 잡동사니
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 12: Line 12:
Dispatcher 모듈에 여러개의 Asterisk IP 가 설정되어 있는 상황에서, 어느 하나의 IP 가 flag 4(Disabled) 로 설정되게 되면 정상적으로 로드 밸런싱을 수행하지 않는 문제가 있었다.
Dispatcher 모듈에 여러개의 Asterisk IP 가 설정되어 있는 상황에서, 어느 하나의 IP 가 flag 4(Disabled) 로 설정되게 되면 정상적으로 로드 밸런싱을 수행하지 않는 문제가 있었다.


== HTABLE ==
== MAXFWD ==
* https://kamailio.org/docs/modules/5.3.x/modules/htable.html#idp51906148
* https://www.kamailio.org/docs/modules/5.0.x/modules/maxfwd.html
 
Max-Forward SIP header 와 관련된 기능을 수행할 수 있는 모듈이다.


This module adds a hash table container to the configuration language. The hash table is stored in shared memory and the access to it can be done via pseudo-variables: $sht(htname=>name). The module supports definition of many hash tables and can load values at startup from a database table.
The SIP Max-Forward header is used to prevent loops in a SIP network. Every server that process and forward a SIP request lowers the Max-Forward value with one. When the value reaches zero, the request is not forwarded and an error response is sent to the UAC.


=== RPC Commands ===
=== Parameters ===
==== htable.get htable key ====
==== max_limit(integer) ====
Lists one value in a hash table.
Set an upper limit for the max-forward value in the outgoing requests. If the header is present, the decremented value is not allowed this max_limits - if it does, the header value will by decreased to "max_limit". This check is done when calling the maxfwd_process() function.


'''Parameters'''
The range of values stretches from 1 to 256, which is the maximum MAX-FORWARDS value allowed by RFC 3261. The value can be changed at runtime.
* htable: Name of the hash table to dump.
* key: Key name of the hash table value to dump.


'''Example'''
Default value is "70"
<pre>
<pre>
...
modparam("maxfwd", "max_limit", 32)
# Dump $sht(students=>alice)
kamcmd htable.get students alice
 
# Dump first entry in array key course $sht(students=>source[0])
kamcmd htable.get students course[0]
...
</pre>
</pre>


==== htable.delete htable key ====
=== Functions ===
Delete one value in a hash table.
==== maxfwd_process(max_value) ====
If no Max-Forward header is present in the received request, a header will be added having the original value equal with "max_value". If a Max-Forward header is already present, its value will be decremented(if not 0). The parameter can be a variable.


'''Parameters'''
This function can be used from REQUEST_ROUTE.
* htable: Name of the hash table to delete.
* key: Key name of the hash table value to delete.


'''Example'''
'''Variables'''
<pre>
* max_value: Value to be added if there is no Max-Forward header field in the message.
...
# Delete $sht(student=>alice)
kamcmd htable.delete students alice


# Delete first entry in array key course $sht(students=>course[0])
'''Return code'''
kamcmd htable.delete students course[0]
* 2 (true): header was not found and a new header was successfully added.
</pre>
* 1 (true): header was found and its value was successfully decremented (had a non-0 value).
 
* -1(false): the header was found and its value is 0(cannot be decremented).
==== htable.sets htable key value ====
* -2(false): error during processing.
Set an item in hash table to string value.
The return code may be extensivly tested via script variable "retcode" (or "$?").
 
'''Parameters'''
* htable: Name of the hash table.
* key: Key name in the hash table.
* value: String value for the item.


'''Example'''
<pre>
<pre>
...
...
# Set $sht(test->x) as string
# initial sanity checks --- messages with
kamcmd htable.sets test x abc
# max_forwards==0, or excessively long requests
 
if (!maxfwd_process("10") && $retcode==-1) {
# Set first entry in array key x $sht(test=>x[0]) as string
  sl_send_reply("483", "Too Many Hops");
kamcmd htable.sets
  exit;
};
...
...
</pre>
</pre>


==== htable.seti htable key value ====
==== mf_process_maxfwd_header(max_value) ====
Set an item in hash table to integer value.
Same as maxfwd_process(max_value).


'''Parameters'''
== PIKE ==
* htable: Name of the hash table.
The pike module keeps trace of all (or selected ones) incoming request's IP source and blocks the ones that exceed the limit.
* key: Key name in the hash table.
* value: Integer value for the item.


'''Example'''
=== Example ===
<pre>
<pre>
...
# ----- pike params -----
# Set $sht(test=>x) as integer
modparam("pike", "sampling_time_unit", 2)
kamcmd htable.seti test x 123
modparam("pike", "reqs_density_per_unit", 5)
modparam("pike", "remove_latency", 4)
 
# ----- htable params -----
/* ip ban htable with autoexpire after 3 minutes */
modparam("htable", "htable", "ipban=>size=8;autoexpire=180;")
 
// REQ_FROM_EXTERNAL_BAN_DETECT evaluate the given source ip is banned or not.
route [BAN_DETECT] {
  if ($sht(ipban=>$si) != $null)
  {
    # ip is already blocked - keep the node warm
    pike_check_req();
    xdbg("request from blocked IP - $rm from $fu (IP:$si:$sp)\n");
    exit;
  }


# Set first entry in array key x $sht(test=>x[0]) as integer
  if (pike_check_req() != 1) {
kamcmd htable.seti test x[0] 123
    $sht(ipban=>$si) = 1;
    xlog("L_ALERT","ALERT: pike block $rm from $fu (IP:$si:$sp)\n");
    exit;
  }
}
</pre>
</pre>


==== htable.dump htable ====
=== See also ===
Lists all the values in a hash table.
* https://kb.asipto.com/kamailio:usage:k31-sip-scanning-attack


'''Parameters'''
== SANITY ==
* htable: Name of the hash table to dump.
* https://www.kamailio.org/docs/modules/devel/modules/sanity.html


'''Example'''
This module aims to implement several sanity checks on incoming request which are suggested or even required by a RFC.
<pre>
...
kamcmd htable.dump ipban
...
</pre>


==== htable.reload htable ====
These checks are not required by Kamailio itself for its functionality. But on the other side it does not make much sense if a broken request traverses through a SIP network if it is rejected sooner or later by a SIP device any way. As every sanity check cost extra performance because of additional parsing and evaluation it is with this module now up to the Kamailio administrator what checks should be done on which request.
Reload hash table from database


'''Parameters'''
=== Parameters ===
* htable: Name of the hash table to reload.
==== default_checks(integer) ====
This parameter determines which of the checks from the sanity module are executed if no parameter was given to the sanity_check function call. By default, all implemented checks are included in the execution of the sanity_check function. Ths integer value is the sum of the check numbers which should be executed by default.


'''Example'''
Default value is "3047". This resolves to the following list of checks: ruri_sip_version(1), ruri_scheme(2), required_headers(4), cseq_method(32), cseq_value(64), content_length(128), expires_value(256), proxy_require(512), digest_credentials(2048).
<pre>
<pre>
kamcmd htable.reload ipban
modparam("sanity", "default_checks", 1)
</pre>
</pre>


==== htable.flush htable ====
==== uri_checks(integer) ====
Empty the hash table.
This parameter determines which URIs are going to be checked if the 'parse uri' will be executed.


'''Parameters'''
Default value is 7. This resolves to the following list of parsed URIs: Request URI(1), From URI(2) and To URI(4)
* htable: Name of the hash table to flush.
 
'''Example'''
<pre>
<pre>
kamcmd htable.flush ipban
modparam("sanity", "uri_checks", 3)
</pre>
</pre>


==== htable.listTables ====
=== Functions ===
Lists all defined tables.
==== sanity_check([msg_checks [, uri_checks]]) ====
This function makes a row of sanity checks over the given SIP request. The behavior of the function is also controlled by autodrop parameter. If autodrop=0, the function returns false (-1) if one of the checks failed. When autodrop=1, the function stops the execution of configuration file. In both cases, if one of checks fails the module sends a precise error reply via SL send_reply(). Thus there is no need to reply with a generic error message.


'''Example'''
Optionally the function takes an integer argument which overwrites the global module parameter default_checks. This makes it possible to run certain tests from script region. The integer value is again the sum of the checks (like for the module parameter) which should be executed at this function call.
<pre>
$ sudo kamcmd htable.listTables
{
name: ipban
dbtable:
dbmode: 0
expire: 300
updateexpire: 1
size: 256
dmqreplicate: 0
}
</pre>


==== htables.stats ====
Optionally the function takes a second integer argument which overwrites the global module parameter uri_checks and thus determines which URIs will be checked if the parse uri test will be executed.
Get statistics for hash tables - name, number of slots, number of items, max number of items per slot, min number of items per slot.


'''Example'''
'''Example'''
<pre>
<pre>
$ sudo kamcmd htable.stats
if(!sanity_check("17895", "7")) {
{
  xlog("Malformed SIP message from $si:$sp\n");
name: ipban
  exit;
slots: 256
all: 0
min: 0
max: 0
}
}
</pre>
</pre>


== MAXFWD ==
== SL ==
* https://www.kamailio.org/docs/modules/5.0.x/modules/maxfwd.html#maxfwd.f.mf_process_maxfwd_header
* https://kamailio.org/docs/modules/5.3.x/modules/sl.html


Max-Forward SIP header 와 관련된 기능을 수행할 수 있는 모듈이다.
SL 모듈을 이용하면 Kamailio 를 stateless UA server 로 사용할 수 있도록 해준다.


The SIP Max-Forward header is used to prevent loops in a SIP network. Every server that process and forward a SIP request lowers the Max-Forward value with one. When the value reaches zero, the request is not forwarded and an error response is sent to the UAC.
The SL module allows the SIP server to act as a stateless UA server and generate replies to SIP requests without keeping state. That is beneficial in many scenarios, in which you wish not to burden server's memory and scale well.


=== Parameters ===
The SL module needs to filter ACKs sent after a local stateless reply to an INVITE was generated. To recognize such ACKs, Kamailio adds special "signature" in to-tags. This signature is sought for in incoming ACKs, and if included the ACKs are absorbed.
==== max_limit(integer) ====
Set an upper limit for the max-forward value in the outgoing requests. If the header is present, the decremented value is not allowed this max_limits - if it does, the header value will by decreased to "max_limit". This check is done when calling the maxfwd_process() function.


The range of values stretches from 1 to 256, which is the maximum MAX-FORWARDS value allowed by RFC 3261. The value can be changed at runtime.
To speed up the filtering process, the module uses a timeout
 
Default value is "70"
<pre>
modparam("maxfwd", "max_limit", 32)
</pre>


=== Functions ===
=== Functions ===
==== maxfwd_process(max_value) ====
==== sl_send_reply(code, reason) ====
If no Max-Forward header is present in the received request, a header will be added having the original value equal with "max_value". If a Max-Forward header is already present, its value will be decremented(if not 0). The parameter can be a variable.
For the current request, a reply is sent back having the given code and text reason. The reply is sent stateless, totally independent of the Transaction module and with no retransmission for the INVITE's replies.


This function can be used from REQUEST_ROUTE.
If the code is in the range 300-399 (redirect reply), the current destination set is appended to the reply as Contact header. The destination set contains the request URI(R-URI), if it is modified compared to the received one, plus the branches added to the request(e.g., after an append_branch() or lookup("location")). If the R-URI was changed but it is not desired to be part of the destination set, it can be reverted using the function revert_uri().


'''Variables'''
Custom headers to the reply can be added using append_to_reply() function from textops module.
* max_value: Value to be added if there is no Max-Forward header field in the message.


'''Return code'''
'''Parameters'''
* 2 (true): header was not found and a new header was successfully added.
* code: Return code
* 1 (true): header was found and its value was successfully decremented (had a non-0 value).
* reason: Reason phrase
* -1(false): the header was found and its value is 0(cannot be decremented).
* -2(false): error during processing.
The return code may be extensivly tested via script variable "retcode" (or "$?").


'''Example'''
<pre>
<pre>
...
sl_send_reply("404", "Not found");
# initial sanity checks --- messages with
# max_forwards==0, or excessively long requests
if (!maxfwd_process("10") && $retcode==-1) {
  sl_send_reply("483", "Too Many Hops");
  exit;
};
...
</pre>
</pre>


== SL ==
== See also ==
* https://kamailio.org/docs/modules/5.3.x/modules/sl.html
* https://www.kamailio.org/docs/modules/5.3.x/
 
SL 모듈을 이용하면 Kamailio 를 stateless UA server 로 사용할 수 있도록 해준다.
 
The SL module allows the SIP server to act as a stateless UA server and generate replies to SIP requests without keeping state. That is beneficial in many scenarios, in which you wish not to burden server's memory and scale well.


The SL module needs to filter ACKs sent after a local stateless reply to an INVITE was generated. To recognize such ACKs, Kamailio adds special "signature" in to-tags. This signature is sought for in incoming ACKs, and if included the ACKs are absorbed.
To speed up the filtering process, the module uses a timeout
[[category:kamailio]]
[[category:kamailio]]

Latest revision as of 19:59, 17 May 2020

Overview

Kamailio module들 내용 설명

Dispatcher

Kamailio 에서 트래픽 로드 밸런싱을 수행할 수 있는 모듈이다.

ETC

Kamailio 4.4.7 버전에서 이슈가 있었다. 새롭게 Asteri

Dispatcher 모듈에 여러개의 Asterisk IP 가 설정되어 있는 상황에서, 어느 하나의 IP 가 flag 4(Disabled) 로 설정되게 되면 정상적으로 로드 밸런싱을 수행하지 않는 문제가 있었다.

MAXFWD

Max-Forward SIP header 와 관련된 기능을 수행할 수 있는 모듈이다.

The SIP Max-Forward header is used to prevent loops in a SIP network. Every server that process and forward a SIP request lowers the Max-Forward value with one. When the value reaches zero, the request is not forwarded and an error response is sent to the UAC.

Parameters

max_limit(integer)

Set an upper limit for the max-forward value in the outgoing requests. If the header is present, the decremented value is not allowed this max_limits - if it does, the header value will by decreased to "max_limit". This check is done when calling the maxfwd_process() function.

The range of values stretches from 1 to 256, which is the maximum MAX-FORWARDS value allowed by RFC 3261. The value can be changed at runtime.

Default value is "70" 

modparam("maxfwd", "max_limit", 32)

Functions

maxfwd_process(max_value)

If no Max-Forward header is present in the received request, a header will be added having the original value equal with "max_value". If a Max-Forward header is already present, its value will be decremented(if not 0). The parameter can be a variable.

This function can be used from REQUEST_ROUTE.

Variables

  • max_value: Value to be added if there is no Max-Forward header field in the message.

Return code

  • 2 (true): header was not found and a new header was successfully added.
  • 1 (true): header was found and its value was successfully decremented (had a non-0 value).
  • -1(false): the header was found and its value is 0(cannot be decremented).
  • -2(false): error during processing.

The return code may be extensivly tested via script variable "retcode" (or "$?"). 

...
# initial sanity checks --- messages with
# max_forwards==0, or excessively long requests
if (!maxfwd_process("10") && $retcode==-1) {
  sl_send_reply("483", "Too Many Hops");
  exit;
};
...

mf_process_maxfwd_header(max_value)

Same as maxfwd_process(max_value).

PIKE

The pike module keeps trace of all (or selected ones) incoming request's IP source and blocks the ones that exceed the limit.

Example

# ----- pike params -----
modparam("pike", "sampling_time_unit", 2)
modparam("pike", "reqs_density_per_unit", 5)
modparam("pike", "remove_latency", 4)

# ----- htable params -----
/* ip ban htable with autoexpire after 3 minutes */
modparam("htable", "htable", "ipban=>size=8;autoexpire=180;")

// REQ_FROM_EXTERNAL_BAN_DETECT evaluate the given source ip is banned or not.
route [BAN_DETECT] {
  if ($sht(ipban=>$si) != $null)
  {
     # ip is already blocked - keep the node warm
     pike_check_req();
     xdbg("request from blocked IP - $rm from $fu (IP:$si:$sp)\n");
     exit;
  }

  if (pike_check_req() != 1) {
     $sht(ipban=>$si) = 1;
     xlog("L_ALERT","ALERT: pike block $rm from $fu (IP:$si:$sp)\n");
     exit;
  }
}

See also

SANITY

This module aims to implement several sanity checks on incoming request which are suggested or even required by a RFC.

These checks are not required by Kamailio itself for its functionality. But on the other side it does not make much sense if a broken request traverses through a SIP network if it is rejected sooner or later by a SIP device any way. As every sanity check cost extra performance because of additional parsing and evaluation it is with this module now up to the Kamailio administrator what checks should be done on which request.

Parameters

default_checks(integer)

This parameter determines which of the checks from the sanity module are executed if no parameter was given to the sanity_check function call. By default, all implemented checks are included in the execution of the sanity_check function. Ths integer value is the sum of the check numbers which should be executed by default.

Default value is "3047". This resolves to the following list of checks: ruri_sip_version(1), ruri_scheme(2), required_headers(4), cseq_method(32), cseq_value(64), content_length(128), expires_value(256), proxy_require(512), digest_credentials(2048). 

modparam("sanity", "default_checks", 1)

uri_checks(integer)

This parameter determines which URIs are going to be checked if the 'parse uri' will be executed.

Default value is 7. This resolves to the following list of parsed URIs: Request URI(1), From URI(2) and To URI(4) 

modparam("sanity", "uri_checks", 3)

Functions

sanity_check([msg_checks [, uri_checks]])

This function makes a row of sanity checks over the given SIP request. The behavior of the function is also controlled by autodrop parameter. If autodrop=0, the function returns false (-1) if one of the checks failed. When autodrop=1, the function stops the execution of configuration file. In both cases, if one of checks fails the module sends a precise error reply via SL send_reply(). Thus there is no need to reply with a generic error message.

Optionally the function takes an integer argument which overwrites the global module parameter default_checks. This makes it possible to run certain tests from script region. The integer value is again the sum of the checks (like for the module parameter) which should be executed at this function call.

Optionally the function takes a second integer argument which overwrites the global module parameter uri_checks and thus determines which URIs will be checked if the parse uri test will be executed.

Example 

if(!sanity_check("17895", "7")) {
  xlog("Malformed SIP message from $si:$sp\n");
  exit;
}

SL

SL 모듈을 이용하면 Kamailio 를 stateless UA server 로 사용할 수 있도록 해준다.

The SL module allows the SIP server to act as a stateless UA server and generate replies to SIP requests without keeping state. That is beneficial in many scenarios, in which you wish not to burden server's memory and scale well.

The SL module needs to filter ACKs sent after a local stateless reply to an INVITE was generated. To recognize such ACKs, Kamailio adds special "signature" in to-tags. This signature is sought for in incoming ACKs, and if included the ACKs are absorbed.

To speed up the filtering process, the module uses a timeout

Functions

sl_send_reply(code, reason)

For the current request, a reply is sent back having the given code and text reason. The reply is sent stateless, totally independent of the Transaction module and with no retransmission for the INVITE's replies.

If the code is in the range 300-399 (redirect reply), the current destination set is appended to the reply as Contact header. The destination set contains the request URI(R-URI), if it is modified compared to the received one, plus the branches added to the request(e.g., after an append_branch() or lookup("location")). If the R-URI was changed but it is not desired to be part of the destination set, it can be reverted using the function revert_uri().

Custom headers to the reply can be added using append_to_reply() function from textops module.

Parameters

  • code: Return code
  • reason: Reason phrase

Example 

sl_send_reply("404", "Not found");

See also

Retrieved from "http://wiki.pchero21.com/index.php?title=Kamailio_module&oldid=3778"