## LiteSpeed Web Server
Users' Manual

### Version 6.3 — Rev. 4

- License Enterprise
- Introduction
- Installation
- Administration
- Security
- Configuration
  - Server General
  - Server Log
  - Server Tuning
  - Server Security
  - Page Cache
  - PageSpeed Config
  - External Apps
  - Fast CGI App
  - Fast CGI Authorizer
  - LSAPI App
  - Servlet Engine
  - Web Server
  - Piped logger
  - Load Balancer
  - Script Handler
  - PHP
  - App Server Settings
  - Listener General
  - Listener SSL
  - Virtual Host Templates
  - Virtual Host Basic
  - Virtual Host General
  - Virtual Host Security
  - Virtual Host SSL
  - Virtual Host PageSpeed Config
  - Rewrite
  - Context
  - Static Context
  - Java Web App Context
  - Servlet Context
  - Fast CGI Context
  - LSAPI Context
  - Proxy Context
  - CGI Context
  - Load Balancer Context
  - Redirect Context
  - App Server Context
  - Rack/Rails Context
  - Add-ons
- Web Console
  - Admin Console General
  - Admin Console Security
  - Admin Listener General
  - Admin Listener SSL

# Server General

General settings for the whole server. When path information is required in a setting, it can be either absolute or relative to $SERVER_ROOT. $SERVER_ROOT is the location where LiteSpeed web server has been installed (your_home_dir/lsws or /opt/lsws, for example). The server executable is under $SERVER_ROOT/bin.

## Table of Contents

### Server Name⇑

#### Description

A unique name for this server. You can use $HOSTNAME as value.

### Number of Processes⇑

#### Description

[Only Available For Web Host Elite Licenses]
Specifies the number of lshttpd workers. Enter 0 to have this number be decided automatically.

#### Syntax

Integer value between 0 and 128.

#### Tips

Set an appropriate number to suit your needs. Adding more processes may not necessarily mean better performance.

### Running As⇑

#### Description

Specifies the user/group that the server process runs as. This value is set during installation. In order to change it, you must download the installation package and perform an upgrade via the command line.

#### Apply

Reinstall required.

#### Tips

Server should not be run as a privileged user, such as "root". It is critical that the server is configured to run as an un-privileged user/group combination that does not have login/shell access. A user and group of nobody is generally a good choice.

### Priority⇑

#### Description

Specifies priority of the server processes. Value ranges from -20 to 20. A lower number means higher priority.

#### Syntax

Integer number

#### Tips

Usually a higher priority leads to slightly higher web performance on a busy server. Do not set priority higher than that of database processes.

#### See Also

External App Priority, CGI Priority

### CPU Affinity⇑

#### Description

CPU affinity binds a process to one or more CPUs (cores). It is beneficial for a process to always use the same CPU because then the process can make use of data left in CPU cache. If the process moves to a different CPU, there is no use of CPU cache and unnecessary overhead is required.
The CPU Affinity setting controls how many CPUs (cores) one server process will be associated with. The minimum value is 0, which will disable this feature. The maximum value is the number of cores the server has. Generally, 1 is the best setting because it creates the strictest use of CPU affinity and thus makes the most use of CPU cache.
Default value: 0

#### Syntax

Integer value from 0 to 64. (0 will disable this feature)

#### Apply

Reinstall required.

### Chroot Path⇑

#### Description

Enterprise Edition Only Specifies the directory where the chroot environment is rooted. Only "root" user can run the server in chroot mode. Whether to run in chroot mode is controlled by Enable chroot option. The installer program will set up the initial chroot environment automatically. This entry is read-only, and if you want to change it, please run the installer again from the command line.
In the chroot environment, the server and its child processes cannot access file systems outside of the chroot jail. Chroot is an advanced security feature and additional administration may be required to make it work properly. All required executables, libraries, configuration files, and device files should be recreated within the chroot jail.
As the root directory is changed, you need to pay special attention to path configuration when an absolute path is used. A Unix domain socket or swapping directory is always relative to the new root directory. All other path configurations are always relative to the real root.

#### Apply

Reinstall required.

#### Tips

Use chroot for better security.

### Enable chroot⇑

#### Description

Enterprise Edition Only Specifies whether to start the server in chroot mode. The new root directory is set by Chroot Path during installation.

#### Syntax

Select from radio box

### Cloud-Linux⇑

#### Description

Specifies whether to enable CloudLinux's Lightweight Virtual Environment (LVE) when it exists. You can use LiteSpeed with LVE to achieve better resource management. For more information, please check http://www.cloudlinux.com.

