NinjaFirewall (Pro+ Edition)

Help & FAQ

The .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 /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.

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 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:

Using the .htninja file

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 (Pro+ 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., or custom IP ranges, see this discussion and that one on the 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 .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: