NinjaFirewall comes with a graphical installer to make the setup process as quick and easy as possible.
Requirements: NinjaFirewall works on Linux servers only. It requires PHP v5.3+ with cURL and ZipArchive support in order to download and install updates, as well as PHP INI support. Most basic shared hosting accounts match those requirements.
Using your FTP client, create a new directory in the root folder of your website (this is the top directory where your main index page is located) and upload all files from the NinjaFirewall ZIP archive into that new directory. Go to
http://yoursite.com/ninjafirewall_folder/ to access the graphical installer and follow the indicated steps.
If you are installing the Pro+ Edition, a valid license will also be required.
If, at the end of the installation process, it displays a
The firewall is not loadedmessage, please consult our Troubleshooting section.
If your installation of NinjaFirewall requires a PHP INI file (
php5.ini) you may need to deny access to it, depending on your webserver configuration:
See our blog article: Protecting NinjaFirewall's PHP INI file.
How to disable NinjaFirewall
There are two possible ways to disable NinjaFirewall:
- Log into the NinjaFirewall admininistration console, go to the "Firewall > Options > Firewall protection", select "Disabled" and click on the "Save Changes" button.
- Rename the PHP INI (php.ini, .user.ini or php5.ini) or the .htaccess file that contains the NinjaFirewall
auto_prepend_filedirective. Use this method only if you cannot get access to your NinjaFirewall admininistration console.
This is the most common problem experienced by some users. At the end of the installation process, it displays the following message:
The firewall is not loaded.
NinjaFirewall needs to inform PHP that it wants to hook all requests before they are passed to your scripts. This is done with some specific instructions added to your PHP user configuration file (usually named php.ini or .user.ini) or, if you are using Apache PHP module, to its user configuration file named .htaccess. These instructions will be given to you during the installation process.
If the test fails, it will display some info and recommendations to help you to solve the issue. If it keeps failing, please contact your hosting company and ask them how you can use per-directory PHP configuration files (see also PHP: The configuration file).
For more information please refer to: Troubleshoot NinjaFirewall installation problems.
I lost my administrator password. How can I recover it?
Because each site is different, it is possible that the default configuration of NinjaFirewall may wrongly block some visitors. If this occurred, NinjaFirewall would display a message with an incident ID (7-digit number):
- Ask your visitor to give you that number.
- Check your firewall log ("Firewall > Security Log" menu from your administration dashboard) and find the rule number that matches the incident ID you want to disable. They are displayed in the
- Go to the "Rules Editor" menu, select the corresponding rule number from the enabled rules list and disable it.
Note: if the
RULE column from your log shows a hyphen
- instead of a number, that means that the rule can be changed in your "Firewall > Policies" page.
For more information please refer to: Testing NinjaFirewall without blocking your visitors.
How powerful is NinjaFirewall?
NinjaFirewall includes a very powerful filtering engine that can detect Web Application Firewall evasion techniques and obfuscation tactics used by hackers, as well as support and decode a large set of encodings. See our blog for a detailed description: An introduction to NinjaFirewall v3.0 filtering engine.
Do I need root privileges to install NinjaFirewall?
Unlike Web Application Firewalls such as ModSecurity, NinjaFirewall does not require any administrator privileges and is fully compatible with most shared hosting accounts.
Does it work with Nginx?
NinjaFirewall works with Nginx and others Unix-based HTTP servers like Apache and LiteSpeed as long as they support the
auto_prepend_file PHP directive (either in PHP INI or .htaccess files).
Do I need to alter my PHP scripts?
You do not need to make any modifications to your scripts. NinjaFirewall hooks all requests before they reach your scripts. It will even work with encoded scripts (ionCube, ZendGuard, SourceGuardian etc).
Will NinjaFirewall detect the correct IP of my visitors if I am behind a CDN service like Cloudflare or Incapsula?
If you are using NinjaFirewall (Pro+ Edition), you can modify the source IP from the "Firewall > Access Control > Source IP" menu. If you are using NinjaFirewall (Pro Edition), you can use an optional configuration file to tell NinjaFirewall which IP to use. Please follow these steps.
Will it slow down my site?
Your visitors will not notice any difference with or without NinjaFirewall. The administration console shows benchmark statistics (the fastest, slowest and average time per request).
Is there a Microsoft Windows version?
NinjaFirewall works on Unix-like servers only. There is no Windows version and we do not expect to release any.
Can I add/write my own security rules?
You can use the optional
.htninja configuration file for that purpose.
Can I migrate my site(s) with NinjaFirewall installed?
In order to migrate your site, you must follow these steps:
- Rename the PHP INI or .htaccess file that contains the NinjaFirewall
- Migrate your site, including NinjaFirewall.
- Edit your PHP INI or .htaccess file and change the
auto_prepend_filepath to the
firewall.phpscript so that it matches your new website document root/directory structure.
- Rename your PHP INI or .htaccess file to its original name.
- Log in to your NinjaFirewall admin dashboard, click on "Firewall > Policies", scroll down to the bottom of the page and click the "Save Changes" button. This operation will adjust your configuration to the new website document root.
- Check the "Summary > Overview" page to ensure there is no error or warning message.
How can I protect Joomla! with NinjaFirewall?
See our article : Securing a Joomla! installation with NinjaFirewall (Pro+).
To uninstall NinjaFirewall:
- Log in to your administration console and disable NinjaFirewall from the "Firewall > Options > Firewall protection" menu.
- Delete any occurences of NinjaFirewall that you added to your PHP INI and/or .htaccess files during the installation.
- Delete the NinjaFirewall directory and all of its contents (subdirectories and files).
- If you were using a .user.ini, it is recommended to restart your HTTP server (Apache), or PHP-FPM (Nginx etc) to force PHP to reload the newly modifier INI file.
Blank page: in some cases, right after uninstalling NinjaFirewall, you may get a blank page and the following error message:
Warning: Unknown: failed to open stream: No such file or directory in Unknown on line 0 Fatal error: Unknown: Failed opening required '.../firewall.php' ... in Unknown on line 0
- The problem can be due to your PHP configuration that may require a few minutes before the PHP INI file, which was edited during the uninstallation process, is reloaded by PHP. If this is your own server, simply restart PHP (e.g. PHP-FPM) or your HTTP server (Apache) in order to reload the INI file immediately, otherwise, you need to wait a couple of minutes, until the file is reloaded. The problem will then go away.
- You still have NinjaFirewall's instructions in your PHP INI file or .htaccess. Open that file, look for similar lines and delete them:
; BEGIN NinjaFirewall auto_prepend_file = /......./firewall.php ; END NinjaFirewall
# BEGIN NinjaFirewall php_value auto_prepend_file /......./firewall.php # END NinjaFirewall
.htninja configuration file
NinjaFirewall (Pro/Pro+ Edition) can use an optional configuration file that lets users prepend their own PHP code to the firewall.
This file must be named
.htninja and must be located either:
- In the folder above your website document root:
If your document root is
/home/user/public_html/, the location of the file will be
This is the recommended choice. Because it is located outside the document root, the file is relatively safe and protected. However, if you have an open_basedir restriction, PHP will not be able to access it.
- In the document root folder:
If your document root is
/home/user/public_html/, the location of the file will be
Recommended only if you have an open_basedir restriction. If you are using the Apache HTTP server, the file is relatively protected because, by default, it will never serve a file whose name starts with
.ht*. However, if you are using Nginx or any other HTTP server that do not use .htaccess files, you must set it up so that it will block any access to the file from a web browser.
NinjaFirewall package contains a sample file, named
It is a regular PHP file. Note that it does not contain a PHP closing tag (
?>). We recommend to keep it that way, because if there was a space or new line character after a closing tag, it would trigger errors on your site (PHP would need to send HTTP headers in order to ouput those characters before your website is loaded). This problem does not occur when the PHP closing tag is missing.
You can check if the
.htinja file was detected from your NinjaFirewall admin dashboard, in the "Firewall > Overview" menu:
You can add/modify server variables in the
.htninja file. For instance, users of the CDN service Cloudflare can copy the visitor real IP (
HTTP_CF_CONNECTING_IP) into the
REMOTE_ADDR variable so that NinjaFirewall will use the correct IP:
Users of the Incapsula CDN service should use the
HTTP_INCAP_CLIENT_IP variable instead:
Users of NinjaFirewall (Pro+ Edition) can perform the same task from the "Access Control > Source IP" menu option rather than using the
ALLOW / BLOCK
It is possible to use NinjaFirewall special return values
BLOCK in order to blacklist or whitelist anything you want:
ALLOW: the firewall will accept the request immediately and will not filter it.
BLOCK: the firewall will block the request (403 Forbidden) and close the connection immediately.
This is the fastest way to allow or block a request because it will be processed before WordPress is loaded and even before NinjaFirewall loads its own configuration. Note that, for this reason, the firewall will not write the event to its log.
For instance, we ask the firewall to allow IP 220.127.116.11:
If you whitelist your IP using the
Live Logfeature will not work.
Allow IPv4 18.104.22.168, 22.214.171.124 and IPv6 2001:4998:c:a06::2:4008:
Allow all IPs from 126.96.36.199 to 188.8.131.52:
To block or allow IPv4 CIDR (e.g., 184.108.40.206/24) or custom IP ranges, see this discussion and that one on the WordPress.org forum.
To reject, use the
BLOCK return value instead:
Users of NinjaFirewall (Pro+ Edition) can whitelist or blacklist IPs from the "Access Control > IP Access Control" menu option rather than using the
To allow any access to a PHP script located inside the
.htninja.sample included in NinjaFirewall package shows some advanced filtering samples, for instance, blocking a
POST request if it contains a
whatever variable sent to a PHP script named