#### Syntax

Select from drop down list

### Max I/O Buffer Size⇑

#### Description

Specifies the maximum buffer size that is used to store a request body and its dynamically generated response. When this limit is reached, the server will start to create temporary swapping files under Swapping Directory.

#### Syntax

Integer number

#### Tips

Set the buffer size large enough to accommodate all concurrent requests/replies to avoid memory to disk swapping. If there is frequent I/O activity to the swap directory, by default /tmp/lshttpd/swap/, this buffer size is too low and LiteSpeed is swapping to disk.

#### See Also

Swapping Directory

### Swapping Directory⇑

#### Description

Specifies the directory where the swapping files should be placed. When the server is started in chroot mode, this directory is relative to the new root directory, otherwise it is relative to the real root directory.
The server uses its own virtual memory to reduce system memory usage. Virtual memory and disk swapping are used to store large request bodies and dynamically generated responses. The swapping directory should be placed on a disk with enough space.
Default value: /tmp/lshttpd/swap

#### Syntax

Absolute path

#### Tips

Place the swapping directory on a separate disk or increase Max I/O Buffer Size to eliminate swapping.

#### See Also

Max I/O Buffer Size

### Auto Fix 503 Error⇑

#### Description

Specifies whether to try to fix the "503 Service Unavailable" error by restarting the server gracefully. A "503" error is usually caused by malfunctioning external applications and a web server restart can often fix the error temporarily. If enabled, the server will restart automatically whenever there are more than 30 "503" errors within a 30 seconds span.
Default value: No

#### Syntax

Select from radio box

### Enable HTTP/2 Over Cleartext TCP⇑

#### Description

Specifies whether to enable HTTP/2 over non-encrypted TCP connections. Default is disabled.

#### Syntax

Select from radio box

### Graceful Restart Timeout (secs)⇑

#### Description

During a graceful restart, even after the new server instance is up, the old instance will continue to handle existing requests. This timeout defines how long the previous instance shall wait before exit. Default value is 300 seconds. -1 means wait forever. 0 means no wait and abort immediately.

#### Syntax

int

### MIME Settings⇑

#### Description

Specifies the file that contains the MIME settings for this server. It is always relative to the real root when an absolute path is given in chroot mode. Click on the filename to view/edit the detailed MIME entries.

#### Syntax

Filename which can be an absolute path or a relative path to $SERVER_ROOT.

#### Tips

Click the filename to edit the MIME settings.

### Suffixes⇑

#### Description

You can list multiple suffixes for the same MIME type, using comma to separate.

### MIME Type⇑

#### Description

A MIME type consists of a type and subtype in the format of "type/subtype".

### Disable Initial Log Rotation⇑

#### Description

Specifies whether to disable rotation of server error log file at startup. Initial log rotation is enabled by default for standard installations. Servers using cPanel, however, always write to the Apache error log and thus ignore this setting.

#### Syntax

Select from radio box

### Server Signature⇑

#### Description

Specifies whether to show the server signature and version number in the response header's "Server" value. There are three options: when set to Hide Version, only LiteSpeed is shown. When set to Show Version, LiteSpeed and the version number are shown. Enterprise Edition Only When set to Hide Full Header, the entire Server header will not be shown in the response header.

#### Syntax

Select from drop down list

#### Tips

Set to Hide Version if you do not wish to expose the server version number.

### Hide Error Page Signature⇑

#### Description

Specifies whether or not to show the lines

> Powered By LiteSpeed.
> LiteSpeed Technologies is not responsible for administration and contents of this web site!"

on your default error pages.

#### Syntax

Select from radio box

### Enable GeoLocation Lookup⇑

#### Description

Enterprise Edition Only Specifies whether to enable/disable IP Geolocation lookup. Can be set at server, virtual host, or context level. IP Geolocation is disabled by default when using value "Not Set".

#### Syntax

Select from radio box

#### See Also

Use Client IP in Header, DB File Path,

### Use Client IP in Header⇑

#### Description

Specifies whether to use the first most valid IP IP address listed in the "X-Forwarded-For" HTTP request header for all IP address-related features, including connection/bandwidth throttling, access control, and IP geolocation.
This feature is useful if your web server is behind a load balancer or a proxy server. If you select Trusted IP Only, then X-Forwarded-For IP will be used only when the request is coming from trusted IPs defined in the server-level Allowed List.
Keep Header from Trusted IP is the same as Trusted IP Only, but the X-Forwarded-For header used for the backend will not be modified to include the connecting peer address.
Use Last IP (for AWS ELB) will use the last IP address in the "X-Forwarded-For" list. Select this option if you are using AWS Elastic Load Balancer or expect the real IP to appended to the end of the "X-Forwarded-For" list.

