Skip to content

CAPTCHA

CAPTCHA is available as a method of defense against DDoS attack.

Note

CAPTCHA may also be used as a method of WordPress Brute Force Attack Protection. Please see the WP-Protect Guide for more information about that.

Note

CAPTCHA activation is dependent on the URL being accessed. It does not activate for API URLs. CAPTCHA only activates for URLs accessed by real clients.

Enable globally at the server level

!CAPTCHA protection

  1. Access the WebAdmin console via https://YOUR_SERVER_IP:7080
  2. Navigate to Configuration > Server > Security > CAPTCHA Protection
  3. Set Enable CAPTCHA to Yes. This is the master switch and it is required for both a control panel environment and an LSWS native environment. It will enable the CAPTCHA feature for all control panel Apache virtual hosts as well as LSWS native virtual hosts globally. It may be overridden at the virtual host level.
  4. Choose the CAPTCHA Type you'd like to use for your server. As of v6.4, LiteSpeed Web Server supports the following options:
    • reCAPTCHA Checkbox
    • reCAPTCHA invisible
    • hCaptcha
    • ALTCHA
    • ALTCHA (invisible)

For other options, hover over the ? symbol to view detailed information about that option.

For demonstration purposes, we will set Trigger Sensitivity to maximum (100), and CAPTCHA Type to reCAPTCHA Checkbox. You may adjust these values according to your needs. Save and restart LSWS. This sensitivity setting will be inherited by all control panel Apache virtual hosts and LSWS native virtual hosts unless overridden at the virtual host level.

After making the change described above, the appropriate directives will be added to the LiteSpeed configuration file found at /usr/local/lsws/conf/httpd_config.xml.

Alternatively, you can add them yourself. Edit the file, and place the following code after the <security>...</security> section: 

  <lsrecaptcha>
   <enabled>1</enabled>
   <type>1</type>
   <sensitivity>100</sensitivity>
  </lsrecaptcha>

You can also enable CAPTCHA on an individual virtual host that is under attack, while leaving other websites disabled.

Validation expiration time

When a visitor accesses the website, they will need to go through CAPTCHA validation. This validation protects the server against HTTP Flood and other DDoS attacks.

After passing the CAPTCHA validation, the visitor is temporarily whitelisted as long as they continue to browse the site. This makes for a better user experience. Once the visitor has been inactive for a specified time, CAPTCHA is once again enabled for that visitor's next request.

Expiration defaults to one day, but is configurable to any number of seconds via the Verification Expires field.

!CAPTCHA verification

Override/disable at the virtual host level

Assuming you have enabled CAPTCHA at the server level globally, you can override the settings at a virtual host level, but how you do so depends on which environment you are using.

Override/disable for Apache virtual hosts

You can configure vhost-level CAPTCHA via the LsRecaptcha directive in the virtual host configuration, like so, and it will override the server setting:

<IfModule LiteSpeed>
   LsRecaptcha 100
</IfModule>

LsRecaptcha has a valid range from 0 to 100.

  • 0 disables CAPTCHA for the virtual host
  • 100 turns on CAPTCHA for every request to the virtual host

You can set it to any value in between 0 and 100 if you want to set Trigger Sensitivity, but we do not recommend this.

Note

The LsRecaptcha directive cannot be used in .htaccess files.

Set max_conn to trigger CAPTCHA

In an Apache configuration file, either at the server level, or at the virtual-host level, you can add the LiteSpeed-specific configuration LsRecaptcha max_conn. The parameter value defines the maximum number of concurrent connections you can have before CAPTCHA is automatically triggered.

Example

To set the maximum number of concurrent requests to 1000, use: 

<IfModule LiteSpeed>
LsRecaptcha max_conn 1000
</IfModule>

Set the parameter value to 1 if you want to always have CAPTCHA on. Set the value to 0 to disable CAPTCHA.

LsRecaptcha max_conn used at the server level applies to all Apache virtual hosts, but the server-level setting may be overridden with a vhost-level configuration.

Override for LiteSpeed native virtual hosts

Use the LSWS WebAdmin console to override CAPTCHA in LSWS native mode.

Navigate to Configuration > Virtual Hosts > Security > CAPTCHA Protection

Set Trigger Sensitivity

Trigger Sensitivity refers to the automatic CAPTCHA sensitivity. The higher the value, the more likely CAPTCHA protection will be used. A value of 0 is equivalent to "Off" while a value of 100 is equivalent to "Always On".

Default values

Server level: 0. Virtual Host level: inherits server-level setting. Syntax: Integer value between 0 and 100.

