Plugin / Banhammer

Installation

Important: PHP Requirement

Before installing, make sure your server has either cURL or file_get_contents() enabled. Banhammer requires at least one of these functions to do its thing.

Install Banhammer

1. Upload the plugin and activate
2. Configure the plugin settings as desired
3. Visit the Armory to monitor traffic and ban/warn any unwanted visitors
4. Visit the Tower to manage any banned/warned targets

More info on installing WP plugins

Caching Plugins

Banhammer works with any type of caching plugin where “page caching” is not enabled.

There are many types of cache plugins. They provide all sorts of different caching mechanisms and features. All caching features work great with Banhammer except for “page caching”. With page caching, the required WP init hook may not be fired, which means that plugins like Banhammer are not able to log and ban requests dynamically. Fortunately, some of the most popular caching plugins provide settings that enable full compatibility with Banhammer. For a complete list, check out this article. Note: that article was written for Blackhole Pro, but the compatibility list and general info apply also to Banhammer.

Use Banhammer

Banhammer enables you to monitor traffic and ban any user or bot. To view your site’s traffic, visit the Armory. There you can ban or warn (flag) anything you wish. Once you have banned something, it will be locked in the Tower, where you can manage all banned users and bots.

Banhammer is designed to be as intuitive as possible, and provides complete documentation via the Help tab on any Banhammer screen. There are three plugin screens:

• Settings – configure options
• Armory – monitor site traffic
• Tower – manage banned visitors

So after configuring options, visit the Armory to monitor site traffic. If you see a visitor that should be banned, click the hammer button to ban them immediately. Or, if you just want to keep an eye on someone, click the horn button to issue a warning. After banning or warning your target, you can visit the Tower to manage as desired. There you can ban, warn, restore, or delete any target with a click.

For complete documentation, visit the Help tab of any Banhammer screen. If anything is unclear or if you find a bug, you can drop a line via my contact form.

With great power..

Please be careful not to ban any important IP addresses. Before banning some target, verify the IP and host name. Verifying the IP address is important because you do not want to accidentally ban major search engines and services. A good way to verify any IP address is to do a reverse lookup. The result should match the host name. For an example of how to verify a bot, check out this article at Perishable Press.

Pro Tip: In the Armory, you can click on the IP Address or Host Name to do a quick whois lookup.

Important! Don’t ban yourself!

Please be careful not to ban yourself when using Banhammer. The Basic Settings are powerful; use them wisely. Here are some things that can help mitigate any accidents:

• Be mindful when monitoring traffic; always know your own IP address and WP username.
• Disable the setting “Login Page”, so you always have access to the Login Page.
• Enable the setting “Ignore Users”, so you always can access the Tower, and your own visits will not be logged in the Armory.

Whoops! How do I get back in?

It’s almost inevitable. Worst-case scenario say you accidentally ban yourself. As site admin, it is easy to restore access. Follow these steps:

1. Download the Banhammer Unlock plugin
2. Upload the Unlock plugin to your server at: /wp-content/mu-plugins/
3. If the mu-plugins directory does not exist, go ahead and create it
4. After uploading the plugin, Banhammer will be disabled, so you can log in and restore access via the Tower
5. Once you have restored access, delete the Banhammer Unlock plugin from the server
6. After deleting the Unlock plugin, Banhammer once again will be enabled

Alternately, if you banned yourself by IP address, you can bypass the ban by using a trustworthy proxy service to log in to your site.

Testing

How do you know if the plugin is working? Like if you want to customize the banned response? Well, there are several ways to go about it.

Method One (easiest): Configure the following Banhammer settings:

• Enable Plugin – enable
• Ignore Users – disable
• Login Page – disable
• Admin Area – disable

After saving the changes, you will be able to ban your own visits to the front-end (non-admin) pages on your site, without actually banning yourself from the Admin Area or Login Page. Just remember to restore access via the Tower when you are finished testing.

Method Two (moderate): Create a new WordPress user and log in using a second browser. Then as you surf around the site, you can monitor and ban the user via the first browser.

Method Three (advanced): Open two browser tabs. Tab 1 is the Armory. Tab 2 is a good proxy service. With Banhammer enabled, visit your site’s homepage via proxy. Then jump over to the Armory and ban the proxy IP address. Then retry the proxy visit to the homepage; it should be denied access. Remember to restore access or delete the banned IP via the Tower when finished testing.

Manually Add IP Address

If you want to ban some IP that has not yet visited your site, you can do so by entering the following URL in your browser’s address bar:

https://example.com/wp-admin/?banhammer-key=[KEY]&banhammer-ip=[IP]

Replace the following:

• Replace [KEY] with your “Target Key”
• Replace [IP] with the IP you want to block
• Replace example.com with your own domain

Note: You can find your Target Key in Banhammer Advanced settings.

For more info about adding targets, visit the Help tab on the Settings page.

Important! Never share your Target Key, always keep it secret.

Auto-Clear Data

To prevent collected data from filling up the database, Banhammer automatically clears all Armory data at regular intervals. By default, the interval is 24 hours. So every 24 hours, the Armory data will be flushed, and fresh data will be collected. Of course, any banned targets will remain banned and available in the Tower. To change the auto-clear interval, check out the “Reset Armory” setting. Visit the Armory Help tab for more details.

Performance Tip!

The first time a logged entry is displayed in the Armory, additional data are fetched behind the scenes. So as you navigate pages, you may notice that pages containing new entries take a bit more time to load. Subsequent views should be nice and speedy via Ajax. So with that in mind, it is optimal for performance to keep the number of items per page to a minimum. Try to keep it anywhere under 10 or so and you should be good. To change the number of entries displayed per page, click “Tools” and go to “Display [x] rows”.

Basic View vs. Advanced View

Under the Tools menu you can toggle between “Basic view” and “Advanced view”. Basic view gives you a streamlined summary. Advanced view gives you complete data for each entry. Note that you can toggle each entry individually between Basic and Advanced. So for example, you can monitor traffic in Basic view, and then toggle open (double-click) any entry that may need banning. The default is Advanced view.

Sound Effects!

Banhammer sound effects can be enabled by clicking “Tools” and then “Enable sound fx”. When enabled, the sounds will be played whenever an action button is clicked. This includes the Ban, Warn, Restore, and Delete buttons. The Armory provides Ban and Warn buttons. The Tower provides all four. Note that enabling sound fx in the Armory applies to the Tower as well.

Note that the sound effects are a work in progress. Finding quality open source audio is challenging. If you are able to contribute better effects, please let me know. And of course, the sound effects can be disabled entirely by clicking “Disable sound fx”.

License for Sound Effects

Audio used in plugin

• Explosion sound by steveygos93: Attribution 3.0 Unported (CC BY 3.0)
• Inception Horn sound by Kubatko: CC0 1.0 Universal (CC0 1.0)
• Shield Guard sound by nekoninja: CC0 1.0 Universal (CC0 1.0)
• Lettuce Chopping sound by danloss: CC0 1.0 Universal (CC0 1.0)

Audio used in promos

• War Drum Loop by limetoe: CC0 1.0 Universal (CC0 1.0)
• Warrior Drums by Sclolex: CC0 1.0 Universal (CC0 1.0)

Uninstalling

This plugin cleans up after itself. All plugin options and collected data will be removed from your database when the plugin is uninstalled via the Plugins screen.

Like the plugin?

If you like Banhammer, please take a moment to give a 5-star rating. It helps to keep development and support going strong. Thank you!