Basic Configuration

This section will cover a basic LiteSpeed Web ADC configuration using a LiteSpeed Web ADC server as well as two (or more) web servers running on separate machines from one another. For simplicity, we will be assuming the following setup:

  • Two web servers
  • LiteSpeed Web ADC configured to handle HTTP traffic
  • A single site being hosted on both of the servers

Tip

If you would like to use LiteSpeed Web ADC for a different application, simply replace clusterHTTP in this guide with the appropriate cluster type (AJP,LSAPI,FCGI,MIX).

Initial Setup

To start, log into your LiteSpeed Web ADC WebAdmin Console using the IP address of your LiteSpeed Web ADC server and the port number you assigned the LiteSpeed Web ADC WebAdmin Console during installation. We will be using 192.168.0.10 as our LiteSpeed Web ADC IP address and the default port 7090 for the LiteSpeed Web ADC WebAdmin Console.

http://192.168.0.10:7090

Create a Cluster

Once you have logged in, navigate to Configuration > Clusters and click Add at the top right of Clusters List.

First, you will be asked what Type of cluster you wish to create. Choose Layer 7 and click Next.

!Choose a cluster type

On the next screen, fill in the details for the new cluster, like so:

!Define a new cluster

  • Cluster Name: clusterXYZ (or whatever you would like to call it)
  • Mode: Stateful
  • Strategy: Least Load
  • Session Extraction: check the following
    • IP Address
    • Query String
    • Cookies
    • SSL Session
  • Session ID String: phpsessid
  • Session Timeout: 600
  • Insert Tracking Cookie: Yes
  • Tracking Cookie Name: lslb_backend

Click Save at the top right.

Create a Worker Group

Now that you have a cluster defined, you can define a worker group, and add in your two web servers as nodes. For this example we will be using 192.168.0.15:81 and 192.168.0.16:82 as our two web servers and ports. Replace these values with the IP addresses and ports of your own web servers.

Click clusterXYZ to view the cluster, and click the tab for Worker Group. Then click Add, and define the worker group as follows:

!Define a new worker group

  • Name: xyzHTTP
  • Type: HTTP Proxy
  • Enabled: Yes
  • Max Connections: 20
  • Initial Request Timeout (secs): 60
  • Retry Timeout (secs): 0
  • Node Address List:(**Node1**)192.168.0.10->192.168.0.15:81, (**Node2**)192.168.0.10->192.168.0.16:82

Leave all other options set to the default values.

Note

Node Address List is a comma-separated list in the following format:

(Node_Tag)ADC_IP_Address->Destination_IP_Address:Destination_Port
If you are using IPv6, the IP must be surrounded by [].

Click Save at the top right.

Create a Virtual Host

With your cluster fully configured, and your web servers added as nodes to a worker group in said cluster, it's time to create a LiteSpeed Web ADC virtual host.

Navigate to Configuration > Virtual Hosts.

Tip

Since you will be creating our own virtual host, you no longer need the provided "Example" host. If you'd like to delete it, you can click Delete in the Action section for that host, and then click Yes to confirm.

Click Add at the top right of the Virtual Host List, and define a new virtual host, like so:

!Create a virtual host

  • Virtual Host Name: vHost-1
  • Default Cluster: clusterXYZ
  • Configure File: $SERVER_ROOT/conf/vhost-1.xml

Click Save at the top right.

Create a Listener

Now that we have a LiteSpeed Web ADC virtual host configured, the final step is to set a listener for that virtual host.

Navigate to Configuration > Listeners

Tip

You may already have a "Default" listener configured and mapped to the "Example" virtual host. If this is the case, you don't need to Add a new listener. You can simply Edit the Default listener and delete it's virtual host mapping to Example.

Click Add at the top right of the Listeners list.

Select Type HTTP (Layer 7) and click Next. Create a new listener with the following values:

!Add a listener

  • Listener Name - Default
  • Port - 80
  • Secure - No

Leave the rest of the settings at their default values, and click Save at the top right.

You will be sent back to the listener list. Click Default. to view the listener we just added.

Since we created our own LiteSpeed Web ADC Virtual host earlier (vHost-1), we can now add a new mapping. Click Add in the Virtual Host Mappings section, and create a mapping with the following values:

!Map a vhost to the listener

  • Virtual Host: vHost-1
  • Domains: *.your-domain-name.com

