VonixGuardian — Configuration Guide

This file is automatically generated on the first server boot. config.json is parsed as strict JSON. Comments are not allowed.

1. Canonical Configuration Reference

{
  "database": {
    "type": "sqlite",
    "file": "vonixguardian.db",
    "jdbcUrl": null,
    "user": null,
    "password": null
  },
  "queue": {
    "maxSize": 50000,
    "flushIntervalMs": 5000,
    "batchSize": 1000
  },
  "logFile": {
    "enabled": true,
    "directory": "logs/vonixguardian",
    "gzipRotated": true,
    "retentionDays": 30
  },
  "actions": {
    "logBlocks": true,
    "logContainers": true,
    "logItems": true,
    "logEntities": true,
    "logExplosions": true,
    "logChat": true,
    "logCommands": true,
    "logSessions": true,
    "logSigns": true,
    "logInteractions": true,
    "logWorldEvents": true,
    "worldBlacklist": [],
    "blockBlacklist": ["minecraft:air"],
    "sourceBlacklist": []
  },
  "permissions": {
    "useLuckPerms": true,
    "defaultOpLevel": 3
  },
  "lookup": {
    "defaultPageSize": 7,
    "maxRadius": 10000,
    "maxResultRows": 100000,
    "maxConcurrent": 4
  },
  "privacy": {
    "hashIps": false,
    "salt": "vonix-guardian-default-salt-CHANGE-ME"
  },
  "purge": {
    "minAgeSecondsConsole": 86400,
    "minAgeSecondsInGame": 2592000
  },
  "theme": "aqua"
}

2. Configuration Sections

2.1 `database` — Storage Backend

Controls the underlying persistence engine.

Key	Type	Default	Options / Valid Range	Description
`type`	string	`"sqlite"`	`"sqlite"`, `"mysql"`, `"postgresql"`	Storage dialect. SQLite is zero-configuration.
`file`	string	`"vonixguardian.db"`	Non-blank path	SQLite file path relative to server root.
`jdbcUrl`	string	`null`	JDBC URI	Required when `type` is `mysql` or `postgresql`.
`user`	string	`null`	string	Database user (ignored for SQLite).
`password`	string	`null`	string	Database password (sample: `"placeholder-password"`).

2.2 `queue` — Asynchronous Writer Pipeline

Prevents the Minecraft server tick loop from blocking on database I/O.

Key	Type	Default	Valid Range	Description
`maxSize`	int	`50000`	`> 0`	Bounded capacity of in-memory action ring buffer.
`flushIntervalMs`	long	`5000`	`> 0`	Polling interval / forced flush age in milliseconds.
`batchSize`	int	`1000`	`> 0` and `≤ maxSize`	Number of rows submitted per JDBC batch transaction.

Backpressure & Event Dropping

If the database write speed cannot keep pace with server activity and the queue reaches maxSize, new events are safely dropped to protect the server’s tick rate. A rate-limited warning is emitted to the console. Check /vg status to monitor queue depth.

2.3 `logFile` — JSON-Lines File Audit

Writes an append-only JSONL stream to disk in addition to JDBC storage.

Key	Type	Default	Description
`enabled`	boolean	`true`	Master toggle for flat-file JSON-Lines logging.
`directory`	string	`"logs/vonixguardian"`	Directory for audit files.
`gzipRotated`	boolean	`true`	Gzip yesterday’s log file automatically at midnight.
`retentionDays`	int	`30`	Keep horizon in days (`0` = retain forever).

2.4 `actions` — Category Toggles & Blacklists

Disabling a category suppresses event capture at the source hook, saving CPU and storage overhead.

worldBlacklist: Array of namespaced world IDs (e.g. ["minecraft:the_end"]).
blockBlacklist: Array of namespaced block IDs (e.g. ["minecraft:air"]). Air is blacklisted by default to avoid physics update noise.
sourceBlacklist: Array of exact sourceTag values to ignore (e.g. ["explosion:tnt"]).

2.5 `privacy` — IP Hashing & Security Warning

Key	Type	Default	Description
`hashIps`	boolean	`false`	When true, hashes player IP addresses on `SESSION_JOIN`.
`salt`	string	`"vonix-guardian-default-salt-CHANGE-ME"`	Secret salt prefix for SHA-256 IP hashing.

Security Warning: Rotate Salt Before Enabling

The default salt is an obvious placeholder. If you set hashIps = true without changing the salt, precomputed rainbow tables can reverse IP addresses trivially. Generate a 32-byte random string before enabling.

2.6 `purge` — Destructive Purge Floors

Hardcoded safety floors enforced by the configuration validator to protect historical evidence from accidental deletion:

Key	Default	Minimum Validator Floor	Human Units
`minAgeSecondsConsole`	`86400`	`≥ 60`	1 day default (console)
`minAgeSecondsInGame`	`2592000`	`≥ 3600`	30 days default (in-game)

3. Reload vs. Restart Matrix

Use /vg reload to update configuration at runtime. Parameters that modify database pools or memory buffers require a full server restart:

Section	Setting	Reload Effect	Notes
`database`	All fields	❌ Requires Restart	HikariCP pool and SQLite connection bound at startup.
`queue`	All fields	❌ Requires Restart	Buffer thread and memory ring allocated at boot.
`logFile`	`enabled`, `directory`	❌ Requires Restart	File handle and writer thread bound at boot.
`logFile`	`gzipRotated`, `retentionDays`	✅ Hot-Swapped	Applied on next rotation sweep.
`actions`	Category booleans	❌ Requires Restart	Event listener registrations occur during server start.
`actions`	All blacklists	✅ Hot-Swapped	Applied immediately to incoming filter checks.
`permissions`	`useLuckPerms`	❌ Requires Restart	Reflection probe cached during JVM initialization.
`permissions`	`defaultOpLevel`	✅ Hot-Swapped	Applied to subsequent permission checks.
`lookup`	`defaultPageSize`, `maxRadius`, `maxResultRows`	✅ Hot-Swapped	Applied to subsequent player lookup commands.
`lookup`	`maxConcurrent`	❌ Requires Restart	Thread pool executor sized at boot.
`privacy`	`hashIps`, `salt`	❌ Requires Restart	IP hasher singleton bound at boot.
`purge`	All floors	✅ Hot-Swapped	Re-read by `/vg purge` execution handler.
`theme`	`theme`	✅ Hot-Swapped	Changes chat prefix and accent colors immediately.

VonixGuardian — Configuration Guide

1. Canonical Configuration Reference

2. Configuration Sections

2.1 database — Storage Backend

2.2 queue — Asynchronous Writer Pipeline

2.3 logFile — JSON-Lines File Audit

2.4 actions — Category Toggles & Blacklists

2.5 privacy — IP Hashing & Security Warning

2.6 purge — Destructive Purge Floors