1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
The Ctl Module
Andrei Pelinescu-Onciul
iptelorg GmbH
Copyright 2009 iptelorg GmbH
_________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. BINRPC
3. Parameters
3.1. binrpc (string)
3.2. mode (integer)
3.3. user (integer or string)
3.4. group (integer or string)
3.5. fifo (integer)
3.6. autoconversion (integer)
3.7. binrpc_max_body_size (integer)
3.8. binrpc_struct_max_body_size (integer)
4. SIP-router RPC Functions
4.1. ctl.listen
4.2. ctl.connections
4.3. ctl.who
List of Examples
1.1. kamcmd example usage
1.2. Set binrpc parameter
1.3. Set mode parameter
1.4. Set user parameter
1.5. Set group parameter
1.6. Set fifo parameter
1.7. Set the autoconversion parameter
1.8. Set the binrpc_max_body_size parameter
1.9. Set the binrpc_struct_max_body_size parameter
1.10. print usage
1.11. ctl.connections usage
1.12. ctl.who usage
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. BINRPC
3. Parameters
3.1. binrpc (string)
3.2. mode (integer)
3.3. user (integer or string)
3.4. group (integer or string)
3.5. fifo (integer)
3.6. autoconversion (integer)
3.7. binrpc_max_body_size (integer)
3.8. binrpc_struct_max_body_size (integer)
4. SIP-router RPC Functions
4.1. ctl.listen
4.2. ctl.connections
4.3. ctl.who
1. Overview
This module implements the binrpc transport interface for Kamailio
RPCs. It supports various transports over which it speaks binrpc: Unix
datagram sockets, Unix stream sockets, UDP and TCP. It also supports a
backward compatible FIFO interface (using the old Kamailio FIFO
protocol).
By default (if no parameters are changed in the config file) it uses a
Unix stream socket under /tmp: /tmp/ser_ctl. This socket is also the
default for kamcmd.
In general it's used in conjunction with kamcmd. kamcmd is a Unix tool
for invoking Kamailio RPC functions. It can be used both in
interactive mode (supports tab-completion and history) or command line
mode.
Example 1.1. kamcmd example usage
$ kamcmd ps
11262 attendant
11268 udp receiver child=0 sock=127.0.0.1:5060
11269 udp receiver child=1 sock=127.0.0.1:5060
11270 udp receiver child=0 sock=192.168.1.101:5060
11271 udp receiver child=1 sock=192.168.1.101:5060
11272 slow timer
11273 timer
11274 ctl handler
11275 tcp receiver child=0
11276 tcp receiver child=1
11277 tcp main process
See utils/kamcmd/EXAMPLES for more examples.
2. BINRPC
binrpc is a ser proprietary binary protocol for invoking rpcs. It was
designed such that it would minimize the packet sizes and it would be
very fast to parse (as opposed to XML-rpc).
The binrpc encoding format is fully documented inside
modules/ctl/binrpc.h.
3. Parameters
3.1. binrpc (string)
3.2. mode (integer)
3.3. user (integer or string)
3.4. group (integer or string)
3.5. fifo (integer)
3.6. autoconversion (integer)
3.7. binrpc_max_body_size (integer)
3.8. binrpc_struct_max_body_size (integer)
3.1. binrpc (string)
Specifies the transport used for the binrpc protocol. The following
transport protocol are supported: Unix datagram sockets, Unix stream
sockets, UDP and TCP.
The format is: [ protocol:] address_port|path .
* For Unix sockets: [unixd|unixs|unix]:path where "unixd" means Unix
datagram sockets and "unix" "unixs" mean Unix stream sockets.
Examples: "unixd:/tmp/unix_dgram", "unixs:/tmp/unix_stream",
"unix:/tmp/unix_stream".
* For UDP or TCP sockets: [udp|tcp]:address:port. If the address is
"*" or missing, it will bind to all the local addresses (0.0.0.0).
Examples: "udp:localhost:2046", "tcp:localhost:2046", "tcp:3012",
"udp:*:3012".
If the protocol part is missing and the address/path part looks like a
file system path it will default to a Unix stream socket and if not to
an Unix UDP socket. Examples:
* "/tmp/unix_test" - equivalent to "unixs:/tmp/unix_test".
* "localhost:3000" - equivalent to "udp:localhost:3000".
Multiple transports / listen addresses can be specified, just by
setting the parameter multiple times.
Default:"unix:/tmp/ser_ctl" (Unix stream socket). The default value is
used only if no binrpc parameter is found in the config file.
Example 1.2. Set binrpc parameter
loadmodule "ctl"
# optional listen addresses, if no one is specified,
# ctl will listen on unixs:/tmp/ser_ctl
modparam("ctl", "binrpc", "unix:/tmp/ser_ctl") # default
modparam("ctl", "binrpc", "udp:localhost:2046")
modparam("ctl", "binrpc", "tcp:localhost:2046")
modparam("ctl", "binrpc", "unixd:/tmp/unix_dgram") # unix datagram
modparam("ctl", "binrpc", "unixs:/tmp/unix_stream") # unix stream
modparam("ctl", "binrpc", "unix:/tmp/unix_default") # unix stream
modparam("ctl", "binrpc", "/tmp/unix_test") # unix stream
modparam("ctl", "binrpc", "localhost:3000") # udp
modparam("ctl", "binrpc", "tcp:3012") # tcp any , port 3012
modparam("ctl", "binrpc", "udp:*:3012") # udp any , port 3012
3.2. mode (integer)
Permissions used for the created Unix sockets or for the fifo.
Default: 0600.
Example 1.3. Set mode parameter
modparam("ctl", "mode", 0600) # permissions
3.3. user (integer or string)
Username or uid used for the created Unix sockets or for the fifo.
Default: not set (the user under which SER runs).
Example 1.4. Set user parameter
modparam("ctl", "user", "andrei")
3.4. group (integer or string)
Group name or gid used for the created Unix sockets or for the fifo.
Default: not set (the group under which SER runs).
Example 1.5. Set group parameter
modparam("ctl", "group", 100)
3.5. fifo (integer)
fifo used for the obsolete fifo protocol. The fifo protocol can be run
over a real fifo, over UDP or over TCP. Format:
[protocol:]path|address. If no protocol is specified the default is
"fifo". Examples: "fifo:/tmp/ser_fifo", "/tmp/ser_fifo2",
"udp:*:2050", "tcp:localhost:2050". For more details on the UDP and
TCP formats see binrpc. Multiple fifos or fifo transports can be used
in the same time (just by setting the fifo parameter multiple times in
the config).
Default: not set (no fifo will be used).
Example 1.6. Set fifo parameter
# old fifo support
modparam("ctl", "fifo", "fifo:/tmp/ser_fifo") # clasic fifo
modparam("ctl", "fifo", "/tmp/ser_fifo2")
modparam("ctl", "fifo", "udp:*:2050") # fifo protocol over udp
modparam("ctl", "fifo", "tcp:*:2050") # fifo over tcp
3.6. autoconversion (integer)
Enable or disable automatic type conversion globally, for all the
methods parameters. If on, a type mismatch in a method parameter will
not cause a fault if it is possible to automatically convert it to the
expected type.
Default: off
It is recommended to leave this parameter to its default off value and
fix instead the client application (which should use the proper types)
or to modify the target rpc to accept any type (see the rpc scan '.'
modifier).
Example 1.7. Set the autoconversion parameter
modparam("ctl", "autoconversion", 1)
3.7. binrpc_max_body_size (integer)
Set the size of binrpc buffer for RPC reply. Value represents
kilobytes.
Default: 4 (meaning 4KB);
Example 1.8. Set the binrpc_max_body_size parameter
modparam("ctl", "binrpc_max_body_size", 10)
3.8. binrpc_struct_max_body_size (integer)
Set the size of binrpc structure buffer for RPC reply. Value
represents kilobytes.
Default: 1 (meaning 1KB);
Example 1.9. Set the binrpc_struct_max_body_size parameter
modparam("ctl", "binrpc_struct_max_body_size", 3)
4. SIP-router RPC Functions
4.1. ctl.listen
4.2. ctl.connections
4.3. ctl.who
4.1. ctl.listen
List all the sockets on which the ctl module listens.
Example 1.10. print usage
$ kamcmd -f"[%v] %v:%v %v\n" ctl.listen
[binrpc] unix_stream:/tmp/ser_ctl
# note: the above command is equivalent with kamcmd listen
4.2. ctl.connections
Returns the number of open binrpc connections (to the ctl module).
Example 1.11. ctl.connections usage
$ kamcmd ctl.connections
1
4.3. ctl.who
List open binrpc connections (to the ctl module).
Example 1.12. ctl.who usage
$ kamcmd -f"[%v] %v: %v %v -> %v %v\n" ctl.who
[binrpc] unix_stream: <anonymous unix socket> -> /tmp/ser_ctl
# note the above command is equivalent to kamcmd who
|
