Artifactspublic-v0

curl

master
ply4 git calls204 ms289 KiB2 cachedprotocol v2
174 lines4.8 KiBRaw

NAME

CURLOPT_PROXY - proxy to use

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);

DESCRIPTION

Set the proxy to use for transfers with this easy handle. The parameter should be a char * to a null-terminated string holding the hostname or dotted numerical IP address. A numerical IPv6 address must be written within [brackets].

To specify port number in this string, append :[port] to the end of the host name. The proxy's port number may optionally (but discouraged) be specified with the separate option CURLOPT_PROXYPORT(3). If not specified, libcurl defaults to using port 1080 for proxies.

The proxy string may be prefixed with [scheme]:// to specify which kind of proxy is used.

Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again.

The application does not have to keep the string around after setting this option.

http://

HTTP Proxy. Default when no scheme or proxy type is specified.

https://

HTTPS Proxy. (with OpenSSL, GnuTLS, mbedTLS, Rustls, Schannel or wolfSSL.)

This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to CURLPROXY_HTTPS2 allows libcurl to negotiate using HTTP/2 with proxy.

Setting CURLOPT_PROXYTYPE(3) to CURLPROXY_HTTPS3 allows libcurl to negotiate using HTTP/3 with proxy. This feature is experimental and requires a build with HTTP/3 proxy support enabled.

socks4://

SOCKS4 Proxy.

socks4a://

SOCKS4a Proxy. Proxy resolves URL hostname.

socks5://

SOCKS5 Proxy.

socks5h://

SOCKS5 Proxy. Proxy resolves URL hostname.

Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify which kind of proxy the string identifies.

When you tell the library to use an HTTP proxy, libcurl transparently converts operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as CURLOPT_QUOTE(3) and similar FTP specifics that do not work unless you tunnel through the HTTP proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL(3).

Setting the proxy string to "" (an empty string) explicitly disables the use of a proxy, even if there is an environment variable set for it.

Unix domain sockets are supported for SOCKS proxies. Set localhost for the host part and append the absolute path to the domain socket. For example: socks5h://localhost/path/to/socket.sock

When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it.

When a proxy is used, the active FTP mode as set with CUROPT_FTPPORT(3), cannot be used.

Doing FTP over an HTTP proxy without CURLOPT_HTTPPROXYTUNNEL(3) set makes libcurl do HTTP with an FTP URL over the proxy. For such transfers, common FTP specific options do not work, for example CURLOPT_USE_SSL(3).

Authentication

The proxy can also be specified with its associated credentials like for ordinary URLs in the style: scheme://username:password@hostname

Alternatively, set them using CURLOPT_PROXYUSERNAME(3) and CURLOPT_PROXYPASSWORD(3).

Environment variables

libcurl respects the proxy environment variables named http_proxy, ftp_proxy, sftp_proxy etc. If set, libcurl uses the specified proxy for that URL scheme. For an ftp:// URL, the ftp_proxy is considered. all_proxy is used if no protocol specific proxy was set.

If no_proxy (or NO_PROXY) is set, it is the exact equivalent of setting the CURLOPT_NOPROXY(3) option.

The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment variables.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
    curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example:80");
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

HISTORY

Since 7.14.1 the proxy environment variable names can include the protocol scheme.

Since 7.21.7 the proxy string supports the socks protocols as "schemes".

Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return error.

Since 7.52.0, it supports HTTPS proxy for OpenSSL.

Since 7.87.0, it supports HTTPS proxy for GnuTLS, for mbedTLS, Rustls, Schannel and wolfSSL.

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

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---
17# NAME
19CURLOPT_PROXY - proxy to use
21# SYNOPSIS
23~~~c
24#include <curl/curl.h>
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
27~~~
29# DESCRIPTION
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].
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.
41The proxy string may be prefixed with `[scheme]://` to specify which kind of
42proxy is used.
44Using this option multiple times makes the last set string override the
45previous ones. Set it to NULL to disable its use again.
47The application does not have to keep the string around after setting this
48option.
50## `http://`
52HTTP Proxy. Default when no scheme or proxy type is specified.
54## `https://`
56HTTPS Proxy. (with OpenSSL, GnuTLS, mbedTLS, Rustls, Schannel or wolfSSL.)
58This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to
59**CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy.
61Setting CURLOPT_PROXYTYPE(3) to **CURLPROXY_HTTPS3** allows libcurl to
62negotiate using HTTP/3 with proxy. This feature is experimental and requires
63a build with HTTP/3 proxy support enabled.
65## socks4://
67SOCKS4 Proxy.
69## `socks4a://`
71SOCKS4a Proxy. Proxy resolves URL hostname.
73## `socks5://`
75SOCKS5 Proxy.
77## `socks5h://`
79SOCKS5 Proxy. Proxy resolves URL hostname.
81##
83Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify which
84kind of proxy the string identifies.
86When you tell the library to use an HTTP proxy, libcurl transparently converts
87operations to HTTP even if you specify an FTP URL etc. This may have an impact
88on what other features of the library you can use, such as CURLOPT_QUOTE(3)
89and similar FTP specifics that do not work unless you tunnel through the HTTP
90proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL(3).
92Setting the proxy string to "" (an empty string) explicitly disables the use
93of a proxy, even if there is an environment variable set for it.
95Unix domain sockets are supported for SOCKS proxies. Set `localhost` for the
96host part and append the absolute path to the domain socket. For example:
97`socks5h://localhost/path/to/socket.sock`
99When you set a hostname to use, do not assume that there is any particular
100single port number used widely for proxies. Specify it.
102When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*,
103cannot be used.
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).
109# Authentication
111The proxy can also be specified with its associated credentials like for
112ordinary URLs in the style: `scheme://username:password@hostname`
114Alternatively, set them using CURLOPT_PROXYUSERNAME(3) and
115CURLOPT_PROXYPASSWORD(3).
117# Environment variables
119libcurl respects the proxy environment variables named **http_proxy**,
120**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified proxy
121for that URL scheme. For an `ftp://` URL, the **ftp_proxy** is
122considered. **all_proxy** is used if no protocol specific proxy was set.
124If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of
125setting the CURLOPT_NOPROXY(3) option.
127The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override environment
128variables.
130# DEFAULT
132NULL
134# %PROTOCOLS%
136# EXAMPLE
138~~~c
139int main(void)
141 CURL *curl = curl_easy_init();
142 if(curl) {
143 CURLcode result;
144 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
145 curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example:80");
146 result = curl_easy_perform(curl);
147 curl_easy_cleanup(curl);
148 }
150~~~
152# HISTORY
154Since 7.14.1 the proxy environment variable names can include the protocol
155scheme.
157Since 7.21.7 the proxy string supports the socks protocols as "schemes".
159Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
160error.
162Since 7.52.0, it supports HTTPS proxy for OpenSSL.
164Since 7.87.0, it supports HTTPS proxy for GnuTLS, for mbedTLS, Rustls,
165Schannel and wolfSSL.
167# %AVAILABILITY%
169# RETURN VALUE
171curl_easy_setopt(3) returns a CURLcode indicating success or error.
173CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
174libcurl-errors(3).
Diagnostics4 git calls · 204 ms
CallStatusSizeTime0204 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit22 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=22
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.3 KiB179 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=178
git.response.bytes=2323
git.response.cache=MISS
git.response.duration_ms=179
git.fetch.wants=072dfd48093ea0155783b92c6211a38092beb7dc
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2323
git.pkt.payload.max=2302
git.sideband.band1.bytes=2301
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e340faeb95be76
Request
4041642c…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format