Skip to content

Commit

Permalink
Merge branch 'develop' into 4.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@invisnet
invisnet committed Mar 11, 2019
2 parents 40f6ae3 + 844d8f2 commit a160fb9
Show file tree
Hide file tree
Showing 31 changed files with 655 additions and 425 deletions.
78 changes: 7 additions & 71 deletions configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,78 +4,14 @@
Configuration
=============

.. _configuration_fail2ban:
Now you have *WPf2b* installed and activated it's time to make it do something useful.

fail2ban
--------

Filters
^^^^^^^
.. toctree::
:hidden:

The filter files included are intended only as a starting point for those who want *WPf2b* to work "out of the box".

There is no "one size fits all" configuration possible for `fail2ban` - what may be a soft failure for one site should be treated as a hard failure for another, and vice versa. Careful thought should be given to what is appropriate for your environment.


Typical Settings
""""""""""""""""

#. Copy `wordpress-hard.conf` and `wordpress-soft.conf` to your `fail2ban/filters.d` directory
#. Edit `jail.local` to include something like:

.. code-block:: sh
[wordpress-hard]
enabled = true
filter = wordpress-hard
logpath = /var/log/auth.log
maxretry = 1
port = http,https
[wordpress-soft]
enabled = true
filter = wordpress-soft
logpath = /var/log/auth.log
maxretry = 3
port = http,https
3. Reload or restart `fail2ban`


`wordpress-hard.conf` and `wordpress-soft.conf`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are some things that are almost always malicious, e.g. blocked users and pingbacks with errors. `wordpress-hard.conf` is designed to catch these so that you can ban the IP immediately.

Other things are relatively benign, like a failed login. You can't let people try forever, but banning the IP immediately would be wrong too. `wordpress-soft.conf` is designed to catch these so that you can set a higher retry limit before banning the IP.

For the avoidance of doubt: you should be using *both* filters.


`wordpress-extra.conf`
^^^^^^^^^^^^^^^^^^^^^^

Version 4 introduced a number of new logging options which didn't fit cleanly into either of the `hard` or `soft` filters - they're `extra`.

For example, if your site doesn't use WordPress comments at all, you could add the rules matching attempted comments to the `hard` filter. Again, there is no "one size fits all" for these rules.


.. _configuration_mu-plugins_support:

`mu-plugins` Support
--------------------

One of the better ways is to install *WPf2b* as usual and then create a symlink in ``mu-plugins``:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban/wp-fail2ban.php
or for the Premium version:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban-premium/wp-fail2ban.php
This has the advantage that you can update *WPf2b* as usual without having to update ``mu-plugins`` directly. For the free version you don't need to activate *WPf2b*, but for the Premium version you do.
configuration/wp-fail2ban
configuration/logging
configuration/fail2ban
configuration/mu-plugins

58 changes: 58 additions & 0 deletions configuration/fail2ban.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
.. _configuration__fail2ban:

fail2ban
--------

``fail2ban`` can be tricky to configure correctly; with so many flavours of Linux it's impossible to provide anything but general guidance.


Filters
^^^^^^^

The filter files included are intended only as a starting point for those who want *WPf2b* to work "out of the box".

There is no "one size fits all" configuration possible for `fail2ban` - what may be a soft failure for one site should be treated as a hard failure for another, and vice versa. Careful thought should be given to what is appropriate for your environment.


Typical Settings
""""""""""""""""

#. Copy `wordpress-hard.conf` and `wordpress-soft.conf` to your `fail2ban/filters.d` directory
#. Edit `jail.local` to include something like:

.. code-block:: sh
[wordpress-hard]
enabled = true
filter = wordpress-hard
logpath = /var/log/auth.log
maxretry = 1
port = http,https
[wordpress-soft]
enabled = true
filter = wordpress-soft
logpath = /var/log/auth.log
maxretry = 3
port = http,https
3. Reload or restart `fail2ban`


`wordpress-hard.conf` and `wordpress-soft.conf`
"""""""""""""""""""""""""""""""""""""""""""""""

There are some things that are almost always malicious, e.g. blocked users and pingbacks with errors. `wordpress-hard.conf` is designed to catch these so that you can ban the IP immediately.

Other things are relatively benign, like a failed login. You can't let people try forever, but banning the IP immediately would be wrong too. `wordpress-soft.conf` is designed to catch these so that you can set a higher retry limit before banning the IP.

For the avoidance of doubt: you should be using *both* filters.


`wordpress-extra.conf`
""""""""""""""""""""""

