1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HTTPPROXYTUNNEL
5Section: 3
6Source: libcurl
7Protocol:
8  - All
9See-also:
10  - CURLOPT_PROXY (3)
11  - CURLOPT_PROXYPORT (3)
12  - CURLOPT_PROXYTYPE (3)
13---
14
15# NAME
16
17CURLOPT_HTTPPROXYTUNNEL - tunnel through HTTP proxy
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel);
25~~~
26
27# DESCRIPTION
28
29Set the **tunnel** parameter to 1L to make libcurl tunnel all operations
30through the HTTP proxy (set with CURLOPT_PROXY(3)). There is a big
31difference between using a proxy and to tunnel through it.
32
33Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it
34to connect to a remote host on a specific port number and then the traffic is
35just passed through the proxy. Proxies tend to white-list specific port numbers
36it allows CONNECT requests to and often only port 80 and 443 are allowed.
37
38To suppress proxy CONNECT response headers from user callbacks use
39CURLOPT_SUPPRESS_CONNECT_HEADERS(3).
40
41HTTP proxies can generally only speak HTTP (for obvious reasons), which makes
42libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without
43this tunnel option set. For example, asking for an FTP URL and specifying an
44HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the
45proxy. By instead tunneling through the proxy, you avoid that conversion (that
46rarely works through the proxy anyway).
47
48# DEFAULT
49
500
51
52# EXAMPLE
53
54~~~c
55int main(void)
56{
57  CURL *curl = curl_easy_init();
58  if(curl) {
59    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
60    curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80");
61    curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L);
62    curl_easy_perform(curl);
63  }
64}
65~~~
66
67# AVAILABILITY
68
69Always
70
71# RETURN VALUE
72
73Returns CURLE_OK
74