Domain Mapping

Learning Focus

By the end of this lesson you will know how to map domains to virtual hosts, handle multiple domains per site, and troubleshoot incorrect routing.

What Domain Mapping Does

Domain mapping tells OpenLiteSpeed which virtual host should handle requests for a given hostname. When a request arrives at a listener, the server reads the Host header and routes it to the matching virtual host.

Configuring Domain Mapping

In WebAdmin

1. Navigate to Listeners → select the listener
2. Click Virtual Host Mappings → Add
3. Set:
   • Virtual Host: select an existing vhost
   • Domains: comma-separated list of domains
4. Save and Graceful Restart

Example Mappings

Domain(s)	Virtual Host	Notes
example.com, www.example.com	example	Main site with www alias
api.example.com	api	Separate API vhost
staging.example.com	staging	Staging environment
*	default	Catch-all fallback

Multiple Domains on One Virtual Host

You can map multiple domains to a single virtual host by listing them with commas:

example.com, www.example.com, example.net

All three domains will serve the same site content.

Troubleshooting Wrong Routing

If requests go to the wrong virtual host:

# Check what the server returns for a specific Host header
curl -H "Host: example.com" http://your-server-ip/

# Compare with another domain
curl -H "Host: other.com" http://your-server-ip/

Problem	Likely Cause	Fix
Default page shows instead of site	Domain not mapped	Add mapping in Listener → Vhost Mappings
Wrong site content served	Domain mapped to wrong vhost	Fix the mapping entry
Works for one domain but not alias	Alias not in the mapping list	Add the alias domain

info

If the mapping is wrong, the server may return the wrong site even when DNS is correct. Always verify mappings after DNS changes.

Key Takeaways

• Domain mapping routes requests to the correct virtual host based on the Host header.
• List all domains (including www aliases) in the mapping entry.
• If the wrong site loads, check the mapping first — it is the most common cause of incorrect routing.

What's Next

• Continue to Contexts to learn about path-based rules within a virtual host.