Skip to content
Glossary

socks5h: SOCKS5 with proxy-side DNS resolution

Definition

socks5h sends the hostname to a SOCKS5 proxy for DNS resolution. See the wire difference from socks5 with a real curl capture.

socks5h tells curl to use SOCKS5 while sending the destination hostname to the proxy for DNS resolution. The trailing h means hostname. With plain socks5, curl resolves the name locally and sends an address. The difference affects DNS visibility, regional answers and whether a proxy can apply hostname policy.

Choose one resolver policy for each request and record it in diagnostics when troubleshooting.

Protocol and scheme

RFC 1928 defines the SOCKS Protocol Version 5 handshake. It allows the CONNECT request to carry an IPv4 address, an IPv6 address or a domain name. The RFC does not name the curl URL scheme socks5h. That is curl’s documented spelling for the SOCKS5 domain-name form, also available as --socks5-hostname.

Resolution location is separate from encryption. With https:// the proxy opens a TCP tunnel and the TLS session is between curl and the destination. The proxy still sees the hostname in the SOCKS request and can see timing and byte counts. It does not automatically become an anonymity service.

A wire capture on localhost

We ran curl 8.7.1 against a dependency-free local SOCKS5 listener. The listener returned a deliberate failure after recording the CONNECT request. Python 3.15.0 printed the request tuple:

$ curl -sS --max-time 3 -x socks5h://127.0.0.1:57015 http://example.invalid/
curl: (97) Can't complete SOCKS5 connection to example.invalid. (4)
exit=97
captured_socks5h_request=(5, 1, 3, 'example.invalid', 80)

$ curl -sS --max-time 3 -x socks5://127.0.0.1:57017 http://localhost/
curl: (97) Can't complete SOCKS5 connection to localhost. (4)
exit=97
captured_socks5_request=(5, 1, 4, '::1', 80)

The third tuple field is the address type. Value 3 is a domain name, so the proxy received example.invalid. Value 4 is IPv6, so curl resolved localhost first and sent ::1. The failure is expected because the test server never opened a tunnel. It does not indicate a DNS failure.

curl form Resolver SOCKS CONNECT contains Useful when
socks5:// Local curl resolver IPv4 or IPv6 address You intentionally need local DNS or have an IP already
socks5h:// Proxy-side resolver Hostname The proxy’s network should choose the DNS answer
--socks5-hostname Proxy-side resolver Hostname You prefer a long option in scripts
HTTP -x Depends on the HTTP proxy HTTP request or CONNECT target The provider exposes an HTTP proxy endpoint

Choosing it in a client

# Hostname goes to the SOCKS server
curl -x socks5h://user:pass@gateway.example:1080 https://example.com/

# Equivalent long option
curl --socks5-hostname gateway.example:1080 https://example.com/

Keep credentials out of shell history and process listings when your client provides a separate option. For curl, --proxy-user is the separate form. The curl proxy guide covers authentication and response checks, and proxy environment variables explains why one library may read ALL_PROXY while another does not.

SOCKS5 can carry more than HTTP, unlike a protocol-aware HTTP proxy. The existing SOCKS5 reference covers authentication and UDP, while HTTP CONNECT describes the equivalent tunnel operation for an HTTP proxy. If a destination behaves differently by region, compare the DNS answer and the exit address before changing headers. The sticky-session guide helps keep that comparison on one exit.

Use socks5h when the proxy should apply its own resolver policy, such as split-horizon DNS, regional routing, or access to a name resolvable only from the proxy network. Use socks5 when local resolution is intentional and sending an address gives the proxy no hostname to resolve. If the destination is already an IP literal, both forms remove the hostname lookup question, although the address type can still be IPv4 or IPv6.

To diagnose a mismatch, record the local DNS answer and compare it with the destination address observed at the proxy. Check whether the application rewrites the proxy URL, whether an environment variable wins over a command-line option, and whether IPv6 is enabled. A successful SOCKS handshake followed by a connection error is different from a proxy handshake error such as curl’s exit 97. Keep these stages separate in logs.

Frequently asked questions

Does socks5h hide DNS from my network?
It moves the lookup to the proxy, so curl does not ask your local resolver. Your network still sees the proxy connection and the proxy sees the hostname.
Is socks5h more secure than socks5?
It changes where DNS resolution happens. It does not add encryption or authenticate the proxy. Use HTTPS and verify the proxy separately.
Why did curl return error 97?
Curl could not complete the SOCKS5 connection. Check the proxy address, port, credentials and whether the proxy can resolve and reach the target.

Sources

  1. RFC 1928: SOCKS Protocol Version 5
  2. RFC 1929: Username/Password Authentication for SOCKS V5
  3. everything curl: SOCKS proxy
  4. curl man page: --socks5-hostname
  5. libcurl error codes: CURLE_PROXY (97) means proxy handshake error

All terms, A to Z