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 105Doing FTP over an HTTP proxy without CURLOPT_HTTPPROXYTUNNEL(3) set makes 106libcurl do HTTP with an FTP URL over the proxy. For such transfers, common FTP 107specific options do not work, for example CURLOPT_USE_SSL(3). 108 109# Environment variables 110 111libcurl respects the proxy environment variables named **http_proxy**, 112**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy 113for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is 114considered. **all_proxy** is used if no protocol specific proxy was set. 115 116If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of 117setting the CURLOPT_NOPROXY(3) option. 118 119The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment 120variables. 121 122# DEFAULT 123 124NULL 125 126# %PROTOCOLS% 127 128# EXAMPLE 129 130~~~c 131int main(void) 132{ 133 CURL *curl = curl_easy_init(); 134 if(curl) { 135 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); 136 curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); 137 curl_easy_perform(curl); 138 } 139} 140~~~ 141 142# HISTORY 143 144Since 7.14.1 the proxy environment variable names can include the protocol 145scheme. 146 147Since 7.21.7 the proxy string supports the socks protocols as "schemes". 148 149Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return 150error. 151 152# %AVAILABILITY% 153 154# RETURN VALUE 155 156Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or 157CURLE_OUT_OF_MEMORY if there was insufficient heap space. 158