Click Save at the top right.

Apply all of the changes with a graceful restart. Navigate to Actions > Graceful Restart and click the OK button when asked Are you sure you want to restart server?.

Your LiteSpeed Web ADC should now be working and ready to handle all incoming HTTP traffic to your specified port/site!

Testing

Below are two methods of testing that LiteSpeed Web ADC is configured correctly and working. We will again be assuming you have two web servers with LiteSpeed Web ADC handling HTTP requests to a web site hosted on both of these servers.

Tip

These tests can both be modified to test other applications of LiteSpeed Web ADC.

For both tests: Run your servers in an isolated environment (no outside traffic), and make a small but noticeable change to the home page on one of your web servers. This is done so that you can easily tell which web server fills the request.

Test 1: Disable a Server

Aside from balancing your servers' traffic to avoid a crash, one of the main features of a load balancer is to appropriately redirect traffic to an available server if another server should experience a failure. With two servers running this is an easy thing to check.

To begin, visit your site through a browser. Make note of which server you are being directed to by noticing the presence or absence of the small change you made earlier. We will call this server "Server 1". If your Mode is set to Stateful under Load Balancer Definition in Configuration > Clusters > clusterXYZ (as it will be if you followed the tutorial above), then Server 1 will be the preferred server for LiteSpeed Web ADC to direct your IP address to. This is known as "Session Affinity".

Now that we know which server you are being directed to, either stop Server 1 or change Server 1's port to a number LiteSpeed Web ADC is not aware of, and restart it. If everything is working correctly, the next time you attempt to visit your site, LiteSpeed Web ADC will instead redirect your request to Server 2, which you can again confirm with respect to the small change made earlier.

Test 2: Round Robin

From the LiteSpeed Web ADC WebAdmin Console, navigate to Configuration > Clusters. Select clusterXYZ, or whatever cluster you are using to direct HTTP traffic. Click Edit at the top right of the Load Balancer Definition section.

Change Mode to Stateless and Strategy to Round Robin.

!Edit load balancer definition

Click Save at the top right.

By choosing Stateless, you have told LiteSpeed Web ADC to ignore "Session Affinity" for this cluster. Meaning that you are equally likely to be sent to Server 1 or Server 2 on an HTTP request for your site. By choosing Round Robin, you have told LiteSpeed Web ADC to rotate back and forth between Server 1 and Server 2 when receiving HTTP requests for your site.

Perform a Graceful Restart to have the new definition take effect.

Tip

Because of possible browser caching, this next part is best done through the terminal.

Use the following terminal command to request your web page. For this example our domain name is your-domain-name.com. Replace this with your own domain name or the IP address and port of your LSLB server.

curl -i your-domain-name.com

or

curl -i 192.168.0.10:80

Run this command a few times to check if LiteSpeed Web ADC is correctly swapping back and forth between Server 1 and Server 2 by checking for the small change made earlier. The output should be similar to Server 1, then Server 2, then Server 1, then Server 2, and so on.

Note

It is recommended to set Mode and Strategy back to your previous settings when done performing this test. The default settings are Stateful and Least Load respectively.

QUIC

You can use QUIC on LiteSpeed Web ADC if the following are true:

  • QUIC is enabled in the WebAdmin Console (it is enabled by default)
  • The browser supports QUIC and has QUIC enabled
  • You are not using a self-signed certificate
  • You are not using a proxy front end like CloudFlare

Create Secure Listener

  • Navigate to WebAdmin Console > Configuration > Listeners and press the Add button.
  • Choose HTTP (Layer 7) then press the Next button.
  • Set Listener Name to LS-443 or your choice of name.
  • Set Port to 443.
  • Set Secure to Yes.
  • Press the Save button.

Configure SSL

  • Back at the Server Listeners list, select LS-443.
  • Select the SSL tab.
  • Click Edit in the SSL Private Key & Certificate section.
  • Set Private Key File, Certificate File and CA Certificate File to your certificate file location.
  • Press the Save button.

Enable QUIC

QUIC is enabled in Web ADC by default. If it has been turned off, and you need to enable it manually, this is how:

  • While still viewing LS-443, scroll down to Security Features and click Edit
  • Set Allow QUIC to Yes.
  • Press the Save button.

!Enable QUIC

Configure Firewall

