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