HOW-TOs
 
Table of Contents
 
• How to increase the limit of file descriptors?Go to top
There are system level and process level file descriptor limits in UNIX like operating systems. LiteSpeed web server only uses a small number of server processes to serve all clients, and each request may need up to 4 file descriptors. Therefore, the maximum number of concurrent requests that the server can handle could be constrained by the process level file descriptor limit. It is important to set this limit high enough. Use ulimit -a to check current setting of per process file descriptor limit. You need root privilege to change this limit. You may want to put this setting in your startup scripts in order to automatically set the limit after rebooting the machine.
  • Linux kernels 2.2.x and 2.4.x:


  • Check the system level limit for open files:
       more /proc/sys/fs/file-max
    If it looks low, increase the limit by:
       echo 40000 > /proc/sys/fs/file-max
    For kernel 2.2.x, you also need:
       echo 65535 > /proc/sys/fs/inode-maxbr> Then increases the current process limit by:
       ulimit -n 10000
    Note: Normal user can use ulimit -n xxxx to change the limit of current process, at least in Kernel 2.4.x. But you need to add following lines in /etc/security/limits.conf:
       soft nofile 2048
       hard nofile 8192

  • Solaris 2.4+:


  • The following lines need to be added in /etc/system:
    * set hard limit on file descriptors: set rlim_fd_max = XXXX
    * set soft limit on file descriptors: set rlim_fd_cur = XXXX

  • FreeBSD:


  • Add the following line in /boot/loader.conf,
    set kern.maxfiles=XXXX
 
• How to setup name based virtual hosting?Go to top
With name based virtual hosting, you can host more web sites than the number of IP addresses you have. In this case, multiple domain names are pointed to same IP address. Use the following guidelines to setup name based virtual hosting.
  1. Setup DNS properly.
    Forward the domain names of your web sites to the IP address used by your web server. This is commonly done by adding an "A" name entry to the DNS zone for the website.
  2. Set up in the web administration interface:
    1. Create a virtual host for each web site.
    2. Create listeners.
      You can create one listener to listen on all local IP addresses. Or you can create multiple listeners with one listener only listening to one specific IP address.
    3. Assign virtual host mappings.
      Go to listener settings, click "Edit" on Virtual Host Mappings table. Check all virtual hosts that should be mapped, and specify the corresponding Domains.
      Note: your.domain will match both www.your.domain and your.domain. The leading "www." in the domain name will be ignored.
 
• How to setup IP based virtual hosting?Go to top
IP based virtual hosting requires at least one unique IP address for each web site. One IP address is dedicated to one virtual host. This allows you to visit a virtual host with URL like "http://192.168.0.1/index.html", and the web server will process this request using the corresponding virtual host context. If using SSL, a unique SSL certificate needs to be assigned for each IP based virtual host as well.
  1. Allocate at least one IP address for each web site you plan to host.
    TIP: You can create an IP alias to assign multiple IPs to one network adapter.
  2. Configure DNS properly.
    Assign the domain name to its corresponding IP address.
  3. Create listeners. You have two choices:
    • Create one listener that listens on all IPs and configure virtual host mappings to share one listener as above.
    • Another choice is to create one listener for each IP. Assign listener only to the corresponding virtual host with the wild card domain name *.
      Unique SSL private key and certificate can be assigned to each listener, thus each web site can use its own certificate.
 
