Server General
General settings for the whole server. When a path information is required, it can be either absolute or relative to $SERVER_ROOT. $SERVER_ROOT is the location where LiteSpeed server was installed. For examples, it can be your_home_dir/lsws, /opt/lsws, or etc. The server executable is under $SERVER_ROOT/bin.
 
Table of Contents
Server Process Server Name   Running As   Priority   Chroot Path   Enable chroot   Cloud Linux   Max I/O Buffer Size   Swapping Directory   Auto Restart   Auto Fix 503 Error   Graceful Restart Timeout   
Using Apache Configuration File Load Apache Configuration   Auto Reload On Changes   Apache Binary Path   Apache Configuration File   Apache Port Offset   Apache IP Offset   Apache Handled Content   Ignore Apache Modules   PHP suEXEC   PHP suEXEC Max Conn   Enable FrontPage Extension   Apache Environment Variables   
General Settings MIME File   Edit MIME File   Disable Initial Log Rotation   Server Signature   Enable IP Geolocation   Use Client IP in Header   Check For Update   Download Updates   Administrator Email   
Server Log File Name   Log Level   Debug Level   Rolling Size   Enable stderr Log   
Access Log File Name   Piped Logger   Log Format   Log Headers   Rolling Size   Keep Days   Compress Archive   
Index Files Index Files   Auto Index   Auto Index URI   
HT Access Allow Override   Access File Name   
Expire Settings Enable Expires   Expires Default   Expires By Type   
IP to Geolocation DB DB File Path   DB Cache Type   
Apache Style Configuration Apache Style Configurations   
 
Server NameGo to top
Description: A unique name for this server. You can use $HOSTNAME as value.
Running AsGo to top
Description: Specifies the user/group that the server process runs as. This value was set during the installation and to change it, you have to perform an upgrade procedure via downloaded software package.
Apply: Reinstall required.
Tips: [Security] Server should not run as a priviledged user such as "root". For security, it it is critical that the server is configured to runs with a un-privileged user/group combination that do not have login/shell access. User/Group of nobody is generally a good choice.
PriorityGo to top
Description: Specifies priority of the server process. Value ranges from -20 to 20. A lower number means higher priority.
Syntax: Integer number
Tips: [Performance] Usually, higher priority leads to slightly higher web performance on a busy server. Do not set priority higher than that of database process.
See Also: External App Priority, CGI Priority
Chroot PathGo to top
Description: [Enterprise Edition Only] Specifies the directory where the chroot environment rooted. Only "root" user can run the web server in chroot mode. Whether to run in chroot mode is controlled by Enable chroot option. The installer program will set up initial chroot environment automatically. This entry is read-only, and if you want to change it, please run the installer again.
In chroot environment, the web server and its children processes cannot access file system 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 devices files should be recreated within the chroot jail.
As the root directory is changed, you need to pay special attention to the 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: [security] Use chroot for better security.
Enable chrootGo to top
Description: [Enterprise Edition Only] Specifies whether to start the web server in chroot mode. The new root directory is set by Chroot Path during installation.
Syntax: Select from radio box
Cloud LinuxGo to top
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 SizeGo to top
Description: Specifies the maximum buffer size that is used to store request body and dynamically generated response. When this limit is reached, server will start to create temporary swapping files under Swapping Directory.
Syntax: Integer number
Tips: [Performance] Set it large enough to accommodate all concurrent requests/replies to avoid memory to disk swapping. If there are frequent i/o activity to the swap directoy, default to /tmp/lshttpd/swap/, this value is too low and LiteSpeed is swapping to disk.
Swapping DirectoryGo to top
Description: Specifies the directory where the swapping files should be placed. When server started in chroot mode, it is relative to the new root directory, otherwise it is relative to the real root.
LiteSpeed web server uses virtual memory to reduce the memory usage. Virtual memory, disk swapping, is used to store big request bodies and dynamically generated responses. The swapping directory should be placed on a disk with enough space.
Syntax: Absolute path.
Tips: [Performance] Place the swapping directory on a separate disk or increase Max I/O Buffer Size to eliminate swapping.
Auto RestartGo to top
Description: Enables service auto-recovery: automatically recreating a new server process when current server exits abnormally.
When this option is enabled, there are two instances of server process "lshttpd". The parent process monitors the child process and will create a new child process if the current one exits abnormally. However, if current child process exits normally, the parent process will exit as well. You can use the shell command lswsctrl stop or directly kill the child process; the parent process will exit assuming that you do want to shut down the server. If the server is started by a super user, the child process will change its ownership based on Running As configuration, and the parent process will not change its user/group.
Syntax: Select from radio box
Tips: [Security] Parent process's only job is to monitor the child, does not interact with the outside world, and therefore safe to execute as a super user.
  [Reliability] This feature should always be enabled for an extra layer protection against service down time.
