NinjaFirewall (WP+ Edition)

Help & FAQ

The .htninja configuration file

An optional NinjaFirewall user configuration file can be used to overwrite some of the firewall hard-coded variables, for instance, to tell NinjaFirewall where is located your WordPress configuration file, wp-config.php, if you moved it to another directory, add/modify server variables or prepend your 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 /home/user/.htninja.
    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 /home/user/public_html/.htninja.
    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.
Any .htninja directive will be processed first, even before NinjaFirewall brute-force protection.

NinjaFirewall package contains a sample file, named .htninja.sample.

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 blog 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 WordPress admin console, in the "NinjaFirewall > Overview" menu:

Path to wp-config.php

Since v3.0.1, NinjaFirewall will look for the wp-config.php script in the current folder or, if it cannot find it, in the parent folder. Therefore, use the .htninja to change the path to the wp-config.php only if you have NinjaFirewall <3.0.1.

If you want NinjaFirewall to use a specific wp-config.php file, add its full path to the $wp_config variable:

Path to NinjaFirewall's log and cache directory

By default, NinjaFirewall saves its logs and cached files into a folder named /nfwlog/ located inside the WordPress /wp-content/ directory. If you want to change that path, use the NFW_LOG_DIR constant:

In the above example, NinjaFirewall's log folder would be /foo/bar/somewhere/nfwlog/.

Server variables

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 (WP+ Edition) can perform the same task from the "Access Control > Source IP" menu option rather than using the .htninja file.


It is possible to use NinjaFirewall special return values ALLOW and 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

If you whitelist your IP using the .htninja, NinjaFirewall Live Log feature will not work.

Allow IPv4, and IPv6 2001:4998:c:a06::2:4008:

Allow all IPs from to

To block or allow IPv4 CIDR (e.g.,, see this discussion on the forum.

To reject, use the BLOCK return value instead:

 Users of NinjaFirewall (WP+ Edition) can whitelist or blacklist IPs from the "Access Control > IP Access Control" menu option rather than using the .htninja file.

To allow any access to a PHP script located inside the /foo/bar/ directory:

Advanced Filtering

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 script.php: