Skip to content

Commit d44b94d

Browse files
liviuchirculiviuchircu
authored
Merge pull request #3986 from dariusstefan/docs/net-proto-readme-master
docs: add README.md for proto_udp and proto_tcp [skip ci]
2 parents 749dfbb + 4a00083 commit d44b94d

2 files changed

Lines changed: 485 additions & 0 deletions

File tree

‎net/proto_tcp/README.md‎

Lines changed: 396 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,396 @@
1+
---
2+
title: "proto_tcp Module"
3+
description: "The **proto_tcp** module is a built-in transport module which implements SIP TCP-based communication. It does not handle TCP connections management, but only offers higher-level primitives to read and write SIP messages over TCP."
4+
---
5+
6+
## Admin Guide
7+
8+
9+
### Overview
10+
11+
12+
The **proto_tcp** module is a built-in
13+
transport module which implements SIP TCP-based communication. It does
14+
not handle TCP connections management, but only offers higher-level
15+
primitives to read and write SIP messages over TCP.
16+
17+
18+
Once loaded, you will be able to define TCP listeners in your script,
19+
by adding its IP, and optionally the listening port, in your configuration
20+
file, similar to this example:
21+
```c
22+
23+
...
24+
socket=tcp:127.0.0.1 # change the listening IP
25+
socket=tcp:127.0.0.1:5080 # change with the listening IP and port
26+
...
27+
```
28+
29+
30+
### Related Core TCP APIs
31+
32+
33+
#### tcp_close_conn(ipport)
34+
35+
36+
Force-close an existing TCP-based connection. The
37+
*ipport* argument may be either a TCP connection ID,
38+
as reported by the *tcp:list* MI command, or a remote
39+
endpoint in the form *ip:port* or
40+
*proto:ip:port*. If the protocol is omitted,
41+
OpenSIPS will search all TCP-based transports.
42+
43+
44+
The function returns true if a matching connection was scheduled for
45+
closing, false if no connection matched and an error on invalid input
46+
or internal failure.
47+
48+
49+
```c title="Force-close a TCP connection from script"
50+
...
51+
if (!tcp_close_conn("tcp:10.0.0.10:5060")) {
52+
xlog("No matching TCP connection was found\n");
53+
}
54+
...
55+
```
56+
57+
58+
#### tcp:close
59+
60+
61+
Core MI command equivalent of [tcp close conn](#tcp_close_conn_ipport). It
62+
accepts a single *ipport* parameter using the same
63+
formats described above.
64+
65+
66+
```c title="Force-close a TCP connection via MI"
67+
$ opensips-cli -x mi tcp:close ipport=tcp:10.0.0.10:5060
68+
OK
69+
```
70+
71+
72+
### Dependencies
73+
74+
75+
#### OpenSIPS Modules
76+
77+
78+
The following modules must be loaded before this module:
79+
80+
81+
- *None*.
82+
83+
84+
#### External Libraries or Applications
85+
86+
87+
The following libraries or applications must be installed before
88+
running OpenSIPS with this module loaded:
89+
90+
91+
- *None*.
92+
93+
94+
### Exported Parameters
95+
96+
97+
#### tcp_port (integer)
98+
99+
100+
The default port to be used for all TCP related operation. Be careful
101+
as the default port impacts both the SIP listening part (if no port is
102+
defined in the TCP listeners) and the SIP sending part (if the
103+
destination URI has no explicit port).
104+
105+
106+
If you want to change only the listening port for TCP, use the port
107+
option in the SIP listener defintion.
108+
109+
110+
*Default value is 5060.*
111+
112+
113+
```c title="Set tcp_port parameter"
114+
...
115+
modparam("proto_tcp", "tcp_port", 5065)
116+
...
117+
```
118+
119+
120+
#### tcp_send_timeout (integer)
121+
122+
123+
Time in milliseconds after a TCP connection will be closed if it is
124+
not available for blocking writing in this interval (and OpenSIPS wants
125+
to send something on it).
126+
127+
128+
*Default value is 100 ms.*
129+
130+
131+
```c title="Set tcp_send_timeout parameter"
132+
...
133+
modparam("proto_tcp", "tcp_send_timeout", 200)
134+
...
135+
```
136+
137+
138+
#### tcp_max_msg_chunks (integer)
139+
140+
141+
The maximum number of chunks that a SIP message is expected to
142+
arrive via TCP. If a packet is received more fragmented than this,
143+
the connection is dropped (either the connection is very
144+
overloaded and this leads to high fragmentation - or we are the
145+
victim of an ongoing attack where the attacker is sending the
146+
traffic very fragmented in order to decrease our performance).
147+
148+
149+
*Default value is 4.*
150+
151+
152+
```c title="Set tcp_max_msg_chunks parameter"
153+
...
154+
modparam("proto_tcp", "tcp_max_msg_chunks", 8)
155+
...
156+
```
157+
158+
159+
#### tcp_crlf_pingpong (integer)
160+
161+
162+
Send CRLF pong (\r\n) to incoming CRLFCRLF ping messages over TCP.
163+
By default it is enabled (1).
164+
165+
166+
*Default value is 1 (enabled).*
167+
168+
169+
```c title="Set tcp_crlf_pingpong parameter"
170+
...
171+
modparam("proto_tcp", "tcp_crlf_pingpong", 0)
172+
...
173+
```
174+
175+
176+
#### tcp_crlf_drop (integer)
177+
178+
179+
Drop CRLF (\r\n) ping messages. When this parameter is enabled,
180+
the TCP layer drops packets that contains a single CRLF message.
181+
If a CRLFCRLF message is received, it is handled according to the
182+
*tcp_crlf_pingpong* parameter.
183+
184+
185+
*Default value is 0 (disabled).*
186+
187+
188+
```c title="Set tcp_crlf_drop parameter"
189+
...
190+
modparam("proto_tcp", "tcp_crlf_drop", 1)
191+
...
192+
```
193+
194+
195+
#### tcp_async (integer)
196+
197+
198+
If the TCP connect and write operations should be done in an
199+
asynchronous mode (non-blocking connect and
200+
write). If disabled, OpenSIPS will block and wait for TCP
201+
operations like connect and write.
202+
203+
204+
*Default value is 1 (enabled).*
205+
206+
207+
```c title="Set tcp_async parameter"
208+
...
209+
modparam("proto_tcp", "tcp_async", 0)
210+
...
211+
```
212+
213+
214+
#### tcp_async_max_postponed_chunks (integer)
215+
216+
217+
If *tcp_async* is enabled, this specifies the
218+
maximum number of SIP messages that can be stashed for later/async
219+
writing. If the connection pending writes exceed this number, the
220+
connection will be marked as broken and dropped.
221+
222+
223+
*Default value is 32.*
224+
225+
226+
```c title="Set tcp_async_max_postponed_chunks parameter"
227+
...
228+
modparam("proto_tcp", "tcp_async_max_postponed_chunks", 16)
229+
...
230+
```
231+
232+
233+
#### tcp_async_local_write_timeout (integer)
234+
235+
236+
If *tcp_async* is enabled, this specifies the
237+
number of milliseconds that a write op will be tried in blocking
238+
mode (optimization). If the write operation lasts more than this,
239+
the write will go to async mode and will be passed to TCP MAIN for
240+
polling.
241+
242+
243+
*Default value is 10 ms.*
244+
245+
246+
```c title="Set tcp_async_local_write_timeout parameter"
247+
...
248+
modparam("proto_tcp", "tcp_async_local_write_timeout", 100)
249+
...
250+
```
251+
252+
253+
#### trace_destination (string)
254+
255+
256+
Trace destination as defined in the tracing module. Currently
257+
the only tracing module is **proto_hep**.
258+
Network events such as connect, accept and connection closed events
259+
shall be traced along with errors that could appear in the process.
260+
261+
262+
**WARNING:**A tracing module must be
263+
loaded in order for this parameter to work. (for example
264+
**proto_hep**).
265+
266+
267+
*Default value is none(not defined).*
268+
269+
270+
```c title="Set trace_destination parameter"
271+
...
272+
modparam("proto_hep", "hep_id", "[hep_dest]10.0.0.2;transport=tcp;version=3")
273+
274+
modparam("proto_tcp", "trace_destination", "hep_dest")
275+
...
276+
```
277+
278+
279+
#### trace_on (int)
280+
281+
282+
This controls whether tracing for tcp is on or not. You still need to define
283+
[trace destination](#param_trace_destination)in order to work, but this value will be
284+
controlled using mi function [tcp trace](#mi_tcp_trace).
285+
286+
287+
```c title="Set trace_on parameter"
288+
...
289+
modparam("proto_tcp", "trace_on", 1)
290+
...
291+
```
292+
293+
294+
#### trace_filter_route (string)
295+
296+
297+
Define the name of a route in which you can filter which connections will
298+
be trace and which connections won't be. In this route you will have
299+
information regarding source and destination ips and ports for the current
300+
connection. To disable tracing for a specific connection the last call in
301+
this route must be **drop**, any other exit
302+
mode resulting in tracing the current connection ( of course you still
303+
have to define a [trace destination](#param_trace_destination) and trace must be
304+
on at the time this connection is opened.
305+
306+
307+
**IMPORTANT**
308+
Filtering on ip addresses and ports can be made using **$si** and **$sp** for matching
309+
either the entity that is connecting to OpenSIPS or the entity to which
310+
OpenSIPS is connecting. The name might be misleading (**$si** meaning the source ip if you read the docs) but in reality
311+
it is simply the socket other than the OpenSIPS socket. In order to match
312+
OpenSIPS interface (either the one that accepted the connection or the one
313+
that initiated a connection) **$socket_in(ip)** (ip) and
314+
**$socket_in(port)** (port) can be used.
315+
316+
317+
**WARNING:** IF [trace on](#param_trace_on) is
318+
set to 0 or tracing is deactived via the mi command [tcp trace](#mi_tcp_trace)
319+
this route won't be called.
320+
321+
322+
```c title="Set trace_filter_route parameter"
323+
...
324+
modparam("proto_tcp", "trace_filter_route", "tcp_filter")
325+
...
326+
/* all tcp connections will go through this route if tracing is activated
327+
* and a trace destination is defined */
328+
route[tcp_filter] {
329+
...
330+
/* all connections opened from/by ip 1.1.1.1:8000 will be traced
331+
on interface 1.1.1.10:5060(opensips listener)
332+
all the other connections won't be */
333+
if ( $si == "1.1.1.1" && $sp == 8000 &&
334+
$socket_in(ip) == "1.1.1.10" && $socket_in(port) == 5060)
335+
exit;
336+
else
337+
drop;
338+
}
339+
...
340+
```
341+
342+
343+
### Exported MI Functions
344+
345+
346+
#### tcp_trace
347+
348+
349+
Name: *tcp_trace*
350+
351+
352+
Parameters:
353+
354+
355+
- trace_mode(optional): set tcp tracing on and off. This parameter
356+
can be missing and the command will show the current tracing
357+
status for this module( on or off );
358+
Possible values:
359+
360+
on
361+
off
362+
363+
364+
MI FIFO Command Format:
365+
366+
367+
```c
368+
:tcp_trace:_reply_fifo_file_
369+
trace_mode
370+
_empty_line_
371+
372+
```
373+
374+
375+
## Frequently Asked Questions
376+
377+
378+
**Q: After switching to OpenSIPS 2.1, I'm getting this error:
379+
"listeners found for protocol tcp, but no module can handle it"**
380+
381+
382+
You need to load the "proto_tcp" module. In your script, make sure
383+
you do a **loadmodule "proto_tcp.so"** after setting the **[mpath](https://docs.opensips.org/manual/2-1/script-coreparameters#mpath)**.
384+
385+
386+
**Q: I cannot locate "proto_tcp.so". Where is it?**
387+
388+
389+
The "proto_udp" and "proto_tcp" modules are simply built into
390+
the opensips binary by default. They are not available as shared
391+
libraries, but look like modules for code consistency reasons.
392+
<!-- CONTRIBUTORS -->
393+
394+
### License
395+
396+
All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0

0 commit comments

Comments
 (0)