• How to be prepared for Denial of Service (DoS) and Distributed Denial of Service (DDoS) attacks?Go to top
LiteSpeed web server is capable of reducing and even eliminating the impact of DoS and DDoS attacks at the HTTP protocol level. The following configuration will help against attacks.
  • Under server Server Tuning configuration:
    1. Set Max Request URL Length, Max Request Header Size, Max Request Body Size, Max Dynamic Response Header Size and Max Dynamic Response Body Size to a value that just above what you really need. This will help to reduce memory usage and identify bad requests quickly.
    2. Set Connection Timeout around 30;
      set Keep-Alive Timeout around 15 or less;
      set Max Keep-Alive Requests to at least 100.
      This will help to close dead connections as soon as possible and make connections available to other clients.

  • Under server Server Security configuration:
    1. Block the IPs that abuse your web server by listing them in the Access Control - Denied List.
    2. Use Per Client Connection Control to control how many concurrent connections are allowed from one IP address. Once the limit is reached, the web server will close newly accepted connections from that IP address immediately and move on to next pending connection.
      Nowadays, almost all web browsers support persistent connections (multiple requests pipelined through one connection), so the number of connections required is very small. Essentially, one connection is enough. However, some web browsers try to establish additional connections to speed up downloading.
      Therefore, allowing 4 to 10 connections from one IP is recommended. Less than that will probably affect normal web services.
      With this per IP limit, the web server can serve more unique clients. The minimum number of unique clients can be derived by using Max Connections divided by max connections per client.
    3. Enable IP level throttling:
      Set Throttle Limit greater than 0 (0 will disable throttling). The limit is rounded up to the closest boundary of 4KB/sec units.
      In this way, your limited network bandwidth will not be used up by a couple of clients with fast network connections; more clients will be served.
    4. If you server is flooded by hundreds of requests from different IPs but with same URL, you can create a General Context to block access to that URL. The Context URI should match or include that URL and Accessible is set to No.
      For example, if the server is pounded with "/foo/bar.html", then you can add context with exact URI=/foo/bar.html, or set URI=/foo/ to block all URLs that start with "/foo/".
 
• How to use GZIP compression to save network bandwidth?Go to top
LiteSpeed web server can send compressed responses for both static and dynamically generated content. You can configure it on the server GZIP Compression Tuning page through WebAdmin interface.
  • Enable Compression setting is the overall controller for both static and dynamic content.
  • When a request for a static file comes in, the web server first looks for the corresponding gzip compressed version in the same directory where the uncompressed file is located. The compressed file will be used only if it is newer and smaller than the original one. If the compressed file does not exist or out of date, the web server can create/update the gzip compressed file automatically if Auto Update Static File is turned on.
    Because compression is a pretty server intensive, the web server will only compress files with a potentially high compression rate based on following rules:
    the MIME type of the response body is text; The file size is between Min Static File Size and Max Static File Size.
  • The web server can perform run-time compression for dynamically generated content as well.
    To turn on compression for dynamic content, both Enable Dynamic Compression and Enable Compression must be set to Yes.
  • Compression Level (Static Content) and Compression Level (Dynamic Content) range from 1 (faster compression) to 9 (better compression). You should tune it based on available hardware resources such as memory and CPU cycles.
 
• How to measure web server performance?Go to top
First, Make sure your web server is tuned up for the maximum performance. There are three commonly used tools for benchmark: ApacheBench, Httperf and AutoBench.
  • Using ApacheBench:
  • ApacheBench is a command line performance-testing tool bundled with Apache httpd. It can simulate hundreds of HTTP/1.0 clients simultaneously accessing same resource on the server.
    You can simply run it with command:
    ab -n 10000 -c 100 http://localhost:8088/index.html
    or you can use keep-alive requests by
    ab -n 10000 -c 100 -k http://localhost:8088/index.html
    For detailed information, please check Apache document.

  • Using Httperf:
  • You can get httperf from http://www.hpl.hp.com/personal/David_Mosberger/httperf.html.
    Httperf uses HTTP/1.1 protocol by default and always use keep-alive requests. It has more command options, for detailed information please refer to its document.
    Here is an example:
    ./httperf --server localhost --port 8088 --uri /index.html --rate 1000 --num-conn 100 --num-call 100 --timeout 50

  • Using Autobench:
  • Autobench is a simple Perl script calling httperf that automates the benchmark process of a web server.
    You can get autobench from http://www.xenoclast.org/autobench/For detailed information, please refer to its document.
It is not recommended to run the server and testing tool on the same machine, as it does not reflect the usage in real world. And the testing tool share the same CPU with web server, you should take that into account if you do so. It is better to perform the test over a LAN using two or more computers. In order to reveal the actual performance of the web server, you need to make sure that the network and the client machines should not become a bottleneck. It is recommended to perform the test on a Gigabits LAN, or multiple switched 100Mb connections. If you only use one machine to simulate clients, make sure that it has equal or higher power than the server machine. Start the test with small files and increase the file size gradually until the network connection is saturated.
 