QUIC (Quick UDP Internet Connections) runs a stream-multiplexing protocol over Transport Layer Security (TLS) on top of UDP instead of TCP. Be sure you've enabled the port with both TCP and UDP.

How to verify QUIC is enabled

You can test your own site, or any site on the Internet, with the free HTTP/3 Check tool. Enter a URL, and HTTP/3 Check will tell you whether QUIC or HTTP/3 are supported by that site. Detailed connection information, including HTTP header and QLOG output are provided as well. (Please check out our video tutorial, if needed.)

Another option is the HTTP/2 and SPDY indicator Chrome extension. It displays a lightning bolt in the Chrome toolbar. Blue indicates HTTP/2 is enabled. While the extension is not actually designed to show HTTP/3 use, you will see a green lightning bolt when HTTP/3 is in use. Hover over the lightning bolt to see a more detailed list of protocols.

High Availability

LiteSpeed Web ADC's High Availability (HA) configuration provides a failover setup for two ADC Nodes. When one node is temporarily unavailable, the other one will automatically detect and take over the traffic.

Two ADC nodes will need to be set up individually.

Once they are set up, LiteSpeed Web ADC HA will use Keepalived to detect the failover.

We will set up two nodes, using the following values as an example:

  • Node1: 10.10.30.96
  • Node2: 10.10.30.97
  • Virtual IP: 10.10.31.31

Install and Configure Keepalived

Before you configure ADC HA, You should install Keepalived on both Node1 and Node2.

On CentOS:

yum install keepalived

On Ubuntu/Debian:

apt-get install keepalived

Start Keepalived:

service keepalived start

You also need to set up autorestart during the system reboot:

systemctl enable keepalived
or
chkconfig keepalived on

The Keepalived configuration file is located at /etc/keepalived/keepalived.conf, but you should not edit this configuration file directly. Instead, you should use ADC Web Admin GUI > HA config to add or configure a Virtual IP. If you manually add a VIP to Keepalived config, it won't be picked up by ADC HA. The VIP configuration under the ADC's HA tab is a GUI to update the Keepalived config file.

Tip

You should always use the WebAdmin GUI to manage VIPs if you want to see them in the status.

Configure High Availability

We assume you have configured the listener, virtual host and backend clusterHTTP on both Node1 and Node2 seperately.

Tip

With IP failover, we recommend listening on *:<port>, instead of individual <IP>:<port>.

Node1

Log in to Node1's ADC Web Admin Console. This is our example configuration:

!Node1 example configuration

  • Server Address: 10.10.30.96:11122
  • Replication Cluster: 10.10.30.96:11122,10.10.30.97:11122
  • Heart Beat Interval (secs): 10
  • Heart Beat Timeout (secs): 30
  • Is Gzip Stream: Yes
  • Enable incremental sync: Yes
  • Is File Cache Enabled: Yes
  • File Cache Server Address: 10.10.30.96:1447

Click Add in HA Interfaces to add a Virtual IP, like so:

!Add a VIP for Node1

  • Interface ID: 5
  • Virtual IP: 10.10.31.31
  • VIP ID: 110
  • VIP Token: test123
  • NIC Name: ens160
  • Priority: 170

After a VIP has been added through the GUI, the configuration will be added to the Keepalived configuration at /etc/keepalived/keepalived.conf, and it will look like this:

###### start of VI_5 ######
vrrp_instance VI_5 {
  state BACKUP
  interface ens160
  lvs_sync_daemon_inteface ens160
  garp_master_delay 2
  virtual_router_id 110
  priority 170
  advert_int 1
  authentication {
      auth_type PASS
      auth_pass test123
  }
  virtual_ipaddress {
      10.10.31.31
  }
}
###### end of VI_5 ######

Node2

Login to Node2's, ADC Web Admin Console. This is our example configuration:

  • Server Address: 10.10.30.97:11122
  • Replication Cluster: 10.10.30.96:11122,10.10.30.97:11122
  • Heart Beat Interval (secs): 10
  • Heart Beat Timeout (secs): 30
  • Is Gzip Stream: Yes
  • Enable incremental sync: Yes
  • Is File Cache Enabled: Yes
  • File Cache Server Address: 10.10.30.97:1447

Click Add in HA Interfaces to add a Virtual IP, like so:

  • Interface ID: 5
  • Virtual IP: 10.10.31.31
  • VIP ID: 110
  • VIP Token: test123
  • NIC Name: ens160
  • Priority: 150

