Web Application Firewall Setup

From Wordfence Documentation
Jump to: navigation, search

Setup Process

When the Wordfence Web Application Firewall is first installed, at the top of WordPress admin pages, you will see "To make your site as secure as possible, take a moment to setup the Wordfence Web Application Firewall."

When you click the "Click here to configure" button, the setup page will detect the server configuration for your site. You should not need to change this option, but you can, if you know that your server configuration is not detected correctly. Click the Continue button.

The next page may recommend downloading one or more files (.htaccess and .user.ini) for backup purposes, in case your host does not support this setup. You can upload the backup files to your site if there are any problems. Once you have downloaded the files, you can click Continue to complete the setup.

On some hosts, you may have to wait up to 5 minutes, for the change to take effect.


If you don't want to set up the firewall right now, you can dismiss the notice. Setup will still be available on the Firewall page if you want to set up Extended Protection in the future.


Solutions to Error Messages and Setup Issues

If installation completes without errors but the firewall still shows Basic WordPress Protection

  • Some servers have a delay, usually only up to 5 minutes before the changes will take effect, due to caching.
    • Waiting for 5 minutes and checking again will solve the issue, if this is the case.
  • 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.
    • Your PHP version can be found on the Diagnostics tab on the Wordfence Tools page.
    • PHP 5.2 was last updated in January 2011, and the PHP developers no longer release security fixes for 5.5 or below. We recommend using at least PHP 5.6 to keep your site stable and secure. For better performance, 7.x versions are preferred.
    • Most hosts will update PHP from 5.2 to a newer version. Many hosts allow you to choose the PHP version your site uses.
  • 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.

SiteGround and other hosts without .user.ini support

If the "Click here to configure" button still appears after completing setup and waiting about 5 minutes, your host may not use the typical configuration files, such as .user.ini.

On SiteGround and other similar hosts that use cPanel:

  1. After attempting the installation, click the "Click here to configure" button again
  2. Look at the line that says something like: auto_prepend_file = '/home/username/public_html/wordfence-waf.php'
  3. Copy the "path" that appears between the quotes - yours will be different. In this example: /home/username/public_html/wordfence-waf.php
  4. Go to your site's cPanel, and click the PHP Variables Manager icon
  5. Click the link that says "public_html"
  6. Enter "auto_prepend_file" as the variable name, click the "Add" button, and then paste the path that you copied
  7. Turn on the checkbox "Apply changes to all sub-directories" and click Save

If the site will not load properly, check the path you pasted to be sure there are no extra letters, quotes, slashes, etc. in the PHP Variables Manager. If it still will not work, you can try deleting the path and saving the settings, to return the site to its previous state and try again.

Using php.ini with multiple sites on a single hosting account

If you have multiple sites on a single hosting account and need to use php.ini like in the cases above, you may need to add a similar php.ini file for each additional site, in each site's subdirectory. In this case, you may also need to add code like this in each additional site's .htaccess file, to tell PHP which php.ini file to use:

SetEnv PHPRC /home/user/public_html/sitename/php.ini

You will need to adjust the path for your site and the site's directory name, before adding this to the .htaccess file. If the subdirectory site's .htaccess file already has a similar line, this change may not be needed.

Note: Some hosts may require PHPRC to show the path without "php.ini" at the end.

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 write to these files or directories temporarily.

This only needs to be done 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 one of these two examples. You will need to replace the path shown with the path given during the firewall optimization.

[HOST=host1.example.com]
auto_prepend_file = '/path/to/site/wordfence-waf.php'
[PATH=/path/to/site/]
auto_prepend_file = '/path/to/site/wordfence-waf.php'

Sites using lsapi instead of mod_php

In version 6.3.12 and later, LiteSpeed and lsapi should be detected automatically. If you use a variant of LiteSpeed and automatic setup is not working, please contact support. (Note that the "OpenLitespeed" server does not currently support .htaccess files or .user.ini and can only be set up manually. We are not aware of any hosts currently using OpenLitespeed.)

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/wordfence-waf.php'
</IfModule>

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"

Still need help?

If you cannot complete the setup and the steps above do not help, you can contact us on the support forum if you are a free customer or open a ticket if you are a premium user.