Firewall Optimization Troubleshooting

Firewall Optimization has one technical goal - to get the PHP variable auto_prepend_file value set to the location of the Firewall initialization file (wordfence-waf.php). Depending on server setup, this involves changes to the .htaccess, .user.ini or php.ini files. In this document we describe what to look for if the Optimization does not complete as expected.

Check PHP Version

On servers using “CGI/FastCGI” or “suPHP”, the firewall setup uses the “.user.ini” file. The “.user.ini” file was introduced in PHP 5.3, so if your site is running PHP 5.2 or older, you will need to update PHP. You can find out your site’s PHP version on the Wordfence “Tools” > “Diagnostics” page.

Some sites hosted under a “cPanel” hosting control panel may show “Basic WordPress Protection” mode even though the “Diagnostics” page shows that the “auto_prepend_file” PHP directive is set correctly. That can mean that the “.user.ini” file is not processed correctly when accessing files in subdirectories, such as the “wp-admin” directory. However, the “.user.ini” file is processed correctly in the site’s root directory. cPanel/WHM seems to be working on this issue. More details and a workaround can be found on their forum. Depending on your hosting plan, you may need to ask your host to make this change.

If php.ini has been edited manually but the changes still do not take effect

Near the bottom of the Wordfence “Tools” > “Diagnostics” page, click the link that says “Click to view your system’s configuration in a new window” and search for “auto_prepend_file”. If the value you entered for “auto_prepend_file” does not appear in the first column, it is being overridden by another “php.ini” file. This may mean that your host has a “php.ini” file that loads after yours, and sets “auto_prepend_file” to a blank value.

You can see which “.ini” files are loaded at the top of the same page on the lines labeled “Loaded Configuration File” and “Additional .ini files parsed”. Make sure that the “.ini” file you have been editing appears in that list. If it does, you may need to ask your host if they can remove the “auto_prepend_file” line from one of these additional files, so that your own value will be used.

In rare cases, when a host uses PHP-FPM, they may have PHP settings defined in a “pool” file. These settings can override options set in your custom “php.ini” or “.user.ini” file. You may need to ask the host if they have settings in a pool file. The default location for the pool file on new Ubuntu servers is similar to:

/etc/php/7.0/fpm/pool.d/www.conf (depending on the PHP version).

An example of an option that would override your “auto_prepend_file” option is:

php_admin_value[auto_prepend_file] = none

If the host is able to remove this option, it should allow your settings to be used for the firewall.

If .user.ini has been edited manually but the changes still do not take effect

If you edited “.user.ini” but your firewall “Protection Level” still shows “Basic WordPress Protection” mode and not “Extended Protection” mode then check the “.user.ini” file for an entry before our firewall code that says this:

ini_set('output_buffering', 0);

Remove or comment out this line and try changing the firewall “Protection Level” to “Enabled and Protecting” mode.

Other security plugins

Some security plugins can change the permissions of files and directories. If you have a security plugin that does that, you can temporarily turn off those options, run the firewall setup, and then re-enable those options. When these features are enabled, you may see the messages in the error messages section.

Error messages

If you see error messages about file permissions, check if you have another security plugin that changes permissions, and temporarily set the files or directories to be writable. If you have previously set file permissions manually, make sure that the web server user can temporarily write to these files or directories. You will only need to do this during the initial firewall setup process, so you can re-enable other security measures after the setup is complete.

Possible error messages include:

We were unable to write to ~/wp-content/wflogs/ which the WAF uses for storage. Please update permissions on the parent directory so the web server can write to it.

Make sure that the “wp-content” directory is writable by the web server, at least during the setup process. You can make the “wp-content” directory unwritable as long as “wp-content/wflogs” has been created and remains writable by the web server user.

We were unable to create the wordfence-waf.php file in the root of the WordPress installation.

This means that new files cannot be written to the root directory of your site.

We were unable to make changes to the .htaccess file.

Check to make sure that the “.htaccess” file can be written by the web server user, and then try the process again.