• How to set up an external application (Fast CGI, Web Server or Servlet Engine)?Go to top
External applications can be set up at either server level or virtual host level. The server level ones can be used by all virtual hosts.
  • Fast CGI application running on the same machine could be started by Web Server on demand. We call this kind of Fast CGI app as local Fast CGI app. Fast CGI application that is not started by Web server is referred as remote Fast CGI application, even it is running on the same machine.
    Servlet Engine has to be started manually no matter it runs on the same machine or not.

  • External applications must be configured before using. It is configured under the External Applications tab, either at server level or virtual host level.
    For all external applications, you must specify Name, Address and Max Connections.
    Name is used to reference this app internally. Address is the socket address used by the application that web server needs to connect to. Max Connections indicates the maximum concurrent connections that the external application would take. For a local fast CGI application, you also need to specify Command, Back Log, Instances and the optional Environment.
    Command is the command to start the fast CGI application, optional command parameter can be given. Back Log is the queue size of the server socket it listens to. Instances specifies the number of Fast CGI processes the server will create. Environment specifies additional environment variables for the Fast CGI app.

  • Multithreaded Fast CGI application can process multiple requests concurrently with one process. Therefore it is unnecessary to create multiple instances for that kind of Fast CGI application. But most Fast CGI is not multithreaded and one process can only process one request at the same time. In this case, multiple instances have to be created to increase the level of concurrency.
    Instances can control how many instances (processes) the web server creates. And Max Connections should be set to match the Instances.
    Some single threaded Fast CGI process can fork children processes to handle multiple requests concurrently, like PHP's Fast CGI implementation. For that kind of Fast CGI, set Instances to 1 and use Fast CGI's configuration to control how many children processes should be created. For example, PHP use a special Environment variable PHP_FCGI_CHILDREN to control it.

  • External applications cannot be used directly; they have to be configured as either Script Handler or Context handler. When configured as script handler, the web server will forward a request to the external application if the request refers to a static file with matching Suffix. When configured as context handler, web server will forward request to the external application if the request's URL matches the Context URI.
 
• How to setup PHP?Go to top
PHP is supported by LiteSpeed web server out of the box, no additional configuration is needed. Does not like Apache's mod_php which embeds PHP engine inside web server processes, LiteSpeed web server talks to standalone PHP Engine processes via Fast CGI protocol. A pre-built PHP executable with minimum features configured is installed to [lsws_home]/fcgi-bin/php. If additional features are required, you should replace it with your customized PHP executable.
  1. Build the PHP engine.
  2. Download PHP 4.3.1 (most reliable FastCGI interface) distribution package; configure it with --enable-fastcgi along with other options you need; copy the executable to [lsws_home]/fcgi-bin/ or virtual host root. The pre-built PHP executable is also configured with option '--with-config-file-path=../conf', different php.ini can be used for different PHP engine in this way, just a recommendation. The default php.ini is located at [lsws_home]/conf/php.ini.
    Note: For PHP 4.3.4, a small change should be made in source code sapi/cgi/cgi_main.c between line 858 and 862.

    	if (env_path_info) {
    		SG(request_info).request_uri = env_path_info;
    	} else {
    		SG(request_info).request_uri = env_script_name;
    	} 
    Should be taken comment out and replaced with the code in the else cluse, look like:
            SG(request_info).request_uri = env_script_name; 
    And PHP 4.3.4 has to be configured with additional option --enable-discard-path --disable-path-info-check in order to make it work properly with LiteSpeed web server, please disregard the statement about those options in the documentation and README.FastCGI, those statements are only applicable to Apache.
    After PHP is successfully built, replace the stock PHP binary coming with the package by using the following command:
    cp -f sapi/cgi/php [lsws_home]/fcgi-bin/php.

  3. Configure the PHP Fast CGI application.
  4. Normally, you do not need to change the default configuration. If you really want to know how it is configured or customized it, load WebAdmin interface, Go to External Applications tab at server level for PHP Fast CGI configuration. Fast CGI application can be defined at server or virtual host level, and the server level one is available to all virtual hosts.
    PHP engine can run on localhost or on another machine. It is recoomended to have web server start PHP engine on demand when running on localhost. There are several environment variables can be used to customize the PHP engine:

    • PHP_FCGI_CHILDREN=XX
    • This controls how many child processes the PHP engine process spawns. You should set Instances to 1 and use this environment variable to control the concurrency of PHP engine. Also set Max Connections attribute to the same value as the number of children processes.

    • PHP_FCGI_MAX_REQUESTS=XXXX
    • This controls how many requests each child process will handle before exit. It protects against memory leak inside PHP. Web server needs to reestablish a connection with a new child process. So set it as high as possible to increase the performance.

    • FCGI_WEB_SERVER_ADDRS=127.0.0.1,192.168.0.1
    • This controls who can connect to the PHP Engine over the network when TCP socket is used. Only 127.0.0.1 and 192.168.0.1 is allowed in the above example. This option is not necessory when PHP engine runs on localhost with proper Address setting. Both unix domain socket and TCP socket can be used when run on localhost, unix domain socket is preferred for better performance. If TCP socket has to be used, then let PHP only listen on the local loopback interface by setting Address to localhost:XXXX.

  5. Set script handler for ".php"
  6. A Script Handler must be configured in order to have the PHP engine handle php script after the Fast CGI is configured. The default Suffix for PHP script is set to php, Type is set to Fast CGI and Handler Name is set to the name of the PHP fast CGI application. You can specify multiple suffix in a comma-separated list like php,php4,phtml. Script Handler can be set at server level or virtual host level. Virtual host level setting overrides the server level setting for the same suffix.

 
• How to setup PHP Accelerators?Go to top
"PHP accelerator", "Turck MMCache" and "Alterntive PHP Cache (APC)" have been tested and work with LiteSpeed. "Zend accelerator" should work fine. For all accelerators, a PHP configuration file - php.ini should be changed. The default php.ini for the pre-built PHP engine is located at [lsws_home]/conf/php.ini.
Litespeed installer can enable "Turck MMCache" or "APC" with our pre-built binaries. If you want to enable, disable or switch after installation, just run [lsws_home]/admin/misc/enable_phpa.sh.
For detailed information regarding how to install the PHP Accelerators, please follow the documentation from the respective vendor.
 
• How to set up LiteSpeed Web Server as a reverse proxy server?Go to top
LiteSpeed Web Server can be used as a transparent reverse proxy server running in front of any web server or application server that supports HTTP protocol, to help improve the scalability, performance and security of the whole system.
Please set up in the WebAdmin interface according to the following steps:
  1. Define an External Applications with Type Web Server. Set Address to the IP address and port used by the backend web server.
  2. Two choices:
For example, you may want to have Apache with mod_perl to handle Perl scripts instead of running them as CGI, assuming Apache is running on the same server machine on port 8080, pointing to the same Document Root.
First, define an External Applications, set Type to Web Server, Name to ApachePerl and Address to localhost:8080.
Then define a Script Handler, set Suffix to pl, Type to Web Server and Handler Name to ApachePerl.
 
• How to setup Servlet/JSP?Go to top
LiteSpeed web server supports Servlet/JSP through AJPv13 protocol. You can choose a servlet engine as long as it is AJPv13 compatible. Please use the following guidelines to set up:
  1. Install a AJPv13 compatible servlet engine.

  2. Tomcat 3.x, 4.x and Jetty 4.x support AJPv13 protocol. The AJPv13 compatible connector of the servlet engine must be enabled. Please refer to respective documents coming with the servlet engine. Make sure the servlet engine works properly through their build-in Http Server.

  3. Make the web application files available to web server.

  4. If the servlet engine runs on a different machine, make a local copy of the web application files. Skip this step if the servlet engine runs on the same machine. Only the specific web application directory is needed, not the whole web-apps/ directory.
    If the web application is packed in a war file, you need to expand it. The WEB-INF/web.xml must exist along with the static files and JSP files. The Java class files under WEB-INF/ can be removed.

  5. Configure the servlet engine using web administration interface.

  6. Under the External Applications tab at server level or virtual host level add a servlet engine. Make sure the Address matches the AJP setting in servlet engine.

  7. Create a Java Web App Context under Context tab of the virtual host.

  8. The Context URI should match the URI used by servlet engine. Set Location to the directory of web application. Select the Servlet Engine just created.

  9. Set Script Handler for JSP.

  10. Add a Script Handler for Suffix jsp for the virtual host. Set Type to Servlet Engine and set the Handler Name to the Servlet engine just created.
 
• How to migrate from Apache?Go to top
If your web site does not depend on any apache modules that the equivalent is not currently available in LiteSpeed web server, the migration is pretty easy.
  1. It is recommended to run LiteSpeed web server parallel to Apache first.
  2. Change the user and group to the same setting as Apache by running install.sh if the server is started by root.
  3. Create a virtual host and configure it to the same settings:
  4. Restart web server and test the setup by sending same requests to both servers. After verifying that LiteSpeed web server is working properly, you can stop Apache and change the listener setting to use the TCP port that Apache used.
 
• How to generate a SSL private key?Go to top
OpenSSL tool kit is required to generate private key.
  1. Install OpenSSL if it is not installed already.
  2. Create RSA private key for your web server by using command
    openssl genrsa -out server.key 1024
    You can create a Triple-DES encrypted private key file by using
    openssl genrsa -des3 -out server.skey 1024

  3. You need to give a password (pass-phase) for the private key file. You will be prompt for the password when the private key file is used every time.
    LiteSpeed web server only support private key files without encryption. You probably think it is not safe for the private key. Well, in theory, it is not as safe as the encrypt version. But in reality, it is impossible to let user input password for the SSL keys whenever the server starts or restarts. Some web server can save the password somehow and automate the pass-phase when the server starts, but it is only as good as the machine is not compromised unless your password is hardware protected. The private key file along with the certificate file should be placed in a directory that is only readable by whom the server running as.
  4. If you generated the encrypted key file, the pass-phase can be removed with the following command:
    openssl rsa -in server.skey -out server.key
1024 in above commands is the length of the private key in bits. The bigger private key is more secure. You can create bigger private key like 2048 bit. However, if you plan to get your certificate from certificate issuer, you may have to use 1024 bit private key as it is the biggest key they can process, check with the issuer first. For more information about creating SSL private key please visit http://www.openssl.org/docs/HOWTO/keys.txt
 
• How to create self signed certificate?Go to top
Self-signed certificates can be used to secure the web administration interface. It is not recommended for a public web site. When you use a self-signed certificate, the browser will ask the user whether to accept the certificate or not as self signed certificates are not trusted by the browser.
  1. Create your private key.
  2. Create the self signed certificate with the command,
    openssl req -new -x509 -key server.key -out server.crt -days 365
    You will be asked for more information about your organization and web site. Please give correct information. You should give valid domain names of your web site when you are asked for Common Name but not any aliases. To determine the valid domain name, you can use commands such as nslookup, dig or host. For example, if the web site can be accessed via both http://foo.bar and http://www.foo.bar, usually foo.bar is the valid domain name (canonical name), www.foo.bar is an alias; foo.bar should be used for the Common Name.
 
• How to get a SSL certificate from certificate issuers?Go to top
You need to generate a certificate request from your private key and send the request to a certificate issuer, like VeriSign or Thawte. The certificate issuer will sign the request and send back the certificate. To generate a certificate request:
  1. Create your private key.
  2. Create the certificate request with command,
    openssl req -new -key server.key -out server.csr
    You will be asked for more information about your organization and web site. Please give correct information. You should give valid domain names of your web site when you are asked for Common Name but not any aliases. To determine the valid domain name, you can use commands such as nslookup, dig or host. For example, if the web site can be accessed via both http://foo.bar and http://www.foo.bar, usually foo.bar is the valid domain name (canonical name), www.foo.bar is an alias; foo.bar should be used for the Common Name.
 
• How to config SSL using the private key and certificate in LiteSpeed web server?Go to top
After you get your certificate, you can configure SSL Settings for your web server.
  1. Create a listener with Secure set to Yes. The official port for SSL is 443, but other port can be used too.
  2. Click on the newly created listener, then go to the SSL Settings. Then edit the SSL Key File and SSL Certificate.
    Give the path of the SSL private key file and certificate file in the pop-up window. Click "Finish" button to save your changes.
  3. You can specify SSL Version and Encryption Level on the same page.
  4. Set Virtual Host Mappings in listener General tab. In the pop-up window, select the Virtual Host that you want to access through this listener and input the valid Domains
  5. Click "Apply Changes" link below the banner. If the new listener uses Port number less than 1024 click Restart in Actions, otherwise just click Reload - Server.
  6. Test your SSL configuration with your browser by accessing https://your.domain:your_port/. The "s" after "http" at the beginning of the address indicates the browser to use SSL protocol.
  7. If you use a self-signed certificate, the browser will prompt you to accept the certificate. Otherwise the browser will accept the certificate automatically without bothering you.
Now you should be able to see your web pages loaded through the secured SSL connection.