LibertyBans

LibertyBans is the sparkling and extraordinary weapon of punishment administration.


Why?
The existing punishment plugins all have their flaws. Either they are plagued with bugs and concurrency issues, or they are closed-source and pay-walled, or both.

None of the existing punishment plugins have a test framework which can compare to LibertyBans' extensive automated testing. This means that many bugs are caught automatically and never make it into stable releases.

LibertyBans features a full-suite of punishment-related tools. It is a general-purpose punishment plugin with a focus on effective design, quality of experience, and unbeatable code quality. It can efficiently scale to large networks and operate on single servers with minimal resources, while still offering a rich, modular feature set.

Features

• Add and remove punishments:
  • /ban, /ipban, /unban, /unbanip - bans or unbans a player or IP address
  • /mute, /ipmute, /unmute, /unmuteip - mutes or unmutes a player or IP address
  • /warn, /ipwarn, /unwarn, /unwarnip - warns or unwarns a player or IP address
  • /kick, /ipkick - kicks a player or IP address
• Temporary versions of bans, mutes, and warns
• All player data is stored using UUIDs.
• List punishments:
  • /banlist - shows all bans
  • /mutelist - shows all mutes
  • /history - shows all punishments for a player
  • /warns - shows all warns for a player
  • /blame - shows all the punishments a staff member has enacted

• Multiple means to block alt accounts:
  • Automatic enforcement to block alt accounts. By default, when using IP-bans, alts are automatically banned from joining if the main account is banned. This behavior is configurable, and you can even increase the strictness of alt-checking.
  • Manual /alts command - shows suspected alt accounts for a player.
  • Alts notification on join - tells staff members when a player whose suspected alt is banned or muted.
  • Connection limit per IP address.

• Exemption. For example, trainees cannot ban admins; admins cannot ban owners.

• Layouts & punishment templates. For example, the first mute for swearing lasts 10 days, the next is for 30 days, and the third mute is permanent. Supports calculating the reason, time, and even punishment type.

• Options and behavior are fully configurable. You can even tweak your connection pool and statement cache settings to fine-tune performance.

• The plugin is carefully designed to be performant and lightweight. It uses an efficient SQL schema which stores the raw bytes of UUIDs and IP addresses, rather than storing them as strings/text.

• Full multi-proxy and multi-instance support. You can place LibertyBans on the proxy if you use a single proxy, or on multiple backend servers.

The wiki has a lot of information, including about the configuration.

• The configuration files are extensively commented and the options are explained in detail.
• If you update LibertyBans, your old configuration will be updated automatically if there are new options.

Commands

Run:

• /libertybans usage

to show all commands. When typing this into your console, leave off the slash.

When creating temporary punishments, the same command is used for permanent punishments. Simply add the time after the username:

• /ban Player1 30d This is a temporary ban

For an extended guide, see this wiki page.

Design

• Effective and lightweight. No complicated installation and avoids unnecessary features.
• Option to use local file-based database (HyperSQL), or remote database (MariaDB, MySQL, PostgreSQL).
• Highly scalable, database-oriented performance emphasising calculations in SQL. Low memory usage because punishments are stored almost completely in the database. Best practices for connection pooling and asynchronous calculations are followed.
• Well-structured API providing a framework for other plugins to work with. An external web interface is maintained by Dmitri and it uses the API.

.


Requirements

• Java 17

Supported platforms:

• Bukkit / Spigot / Paper / Purpur (+Folia)
• BungeeCord / Waterfall
• Sponge
• Velocity

Compatibility with Geyser/Floodgate usernames. Platform forks supported where reasonable.

Due to 1.19+ chat signing, installing LibertyBans on a Velocity proxy requires SignedVelocity for mutes to work. Velocity users will need to install SignedVelocity on their proxy and backend servers, or switch to using LibertyBans on the backend servers.

Installation

LibertyBans will work out-of-the-box for most users.

If you're running a proxy:

• When using a single proxy, it is recommended to install LibertyBans on the proxy itself.
• LibertyBans can also be installed on the backend servers if you are willing to configure multi-instance synchronization.

See also this wiki page on proxy installation.

External Connections
When the plugin first starts, it downloads its internal dependencies. This is normal, and can take a couple of seconds the first time. Afterward, the plugin should start faster. The method used to download dependencies is just as secure as if the dependencies were shaded – the expected hashes of the dependencies are hard-coded, so if the downloaded dependency's hash differs, it is not saved to the filesystem.

Fun Facts

• LibertyBans was first released on 4 July 2020, Independence Day in the United States of America.
• The plugin takes more time to build a jar, including time to run automated tests, than the server software itself.
  
• The number of contributors to LibertyBans, including users reporting bugs, fits into a single chat message.
• Updates are typically released on or shortly after major holidays or days of significance.
  • 0.8.0 was released 11 September 2021.
  • 0.8.1 was released 3 days after Thanksgiving.
  • 1.0.0 was released 2 days after New Year's.
  • 1.0.1 was released 2 days after Valentine's Day.
  • 1.0.2 came out on 4 July 2022, exactly 2 years after the first release.
  • 1.0.4 was released on 11 September 2022.
  • 1.1.0-M1 was released on Christmas Day, 2022.
  • 1.1.0-M2 arrived 2 days after St. Patrick's Day.
  • 1.1.0-M3 followed, 5 days after July 4.
  • 1.1.0-RC1 was released 11 September 2023.
  • 1.1.0-RC2 was delivered on 29 February 2024.
  • 1.1.0-RC3 was released 30 March 2025.
  • 1.1.1 was released on 4 July 2025.
  • 1.1.4 was released on 4 July 2026.

Reporting Bugs
Please use Github issues: https://github.com/A248/LibertyBans/issues

But the bigger question is, can you even find any bugs?