#### Syntax

Select from drop down list

### External Application Abort⇑

#### Description

When a client breaks a connection with the server, LiteSpeed Web Server can automatically abort external application processes generating responses for that client. Some users, however, may have (long-running) processes that they wish to continue running whether or not the client is still connected.
There are three options for this:

- No Abort: Never abort external applications because of a broken connection.
- Enable Abort for Requests from External IPs: Only processes started by requests from external IPs will be automatically aborted because of a broken connection. This is the default setting. It is a good setting if you have some internal long-running processes, like some cron jobs.
- Enable Abort for All Requests: External application processes will be automatically aborted if the connection is broken, regardless of the source of the request.

#### Syntax

Select from drop down list

### Check For Update⇑

#### Description

Specifies how often the update agent will check for a new product release. Options are "Daily", "Weekly", "Monthly" and "Disable".

#### Syntax

Select from drop down list

### Download Updates⇑

#### Description

Specifies whether to auto-download a new product release package file when available. If a new package has been successfully downloaded, an online one-click upgrade can be performed via the WebAdmin console under Service Manager - Version Management.

#### Syntax

Select from drop down list

### Administrator Email⇑

#### Description

Specifies the server administrator's email address(es). If specified, administrators will be notified by email of important events (for example, when the LiteSpeed service is restarted automatically due to crash detection or when license is expiring).

#### Syntax

Comma delimited list of email address.

#### Tips

Email alert feature will only work if the server has an active MX server such as postfix, exim, or sendmail.

### Index Files⇑

#### 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 filenames.

#### Tips

Only set index files that you need.

### Auto Index⇑

#### 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

It is recommended to turn off Auto Index wherever possible to prevent revealing confidential data.

#### See Also

Index Files, Auto Index URI

### Auto Index URI⇑

#### Description

Specifies the URI that will be used to generate the index page when index files listed in Index Files are not available in a directory. LiteSpeed web server uses an external script to generate the index page providing the maximum customization flexibility. The default script produces an index page with same look as Apache's. To customize the generated index page, please read online wiki How-tos. The directory to be indexed is passed to the script via an environment variable "LS_AI_PATH".

#### Syntax

URI

#### See Also

Index Files, Auto Index

### HT Access⇑

#### Description

The following directives are supported in a directory level access control file (.htaccess file).

- Authentication
  - AuthGroupFile
  - AuthName
  - AuthType
  - AuthUserFile
  - Require
  - Satisfy
  - <Limit> (GET, HEAD, POST only)
  - <LimitExcept> (GET, HEAD, POST only)
- Access Control
  - Allow
  - Deny
  - Order
  - <Limit> (GET, HEAD, POST only)
  - <LimitExcept> (GET, HEAD, POST only)
- File Info
  - AddDefaultCharset
  - AddType
  - DefaultType
  - ForceType
  - Redirect
  - RedirectPermanent
  - RedirectTemp
  - RewriteBase
  - RewriteCond
  - RewriteEngine
  - RewriteOptions
  - RewriteRule
- Other
  - DirectoryIndex
  - ExpiresActive
  - ExpiresByType
  - ExpiresDefault
  - Options

### Allow Override⇑

#### Description

Specifies what directives in an access control file are allowed. An access control file can be placed in a directory to control the accessibility of files under that directory.

- When nothing is checked, inherited default settings will be used.
- When None is checked, access control files will be ignored.
- When Limit is checked, directives "Allow", "Deny", and "Order" are allowed. <Limit> and <LimitExcept> directives are also allowed with limited support for GET, HEAD, and POST requests.
- When Auth is checked, directives "AuthGroupFile", "AuthName", "AuthType", "AuthUserFile", "Require", and "Satisfy" are allowed. <Limit> and <LimitExcept> directives are also allowed with limited support for GET, HEAD, and POST requests.
- When FileInfo is checked, directives "AddDefaultCharset", "AddType", "DefaultType", "ForceType", "Redirect", "RedirectPermanent", "RedirectTemp", "RewriteBase", "RewriteCond", "RewriteEngine", "RewriteOptions", and "RewriteRule" are allowed.
- When Indexes is checked, directives "DirectoryIndex", "ExpiresActive", "ExpiresByType", and "ExpiresDefault" are allowed.
- When Options is checked, directive "Options" is allowed.

