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 72Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify 73which kind of proxy the string identifies. 74 75When you tell the library to use an HTTP proxy, libcurl transparently converts 76operations to HTTP even if you specify an FTP URL etc. This may have an impact 77on what other features of the library you can use, such as 78CURLOPT_QUOTE(3) and similar FTP specifics that do not work unless you 79tunnel through the HTTP proxy. Such tunneling is activated with 80CURLOPT_HTTPPROXYTUNNEL(3). 81 82Setting the proxy string to "" (an empty string) explicitly disables the use 83of a proxy, even if there is an environment variable set for it. 84 85A proxy host string can also include protocol scheme (http://) and embedded 86user + password. 87 88Unix domain sockets are supported for socks proxies since 7.84.0. Set 89localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock 90 91The application does not have to keep the string around after setting this 92option. 93 94When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*, 95cannot be used. 96 97# Environment variables 98 99libcurl respects the proxy environment variables named **http_proxy**, 100**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy 101for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is 102considered. **all_proxy** is used if no protocol specific proxy was set. 103 104If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of 105setting the CURLOPT_NOPROXY(3) option. 106 107The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment 108variables. 109 110# DEFAULT 111 112Default is NULL, meaning no proxy is used. 113 114When you set a hostname to use, do not assume that there is any particular 115single port number used widely for proxies. Specify it! 116 117# EXAMPLE 118 119~~~c 120int main(void) 121{ 122 CURL *curl = curl_easy_init(); 123 if(curl) { 124 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); 125 curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); 126 curl_easy_perform(curl); 127 } 128} 129~~~ 130 131# AVAILABILITY 132 133Since 7.14.1 the proxy environment variable names can include the protocol 134scheme. 135 136Since 7.21.7 the proxy string supports the socks protocols as "schemes". 137 138Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return 139error. 140 141# RETURN VALUE 142 143Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or 144CURLE_OUT_OF_MEMORY if there was insufficient heap space. 145
