.\" generated by cd2nroff 0.1 from CURLOPT_CONNECT_TO.md
.TH CURLOPT_CONNECT_TO 3 "2024-11-18" libcurl
.SH NAME
CURLOPT_CONNECT_TO \- connect to another host and port instead
.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 hostname to
connect to, and CONNECT\-TO\-PORT is the port to connect to.

The first string that matches the request\(aqs 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 always match (the request\(aqs host or port is ignored). When
CONNECT\-TO\-HOST or CONNECT\-TO\-PORT is empty, the "connect to" feature is
disabled for the host or port, and the request\(aqs host or port are 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 request\(aqs 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.

When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the
list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for
a transfer before you call \fIcurl_slist_free_all(3)\fP on the list.
.SH DEFAULT
NULL
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl;
  struct curl_slist *connect_to = NULL;
  connect_to = 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, "https://example.com");

    curl_easy_perform(curl);

    /* always cleanup */
    curl_easy_cleanup(curl);
  }

  curl_slist_free_all(connect_to);
}
.fi
.SH AVAILABILITY
Added in curl 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_FOLLOWLOCATION (3),
.BR CURLOPT_HTTPPROXYTUNNEL (3),
.BR CURLOPT_RESOLVE (3),
.BR CURLOPT_URL (3)