reCAPTCHA with OpenLiteSpeed
As of OpenLiteSpeed 1.5.1, reCAPTCHA is available as a method of defense against DDoS attack.
How To Enable at the Server Level
Access the WebAdmin console via
Navigate to Configuration > Server > Security > LS reCAPTCHA
Set Enable reCAPTCHA to
Yes. This is the master switch and it is required for enabling at the vhost level.
For other options, hover over the ? symbol to view detailed information about that option.
reCAPTCHA will be activated once concurrent requests count reaches the configured connection limit.
How To Enable at the Virtual Host Level
Server-level reCAPTCHA must be enabled, as it is a master switch.
Virtual-host-level connection limits will override server level.
You can enable virtual-host-level reCAPTCHA through rewrite rules or through the WebAdmin console.
Enable reCAPTCHA For Virtual Hosts Through Rewrite Rules
From the Virtual Host configuration screen, navigate to Rewrite, set Enable Rewrite to
Yes or in
.htaccess file and enter either the
[E=verifycaptcha: ACTION] directive:
[E=verifycaptcha] will always redirect to reCAPTCHA until verified.
ACTION can be
deny to return a 403 or
drop to drop the connection when
Max Tries is reached. Until Max Tries is reached, the client will be redirected to reCAPTCHA.
RewriteCond SOME-CONDITIONAL-CHECK RewriteRule .* - [E=verifycaptcha]
SOME-CONDITIONAL-CHECK would be a suspicious UA, IP address, etc.)
Enable reCAPTCHA for OpenLiteSpeed Virtual Hosts
You can also use the OpenLiteSpeed WebAdmin console to enable reCAPTCHA.
Navigate to Configuration > Virtual Hosts > Security and set LS reCAPTCHA to
Customizing the Good Bots List
Google bots are considered good bots because they help index your site. However, they cannot do their job properly without receiving the correct page. The Bot White List configuration may be used to specify bots that you may need for your site.
Here, we have configured
Edge in the Bot White List text area. Bot White List is a contains match, but regex may be used as well.
After restarting, browsers containing
Edge in the user-agent header will bypass reCAPTCHA:
The browser on the left is Microsoft Edge, the browser on the right is Chrome.}}
The Allowed Robot Hits configuration may be used to limit how many times a good bot (including Googlebot) is allowed to hit a URL before it is redirected to reCAPTCHA as well. This may be useful to prevent bad actors from bypassing reCAPTCHA using a custom user agent.
Customizing the reCAPTCHA Page
The default reCAPTCHA page is generic. If you would like to customize the page, you may do so by creating a file at
There are two script tags that are required and it is strongly recommended to avoid changing the
form and the
recaptchadiv unless you know what you are doing. There are three echos within the page itself. Those are used by the web server to customize the reCAPTCHA type and keys and specify any query string used.
Beyond those required attributes, everything else is customizable. As noted before, please ensure that you have backups of the default page and your customized page. Note that the
.shtml extension is required in order to use configured type and keys.
Apply Your Own Site Key
You can apply your own reCAPTCHA key and adjust the configuration as you like. Client verification is completely determined by Google’s reCAPTCHA service. The invisible type may display a difficult puzzle.
For server wide protection that needs to cover a lot of domains, make sure Verify the origin of reCAPTCHA solutions is unchecked. Otherwise, you may need to apply a key for each domain.
reCAPTCHA Returning 403 and Dropping Connection
If reCAPTCHA fails a few times, it will return a 403 error and then drop the connection from that IP. It is the way it works in order to block attacks. If the
invisible reCAPTCHA keeps auto-refreshing and then fails, just change the type to