/
xmlrpc_admin.xml
313 lines (299 loc) · 8.9 KB
/
xmlrpc_admin.xml
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;
]>
<chapter>
<title>&adminguide;</title>
<section>
<title>Dependencies</title>
<section>
<title>&kamailio; modules</title>
<para>
The following modules must be loaded before this module:
<itemizedlist>
<listitem>
<para>
<emphasis>SL</emphasis> - Stateless request handling
</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Parameters</title>
<section id="route">
<title><varname>route</varname> (string)</title>
<para>
Name of the route called for XMLRPC messages.
</para>
<para>
This route will be called only for HTTP messages whose method is
either GET or POST. The message visible inside the route
will be a HTTP request converted to SIP (the uri will be fixed and
a fake via will be added).
</para>
<para>
The route should perform additional security checks to
ensure the client is authorized to execute management/RPC functions
and then it should call the <function>dispatch_rpc()</function>.
</para>
<para>
Default: the main route is used.
</para>
<example>
<title>Set <varname>route</varname> parameter</title>
<programlisting>
modparam("xmlrpc", "route", "route_for_xmlrpcs")
</programlisting>
</example>
</section>
<section id="autoconversion">
<title><varname>autoconversion</varname> (string)</title>
<para>
Enable or disable automatic parameter 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 type expected by the method.
</para>
<para>
Default: off.
</para>
<para>
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).
</para>
<example>
<title>Set the <varname>autoconversion</varname> parameter</title>
<programlisting>
modparam("xmlrpc", "autoconversion", 1)
</programlisting>
</example>
</section>
<section id="escape_cr">
<title><varname>escape_cr</varname> (integer)</title>
<para>
Enable CR ('\r') escaping in replies. If enabled each '\r' in the
xmlrpc reply will be replaced with "&#xD;", according to the
xml spec.
</para>
<para>
It should be turned off only if you suspect interoperability problems
with older clients.
</para>
<para>
Default: on.
</para>
<example>
<title>Set the <varname>escape_cr</varname> parameter</title>
<programlisting>
modparam("xmlrpc", "escape_cr", 1)
</programlisting>
</example>
</section>
<section id="double_lf_to_crlf">
<title><varname>double_lf_to_crlf</varname> (integer)</title>
<para>
When enabled double LFs ('\n\n') in the input xmlrpc strings
will be replaced with CR LF ('\r\n'). This makes LF LF behave like
an escape character for CR LF and is needed for compatibility with
&kamailio; tools and to work around buggy xmlrpc clients that don't
escape the CR in CR LF ('\r' should be escaped to "&#xD;"
otherwise according to the xml spec "\r\n" will be transformed to
'\n'), but need to send CR LF in the strings (e.g. they use
<function>tm.t_uac_wait</function>).
</para>
<para>
Note: when this option is turned on, there is no way to send a double
LF ('\n\n'), it will always be transformed in CR LF ('\r\n').
</para>
<para>
Default: off.
</para>
<example>
<title>Set the <varname>double_lf_to_crlf</varname> parameter</title>
<programlisting>
modparam("xmlrpc", "double_lf_to_crlf", 1)
</programlisting>
</example>
</section>
<section id="param_mode">
<title><varname>mode</varname> (integer)</title>
<para>
When set to 1, the xmlrpc module does not register to core the callback
functions for non-SIP messages. Useful when another module register
a callback for HTTP request, letting the admin decide when to
call the XMLRPC route (or functions).
</para>
<para>
Default: 0.
</para>
<example>
<title>Set the <varname>mode</varname> parameter</title>
<programlisting>
modparam("xmlrpc", "mode", 1)
</programlisting>
</example>
</section>
<section>
<title><varname>url_skip</varname> (str)</title>
<para>
Regular expression to match the HTTP URL. If there is a match,
then the xmlrpc route is not executed.
</para>
<para>
<emphasis>
Default value is null (don't skip).
</emphasis>
</para>
<example>
<title>Set <varname>url_skip</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("xmlrpc", "url_skip", "^/sip")
...
</programlisting>
</example>
</section>
<section>
<title><varname>url_match</varname> (str)</title>
<para>
Regular expression to match the HTTP URL. If there is no match,
then xmlrpc route is not executed. This check is done after
url_skip, so if both url_skip and url_match would match then
the xmlrpc route is not executed (url_skip has higher priority).
</para>
<para>
<emphasis>
Default value is null (match everything).
</emphasis>
</para>
<example>
<title>Set <varname>url_match</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("xmlrpc", "url_match", "^/RPC2")
...
</programlisting>
</example>
</section>
<section id="event_callback">
<title><varname>event_callback</varname> (string)</title>
<para>
The name of the function in the kemi configuration file (embedded
scripting language such as Lua, Python, ...) to be executed instead
of route blocks defined by route parameter for xmlrpc request.
</para>
<para>
This route will be called only for HTTP messages whose method is
either GET or POST. The message visible inside the route
will be a HTTP request converted to SIP (the uri will be fixed and
a fake via will be added).
</para>
<para>
The route should perform additional security checks to
ensure the client is authorized to execute management/RPC functions
and then it should call the <function>dispatch_rpc()</function>.
</para>
<example>
<title>Set <varname>event_callback</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("xmlrpc", "event_callback", "ksr_xmlrpc_event")
...
-- event callback function implemented in Lua
function ksr_xmlrpc_event(evname)
KSR.info("===== xmlrpc triggered event: " .. evname .. "\n");
local rpc_method = KSR.pv.get("$rm") or ""
if ((rpc_method == "POST" or rpc_method == "GET")) then
if (KSR.xmlrpc.dispatch_rpc() < 0) then
KSR.err("error while executing xmlrpc event")
end
end
return 1;
end
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Functions</title>
<section id="xmlrpc.dispatch_rpc">
<title>
<function>dispatch_rpc()</function>
</title>
<para>
This function processes an XMLRPC request, found in the body of
the request.
</para>
<para>
It should be used only in a route specified using the
<varname>"route"</varname> module parameter or if the request method
is GET or POST (using it for other request methods will not have
adverse side-effects, but it will probably not work).
</para>
<para>
dispatch_rpc() extracts the XML-RPC document from the body of the
request to determine the name of the RPC method to be called and then
it searches through the list of all the RPC functions to find a
function with matching name. If such a function is found then
dispatch_rpc() will pass control to the function to handle the
request.
</para>
<example>
<title><function>dispatch_rpc</function> usage</title>
<programlisting>
#...
modparam("xmlrpc", "route", "XMLRPC");
#...
route[XMLRPC]{
if search("^User-Agent:.*xmlrpclib"))
set_reply_close();
set_reply_no_connect(); # optional
dispatch_rpc();
}
</programlisting>
</example>
</section>
<section id="xmlrpc.xmlrpc_reply">
<title>
<function>xmlrpc_reply(code, reason)</function>
</title>
<para>
This function can be called from the config script to directly
generate an XML-RPC reply.
</para>
<example>
<title><function>xmlrpc_reply</function> usage</title>
<programlisting>
#...
modparam("xmlrpc", "route", "XMLRPC");
#...
route[XMLRPC]{
# allow XMLRPC requests only on TLS and only if the client
# certificate is valid
if (proto!=TLS){
xmlrpc_reply("400", "xmlrpc allowed only over TLS");
return;
}
if (@tls.peer.verified!=""){
xmlrpc_reply("400", "Unauthorized");
return;
}
if search("^User-Agent:.*xmlrpclib"))
set_reply_close();
set_reply_no_connect(); # optional
dispatch_rpc();
}
</programlisting>
</example>
</section>
</section>
</chapter>