WP Fail2Ban

https://github.com/wp-fail2ban/docs
Admin
Tokens:59,452
Snippets:82
Trust Score:4.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Register Plugin Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/developers/api/register-plugin.rst

Example of how to register a plugin using the `do_action` hook, including error handling for potential exceptions.

```php
try {
    do_action('wp_fail2ban_register_plugin', 'my-plugin-slug', 'My Plugin Name');
} catch(LengthException $e) {
    // slug or name too long
} catch(RuntimeException $e) {
    // database error
}
```

--------------------------------

### PHP Example for Logging Message

Source: https://github.com/wp-fail2ban/docs/blob/5.0/developers/api/log-message.rst

Demonstrates how to use the `do_action` hook to log a message with custom variables in PHP.

```php
function myplugin_foobar()
{
    $vars = [
        'VAR1' => 12345,
        'VAR2' => 'xyz'
    ];
    do_action(
        'wp_fail2ban_log_message',
        'my-plugin-slug',
        'my-plugin-msg-slug-1',
        $vars
    );
}
```

--------------------------------

### Example: Using LOG_LOCAL3

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_COMMENT_LOG.rst

Defines the WP_FAIL2BAN_PLUGIN_COMMENT_LOG constant, used as a facility for 'Comment' class plugin events. This example demonstrates its assignment with LOG_LOCAL3.

```php
/**
 * Facility for "Comment" class plugin events.
 */
define('WP_FAIL2BAN_PLUGIN_COMMENT_LOG', LOG_LOCAL3);

```

--------------------------------

### Example: Using LOG_LOCAL3

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_PASSWORD_LOG.rst

Defines the WP_FAIL2BAN_PLUGIN_PASSWORD_LOG constant, specifying the logging facility for 'Password' class plugin events.

```php
/**
 * Facility for "Password" class plugin events.
 */
define('WP_FAIL2BAN_PLUGIN_PASSWORD_LOG', LOG_LOCAL3);
```

--------------------------------

### WP_FAIL2BAN_PLUGIN_XMLRPC_LOG PHP Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_XMLRPC_LOG.rst

Defines the WP_FAIL2BAN_PLUGIN_XMLRPC_LOG constant, specifying the syslog facility for logging events related to the XML-RPC class plugin. This example uses LOG_LOCAL5.

```php
/**
 * Facility for XML-RPC class events.
 */
define('WP_FAIL2BAN_PLUGIN_XMLRPC_LOG', LOG_LOCAL5);

```

--------------------------------

### Example: Using LOG_LOCAL3

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PINGBACK_LOG.rst

Demonstrates how to define the WP_FAIL2BAN_PINGBACK_LOG constant using LOG_LOCAL3 for logging pingbacks. This constant configures the logging facility for pingback events.

```php
/**
 * Facility for logging pingbacks.
 */
define('WP_FAIL2BAN_PINGBACK_LOG', LOG_LOCAL3);

```

--------------------------------

### Symlink WP-Fail2Ban Free within mu-plugins

Source: https://github.com/wp-fail2ban/docs/blob/5.0/configuration/mu-plugins.rst

Creates a symbolic link for the free version of WP-Fail2Ban when its directory is directly within mu-plugins. This is an alternative setup for loading the plugin early.

```shell
# ln -s wp-fail2ban/wp-fail2ban.php
```

```shell
# ls -l
total 1
lrwxr-xr-x  1  www  www  38  4 Nov 16:24 wp-fail2ban.php -> wp-fail2ban/wp-fail2ban.php
```

--------------------------------

### fail2ban WordPress Hard and Soft Jails

Source: https://github.com/wp-fail2ban/docs/blob/5.0/configuration/fail2ban.rst

Configuration example for fail2ban WordPress jails. This snippet defines settings for both 'wordpress-hard' and 'wordpress-soft' filters, specifying log paths and retry limits for IP blocking.

```ini
[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
```

--------------------------------

### Example: Using LOG_LOCAL5

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_AUTH_LOG.rst

Demonstrates defining the WP_FAIL2BAN_PLUGIN_AUTH_LOG constant with LOG_LOCAL5. This constant specifies the logging facility for "Auth" class plugin events.

