diff --git a/modules/proto_msrp/README b/modules/proto_msrp/README new file mode 100644 index 00000000000..29f314ab5c1 --- /dev/null +++ b/modules/proto_msrp/README @@ -0,0 +1,197 @@ +proto_msrp Module + __________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1.1. Overview + 1.2. Dependencies + + 1.2.1. OpenSIPS Modules + 1.2.2. External Libraries or Applications + + 1.3. Exported Parameters + + 1.3.1. msrp_send_timeout (integer) + 1.3.2. msrp_max_msg_chunks (integer) + 1.3.3. trace_destination (string) + 1.3.4. trace_on (int) + 1.3.5. trace_filter_route (string) + + 1.4. Exported MI Functions + + 1.4.1. msrp_trace + + List of Examples + + 1.1. Set msrp_send_timeout parameter + 1.2. Set msrp_max_msg_chunks parameter + 1.3. Set trace_destination parameter + 1.4. Set trace_on parameter + 1.5. Set trace_filter_route parameter + +Chapter 1. Admin Guide + +1.1. Overview + + The proto_msrp module provides the MSRP protocol stack, meaning + the network read/wite (plain and TLS), message parsing and + assembling, transactional layer and the basic signalling + operations. + + Once loaded, you will be able to define MSRP listeners in your + script, by adding its IP, and optionally the listening port, in + your configuration file, similar to this example: + +... +socket=msrp:127.0.0.1:65432 +... + +1.2. Dependencies + +1.2.1. OpenSIPS Modules + + The following modules must be loaded before this module: + * None. + +1.2.2. External Libraries or Applications + + The following libraries or applications must be installed + before running OpenSIPS with this module loaded: + * None. + +1.3. Exported Parameters + +1.3.1. msrp_send_timeout (integer) + + Time in milliseconds after a MSRP connection will be closed if + it is not available for blocking writing in this interval (and + OpenSIPS wants to send something on it). + + Default value is 100 ms. + + Example 1.1. Set msrp_send_timeout parameter +... +modparam("proto_msrp", "msrp_send_timeout", 200) +... + +1.3.2. msrp_max_msg_chunks (integer) + + The maximum number of chunks that a SIP message is expected to + arrive via MSRP. If a packet is received more fragmented than + this, the connection is dropped (either the connection is very + overloaded and this leads to high fragmentation - or we are the + victim of an ongoing attack where the attacker is sending the + traffic very fragmented in order to decrease our performance). + + Default value is 4. + + Example 1.2. Set msrp_max_msg_chunks parameter +... +modparam("proto_msrp", "msrp_max_msg_chunks", 8) +... + +1.3.3. trace_destination (string) + + Trace destination as defined in the tracing module. Currently + the only tracing module is proto_hep. Network events such as + connect, accept and connection closed events shall be traced + along with errors that could appear in the process. + + WARNING: A tracing module must be loaded in order for this + parameter to work. (for example proto_hep). + + Default value is none(not defined). + + Example 1.3. Set trace_destination parameter +... +modparam("proto_hep", "hep_id", "[hep_dest]10.0.0.2;transport=tcp;versio +n=3") + +modparam("proto_msrp", "trace_destination", "hep_dest") +... + +1.3.4. trace_on (int) + + This controls whether tracing for MSRP is on or not. You still + need to define Section 1.3.3, “trace_destination (string)”in + order to work, but this value will be controlled using MI + function Section 1.4.1, “ msrp_trace ”. + Default value is 0(tracing inactive). + + Example 1.4. Set trace_on parameter +... +modparam("proto_msrp", "trace_on", 1) +... + +1.3.5. trace_filter_route (string) + + Define the name of a route in which you can filter which + connections will be trace and which connections won't be. In + this route you will have information regarding source and + destination ips and ports for the current connection. To + disable tracing for a specific connection the last call in this + route must be drop, any other exit mode resulting in tracing + the current connection ( of course you still have to define a + Section 1.3.3, “trace_destination (string)” and trace must be + on at the time this connection is opened. + + IMPORTANT Filtering on ip addresses and ports can be made using + $si and $sp for matching either the entity that is connecting + to OpenSIPS or the entity to which OpenSIPS is connecting. The + name might be misleading ( $si meaning the source ip if you + read the docs) but in reality it is simply the socket other + than the OpenSIPS socket. In order to match OpenSIPS interface + (either the one that accepted the connection or the one that + initiated a connection) $socket_in(ip) (ip) and + $socket_in(port) (port) can be used. + + WARNING: IF Section 1.3.4, “trace_on (int)” is set to 0 or + tracing is deactived via the mi command Section 1.4.1, “ + msrp_trace ” this route won't be called. + Default value is none(no route is set). + + Example 1.5. Set trace_filter_route parameter +... +modparam("proto_msrp", "trace_filter_route", "msrp_filter") +... +/* all MSRP connections will go through this route if tracing is activat +ed + * and a trace destination is defined */ +route[msrp_filter] { + ... + /* all connections opened from/by ip 1.1.1.1:8000 will be traced + on interface 1.1.1.10:5060(opensips listener) + all the other connections won't be */ + if ( $si == "1.1.1.1" && $sp == 8000 && + $socket_in(ip) == "1.1.1.10" && $socket_in(port) == 506 +0) + exit; + else + drop; +} +... + +1.4. Exported MI Functions + +1.4.1. msrp_trace + + Name: msrp_trace + + Parameters: + * trace_mode(optional): set MSRP tracing on and off. This + parameter can be missing and the command will show the + current tracing status for this module( on or off ); + Possible values: + + on + + off + + MI FIFO Command Format: + :msrp_trace:_reply_fifo_file_ + trace_mode + _empty_line_ + + Documentation Copyrights: + + Copyright © 2022 www.opensips-solutions.com