How to override DNS resolution with cURL

Overriding DNS resolution in cURL is useful when a hostname must stay unchanged while a single request is steered to a different backend. That makes it practical for canary checks, reverse-proxy validation, blue/green cutovers, or incident triage without editing /etc/hosts or affecting any other application on the workstation.

The --resolve option inserts a host:port:address mapping directly into curl's in-memory DNS cache for the current command. curl connects to the supplied address, but it still uses the hostname from the URL for the HTTP Host header and, on HTTPS, for SNI and certificate validation.

Mappings are exact-match on both hostname and port, so api.example.test:18080 and api.example.test:18443 need separate entries even when they point at the same address. Redirect chains or companion endpoints may need multiple mappings in one command, and HTTPS testing still requires a certificate that matches the URL hostname or a trusted internal CA bundle. The published hostnames and response bodies below stay masked while preserving a realistic service-check shape.

1. Request the test listener through the production-style hostname by adding one --resolve mapping.

   $ curl --silent --show-error --resolve api.example.test:18080:127.0.0.1 http://api.example.test:18080/
   service=orders-api environment=blue-canary port=18080

   Replace api.example.test, 18080, and 127.0.0.1 with the real hostname, port, and target address for the environment being validated.

2. Inspect the verbose transcript to confirm that curl used the injected DNS entry and kept the URL host in the request.

   $ curl --verbose --silent --show-error --resolve api.example.test:18080:127.0.0.1 http://api.example.test:18080/ --output /dev/null 2>&1 | grep -E '^\* Added|^\*   Trying|^> Host:'
   * Added api.example.test:18080:127.0.0.1 to DNS cache
   *   Trying 127.0.0.1:18080...
   > Host: api.example.test:18080

   Success is visible when the Trying line shows the override address and the Host line still shows the intended hostname.

3. Add a separate override for every additional port that the same hostname uses.

   $ curl --verbose --silent --show-error --resolve api.example.test:18443:127.0.0.1 http://api.example.test:18443/ --output /dev/null
   * Added api.example.test:18443:127.0.0.1 to DNS cache
   * Hostname api.example.test was found in DNS cache
   *   Trying 127.0.0.1:18443...
   * Connected to api.example.test (127.0.0.1) port 18443

   An entry for :18080 does not apply to :18443 or :443. For HTTPS, the same exact-match rule applies and the server certificate must still match the hostname in the URL.

4. Load every hostname that participates in the request path when redirects or companion services are involved.

   $ curl --verbose --silent --show-error \
     --resolve api.example.test:18080:127.0.0.1 \
     --resolve auth.example.test:18080:127.0.0.1 \
     http://api.example.test:18080/ --output /dev/null
   * Added api.example.test:18080:127.0.0.1 to DNS cache
   * Added auth.example.test:18080:127.0.0.1 to DNS cache
   * Hostname api.example.test was found in DNS cache
   *   Trying 127.0.0.1:18080...
   * Connected to api.example.test (127.0.0.1) port 18080

   Repeated --resolve options stay scoped to the current invocation, so the extra mappings disappear as soon as the command exits.

5. Verify the final network destination with remote_ip before relying on the override in scripts or incident runbooks.

   $ curl --silent --show-error --resolve api.example.test:18080:127.0.0.1 --write-out 'remote_ip=%{remote_ip}\n' http://api.example.test:18080/ --output /dev/null
   remote_ip=127.0.0.1

   Use remote_ip as the decisive success check when automation needs to prove that the request reached the overridden address instead of the resolver's default answer.