VelocityIPLogger

VelocityIPLogger is a Velocity proxy plugin for moderation and security auditing. It builds historical correlations between player UUIDs, usernames, and IP addresses, logs connection activity, and enriches IP records with local GeoIP MMDB data. Player lookups are local; no per-player external API requests are made.

What it does

• Builds long-term UUID, username, and IP correlation records.
• Logs connection and disconnection events with timestamps, session IDs, and session duration.
• Enriches IP records with country, region, city, timezone, ISP, ASN, latitude, longitude, and lookup status when GeoIP logging is enabled.
• Stores data in plain TSV files under plugins/velocityiplogger/ for review, export, and external analysis.
• Supports configurable logging controls for usernames, IPs, GeoIP enrichment, TSV outputs, console logs, command access, and retention pruning.
• Caches GeoIP lookups in memory for faster repeated lookups.

Why you would want it

If you investigate ban evasion, alt accounts, account sharing, or suspicious activity, this plugin gives you fast historical identity/IP evidence for operational moderation workflows.

GeoIP providers

Two providers are supported through config.yml:

• DB-IP default: no account required, uses DB-IP City Lite and ASN Lite MMDB downloads.
• MaxMind GeoLite2: requires a MaxMind account/license key, uses GeoLite2 City and ASN downloads.

Databases are downloaded when needed, refreshed after the configured staleness interval, and can be forced immediately with /viplookup updatedb.

Commands

Commands are console-only by default. Set commands.allow-admin-permission: "true" to also allow players with velocityiplogger.admin to use them.

Command	Description
/viplookup uuid <uuid>	Look up all data for a UUID
/viplookup username <name>	Look up all data for a username
/viplookup ip <ip>	Look up all data for an IP
/viplookup reload	Reload config without restarting the proxy
/viplookup updatedb	Force immediate GeoIP database redownload
/viplookup checkupdates	Manually check GitHub Releases for a newer stable version

Aliases: /viplog, /iplookup, /iplog

Additional subcommand aliases are also accepted: user, name, update-db, refreshdb, checkupdate, updatecheck, update-check, and updates.

Privacy and network disclosure

This plugin can store UUIDs, usernames, IPs, connection timestamps, session durations, and optional GeoIP enrichment. Logging fields, TSV outputs, console output, retention, and player command access are configurable.

Outbound network activity is limited to:

• GeoIP database downloads when needed.
• Optional scheduled stable-release update checks against GitHub Releases, enabled by default.
• Manual update checks when /viplookup checkupdates is run.
• Optional anonymous telemetry pings to NamelessTelemetry, enabled by default.

Telemetry does not send player UUIDs, usernames, player IPs, connection logs, or GeoIP data. It sends only a hashed local instance ID, UTC date, project name, and count. Set telemetry.enabled: "false" to disable it.

Treat stored identity/IP data as sensitive and set retention policies appropriate for your jurisdiction and server policy.

Nightly auto-builds

Nightly development builds are published automatically from the latest main or master branch changes, and can also be triggered manually.

https://github.com/NanashiTheNameless/VelocityIPLogger/releases/tag/nightly

Nightly builds are intended for testing and may change more frequently than stable versioned releases. Built-in update checks ignore prereleases and the nightly tag.