LiteSpeed calculates Trigger Sensitivity as the percentage of your server capacity used, based on the number of active connections. CAPTCHA is activated when this formula is true:

Active connections * 100 / Max Connections > (100 - Trigger Sensitivity)

For example:

If Max Connections = 1000, Trigger Sensitivity = 20, and you currently have 900 connections, the formula would be evaluated like so:

900 * 100 / 1000 > 100 - 20

90 > 80

The result is true, so the incoming connection will be given a CAPTCHA test.

Calculating backwards, you can see that when the number of connections drops to less than 800, CAPTCHA will not be invoked.

Warning

We've discovered in real world usage that Trigger Sensitivity can be ineffective in some setups.

Here's why: Trigger Sensitivity is based on the number of active connections. But sometimes, sites have a large number of connections that are unrelated to the main page HTML. These extra connections don't result in anything that is visible to the user, but they require a high connection limit. The high connection limit negatively impacts the Trigger Sensitivity calculation, making most values under 100 behave effectively like 0.

In our experience, the headaches caused by trying to use Trigger Sensitivity under these conditions are not worth the benefits. If you have high connection limits set, we recommend two possible courses of action:

  • Go all or nothing: set the sensitivity to 100 (always on) or 0 (always off)
  • Use rewrite rules: Set sensitivity to 0 at the virtual host level, and then selectively enable CAPTCHA for certain URLs via rewrite rules, like the following example, which applies to all URLs in the /admin/ directory.

This is how it would appear if added to the Apache virtual host configuration: 

<IfModule LiteSpeed>
RewriteRule /admin/ - [E=verifycaptcha:deny]
</IfModule>

The same rule would need to look a bit different (no beginning / on admin/) if added to .htaccess, like this: 

<IfModule LiteSpeed>
RewriteRule admin/ - [E=verifycaptcha:deny]
</IfModule>

DirectAdmin configuration

Override or disable for Apache virtual hosts

You can configure virtual host reCAPTCHA with the LsRecaptcha directive in the virtual host include file, such as /usr/local/directadmin/data/users/USERNAME/domains/DOMAINNAME.cust_httpd or globally /usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.post.

<IfModule LiteSpeed>
   LsRecaptcha (0-100)
</IfModule>

The 0-100 value defines or overrides Trigger Sensitivity for the virtual host. When LsRecaptcha is set to 0, reCAPTCHA is disabled for that virtual host.

Note

The LsRecaptcha directive cannot be used in .htaccess files.

After editing the include file, rebuild Apache configuration and restart LiteSpeed Web Server:

/usr/local/directadmin/custombuild/build rewrite_confs
service lsws restart

If you need additional examples or custom configuration templates, please refer to the DirectAdmin Customizing guide.

Enable reCAPTCHA for specific URLs

To protect a specific URL path across all DirectAdmin virtual hosts, create a global include file at /usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.post with the following content:

<IfModule LiteSpeed>
RewriteRule /administrator/ - [E=verifycaptcha:deny]
</IfModule>

To apply the rule to a single virtual host, add it to /usr/local/directadmin/data/users/USERNAME/domains/DOMAINNAME.cust_httpd instead.

After editing, rebuild Apache configuration and restart LiteSpeed Web Server:

/usr/local/directadmin/custombuild/build rewrite_confs
service lsws restart

Add headers to the reCAPTCHA page

You can customize the headers on the reCAPTCHA page. To do so, add a static context with the URL /.lsrecap/, then add the desired response header for that context.

<IfModule LiteSpeed>
    <Location "/.lsrecap/">
        Header set Access-Control-Allow-Origin "*"
    </Location>
</IfModule>

This snippet cannot be added to .htaccess. It must be added to an Apache config file, or via the WebAdmin Console for an LSWS native virtual host.

Example

To add a CORS header to the reCAPTCHA page on DirectAdmin:

  • Add a <Location "/.lsrecap/"> context to /usr/local/directadmin/data/templates/custom/cust_httpd.CUSTOM.post to apply to all virtual hosts.
  • Add a <Location "/.lsrecap/"> context to /usr/local/directadmin/data/users/USERNAME/domains/DOMAINNAME.cust_httpd to apply to a single virtual host.

Troubleshooting

CAPTCHA Returns 403 and Drops Connection

If CAPTCHA fails a few times, it will return a 403 error and then drop the connection from that IP. It works this way in order to block attacks. If the reCAPTCHA invisible keeps auto-refreshing and then fails, try changing the CAPTCHA Type.