Commit cd8d2362 authored by Michael Kaufmann's avatar Michael Kaufmann Committed by Daniel Stenberg
Browse files

news: CURLOPT_CONNECT_TO and --connect-to 

Makes curl connect to the given host+port instead of the host+port found
in the URL.
parent f86f50f0

docs/curl.1

+13 −0
Original line number Diff line number Diff line
@@ -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

docs/libcurl/curl_easy_setopt.3

+2 −0
Original line number Diff line number Diff line
@@ -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

docs/libcurl/opts/CURLOPT_CONNECT_TO.3

0 → 100644
+105 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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), "

docs/libcurl/opts/CURLOPT_RESOLVE.3

+2 −2
Original line number Diff line number Diff line
@@ -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), "

docs/libcurl/opts/Makefile.am

+3 −3
Original line number Diff line number Diff line
@@ -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	\