Allow Override configuration is available at the Server, Virtual Host, and Context levels. If a configuration is unchecked at the Server level, those controlled directives will be disabled for the entire server regardless of settings at lower levels. Lower levels can disable a setting that is enabled at a higher level, but cannot enable a setting that is disabled at an upper level.
Default values:
Server level: "None" (ignore access control file)
VH level: Inherit Server level setting
Context level Inherit VH level setting

#### Syntax

Select from checkbox

#### Tips

If there is no need for directory level configuration customization, check None.

### Access File Name⇑

#### Description

Specifies the name of access control files. These files will be used only if Allow Override is enabled. Default name is .htaccess. You can configure this at server level and virtual host level. Server level is the default setting, and you can override it at virtual host level.

#### Syntax

Filename starting with "."

#### See Also

Allow Override

### Enable Expires⇑

#### 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 Default⇑

#### 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 Type⇑

#### 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/*.

### MaxMind GeoIP DB⇑

#### Description

Multiple MaxMind geolocation databases can be specified here. MaxMind has the following type of DBs: Country, Region, City, Organization, ISP and Netspeed. If multiple databases of types "Country", "Region", and "City" are configured, the last configuration will be effective.

### DB File Path⇑

#### Description

Specifies the path to MaxMind GeoIP database.

#### Syntax

Absolute path

#### Example

/usr/local/share/GeoIP/GeoLite2-Country.mmdb

### DB Name⇑

#### Description

MaxMind GeoIP database name. As of GeoIP2, this setting is required.
When upgrading from a GeoIP to a GeoIP2, using values "COUNTRY_DB", "CITY_DB", or "ASN_DB" for this setting will automatically populate PHP's $_SERVER variable with some GeoIP compatible entries (listed by DB Name value below) to help ease this transition.
CITY_DB: 'GEOIP_COUNTRY_CODE', 'GEOIP_COUNTRY_NAME', 'GEOIP_CONTINENT_CODE', 'GEOIP_COUNTRY_CONTINENT', 'GEOIP_DMA_CODE', 'GEOIP_METRO_CODE', 'GEOIP_LATITUDE', 'GEOIP_LONGITUDE', 'GEOIP_POSTAL_CODE', and 'GEOIP_CITY'.
COUNTRY_DB: 'GEOIP_COUNTRY_CODE', 'GEOIP_COUNTRY_NAME', 'GEOIP_CONTINENT_CODE', and 'GEOIP_COUNTRY_CONTINENT'.
ASN_DB: 'GEOIP_ORGANIZATION' and 'GEOIP_ISP'.

#### Example

COUNTRY_DB

### Environment Variables⇑

#### Description

Assign the results of database lookups to environment variables.

#### Syntax

Variable_Name mapped_DB_data
One entry per line. Path to data can use map keys or 0-based array indexes, both being separated by /.

#### Example

COUNTRY_CODE COUNTRY_DB/country/iso_code
REGION_CODE CITY_DB/subdivisions/0/iso_code

### IP2Location DB File Path⇑

#### Description

The location of a valid database file.

#### Syntax

Filename which can be an absolute path or a relative path to $SERVER_ROOT.

### DB Cache Type⇑

#### Description

The caching method used. The default value is Memory.

#### Syntax

Select from drop down list

### Load Apache Configuration⇑

#### Description

Specifies whether LiteSpeed will read and use a Apache configuration file to configure the web server. Native configurations will have higher priority when there is conflict between LiteSpeed internal and Apache-based configurations.

#### Syntax

Select from radio box

### Auto Reload On Changes⇑

#### Description

Specifies how to apply Apache configuration changes. When set to "Yes", LSWS will perform a graceful restart whenever the Apache configuration file has been modified. This may cause LSWS to restart multiple times when updating Apache configurations. A better solution (introduced in version 3.3.8) is "Use Apache binary wrapper". This will replace Apache httpd binary with a wrapper script. Whenever Apache is requested to start/stop/restart, the script will tell LSWS to take corresponding action. Apache Binary Path must be set to use this setting. Default is "No" for standard installations. For cPanel servers, the default is "Use Apache binary wrapper". ("Override cPanel restart HTTPD script" is an optional workaround that should only be used if the option "Use Apache binary wrapper" is having problems.) For other control panels default is "Yes".

#### Syntax

Select from radio box

#### See Also

Apache Binary Path

### Apache Binary Path⇑

#### Description

Specifies the location of the Apache binary. Usually, it is located at /usr/local/apache/bin/httpd or /usr/local/apache2/bin/httpd, etc. This option must be set when "Use Apache binary wrapper" is used for Auto Reload On Changes.