After a VIP has been added through the GUI, the configuration will be added to the Keepalived configuration at /etc/keepalived/keepalived.conf, and it will look like this:

###### start of VI_5 ######
vrrp_instance VI_5 {
  state BACKUP
  interface ens160
  lvs_sync_daemon_inteface ens160
  garp_master_delay 2
  virtual_router_id 110
  priority 150
  advert_int 1
  authentication {
      auth_type PASS
      auth_pass test123
  }
  virtual_ipaddress {
      10.10.31.31
  }
}
###### end of VI_5 ######

Notes

  1. Node1 virtual_router_id should be the same as Node2
  2. state MASTER/BACKUP doesn't really matter, since the higher priority one will always be MASTER.

Test IP Failover

IP failover is completely managed by Keepalived. The ADC just adds a configuration management interface. IP failover only happens when one server is completely down. The other server will then take over the IP. Shuting down LS ADC won't trigger an IP failover.

It's a good idea to test IP failover. Here's how:

Check Master Node

The master node is currently Node1, 10.10.30.96. Run ip a, and you should get similar output to this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
  inet 127.0.0.1/8 scope host lo
     valid_lft forever preferred_lft forever
  inet6 ::1/128 scope host 
     valid_lft forever preferred_lft forever
2: ens160: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
  link/ether 00:0c:29:c4:09:80 brd ff:ff:ff:ff:ff:ff
  inet 10.10.30.96/16 brd 10.10.255.255 scope global ens160
     valid_lft forever preferred_lft forever
  inet 10.10.31.31/32 scope global ens160
     valid_lft forever preferred_lft forever
  inet6 fe80::20c:29ff:fec4:980/64 scope link 
     valid_lft forever preferred_lft forever

You can see the VIP 10.10.31.31.

Check Backup Node

The backup node is currently Node2, 10.10.30.97. Run ip a, and you should get similar output to this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
  inet 127.0.0.1/8 scope host lo
     valid_lft forever preferred_lft forever
  inet6 ::1/128 scope host 
     valid_lft forever preferred_lft forever
2: ens160: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
  link/ether 00:0c:29:95:67:6d brd ff:ff:ff:ff:ff:ff
  inet 10.10.30.97/16 brd 10.10.255.255 scope global ens160
     valid_lft forever preferred_lft forever
  inet6 fe80::20c:29ff:fe95:676d/64 scope link 
     valid_lft forever preferred_lft forever

You don't see VIP on Node2, because VIP is active on Node1. This is how it should work.

Shut Down Master

If you shut down the master (Node1), then the VIP 10.10.31.31 should be automatically migrated to the backup server (Node2). You can check ip a after shutting down the master server:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000                                                                            
  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00                                                                                                              
  inet 127.0.0.1/8 scope host lo                                                                                                                                     
     valid_lft forever preferred_lft forever
  inet6 ::1/128 scope host 
     valid_lft forever preferred_lft forever
2: ens160: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
  link/ether 00:0c:29:95:67:6d brd ff:ff:ff:ff:ff:ff
  inet 10.10.30.97/16 brd 10.10.255.255 scope global ens160
     valid_lft forever preferred_lft forever
  inet 10.10.31.31/32 scope global ens160
     valid_lft forever preferred_lft forever
  inet6 fe80::20c:29ff:fe95:676d/64 scope link 
     valid_lft forever preferred_lft forever

As you can see, VIP 10.10.31.31 is assigned to Node2 now.

Fixing Out of Sync Replication

YOu can check HA status by clicking the Status tab in the HA section. Sometimes you may see that replication is out of sync.

There are a few possible causes:

  1. If one ADC instance is down, the replication will be out of sync, That's expected. The ADC will try to restore synchronization in a short time.
  2. Make sure Node1 and Node2 are configured the same way. If they are configured differently, you cannot expect HA/Replication to work.

Testing VIP

Try accessing 10.10.31.31 (VIP) from the browser. You will see the backend server page. Disable one node, and you should still see the webpage. Check ADC HA status. The live node will become the Master when the other one is down.

Syncing Cache

Cache purge is automatically synced between two HA nodes. When a node receives a purge request, the cached file will not be deleted immediately. It will be regenerated when a new request for that URL is received.