```php
/**
 * Facility for "Auth" class plugin events.
 */
define('WP_FAIL2BAN_PLUGIN_AUTH_LOG', LOG_LOCAL5);
```

--------------------------------

### Register Message Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/developers/api/register-message.rst

Demonstrates how to register a custom message using the `do_action` hook with specific arguments for wp-fail2ban. Includes error handling for potential exceptions.

```php
$args = [
    'slug'        => 'my-plugin-msg-slug-1',
    'fail'        => 'hard',
    'priority'    => LOG_NOTICE,
    'event_class' => 'Password',
    'event_id'    => 0x001F,
    'message'     => 'Message with ___VAR1___ and ___VAR2___',
    'vars'        => [
        'VAR1' => '\d+',
        'VAR2' => '*.'
    ]
];
try {
    do_action('wp_fail2ban_register_message', 'my-plugin-slug', $args);
} catch(InvalidArgumentException $e) {
    // Missing entry or invalid type
} catch(UnexpectedValueException $e) {
    // Invalid value
}
```

--------------------------------

### Example: Using LOG_LOCAL5

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_SPAM_LOG.rst

Facility for Spam class plugin events. Defines the logging facility for Spam class plugin events. This constant was introduced in version 4.2.0 and updated in 4.4.0 to use WP_FAIL2BAN_USE_AUTHPRIV.

```php
/**
 * Facility for Spam class plugin events.
 */
define('WP_FAIL2BAN_PLUGIN_SPAM_LOG', LOG_LOCAL5);
```

--------------------------------

### Example: Using LOG_LOCAL3

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PLUGIN_REST_LOG.rst

Defines the logging facility for REST class plugin events. This constant is used to specify where log messages from the REST class plugins should be directed.

```php
/**
 * Facility for "REST" class plugin events.
 */
define('WP_FAIL2BAN_PLUGIN_REST_LOG', LOG_LOCAL3);
```

--------------------------------

### Register wp-fail2ban Plugins and Messages

Source: https://github.com/wp-fail2ban/docs/blob/5.0/developers/api/example.rst

Demonstrates registering a custom plugin slug and name, then registering a custom message with variables. Finally, it shows how to log this message using the 'wp_fail2ban_log_message' action. Includes error handling for registration steps.

```php
/**
 * Registers a custom plugin and its messages with wp-fail2ban.
 */
function myplugin_wpf2b_register()
{
    // Register the plugin
    try {
        do_action(
            'wp_fail2ban_register_plugin',
            'my-plugin-slug',
            'My Plugin Name'
        );
    } catch(LengthException $e) {
        // Handle slug or name being too long
        error_log('wp-fail2ban registration error: ' . $e->getMessage());
    } catch(RuntimeException $e) {
        // Handle database errors during registration
        error_log('wp-fail2ban registration error: ' . $e->getMessage());
    }

    // Register a custom message
    $args = [
        'slug'        => 'my-plugin-msg-slug-1',
        'fail'        => 'hard',
        'priority'    => LOG_NOTICE,
        'event_class' => 'Password',
        'event_id'    => 0x001F,
        'message'     => 'Message with ___VAR1___ and ___VAR2___',
        'vars'        => [
            'VAR1' => '\d+',
            'VAR2' => '*.'
        ]
    ];
    try {
        do_action(
            'wp_fail2ban_register_message',
            'my-plugin-slug',
            $args
        );
    } catch(InvalidArgumentException $e) {
        // Handle missing entry or invalid message type
        error_log('wp-fail2ban message registration error: ' . $e->getMessage());
    } catch(UnexpectedValueException $e) {
        // Handle invalid message value
        error_log('wp-fail2ban message registration error: ' . $e->getMessage());
    }
}

// Hook the registration function to the wp_fail2ban_register action
add_action(
    'wp_fail2ban_register',
    __NAMESPACE__.'\myplugin_wpf2b_register'
);

/**
 * Logs a custom message using wp-fail2ban.
 */
function myplugin_foobar()
{
    $vars = [
        'VAR1' => 12345,
        'VAR2' => 'xyz'
    ];
    // Log the registered message with specific variables
    do_action(
        'wp_fail2ban_log_message',
        'my-plugin-slug',
        'my-plugin-msg-slug-1',
        $vars
    );
}

```

--------------------------------