Auto Fix 503 ErrorGo to top
Description: Specifies whether to try to fix the "503 Service Unavailable" error by restarting the web server gracefully. A "503" error is usually caused by malfunctioned 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. Feature is enabled by default.
Syntax: Select from radio box
Graceful Restart TimeoutGo to top
Description: During graceful restart, the new server instance is up, while 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
Load Apache ConfigurationGo to top
Description: Specifies whether LiteSpeed will read and use a Apache configuration file to configure the web server. Native configuration will have higher priority when there is conflict between LiteSpeed internal and Apache based configuration. When conflict arrise, conflicted Apache configuration item(s) will be ignored.
Syntax: Select from radio box
Auto Reload On ChangesGo to top
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. It works, but LSWS may restart multiple times during updating Apache configuration. A better solution is introduced in 3.3.8 release, "Using 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. Default is "No".
Syntax: Select from radio box
See Also: Apache Binary Path
Apache Binary PathGo to top
Description: Specifies the location of 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 FileGo to top
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 OffsetGo to top
Description: Specifies an offset to be added to listening TCP ports specified in Apache configuration file. This will allow LiteSpeed to run alongside with Apache to test things out instead of switching between LiteSpeed and Apache back and forth on a production server. When you are testing, it should be set to a non-zero value, the ports configured in Apache configuration plus this offset will be used by LiteSpeed; After confirming that everything works properly, you can stop Apache, set this option to 0, and then restart LiteSpeed. If 0 or the value is not set, the original port specified in Apache configuration file will be used.
Apache IP OffsetGo to top
Description: Specifies an offset to be added to listening IP address specified in Apache configuration file. This will allow LiteSpeed to run alongside with Apache to test things out. The offset is in numberic format, not in IP address format. Adding "256" will add '1' to the value of C class subnet, This option only works with IPv4 address.
Apache Handled ContentGo to top
Description: Specifies what resources will be passed to and processed by backend Apache. Resources are specified by a comma delimited list of URI, file suffixes or regular expression. A URI starts with '/'; a suffix starts with '.', a regular expression starts with "exp:" prefix. For example: "/svn/, .shtml" let Apache handle requests with URI starting with "/svn/" or ending with ".shtml". The same effect can be achieved with regular expression "exp:^/svn/, exp:\.shtml$".
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 none zero value.
Ignore Apache ModulesGo to top
Description: Specifies a list of Apache modules that should be ignored by LiteSpeed while parsing Apache configuration file. LiteSpeed will treat the listed modules as unsupported; configuration directives enclosed in <IfModule ...> ... </IfModule> will be ignored.
Syntax: comma delimited list of module names
PHP suEXECGo to top
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 script will be executed under the user specified, as well as the group unless Force GID is set. 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 used together with DirectAdmin, this value is recommended. Default is no.
Syntax: Select from radio box
PHP suEXEC Max ConnGo to top
Description: Specifies the maximum concurrent PHP requestes can be processed when run PHP script in suEXEC mode. This is the maximum number of PHP processes each user can get. Default value is 5.
Syntax: Integer number
Enable FrontPage ExtensionGo to top
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 Apache binary, configuration for frontpage module is not in httpd.conf, you need to enabled it explicitly here. Default is disabled.
Syntax: Select from radio box
Apache Environment VariablesGo to top
Description: Shell environment variables used inside Apache configuration file, LSWS will replace ${ENVVAR} with the value if "ENVVAR" is set here. if ENVVAR variable is not set here, "${ENVVAR}" are left unchanged. Apache Env Syntax reference - http://httpd.apache.org/docs/2.2/configuring.html#syntax
Syntax: Name and value pairs, one pair per line in the form of ENV=VALUE
MIME FileGo to top
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.
Syntax: File name which can be an absolute path or relative to $SERVER_ROOT.
Tips: Click the file name to edit the MIME settings
Edit MIME FileGo to top
Description: You can edit (add/modify/delete) the MIME entries. Same MIME type can have multiple suffixes.
Disable Initial Log RotationGo to top
Description: Specifies whether to disabled rotatation of server error log file at startup. Default is not to disable it.
Syntax: Select from radio box
Server SignatureGo to top
Description: Specifies whether to expose the server signature number in the response header Server. There are three options, when set to Hide Version, only LiteSpeed is shown, when set to Show Version, the detail version number is shown, [Enterprise Edition Only] when set to Hide Full Header, the whole Server header will not be set in the response header.
Syntax: Select from radio box
Tips: [Security] Set to Hide Version if you do not wish to expose the server version number.
Enable IP GeolocationGo to top
Description: [Enterprise Edition Only] Specifies whether to enable IP to 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
Use Client IP in HeaderGo to top
Description: Specifies whether to use IP address listed in "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.
Syntax: Select from drop down list
Check For UpdateGo to top
Description: Specifies how often the update agent will check for new product release. Options are "Daily", "Weekly", or "Monthly".
Syntax: Select from drop down list
Download UpdatesGo to top
Description: Specifies whether to auto-download the 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 web administration console under "Service Manager"->Version Management.
Syntax: Select from drop down list
Administrator EmailGo to top
Description: Specifies the server administrator's email address(es). It is a comma delimited list. If specified, administrators will be notified by email of important events: i.e. when the LiteSpeed service is restarted automatically due to crash detection.
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.
File NameGo to top
Description: Specifies the path of log file.
Syntax: File name which can be an absolute path or relative to $SERVER_ROOT.
Tips: [Performance] Place log file on a separate disk.
Log LevelGo to top
Description: Specifies the level of logging. Available levels are ERROR, WARNING, NOTICE, INFO and DEBUG from high to low. Only messages with higher level than current setting will be logged.
Syntax: Select from drop down list
Tips: [Performance] Unless Debug Level is set to a level other than NONE, using DEBUG log level does not have any performance impact. DEBUG log level is recommended.
See Also: Debug Level
Debug LevelGo to top
Description: Specifies the level of debugging log. If the log level is DEBUG, server will use this to control debugging level. Debug logging is disabled when 'Debug Level' is set to NONE even if Log Level is set to DEBUG. Toggle Debug Logging can be used to control debug level on a live server without restarting.
Syntax: Select from drop down list
Tips: [Performance] Important! Always set it to NONE if you do not need detailed debug logging. Active debug logging will severely degrade service performance and potentially saturate disk space in a very short timeframe. Debug logging includes detailed information for each request and response.
See Also: Log Level, Toggle Debug Logging
Rolling SizeGo to top
Description: Specifies when the current log file needs to be rolled over, also known as log rotation. When the file size is over the rollover limit, the active log file will be renamed to log_name.mm_dd_yyyy(.sequence) in the same directory and a new active log file will be created. The actual size of the rotated log file could be a little bigger. Set to 0 to disable log rotation.
Syntax: Integer number
Tips: Append "K", "M", "G" to the number for kilo-, mega- and giga- bytes
Enable stderr LogGo to top
Description: Specifies whether to write to log when receiving stderr output from any process started by the server. If enabled, stderr messages will be logged in the same directory as the server log with the fixed name "stderr.log". If disabled, all stderr output will be discarded.
Syntax: Select from radio box
Tips: Turn it on if you need to debug configured external applications: i.e. php, ruby, java, python, perl.
File NameGo to top
Description: Specifies the file name of the access log file.
Syntax: File name which can be an absolute path or relative to $SERVER_ROOT.
Tips: [Performance] Put access log file on a separate disk.
Piped LoggerGo to top
Description: Specifies the external application that will receive the access log data sent by LiteSpeed through a pipe on its STDIN stream (file handle 0). When specified, access log will be sent only to the logger application but not the access log file specified in previous entry.
Logger process is spawned in the same way as other external (CGI/FastCGI/LSAPI) processes, which means it will execute as the uid according to the virtual host's configuration of ExtApp Set UID Mode, and will never run on behalf of a privileged user.
The logger application must be defined in External Application section first. Server level access logging can only use external logger application defined at server level, while virtual host level access log can only use logger application defined at virtual host level.
The LiteSpeed server performs simple load balancing among multiple logger applications if more than one instance of logger application is configured. LiteSpeed server always attempts to keep the number of logger application as low as possible. Only when one logger application failed to process access log entries in time will the server attempt to spawn another instance of logger application.
If a logger crashes, the web server will start another instance but the log data in the stream buffer will be lost.
It is possible to lose log data if external loggers cannot keep up with the speed and volume of the log stream.
Syntax: Select from drop down list
Log FormatGo to top
Description: [Enterprise Edition Only] Specifies the log format for access log. When log format is set, it will override Log Level setting. The syntax of log format is compatible with Apache 2.0's custom log format.
Syntax: string
Log HeadersGo to top
Description: Specifies whether to log HTTP request headers: Referer, UserAgent, and Host.
Syntax: Select from checkbox
Tips: [Performance] Turn it off if you do not need these headers in the access log.
Keep DaysGo to top
Description: Specifies how many days the access log file will be kept on disk. Only rotated log file older than specified days will be deleted and the active current log file will not be touched regardless how many days' data it contains. If you do not want to auto-delete stale and very old log files, set this value to 0.
Syntax: Integer number
Compress ArchiveGo to top
Description: Specifies whether to compress rotated log files in order to save disk space.
Syntax: Select from radio box
Tips: Log files are highly compressible and this is recommended to reduce disk usage for old logs.
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 server, virtual host and context level.
Syntax: comma delimited list of name of index files
Tips: [Performance] Only set index files that you need.
Auto IndexGo to top
Description: Specifies whether to generate directory index on the fly when index files listed in Index Files are not available in a directory. This option is customizable under 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 read How to customize auto index script?
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
Auto Index URIGo to top
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 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 How to customize auto index script? 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 AccessGo to top
Description: The following directives are supported in a directory level access control file.
  • Authentication
    • AuthType
    • AuthName
    • AuthUserFile
    • AuthGroupFile
    • Require
  • Access Control
    • Allow from
    • Deny from
    • Order
  • File Info
    • AddDefaultCharset
    • AddType
    • DefaultType
    • ExpiresActive
    • ExpiresDefault
    • ExpiresByType
    • ForceType
    • Redirect
    • RedirectTemp
    • RedirectPermanent
    • RewriteEngine
    • RewriteOptions
    • RewriteBase
    • RewriteCond
    • RewriteRule
    • Satisfy
  • Other
    • <Limit>
    • <LimitExcept>
    • DirectoryIndex
    • Options
