diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/curl.1 | 13 | ||||
-rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/opts/CURLOPT_CONNECT_TO.3 | 105 | ||||
-rw-r--r-- | docs/libcurl/opts/CURLOPT_RESOLVE.3 | 4 | ||||
-rw-r--r-- | docs/libcurl/opts/Makefile.am | 6 | ||||
-rw-r--r-- | docs/libcurl/symbols-in-versions | 1 |
6 files changed, 126 insertions, 5 deletions
diff --git a/docs/curl.1 b/docs/curl.1 index 523e05df3..e7d92001a 100644 --- a/docs/curl.1 +++ b/docs/curl.1 @@ -1176,6 +1176,19 @@ effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the hostname itself. For example, local.com would match local.com, local.com:80, and www.local.com, but not www.notlocal.com. (Added in 7.19.4). +.IP "--connect-to <host:port:connect-to-host:connect-to-port>" +For a request to the given "host:port" pair, connect to +"connect-to-host:connect-to-port" instead. +This is suitable to direct the request at a specific server, e.g. at a specific +cluster node in a cluster of servers. +This option is only used to establish the network connection. It does NOT +affect the hostname/port that is used for TLS/SSL (e.g. SNI, certificate +verification) or for the application protocols. +"host" and "port" may be the empty string, meaning "any host/port". +"connect-to-host" and "connect-to-port" may also be the empty string, +meaning "use the request's original host/port". +This option can be used many times to add many connect rules. +(Added in 7.49.0). .IP "--ntlm" (HTTP) Enables NTLM authentication. The NTLM authentication method was designed by Microsoft and is used by IIS web servers. It is a proprietary diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6905a96cd..07f704b09 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -165,6 +165,8 @@ Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP .IP CURLOPT_HTTPPROXYTUNNEL Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP +.IP CURLOPT_CONNECT_TO +Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP .IP CURLOPT_SOCKS5_GSSAPI_SERVICE Socks5 GSSAPI service name. \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP .IP CURLOPT_SOCKS5_GSSAPI_NEC diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 new file mode 100644 index 000000000..d80336e24 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 @@ -0,0 +1,105 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_CONNECT_TO 3 "10 April 2016" "libcurl 7.49.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONNECT_TO \- Connect to a specific host and port instead of the URL's host and port +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO, + struct curl_slist *connect_to); +.fi +.SH DESCRIPTION +Pass a pointer to a linked list of strings with "connect to" information to +use for establishing network connections with this handle. The linked list +should be a fully valid list of \fBstruct curl_slist\fP structs properly +filled in. Use \fIcurl_slist_append(3)\fP to create the list and +\fIcurl_slist_free_all(3)\fP to clean up an entire list. + +Each single string should be written using the format +HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the +request, PORT is the port of the request, CONNECT-TO-HOST is the host name to +connect to, and CONNECT-TO-PORT is the port to connect to. + +The first string that matches the request's host and port is used. + +Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST. +A numerical IPv6 address must be written within [brackets]. + +Any of the four values may be empty. When the HOST or PORT is empty, the host +or port will always match (the request's host or port is ignored). +When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature +will be disabled for the host or port, and the request's host or port will be +used to establish the network connection. + +This option is suitable to direct the request at a specific server, e.g. at a +specific cluster node in a cluster of servers. + +The "connect to" host and port are only used to establish the network +connection. They do NOT affect the host and port that are used for TLS/SSL +(e.g. SNI, certificate verification) or for the application protocols. + +In contrast to \fICURLOPT_RESOLVE(3)\fP, the option +\fICURLOPT_CONNECT_TO(3)\fP does not pre-populate the DNS cache and therefore +it does not affect future transfers of other easy handles that have been added +to the same multi handle. + +The "connect to" host and port are ignored if they are equal to the host and +the port in the request URL, because connecting to the host and the port in +the request URL is the default behavior. + +If an HTTP proxy is used for a request having a special "connect to" host or +port, and the "connect to" host or port differs from the requests's host and +port, the HTTP proxy is automatically switched to tunnel mode for this +specific request. This is necessary because it is not possible to connect to a +specific host or port in normal (non-tunnel) mode. + +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl; +struct curl_slist *connect_to = NULL; +host = curl_slist_append(NULL, "example.com::server1.example.com:"); + +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to); + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); +} + +curl_slist_free_all(connect_to); +.fi +.SH AVAILABILITY +Added in 7.49.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_URL "(3), " CURLOPT_RESOLVE "(3), " CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3 index a4da9b5a7..3eb1e9577 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3 @@ -45,7 +45,7 @@ ADDRESS can of course be either IPv4 or IPv6 style addressing. This option effectively pre-populates the DNS cache with entries for the host+port pair so redirects and everything that operations against the HOST+PORT will instead use your provided ADDRESS. Addresses set with -\fICURL_RESOLVE\fP will not time-out from the DNS cache like ordinary entries. +\fICURLOPT_RESOLVE\fP will not time-out from the DNS cache like ordinary entries. Remove names from the DNS cache again, to stop providing these fake resolves, by including a string in the linked list that uses the format @@ -79,4 +79,4 @@ Added in 7.21.3. Removal support added in 7.42.0. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" -.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " +.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_CONNECT_TO "(3), " diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 00afc0057..c8c6657c0 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -28,7 +28,7 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \ CURLOPT_CERTINFO.3 CURLOPT_CHUNK_BGN_FUNCTION.3 CURLOPT_CHUNK_DATA.3 \ CURLOPT_CHUNK_END_FUNCTION.3 CURLOPT_CLOSESOCKETDATA.3 \ CURLOPT_CLOSESOCKETFUNCTION.3 CURLOPT_CONNECT_ONLY.3 \ - CURLOPT_CONNECTTIMEOUT.3 CURLOPT_CONNECTTIMEOUT_MS.3 \ + CURLOPT_CONNECTTIMEOUT.3 CURLOPT_CONNECTTIMEOUT_MS.3 CURLOPT_CONNECT_TO.3 \ CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 CURLOPT_CONV_FROM_UTF8_FUNCTION.3 \ CURLOPT_CONV_TO_NETWORK_FUNCTION.3 CURLOPT_COOKIE.3 \ CURLOPT_COOKIEFILE.3 CURLOPT_COOKIEJAR.3 CURLOPT_COOKIELIST.3 \ @@ -147,7 +147,7 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \ CURLOPT_CHUNK_END_FUNCTION.html CURLOPT_CLOSESOCKETDATA.html \ CURLOPT_CLOSESOCKETFUNCTION.html CURLOPT_CONNECT_ONLY.html \ CURLOPT_CONNECTTIMEOUT.html CURLOPT_CONNECTTIMEOUT_MS.html \ - CURLOPT_CONV_FROM_NETWORK_FUNCTION.html \ + CURLOPT_CONNECT_TO.html CURLOPT_CONV_FROM_NETWORK_FUNCTION.html \ CURLOPT_CONV_FROM_UTF8_FUNCTION.html \ CURLOPT_CONV_TO_NETWORK_FUNCTION.html CURLOPT_COOKIE.html \ CURLOPT_COOKIEFILE.html CURLOPT_COOKIEJAR.html CURLOPT_COOKIELIST.html \ @@ -281,7 +281,7 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \ CURLOPT_CLOSESOCKETDATA.pdf CURLOPT_CLOSESOCKETFUNCTION.pdf \ CURLOPT_CONNECT_ONLY.pdf CURLOPT_CONNECTTIMEOUT.pdf \ CURLOPT_CONNECTTIMEOUT_MS.pdf CURLOPT_CONV_FROM_NETWORK_FUNCTION.pdf \ - CURLOPT_CONV_FROM_UTF8_FUNCTION.pdf \ + CURLOPT_CONNECT_TO.pdf CURLOPT_CONV_FROM_UTF8_FUNCTION.pdf \ \ CURLOPT_CONV_TO_NETWORK_FUNCTION.pdf CURLOPT_COOKIE.pdf \ CURLOPT_COOKIEFILE.pdf CURLOPT_COOKIEJAR.pdf CURLOPT_COOKIELIST.pdf \ CURLOPT_COOKIESESSION.pdf CURLOPT_COPYPOSTFIELDS.pdf CURLOPT_CRLF.pdf \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 524d4ff62..ba144ec45 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -331,6 +331,7 @@ CURLOPT_CLOSESOCKETFUNCTION 7.21.7 CURLOPT_CONNECTTIMEOUT 7.7 CURLOPT_CONNECTTIMEOUT_MS 7.16.2 CURLOPT_CONNECT_ONLY 7.15.2 +CURLOPT_CONNECT_TO 7.49.0 CURLOPT_CONV_FROM_NETWORK_FUNCTION 7.15.4 CURLOPT_CONV_FROM_UTF8_FUNCTION 7.15.4 CURLOPT_CONV_TO_NETWORK_FUNCTION 7.15.4 |