ioChem-BD

Appearance

Configure ALTCHA bot protection ​

ioChem-BD includes ALTCHA protection to defend against automated bot attacks and abuse. ALTCHA is a proof-of-work challenge system that requires clients to solve a computational puzzle before accessing protected pages, effectively blocking malicious bots while remaining transparent to legitimate users.

How it works ​

The ALTCHA filter operates in two modes:

Normal mode (default)

In normal mode, ALTCHA protection is only applied to search pages (/simple-search and handle-based search URLs). The filter monitors the number of query parameters in each request. When a search request contains more parameters than the configured threshold (default: 12), the user is redirected to an ALTCHA verification page.

This approach targets automated attacks that typically send requests with many parameters to exploit search functionality or cause excessive server load.

Under Attack mode

When enabled, ALTCHA verification is required for all pages except essential static resources. This mode is useful during active bot attacks or periods of heavy abuse when broader protection is needed.

Static resources like images, CSS, JavaScript, and help files are automatically excluded to ensure normal page rendering.

Configuration ​

ALTCHA protection is configured in BASE_PATH/browse/config/dspace.cfg, where BASE_PATH is the base folder where ioChem-BD software is installed.

Available properties ​

bash
# Enable Under Attack mode (default: false)
# When true, ALTCHA check is applied to all pages, not just search pages
altcha.under.attack = false

# Maximum query parameters before triggering ALTCHA (default: 12)
# Requests exceeding this limit will require ALTCHA verification
altcha.max.query.params = 12

Enabling Under Attack mode ​

During an active attack or abuse period, you can enable Under Attack mode to require ALTCHA verification on all pages:

  1. Edit BASE_PATH/browse/config/dspace.cfg

  2. Set the property:

    bash
    altcha.under.attack = true

  3. Restart the ioChem-BD services to apply changes:

    bash
    iochembd$  BASE_PATH/apache-tomcat/bin/shutdown.sh -force
iochembd$  BASE_PATH/apache-tomcat/bin/startup.sh

  4. Monitor your server logs for the confirmation message:

    bash
    INFO  AltchaFilter - ALTCHA under attack mode is ENABLED - all pages will be checked

Disabling Under Attack mode ​

Once the attack has subsided, disable Under Attack mode to return to normal operation:

  1. Edit BASE_PATH/browse/config/dspace.cfg

  2. Set the property:

    bash
    altcha.under.attack = false

  3. Restart the ioChem-BD services

Adjusting sensitivity ​

The altcha.max.query.params property controls how sensitive the filter is in normal mode. Lower values trigger ALTCHA more frequently, while higher values are more permissive.

bash
# More sensitive - triggers on requests with more than 8 parameters
altcha.max.query.params = 8

# Less sensitive - triggers on requests with more than 20 parameters
altcha.max.query.params = 20

TIP

The maximum allowed value is 39. Values of 40 or higher are automatically reduced to 30.

Excluded paths ​

The following paths are always excluded from ALTCHA verification to ensure proper functionality:

Exact paths:

  • / - Homepage
  • /home.jsp - Homepage (JSP)
  • /index.jsp - Index page
  • /altcha-verify - ALTCHA verification endpoint
  • /altcha-challenge - ALTCHA challenge endpoint
  • /favicon.ico - Site favicon
  • /robots.txt - Search engine robots file
  • /cas-login - CAS authentication endpoint

Path prefixes (directories):

  • /static/ - Static resources (CSS, JS)
  • /image/ - Image files
  • /css/ - Stylesheets
  • /xslt/ - Chemistry visualization tools
  • /help/ - Help documentation
  • /retrieve - File retrieval endpoints
  • /mydspace - User workspace

File extensions:

  • Files ending in .js - JavaScript files

ALTCHA difficulty scaling ​

The ALTCHA challenge difficulty automatically scales based on the number of query parameters detected. Requests with more parameters receive harder challenges, making it progressively more expensive for attackers to abuse the system while keeping the challenge trivial for legitimate users.

  • Normal requests: Base difficulty (100,000 iterations)
  • Excessive parameters: Scaled difficulty up to 1,000,000 iterations
  • Under Attack mode: Maximum difficulty for all checked requests

Troubleshooting ​

Users report being asked to solve ALTCHA repeatedly

This may indicate that cookies are not being preserved between requests. Ensure that the browser accepts cookies from your ioChem-BD domain. The ALTCHA verification is stored in the user's session.

ALTCHA is not triggering during an attack

Verify that Under Attack mode is enabled in the configuration and that the service was restarted. Check the server logs for the "ALTCHA under attack mode is ENABLED" message.

Static resources are requiring ALTCHA verification

Ensure the resources are served from one of the excluded paths. If you have custom static resource directories, they may need to be added to the filter's exclusion list.

Please contact us at contact@iochem-bd.org for further assistance with ALTCHA protection configuration.