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 sites with 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 Diagnostics page.

Some cPanel sites may show “Basic Protection” even though the Diagnostics page shows that “auto_prepend_file” is set correctly. That can mean that .user.ini files are not processed correctly when accessing files in subdirectories, such as wp-admin, even though they’re applied correctly in the site’s main directory. cPanel/WHM seem 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 Diagnostics page, located on the Tools menu, 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 the 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) and 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.

Other security plugins

Some security plugins can change 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, 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’ll only need to do this during the initial firewall setup process, so you can re-enable other security measures after 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 wp-content/ 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 main folder 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’t already have the file mentioned in the message, make sure the main folder 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 at the bottom of the page below the Alternate Method heading.

Depending on your server configuration, you may be prompted to create wordfence-waf.php, and edit or create .htaccess or .user.ini files in the site’s main 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 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 lsapi. If you use a variant of LiteSpeed and automatic setup is not working, please contact support. Note that if you are using the “OpenLiteSpeed” web server then refer to the separate OpenLiteSpeed section below.

If your site uses “lsapi” 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 site is using “lsapi” by going to the Tools page on the Wordfence menu and clicking the Diagnostics tab, then click the link that says “Click to view your system’s configuration in a new window” near the bottom of the page. If the Server API field near the top of that page says “LiteSpeed”, search for $_SERVER[‘SERVER_SOFTWARE’] near the bottom of the page, and if you find “Apache” there, this change should be what you need:

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

You edited user.ini but your site still shows basic protection and not enhanced protection
Check the user.ini file for an entry before our waf code that says this:

ini_set('output_buffering', 0);

Remove or comment out this line and try moving the protection to “Enabled and Protecting.”

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.