Configuration & Setup Guide

Complete implementation workflow, token permissions architecture, and fallback configuration strategies.

1. Cloudflare Token Permissions

To synchronize IP addresses securely, you must create a custom API Token on your Cloudflare dashboard with restricted write capabilities. For reference, you can consult the official Cloudflare API Token Documentation ↗. Do NOT use your Global API Key in production.

⚠️ Required Token Permissions Scope

The token must be authorized with exactly the following scope:
Account > Account Filter Lists > Edit
If this specific scope is missing, the API Client will trigger a 403 Forbidden error and suspend synchronization.

Steps to create the token:

  1. Log in to your Cloudflare Dashboard.
  2. Go to the top right profile icon and select My Profile > API Tokens.
  3. Click Create Token, choose Create Custom Token.
  4. Give the token a name (e.g., WP Cerber lockout sync).
  5. Under Permissions, select:
    • Account | Account Filter Lists | Edit
  6. Under Account Resources, select your target account.
  7. Complete verification and copy the generated token string.

2. WordPress Configuration

Once you install the plugin zip, configure it directly within the WordPress dashboard.

3. Credential Fallback Resolution

The plugin resolves Cloudflare credentials dynamically. If database settings are empty, it searches other system contexts in the following order:

Priority Hierarchy:

  1. Plugin Settings: Values submitted via the settings form (stored in wp_options).
  2. PHP Constants: Values declared in wp-config.php (never stored in the database).
  3. Cloudflare Official Plugin: Configuration values from the official WordPress Cloudflare plugin database entries.

🔒 Security Recommendation: Use PHP Constants

When credentials are saved via the settings form, they are stored as plaintext in the WordPress database (wp_options table). This means they can be exposed through:

  • Database backups stored without encryption
  • SQL injection vulnerabilities in other plugins
  • Compromised database admin tools (e.g., phpMyAdmin)
  • Shared hosting environments with weak isolation

For production environments, define your credentials as PHP constants in wp-config.php instead. This keeps sensitive tokens out of the database entirely. The wp-config.php file resides on the server filesystem and — on properly configured hosts — is located outside the public web root.

Defining constants in wp-config.php:

Add the following lines to your wp-config.php file, above the line that reads /* That's all, stop editing! */:

// Cerber Lockout Cloudflare Sync — Credentials
define( 'CLOUDFLARE_API_TOKEN',  'your_cloudflare_api_token_here' );
define( 'CLOUDFLARE_ACCOUNT_ID', 'your_32_char_account_id_here' );
define( 'CLOUDFLARE_LIST_ID',    'your_32_char_list_id_here' );

All Supported Constants:

The following constants are recognised by the plugin. Only CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_LIST_ID are required.

Constant Description Required
CLOUDFLARE_API_TOKEN API Token with Account Filter Lists: Edit permission. This is the recommended authentication method. Yes *
CLOUDFLARE_ACCOUNT_ID Your Cloudflare Account ID (32-character hex string, found on the dashboard overview page). Yes
CLOUDFLARE_LIST_ID The ID of the target IP List (32-character hex string, found under Configurations > Lists). Yes
CLOUDFLARE_API_KEY Legacy Global API Key. Used only if CLOUDFLARE_API_TOKEN is not defined. Not recommended — grants full account access. No
CLOUDFLARE_EMAIL Account email associated with the Global API Key. Required only when using CLOUDFLARE_API_KEY. No

* If CLOUDFLARE_API_TOKEN is not defined, the plugin will attempt to resolve credentials from CLOUDFLARE_API_KEY or the official Cloudflare plugin's stored settings.

4. Notification Alerts

The plugin contains an alert system. By default, it emails the administrator if the Cloudflare API returns an authorization error (such as an expired token). The notification email is rate-limited to 1 email per hour to prevent server load or email server blocklisting during an active attack.

You can also enable Success Notifications in the configuration screen to receive alerts for every successful IP block sync.

5. Cloudflare List Capacity & Monitoring

Cloudflare Account IP Lists have a strict capacity limit of 10,000 items. If the list is saturated, Cloudflare will reject new IP additions, causing synchronization to fail.

Capacity Tracking: