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 93Unix domain sockets are supported for socks proxies since 7.84.0. Set 94localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock 95 96When you set a hostname to use, do not assume that there is any particular 97single port number used widely for proxies. Specify it. 98 99When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*, 100cannot be used. 101 102Doing FTP over an HTTP proxy without CURLOPT_HTTPPROXYTUNNEL(3) set makes 103libcurl do HTTP with an FTP URL over the proxy. For such transfers, common FTP 104specific options do not work, for example CURLOPT_USE_SSL(3). 105 106# Authentication 107 108The proxy can also be specified with its associated credentials like for 109ordinary URLs in the style: `scheme://username:password@hostname` 110 111Alternatively, set them using CURLOPT_PROXYUSERNAME(3) and 112CURLOPT_PROXYPASSWORD(3). 113 114# Environment variables 115 116libcurl respects the proxy environment variables named **http_proxy**, 117**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy 118for that URL scheme. For an "FTP://" URL, the **ftp_proxy** is 119considered. **all_proxy** is used if no protocol specific proxy was set. 120 121If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of 122setting the CURLOPT_NOPROXY(3) option. 123 124The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment 125variables. 126 127# DEFAULT 128 129NULL 130 131# %PROTOCOLS% 132 133# EXAMPLE 134 135~~~c 136int main(void) 137{ 138 CURL *curl = curl_easy_init(); 139 if(curl) { 140 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); 141 curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); 142 curl_easy_perform(curl); 143 } 144} 145~~~ 146 147# HISTORY 148 149Since 7.14.1 the proxy environment variable names can include the protocol 150scheme. 151 152Since 7.21.7 the proxy string supports the socks protocols as "schemes". 153 154Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return 155error. 156 157# %AVAILABILITY% 158 159# RETURN VALUE 160 161curl_easy_setopt(3) returns a CURLcode indicating success or error. 162 163CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 164libcurl-errors(3). 165