Further cache replication can be enabled or disabled as desired. To enable cache replication, navigate to ADC WebAdmin Console > Configuration > HA and set Enable Replication for Cached Data to Yes.

!Enable cache replication

When replication is enabled, caches are synced between the HA ADC nodes. When the backend LiteSpeed Cache plugin sends a cache request to the live ADC, that request will be synced with the nodes.

Notes

  1. Replication happens only between two front end High Availability ADCs, and not backend cluster web servers. Avoid caching on the cluster-server-node layer, as cached data within web server nodes will not be purged properly and will no longer be synchronized. In a clustered environment, LSCache data should only be maintained at the ADC layer.
  2. Only LSCache data is synced between two HA ADCs. Configuration is not synced. Therefore, the ADCs must be manually configured independently to serve the same sites.

PageSpeed

Warning

We no longer recommend using PageSpeed. The module has not been maintained for some time now, and as such, it may cause stability issues.

Server Level Configuration

Log into LiteSpeed ADC WebAdmin Console, Configuration > Server > PageSpeed

!Configure PageSpeed

Load Module: This is the master switch, and must be enabled to activate PageSpeed, otherwise none of following settings will take effect.

Enable PageSpeed: This can be set either at the server level or vhost level. Vhost level settings will override those at the server level.

PageSpeed Settings: This will vary according to your usage, but we will use the following as an example:

    pagespeed FileCachePath /tmp/lshttpd/pagespeed;
    pagespeed RewriteLevel CoreFilters;

Note

Please be aware, improper settings may break the content of sites or some static files like JS/CSS.

Vhost Level Configuration

In this example we've used the same settings as we did at the server level.

!Configure VHost

After configuration is complete, run a graceful restart to apply the settings.

Verify

!Response Header Before

We can verify PageSpeed by checking the HTTP response header. Before PageSPeed is activated, in this example, the page size is 254 KB, wwith 17 requests.

!Response Header After

After PageSpeed is activated, we can see that the page size has been reduced to 196 KB and requests are down to 14 requests. Also there is now an x-ls-pagespeed header.

GeoIP

There are two location database settings in LiteSpeed Web ADC's WebAdmin Console: IP to GeoLocation DB for the MaxMind legacy database and the MaxMind GeoIP2 database, and IP2Location DB for the IP2Location database.

Tip

We will explain how to set up both types of Geolocation database, but you will not need to use both. You can only use one location database at a time, so choose your favorite and stick with that one.

Setting up and enabling GeoIP on LiteSpeed ADC involves choosing a database, downloading and installing the database to a directory, setting up the database path in ADC Admin, enabling geolocation lookup, setting rewrite rules, and finally, running some tests.

!

Set Enable GeoLocation Lookup to Yes. This must be set, if you want Geolocation to work on Web ADC.

Download and Configure

Choose your favorite database: MaxMind GeoIP2, MaxMind Legacy Database, or IP2location database. Then, set up the correct database path in the appropriate section in the ADC WebAdmin Console, as described.

MaxMind GeoIP2 Database

Note

If you have switched from the MaxMind GeoIP2 service to an IP2location database, many of your PHP scripts may still make use of the GEOIP_* environment variables $SERVER['GEOIP_COUTRY_CODE'] and $SERVER['GEOIP_ADDR']. Because it may be impossible to remove these environment variables, all recent versions of LiteSpeed Web ADC automatically map GEOIP_COUNTRY_CODE to IP2LOCATION_COUNTRY_SHORT and GEOIP_ADDR to IP2LOCATION_ADDR in order to address this problem.

Download

Register for a MaxMind account and obtain a license key, then download a GeoLite2 database.

After download, you can unzip it:

tar -zxvf GeoLite2-Country_00000000.tar.gz

(Be sure to replace 00000000 with the correct digits in the filename of your downloaded DB.)

Move the unzipped file GeoLite2-Country.mmdb to /usr/share/GeoIP/GeoLite2-Country.mmdb.

Configure

Navigate to Configuration > Server > General, and click Add in the MaxMind GeoIP DB section. Set DB File Path to the database path. Then set DB Name to COUNTRY_DB or CITY_DB. Your choice of DB name is important: you must use COUNTRY_DB for a country database, and CITY_DB for a city database. These two fields are mandatory and cannot be left blank.

Environment Variables and Notes are optional.