We were unable to make changes to the .user.ini file.

Some server configurations need this file in addition to “.htaccess”. Some hosts may use a different filename. If you don not already have the file mentioned in the message, make sure the root directory of the site is writable. Each of these issues can be solved by temporarily disabling permissions changes made by other security plugins, or by manually adjusting permissions.

Other Installation Issues

If you have other security measures that prevent the necessary files from being updated, or if you have manually set file permissions, you can set up the firewall manually. When you click the “CLICK HERE TO CONFIGURE” button, follow the directions under the “Alternative Hosting Provider Setups” heading.

Depending on your server configuration, you may be prompted to create the “wordfence-waf.php” file, and edit or create “.htaccess” or “.user.ini” files in the site’s root directory.

Using a single php.ini on servers with multiple sites

The “php.ini” file supports sections, so if you only have a single “php.ini” file, you may be able to add a section similar to the examples below. You will need to replace the path shown with the full file path given during the firewall optimization for the “auto_prepend_file” directive. For example, you have three sites:

All three sites are located in these separate subdirectories of the document root directory, which for this illustration we will call “public_html”:


You can use the HOST or PATH directive and one of these directives may be better suited for your sites or server environment so we recommend that you check with your hosting provider which directive to use.

Using the HOST directive you would have this in your “php.ini” file:

auto_prepend_file = '/path/to/public_html/site-one/wordfence-waf.php'
auto_prepend_file = '/path/to/public_html/site-two/wordfence-waf.php'
auto_prepend_file = '/path/to/public_html/site-three/wordfence-waf.php'

Note that if is configured to only be accessible via the “www” subdomain for example then the “www” subdomain also needs to be added to the HOST directive like this:

auto_prepend_file = '/path/to/public_html/site-two/wordfence-waf.php'

However, if is configured to be accessible with or without the “www” subdomain then you may need to use the PATH directive instead.

Using the PATH directive you would have this in your “php.ini” file:

auto_prepend_file = '/path/to/public_html/site-one/wordfence-waf.php'
auto_prepend_file = '/path/to/public_html/site-two/wordfence-waf.php'
auto_prepend_file = '/path/to/public_html/site-three/wordfence-waf.php'

Another thing to consider is if your hosting provider ever changes the file path, or there are multiple valid paths pointing to the site’s files, then using the HOST directive may be preferred.

You can read more about the HOST and PATH directives below on the documentation:

Sites using lsapi instead of mod_php

In version 6.3.12 and later, Wordfence should automatically detect LiteSpeed and servers using the “lsapi” module. If you use a variant of LiteSpeed and the automatic setup is not working, please contact our support team. Note that if you are using the “OpenLiteSpeed” web server then refer to the separate OpenLiteSpeed section below.

If your server uses the “lsapi” module and shows that “Basic WordPress Protection” is still active after the firewall optimization, first check that you are using the latest version of Wordfence, and update it if necessary. Otherwise, you may need to add the section below to your “.htaccess” file.

You can confirm if your server is using the “lsapi” module by going to the “Tools” > “Diagnostics” page. Expand the “Other Tests” section and click on the link that says “Click to view your system’s configuration in a new window”. If the “Server API” field near the top of that page says “LiteSpeed” then search for “$_SERVER[‘SERVER_SOFTWARE’]” near the bottom of the page. If it says “Apache” then this change should be what you need:

<IfModule lsapi_module>
php_value auto_prepend_file '/path/to/site/wordfence-waf.php'

Sites using OpenLiteSpeed

The OpenLiteSpeed web server does not currently support “.htaccess” or “.user.ini” files and can only be set up manually. OpenLiteSpeed has instructions in this link below:

When the “Optimize Wordfence Firewall” dialogue is displayed then to complete the “Manual Configuration” you will need to do this:

1. Select “Manual Configuration” and press “Continue”.
2. Take note of the “auto_prepend_file” file path displayed.
3. Follow the instructions in the OpenLiteSpeed documentation link above.