#### See Also

Auto Reload On Changes

### Apache Configuration File⇑

#### Description

Specifies the location of Apache configuration file. Usually, it is located at /usr/local/apache/conf/httpd.conf or /etc/httpd/conf/httpd.conf.

### Apache Port Offset⇑

#### Description

Specifies an offset to be added to listening TCP ports specified in the Apache configuration file. In the testing phase, this allows LiteSpeed to run alongside Apache on a different port instead of switching back and forth between LiteSpeed and Apache on a production server.
If set to 0 or not set, LiteSpeed will use the ports specified in the Apache configuration file. When testing, make this setting a non-zero value. LiteSpeed will then add this offset value to the port specified in the Apache configuration and use this port. After confirming that everything works properly, you can stop Apache, set this option back to 0, and restart LiteSpeed.

### Apache IP Offset⇑

#### Description

Specifies an offset to be added to listening IP address specified in the Apache configuration file. This allows LiteSpeed to run alongside Apache in the testing phase instead of switching back and forth between LiteSpeed and Apache on a production server. The calculated IP address has to be available on this server.

#### Syntax

The offset should be set as an integer (allow negative number), not an IP address. Adding "256" will add 1 to the value of the C class subnet. This option only works with IPv4 address.

### Apache Handled Content⇑

#### Description

Specifies resources to be passed to and processed by Apache on the backend. This feature requires running Apache parallel to LiteSpeed on either another IP or a different port, so either "Apache Port Offset" or "Apache IP Offset" should be set to a non-zero value.

#### Syntax

Resources are specified by a comma delimited list of URI, file suffixes, or regular expressions. A URI starts with "/"; a suffix starts with ".", a regular expression starts with "exp:". For example: "/svn/, .shtml" lets Apache handle requests with a URI starting with "/svn/" or ending with ".shtml". The same effect can be achieved with the regular expression "exp:^/svn/, exp:\.shtml$".

### Ignore Apache Modules⇑

#### Description

Specifies a list of names of Apache modules that should be ignored by LiteSpeed while parsing the Apache configuration file. LiteSpeed will treat the listed modules as unsupported. This will cause configuration directives related to these modules enclosed in matching <IfModule> or <IfDefined> tags to be ignored.

#### Syntax

comma delimited list of module names

### Just In Time Configuration⇑

#### Description

With just in time configuration, the web server only finalizes vhost configurations when that virtual host is accessed for the first time, instead of loading all configurations at start up. This allows the web server to save memory and speed up server start up.

#### Syntax

Select from radio box

### PHP suEXEC⇑

#### Description

Specifies whether to run PHP script in suEXEC mode when "user" and "group" are specified for a virtual host. When set to Yes, PHP scripts will be executed under the user (and group unless Force GID is set) specified. When set to User's Home Directory Only, scripts outside a user's home directory will run as the global user/group that the web server run as. When using DirectAdmin, User's Home Directory Only is recommended. Default is No.

#### Syntax

Select from radio box

#### See Also

Force GID

### PHP suEXEC Max Conn⇑

#### Description

Specifies the maximum number of concurrent PHP processes that can be created by LSWS for each user when running PHP scripts in suEXEC mode. Default value is 5.

#### Syntax

Integer number

#### Tips

This limit is per user per lshttpd process. Thus, if you have a 2-CPU license, this limit will be doubled. The limit will be 4x for a 4-CPU license, and so on.

### Enable FrontPage Extension⇑

#### Description

Specifies whether to explicitly enable Microsoft Front Page Server Extension or not. Usually, LSWS will enable it when module "frontpage" has been loaded in Apache httpd.conf. However, when mod_frontpage is statically linked into the Apache binary, configuration for the FrontPage module is not in httpd.conf, and you need to enable it explicitly here. Default is "disabled".

#### Syntax

Select from radio box

### Apache Environment Variables⇑

#### Description

For shell environment variables used inside the Apache configuration file, LSWS will replace "${ENVVAR}" with the values set here. If the ENVVAR variable is not set here, "${ENVVAR}" occurrences are left unchanged.

#### Syntax

Name and value pairs, one pair per line in the form of ENV=VALUE

#### See Also

Apache Env Syntax reference

### Apache Style Configurations⇑

#### Description

Specifies Apache configuration directives (supported by LiteSpeed) that you want to use in LiteSpeed native configuration file. For example, to override the default PHP configurations (php.ini entries) the server will need four directives: "php_value", "php_flag", "php_admin_value" and "php_admin_flag".

#### Syntax

Same as Apache configuration file.