Hostname Resolution (hosts.txt)¶

Problem: Internal hostnames don't resolve via DNS, or you need to redirect production hostnames to test servers during load testing without modifying your system's /etc/hosts file (which only affects the controller, not remote engines).

Two different features share the name 'Hostname Resolution'

This page covers hosts.txt, which maps a hostname to a specific IP address (a DNS override), and is distributed to remote engines. That is different from the Hostname Resolution preference (Window → Preferences → Hostname Resolution), which rewrites one hostname to another and is covered under URLs & Hostnames. Use hosts.txt when you need to control which IP a hostname connects to; use the preference when you need to swap one hostname for another.

When You Need Custom DNS Overrides¶

You'll know you need hostname resolution configuration if:

Test environment uses internal hostnames (e.g., app.internal.corp) that don't resolve publicly
Production load test must target staging servers (e.g., www.example.com → 10.1.1.5 instead of the live production IP)
Load balancer requires specific IP addresses that differ from public DNS
Remote engines can't resolve hostnames correctly (modifying /etc/hosts on every engine is impractical)

Common scenarios:

Testing pre-production environments with internal DNS
Bypassing CDNs to test origin servers directly
Routing traffic to specific data center IPs for geographic load testing
Working around DNS propagation delays during infrastructure changes

Why Use hosts.txt Instead of System Hosts File¶

System hosts file (/etc/hosts on Linux/macOS, C:\Windows\System32\drivers\etc\hosts on Windows):

❌ Only affects the local machine: you must edit every remote engine's hosts file manually
❌ Requires admin/root privileges to modify
❌ Conflicts with other applications using the same hostnames

Load Tester's hosts.txt:

✅ Automatically distributed to remote engines: configure once, applies everywhere
✅ No admin privileges required (stored in Load Tester's workspace)
✅ Test-specific: doesn't interfere with other applications

hosts.txt File Format¶

The format is identical to the standard /etc/hosts file format. Each line maps an IP address to a hostname (with optional aliases).

File location: Create hosts.txt in Load Tester's custom configuration directory:

Windows: C:\Users\<username>\WebPerformance7\config\hosts.txt
macOS/Linux: ~/WebPerformance7/config/hosts.txt

See Configuration Files Reference for the exact path.

File format: Plain text, one entry per line:

IPAddress     Hostname     [Aliases]

Whitespace: Separate the IP address and hostname with one or more spaces or tabs.

Comments: Lines starting with # are ignored.

Example 1: Single Hostname Override¶

Scenario: Redirect www.example.com to a test server at 10.1.1.5.

hosts.txt:

# Redirect production hostname to test server
10.1.1.5     www.example.com

What this does:

All HTTP requests to www.example.com resolve to 10.1.1.5 instead of the public DNS value
Both controller and remote engines use this override

Example 2: Multiple IPs for Load Balancing¶

Scenario: Round-robin between two backend servers (10.1.1.1 and 10.1.1.2) for app.internal.corp.

hosts.txt (multi-line format):

10.1.1.1     app.internal.corp
10.1.1.2     app.internal.corp

Or (compact format with comma-separated IPs):

10.1.1.1, 10.1.1.2=app.internal.corp

What this does:

Load Tester alternates between the two IP addresses when resolving app.internal.corp
Simulates client-side round-robin load balancing (not true DNS round-robin, which would require server-side configuration)

Example 3: Complete hosts.txt File¶

Scenario: Pre-production environment with multiple internal hostnames.

hosts.txt:

# This is an example hosts.txt file for Load Tester
# Format: IPAddress     Hostname     [Aliases]

# Web servers
10.1.1.5     www.staging.corp     web01
10.1.1.6     www.staging.corp     web02

# API server
10.1.2.10    api.staging.corp

# Database (for monitoring tools, not HTTP)
10.1.3.20    db.staging.corp

What this does:

www.staging.corp resolves to both 10.1.1.5 and 10.1.1.6 (alternating)
api.staging.corp resolves to 10.1.2.10
db.staging.corp resolves to 10.1.3.20
Aliases (web01, web02) are optional but can be used in URLs

Resolution Order¶

When Load Tester resolves a hostname, it checks in this order:

Load Tester's hosts.txt (this file)
System hosts file (/etc/hosts or Windows equivalent)
DNS query (standard network DNS)

If the hostname appears in hosts.txt, Load Tester uses that IP address and skips steps 2 and 3. This means your custom configuration overrides both the system hosts file and DNS.

Applying Configuration Changes¶

After editing hosts.txt:

Save the file (plain text, no formatting)
Restart Load Tester (changes only take effect on startup)
Run a replay to verify hostnames resolve correctly
Check Headers View to see the actual IP address Load Tester connected to

Verifying the override worked:

Open Headers View for any transaction
Look at the Request Line (first line): GET /path HTTP/1.1
Look at the Host header: Host: www.example.com
Look at the TCP connection info (if visible): Should show the IP from hosts.txt, not the public DNS IP

Remote engines

hosts.txt is automatically distributed to remote engines, so you configure it once on the controller. If an override works on the controller but not on an engine, verify the file actually exists on the controller and that all engines match the controller version.

Ask the AI to Generate hosts.txt Configuration

If you're unsure about IP addresses, hostnames, or syntax:

I need to redirect www.example.com to a test server at 10.1.1.5 for load
testing. Can you show me the exact hosts.txt configuration and where to
put the file?

The AI can:

Generate the exact hosts.txt syntax for your scenario
Explain whether you need multi-IP round-robin or single IP override
Verify the file location and restart procedure
Troubleshoot DNS resolution issues during replay
Explain the interaction between hosts.txt, system hosts, and DNS