How to override DNS resolution with cURL

Overriding hostname resolution for curl requests supports controlled testing of web services during migrations, incident response, and configuration changes. Traffic can be pinned to a specific backend address while URLs still use the production hostname, which helps compare new deployments with live traffic patterns. Targeted overrides also avoid side effects on browsers or other applications that rely on system-wide DNS.

By default, curl delegates hostname lookups to the operating system resolver and caches the answers internally for the lifetime of the process. When the –resolve option is supplied, curl injects a static mapping for a hostname, port, and IP address into this cache and continues to send the original hostname in the HTTP Host header and in TLS Server Name Indication (SNI). Requests therefore reach an alternate address while application-layer routing still sees the canonical hostname.

Incorrect overrides can direct requests and credentials to the wrong host, break certificate validation, or hide issues in the real DNS configuration. The examples below focus on the –resolve option in the curl command‑line client and assume a shell environment where documentation IP ranges such as 203.0.113.0/24 are safe placeholders. Careful use is important when testing endpoints that handle production secrets or user data.

1. Send a verbose HTTPS request to record the default IP address used for a hostname.

   $ curl -v https://example.com/
   *   Trying 93.184.216.34:443...
   * Connected to example.com (93.184.216.34) port 443 (#0)
   > GET / HTTP/1.1
   > Host: example.com
   ##### snipped #####

   curl logs the resolved address in the Trying and Connected to lines while preserving the original hostname in the Host header.

2. Inject a custom hostname mapping for TCP port 443 using the –resolve option.

   $ curl -v --resolve example.com:443:203.0.113.10 https://example.com/
   * Added example.com:443:203.0.113.10 to DNS cache
   *   Trying 203.0.113.10:443...
   * Connected to example.com (203.0.113.10) port 443 (#0)
   ##### snipped #####

   Sending sensitive requests with an incorrect –resolve entry can leak credentials or data to an unintended host and may mask real DNS or certificate problems.

3. Test a different service port by overriding the mapping for HTTP on port 80.

   $ curl -v --resolve example.com:80:203.0.113.20 http://example.com/
   * Added example.com:80:203.0.113.20 to DNS cache
   *   Trying 203.0.113.20:80...
   * Connected to example.com (203.0.113.20) port 80 (#0)
   ##### snipped #####

   Each –resolve entry is keyed by hostname and numeric port, so HTTPS and HTTP overrides can apply different IP addresses for the same name.

4. Provide multiple overrides for redirect chains or multi-host tests by passing several –resolve arguments.

   $ curl -v \
     --resolve example.com:443:203.0.113.10 \
     --resolve www.example.net:443:198.51.100.20 \
     https://example.com/
   * Added example.com:443:203.0.113.10 to DNS cache
   * Added www.example.net:443:198.51.100.20 to DNS cache
   ##### snipped #####

   Per-command –resolve entries behave like temporary /etc/hosts mappings limited to the current curl invocation and do not affect other processes on the system.

5. Verify the override by confirming that the verbose log shows the expected IP address in the Connected to line while the URL still contains the original hostname.

   $ curl -v --resolve example.com:443:203.0.113.10 https://example.com/
   * Added example.com:443:203.0.113.10 to DNS cache
   *   Trying 203.0.113.10:443...
   * Connected to example.com (203.0.113.10) port 443 (#0)
   ##### snipped #####

   Success signals: the log includes an Added host:port:address to DNS cache line for the hostname and shows the intended IP in the Trying and Connected to entries, while HTTP and TLS use the original hostname.