OpenLiteSpeed Web Server Users' Manual

Version 1.4 Rev. 2
Configuration

Module Configuration

Module support is available in Openlitespeed 1.3 and LSWS Enterprise 5.0 and greater. All required modules must be registered under the Server Modules Configuration tab. Module files must be located in the server root/modules folder to be available for registering. On start up, the server loads all registered modules. The server must be restarted after new modules are registered. Modules can be configured globally under the Server Module configuration tab. The configuration data is then available to the Listener and Virtual Host Module Configurations to inherit or modify.

Table of Contents

Server Modules

Module | Is Internal | Module Parameters | Enable Hooks | Hook::L4_BEGINSESSION Priority | Hook::L4_ENDSESSION Priority | Hook::L4_RECVING Priority | Hook::L4_SENDING Priority | Hook::HTTP_BEGIN Priority | Hook::RECV_REQ_HEADER Priority | Hook::URI_MAP Priority | Hook::HTTP_AUTH Priority | Hook::RECV_REQ_BODY Priority | Hook::RCVD_REQ_BODY Priority | Hook::RECV_RESP_HEADER Priority | Hook::RECV_RESP_BODY Priority | Hook::RCVD_RESP_BODY Priority | Hook::HANDLER_RESTART Priority | Hook::SEND_RESP_HEADER Priority | Hook::SEND_RESP_BODY Priority | Hook::HTTP_END Priority | Hook::MAIN_INITED Priority | Hook::MAIN_PREFORK Priority | Hook::MAIN_POSTFORK Priority | Hook::WORKER_POSTFORK Priority | Hook::WORKER_ATEXIT Priority | Hook::MAIN_ATEXIT Priority | 

Listener Modules

Module | Module Parameters | Enable Hooks | 

Virtual Host Modules

Module | Module Parameters | Enable Hooks | 

Virtual Host Module Context

URI | Module Parameters | Enable Hooks | 

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 | 

Server ModulesGo to top
Description: The Server module configuration globally defines the module configuration data. Once defined, the Listeners and Virtual Hosts have access to the modules and module configurations.

All modules that are to be processed must be registered in the Server configuration. The Server configuration also defines the default values for module parameter data. These values can be inherited or overridden by the Listener and Virtual Host configuration data.

Module priority is only defined at server level and is inherited by the Listener and Virtual Host configurations.
ModuleGo to top
Description: Name of the module. The module name will be the same as the module filename. The module file must be located under $SERVER_ROOT/modules/modulename.so in order to be loaded by the server application. The server will load the registered modules at start up. This requires that the server is restarted after new modules are registered.
Syntax: the library name of .so.
Is InternalGo to top
Description: Specify whether the module is an internal module, which is staticaly linked, instead of being an external .so library.
Syntax: Select from radio box
Module ParametersGo to top
Description: Set module parameters. The module parameters are defined by the module developer.

Set the value in the Server configuration to globally assign the default value. The user can override this setting at the Listener, Virtual Host or Context levels. If the 'Not Set' radio button is selected, it will be inherited from the upper level.
Syntax: Specified by the module interface.
Enable HooksGo to top
Description: Enables or disables the module hooks globally.
If the 'Not Set' radio button is selected and the module contains hook functions, the default is enabled. The user can override this global setting at each level.
Syntax: Select from radio box
Hook::L4_BEGINSESSION PriorityGo to top
Description: Sets the priority for this module callback within the L4 Begin Session Hook.
The L4 Begin Session Hook is triggered when the TCP/IP connection begins.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::L4_ENDSESSION PriorityGo to top
Description: Sets the priority for this module callback within the L4 End Session Hook.
The L4 End Session Hook is triggered when the TCP/IP connection ends.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::L4_RECVING PriorityGo to top
Description: Sets the priority for this module callback within the L4 Receiving Hook.
The L4 Receiving Hook is triggered when the TCP/IP connection receives data.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::L4_SENDING PriorityGo to top
Description: Sets the priority for this module callback within the L4 Sending Hook.
The L4 Sending Hook is triggered when the TCP/IP connection sends data.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::HTTP_BEGIN PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Begin Hook.
The HTTP Begin Hook is triggered when the TCP/IP connection begins an HTTP Session.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RECV_REQ_HEADER PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Receive Request Header Hook.
The HTTP Receive Request Header Hook is triggered when the web server receives a request header.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::URI_MAP PriorityGo to top
Description: Sets the priority for this module callback within the HTTP URI Map Hook.
The HTTP URI Map Hook is triggered when the web server maps a URI request to a context.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::HTTP_AUTH PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Authentication Hook.
The HTTP Authentication Hook is triggered after resource mapping and before handler processing. It occurs after HTTP built-in authentication, and can be used to perform additional authentication checking.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RECV_REQ_BODY PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Receive Request Body Hook.

