OpenLiteSpeed Web Server Users' Manual

Version 1.3 Rev. 1
Configuration

Context

In LiteSpeed Web Server terminology, a "context" is a virtual location, a common parent URL, that identifies a group of resources. Contexts can be thought of as different directories in your website's directory tree. For example, "/" is the root context mapped to the document root of a website. "/cgi-bin/" is a context farther up on the tree, dedicated to the CGI applications for this site. A context can be explicitly defined in LiteSpeed's WebAdmin console for the following purposes:

Table of Contents

Static Context

URI | Location | Accessible | Enable Expires | Expires Default | Expires By Type | Extra Headers | MIME Type | Force MIME Type | Default MIME Type | Auto Index | Index Files | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable Rewrite | Rewrite Inherit | Rewrite Base | Rewrite Rules | Enable IP Geolocation | 

Java Web App Context

URI | Location | Servlet Engine | Enable Expires | Expires Default | Expires By Type | Extra Headers | Auto Index | Index Files | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

Servlet Context

URI | Servlet Engine | Extra Headers | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

FastCGI Context

URI | FastCGI App | Extra Headers | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

LiteSpeed SAPI Context

URI | LiteSpeed SAPI App | Extra Headers | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

Proxy Context

URI | Web Server | Extra Headers | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

CGI Context

URI | Path | Extra Headers | Allow Set UID | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable Rewrite | Rewrite Inherit | Rewrite Base | Rewrite Rules | Enable IP Geolocation | 

Redirect Context

URI | External Redirect | Status Code | Destination URI | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | 

Load Balancer Context

URI | Load Balancer | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

Rack/Rails Context

URI | Location | Run-Time Mode | Max Connections | Environment | Enable Expires | Expires Default | Expires By Type | Extra Headers | Index Files | Auto Index | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable Rewrite | Rewrite Inherit | Rewrite Base | Rewrite Rules | Enable IP Geolocation | 

Module Handler Context

URI | Module | Extra Headers | Realm | Authentication Name | Require (Authorized Users/Groups) | Access Allowed | Access Denied | Authorizer | Add Default Charset | Customized Default Charset | Enable IP Geolocation | 

