aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/curl.113
-rw-r--r--docs/libcurl/curl_easy_setopt.32
-rw-r--r--docs/libcurl/opts/CURLOPT_CONNECT_TO.3105
-rw-r--r--docs/libcurl/opts/CURLOPT_RESOLVE.34
-rw-r--r--docs/libcurl/opts/Makefile.am6
-rw-r--r--docs/libcurl/symbols-in-versions1
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
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-02 22:37:37 +0000