Allow OverrideGo to top
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 to files under that directory.
  • When nothing is checked, inherited default settings will be used.
  • When None is checked, access control file will be ignored.
  • When Limit is checked, directives "Order", "Allow from" and "Deny from" are allowed.
  • When Auth is checked, directives "AuthGroupFile", "AuthName", "AuthType", "AuthUserFile", "Require" are allowed.
  • When FileInfo is checked, directives "Satisfy", AddDefaultCharset", "AddType", "DefaultType", "ForceType", "ExpiresActive", "ExpiresDefault", "ExpiresByType", "Redirect", "RedirectTemp", "RedirectPermanent", "RewriteEngine", "RewriteOptions", "RewriteBase", "RewriteCond" and "RewriteRule" are allowed
  • When Indexes is checked, directive "DirectoryIndex" is allowed
  • When Options is checked, directive "Options" is allowed
Allow Override configuration is available at three levels: server, virtual host and context. If server level configuration is not checked, the controlled directives will be disabled for the whole server no matter if it is enabled or not at lower levels. If server level is enabled, virtual host will inherit same settings by default, similarly context level will inherit virtual host settings. In other words, lower level can disable a setting that is enabled by upper level, but cannot enable a setting that is disabled by upper level.
Syntax: Select from checkbox
Tips: [Performance] If there is no need for directory level configuration customization, check None.
Access File NameGo to top
Description: Specifies the name of the access control file. The file will be used only if Allow Override is enabled. Default name is .htaccess.
Syntax: file name with leading "."
Enable ExpiresGo to top
Description: Specifies whether to generate Expires header for static files. If enabled, 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 the virtual host settings and virtual host settings will override the server settings.
Syntax: Select from radio box
Expires DefaultGo to top
Description: Specifies default settings for Expires header generation. This setting is effective when Enable Expires is set. It can be overridden by Expires By Type. Do not set this default at server or virtual host level unless you have to, since it will generate Expires header for all pages. Most of time this is set at 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
After base time(A|M) plus specified seconds, it will expire. Base time "A" means the client's access time and "M" means the file's last modified time.
Expires By TypeGo to top
Description: Specifies Expires settings for individual MIME types.
Syntax: Comma delimited list of "MIME-type=A|Mseconds". After base time(A|M) plus specified seconds, it will expire. Base time "A" means the client's access time and "M" means the file's last modified time. MIME-type can accept wildcard "*", like image/*.
IP to Geolocation DBGo to top
Description: [Enterprise Edition Only] Multiple MaxMind geolocation databases can be specified here. MaxMind has the following type of DB: Country, Region, City, Organization, ISP and Netspeed. For database type of Country, Region and City, the later type of DB contains more information than that of a DB with former type, only one of those type of DB should be specified, if multiple DBs with those types are configured, the last one will be effective.
DB File PathGo to top
Description: [Enterprise Edition Only] Specifies the path to MaxMind GeoIP database.
Syntax: file path
DB Cache TypeGo to top
Description: [Enterprise Edition Only] Specifies what kind of cache mode should be used. Cache modes are: Standard, MemoryCache, CheckCache and IndexCache. MemoryCache is recommended and it is the default.
Syntax: Select from drop down list
Apache Style ConfigurationsGo to top
Description: Specifies Apache configuration directives that are supported by LiteSpeed. For example, default PHP configuration, php.ini entries, can be overridden by the server with 4 directives: "php_value", "php_flag", "php_admin_value" and "php_admin_flag".
Syntax: Same as Apache configuration file