How to add virtual hosts and domains in OpenLiteSpeed

In OpenLiteSpeed, hosting a domain takes two pieces: a virtual host, which holds the site's files and settings, and a listener mapping, which tells the server which domain names on which port go to that virtual host. This guide sets up both in WebAdmin for example.com, and shows the config files WebAdmin writes so you can check its work.

Before you start

• OpenLiteSpeed installed and WebAdmin reachable. See Install OpenLiteSpeed web server on Ubuntu.
• LSPHP installed if the site uses PHP.
• Your domain's A record pointing at the server IP, for example 203.0.113.10. DNS can take time to update.
• Ports 80 and 443 open in the firewall, and no other web server using them.

Step 1: Create the site folders

Keep each site in its own folder. Create a document root and a logs folder:

sudo mkdir -p /var/www/example.com/html /var/www/example.com/logs
echo '<h1>example.com works</h1>' | sudo tee /var/www/example.com/html/index.html

On Ubuntu and Debian, OpenLiteSpeed runs PHP as the nobody user and nogroup group by default. Give your own user ownership, with read access for the server:

sudo chown -R deploy:nogroup /var/www/example.com
sudo find /var/www/example.com -type d -exec chmod 755 {} \;

Folders the app writes to, such as WordPress uploads, need write access for the PHP user. Grant that only where needed.

Step 2: Add the virtual host

1. Log in to WebAdmin at https://203.0.113.10:7080.
2. Go to Virtual Hosts and click + (Add).
3. Fill in the basics:

• Virtual Host Name: example.com
• Virtual Host Root: /var/www/example.com/
• Config File: $SERVER_ROOT/conf/vhosts/$VH_NAME/vhconf.conf
• Enable Scripts/ExtApps: Yes
• Restrained: Yes, which keeps the site's scripts inside its own root.

1. Click Save. WebAdmin warns that the config file does not exist. Click the link to create it, then save again.

Step 3: Set the document root and index files

Open the new virtual host and go to the General tab:

1. Edit the General section:

• Document Root: $VH_ROOT/html/
• Domain Name: example.com
• Domain Aliases: www.example.com

1. Edit Index Files:

• Use Server Index Files: No
• Index Files: index.php, index.html
• Auto Index: No, so visitors cannot browse folders without an index.

1. Optionally, on the Log tab, set the error and access logs to $VH_ROOT/logs/error.log and $VH_ROOT/logs/access.log.

Save each section.

Step 4: Enable rewrites

Most PHP apps need URL rewriting for pretty links. On the Rewrite tab, edit Rewrite Control:

• Enable Rewrite: Yes
• Auto Load from.htaccess: Yes

This lets OpenLiteSpeed read RewriteRule lines from the site's .htaccess file. Other Apache directives in .htaccess are ignored. See Make.htaccess rewrites work in OpenLiteSpeed for the details.

Step 5: Add a listener on port 80 and map the domain

A fresh install has one listener, Default, on port 8088. Add one for normal web traffic:

1. Go to Listeners and click +.
2. Set Listener Name to HTTP, IP Address to ANY IPv4, Port to 80, and Secure to No. Save.
3. Open the new listener. Under Virtual Host Mappings, click +.
4. Choose the Virtual Host example.com, and set Domains to example.com, www.example.com. Save.

You can map many virtual hosts to the same listener. OpenLiteSpeed picks the vhost by the domain name the browser asks for.

Step 6: Apply with a graceful restart

Click the Graceful Restart icon at the top right of WebAdmin, or run:

sudo /usr/local/lsws/bin/lswsctrl restart

A graceful restart loads the new config without dropping connections already in progress.

What WebAdmin writes

WebAdmin stores your settings in plain text. The virtual host config is in /usr/local/lsws/conf/vhosts/example.com/vhconf.conf, and the listener mapping is in /usr/local/lsws/conf/httpd_config.conf:

listener HTTP {
  address                 *:80
  secure                  0
  map                     example.com example.com, www.example.com
}

You can edit these files by hand, but WebAdmin may rewrite them. Pick one way of working and stick to it, and always restart after editing.

Check it works

1. From your computer, run:

   curl -I http://example.com/

You should get HTTP/1.1 200 OK and a server: LiteSpeed header.

1. Open http://example.com in a browser and see the test page.
2. If DNS has not updated yet, test with the host header: curl -H "Host: example.com" http://203.0.113.10/.

Troubleshooting

• You see the OpenLiteSpeed example page instead of your site: the domain is not mapped on the listener the request arrived on. Check the mapping and the port.
• 404 for every page: the document root is wrong. Make sure it ends in /html/ and that index.html exists there.
• 403 Forbidden: the server cannot read the files, or Restrained blocks a symlink outside the root. Check ownership and ls -l.
• Settings saved but nothing changed: you have not done a graceful restart yet.
• Port 80 listener will not start: another program holds port 80. Find it with sudo ss -ltnp | grep ':80 '.

Next steps

• Add HTTPS to the new site: Add Let's Encrypt SSL to OpenLiteSpeed.
• Put WordPress on it: Install WordPress on OpenLiteSpeed with LSCache.
• Set up DNS records correctly: DNS records explained.