Static ContextGo to top
Description: Context settings are used to specify special settings for files in a certain location. These settings can be used to bring in files outside of the document root (like Apache's Alias or AliasMatch directives), or to protect a particular directory using authorization realms, or to block or restrict access to a particular directory within the document root.
URIGo to top
Description: Specifies the URI for this context.
Syntax: The URI can be a plain URI (starting with "/") or a Perl compatible regular expression URI (starting with "exp:"). If a plain URI ends with a "/", then this context will include all sub-URIs under this URI. If the context maps to a directory on the file system, a trailing "/" must be added.
See Also: Location
LocationGo to top
Description: Specifies the corresponding location of this context in the file system.
Syntax: It can be an absolute path or path relative to $SERVER_ROOT, $VH_ROOT, or $DOC_ROOT. $DOC_ROOT is the default relative path, and can be omitted.

If the URI is a regular expression, then the matched sub-string can be used to form the "Root" string. The matched sub-string can be referenced with the values "$1" - "$9". "$0" and "&" can be used to reference the whole matched string. Additionally, a query string can be set by appending a "?" followed by the query string. Be careful. "&" should be escaped as "\&" in the query string.
Example: A plain URI like /examples/ with Location set to /home/john/web_examples will map the request "/examples/foo/bar.html" to file "/home/john/web_examples/foo/bar.html".
To simulate Apache's mod_userdir, set URI to exp: ^/~([A-Za-z0-9]+)(.*), set Location to /home/$1/public_html$2. With these settings, a request of URI /~john/foo/bar.html will map to file /home/john/public_html/foo/bar.html.
See Also: URI
AccessibleGo to top
Description: Specifies whether this context can be accessed. Set to No to deny access. You can use this feature to protect the specified directory from being visited. You may use it when you are updating contents for this context or you have special data in this directory.
Syntax: Select from radio box
Enable ExpiresGo to top
Description: Specifies whether to generate an Expires header for static files. If enabled, an Expires header will be generated based on Expires Default and Expires By Type.

This can be set at server, virtual host and context level. Lower level settings will override higher level ones, i.e. context settings will override virtual host settings and virtual host settings will override server settings.
Syntax: Select from radio box
Expires DefaultGo to top
Description: Specifies default settings for Expires header generation. This setting takes effect when Enable Expires is set to "Yes". It can be overridden by Expires By Type. Do not set this default at the server or virtual host level unless you have to, since it will generate Expires headers for all pages. Most of time this should be set at the context level for certain directories that do not change often. If there is no default setting, no Expires header will be generated for types not specified in Expires By Type.
Syntax: A|Mseconds
The file will expire after base time(A|M) plus specified seconds. Base time "A" sets the value to the client's access time and "M" to the file's last modified time.
Expires By TypeGo to top
Description: Specifies Expires header settings for individual MIME types.
Syntax: Comma delimited list of "MIME-type=A|Mseconds". The file will expire after base time (A|M) plus specified seconds.

Base time "A" sets the value to the client's access time and "M" to the file's last modified time. MIME-type accepts wildcard "*", like image/*.
Extra HeadersGo to top
Description: Specifies extra response headers to be added. Multiple headers can be added, one header per line.
Syntax: "[HeaderName]: [HeaderValue]" in each line.
Example: Cache-control: no-cache, no-store
My-header: Custom header value
MIME TypeGo to top
Description: Specifies additional MIME types and mappings for this context. New mappings will override existing mappings under this context and its children contexts.
If you want to show PHP scripts as text files instead of being executed as scripts, just override the .php mapping to MIME type "text/plain".
Syntax: MIME-type1 extension extension ..., MIME-type2 extension ... Use comma to separate between MIME types, use space to separate multiple extensions.
Example: image/jpg jpeg jpg, image/gif gif
Force MIME TypeGo to top
Description: When specified, all files under this context will be served as static files with the MIME type specified regardless of file suffix. When set to NONE, inherited force type setting will be disabled.
Syntax: MIME type or NONE.
Default MIME TypeGo to top
Description: When specified, this type will be used when MIME type mapping cannot be determined by the suffix of a document or if there is no suffix. If not specified, the default value application/octet-stream will be used.
Syntax: MIME-type
Auto IndexGo to top
Description: Specifies whether to generate a directory index on the fly when index files listed in Index Files are not available in a directory. This option is customizable at the virtual host and context level, and is inherited along the directory tree until it is explicitly overridden. You can customize the generated index page. Please check online wiki How-tos.
Syntax: Select from radio box
Tips: [Security] It is recommended to turn off Auto Index wherever possible to prevent revealing confidential data.
See Also: Index Files, Auto Index URI
Index FilesGo to top
Description: Specifies names of index files that will be searched sequentially when a URL is mapped to a directory. You can customize it at the server, virtual host, and context level.
Syntax: Comma delimited list of index file names.
Tips: [Performance] Only set index files that you need.
RealmGo to top
Description: Specifies the authorization realm for this context. When specified, a valid user name and password must be provided in order to access this context. Authorization Realms are set up in the Virtual Host Security section. This setting uses each realm's Realm Name.
Syntax: Select from drop down list
Authentication NameGo to top
Description: Specifies an alternative name for the authorization realm for current context. If it is not specified, the original realm name will be used. The authentication name is displayed on the browser's login pop-up.
Require (Authorized Users/Groups)Go to top
Description: Specifies which user/group can access this context. This allows you to use one user/group database (specified in Realm) across a number of contexts, but only allow certain users/groups from that database to access this context.
Syntax: Syntax is compatible with Apache's Require directive. For example:
  • user username [username ...]
    Only listed users can access this context;
  • group groupid [groupid ...]
    Only users belonging to the listed groups can access this context.
If this setting is not specified, all valid users will be able to access this resource.
Access AllowedGo to top
Description: Specifies which IPs or sub-networks are allowed to access resources under this context. Together with Access Denied and server/virtual host-level access control, accessibility is determined by the smallest scope that a client's IP address falls into.
Syntax: Comma-delimited list of IPs/sub-networks.
Example: Sub-networks can be written as 192.168.1.0/255.255.255.0, 192.168.1 or 192.168.1.*.
Access DeniedGo to top
Description: Specifies which IPs or sub-networks are NOT allowed to access resources under this context. Together with Access Allowed and server/virtual host-level access control, accessibility is determined by the smallest scope that a client's IP address falls into.
Syntax: Comma-delimited list of IPs/sub-networks.
Example: Sub-networks can be written as 192.168.1.0/255.255.255.0, 192.168.1 or 192.168.1.*.
AuthorizerGo to top
Description: Specifies an external application that can be used to generate authorized/unauthorized decisions. Currently, only the FastCGI Authorizer is available. For more details about the FastCGI Authorizer role, please visit http://www.fastcgi.com.
Syntax: Select from drop down list
Add Default CharsetGo to top
Description: Specifies whether to add a character set tag to the "Content-Type" response header, when content type is either "text/html" or "text/plain" without any parameters. When set to Off, this function is disabled. When set to On, either the character set specified by Customized Default Charset or the default "iso-8859-1" will be added.
Syntax: Select from radio box
Customized Default CharsetGo to top
Description: Specifies a character set to be used when Add Default Charset is On. This is optional. The default value is iso-8859-1. This entry has no effect when Add Default Charset is Off.
Syntax: Name of a character set, like utf-8
Example: utf-8
Enable RewriteGo to top
Description: Specifies whether to enable LiteSpeed's URL rewrite engine. This option can be customized at virtual host- and context-level, and is inherited along the directory tree until it is explicitly overridden.
Syntax: Select from radio box
Rewrite InheritGo to top
Description: Specifies whether to inherit rewrite rules from parent contexts. If rewrite is enabled and not inherited, rewrite base and rewrite rules defined in this context will be used.
Syntax: Select from radio box
Rewrite BaseGo to top
Description: Specifies the base URL for rewrite rules.
Syntax: URL
Rewrite RulesGo to top
Description: Specifies a list of rewrite rules at virtual host or context level. A rewrite rule is comprised of one RewriteRule directive and optionally preceded by multiple RewriteCond directives.
  • Each directive should take only one line.
  • RewriteCond and RewriteRule follow Apache's rewrite directive syntax. Just copy and paste rewrite directives from your Apache configuration files.
  • There are minor differences between LiteSpeed and Apache mod_rewrite implementation:
    • %\{LA-U:variable\} and %\{LA-F:variable\} are ignored by the LiteSpeed rewrite engine
    • two new server variables are added in the LiteSpeed rewrite engine: %\{CURRENT_URI\} represents the current URI processed by the rewrite engine and %\{SCRIPT_NAME\} has the same meaning as the corresponding CGI environment variable.
The implementation of LiteSpeed's rewrite engine follows the specifications of Apache's rewrite engine. For more details about rewrite rules, please refer to Apache's mod_rewrite document and Apache's URL rewriting guide.
Syntax: string
Enable IP GeolocationGo to top
Description: Specifies whether to enable IP geolocation lookup. It can be set at server-, virtual host-, or context-level.
Syntax: Select from radio box
See Also: Use Client IP in Header, DB File Path, DB Cache Type
Java Web App ContextGo to top
Description: Many people running Java applications use the servlet engine to serve static content as well. But no servlet engine is nearly as efficient as LiteSpeed Web Server for these processes. In order to improve the overall performance, LiteSpeed Web Server can be configured as a gateway server, which serves static content and forwards dynamic Java page requests to the servlet engine.

LiteSpeed Web Server requires certain contexts to be defined in order to run a Java application. A Java Web App Context automatically creates all required contexts based on the Java web application's configuration file (WEB-INF/web.xml).

There are a few points you need to keep in mind when setting up a Java Web App Context:
  • A Servlet Engine external application must be set up in External Application before Java Web App Context can be set up.
  • A Script Handler for .jsp files should be defined as well.
  • If the web application is packed into a .war file, the .war file must be expanded. The server cannot access compressed archive files.
  • For the same resources, the same URL should be used no matter whether it is accessed through LiteSpeed Web Server or through the servlet engine's built-in HTTP server.
    For example, Tomcat 4.1 is installed under /opt/tomcat. Files for the "examples" web application are located at /opt/tomcat/webapps/examples/. Through Tomcat's built-in HTTP server, the "examples" web application is thus accessed with a URI like "/examples/***". The corresponding Java Web App Context should thus be configured: URI = /examples/, Location = /opt/tomcat/webapps/examples/.
URIGo to top
Description: Specifies the URI for this context. The URI should start with a "/". If a URI ends with a "/", then this context will include all sub-URIs under this URI.
Syntax: URI
LocationGo to top
Description: Specifies the directory that contains the files for this web application. This is the directory containing "WEB-INF/web.xml".
Syntax: path
Servlet EngineGo to top
Description: Specifies the name of the servlet engine that serves this web application. Servlet engines must be defined in the External Application section at the server or virtual host level.
Syntax: Select from drop down list
Servlet ContextGo to top
Description: Servlets can be imported individually through Servlet Contexts. A Servlet Context just specifies the URI for the servlet and the name of the servlet engine. You only need to use this when you do not want to import the whole web application or you want to protect different servlets with different authorization realms. This URI has the same requirements as for a Java Web App Context.
FastCGI ContextGo to top
Description: FastCGI applications cannot be used directly. A FastCGI application must be either configured as a script handler or mapped to a URL through FastCGI context. A FastCGI context will associate a URI with a FastCGI application.
FastCGI AppGo to top
Description: Specifies the name of the FastCGI application. This application must be defined in the External Application section at the server or virtual host level.
Syntax: Select from drop down list
LiteSpeed SAPI ContextGo to top
Description: External applications cannot be used directly. They must be either configured as a script handler or mapped to a URL through a context. An LiteSpeed SAPI Context will associate a URI with an LSAPI (LiteSpeed Server Application Programming Interface) application. Currently PHP, Ruby and Python have LSAPI modules. LSAPI, as it is developed specifically for LiteSpeed web server, is the most efficient way to communicate with LiteSpeed web server.
LiteSpeed SAPI AppGo to top
Description: Specifies the name of the LiteSpeed SAPI application to be connected to this context. This application must be defined in the External Application section at the server or virtual host level.
Syntax: Select from drop down list
Proxy ContextGo to top
Description: A Proxy Context enables this virtual host as a transparent reverse proxy server. This proxy server can run in front of any web servers or application servers that support HTTP protocol. The External web server that this virtual host proxies for has to be defined in External Application before you can set up a Proxy Context.
Web ServerGo to top
Description: Specifies the name of the external web server. This external web server must be defined in the External Application section at the server or virtual host level.
Syntax: Select from drop down list
CGI ContextGo to top
Description: A CGI context defines scripts in a particular directory as CGI scripts. This directory can be inside or outside of the document root. When a file under this directory is requested, the server will always try to execute it as a CGI script, no matter if it's executable or not. In this way, file content under a CGI Context is always protected and cannot be read as static content. It is recommended that you put all your CGI scripts in a directory and set up a CGI Context to access them.
PathGo to top
Description: Specifies the location of CGI scripts.
Syntax: The path can be a directory that contains a group of CGI scripts, like $VH_ROOT/myapp/cgi-bin/. In this case, the context URI must end with "/", like /app1/cgi/. The Path can also specify only one CGI script, like $VH_ROOT/myapp/myscript.pl. This script should have the corresponding URI /myapp/myscript.pl.
Allow Set UIDGo to top
Description: Specifies whether the set UID bit is allowed for CGI scripts. If the set UID bit is allowed and the set UID bit is enabled for a CGI script, no matter which user the CGI script was started on behalf of, the user ID of the CGI process will switch to the user ID of the owner of the CGI script.
The default is "Off".
Syntax: Select from radio box
Tips: [Security] Do not allow Set UID CGI scripts whenever possible, as it is inherently a security risk.
Redirect ContextGo to top
Description: A Redirect Context can be used to forward one URI or a group of URIs to another location. The destination URI can be either on the same web site (an internal redirect) or an absolute URI pointing to another web site (an external redirect).
External RedirectGo to top
Description: Specifies whether this redirect is external. For external redirection, Status Code may be specified and Destination URI can start either with "/" or "http(s)://". For internal redirection, Destination URI must start with "/".
Status CodeGo to top
Description: Specifies the response status code of the external redirection. If the status code is between 300 and 399, Destination URI can be specified.
Syntax: Select from drop down list
Destination URIGo to top
Description: Specifies the target location of the redirection. If this redirected URI maps to a URI in another redirect context, it will be redirected again.
Syntax: This URI can either be a relative URI on the same web site starting with "/", or an absolute URI pointing to different web site starting with "http(s)://". If the URI contains regular expression, the destination can reference the matched variables, such as $1 or $2.
Load Balancer ContextGo to top
Description: Like other external applications, load balancer worker applications cannot be used directly. They must be mapped to a URL through a context. A Load Balancer Context will associate a URI to be load balanced by the load balancer workers.
Load BalancerGo to top
Description: Specifies the name of the load balancer to be associated to this context. This load balancer is a virtual application, and must be defined in the External Application section at the server or virtual host level.
Syntax: Select from drop down list
Rack/Rails ContextGo to top
Description: A Rack/Rails Context provides an easy way to configure a Ruby Rack/Rails application. To add a Rack/Rails application through a Rack/Rails Context, only mounting the URL and the application's root directory is required. There is no need to go through all the troubles to define an external application, add a 404 handler, and rewrite rules, etc.
Run-Time ModeGo to top
Description: Specifies which mode Rack/Rails will be running as: "Development", "Production", or "Staging". The default is "Production".
Syntax: Select from drop down list
Max ConnectionsGo to top
Description: Specifies the maximum number of concurrent connections that can be established between the web server and an external application. This setting controls how many requests can be processed concurrently by an external application, however, the real limit also depends on the external application itself. Setting this value higher will not help if the external application is not fast enough or cannot scale to a large number of concurrent requests.
Syntax: Integer number
Tips: [Performance] Setting a high value does not directly translate to higher performance. Setting the limit to a value that will not overload the external application will provide the best performance/throughput.
EnvironmentGo to top
Description: Specifies extra environment variables for the external application.
Syntax: Key=value. Multiple variables can be separated by "ENTER"
Module Handler ContextGo to top
Description: A module handler context will associate a URI with a registered module. Modules need to be registered at Server Module Configuration tab.
ModuleGo to top
Description: Name of the module. The module must be registered under the Server Module Configuration tab. Once it is registered, the module name will be available in the drop down box for the Listener and Virtual Host configurations.
Syntax: Select from drop down list