Virtual Host Setup

Learning Focus

By the end of this lesson you will know how to create a virtual host in OpenLiteSpeed, configure its essential components, and connect it to a listener.

What a Virtual Host Is

A virtual host contains the settings for one website or application. It defines where files live, how requests are handled, and which domains point to that site.

Core Components

Component	Purpose	Example
Virtual Host Root	Base directory for this vhost's config and data	/usr/local/lsws/conf/vhosts/example/
Config File	Per-site configuration	$VH_ROOT/vhconf.conf
Document Root	Where public web files are served from	/var/www/example.com/public/
Domain Mapping	Which domains route to this vhost	example.com, www.example.com
Script Handlers	How .php and other extensions are processed	Map to lsphp external app
Contexts	Path-based rules for special behavior	Proxy, redirect, static, or CGI

Creating a Virtual Host

Step 1: Prepare the File System

# Create the document root
sudo mkdir -p /var/www/example.com/public

# Create a test index page
echo '<h1>Hello from example.com</h1>' | sudo tee /var/www/example.com/public/index.html

# Set permissions
sudo chown -R nobody:nogroup /var/www/example.com/
sudo chmod -R 755 /var/www/example.com/

Step 2: Create the Virtual Host in WebAdmin

1. Navigate to Virtual Hosts → Add
2. Fill in:
   • Virtual Host Name: example
   • Virtual Host Root: $SERVER_ROOT/conf/vhosts/$VH_NAME/
   • Config File: $VH_ROOT/vhconf.conf
   • Document Root: /var/www/example.com/public/
3. Click Save (WebAdmin creates the config file for you)

Step 3: Map Domains to the Virtual Host

1. Navigate to Listeners → select your HTTP or HTTPS listener
2. Click Virtual Host Mappings → Add
3. Set:
   • Virtual Host: example
   • Domains: example.com, www.example.com
4. Save

Step 4: Add PHP Support (Optional)

1. In the virtual host settings, go to Script Handlers → Add
2. Set:
   • Suffix: php
   • Handler Type: LiteSpeed SAPI
   • Handler Name: select your lsphp external app
3. Save

Step 5: Apply and Verify

# Graceful reload
sudo /usr/local/lsws/bin/lswsctrl restart

# Test the site
curl -H "Host: example.com" http://localhost/

# Check the error log
tail -20 /usr/local/lsws/logs/error.log

Common Setup Mistakes

Mistake	Symptom	Fix
Forgot domain mapping	Default page loads instead	Add mapping in Listener → Virtual Host Mappings
Wrong document root path	404 on all pages	Fix the path in Virtual Host → General
Permissions too restrictive	403 Forbidden	chown -R nobody:nogroup and chmod 755
No index file in doc root	403 instead of page	Add index.html or index.php
PHP handler not mapped	PHP files download instead of run	Add script handler for .php suffix

info

Think of the virtual host as the site-specific layer that sits behind the listener. The listener accepts traffic; the virtual host decides what to do with it.

Key Takeaways

• Each website gets its own virtual host with isolated configuration.
• The essential setup is: create vhost → set document root → map domains → add handlers.
• Always verify with a test request and error log after creating a new virtual host.

What's Next

• Continue to Document Root to understand where web files are served from.