Version 4 introduced a number of new logging options which didn't fit cleanly into either of the `hard` or `soft` filters - they're `extra`.

For example, if your site doesn't use WordPress comments at all, you could add the rules matching attempted comments to the `hard` filter. Again, there is no "one size fits all" for these rules.

92 changes: 92 additions & 0 deletions configuration/logging.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
.. _configuration__logging:

Logging
-------

The key concept behind *WPf2b* is logging *Events* to ``syslog``. If *WPf2b* doesn't log an Event, or logs it to the wrong place, ``fail2ban`` won't work as it should. If in doubt go with the defaults - they should work for most systems, and once you understand how the pieces fit together you can revisit this.

.. _configuration__logging__choosing_events:

Choosing the Events to Log
^^^^^^^^^^^^^^^^^^^^^^^^^^

If you're unfamiliar with ``fail2ban`` and ``syslog`` I recommend **not** enabling any extra logging to start with - skip ahead to configuring :ref:`configuration__fail2ban`. *WPf2b* automatically handles the most important things with sensible defaults that should work for most systems.

Advanced Users
^^^^^^^^^^^^^^

Events
""""""

Over the years *WPf2b* has accumulated a lot of logging ability (and there're even more on the way):

+--------------------------------------------+-------------------------------------------+
| Event | Reference |
+============================================+===========================================+
| Auth OK | :ref:`WP_FAIL2BAN_AUTH_LOG` |
+--------------------------------------------+ +
| Auth Fail | |
+--------------------------------------------+-------------------------------------------+
| Blocked User | :ref:`WP_FAIL2BAN_BLOCKED_USERS` |
+--------------------------------------------+-------------------------------------------+
| Blocked User Enumeration | :ref:`WP_FAIL2BAN_BLOCK_USER_ENUMERATION` |
+--------------------------------------------+-------------------------------------------+
| Comment | :ref:`WP_FAIL2BAN_LOG_COMMENTS` |
+--------------------------------------------+-------------------------------------------+
| Comment: Spam | :ref:`WP_FAIL2BAN_LOG_SPAM` |
+--------------------------------------------+-------------------------------------------+
| Attempted Comment: Post not found | :ref:`WP_FAIL2BAN_LOG_COMMENTS_EXTRA` |
+--------------------------------------------+-------------------------------------------+
| Attempted Comment: Closed post | :ref:`WP_FAIL2BAN_LOG_COMMENTS_EXTRA` |
+--------------------------------------------+-------------------------------------------+
| Attempted Comment: Trash post | :ref:`WP_FAIL2BAN_LOG_COMMENTS_EXTRA` |
+--------------------------------------------+-------------------------------------------+
| Attempted Comment: Draft post | :ref:`WP_FAIL2BAN_LOG_COMMENTS_EXTRA` |
+--------------------------------------------+-------------------------------------------+
| Attempted Comment: Password-protected post | :ref:`WP_FAIL2BAN_LOG_COMMENTS_EXTRA` |
+--------------------------------------------+-------------------------------------------+
| Pingback | :ref:`WP_FAIL2BAN_LOG_PINGBACKS` |
+--------------------------------------------+-------------------------------------------+
| Pingback error | :ref:`WP_FAIL2BAN_PINGBACK_ERROR_LOG` |
+--------------------------------------------+-------------------------------------------+

You should consider enabling *Comment: Spam* and *Attempted Comment: Closed post*, and, if you don't use WordPress's commenting system at all, you should enable **all** the *Attempted Comment* Events.


Facilities
""""""""""

By default, *WPf2b* uses the following ``syslog`` Facilities and *Levels*:

+----------------------------------+----------------------------+--------+
| What | Default | Level |
+==================================+============================+========+
| Auth OK | :ref:`LOG_AUTH <LOG_AUTH>` | INFO |
+----------------------------------+ +--------+
| Auth Fail | | NOTICE |
+----------------------------------+ + |
| Blocked User | | |
+----------------------------------+ + |
| Blocked User Enum | | |
+----------------------------------+----------------------------+--------+
| Comment | :ref:`LOG_USER <LOG_USER>` | INFO |
+----------------------------------+----------------------------+--------+
| Comment: Spam | :ref:`LOG_AUTH <LOG_AUTH>` | NOTICE |
+----------------------------------+ + |
| Comment: Post not found | | |
+----------------------------------+ + |
| Comment: Closed post | | |
+----------------------------------+ + |
| Comment: Trash post | | |
+----------------------------------+ + |
| Comment: Draft post | | |
+----------------------------------+ + |
| Comment: Password-protected post | | |
+----------------------------------+----------------------------+--------+
| Pingback | :ref:`LOG_USER <LOG_USER>` | INFO |
+----------------------------------+----------------------------+--------+
| Pingback error | :ref:`LOG_AUTH <LOG_AUTH>` | NOTICE |
+----------------------------------+----------------------------+--------+

Unfortunately, there is no way of knowing *a priori* which Facility goes where. There is a table of default locations of :ref:`syslog_logfiles` for various OSs; if you're running something not listed there and you know where the various Facilities go, please either submit a PR on GitHub, or let me know in the `forum <https://forums.invis.net/c/wp-fail2ban-support/documentation>`_.

67 changes: 67 additions & 0 deletions configuration/mu-plugins.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
.. _configuration__mu-plugins:

`mu-plugins` Support
--------------------

There are two main reasons for using `mu-plugins`:

#. You need to load *WPf2b* before other security plugins [#f1]_,
#. You don't trust the site administrators.

Loading Early
^^^^^^^^^^^^^

One of the better ways is to install *WPf2b* as usual and then create a symlink in ``mu-plugins``:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban/wp-fail2ban.php
or for the Premium version:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban-premium/wp-fail2ban.php
This has the advantage that you can update *WPf2b* as usual without having to update ``mu-plugins`` directly. For the free version you don't need to activate *WPf2b*, but you do for the Premium version.

Forcing Usage
^^^^^^^^^^^^^

The main objective here is to stop people fiddling with things, so there are necessarily some restrictions on configuring *WPf2b*.

*WPf2b* must be configured in ``wp-config.php`` - you can't use the Premium config UI; not only does it make no sense, it won't work [#f2]_.

The actual configuration itself is simple; for the **Free** version:

#. Extract the **Free** version of *WPf2b* into a directory called `wp-fail2ban` within `mu-plugins`.
#. symlink ``wp-fail2ban.php``:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> wp-fail2ban/wp-fail2ban.php
3. **Keep** *WPf2b* **up-to-date**.

For the **Premium** version:

#. Extract the **Premium** version of *WPf2b* into a directory called `wp-fail2ban-premium` within `mu-plugins`.
#. symlink ``wp-fail2ban.php``:

.. code-block:: sh
lrwxr-xr-x 1 www www 38 4 Nov 16:24 wp-fail2ban.php -> wp-fail2ban-premium/wp-fail2ban.php
3. **Keep** *WPf2b* **up-to-date**.

Keeping *WPf2b* up-to-date
""""""""""""""""""""""""""

It's that last step that catches out most people - WordPress doesn't check ``mu-plugins`` for updates, so by configuring *WPf2b* in this way **you are taking responsibility** for keeping *WPf2b* up-to-date. I do my best, but I cannot guarantee there will never be a critical problem with *WPf2b* - you and you alone are responsible for checking for updates and installing them.


.. rubric:: Footnotes

.. [#f1] For example, WordFence, which assumes it's the only one.
.. [#f2] It may look like it works now, but in a future release it will be blocked.
11 changes: 11 additions & 0 deletions configuration/wp-fail2ban.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
.. _configuration__wp-fail2ban:

WP fail2ban
-----------

The Free version of *WPf2b* is configured by defining constants in ``wp-config.php``. If you're using the Permium version, or you know your way around ``wp-config.php`` already, skip ahead to :ref:`configuration__logging`.

The first step is to check you can edit your ``wp-config.php`` file. If you're not sure how to do that you'll need to contact your hosting provider - for now you can skip ahead to configuring :ref:`configuration__fail2ban`.

The second step is to **take a backup** of ``wp-config.php``. We're not going to touch any other part of WordPress, so if anything goes wrong and your site stops working, restoring this backup should get you running again.

0 comments on commit a160fb9

Please sign in to comment.