8c933e8f0ff43490cc9df1d947ebd5d6e0286ccb
[sip-router] / src / modules / http_client / doc / http_client_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19         This module implements protocol functions that use the libcurl library
20         to fetch data from external HTTP servers or post data to HTTP servers.
21         The module is using a concept of "connections" to define properties
22         of HTTP sessions in a simple way.
23         </para>
24         <para>
25         The http_client module has multiple settings, some of them applies to
26         a defined connection. You can set timeouts, max data sizes for download
27         and much more either using modparam settings or parameters to the
28         connection definition.
29         </para>
30         <para>
31         The connections can either be defined with the "httpcon" module parameter
32         or in a separate configuration file, as specified by the "config_file" module
33         parameter. 
34         </para>
35         <para>
36         Like in SIP, the HTTP URL may need encoding to be transported safely
37         over the network. Check the string encoding functions in the Transformation
38         Cookbook (as used in the http_client_query example below).
39         </para>
40         <para>
41         Function http_client_query allows &kamailio; to issue an HTTP GET
42         request and get access to parts of the reply. This function has
43         been ported from the utils module and now use the same libcurl
44         functions.
45         </para>
46         <para>
47         The http_client module use the CURL library setting up connections.
48         The CURL library by default use the system configured DNS resolvers,
49         not the Kamailio resolver.
50         </para>
51         <para>
52         The module is limited to using HTTP and HTTPS protocols.
53         </para>
54         </section>
55         <section>
56         <title>Dependencies</title>
57         <section>
58                 <title>&kamailio; Modules</title>
59                 <para>
60                 The following modules must be loaded before this module:
61                         <itemizedlist>
62                         <listitem>
63                         <para>
64                         TLS - if you use TLS connections (https) the tls module should be
65                         loaded first in order to initialize &openssl; properly.
66                         </para>
67                         </listitem>
68                         </itemizedlist>
69                 </para>
70         </section>
71         <section>
72                 <title>External Libraries or Applications</title>
73                 <para>
74                 The following libraries or applications must be
75                 installed before  
76                 running &kamailio; with this module loaded:
77                         <itemizedlist>
78                         <listitem>
79                         <para>
80                                 <emphasis>&libcurl;</emphasis>.
81                         </para>
82                         </listitem>
83                         </itemizedlist>
84                 </para>
85         </section>
86         </section>
87         
88         <section>
89                 <title>Parameters</title>
90                 <section id="http_client.p.httpredirect">
91                         <title><varname>httpredirect</varname> (int)</title>
92                         <para>
93                         If set to 1, enabled, http_client will follow HTTP 302 Redirects.
94                         If set to 0, http_client will not follow redirects. Default is 1, enabled.
95                         </para>
96                         <para>
97                         The latest redirect URL will be stored in the <emphasis>$curlredirect</emphasis>
98                         pseudovariable.
99                         </para>
100                         <example>
101                         <title>Set <varname>httpredirect</varname> parameter</title>
102                                 <programlisting format="linespecific">
103 ...
104 modparam("http_client", "httpredirect", 0)
105 ...
106                                 </programlisting>
107                         </example>
108                 </section>
109                 <section id="http_client.p.httpproxy">
110                         <title><varname>httpproxy</varname> (string)</title>
111                         <para>
112                         URL for a HTTP proxy to use as a default proxy for all connections.
113                         </para>
114                         <para>
115                         This setting is also available on a per connection basis in the
116                         http_client configuration file.
117                         </para>
118                         <example>
119                         <title>Set <varname>httpproxy</varname> parameter</title>
120                                 <programlisting format="linespecific">
121 ...
122 modparam("http_client", "httpproxy", "https://superproxy.example.com")
123 ...
124                                 </programlisting>
125                         </example>
126                 </section>
127                 <section id="http_client.p.httpproxyport">
128                         <title><varname>httpproxyport</varname> (string)</title>
129                         <para>
130                         Port number for a HTTP proxy to use as a default proxy port for all connections.
131                         </para>
132                         <para>
133                         This setting is also available on a per connection basis in the
134                         http_client configuration file.
135                         </para>
136                         <example>
137                         <title>Set <varname>httpproxyport</varname> parameter</title>
138                                 <programlisting format="linespecific">
139 ...
140 modparam("http_client", "httpproxyport", 8042)
141 ...
142                                 </programlisting>
143                         </example>
144                 </section>
145                 <section id="http_client.p.useragent">
146                         <title><varname>useragent</varname> (string)</title>
147                         <para>
148                         Useragent to use in the HTTP protocol for requests. Defaults to
149                         the &kamailio; SIP useragent string - including software version and platform.
150                         </para>
151                         <example>
152                         <title>Set <varname>useragent</varname> parameter</title>
153                                 <programlisting format="linespecific">
154 ...
155 modparam("http_client", "useragent", "Secret HTTP REST grabber 0.42")
156 ...
157                                 </programlisting>
158                         </example>
159                 </section>
160                 <section id="http_client.p.maxdatasize">
161                         <title><varname>maxdatasize</varname> (int)</title>
162                         <para>
163                         Defines the maximum size in bytes for a response. Note that this
164                         is allocated from pkg memory (process memory) dynamically.
165                         </para>
166                         <para>
167                         <emphasis>
168                                 Default value is zero, i.e.,
169                                 the limit on the datasize is disabled.
170                         </emphasis>
171                         </para>
172                         <example>
173                         <title>Set <varname>maxdatasize</varname> parameter</title>
174                                 <programlisting format="linespecific">
175 ...
176 modparam("http_client", "maxdatasize", 2000)
177 ...
178                                 </programlisting>
179                         </example>
180                 </section>
181                 <section id="http_client.p.connection_timeout">
182                         <title><varname>connection_timeout</varname> (int)</title>
183                         <para>
184                         Defines in seconds how long &kamailio; waits for response
185                         from servers.
186                         </para>
187                         <para>
188                         <emphasis>
189                                 Default value is zero, i.e.,
190                                 the timeout function is disabled.
191                         </emphasis>
192                         </para>
193                         <example>
194                         <title>Set <varname>connection_timeout</varname> parameter</title>
195                                 <programlisting format="linespecific">
196 ...
197 modparam("http_client", "connection_timeout", 2)
198 ...
199                                 </programlisting>
200                         </example>
201                 </section>
202                 <section id="http_client.p.client_cert">
203                         <title><varname>client_cert</varname> (string)</title>
204                         <para>
205                         File name for a TLS client certificate. The certificate needs to be encoded
206                         in PEM format.
207                         </para>
208                         <para>
209                         <emphasis>
210                                 Default value is empty string, i.e.
211                                 no client certificate used. Note that if
212                                 you specify a client cert, you also need to specify
213                                 the <varname>client_key</varname>.
214                         </emphasis>
215                         </para>
216                         <example>
217                         <title>Set <varname>client_cert</varname> parameter</title>
218                                 <programlisting format="linespecific">
219 ...
220 modparam("http_client", "client_cert", "/var/certs/sollentuna.example.com.cert")
221 ...
222                                 </programlisting>
223                         </example>
224                 </section>
225                 <section id="http_client.p.client_key">
226                         <title><varname>client_key</varname> (string)</title>
227                         <para>
228                         File name for a TLS client key. The key needs to be encoded
229                         in PEM format.
230                         </para>
231                         <para>
232                         <emphasis>
233                                 Default value is empty string, i.e.
234                                 no client certificate or key is used. Note that if
235                                 you specify a client key, you also need to specify
236                                 the <varname>client_cert</varname>.
237                         </emphasis>
238                         </para>
239                         <example>
240                         <title>Set <varname>client_key</varname> parameter</title>
241                                 <programlisting format="linespecific">
242 ...
243 modparam("http_client", "client_key", "/var/certs/sollentuna.example.com.key")
244 ...
245                                 </programlisting>
246                         </example>
247                 </section>
248                 <section id="http_client.p.cacert">
249                         <title><varname>cacert</varname> (string)</title>
250                         <para>
251                         File name for the trusted TLS CA cert used to verify servers.
252                         The certificates need to be encoded in PEM format.
253                         </para>
254                         <para>
255                         <emphasis>
256                                 Default value is empty string, i.e.
257                                 no CA certificate is used to verify the host. If
258                                 <varname>tlsverifyhost</varname> is on, all TLS
259                                 connections will fail without any CA certificate
260                                 to validate with.
261                         </emphasis>
262                         </para>
263                         <example>
264                         <title>Set <varname>cacert</varname> parameter</title>
265                                 <programlisting format="linespecific">
266 ...
267 modparam("http_client", "cacert", "/var/certs/ca/edvina-sip-ca.pem")
268 ...
269                                 </programlisting>
270                         </example>
271                 </section>
272                 <section id="http_client.p.cipher_suites">
273                         <title><varname>cipher_suites</varname> (string)</title>
274                         <para>
275                         List of allowed cipher suites.
276                         See http://curl.haxx.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html for details
277                         of the cipher list curl option.
278                         </para>
279                         <para>
280                         <emphasis>
281                                 Default value is empty string, i.e.
282                                 the default list of ciphers in libcurl will be used.
283                         </emphasis>
284                         </para>
285                         <example>
286                         <title>Set <varname>cipher_suites</varname> parameter</title>
287                                 <programlisting format="linespecific">
288 ...
289 modparam("http_client", "cipher_suites", "ecdhe_ecdsa_aes_128_gcm_sha_256,rsa_aes_128_gcm_sha_256")
290 ...
291                                 </programlisting>
292                         </example>
293                 </section>
294                 <section id="http_client.p.verify_peer">
295                         <title><varname>verify_peer</varname> (int)</title>
296                         <para>
297                         If set to 0, TLS verification of the server certificate
298                         is disabled. This means that the connection will get 
299                         encrypted, but there's no authentication. There's no
300                         proof that the transmission of data is to the host
301                         that is meant to receive data.
302                         </para>
303                         <para>
304                         If set to 1, default setting, and one or more CA certificates
305                         is configured, the server TLS certificate will be validated.
306                         If validation fails, the connection fails.
307                         </para>
308                         <para>
309                         See the curl documentation for more details.
310                         http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
311                         </para>
312                         <example>
313                         <title>Set <varname>verify_peer</varname> parameter</title>
314                                 <programlisting format="linespecific">
315 ...
316 modparam("http_client", "verify_peer", 1)
317 ...
318                                 </programlisting>
319                         </example>
320                 </section>
321                 <section id="http_client.p.verify_host">
322                         <title><varname>verify_host</varname> (int)</title>
323                         <para>
324                         If set to 0, domain verification of the server certificate
325                         is disabled. This means that the connection will get 
326                         encrypted but there is no check that data will be sent to the
327                         host that is meant to receive it. Disable with caution.
328                         </para>
329                         <para>
330                         If set to 2, default setting, the hostname in the URL will
331                         be verified against the Common Name or Subject Alt Name
332                         in the certificate. If validation fails, the connection fails.
333                         </para>
334                         <para>
335                         See the curl documentation for more details.
336                         http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
337                         </para>
338                         <example>
339                         <title>Set <varname>verify_host</varname> parameter</title>
340                                 <programlisting format="linespecific">
341 ...
342 modparam("http_client", "verify_host", 2)
343 ...
344                                 </programlisting>
345                         </example>
346                 </section>
347                 <section id="http_client.p.tlsversion">
348                         <title><varname>tlsversion</varname> (int)</title>
349                         <para>
350                         Sets the preferred TLS/SSL version.
351                         </para>
352                         <para>
353                         Valid values are:
354                                 <itemizedlist>
355                                 <listitem><para>0 - Use libcurl default</para></listitem>
356                                 <listitem><para>1 - "TLSv1"</para></listitem>
357                                 <listitem><para>2 - "SSLv2"</para></listitem>
358                                 <listitem><para>3 - "SSLv3"</para></listitem>
359                                 <listitem><para>4 - "TLSv1.0"</para></listitem>
360                                 <listitem><para>5 - "TLSv1.1"</para></listitem>
361                                 <listitem><para>6 - "TLSv1.2"</para></listitem>
362                                 </itemizedlist>
363                         </para>
364                         <para>
365                         SSL versions are now disabled by default.
366                         See the curl documentation for more details.
367                         http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
368                         </para>
369                         <example>
370                         <title>Set <varname>tlsversion</varname> parameter</title>
371                                 <programlisting format="linespecific">
372 ...
373 modparam("http_client", "tlsversion", 6)
374 ...
375                                 </programlisting>
376                         </example>
377                 </section>
378                 <section id="http_client.p.authmethod">
379                         <title><varname>authmethod</varname> (int)</title>
380                         <para>
381                         Sets the preferred authentication mode for HTTP/HTTPS requests. The value is a bitmap
382                         and multiple methods can be used. Note that in this case, the CURL library will make an
383                         extra request to discover server-supported authentication methods. You may want to use
384                         a specific value.
385                         </para>
386                         <para>
387                         Valid values are:
388                                 <itemizedlist>
389                                 <listitem><para>1 - BASIC authentication</para></listitem>
390                                 <listitem><para>2 - HTTP Digest authentication</para></listitem>
391                                 <listitem><para>4 - GSS-Negotiate authentication</para></listitem>
392                                 <listitem><para>8 - NTLM authentication</para></listitem>
393                                 <listitem><para>16 - HTTP Digest with IE flavour</para></listitem>
394                                 </itemizedlist>
395                         Default value is 3 - BASIC and Digest authentication.
396                         </para>
397                         <para>
398                         This is also configurable per connection in the http_client configuration file.
399                         </para>
400                         <example>
401                         <title>Set <varname>authmethod</varname> parameter</title>
402                                 <programlisting format="linespecific">
403 ...
404 # Use the best of BASIC and Digest authentication.
405 modparam("http_client", "authmetod", 3)
406 ...
407                                 </programlisting>
408                         </example>
409                 </section>
410                 <section id="http_client.p.keep_connections">
411                         <title><varname>keep_connections</varname> (int)</title>
412                         <para>
413                         If an HTTP server is accessed multiple times keeping the connection open for reuse
414                         saves a significant amount of time, especially if TLS is used. If this function
415                         is enabled, the Curl library will try to reuse existing open connections. The
416                         HTTP server will have to support this feature and keep connections open for it
417                         to work properly.
418                         </para>
419                         <para>
420                         Valid values are:
421                                 <itemizedlist>
422                                 <listitem><para>0 - Close connections after request (default)</para></listitem>
423                                 <listitem><para>1 - Reuse connections</para></listitem>
424                                 </itemizedlist>
425                         </para>
426                         <para>
427                         This is also configurable per connection in the http_client configuration file.
428                         </para>
429                         <example>
430                         <title>Set <varname>keep_connections</varname> parameter</title>
431                                 <programlisting format="linespecific">
432 ...
433 modparam("http_client", "keep_connections", 1)
434 ...
435                                 </programlisting>
436                         </example>
437                 </section>
438                 <section id="http_client.p.httpcon">
439                         <title><varname>httpcon</varname> (string)</title>
440                         <para>
441                         Defines a connection and credentials for the connection for use
442                         in a connection-oriented function call in this module.
443                         </para>
444                         <para>
445                         <emphasis>Syntax:</emphasis>
446                         &lt;connection-name&gt;=&gt;&lt;schema&gt;://[&lt;username&gt;:&lt;password&gt;@]&lt;hostname/address&gt;[;param=value]
447                         </para>
448                         <para>
449                         The address in the URL is the base for the URL in the <function>http_connect()</function> call. The
450                         address given in the function call will be appended to the base URL in the connection definition.
451                         </para>
452                         <para>
453                         The HTTP connection will be defined using default values in modparam's above the definition
454                         of the httpcon in the configuration file. Also note that connections can be defined in a
455                         separate text file if you have many parameters per connection, or want to use a per-connection
456                         setting that can be set in that file but not in the httpcon modparam, like authmethod.
457                         </para>
458                         <para>
459                         <emphasis>
460                                 By default, no connections are defined.
461                         </emphasis>
462                         </para>
463                         <para>
464                         Parameters
465                         <itemizedlist>
466                                 <listitem><para>
467                                 <emphasis>useragent</emphasis> Useragent used for HTTP requests. Overrides
468                                 useragent modparam.
469                                 </para></listitem>
470                                 <listitem><para>
471                                 <emphasis>verify_peer</emphasis> Set to 1 to enable or 0 to disable server
472                                 certificate verification.
473                                 Overrides verify_peer modparam.
474                                 </para></listitem>
475                                 <listitem><para>
476                                 <emphasis>verify_host</emphasis> Set to 2 to enable or 0 to disable server
477                                 hostname verification.
478                                 Overrides verify_host modparam.
479                                 </para></listitem>
480                                 <listitem><para>
481                                 <emphasis>client_cert</emphasis> Client certificate used for this connection.
482                                 Overrides the default client_cert modparam.
483                                 </para></listitem>
484                                 <listitem><para>
485                                 <emphasis>client_key</emphasis> Client key used for this connection.
486                                 Overrides the default client_key modparam.
487                                 </para></listitem>
488                                 <listitem><para>
489                                 <emphasis>cipher_suites</emphasis> Client certificate used for this connection.
490                                 Overrides the default cipher_suite modparam.
491                                 </para></listitem>
492                                 <listitem><para>
493                                 <emphasis>timeout</emphasis> Timeout used for this connection. Overrides the 
494                                 default connection_timeout for the module.
495                                 </para></listitem>
496                                 <listitem><para>
497                                 <emphasis>tlsversion</emphasis> TLS version used for this connection. Overrides the 
498                                 default tlsversion for the module.
499                                 </para></listitem>
500                                 <listitem><para>
501                                 <emphasis>maxdatasize</emphasis> The maximum datasize for a response. Overrides
502                                 the maxdatasize modparam setting.
503                                 </para></listitem>
504                                 <listitem><para>
505                                 <emphasis>httpredirect</emphasis> Set to 1 for following HTTP 302
506                                 redirect. 0 to disable. Overrides the default httpredirect modparam.
507                                 </para></listitem>
508                                 <listitem><para>
509                                 <emphasis>failover</emphasis> The name of another <emphasis>httpcon</emphasis>
510                                 connection to use with the same arguments in case a connection with this http_con fails.
511                                 Failure is either a connection failure or a response code of 500 or above.
512                                 </para></listitem>
513                         </itemizedlist>
514                         </para>
515                         <example>
516                         <title>Set <varname>httpcon</varname> parameter</title>
517                                 <programlisting format="linespecific">
518 ...
519 modparam("http_client", "httpcon", "apione=>http://atlanta.example.com")
520 modparam("http_client", "httpcon", "apitwo=>http://atlanta.example.com/api/12")
521 modparam("http_client", "httpcon", "apithree=>http://annabella:mysecret@atlanta.example.com/api/12")
522 modparam("http_client", "httpcon", "apifour=>http://stockholm.example.com/api/getstuff;timeout=12;failover=apione")
523 ...
524                                 </programlisting>
525                         </example>
526                 </section>
527                 <section id="http_client.p.config_file">
528                         <title><varname>config_file</varname> (string)</title>
529                         <para>
530                         The file name of a configuration file containing definitions
531                         of http connections. This is an alternative to the
532                         "httpcon" module parameter - especially when the number of
533                         options per line gets too big.
534                         </para>
535                         <para>
536                         If the file or directory name starts with a '.' the path will be relative to the
537                         working directory (<emphasis>at runtime</emphasis>). If it starts
538                         with a '/' it will be an absolute path and if it starts with anything
539                         else the path will be relative to the main config file directory
540                         (e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
541                         </para>
542                         <para>
543                                 The following parameters can be set in the config file, for each connection.
544                                 If a parameter is not specified, the default values set by the modparams will be used.
545                         </para>
546                         <itemizedlist>
547                                 <listitem><para>url</para></listitem>
548                                 <listitem><para>username</para></listitem>
549                                 <listitem><para>password</para></listitem>
550                                 <listitem><para>authmethod</para></listitem>
551                                 <listitem><para>keep_connections</para></listitem>
552                                 <listitem><para>useragent</para></listitem>
553                                 <listitem><para>verify_peer</para></listitem>
554                                 <listitem><para>verify_host</para></listitem>
555                                 <listitem><para>client_cert</para></listitem>
556                                 <listitem><para>client_key</para></listitem>
557                                 <listitem><para>cipher_suites</para></listitem>
558                                 <listitem><para>tlsversion - Valid values are:</para>
559                                 <itemizedlist>
560                                 <listitem><para>"DEFAULT"</para></listitem>
561                                 <listitem><para>"TLSv1"</para></listitem>
562                                 <listitem><para>"SSLv22</para></listitem>
563                                 <listitem><para>"SSLv3"</para></listitem>
564                                 <listitem><para>"TLSv1.0"</para></listitem>
565                                 <listitem><para>"TLSv1.1"</para></listitem>
566                                 <listitem><para>"TLSv1.2"</para></listitem>
567                                 </itemizedlist>
568                                 </listitem>
569                                 <listitem><para>timeout</para></listitem>
570                                 <listitem><para>maxdatasize</para></listitem>
571                                 <listitem><para>http_follow_redirect</para></listitem>
572                                 <listitem><para>httpproxy</para></listitem>
573                                 <listitem><para>httpproxyport</para></listitem>
574                                 <listitem><para>failover</para></listitem>
575                         </itemizedlist>
576                         See the "httpcon" module parameter for explanation of these settings.
577                         <para>
578                         By default no config file is specified.
579                         </para>
580                         <para>
581                         All the parameters that take filenames as values will be resolved
582                         using the same rules as for the tls config filename itself: starting
583                         with a '.' means relative to the working directory, a '/' means an
584                         absolute path and  anything else a path relative to the directory of
585                         the current &kamailio; main config file.
586                         </para>
587                         <para>
588                         To set a string value to null, in order to override default settings,
589                         you can specify an value of "" - two quotation marks. In order to disable
590                         a http proxy setting you can set the port to zero.
591                         </para>
592                         <example>
593                         <title>Set <varname>config_file</varname> parameter</title>
594                                 <programlisting format="linespecific">
595 ...
596 modparam("http_client", "config_file", "httpconnections.cfg)
597 ...
598                                 </programlisting>
599                         </example>
600                         <example>
601                         <title>Short http_client config file</title>
602         <programlisting>
603 [authapiserver]
604 url = https://api.runbo.example.com/v4.2/auth
605 timeout = 1
606 maxdatasize = 4 
607 tlsversion = TLSv1.2
608 verify_peer = yes
609 client_key = default_key.pem
610 client_cert = default_cert.pem
611 http_follow_redirect = no
612
613         </programlisting>
614         </example>
615
616                 </section>
617         </section>
618
619         <section>
620         <title>Functions</title>
621                 <section id="http_client.f.http_connect">
622                         <title>
623                                 <function moreinfo="none">http_connect(connection, url, [content_type, data,] result)</function>
624                         </title>
625                         <para>
626                         Sends HTTP GET or POST request to a given connection. For a
627                         POST request, content-type can be specified.
628                         </para>
629                         <itemizedlist>
630                                 <listitem>
631                                         <para>
632                                                 <emphasis>connection</emphasis> - the name of an existing
633                                                 HTTP connection, definied by a httpcon modparam.
634                                         </para>
635                                         <para>
636                                                 <emphasis>url</emphasis> - the part of the URL to add to the
637                                                 predefined URL in the connection definition.
638                                         </para>
639                                         <para>
640                                                 <emphasis>content_type</emphasis> - Used only when posting
641                                                 data with HTTP POST. An Internet Media type, like
642                                                 "application/json" or "text/plain". Will be added to the
643                                                 HTTP request as a header.
644                                         </para>
645                                         <para>
646                                                 <emphasis>data</emphasis> - Data or a pseudo variable holding
647                                                 data to be posted.
648                                         </para>
649                                         <para>
650                                                 <emphasis>result</emphasis> - The name of a pseudo variable that
651                                                 will have the data of the response from the HTTP server.
652                                         </para>
653                                 </listitem>
654                         </itemizedlist>
655                         <para>
656                         The return value is the HTTP return code (if >=100) or the
657                         CURL error code if below 100. See the $curlerror pseudovariable
658                         below for more information about CURL error codes.
659                         </para>
660                         <para>
661                         This function can be used from REQUEST_ROUTE,
662                         ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
663                         </para>
664                         <example>
665                                 <title><function>http_connect()</function> usage</title>
666                                 <programlisting format="linespecific">
667 ...
668 modparam("http_client", "httpcon", "apiserver=>http://kamailio.org/api/");
669 ...
670 # POST Request
671 $var(res) = http_connect("apiserver", "/mailbox", "application/json", "{ ok, {200, ok}}", "$avp(gurka)");
672 xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n");
673
674 $var(res) = http_connect("apiserver", "/callroute", "application/json", "$var(jsondata)", "$avp(route)");
675 xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n");
676 ...
677                                 </programlisting>
678                         </example>
679                 </section>
680                 <section id="http_client.f.http_get_redirect">
681                         <title>
682                                 <function moreinfo="none">http_get_redirect(connection, result)</function>
683                         </title>
684                         <para>
685                         When a http connection gets a redirect and the connection is configured to follow
686                         redirects (301,302) then the target URL, the result of the redirects can be
687                         retrieved with this function after a successful connection.
688                         </para>
689                         <itemizedlist>
690                                 <listitem>
691                                         <para>
692                                                 <emphasis>connection</emphasis> - the name of an existing
693                                                 HTTP connection, definied by a httpcon modparam.
694                                         </para>
695                                         <para>
696                                                 <emphasis>result</emphasis> - The name of a pseudo variable that
697                                                 will contain the last used URL.
698                                         </para>
699                                 </listitem>
700                         </itemizedlist>
701                         <example>
702                                 <title><function>http_get_redirect()</function> usage</title>
703                                 <programlisting format="linespecific">
704 ...
705 modparam("http_client", "httpredirect", 1);
706 ...
707 http_get_redirect("apiserver", "$var(targeturl)");
708 ...
709                                 </programlisting>
710                         </example>
711                 </section>
712                 <section id="http_client.f.curl_http_query">
713                         <title>
714                                 <function moreinfo="none">http_client_query(url, [post-data], result)</function>
715                         </title>
716                         <para>
717                         Sends HTTP GET or POST request according to URL given in
718                         <quote>url</quote> parameter, which is a string that may
719                         contain pseudo variables.
720                         </para>
721                         <para>
722                         If you want to make a POST-Request, you have to define
723                         the <quote>post</quote>-data, that should be submitted
724                         in that request as the second parameter.
725                         </para>
726                         <para>
727                         If HTTP server returns a class 2xx, 3xx or 4xx reply,
728                         the first line of the reply's body (if any) is
729                         stored in <quote>result</quote> parameter,
730                         which must be a writable pseudo variable.
731                         </para>
732                         <para>
733                         Function returns reply code of HTTP reply or -1
734                         if something went wrong.
735                         </para>
736                         <para>
737                         This function can be used from REQUEST_ROUTE,
738                         ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
739                         </para>
740                         <para>
741                         Note that this function is based on the http_query function in the utils module.
742                         It is changed to use the same base library and settings as the rest of the functions in this module.
743                         </para>
744                         <example>
745                                 <title><function>curl_http_query()</function> usage</title>
746                                 <programlisting format="linespecific">
747 ...
748 # GET-Request
749 http_client_query("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
750            "$var(result)");
751 switch ($retcode) {
752        ...
753 }
754 ...
755                                 </programlisting>
756                                 <programlisting format="linespecific">
757 ...
758 # POST-Request
759 http_client_query("http://api.com/index.php", "r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
760            "$var(result)");
761 switch ($retcode) {
762        ...
763 }
764 ...
765                                 </programlisting>
766                         </example>
767                 </section>
768         </section>
769         <section>
770         <title>Pseudovariables</title>
771                 <section >
772                         <title>
773                                 <function moreinfo="none">$curlerror(error)</function>
774                         </title>
775                         <para>
776                         The cURL library returns error codes from the protocol used. If an error
777                         happens, a cURL specific error code below 100 is returned.
778                         The $curlerror pv returns a text string representing the error.
779                         For more information on cURL error codes, please visit
780                         http://curl.haxx.se/libcurl/c/libcurl-errors.html
781                         </para>
782                 </section>
783         </section>
784         <section>
785         <title>RPC Commands</title>
786                 <section>
787                         <title><function moreinfo="none">httpclient.listcon</function></title>
788                         <para>
789                                 Lists all defined httpcon connections
790                         </para>
791                 <para>Parameters:</para>
792                 <itemizedlist>
793                         <listitem><para>No parameters</para></listitem>
794                 </itemizedlist>
795                 </section>
796         </section>
797         <section>
798         <title>Counters</title>
799                 <section >
800                         <title>
801                                 <function moreinfo="none">httpclient.connections</function>
802                         </title>
803                         <para>
804                                 The number of connection definitions that are in-memory.
805                         </para>
806                 </section>
807                 <section >
808                         <title>
809                                 <function moreinfo="none">httpclient.connok</function>
810                         </title>
811                         <para>
812                                 The number of successful connections since &kamailio; start
813                         </para>
814                 </section>
815                 <section >
816                         <title>
817                                 <function moreinfo="none">httpclient.connfail</function>
818                         </title>
819                         <para>
820                                 The number of failed connections since &kamailio; start
821                         </para>
822                 </section>
823         </section>
824
825         <section id="http_client.s.remarks">
826                 <title>Remarks</title>
827                 <para>
828                         Note: libcurl leak in CentOS 6 - this module uses libcurl library
829                         and in case if you are using CentOS 6, be aware that standard
830                         libcurl-7.19.7-52 has a memory leak. To fix this memory, install
831                         libcurl from city-fan repository. More details at:
832                         <ulink url="https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6">
833                         https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6</ulink>
834                 </para>
835         </section>
836 </chapter>