The full power of GeoIP2 depends on the use of environment variables in the LiteSpeed configuration. The format used is designed to be as similar as possible to the Apache mod_maxminddb environment described here, specifically for the MaxMindDBEnv variable. Each environment variable is specified in the environment text box as one line:

  • The name of the environment variable that will be exported, for example GEOIP_COUNTRY_NAME
  • A space
  • The logical name of the environment variable, which consists of:
    • The name of the database as specified in the DB Name field as the prefix. For example, COUNTRY_DB
    • A forward slash /
    • The name of the field as displayed in mmdblookup. For example: country/names/en

Thus the default generates GEOIP_COUNTRY_NAME COUNTRY_DB/country/names/en.

If you wanted the country code to be displayed in Spanish, you would enter the environment variable GEOIP_COUNTRY_NAME COUNTRY_DB/country/names/es.

Note that if a variable is used by multiple databases (for example, the default GEOIP_COUNTRY_NAME), you need to override the value in the last database specified (or all databases in case they get reordered, just to be safe).

Note that subdivisions is an array and must be referenced by index (usually 0 or 1).

The default environment variables vary by database and are designed to be as similar to the legacy GeoIP environment variables as possible.

Our default list is:

  • GEOIP_COUNTRY_CODE: /country/iso_code
  • GEOIP_CONTINENT_CODE: /continent/code
  • GEOIP_REGION: /subdivisions/0/iso_code
  • GEOIP_METRO_CODE: /location/metro_code
  • GEOIP_LATITUDE: /location/latitude
  • GEOIP_LONGITUDE: /location/longitude
  • GEOIP_POSTAL_CODE: /postal/code
  • GEOIP_CITY: /city/names/en

You can customize the configuration to add the environment variables you want as describe above.

Example

You can create a MyTest_COUNTRY_CODE variable, like so:

MyTest_COUNTRY_CODE CITY_DB/country/iso_code
!

If you do set your own variables, please be careful to use the correct entry names. For example, GEOIP_REGION_NAME CITY_DB/subdivisions/0/name/en would be incorrect, as name should be names.

Example

You can create a MyTest2_COUNTRY_CODE variable by using a defined COUNTRY DB name COUNTRY_DB_20190402 with a country database.

MyTest2_COUNTRY_CODE COUNTRY_DB_20190402/country/iso_code
!

Example

You can define a list of variables, one per line, like so:

HTTP_GEOIP_CITY CITY_DB/city/names/en
HTTP_GEOIP_POSTAL_CODE CITY_DB/postal/code
HTTP_GEOIP_CITY_CONTINENT_CODE CITY_DB/continent/code
HTTP_GEOIP_CITY_COUNTRY_CODE CITY_DB/country/iso_code
HTTP_GEOIP_CITY_COUNTRY_NAME CITY_DB/country/names/en
HTTP_GEOIP_REGION CITY_DB/subdivisions/0/iso_code
HTTP_GEOIP_LATITUDE CITY_DB/location/latitude
HTTP_GEOIP_LONGITUDE CITY_DB/location/longitude
!

IP2Location Database

Download the IP2Location Database from the IP2Location website.

Click Edit in the IP2Location DB section, and set IP2Location DB File Path to the location of the downloaded database.

Testing

This example test case redirects all US IPs to the /en/ site for the example.com virtual host.

Navigate to Virtual Hosts > example.com > Rewrite Control > Rewrite, and set Enable Rewrite to Yes.

Then add the following to Rewrite Rules:

RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^US$
RewriteRule ^.*$ https://example.com/en [R,L]
!

Visit example.com through a US IP, and it should redirect to https://example.com/en successfully.

Visiting example.com through a non-US IP should not redirect at all.

Custom Headers

You can send extra custom headers to the backend server.

There are standard headers for Reverse Proxy HTTPS traffic, such as X-Forwarded-For and X-Forwarded-Proto. LiteSpeed ADC adds these request headers in order to pass information to the origin backend web servers.

Tip

Be careful when using these headers on the origin server, since they will contain more than one (comma-separated) value if the original request already contains one of these headers.

If you need to specify custom request headers to be added to the forwarded request, you can do so, in the manner of Apache's mod_headers RequestHeader directive.

Navigate to Configuration > Clusters > [example cluster] > Session Management and click Edit. Set Forwarded By Header to the custom header value you wish to add to all proxy requests that are made to the backend server.