The HTTP Receive Request Body Hook is triggered when the web server receives request body data.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RCVD_REQ_BODY PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Received Request Body Hook.

The HTTP Received Request Body Hook is triggered when the web server finishes receiving request body data.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RECV_RESP_HEADER PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Receive Response Header Hook.

The HTTP Receive Response Header Hook is triggered when the web server creates the response header.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RECV_RESP_BODY PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Receive Response Body Hook.

The HTTP Receive Response Body Hook is triggered when the web server backend receives the response body.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::RCVD_RESP_BODY PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Received Response Body Hook.

The HTTP Received Response Body Hook is triggered when the web server backend finishes receiving the response body.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::HANDLER_RESTART PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Handler Restart Hook.
The HTTP Handler Restart Hook is triggered when the web server needs to discard the current response and start processing from beginning, for example, when an internal redirect has been requested.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::SEND_RESP_HEADER PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Send Response Header Hook.

The HTTP Send Response Header Hook is triggered when the web server is ready to send the response header.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::SEND_RESP_BODY PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Send Response Body Hook.

The HTTP Send Response Body Hook is triggered when the web server is going to send the response body.

It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::HTTP_END PriorityGo to top
Description: Sets the priority for this module callback within the HTTP Session End Hook.

The HTTP Session End Hook is triggered when the HTTP connection has ended.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::MAIN_INITED PriorityGo to top
Description: Sets the priority for this module callback within the Main Initialized Hook.

The Main Initialized Hook is triggered once upon startup, after the server configuration and initialization is completed by the main (controller) process, and before any requests are serviced.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::MAIN_PREFORK PriorityGo to top
Description: Sets the priority for this module callback within the Main Prefork Hook.

The Main Prefork Hook is triggered by the main (controller) process immediately before a new worker process is started (forked). This is called for each worker, and may happen during system startup, or if a worker has been restarted.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::MAIN_POSTFORK PriorityGo to top
Description: Sets the priority for this module callback within the Main Postfork Hook.

The Main Postfork Hook is triggered by the main (controller) process immediately after a new worker process has been started (forked). This is called for each worker, and may happen during system startup, or if a worker has been restarted.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::WORKER_POSTFORK PriorityGo to top
Description: Sets the priority for this module callback within the Worker Postfork Hook.

The Worker Postfork Hook is triggered by a worker process after being created by the main (controller) process. Note that a corresponding Main Postfork Hook may be called by the main process either before or after this callback.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::WORKER_ATEXIT PriorityGo to top
Description: Sets the priority for this module callback within the Worker At Exit Hook.

The Worker At Exit Hook is triggered by a worker process just prior to exiting. It is the last hook point to be called by a worker.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Hook::MAIN_ATEXIT PriorityGo to top
Description: Sets the priority for this module callback within the Main At Exit Hook.

The Main At Exit Hook is triggered by the main (controller) process just prior to exiting. It is the last hook point to be called by the main process.
It will only take effect if the module has a hook point here. If it is not set, the priority will be the default value defined in the module.
Syntax: Integer value from -6000 to 6000. Lower value means higher priority.
Listener ModulesGo to top
Description: Listener module configuration data is, by default inherited from the Server module configuration. The Listener Modules are limited to the TCP/IP Layer 4 hooks.
Enable HooksGo to top
Description: Enables or disables the module hooks at the Listener level. Only if the module has TCP/IP level hooks (L4_BEGSESSION, L4_ENDSESSION, L4_RECVING, L4_SENDING), this setting will take effect.

If the 'Not Set' radio button is selected, the default will be inherited from the Server configuration. The user only needs to set it here to override the default settings.
Syntax: Select from radio box
Virtual Host ModulesGo to top
Description: Virtual Host module configuration data is, by default inherited from the Server module configuration. The Virtual Host Modules are limited to the HTTP level hooks.
Enable HooksGo to top
Description: Enables or disables the module hooks at the Virtual Host or Context level. Only if the module has HTTP level hooks, this setting will take effect.

If the 'Not Set' radio button is selected, the Virtual Host level default settings will be inherited from the Server configuration. Context level settings will be inherited from the Virtual Host level. The user only needs to set it here to override the default settings.
Syntax: Select from radio box
Virtual Host Module ContextGo to top
Description: It's a centralized place to customize module settings for virtual host contexts. Settings for a context URI will override the virtual host or the server level settings.
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
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
Extra HeadersGo to top
Description: Specifies extra response headers to be added. Multiple headers can be added, one header per line. Put "NONE" to disable headers inherited from parent content.
Syntax: "[HeaderName]: [HeaderValue]" in each line.
Example: Cache-control: no-cache, no-store
My-header: Custom header value
RealmGo to top
Description: Specifies the authorization realm for this context. When specified, a valid username 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 the current context. If 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 allowed 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.
Example: utf-8
Enable IP GeolocationGo to top
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, DB Cache Type