### WP-FAIL2BAN_AUTH_LOG PHP Constant Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_AUTH_LOG.rst

This PHP code snippet demonstrates how to define the WP_FAIL2BAN_AUTH_LOG constant, which specifies the logging facility for Auth class events in WP-fail2ban. The example uses LOG_LOCAL5.

```php
/**
 * Facility for Auth class events.
 */
define('WP_FAIL2BAN_AUTH_LOG', LOG_LOCAL5);
```

--------------------------------

### WP Fail2Ban Blocked Users Regex Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_BLOCKED_USERS.rst

This example demonstrates defining the WP_FAIL2BAN_BLOCKED_USERS constant with a regular expression. This regex is used to block login attempts for usernames matching the pattern, helping to mitigate brute-force attacks. The plugin makes the regex case-insensitive.

```php
/**
 * Block logic
 */
define('WP_FAIL2BAN_BLOCKED_USERS', '^admin$');
```

--------------------------------

### WP Fail2Ban Blocked Users Array Example

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_BLOCKED_USERS.rst

This example shows how to define the WP_FAIL2BAN_BLOCKED_USERS constant with an array of usernames. This method is supported for PHP 7 and later, providing a straightforward way to block specific user accounts from logging in and reducing server load during attacks.

```php
/**
 * Block login
 */
define('WP_FAIL2BAN_BLOCKED_USERS', ['admin', 'another', 'user']);
```

--------------------------------

### Symlink WP-Fail2Ban Free to mu-plugins

Source: https://github.com/wp-fail2ban/docs/blob/5.0/configuration/mu-plugins.rst

Creates a symbolic link for the free version of WP-Fail2Ban into the mu-plugins directory. This method allows WP-Fail2Ban to load early and bypass standard plugin activation.

```shell
# ln -s ../plugins/wp-fail2ban/wp-fail2ban.php
```

```shell
# ls -l
total 1
lrwxr-xr-x  1  www  www  38  4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban/wp-fail2ban.php
```

--------------------------------

### Set Custom fail2ban Install Path - WP fail2ban PHP

Source: https://github.com/wp-fail2ban/docs/blob/5.0/configuration/site-health-tool.rst

This directive specifies a custom installation path for fail2ban when it's not located in the default directories like /etc/fail2ban or /usr/local/etc/fail2ban. It helps WP fail2ban locate necessary files for its operations, especially for site health checks.

```php
/** 
 * Be sure to change the path to point to your fail2ban install
 */
define('WP_FAIL2BAN_INSTALL_PATH', '/var/fail2ban');
```

--------------------------------

### Symlink WP-Fail2Ban Premium to mu-plugins

Source: https://github.com/wp-fail2ban/docs/blob/5.0/configuration/mu-plugins.rst

Creates a symbolic link for the premium version of WP-Fail2Ban into the mu-plugins directory. This is essential for ensuring the premium version loads correctly and can be managed via wp-config.php.

```shell
# ln -s ../plugins/wp-fail2ban-premium/wp-fail2ban.php
```

```shell
# ls -l
total 1
lrwxr-xr-x  1  www  www  38  4 Nov 16:24 wp-fail2ban.php -> ../plugins/wp-fail2ban-premium/wp-fail2ban.php
```

--------------------------------

### Example: Using LOG_LOCAL4

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_SPAM_LOG.rst

This PHP code snippet demonstrates how to define the WP_FAIL2BAN_SPAM_LOG constant, specifying LOG_LOCAL4 as the syslog facility for Spam class events.

```php
/*
 * Facility for Spam class events.
 */
define('WP_FAIL2BAN_SPAM_LOG', LOG_LOCAL4);

```

--------------------------------

### Example: Using LOG_LOCAL3

Source: https://github.com/wp-fail2ban/docs/blob/5.0/defines/constants/WP_FAIL2BAN_PASSWORD_REQUEST_LOG.rst

This snippet shows how to define the WP_FAIL2BAN_PASSWORD_REQUEST_LOG constant. It specifies the syslog facility to be used for logging password reset events, such as LOG_LOCAL3.

```php
/**
 * Facility for logging password reset events.
 */
define('WP_FAIL2BAN_PASSWORD_REQUEST_LOG', LOG_LOCAL3);
```
Tokens:
Raw