Example

X-Forwarded-By

Advanced Reverse Proxy

We've covered how to set up a simple reverse proxy, but it requires the request URI to be the same in the frontend as in the backend, otherwise a 404 Not Found Error would be returned.

It is possible to set up a more advanced reverse proxy, which would allow you to proxy a frontend URI to a different backend URI, and mask the URI path.

Preparation

We will use 3 test servers as examples with the following domains:

  • adc.litespeed.dev
  • adc2.litespeed.dev
  • adc3.litespeed.dev

adc.litespeed.dev will be the main server and other two are served for different backends.

With each server, we create a PHP file with the following code:

<?php
echo "SCRIPT_FILENAME: ".$_SERVER["SCRIPT_FILENAME"]."<br>";
echo "SERVER ADDR: ".$_SERVER["SERVER_ADDR"]."<br>";
echo "HTTP_HOST: ".$_SERVER['HTTP_HOST']."<br>";
!

If we run this PHP file on each server, we it will show us which backend we are requesting with.

!

We also need to create three cluster backends that match each domain to its real IP, because ADC will redirect/proxy the request to a cluster worker to do the proxy.

We have two methods to do this, via RewriteRule or Context:

RewriteRules

In the ADC WebAdmin Virtual Host > Rewrite tab, enable rewrite rules and add the following rule:

RewriteRule ^(.*)$ http://adc2/$1 [P,E=Proxy-Host:adc2.litespeed.dev]

!

In this example, adc2 is the cluster name, and adc2.litespeed.dev is the backend domain. You may get 404 errors if the hostname doesn't match in the backend.

Save your changes, restart the ADC, and visit adc.litespeed.dev again. You will see it is now proxied to adc2.litespeed.dev.

!

Now that you know that works, you can use RewriteCond and RewriteRule to further customize the scenarios you expect to encounter.

Example

To proxy a request URI that contains the query string adc2 to adc2.litespeed.dev, and on where the URI contains the query string adc3 to adc3.litespeed.dev, we would use the following ruleset:

RewriteCond %{QUERY_STRING} adc2
RewriteRule ^(.*)$ http://adc2/$1 [P,E=Proxy-Host:adc2.litespeed.dev,L]

RewriteCond %{QUERY_STRING} adc3
RewriteRule ^(.*)$ http://adc3/$1 [P,E=Proxy-Host:adc3.litespeed.dev,L]

!

You will find that visits to adc.litespeed.dev/index.php?adc2 are proxied to adc2.litespeed.dev and visits to adc.litespeed.dev/index.php?adc3 are proxied to adc3.litespeed.dev.

We can also rewrite the URI path where we will create a file new-uri.php with same PHP code

Example

This time we will rewrite adc.litespeed.dev/index.php?rewrite to adc3.litespeed.dev/new-uri.php with the following ruleset:

RewriteCond %{QUERY_STRING} rewrite
RewriteRule ^(.*)$ http://adc3/new-uri.php$1 [P,E=Proxy-Host:adc3.litespeed.dev]
!

Contexts

This works pretty much the same as with the previous rewrite rules, so we will use the same examples as before.

To proxy adc.litespeed.dev/index.php to adc2.litespeed.dev/index.php configure the context like so:

!

  • URI: /index.php
  • Cluster: adc2
  • Enable Rewrite: Yes
  • Rewrite Rules:
    RewriteRule ^(.*) - [E=Proxy-Host:adc2.litespeed.dev]
    

You need to use Rewrite Rules to alter the hostname, otherwise you will have 404 errors.

Note

Contexts have a dedicated cluster and do not support query strings, so you may not be able to proxy to different backends by query string like the earlier rewrite rule examples.

Example

Here we will proxy adc.litespeed.dev/adc3 to adc3.litespeed.dev/new-uri.php with the following settings:

!

  • URI: /adc3
  • Cluster: adc3
  • Enable Rewrite: Yes
  • Rewrite Rules:
    RewriteRule ^(.*)$ http://adc3/new-uri.php$1 [P,E=Proxy-Host:adc3.litespeed.dev]
    

Turning On the Debug Log

To turn on the Web ADC Debug Log, you would follow the exact same steps that are laid-out here for LiteSpeed Web Server.


Last update: November 19, 2020