Skip to content
Orb

DNS Override

The --connect-to option allows you to override DNS resolution and route requests to a different host or port. This is useful for testing, debugging, and local development.

Basic Usage

Section titled “Basic Usage”
Terminal window
orb --connect-to "example.com:443:localhost:8443" https://example.com

Format: HOST1:PORT1:HOST2:PORT2

This routes requests for example.com:443 to localhost:8443.

How It Works

Section titled “How It Works”
  1. Orb resolves HOST2 to get the actual IP address
  2. Connects to HOST2:PORT2 instead of HOST1:PORT1
  3. Sends the request with the original Host: HOST1 header
  4. TLS validation (if any) uses the original hostname

The request URL and Host header remain unchanged - only the network connection is rerouted.

Wildcard Matching

Section titled “Wildcard Matching”

Any Host

Section titled “Any Host”

Leave HOST1 empty to match any hostname:

Terminal window
orb --connect-to ":443:localhost:8443" https://any-domain.com

Any Port

Section titled “Any Port”

Leave PORT1 empty to match any port:

Terminal window
orb --connect-to "example.com::localhost:8443" https://example.com
orb --connect-to "example.com::localhost:8443" https://example.com:8080

Both Wildcards

Section titled “Both Wildcards”
Terminal window
orb --connect-to "::localhost:8443" https://anything.com:any-port

Multiple Rules

Section titled “Multiple Rules”

Use --connect-to multiple times for multiple rules:

Terminal window
orb \
  --connect-to "api.prod.example.com:443:localhost:3000" \
  --connect-to "auth.prod.example.com:443:localhost:3001" \
  https://api.prod.example.com

Rules are matched in order. First match wins.

Common Use Cases

Section titled “Common Use Cases”

Local Development

Section titled “Local Development”

Test production URLs against local services:

Terminal window
# Route production API to local server
orb --connect-to "api.example.com:443:localhost:8080" \
  https://api.example.com/users

Testing with Different Servers

Section titled “Testing with Different Servers”
Terminal window
# Test staging server with production URL
orb --connect-to "api.example.com:443:staging.example.com:443" \
  https://api.example.com/health

Docker Development

Section titled “Docker Development”
Terminal window
# Route to Docker container
orb --connect-to "api.example.com:443:host.docker.internal:8080" \
  https://api.example.com

Load Balancer Bypass

Section titled “Load Balancer Bypass”

Test a specific backend server:

Terminal window
# Route directly to a specific server
orb --connect-to "api.example.com:443:server-01.internal:443" \
  https://api.example.com/health

Local Mock Server

Section titled “Local Mock Server”

Test with a mock server:

Terminal window
# Route to mock server
orb --connect-to "api.example.com:443:127.0.0.1:9999" \
  -k \
  https://api.example.com/users

With Verbose Output

Section titled “With Verbose Output”

See the override in action:

Terminal window
orb -v --connect-to "example.com:443:localhost:8443" https://example.com

Output:

* Connecting to localhost:8443 (overriden from example.com:443)
* Resolving host: localhost
*   Resolved localhost to 127.0.0.1 (0ms)
...

TLS Considerations

Section titled “TLS Considerations”

When overriding HTTPS connections:

  1. Certificate validation uses the original hostname (HOST1)
  2. If the target server has a different certificate, use -k or provide the correct CA with --cacert
Terminal window
# Local server with production certificate
orb --connect-to "api.example.com:443:localhost:8443" \
  https://api.example.com


# Local server with self-signed certificate
orb --connect-to "api.example.com:443:localhost:8443" \
  -k \
  https://api.example.com


# Local server with known CA
orb --connect-to "api.example.com:443:localhost:8443" \
  --cacert local-ca.pem \
  https://api.example.com