Plugin Configuration
Settings are on the pages of the Logystera menu in your WordPress admin: Credentials, Settings and the others described in the Admin Panel Reference.
Connection
Credentials are configured automatically when you use the Connect to Logystera button (see Installation). You can also enter them manually on the Credentials page.
| Setting | Description |
|---|---|
| Gateway URL | Gateway endpoint. Leave as default unless self-hosting. |
| Entity Token | Your entity's public token. Required. |
| Entity Secret | Your entity's HMAC signing secret. Required. Never expose publicly. |
To rotate credentials, use Rotate Credentials on the Credentials page — new credentials are delivered automatically.
Event Capture
Configure under Event Capture on the Settings page.
| Setting | Default | Description |
|---|---|---|
| Collect | On | Enable/disable local event capture. When off, no events are written to the buffer. |
| Ingest | On | Enable/disable shipping to the gateway. When off, events stay local. Automatically disabled when Collect is off. |
Delivery
| Setting | Default | Description |
|---|---|---|
| Batch size | 100 on new installs | Events sent in one request to the gateway, from 50 to 1000. Larger batches mean fewer requests; smaller ones keep each request short on slow hosts. |
| Flush interval | Every 5 minutes | How often the scheduled send runs: every minute, 2, 5 or 15 minutes. |
Batch Size and Flush Interval are disabled when Ingest is off.
Page visits only record events to a file on your server; sending happens on the scheduled run, or when you click Send Now (Flush Queue) on the Status page. With WordPress's built-in cron the scheduled run only happens when someone loads a page, so a quiet site may send later than the interval. With a system cron (DISABLE_WP_CRON) the interval is the minimum gap between sends and cannot be shorter than your host's cron schedule. See Setup and Sending.
Since 1.0.0, on servers that cannot finish a response before sending (typically Apache with mod_php), a send made at the end of a request is capped at about one second and one batch; anything left is delivered by the scheduled send.
Privacy
| Setting | Default | Description |
|---|---|---|
| Anonymize IPs | On | Truncate IPs to /24 (IPv4) or /48 (IPv6) before sending. |
When IP anonymization is enabled:
labels.actor.ipon every non-system signal is truncated (IPv4 → /24, IPv6 → /48).payload.ip_hashonwp.rest.enumerationandwp.waf.eventis hashed from that truncated address, not the raw IP. With the setting off, those hashes stay the raw-IP pseudonym (unsalted SHA-256 truncated to 16 hex chars — fleet-joinable, not irreversible for IPv4).203.0.113.42→203.0.113.02001:db8:1234:5678::1→2001:db8:1234::
Usernames are always HMAC-SHA256 hashed. Whether the raw name is also sent is controlled by two independent settings in the Privacy group of Event Hooks below:
- Readable attempted usernames (default on) — sends the name tried at a failed login, but only when WordPress confirms it belongs to a real account and the name contains no
@. Turn this off to report only the hash and whether the account exists, never the raw name. - Readable e-mail logins (default off) — on a site where an account's own username is an email address, sends that address on user-lifecycle and file-edit events instead of the
[email]placeholder. An ordinary (non-email) username on those events is sent readable either way.
The plugin integrates with the WordPress Privacy Policy guide via wp_add_privacy_policy_content(). When editing your site's Privacy Policy page, a suggested Logystera section is available in the policy guide sidebar.
Local history
The plugin can maintain a local MySQL history of events for review in the admin panel.
| Setting | Default | Description |
|---|---|---|
| Enable Local Event History | Off | Store shipped events in MySQL for browsing on the Events page. |
| Max events | 10,000 | Maximum events stored locally. Gateway-managed — not user-editable. |
| Retention | 7 days | How long to keep history. Gateway-managed, read-only. |
Tables created: wp_logystera_events and wp_logystera_gateway_logs (via dbDelta on enable). Tables are kept when the feature is disabled (data preserved for re-enabling). Use Wipe local history to permanently drop tables.
Event hooks
Individual signal groups are toggled on the Settings page, under Advanced settings → Event Hooks. Check all and Uncheck all change every hook at once; click Save Event Settings to apply. Hooks are organized into these groups:
Identity & Access
| Hook | Default | Description |
|---|---|---|
| HTTP request tracking | On | Record requests that reach WordPress. |
| Firewall-blocked requests | Off | Record requests that end before WordPress finishes loading. Coverage depends on how the firewall is loaded; the Status page shows it for your site. |
| Wordfence block log | Off | Under Wordfence Extended protection, read the blocks Wordfence recorded in its own log (read-only). |
| Firewall security decisions | On | Record supported firewall decision events such as lockouts, blocks and throttles. |
| Sensitive file probes | On | Record when a request for a sensitive file (wp-config.php backups, debug.log, .env and similar) is answered with a 2xx instead of being blocked. |
| Login attempts | On | Track successful and failed logins. Essential for brute-force detection. |
| Logout events | On | Track explicit user logouts. |
| User signals | On | Track new user registrations and admin role changes. |
| Denied permission checks | On | Record when a logged-in user is refused a capability. A run of refusals on one account can show a privilege-escalation attempt. |
| REST API enumeration | On | Record requests to REST endpoints that list or look up users and other content, a common way to collect usernames before a login attack. |
| XML-RPC calls | On | Record one summary per XML-RPC request that got past login. Failed XML-RPC logins are covered by Login attempts. |
Security
| Hook | Default | Description |
|---|---|---|
| Content and comment changes | On | Record when published posts, pages or comments change: counts of links (including hidden ones), sizes, and who made the change (as a hash). The text itself never leaves your site. With this off, injected spam links in your content are not detected. |
File Uploads
| Hook | Default | Description |
|---|---|---|
| Blocked uploads | On | Track attempts to upload dangerous file types (.php, .exe, etc.). |
Configuration & Supply Chain
| Hook | Default | Description |
|---|---|---|
| Email signals | On | Track email send success and failure with metadata (recipient count, subject category). |
| Plugin/theme/core changes | On | Track plugin activations and deactivations, theme switches, and core, plugin and theme updates. |
| Vulnerability & update monitoring | On | Send a snapshot of installed plugins and themes with their versions, plus an administrator-account summary and configuration facts, about once a day. Known-vulnerability and outdated-software checks run against it. |
| Security-relevant option changes | On | Record changes to a fixed list of options an attacker has reason to change, such as site URL, admin email, open registration, the default role for new users and active plugins. |
| Theme file editor | On | Record each save attempt from the built-in theme file editor: which file, who saved it, content hashes and sizes, and whether the new code looks obfuscated. |
| Plugin file editor | On | The same for the built-in plugin file editor. |
Traffic
| Hook | Default | Description |
|---|---|---|
| Search queries | On | Track site search queries for top-searches analysis. |
Health & Errors
| Hook | Default | Description |
|---|---|---|
| Cron health | On | Track missed scheduled posts and overdue cron jobs. |
| File integrity | On | Detect changes to wp-config.php and .htaccess by hash comparison. |
| Plugin, theme and upload files | Off | Watch plugin, theme and uploads folders for PHP files that change or appear outside normal updates, and for executable files in uploads. Only file names, sizes and fingerprints are sent. |
| Environment snapshot | On | Report WordPress version, PHP version, plugin count and theme on each flush cycle. |
| Fatal errors | On | Capture PHP fatal errors. Essential for incident detection. |
| PHP warnings | On | Capture individual PHP warnings and notices with file, line and plugin attribution. |
| Database errors | On | Track $wpdb errors (deadlocks, connection failures, etc.). |
| Memory warnings | On | Alert when PHP memory usage exceeds 90% of the limit. |
| Webhook delivery results | On | Record the result of each webhook the Gravity Forms Webhooks add-on sends. Changes nothing on a site without that add-on. |
| Failed outbound requests | On | Record when a request this site makes to another server fails or times out. Only the destination host, the plugin that made the request and the kind of failure are sent. |
Performance (Advanced)
Off by default. Enable with caution on shared hosting.
| Hook | Default | Description |
|---|---|---|
| Hook timing | Off | Track execution time of WordPress hooks. Sampled at 10% of requests. |
| Cache statistics | Off | Track the object cache hit/miss ratio and backend type. |
| Slow queries | Off | Track database queries exceeding 500ms. Sampled at 10% of requests. Works best with SAVEQUERIES defined. |
| Agent overhead | Off | Measure the time and memory the plugin itself costs a request. |
| Hook circuit breaker | Off | Stop measuring a hook that keeps running long, so the measurement cannot become the cost. |
Privacy
| Hook | Default | Description |
|---|---|---|
| Anonymize IPs | On | Mask IPs before sending (see Privacy above). |
| Readable attempted usernames | On | Send the name tried at a failed login when it matches a real account. Off reports only a hash and whether the account exists, never the raw name. |
| Readable e-mail logins | Off | On a site where a username is itself an email address, send that address on account-lifecycle and file-edit events instead of [email]. Does not affect login attempts. |
Visitor IP behind Cloudflare or another proxy
If your site sits behind Cloudflare (or another reverse proxy), the agent resolves each visitor's IP from REMOTE_ADDR by default — and Cloudflare's edge address is a normal, publicly routable IP, not an internal one. The agent doesn't trust X-Forwarded-For / X-Real-IP automatically in that case, on purpose: those headers are just as easy for a malicious visitor to set as for a real proxy, so trusting them without knowing a proxy actually sits in front of the site would let anyone claim to be any IP. The result, until you configure it: every visitor is recorded as one of a handful of Cloudflare addresses, and per-visitor detection (failed logins, brute-force, login anomalies) can't tell them apart.
Two wp-config.php constants control this:
| Constant | Type | What it does |
|---|---|---|
LOGYSTERA_TRUST_PROXY_HEADERS |
boolean | When true, always trust X-Forwarded-For / X-Real-IP to resolve the visitor IP. Without it, the agent only trusts those headers when REMOTE_ADDR looks like an internal hop (a private/reserved address) — which a Cloudflare-fronted site never is. |
LOGYSTERA_TRUSTED_PROXIES |
array or comma-separated string | Extra proxy IPs to peel off the X-Forwarded-For chain, for setups with more than one hop in front of the site (your own load balancer in front of Cloudflare, for example). Exact-IP match only — no CIDR ranges. Not needed for a plain Cloudflare setup. |
Before setting LOGYSTERA_TRUST_PROXY_HEADERS, lock your origin server so it only accepts traffic from Cloudflare's IP ranges. Without that, a client can bypass Cloudflare, connect to your origin directly, and forge the same headers itself — exactly the spoofing this setting is meant to avoid. Once the origin is locked, add:
// wp-config.php
define( 'LOGYSTERA_TRUST_PROXY_HEADERS', true );
To confirm it worked, open Logystera → Debug (the Debug page) and check the Client IP & Proxy card: it shows the resolved client IP, REMOTE_ADDR, the X-Forwarded-For chain with each hop classified, and whether headers are currently trusted, with a ✅ once the resolved IP matches the real visitor instead of a Cloudflare address. See Troubleshooting → All visitors show as the same few IP addresses if it's still wrong.
wp-config.php constants
A small number of settings can be set via wp-config.php constants. Constants take precedence over database settings.
| Constant | Description |
|---|---|
LOGYSTERA_DEBUG |
Enable debug logging to wp-content/debug.log. |
LOGYSTERA_GATEWAY_DEFAULT |
Override the default gateway URL (shown as default in the UI). |
LOGYSTERA_FLUSH_BUDGET |
Time limit in seconds for a single cron flush run. Example: define('LOGYSTERA_FLUSH_BUDGET', 30.0); |
LOGYSTERA_TRUST_PROXY_HEADERS |
Trust X-Forwarded-For / X-Real-IP for the visitor IP. See Visitor IP behind Cloudflare or another proxy above. |
LOGYSTERA_TRUSTED_PROXIES |
Proxy IPs to peel from the X-Forwarded-For chain on multi-hop setups. See above. |
WP-Cron dependency
The plugin uses WP-Cron for two scheduled tasks:
| Cron hook | Interval | Purpose |
|---|---|---|
logystera_flush_queue_event |
Every 5 minutes (configurable) | Flush buffered events to gateway |
logystera_agent_heartbeat_event |
Every 15 minutes | Heartbeat check — missing heartbeat triggers an alert |
If your server uses DISABLE_WP_CRON = true and runs WordPress cron externally, make sure your cron job calls wp-cron.php at least as often as your Flush interval; every minute is the usual choice. Setup and Sending shows how.