Advanced ban

An advanced IP address banning module that replaces Drupal core's Ban module with support for IP ranges, expiry dates, ban reasons, and protected IPs.

advban

4,292 sites

drupal.org

gui api utility

security ip ban access control spam prevention firewall ip blocking ip range blacklist

Drupal 8 Drupal 9 Drupal 10 Drupal 11 Drupal 12

Install

Drupal 12, 11, 10 v8.x-1.9

composer require 'drupal/advban:8.x-1.9'

Drupal 9, 8 v8.x-1.5

composer require 'drupal/advban:8.x-1.5'

Overview

Advanced Ban is a comprehensive replacement for Drupal's core Ban module, providing enhanced IP address management capabilities for site administrators. The module allows banning individual IP addresses as well as IPv4 IP ranges, with configurable expiration dates that automatically unban IPs after a specified duration.

Unlike the core Ban module, Advanced Ban supports ban reasons to document why an IP was blocked, a protected IP list that overrides bans (useful for whitelisting trusted services like Googlebot), and customizable ban messages shown to blocked visitors. The module includes HTTP middleware that intercepts requests before page caching, ensuring banned users never receive cached content.

Upon installation, the module automatically migrates existing banned IPs from the core Ban module. Expired bans are automatically cleaned up via cron, and administrators have full control over bulk deletion with filters for simple/range IPs and expired/active bans.

Features

Ban individual IP addresses with validation to prevent banning reserved addresses
Ban IPv4 address ranges by specifying start and end IP addresses
Configurable ban expiry durations using PHP strtotime format (e.g., +1 hour, +1 day, +1 week)
Automatic unblocking of expired IP bans via cron
Ban reason field to document why an IP was banned
Protected IP whitelist supporting individual IPs, CIDR notation, and domain names
HTTP middleware that blocks banned IPs before page caching with priority 250
Customizable ban message text with variable placeholders for IP and expiry date
Search functionality to find banned IPs by IP address or ban reason
Bulk delete functionality with filters for simple/range IPs and expired/not-expired status
Pagination support for the banned IP list
Automatic migration of banned IPs from core Ban module on installation
Protected IPs support comments (lines starting with #) for documentation

Use Cases

Blocking spam bot IP ranges

Use the IP range ban feature to block entire subnets of known spam sources. Enter the start and end IP of the range, add a descriptive reason like 'Spam network', and set an appropriate expiry duration. The module will block all IPs within the range from accessing the site.

Temporary bans for abusive users

When dealing with abusive users who haven't crossed the line for a permanent ban, use the expiry duration feature. Ban their IP with a duration like '+1 week' or '+1 month'. The ban will automatically be lifted when the duration expires via cron, with no manual intervention needed.

Protecting legitimate bots and services

Add trusted services to the Protected IPs list to ensure they're never accidentally banned. Use CIDR notation for IP ranges (e.g., '66.249.64.0/19' for Googlebot), domain names (e.g., 'googlebot.com'), or individual IPs. Add comments with # to document each entry.

Migrating from core Ban module

Simply enable Advanced Ban after core Ban module - the installation will automatically migrate all existing banned IPs with the reason 'Migrated from Ban'. You can then enhance these entries with expiry dates and more detailed reasons using the edit function.

Auditing and searching banned IPs

Use the Search page to find specific banned IPs or search by reason text. This is useful for auditing bans, finding related entries (e.g., all IPs banned for 'brute force attack'), or verifying if a specific IP is banned.

Bulk cleanup of expired bans

While cron automatically removes expired bans, you can use the Delete All page to immediately clean up. Select 'Delete expired IP only' to remove all expired entries, or combine filters to delete only expired range IPs, for example.

Tips

Use CIDR notation in Protected IPs for efficient subnet whitelisting (e.g., '192.168.1.0/24' for an entire local network)
Add comments in Protected IPs using # to document why each IP/range is protected for future reference
Enable 'Save last IP ban expiry duration' if you frequently ban IPs with the same duration to speed up workflow
Set a reasonable pagination limit (e.g., 50) in settings if you have many banned IPs to improve admin page performance
Use the reason field consistently (e.g., 'spam:forum', 'brute-force:login') to enable effective searching later
The module runs before page caching (priority 250), so banned users won't receive cached pages

Technical Details

Advanced IP address bans /admin/config/people/advban

Main administration page for managing banned IP addresses. Displays a paginated table of all banned IPs with their expiration times, reasons, and status. Also provides a form to add new IP bans.

Edit the banned IP address /admin/config/people/advban/edit/{ban_id}

Edit an existing IP ban entry to change its expiry duration or reason. Displays a preview of the current ban information.

Delete IP address /admin/config/people/advban/delete/{ban_id}

Confirmation form to remove a specific IP address or range from the ban list.

Delete All IP addresses /admin/config/people/advban/delete_all

Bulk delete IP bans with filtering options based on IP type (simple or range) and expiration status.

Search IP /admin/config/people/advban/search

Search for banned IP addresses by IP address or ban reason. Results show matching bans with edit and delete operations.

Advanced ban settings /admin/config/people/advban/settings

Configure module-wide settings including expiry durations, protected IPs, ban messages, and display options.

Ban IP addresses

Allows users to manage banned IP addresses, including adding, editing, deleting, and searching IP bans, as well as configuring module settings.

hook_cron

Automatically removes expired IP bans during cron runs and logs the count of unbanned IPs

hook_help

Provides help text for the module's help page and admin page

hook_theme

Defines the ip_ban_view theme hook for displaying IP ban details in edit form

Cannot ban my own IP address

This is a safety feature to prevent administrators from accidentally locking themselves out. The module validates that neither the start IP nor any IP in a range matches your current IP address.

Banned IP can still access the site

Check if the IP is in the Protected IPs list. Protected IPs always override bans. Also verify the ban hasn't expired by checking the Status column in the IP list.

IP range ban not working for IPv6 addresses

IP range banning only supports IPv4 addresses. You can still ban individual IPv6 addresses, but not ranges. The module validates and shows an error message when attempting to create IPv6 ranges.

Expired bans not being removed automatically

Expired bans are removed by cron. Ensure cron is running regularly on your site. You can also manually run cron or use the Delete All page to immediately remove expired entries.

Ban message not showing properly

Check the Ban text settings. Ensure you're using the correct variables: @ip for the IP address and @expiry_date for the expiration date (only available in 'Ban text with expire' setting).

The module prevents administrators from banning their own IP address to avoid lockouts
Protected IPs always take precedence over bans, so ensure your protected list only contains truly trusted addresses
The HTTP middleware runs with high priority (250) to block banned IPs before any cached content is served
Reserved IP addresses (like 255.255.255.255) cannot be banned to prevent configuration issues
IP bans operate at the HTTP layer - sophisticated attackers may use proxies or VPNs to bypass bans