mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
675 lines
20 KiB
675 lines
20 KiB
http_client
|
|
|
|
Olle E. Johansson
|
|
|
|
Edvina AB
|
|
|
|
Juha Heinanen
|
|
|
|
TutPro Inc.
|
|
|
|
Carsten Bock
|
|
|
|
ng-voice GmbH
|
|
|
|
Hugh Waite
|
|
|
|
Xura Inc
|
|
|
|
Copyright © 2008-2009 Juha Heinanen
|
|
|
|
Copyright © 2013 Carsten Bock, ng-voice GmbH
|
|
|
|
Copyright © 2015 Olle E. Johansson, Edvina AB
|
|
|
|
Copyright © 2016 Hugh Waite, Xura Inc
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. httpredirect (int)
|
|
3.2. useragent (string)
|
|
3.3. maxdatasize (int)
|
|
3.4. connection_timeout (int)
|
|
3.5. client_cert (string)
|
|
3.6. client_key (string)
|
|
3.7. cacert (string)
|
|
3.8. cipher_suites (string)
|
|
3.9. verify_peer (int)
|
|
3.10. verify_host (int)
|
|
3.11. tlsversion (int)
|
|
3.12. authmethod (int)
|
|
3.13. httpcon (string)
|
|
3.14. config_file (string)
|
|
|
|
4. Functions
|
|
|
|
4.1. http_connect(connection, url, [content_type, data,]
|
|
result)
|
|
|
|
4.2. http_client_query(url, [post-data], result)
|
|
|
|
5. Pseudovariables
|
|
|
|
5.1. $curlerror(error)
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. httpclient.listcon
|
|
|
|
7. Counters
|
|
|
|
7.1. httpclient.connections
|
|
7.2. httpclient.connok
|
|
7.3. httpclient.connfail
|
|
|
|
2. Developer Guide
|
|
|
|
1. Available Functions
|
|
|
|
1.1. http_connect(msg, connection, url, result,
|
|
content_type, post)
|
|
|
|
List of Examples
|
|
|
|
1.1. Set httpredirect parameter
|
|
1.2. Set useragent parameter
|
|
1.3. Set maxdatasize parameter
|
|
1.4. Set connection_timeout parameter
|
|
1.5. Set client_cert parameter
|
|
1.6. Set client_key parameter
|
|
1.7. Set cacert parameter
|
|
1.8. Set cipher_suites parameter
|
|
1.9. Set verify_peer parameter
|
|
1.10. Set verify_host parameter
|
|
1.11. Set tlsversion parameter
|
|
1.12. Set authmethod parameter
|
|
1.13. Set httpcon parameter
|
|
1.14. Set config_file parameter
|
|
1.15. Short http_client config file
|
|
1.16. http_connect() usage
|
|
1.17. curl_http_query() usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. httpredirect (int)
|
|
3.2. useragent (string)
|
|
3.3. maxdatasize (int)
|
|
3.4. connection_timeout (int)
|
|
3.5. client_cert (string)
|
|
3.6. client_key (string)
|
|
3.7. cacert (string)
|
|
3.8. cipher_suites (string)
|
|
3.9. verify_peer (int)
|
|
3.10. verify_host (int)
|
|
3.11. tlsversion (int)
|
|
3.12. authmethod (int)
|
|
3.13. httpcon (string)
|
|
3.14. config_file (string)
|
|
|
|
4. Functions
|
|
|
|
4.1. http_connect(connection, url, [content_type, data,] result)
|
|
4.2. http_client_query(url, [post-data], result)
|
|
|
|
5. Pseudovariables
|
|
|
|
5.1. $curlerror(error)
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. httpclient.listcon
|
|
|
|
7. Counters
|
|
|
|
7.1. httpclient.connections
|
|
7.2. httpclient.connok
|
|
7.3. httpclient.connfail
|
|
|
|
1. Overview
|
|
|
|
This module implements protocol functions that use the libcurl library
|
|
to fetch data from external HTTP servers or post data to HTTP servers.
|
|
The module is using a concept of "connections" to define properties of
|
|
HTTP sessions in a simple way.
|
|
|
|
The http_client module has multiple settings, some of them applies to a
|
|
defined connection. You can set timeouts, max data sizes for download
|
|
and much more either using modparam settings or parameters to the
|
|
connection definition.
|
|
|
|
The connections can either be defined with the "httpcon" module
|
|
parameter or in a separate configuration file, as specified by the
|
|
"config_file" module parameter.
|
|
|
|
Like in SIP, the HTTP URL may need encoding to be transported safely
|
|
over the network. Check the string encoding functions in the
|
|
Transformation Cookbook (as used in the http_client_query example
|
|
below).
|
|
|
|
Function http_client_query allows Kamailio to issue an HTTP GET request
|
|
and get access to parts of the reply. This function has been ported
|
|
from the utils module and now use the same libcurl functions.
|
|
|
|
The http_client module use the CURL library setting up connections. The
|
|
CURL library by default use the system configured DNS resolvers, not
|
|
the Kamailio resolver.
|
|
|
|
The module is limited to using HTTP and HTTPS protocols.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* TLS - if you use TLS connections (https) the tls module should be
|
|
loaded first in order to initialize OpenSSL properly.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libcurl.
|
|
|
|
3. Parameters
|
|
|
|
3.1. httpredirect (int)
|
|
3.2. useragent (string)
|
|
3.3. maxdatasize (int)
|
|
3.4. connection_timeout (int)
|
|
3.5. client_cert (string)
|
|
3.6. client_key (string)
|
|
3.7. cacert (string)
|
|
3.8. cipher_suites (string)
|
|
3.9. verify_peer (int)
|
|
3.10. verify_host (int)
|
|
3.11. tlsversion (int)
|
|
3.12. authmethod (int)
|
|
3.13. httpcon (string)
|
|
3.14. config_file (string)
|
|
|
|
3.1. httpredirect (int)
|
|
|
|
If set to 1, enabled, http_client will follow HTTP 302 Redirects. If
|
|
set to 0, http_client will not follow redirects. Default is 1, enabled.
|
|
|
|
Example 1.1. Set httpredirect parameter
|
|
...
|
|
modparam("http_client", "httpredirect", 0)
|
|
...
|
|
|
|
3.2. useragent (string)
|
|
|
|
Useragent to use in the HTTP protocol for requests. Defaults to the
|
|
Kamailio SIP useragent string - including software version and
|
|
platform.
|
|
|
|
Example 1.2. Set useragent parameter
|
|
...
|
|
modparam("http_client", "useragent", "Secret HTTP REST grabber 0.42")
|
|
...
|
|
|
|
3.3. maxdatasize (int)
|
|
|
|
Defines the maximum size in bytes for a response. Note that this is
|
|
allocated from pkg memory (process memory) dynamically.
|
|
|
|
Default value is zero, i.e., the limit on the datasize is disabled.
|
|
|
|
Example 1.3. Set maxdatasize parameter
|
|
...
|
|
modparam("http_client", "maxdatasize", 2000)
|
|
...
|
|
|
|
3.4. connection_timeout (int)
|
|
|
|
Defines in seconds how long Kamailio waits for response from servers.
|
|
|
|
Default value is zero, i.e., the timeout function is disabled.
|
|
|
|
Example 1.4. Set connection_timeout parameter
|
|
...
|
|
modparam("http_client", "connection_timeout", 2)
|
|
...
|
|
|
|
3.5. client_cert (string)
|
|
|
|
File name for a TLS client certificate. The certificate needs to be
|
|
encoded in PEM format.
|
|
|
|
Default value is empty string, i.e. no client certificate used. Note
|
|
that if you specify a client cert, you also need to specify the
|
|
client_key.
|
|
|
|
Example 1.5. Set client_cert parameter
|
|
...
|
|
modparam("http_client", "client_cert", "/var/certs/sollentuna.example.com.cert")
|
|
...
|
|
|
|
3.6. client_key (string)
|
|
|
|
File name for a TLS client key. The key needs to be encoded in PEM
|
|
format.
|
|
|
|
Default value is empty string, i.e. no client certificate or key is
|
|
used. Note that if you specify a client key, you also need to specify
|
|
the client_cert.
|
|
|
|
Example 1.6. Set client_key parameter
|
|
...
|
|
modparam("http_client", "client_key", "/var/certs/sollentuna.example.com.key")
|
|
...
|
|
|
|
3.7. cacert (string)
|
|
|
|
File name for the trusted TLS CA cert used to verify servers. The
|
|
certificates need to be encoded in PEM format.
|
|
|
|
Default value is empty string, i.e. no CA certificate is used to verify
|
|
the host. If tlsverifyhost is on, all TLS connections will fail without
|
|
any CA certificate to validate with.
|
|
|
|
Example 1.7. Set cacert parameter
|
|
...
|
|
modparam("http_client", "cacert", "/var/certs/ca/edvina-sip-ca.pem")
|
|
...
|
|
|
|
3.8. cipher_suites (string)
|
|
|
|
List of allowed cipher suites. See
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html for details
|
|
of the cipher list curl option.
|
|
|
|
Default value is empty string, i.e. the default list of ciphers in
|
|
libcurl will be used.
|
|
|
|
Example 1.8. Set cipher_suites parameter
|
|
...
|
|
modparam("http_client", "cipher_suites", "ecdhe_ecdsa_aes_128_gcm_sha_256,rsa_ae
|
|
s_128_gcm_sha_256")
|
|
...
|
|
|
|
3.9. verify_peer (int)
|
|
|
|
If set to 0, TLS verification of the server certificate is disabled.
|
|
This means that the connection will get encrypted, but there's no
|
|
authentication. There's no proof that the transmission of data is to
|
|
the host that is meant to receive data.
|
|
|
|
If set to 1, default setting, and one or more CA certificates is
|
|
configured, the server TLS certificate will be validated. If validation
|
|
fails, the connection fails.
|
|
|
|
See the curl documentation for more details.
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
|
|
|
|
Example 1.9. Set verify_peer parameter
|
|
...
|
|
modparam("http_client", "verify_peer", 1)
|
|
...
|
|
|
|
3.10. verify_host (int)
|
|
|
|
If set to 0, domain verification of the server certificate is disabled.
|
|
This means that the connection will get encrypted but there is no check
|
|
that data will be sent to the host that is meant to receive it. Disable
|
|
with caution.
|
|
|
|
If set to 2, default setting, the hostname in the URL will be verified
|
|
against the Common Name or Subject Alt Name in the certificate. If
|
|
validation fails, the connection fails.
|
|
|
|
See the curl documentation for more details.
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
|
|
|
|
Example 1.10. Set verify_host parameter
|
|
...
|
|
modparam("http_client", "verify_host", 2)
|
|
...
|
|
|
|
3.11. tlsversion (int)
|
|
|
|
Sets the preferred TLS/SSL version.
|
|
|
|
Valid values are:
|
|
* 0 - Use libcurl default
|
|
* 1 - "TLSv1"
|
|
* 2 - "SSLv2"
|
|
* 3 - "SSLv3"
|
|
* 4 - "TLSv1.0"
|
|
* 5 - "TLSv1.1"
|
|
* 6 - "TLSv1.2"
|
|
|
|
SSL versions are now disabled by default. See the curl documentation
|
|
for more details. http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
|
|
|
|
Example 1.11. Set tlsversion parameter
|
|
...
|
|
modparam("http_client", "tlsversion", 6)
|
|
...
|
|
|
|
3.12. authmethod (int)
|
|
|
|
Sets the preferred authentication mode for HTTP/HTTPS requests. The
|
|
value is a bitmap and multiple methods can be used. Note that in this
|
|
case, the CURL library will make an extra request to discover
|
|
server-supported authentication methods. You may want to use a specific
|
|
value.
|
|
|
|
Valid values are:
|
|
* 1 - BASIC authentication
|
|
* 2 - HTTP Digest authentication
|
|
* 4 - GSS-Negotiate authentication
|
|
* 8 - NTLM authentication
|
|
* 16 - HTTP Digest with IE flavour
|
|
|
|
Example 1.12. Set authmethod parameter
|
|
...
|
|
# Use the best of BASIC and Digest authentication.
|
|
modparam("http_client", "authmetod", 3)
|
|
...
|
|
|
|
3.13. httpcon (string)
|
|
|
|
Defines a connection and credentials for the connection for use in a
|
|
connection-oriented function call in this module.
|
|
|
|
Syntax:
|
|
<connection-name>=><schema>://[<username>:<password>@]<hostname/address
|
|
>[;param=value]
|
|
|
|
The address in the URL is the base for the URL in the http_connect()
|
|
call. The address given in the function call will be appended to the
|
|
base URL in the connection definition.
|
|
|
|
By default, no connections are defined.
|
|
|
|
Parameters
|
|
* useragent Useragent used for HTTP requests. Overrides useragent
|
|
modparam.
|
|
* verify_peer Set to 1 to enable or 0 to disable server certificate
|
|
verification. Overrides verify_peer modparam.
|
|
* verify_host Set to 2 to enable or 0 to disable server hostname
|
|
verification. Overrides verify_host modparam.
|
|
* client_cert Client certificate used for this connection. Overrides
|
|
the default client_cert modparam.
|
|
* client_key Client key used for this connection. Overrides the
|
|
default client_key modparam.
|
|
* cipher_suites Client certificate used for this connection.
|
|
Overrides the default cipher_suite modparam.
|
|
* timeout Timeout used for this connection. Overrides the default
|
|
connection_timeout for the module.
|
|
* tlsversion TLS version used for this connection. Overrides the
|
|
default tlsversion for the module.
|
|
* maxdatasize The maximum datasize for a response. Overrides the
|
|
maxdatasize modparam setting.
|
|
* httpredirect Set to 1 for following HTTP 302 redirect. 0 to
|
|
disable. Overrides the default httpredirect modparam.
|
|
|
|
Example 1.13. Set httpcon parameter
|
|
...
|
|
modparam("http_client", "httpcon", "apione=>http://atlanta.example.com")
|
|
modparam("http_client", "httpcon", "apitwo=>http://atlanta.example.com/api/12")
|
|
modparam("http_client", "httpcon", "apithree=>http://annabella:mysecret@atlanta.
|
|
example.com/api/12")
|
|
modparam("http_client", "httpcon", "apifour=>http://stockholm.example.com/api/ge
|
|
tstuff;timeout=12")
|
|
...
|
|
|
|
3.14. config_file (string)
|
|
|
|
The file name of a configuration file containing definitions of http
|
|
connections. This is an alternative to the "httpcon" module parameter -
|
|
especially when the number of options per line gets too big.
|
|
|
|
If the file or directory name starts with a '.' the path will be
|
|
relative to the working directory (at runtime). If it starts with a '/'
|
|
it will be an absolute path and if it starts with anything else the
|
|
path will be relative to the main config file directory (e.g.: for
|
|
kamailio -f /etc/kamailio/kamailio.cfg it will be relative to
|
|
/etc/kamailio/).
|
|
|
|
The following parameters can be set in the config file, for each
|
|
connection. If a parameter is not specified, the default values set by
|
|
the modparams will be used.
|
|
* url
|
|
* username
|
|
* password
|
|
* failover
|
|
* useragent
|
|
* verify_peer
|
|
* verify_host
|
|
* client_cert
|
|
* client_key
|
|
* cipher_suites
|
|
* tlsversion - Valid values are:
|
|
+ "DEFAULT"
|
|
+ "TLSv1"
|
|
+ "SSLv22
|
|
+ "SSLv3"
|
|
+ "TLSv1.0"
|
|
+ "TLSv1.1"
|
|
+ "TLSv1.2"
|
|
* timeout
|
|
* maxdatasize
|
|
* http_follow_redirect
|
|
|
|
See the "httpcon" module parameter for explanation of these settings.
|
|
|
|
By default no config file is specified.
|
|
|
|
All the parameters that take filenames as values will be resolved using
|
|
the same rules as for the tls config filename itself: starting with a
|
|
'.' means relative to the working directory, a '/' means an absolute
|
|
path and anything else a path relative to the directory of the current
|
|
Kamailio main config file.
|
|
|
|
To set a string value to null, in order to override default settings,
|
|
you can specify an value of "" - two quotation marks. In order to
|
|
disable a http proxy setting you can set the port to zero.
|
|
|
|
Example 1.14. Set config_file parameter
|
|
...
|
|
modparam("http_client", "config_file", "httpconnections.cfg)
|
|
...
|
|
|
|
Example 1.15. Short http_client config file
|
|
[authapiserver]
|
|
url = https://api.runbo.example.com/v4.2/auth
|
|
timeout = 1
|
|
maxdatasize = 4
|
|
tlsversion = TLSv1.2
|
|
verify_peer = yes
|
|
client_key = default_key.pem
|
|
client_cert = default_cert.pem
|
|
http_follow_redirect = no
|
|
|
|
4. Functions
|
|
|
|
4.1. http_connect(connection, url, [content_type, data,] result)
|
|
4.2. http_client_query(url, [post-data], result)
|
|
|
|
4.1. http_connect(connection, url, [content_type, data,] result)
|
|
|
|
Sends HTTP GET or POST request to a given connection. For a POST
|
|
request, content-type can be specified.
|
|
* connection - the name of an existing HTTP connection, definied by a
|
|
httpcon modparam.
|
|
url - the part of the URL to add to the predefined URL in the
|
|
connection definition.
|
|
content_type - Used only when posting data with HTTP POST. An
|
|
Internet Media type, like "application/json" or "text/plain". Will
|
|
be added to the HTTP request as a header.
|
|
data - Data or a pseudo variable holding data to be posted.
|
|
result - The name of a pseudo variable that will have the data of
|
|
the response from the HTTP server.
|
|
|
|
The return value is the HTTP return code (if >=100) or the CURL error
|
|
code if below 100. See the $curlerror pseudovariable below for more
|
|
information about CURL error codes.
|
|
|
|
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
|
|
FAILURE_ROUTE, and BRANCH_ROUTE.
|
|
|
|
Example 1.16. http_connect() usage
|
|
...
|
|
modparam("http_client", "httpcon", "apiserver=>http://kamailio.org/api/");
|
|
...
|
|
# POST Request
|
|
$var(res) = http_connect("apiserver", "/mailbox", "application/json", "{ ok, {20
|
|
0, ok}}", "$avp(gurka)");
|
|
xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n"
|
|
);
|
|
|
|
$var(res) = http_connect("apiserver", "/callroute", "application/json", "$var(js
|
|
ondata)", "$avp(route)");
|
|
xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n"
|
|
);
|
|
...
|
|
|
|
4.2. http_client_query(url, [post-data], result)
|
|
|
|
Sends HTTP GET or POST request according to URL given in “url”
|
|
parameter, which is a string that may contain pseudo variables.
|
|
|
|
If you want to make a POST-Request, you have to define the “post”-data,
|
|
that should be submitted in that request as the second parameter.
|
|
|
|
If HTTP server returns a class 2xx, 3xx or 4xx reply, the first line of
|
|
the reply's body (if any) is stored in “result” parameter, which must
|
|
be a writable pseudo variable.
|
|
|
|
Function returns reply code of HTTP reply or -1 if something went
|
|
wrong.
|
|
|
|
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
|
|
FAILURE_ROUTE, and BRANCH_ROUTE.
|
|
|
|
Note that this function is based on the http_query function in the
|
|
utils module. It is changed to use the same base library and settings
|
|
as the rest of the functions in this module.
|
|
|
|
Example 1.17. curl_http_query() usage
|
|
...
|
|
# GET-Request
|
|
http_client_query("http://api.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(
|
|
fu{s.escape.param})",
|
|
"$var(result)");
|
|
switch ($retcode) {
|
|
...
|
|
}
|
|
...
|
|
...
|
|
# POST-Request
|
|
http_client_query("http://api.com/index.php", "r_uri=$(ru{s.escape.param})&f_uri
|
|
=$(fu{s.escape.param})",
|
|
"$var(result)");
|
|
switch ($retcode) {
|
|
...
|
|
}
|
|
...
|
|
|
|
5. Pseudovariables
|
|
|
|
5.1. $curlerror(error)
|
|
|
|
5.1. $curlerror(error)
|
|
|
|
The cURL library returns error codes from the protocol used. If an
|
|
error happens, a cURL specific error code below 100 is returned. The
|
|
$curlerror pv returns a text string representing the error. For more
|
|
information on cURL error codes, please visit
|
|
http://curl.haxx.se/libcurl/c/libcurl-errors.html
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. httpclient.listcon
|
|
|
|
6.1. httpclient.listcon
|
|
|
|
Lists all defined httpcon connections
|
|
|
|
Parameters:
|
|
* No parameters
|
|
|
|
7. Counters
|
|
|
|
7.1. httpclient.connections
|
|
7.2. httpclient.connok
|
|
7.3. httpclient.connfail
|
|
|
|
7.1. httpclient.connections
|
|
|
|
The number of connection definitions that are in-memory.
|
|
|
|
7.2. httpclient.connok
|
|
|
|
The number of successful connections since Kamailio start
|
|
|
|
7.3. httpclient.connfail
|
|
|
|
The number of failed connections since Kamailio start
|
|
|
|
Chapter 2. Developer Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Available Functions
|
|
|
|
1.1. http_connect(msg, connection, url, result, content_type,
|
|
post)
|
|
|
|
1. Available Functions
|
|
|
|
1.1. http_connect(msg, connection, url, result, content_type, post)
|
|
|
|
1.1. http_connect(msg, connection, url, result, content_type, post)
|
|
|
|
Sends HTTP GET or POST request to a given connection.
|
|
|
|
Returns the status code of the HTTP response (if >= 100), or a curl
|
|
error code (if < 100)
|
|
|
|
Meaning of the parameters is as follows:
|
|
* struct sip_msg *msg
|
|
The current sip message structure.
|
|
* const str *connection
|
|
The name of a preset http_con connection to use for this query.
|
|
* const str *url
|
|
A string that will be appended to the base URL specified in the
|
|
connection. This parameter can be NULL, which means nothing will be
|
|
appended to the base URL.
|
|
* str *result
|
|
A pointer to a string that will contain the response body. On
|
|
success, the data is allocated in pkg memory by the http_client
|
|
module and must be freed by the caller.
|
|
* const char *content_type
|
|
A null-terminated string specifying the content type to place in a
|
|
Content-Type header. Use NULL when a message body is not required.
|
|
* const str *post
|
|
A string containing the message body to send. Use NULL when a
|
|
message body is not required.
|