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