diff --git a/modules/http_async_client/README b/modules/http_async_client/README index f5b9a6a799a..664c73a690d 100644 --- a/modules/http_async_client/README +++ b/modules/http_async_client/README @@ -37,27 +37,27 @@ Federico Cabiddu 3.1. workers (int) 3.2. connection_timeout (str) 3.3. hash_size (str) - 3.4. tlsversion (int) - 3.5. tlsverifyhost (int) - 3.6. tlsverifypeer (int) + 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. tlsclientcert (int) - 3.10. tlsclientkey (int) - 3.11. tlscapath (int) + 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. http_verify_host(verify) - 4.4. http_verify_peer(verify) + 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_ssl_cert(path) - 4.9. http_set_ssl_key(path) - 4.10. http_set_ca_path(path) + 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 @@ -72,24 +72,25 @@ Federico Cabiddu 1.1. Set workers parameter 1.2. Set connection_timeout parameter 1.3. Set hash_size parameter - 1.4. Set tlsversion parameter - 1.5. Set tlsverifyhost parameter - 1.6. Set tlsverifypeer 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 tlsclientcert parameter - 1.10. Set tlsclientkey parameter - 1.11. Set tlscapath 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. http_verify_host() usage - 1.15. http_verify_peer() 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_ssl_cert() usage - 1.20. http_set_ssl_key() usage - 1.21. http_set_ca_path() 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 @@ -106,27 +107,27 @@ Chapter 1. Admin Guide 3.1. workers (int) 3.2. connection_timeout (str) 3.3. hash_size (str) - 3.4. tlsversion (int) - 3.5. tlsverifyhost (int) - 3.6. tlsverifypeer (int) + 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. tlsclientcert (int) - 3.10. tlsclientkey (int) - 3.11. tlscapath (int) + 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. http_verify_host(verify) - 4.4. http_verify_peer(verify) + 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_ssl_cert(path) - 4.9. http_set_ssl_key(path) - 4.10. http_set_ca_path(path) + 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 @@ -162,14 +163,14 @@ Chapter 1. Admin Guide 3.1. workers (int) 3.2. connection_timeout (str) 3.3. hash_size (str) - 3.4. tlsversion (int) - 3.5. tlsverifyhost (int) - 3.6. tlsverifypeer (int) + 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. tlsclientcert (int) - 3.10. tlsclientkey (int) - 3.11. tlscapath (int) + 3.9. tls_client_cert (int) + 3.10. tls_client_key (int) + 3.11. tls_ca_path (int) 3.1. workers (int) @@ -180,7 +181,7 @@ Chapter 1. Admin Guide Example 1.1. Set workers parameter ... -modparam("async_http", "workers", 2) +modparam("http_async_client", "workers", 2) ... 3.2. connection_timeout (str) @@ -192,7 +193,7 @@ modparam("async_http", "workers", 2) Example 1.2. Set connection_timeout parameter ... -modparam("async_http", "connection_timeout", 1000) +modparam("http_async_client", "connection_timeout", 1000) ... 3.3. hash_size (str) @@ -206,43 +207,43 @@ modparam("async_http", "connection_timeout", 1000) Example 1.3. Set hash_size parameter ... -modparam("async_http", "hash_size", 1024) +modparam("http_async_client", "hash_size", 1024) ... -3.4. tlsversion (int) +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 tlsversion parameter + Example 1.4. Set tls_version parameter ... -modparam("async_http", "tlsversion", 6) +modparam("http_async_client", "tls_version", 6) ... -3.5. tlsverifyhost (int) +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 tlsverifyhost parameter + Example 1.5. Set tls_verify_host parameter ... -modparam("async_http", "tlsverifyhost", 0) +modparam("http_async_client", "tls_verify_host", 0) ... -3.6. tlsverifypeer (int) +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 tlsverifypeer parameter + Example 1.6. Set tls_verify_peer parameter ... -modparam("async_http", "tlsverifypeer", 0) +modparam("http_async_client", "tls_verify_peer", 0) ... 3.7. curl_verbose (int) @@ -255,7 +256,7 @@ modparam("async_http", "tlsverifypeer", 0) Example 1.7. Set curl_verbose parameter ... -modparam("async_http", "curl_verbose", 1) +modparam("http_async_client", "curl_verbose", 1) ... 3.8. memory_manager (string) @@ -273,57 +274,59 @@ modparam("async_http", "curl_verbose", 1) Example 1.8. Set memory_manager parameter ... -modparam("async_http", "memory_manager", "sys") +modparam("http_async_client", "memory_manager", "sys") ... -3.9. tlsclientcert (int) +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 tlsclientcert parameter + Example 1.9. Set tls_client_cert parameter ... -modparam("async_http", "tlsclientcert", "/etc/kamailio/ssl/clientcert.pem") +modparam("http_async_client", "tls_client_cert", "/etc/kamailio/ssl/clientcert.p +em") ... -3.10. tlsclientkey (int) +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 tlsclientkey parameter + Example 1.10. Set tls_client_key parameter ... -modparam("async_http", "tlsclientkey", "/etc/kamailio/ssl/clientcert.key") +modparam("http_async_client", "tls_client_key", "/etc/kamailio/ssl/clientcert.ke +y") ... -3.11. tlscapath (int) +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 tlscapath parameter + Example 1.11. Set tls_ca_path parameter ... -modparam("async_http", "tlscapath", "/etc/kamailio/ssl/ca/") +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. http_verify_host(verify) - 4.4. http_verify_peer(verify) + 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_ssl_cert(path) - 4.9. http_set_ssl_key(path) - 4.10. http_set_ca_path(path) + 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) @@ -372,7 +375,7 @@ route[HTTP_REPLY] { 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_error)\n"); + xlog("L_INFO", "route[HTTP_REPLY]: error $http_err)\n"); } } ... @@ -397,7 +400,7 @@ t_reply("200", "Ok"); ... -4.3. http_verify_host(verify) +4.3. tls_verify_host(verify) For the next HTTPS connection, whether the client should verify the server host. @@ -405,14 +408,14 @@ t_reply("200", "Ok"); 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. http_verify_host() usage + Example 1.14. tls_verify_host() usage ... -http_verify_host("0"); +tls_verify_host("0"); # host verification is disabled for the next query http_query("https://example.com/test.php", "HTTP_REPLY"); ... -4.4. http_verify_peer(verify) +4.4. tls_verify_peer(verify) For the next HTTPS connection, whether the client should verify the server identity. @@ -421,9 +424,9 @@ http_query("https://example.com/test.php", "HTTP_REPLY"); to disable. Default: the global value set as verify_peer module parameter. - Example 1.15. http_verify_peer() usage + Example 1.15. tls_verify_peer() usage ... -http_verify_peer("0"); +tls_verify_peer("0"); # server identity verification is disabled for the next query http_query("https://example.com/test.php", "HTTP_REPLY"); ... @@ -488,49 +491,81 @@ http_set_method("PUT"); http_query("https://example.com/test.php", "{'foo': 'bar'}", "HTTP_REPLY"); ... -4.8. http_set_ssl_cert(path) +4.8. http_set_tls_client_cert(path) For the next HTTPS connection, what client certificate to use. - Default: the global value set as ssl_cert module parameter. + Default: the global value set as tls_client_cert module parameter. - Example 1.19. http_set_ssl_cert() usage + Example 1.19. http_set_tls_client_cert() usage ... -http_set_ssl_cert("/etc/kamailio/ssl/cert.pem"); +http_set_tls_client_cert("/etc/kamailio/ssl/cert.pem"); # Next query will use the client cert above http_query("https://example.com/test.php", "HTTP_REPLY"); ... -4.9. http_set_ssl_key(path) +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 ssl_key module parameter. + Default: the global value set as tls_client_key module parameter. - Example 1.20. http_set_ssl_key() usage + Example 1.20. http_set_tls_client_key() usage ... -http_set_ssl_key("/etc/kamailio/ssl/cert.key"); +http_set_tls_client_key("/etc/kamailio/ssl/cert.key"); # Next query will use the client cert key above http_query("https://example.com/test.php", "HTTP_REPLY"); ... -4.10. http_set_ca_path(path) +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 ca_path module parameter. + Default: the global value set as tls_ca_path module parameter. - Example 1.21. http_set_ca_path() usage + Example 1.21. http_set_tls_ca_path() usage ... -http_set_ssl_key("/etc/kamailio/ssl/ca/"); +http_set_tls_client_key("/etc/kamailio/ssl/ca/"); # Next query will use the CA certs above http_query("https://example.com/test.php", "HTTP_REPLY"); ... 5. Pseudo Variables - The following pseudo variables can only be used in the callback routes - executed by http_async_query() + 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()) + + 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 +# the following request will use the above parameters +http_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 $ah_err for details) * $http_err: cURL error string if an error occured, $null otherwise