xref: /curl/docs/libcurl/opts/CURLOPT_PROXY.md (revision 24b66a1d) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_PROXY
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPPROXYTUNNEL (3)
9  - CURLOPT_PRE_PROXY (3)
10  - CURLOPT_PROXYPORT (3)
11  - CURLOPT_PROXYTYPE (3)
12Protocol:
13  - All
14---
15
16# NAME
17
18CURLOPT_PROXY - proxy to use
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
26~~~
27
28# DESCRIPTION
29
30Set the *proxy* to use for transfers with this easy handle. The parameter
31should be a char * to a null-terminated string holding the hostname or dotted
32numerical IP address. A numerical IPv6 address must be written within
33[brackets].
34
35To specify port number in this string, append :[port] to the end of the host
36name. The proxy's port number may optionally (but discouraged) be specified
37with the separate option CURLOPT_PROXYPORT(3). If not specified, libcurl
38defaults to using port 1080 for proxies.
39
40The proxy string may be prefixed with [scheme]:// to specify which kind of
41proxy is used.
42
43## http://
44
45HTTP Proxy. Default when no scheme or proxy type is specified.
46
47## https://
48
49HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it
50also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and
51wolfSSL.)
52
53This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to
54**CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy.
55
56## socks4://
57
58SOCKS4 Proxy.
59
60## socks4a://
61
62SOCKS4a Proxy. Proxy resolves URL hostname.
63
64## socks5://
65
66SOCKS5 Proxy.
67
68## socks5h://
69
70SOCKS5 Proxy. Proxy resolves URL hostname.
71
72##
73
74Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify which
75kind of proxy the string identifies.
76
77When you tell the library to use an HTTP proxy, libcurl transparently converts
78operations to HTTP even if you specify an FTP URL etc. This may have an impact
79on what other features of the library you can use, such as CURLOPT_QUOTE(3)
80and similar FTP specifics that do not work unless you tunnel through the HTTP
81proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL(3).
82
83Setting the proxy string to "" (an empty string) explicitly disables the use
84of a proxy, even if there is an environment variable set for it.
85
86A proxy host string can also include protocol scheme (http://) and embedded
87user + password.
88
89Unix domain sockets are supported for socks proxies since 7.84.0. Set
90localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock
91
92When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*,
93cannot be used.
94
95# Environment variables
96
97libcurl respects the proxy environment variables named **http_proxy**,
98**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy
99for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is
100considered. **all_proxy** is used if no protocol specific proxy was set.
101
102If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of
103setting the CURLOPT_NOPROXY(3) option.
104
105The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment
106variables.
107
108# DEFAULT
109
110Default is NULL, meaning no proxy is used.
111
112When you set a hostname to use, do not assume that there is any particular
113single port number used widely for proxies. Specify it!
114
115# EXAMPLE
116
117~~~c
118int main(void)
119{
120  CURL *curl = curl_easy_init();
121  if(curl) {
122    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
123    curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
124    curl_easy_perform(curl);
125  }
126}
127~~~
128
129# AVAILABILITY
130
131Since 7.14.1 the proxy environment variable names can include the protocol
132scheme.
133
134Since 7.21.7 the proxy string supports the socks protocols as "schemes".
135
136Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
137error.
138
139# RETURN VALUE
140
141Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
142CURLE_OUT_OF_MEMORY if there was insufficient heap space.
143