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