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