reCAPTCHA Server-Wide Protection
We are very excited to introduce a new feature to the LiteSpeed family: reCAPTCHA!
reCAPTCHA is yet another form of DDoS Server-Wide Protection that we provide in order to maintain excellent performance and reduce downtime. You can find out more about our DDoS Protection features here.
What is reCAPTCHA?
Most people use the reCAPTCHA system to detect whether a visitor is a human or a robot. When a visitor accesses a site or wants to submit a form, they must complete a challenge. The challenge makes a request to Google’s reCAPTCHA server for validation. Google responds to the challenge with a success or failure message. If successful, the site considers the visitor human, and permits form submission.
Most often, sites implement reCAPTCHA in the middle of a page, to ensure humans are the only submission sources. While this can help with data validation, by this point the visitor has already loaded the page. If the site is fully featured, it likely uses some backend technology – PHP, Ruby, Python, etc. If the site is under attack, a reCAPTCHA plugin will only help with validating results, but the server will still be bogged down with requests to the backend.
However, LiteSpeed recognizes a higher potential to be had with reCAPTCHA. reCAPTCHA provides more control when compared to most DDoS protection solutions. Good actors will be able to access the site and bad actors will be stopped, providing a powerful tool to mitigate resource usage if we avoid triggering backend engines.
The LiteSpeed Advantage
LiteSpeed provides flexibility and scalability with our reCAPTCHA implementation. For starters, our reCAPTCHA page uses SSI. It is essentially a static page. When a visitor completes the challenge, LiteSpeed adds the IP to a whitelist. Once on the whitelist, we do not need to verify the visitor again in the future. This means that the only cost to the server for visitors redirecting to our reCAPTCHA page is equivalent to serving a small resource. On a website that runs, for example, WordPress, this means handling over 10x more requests than an NGINX server with FCGI Cache, assuming the attacker is visiting a cached page.
Another advantage for LiteSpeed: reCAPTCHA doesn’t always have to be enabled. The LiteSpeed implementation uses a sensitivity scale. reCAPTCHA is activated automatically when the server undergoes heavy load.. When the load eases up, we deactivate reCAPTCHA, leaving a frictionless experience for the visitors. In addition to the sensitivity scale, you can also use rewrite rules to enable reCAPTCHA. With rewrite rules, you can better control where reCAPTCHA activates down to a page-by-page basis
How does it work?
LiteSpeed redirects non trusted visitors to a static page when the server detects high load. The static page generates a challenge for the visitor. Upon completion, the verification runs through LiteSpeed. LiteSpeed comes bundled with an executable that takes the challenge response and forwards the request to Google. If successful, Google replies with a response header that indicates success to LiteSpeed. Future visits by the same client will not be subjected to further reCAPTCHA checks.
LiteSpeed denies clients that fail by dropping the connection or returning a 403 error.
We permit access to a predefined list of “good bots”. Admins can add to this list via configuration options. In addition, good bots are not completely unlimited – if they visit the server too frequently (another configurable option), we redirect them to reCAPTCHA. This denies access in case a bad actor attempts to bypass verification by impersonating a good bot.
How to Configure LiteSpeed Products to Use reCAPTCHA:
You can enable reCAPTCHA at the Virtual Host level for LSWS Native Virtual Hosts as well as Apache Virtual Hosts (with or without a control panel).
For LSWS native, you can find the server-level reCAPTCHA settings in the Web Admin under Configuration > Server > Security after CGI Settings. At minimum, Enable reCAPTCHA and Trigger Sensitivity** should be set.
- Enable reCAPTCHA enables it server wide.
- Trigger Sensitivity** is a scale to configure the server “busy-ness” sensitivity level. Set to
0to disable reCAPTCHA, and
100to always trigger reCAPTCHA.
- Site Key & Secret Key are keys that you can generate yourself for Google’s reCAPTCHA. LiteSpeed has a default set of keys, so this is not required, but is available if you prefer to use your own set of keys. 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 Type indicates to the static page which type of reCAPTCHA to use. Currently,
reCAPTCHA v2 Invisibleand
reCAPTCHA v2 Checkboxare available. Invisible will attempt to submit a reCAPTCHA challenge without user input, but it is still possible for the user to need to complete a challenge. Checkbox requires the visitor to check a box before the challenge is issued.
- Max Tries is the number of attempts the visitor is allowed before LiteSpeed blocks the IP. Sometimes, reCAPTCHA may not show up properly for the visitor, so we recommend setting a low number greater than
3is the default.
- Allowed Robot Hits is the number of visits allowed by a bot to the server per 10 seconds. Each visit by the bot that triggers the reCAPTCHA logic (most every request that is “normal”) will increment the count. The default is
3, but if your sites have some bots that crawl the sites, we recommend that you have a higher count.
- Bot White List is a Regex-supported list of user agents to count as a “Good Bot”. Some bots such as Googlebot are considered good by default (Googlebot is unlimited if we can confirm that the visitor is in fact Googlebot.), but this is provided for a customized list, if needed.
**Trigger Sensitivity is a LSWS configuration only. The ADC (and soon, OLS) use a concurrent HTTP connection count and a concurrent HTTPS connection count.
Tips and Tricks
You can configure or override reCAPTCHA on a per-vhost basis, however, you must enable reCAPTCHA at the server level in order for it to take effect at all.
Assuming you have enabled reCAPTCHA 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
As of LSWS v5.4RC4, you can configure vhost-level reCAPTCHA via the
LsRecaptcha directive in the virtual host include configuration.
0-100 value defines or overrides Trigger Sensitivity for the virtual host. When LsRecaptcha is set to
0, it means the reCAPTCHA feature has been disabled for that virtual host.
LsRecaptcha directive cannot be used in .htaccess files.
Override for LiteSpeed Native Virtual Hosts
Use the LSWS WebAdmin console to override reCAPTCHA in LSWS native mode.
Navigate to Configuration → Virtual Hosts → Security → reCAPTCHA Protection
Advanced Configuration: Define reCAPTCHA Actions Through Rewrite Rules
If you want to further define the reCAPTCHA action as
drop, you can use one of the following rewrite rule directives in control panel virtual host document root .htaccess:
[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 Triesis 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.)
NOTE: In most cases, rewrite rules will override the default server behavior. However, in cases where trigger sensitivity is high, visitors may be sent directly to reCAPTCHA before the rewrite rules can even be processed.
Customize 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 Whitelist configuration may be used to specify bots that you may need for your site.
Here, we have configured ‘Edge’ in the Bot Whitelist text area. Bot Whitelist 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 Allowed Bot 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 the LSWS configured type and keys.
Trigger Sensitivity refers to the automatic reCAPTCHA sensitivity. The higher the value, the more likely reCAPTCHA Protection will be used. A value of
0 is equivalent to “Off” while a value of
100 is equivalent to “Always On”.
- Server level:
- Virtual Host level: inherits server-level setting.
Syntax: Integer value between
LiteSpeed calculates Trigger Sensitivity as the percentage of your server capacity used, based on the number of active connections. reCAPTCHA is activated when this formula is true:
Active connections * 100 / Max Connections > (100 – Trigger Sensitivity)
Other Good Things to Know
As mentioned, LiteSpeed only redirects non-trusted visitors. Check the Access Control Settings to configure trusted IPs.
LiteSpeed redirects to reCAPTCHA once every few seconds (up to 10 seconds), and throttles all other requests. This is to prevent triggering reCAPTCHA too often, which would result in an extremely difficult challenge.
Sometimes, the reCAPTCHA static page hangs. This may be because a resource (.css, .js) has triggered reCAPTCHA. Wait a few seconds and try again. The page should redirect properly.