OpenLiteSpeed Users' Manual - Configuration
Description: OpenLiteSpeed Users' Manual - Configuration.

Users' Manual
Version 1.9 — Rev. 4

# Configuration

## Concepts

Here are some basic concepts you should know before going into the detail of the configuration.

## Virtual hosts

OpenLiteSpeed can host multiple web sites (virtual hosts) with one server instance.

Traditionally, virtual hosts are classified into two types: IP-based virtual hosts and name-based virtual hosts. IP-based virtual hosts are web sites that have their own unique IP addresses. Name-based virtual hosts are web sites that are distinguished by their domain name and thus may share an IP address with other sites. There is no clear distinction between these two categories in OpenLiteSpeed. IP-based virtual hosts are considered just a special kind of name-based virtual host. Both of them can be easily configured, or even mixed together.

Unlike other web servers, OpenLiteSpeed does not have a default web site. Every web site is configured as a virtual host even if only one web site is hosted.

## Listeners

In OpenLiteSpeed, a listener is a server socket that listens on a specific IP address and TCP port. If you imagine the web server as a building, the listeners are the doors (each with its own IP address and port). Clients (browsers) have to go through a door (a listener) to submit their requests.

For each listener, an IP address and a port number need to be specified. IP address can be any valid local IP address, or you can set a wildcard IP (*) that refers to all available IP addresses on that machine. A port is an integer between 0 and 65535. The default port for HTTP is 80 and 443 for HTTPS. Other ports can be used, though, on UNIX machines, only the super user "root" has permission to use ports below 1024.

Only one listener is allowed for each IP and port combination. Thus, if a listener is configured to one port with the wildcard IP address, you cannot configure another listener to the same port, even if you specify a particular IP. For example, if there are multiple IP addresses on the web server machine, and HTTP traffic needs to be allowed on port 8080 for all IP addresses, this can be configured in two ways: set up one listener using the wildcard IP (*) and port 8080, or set up multiple listeners, one for each IP, all listening to port 8080. These two methods cannot be mixed on a single port.

There are two types of listeners in OpenLiteSpeed: plain and secure (SSL). Each secure listener requires a paired SSL private key and SSL certificate. The private key can be generated with an SSL toolkit like OpenSSL. The SSL certificate can be self-signed or obtained from a trusted certificate authority (CA) such as DigiCert or Let's Encrypt. You can share the same private key and certificate pair among multiple listeners.

## Listener-to-virtual-host mapping

LiteSpeed's listener-to-virtual-host mapping provides extra flexibility, allowing you to:

- map one listener to one virtual host.
- map one listener to different virtual hosts for different domain names.
- map multiple listeners to the same virtual host.
- map multiple listeners to multiple virtual hosts depending on their domain names.

In listener-to-virtual-host mapping, every listener has a virtual host lookup table with key-value pairs that specify a domain name (key) for a particular virtual host (value).

When a browser tries to retrieve a web page from a web server, it first uses a DNS lookup to find the IP address associated with that domain name. It then sends a request to establish a TCP connection with the web server on a specific IP and port. If there is a listener assigned to that IP and port, a connection is established. The browser then sends an HTTP request, which includes, in the header, the domain name of the web site being accessed. The web server checks the lookup table associated with that listener for the domain name in the request. If a match is found, the request is routed to the virtual host for processing.

In order to make a virtual host accessible through a specific listener, you must make sure that:

1. DNS is configured properly to map the domain name of the web site to the IP used by that listener. How to configure DNS is beyond the scope of this document.
2. A mapping to the virtual host for that domain name exists in the listener's lookup table.

A catchall virtual host can be specified for one listener with the wildcard domain name *. When the server cannot find a matching virtual host, the request will be routed to the catchall virtual host. If there is no such catchall virtual host configured, the web server will return error code 404.