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.
614 lines
18 KiB
614 lines
18 KiB
HTTP_ASYNC_CLIENT Module
|
|
|
|
Federico Cabiddu
|
|
|
|
<federico.cabiddu@gmail.com>
|
|
|
|
Giacomo Vacca
|
|
|
|
<giacomo.vacca@gmail.com>
|
|
|
|
Camille Oudot
|
|
|
|
Orange
|
|
<camille.oudot@orange.com>
|
|
|
|
Edited by
|
|
|
|
Federico Cabiddu
|
|
|
|
<federico.cabiddu@gmail.com>
|
|
|
|
Copyright © 2016 Federico Cabiddu
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. workers (int)
|
|
3.2. connection_timeout (str)
|
|
3.3. hash_size (str)
|
|
3.4. tls_version (int)
|
|
3.5. tls_verify_host (int)
|
|
3.6. tls_verify_peer (int)
|
|
3.7. curl_verbose (int)
|
|
3.8. memory_manager (string)
|
|
3.9. tls_client_cert (int)
|
|
3.10. tls_client_key (int)
|
|
3.11. tls_ca_path (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. http_async_query(url, [post_data], route_name)
|
|
4.2. http_async_suspend(suspend)
|
|
4.3. tls_verify_host(verify)
|
|
4.4. tls_verify_peer(verify)
|
|
4.5. http_set_timeout(timeout)
|
|
4.6. http_append_header(header)
|
|
4.7. http_set_method(method)
|
|
4.8. http_set_tls_client_cert(path)
|
|
4.9. http_set_tls_client_key(path)
|
|
4.10. http_set_tls_ca_path(path)
|
|
|
|
5. Pseudo Variables
|
|
6. Statistics
|
|
|
|
6.1. requests
|
|
6.2. replies
|
|
6.3. errors
|
|
6.4. timeouts
|
|
|
|
List of Examples
|
|
|
|
1.1. Set workers parameter
|
|
1.2. Set connection_timeout parameter
|
|
1.3. Set hash_size parameter
|
|
1.4. Set tls_version parameter
|
|
1.5. Set tls_verify_host parameter
|
|
1.6. Set tls_verify_peer parameter
|
|
1.7. Set curl_verbose parameter
|
|
1.8. Set memory_manager parameter
|
|
1.9. Set tls_client_cert parameter
|
|
1.10. Set tls_client_key parameter
|
|
1.11. Set tls_ca_path parameter
|
|
1.12. http_async_query() usage
|
|
1.13. http_async_suspend() usage
|
|
1.14. tls_verify_host() usage
|
|
1.15. tls_verify_peer() usage
|
|
1.16. http_set_timeout() usage
|
|
1.17. http_append_header() usage
|
|
1.18. http_set_method() usage
|
|
1.19. http_set_tls_client_cert() usage
|
|
1.20. http_set_tls_client_key() usage
|
|
1.21. http_set_tls_ca_path() usage
|
|
1.22. $http_req(key) variable 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. workers (int)
|
|
3.2. connection_timeout (str)
|
|
3.3. hash_size (str)
|
|
3.4. tls_version (int)
|
|
3.5. tls_verify_host (int)
|
|
3.6. tls_verify_peer (int)
|
|
3.7. curl_verbose (int)
|
|
3.8. memory_manager (string)
|
|
3.9. tls_client_cert (int)
|
|
3.10. tls_client_key (int)
|
|
3.11. tls_ca_path (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. http_async_query(url, [post_data], route_name)
|
|
4.2. http_async_suspend(suspend)
|
|
4.3. tls_verify_host(verify)
|
|
4.4. tls_verify_peer(verify)
|
|
4.5. http_set_timeout(timeout)
|
|
4.6. http_append_header(header)
|
|
4.7. http_set_method(method)
|
|
4.8. http_set_tls_client_cert(path)
|
|
4.9. http_set_tls_client_key(path)
|
|
4.10. http_set_tls_ca_path(path)
|
|
|
|
5. Pseudo Variables
|
|
6. Statistics
|
|
|
|
6.1. requests
|
|
6.2. replies
|
|
6.3. errors
|
|
6.4. timeouts
|
|
|
|
1. Overview
|
|
|
|
This module performs asynchronous HTTP queries.
|
|
|
|
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:
|
|
* tm - Transaction module
|
|
* pv - Pseudo-Variables module
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libcurl libev
|
|
|
|
3. Parameters
|
|
|
|
3.1. workers (int)
|
|
3.2. connection_timeout (str)
|
|
3.3. hash_size (str)
|
|
3.4. tls_version (int)
|
|
3.5. tls_verify_host (int)
|
|
3.6. tls_verify_peer (int)
|
|
3.7. curl_verbose (int)
|
|
3.8. memory_manager (string)
|
|
3.9. tls_client_cert (int)
|
|
3.10. tls_client_key (int)
|
|
3.11. tls_ca_path (int)
|
|
|
|
3.1. workers (int)
|
|
|
|
Number of worker processes to be started to send HTTP requests and
|
|
asynchronously handle responses.
|
|
|
|
Default value is 1.
|
|
|
|
Example 1.1. Set workers parameter
|
|
...
|
|
modparam("http_async_client", "workers", 2)
|
|
...
|
|
|
|
3.2. connection_timeout (str)
|
|
|
|
Defines in milliseconds how long Kamailio waits for response from HTTP
|
|
server.
|
|
|
|
Default value is 500ms.
|
|
|
|
Example 1.2. Set connection_timeout parameter
|
|
...
|
|
modparam("http_async_client", "connection_timeout", 1000)
|
|
...
|
|
|
|
3.3. hash_size (str)
|
|
|
|
The size of the hash table internally used to keep the requests. A
|
|
larger table is much faster but consumes more memory. The hash size
|
|
must be a power of two, otherwise it will be rounded down to the
|
|
nearest power of two.
|
|
|
|
Default value is 2048.
|
|
|
|
Example 1.3. Set hash_size parameter
|
|
...
|
|
modparam("http_async_client", "hash_size", 1024)
|
|
...
|
|
|
|
3.4. tls_version (int)
|
|
|
|
For HTTPS connections, what's the preferred SSL version.
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
|
|
|
|
Default value is 0 (default SSL version).
|
|
|
|
Example 1.4. Set tls_version parameter
|
|
...
|
|
modparam("http_async_client", "tls_version", 6)
|
|
...
|
|
|
|
3.5. tls_verify_host (int)
|
|
|
|
For HTTPS connections, whether the client should verify the server
|
|
host. http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
|
|
|
|
Default value is 2 (enabled).
|
|
|
|
Example 1.5. Set tls_verify_host parameter
|
|
...
|
|
modparam("http_async_client", "tls_verify_host", 0)
|
|
...
|
|
|
|
3.6. tls_verify_peer (int)
|
|
|
|
For HTTPS connections, whether the client should verify the server
|
|
identity. http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
|
|
|
|
Default value is 1 (enabled).
|
|
|
|
Example 1.6. Set tls_verify_peer parameter
|
|
...
|
|
modparam("http_async_client", "tls_verify_peer", 0)
|
|
...
|
|
|
|
3.7. curl_verbose (int)
|
|
|
|
If defined to a non-zero value, extra informations from cURL (request
|
|
and response headers) will be included in the kamailio logs, with
|
|
LM_INFO priority.
|
|
|
|
Default value is 0 (disabled).
|
|
|
|
Example 1.7. Set curl_verbose parameter
|
|
...
|
|
modparam("http_async_client", "curl_verbose", 1)
|
|
...
|
|
|
|
3.8. memory_manager (string)
|
|
|
|
Choose the memory manager used by curl:
|
|
* shm: curl will use kamailio's SHM pool and memory manager
|
|
* sys: curl will use the system memory and memory manager (malloc,
|
|
free, ...)
|
|
|
|
Note: if this module is used in conjunction with another module using
|
|
libcurl (http_client, utils, xcap, xcap_client), it must be loaded as
|
|
first one for this parameter to have effect, otherwise curl will likely
|
|
use the system memory allocator by default. On the other hand if the
|
|
module is loaded before any other module using libcurl, all the modules
|
|
will use the memory manager specified by this parameter.
|
|
|
|
Default value "shm"
|
|
|
|
Example 1.8. Set memory_manager parameter
|
|
...
|
|
modparam("http_async_client", "memory_manager", "sys")
|
|
...
|
|
|
|
3.9. tls_client_cert (int)
|
|
|
|
For HTTPS connections, the file path of the TLS client certificate to
|
|
be used http://curl.haxx.se/libcurl/c/CURLOPT_SSLCERT.html
|
|
|
|
Default value is NULL (not used). Default type is PEM.
|
|
|
|
Example 1.9. Set tls_client_cert parameter
|
|
...
|
|
modparam("http_async_client", "tls_client_cert", "/etc/kamailio/ssl/clientcert.p
|
|
em")
|
|
...
|
|
|
|
3.10. tls_client_key (int)
|
|
|
|
For HTTPS connections, the file path of the TLS client certificate key
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_SSLKEY.html
|
|
|
|
Default value is NULL (not used).
|
|
|
|
Example 1.10. Set tls_client_key parameter
|
|
...
|
|
modparam("http_async_client", "tls_client_key", "/etc/kamailio/ssl/clientcert.ke
|
|
y")
|
|
...
|
|
|
|
3.11. tls_ca_path (int)
|
|
|
|
The path of the directory holding the CA certificates.
|
|
http://curl.haxx.se/libcurl/c/CURLOPT_CAPATH.html
|
|
|
|
Default value is NULL..
|
|
|
|
Example 1.11. Set tls_ca_path parameter
|
|
...
|
|
modparam("http_async_client", "tls_ca_path", "/etc/kamailio/ssl/ca/")
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. http_async_query(url, [post_data], route_name)
|
|
4.2. http_async_suspend(suspend)
|
|
4.3. tls_verify_host(verify)
|
|
4.4. tls_verify_peer(verify)
|
|
4.5. http_set_timeout(timeout)
|
|
4.6. http_append_header(header)
|
|
4.7. http_set_method(method)
|
|
4.8. http_set_tls_client_cert(path)
|
|
4.9. http_set_tls_client_key(path)
|
|
4.10. http_set_tls_ca_path(path)
|
|
|
|
4.1. http_async_query(url, [post_data], route_name)
|
|
|
|
Sends HTTP(S) request asyncronously to the URL given in “url”
|
|
parameter, which is a string that may contain pseudo variables.
|
|
|
|
Unless a specific HTTP method was specified using
|
|
http_async_set_method(), it defaults to a GET request, or to a POST
|
|
request if “post_data” is issued as second argument.
|
|
|
|
Parameter “post_data”, optional, which is sent as the body of the
|
|
request, may also contain pseudo variables.
|
|
|
|
Parameter “route_name” defines the route to be executed upon reception
|
|
of HTTP reply, on error or on timeout. If a transaction exists before
|
|
calling http_async_query(), it will be paused and resumed in this
|
|
route, while the routing script execution will be stopped. If executed
|
|
in a transactionless context, or if http_async_suspend_transaction() or
|
|
$http_req(suspend) are used to not suspend the transaction, the routing
|
|
script execution will continue and the query result will be available
|
|
in “route_name”.
|
|
|
|
Return value: 0 (stop script execution) on success in transaction
|
|
context, 1 (continue script execution) in transaction-less context (or
|
|
if http_async_suspend_transaction(0) or $http_req(suspend) are used),
|
|
-1 on error.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
This method is executed asynchronously. The HTTP return code, body and
|
|
error are returned in the module-specific $http_* PVs (see below). See
|
|
example on how to retrieve return values.
|
|
|
|
Example 1.12. http_async_query() usage
|
|
...
|
|
# create a transaction to be paused, and resumed in route[HTTP_REPLY]
|
|
t_newtran();
|
|
# GET
|
|
http_async_query("http://example.com/test.php?r_uri=$rU&f_uri=$fU", "HTTP_REPLY"
|
|
);
|
|
...
|
|
# POST
|
|
http_async_query("http://example.com/test.php", "{'r_uri':'$rU', 'f_uri':'$fU'}"
|
|
, "HTTP_REPLY");
|
|
...
|
|
route[HTTP_REPLY] {
|
|
if ($http_ok) {
|
|
xlog("L_INFO", "route[HTTP_REPLY]: status $http_rs\n");
|
|
xlog("L_INFO", "route[HTTP_REPLY]: body $http_rb\n");
|
|
} else {
|
|
xlog("L_INFO", "route[HTTP_REPLY]: error $http_err)\n");
|
|
}
|
|
}
|
|
...
|
|
|
|
4.2. http_async_suspend(suspend)
|
|
|
|
In a transaction context if the transaction must be suspended and
|
|
script execution stopped.
|
|
|
|
Parameter “suspend” set to "1" to suspend the transaction, "0" to not
|
|
suspend and continue with script execution. Default: 1 (transaction
|
|
suspended).
|
|
|
|
Example 1.13. http_async_suspend() usage
|
|
...
|
|
t_newtran();
|
|
http_async_suspend(0);
|
|
# the transaction won't be suspended for the next query
|
|
http_async_query("http://example.com/test.php", "HTTP_REPLY");
|
|
xlog("L_INFO", "query sent\n");
|
|
t_reply("200", "Ok");
|
|
|
|
...
|
|
|
|
4.3. tls_verify_host(verify)
|
|
|
|
For the next HTTPS connection, whether the client should verify the
|
|
server host.
|
|
|
|
Parameter “verify” set to "1" to enable the host verification, "0" to
|
|
disable. Default: the global value set as verify_host module parameter.
|
|
|
|
Example 1.14. tls_verify_host() usage
|
|
...
|
|
tls_verify_host("0");
|
|
# host verification is disabled for the next query
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
4.4. tls_verify_peer(verify)
|
|
|
|
For the next HTTPS connection, whether the client should verify the
|
|
server identity.
|
|
|
|
Parameter “verify” set to "1" to enable the identity verification, "0"
|
|
to disable. Default: the global value set as verify_peer module
|
|
parameter.
|
|
|
|
Example 1.15. tls_verify_peer() usage
|
|
...
|
|
tls_verify_peer("0");
|
|
# server identity verification is disabled for the next query
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
4.5. http_set_timeout(timeout)
|
|
|
|
For the next HTTP query, set the response timeout.
|
|
|
|
Parameter “timeout” string representing the timeout in milliseconds.
|
|
Default: the global value set as http_timeout module parameter.
|
|
|
|
Example 1.16. http_set_timeout() usage
|
|
...
|
|
http_set_timeout("200");
|
|
# the server must respond in maximum 200ms, otherwise the query will fail
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
4.6. http_append_header(header)
|
|
|
|
Set/remove/replace a header in the next HTTP query.
|
|
|
|
From libcurl's documentation:
|
|
|
|
“If you add a header that is otherwise generated and used by libcurl
|
|
internally, your added one will be used instead. If you add a header
|
|
with no content as in 'Accept:' (no data on the right side of the
|
|
colon), the internally used header will get disabled. With this option
|
|
you can add new headers, replace internal headers and remove internal
|
|
headers. To add a header with no content (nothing to the right side of
|
|
the colon), use the form 'MyHeader;' (note the ending semicolon).”
|
|
|
|
“The headers included in the linked list must not be CRLF-terminated,
|
|
because libcurl adds CRLF after each header item.”
|
|
|
|
Parameter “header” string representing the header to pass to libcurl
|
|
for the next query.
|
|
|
|
Example 1.17. http_append_header() usage
|
|
...
|
|
http_append_header("X-Sip-Call-Id: $ci");
|
|
# a new 'X-Sip-Call-Id' header will be added to the next query
|
|
http_append_header("Content-Type": application/json");
|
|
# the curl default 'application/x-www-form-urlencoded' Content-Type will be repl
|
|
aced
|
|
http_async_query("https://example.com/test.php", "{'foo': 'bar'}", "HTTP_REPLY")
|
|
;
|
|
...
|
|
|
|
4.7. http_set_method(method)
|
|
|
|
For the next HTTP query, set the method.
|
|
|
|
Parameter “method” string representing the method (verb): either "GET",
|
|
"POST", "PUT" or "DELETE" (these are the only supported methods).
|
|
(Note: if http_set_method() is not called before a query, curl will use
|
|
GET, or POST if a body is specified)
|
|
|
|
Example 1.18. http_set_method() usage
|
|
...
|
|
http_set_method("PUT");
|
|
# the next query will be a HTTP PUT request
|
|
http_async_query("https://example.com/test.php", "{'foo': 'bar'}", "HTTP_REPLY")
|
|
;
|
|
...
|
|
|
|
4.8. http_set_tls_client_cert(path)
|
|
|
|
For the next HTTPS connection, what client certificate to use.
|
|
|
|
Default: the global value set as tls_client_cert module parameter.
|
|
|
|
Example 1.19. http_set_tls_client_cert() usage
|
|
...
|
|
http_set_tls_client_cert("/etc/kamailio/ssl/cert.pem");
|
|
# Next query will use the client cert above
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
4.9. http_set_tls_client_key(path)
|
|
|
|
For the next HTTPS connection, what client certificate key to use.
|
|
|
|
Default: the global value set as tls_client_key module parameter.
|
|
|
|
Example 1.20. http_set_tls_client_key() usage
|
|
...
|
|
http_set_tls_client_key("/etc/kamailio/ssl/cert.key");
|
|
# Next query will use the client cert key above
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
4.10. http_set_tls_ca_path(path)
|
|
|
|
For the next HTTP connection, what CA certificate files to use.
|
|
|
|
Default: the global value set as tls_ca_path module parameter.
|
|
|
|
Example 1.21. http_set_tls_ca_path() usage
|
|
...
|
|
http_set_tls_client_key("/etc/kamailio/ssl/ca/");
|
|
# Next query will use the CA certs above
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
5. Pseudo Variables
|
|
|
|
The $http_req(key) write-only variable can be used to set custom
|
|
parameters before sending a HTTP query
|
|
|
|
setting this variable has the same effect than using the
|
|
http_set_*()functions
|
|
|
|
key can be one of:
|
|
* all: if set to $null, resets all the parameters to their default
|
|
value (the ones defined in modparam)
|
|
* hdr: sets/modifies/remove a HTTP header (see http_append_header()).
|
|
N.B.: setting this variable multiple times will add several headers
|
|
to the query.
|
|
* method: sets the HTTP method (see http_set_method())
|
|
* timeout: sets the HTTP timeout (see http_set_timeout())
|
|
* tls_client_cert: sets the client certificate to use (see
|
|
http_set_tls_client_cert())
|
|
* tls_client_key: sets the client certificate key to use (see
|
|
http_set_tls_client_key())
|
|
* tls_ca_path: sets the CA certificate files to use (see
|
|
http_set_tls_ca_path())
|
|
* suspend: if set to 0 doesn't suspend the current transaction before
|
|
performing the query (see http_async_suspend())
|
|
|
|
Example 1.22. $http_req(key) variable usage
|
|
...
|
|
$http_req(all) = $null; # reset the parameters
|
|
$http_req(timeout) = 100; # 100 ms
|
|
$http_req(method) = "DELETE";
|
|
$http_req(hdr) = "X-Sip-Call-Id: " + $ci;
|
|
$http_req(hdr) = "X-Foo: bar"; # add a 2nd header
|
|
$http_req(suspend) = 0; # don't suspend the transaction, continue ro
|
|
uting script's execution
|
|
# the following request will use the above parameters
|
|
http_async_query("https://example.com/test.php", "HTTP_REPLY");
|
|
...
|
|
|
|
The following read-only pseudo variables can only be used in the
|
|
callback routes executed by http_async_query()
|
|
* $http_ok: 1 if cURL executed the request successfully, 0 otherwise
|
|
(check $http_err for details)
|
|
* $http_err: cURL error string if an error occured, $null otherwise
|
|
* $http_rs: http status
|
|
* $http_rr: http reason phrase
|
|
* $http_hdr(Name): value of the Name header (the $(http_hdr(Name)[N])
|
|
syntax can also be used, check the SIP $hdr() PV documentation for
|
|
details)
|
|
* $http_mb and $http_ml: HTTP response buffer (including headers) and
|
|
length
|
|
* $http_rb and $http_bs: HTTP response body and body length
|
|
|
|
6. Statistics
|
|
|
|
6.1. requests
|
|
6.2. replies
|
|
6.3. errors
|
|
6.4. timeouts
|
|
|
|
6.1. requests
|
|
|
|
The number of http requests sent.
|
|
|
|
6.2. replies
|
|
|
|
The number of received http replies.
|
|
|
|
6.3. errors
|
|
|
|
The number of errors.
|
|
|
|
6.4. timeouts
|
|
|
|
The number of timed out requests.
|