1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_CONNECT_TO 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_FOLLOWLOCATION (3) 9 - CURLOPT_HTTPPROXYTUNNEL (3) 10 - CURLOPT_RESOLVE (3) 11 - CURLOPT_URL (3) 12Protocol: 13 - All 14--- 15 16# NAME 17 18CURLOPT_CONNECT_TO - connect to another host and port instead 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO, 26 struct curl_slist *connect_to); 27~~~ 28 29# DESCRIPTION 30 31Pass a pointer to a linked list of strings with "connect to" information to 32use for establishing network connections with this handle. The linked list 33should be a fully valid list of **struct curl_slist** structs properly filled 34in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to 35clean up an entire list. 36 37Each single string should be written using the format 38HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the 39request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to 40connect to, and CONNECT-TO-PORT is the port to connect to. 41 42The first string that matches the request's host and port is used. 43 44Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST. 45A numerical IPv6 address must be written within [brackets]. 46 47Any of the four values may be empty. When the HOST or PORT is empty, the host 48or port always match (the request's host or port is ignored). When 49CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is 50disabled for the host or port, and the request's host or port are used to 51establish the network connection. 52 53This option is suitable to direct the request at a specific server, e.g. at a 54specific cluster node in a cluster of servers. 55 56The "connect to" host and port are only used to establish the network 57connection. They do NOT affect the host and port that are used for TLS/SSL 58(e.g. SNI, certificate verification) or for the application protocols. 59 60In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not 61pre-populate the DNS cache and therefore it does not affect future transfers 62of other easy handles that have been added to the same multi handle. 63 64The "connect to" host and port are ignored if they are equal to the host and 65the port in the request URL, because connecting to the host and the port in 66the request URL is the default behavior. 67 68If an HTTP proxy is used for a request having a special "connect to" host or 69port, and the "connect to" host or port differs from the request's host and 70port, the HTTP proxy is automatically switched to tunnel mode for this 71specific request. This is necessary because it is not possible to connect to a 72specific host or port in normal (non-tunnel) mode. 73 74When this option is passed to curl_easy_setopt(3), libcurl does not copy the 75list so you **must** keep it around until you no longer use this *handle* for 76a transfer before you call curl_slist_free_all(3) on the list. 77 78# DEFAULT 79 80NULL 81 82# EXAMPLE 83 84~~~c 85int main(void) 86{ 87 CURL *curl; 88 struct curl_slist *connect_to = NULL; 89 connect_to = curl_slist_append(NULL, "example.com::server1.example.com:"); 90 91 curl = curl_easy_init(); 92 if(curl) { 93 curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to); 94 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 95 96 curl_easy_perform(curl); 97 98 /* always cleanup */ 99 curl_easy_cleanup(curl); 100 } 101 102 curl_slist_free_all(connect_to); 103} 104~~~ 105 106# AVAILABILITY 107 108Added in 7.49.0 109 110# RETURN VALUE 111 112Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 113