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 Process

Server Name | Number of Workers | Running As | Priority | CPU Affinity | Cloud-Linux | Max I/O Buffer Size | Swapping Directory | Auto Fix 503 Error | Enable HTTP/2 Over Cleartext TCP | Graceful Restart Timeout (secs) | Statistics Output Directory | Output JSON reports

General Settings

MIME Settings | Suffixes | MIME Type | Disable Initial Log Rotation | Server Signature | Enable GeoLocation Lookup | Use Client IP in Header | Administrator Email

Index Files

Index Files | Auto Index | Auto Index URI

Expires Settings

Enable Expires | Expires Default | Expires By Type

Rewrite Control

Auto Load from .htaccess

File Upload

Temporary File Path | Temporary File Permissions | Pass Upload Data by File Path

MaxMind GeoIP DB

DB File Path | DB Name | Environment Variables

IP2Location DB

IP2Location DB File Path | DB Cache Type

Server Name

Description

A unique name for this server. If empty, server hostname will be used by default.

Number of Workers

Description

Specifies the number of httpd workers.

Syntax

Integer value between 1 and 16.

Tips

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

Running As

Description

Specifies the user/group that the server process runs as. This is set using the parameters "--with-user" and "--with-group" when running the configure command before installation. To reset these values, you must rerun the configure command and reinstall.

Apply

Reinstall required.

Tips

Server should not run as a privileged user such as "root". It is critical that the server is configured to run with a un-privileged user/group combination that does not have login/shell access. A user/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.

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 directoy, 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

Statistics Output Directory

Description

The directory where the Real-Time Stats report file will be written. The default directory is /tmp/lshttpd/ .

Syntax

Absolute path

Tips

During server operation, the .rtreport file will be written to every second. To avoid unnecessary disk writes, set this to a RAM Disk.
The .rtreport file can be used with 3rd party monitoring software to track server health.

Output JSON reports

Description

Output additional JSON formatted report files, with the .json extension, to the /tmp/lshttpd directory.

Default value: No

Syntax

Select from radio box

Example

When set to Yes, .status.json and .rtreport.json, .rtreport.2.json, etc report files will be created in addition to the usual .status and .rtreport, .rtreport.2, etc report files.

Tips

This is useful for application developers who may want to integrate LiteSpeed status and real-time reports into their applications using standard JSON processing tools built-in to most programming languages.

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 enable/disable rotation of server error log file at startup. Initial log rotation is enabled by default when using value "Not Set".

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

Enable GeoLocation Lookup

Description

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

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

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

Auto Load from .htaccess

Description

Autoload rewrite rules contained in a directory's .htaccess file when first accessing that directory if an HttpContext for that directory using the rewritefile directive does not already exist. Once initially loaded, a graceful restart must be performed for any further changes to that .htaccess file to take effect.

Virtual Host-level setting overrides Server-level setting. Default values:

Server-level: No

VH-Level: Inherit Server-level setting

Syntax

Select from radio box

File Upload

Description

Provides additional security functionality when uploading files by using a Request Body Parser to parse files to a server local directory where they can be easily scanned for malicious intent by third party modules. Request Body Parser is used when Pass Upload Data by File Path is enabled or a module calls LSIAPI’s set_parse_req_body in the LSI_HKPT_HTTP_BEGIN level. API examples provided in source package.

See Also

Hook::HTTP_BEGIN Priority

Temporary File Path

Description

Temporary directory where files being uploaded to server will be stored while request body parser is working. Default value is /tmp/lshttpd/.

Syntax

Absolute path or path starting with $SERVER_ROOT (for Server and VHost levels) or $VH_ROOT (for VHost levels).

Temporary File Permissions

Description

Determines file permissions used for files stored in temporary directory. Server level setting is global, can be overridden at VHost level.

Syntax

3 digits octet number. Default value is 666.

Pass Upload Data by File Path

Description

Specify whether or not to pass upload file data by path. If enabled, file path along with some other information is sent to backend handler instead of file itself when uploading. This saves on CPU resources and file transfer time but requires some updates to backend to implement. If disabled, file content will be transferred to backend handler, request body is still parsed to files.

Syntax

Select from radio box

Tips

Enable this to speed up file upload processing if backward compatibility is not an issue.

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