About
LiteBans is a lightweight banning plugin supporting UUIDs which allows temporary and permanent bans.
When a player changes their Minecraft name through Mojang, they will still keep their bans, mutes, and warnings.
All punishments made through LiteBans will take effect globally across all servers linked to the same database.
Although LiteBans is designed to effectively synchronize between hundreds of servers, it can still work alone on a single server without a MySQL database.
LiteBans can run natively under Spigot and BungeeCord, offering the same features on both platforms.
(The plugin can be installed in the Spigot plugin folder or the BungeeCord plugin folder.)
Features
One of the best features of LiteBans for networks is its cross-server synchronization system.
LiteBans does not store the full database in memory. It queries the database whenever a player joins. This means that the plugin is almost entirely stateless and most of the synchronization is already achieved by design, as plugin state does not have to be synchronized between servers.
It also means that there is no overhead. If there are 2 million active bans stored in the database, the plugin uses the same amount of memory as it would if there were no bans stored in the database at all. Plugin performance will mostly depend on your database server, since the plugin is multithreaded and uses connection pooling to get as much performance as possible.
The only active synchronization which has to be performed by LiteBans is for broadcasts and punishments affecting online players. Unbans are not synchronized since bans are not stored in memory.
Cross-server synchronization does not depend on BungeeCord since the plugin doesn't utilize plugin messaging channels.
Since the Spigot and BungeeCord versions of the plugin share the same code and are both equally stateless, they can synchronize with each other as well without any additional configuration. This works in both directions.
For example:
Server A, Server B and Server C are all running LiteBans, connected to the same MySQL database.
If a player who is on Server A is muted on Server B, it will immediately take effect on Server A, the player will be muted, and all players on Server A, B and C will see the broadcast indicating that the player was muted if they have permission and if broadcast synchronization is enabled. If the player leaves Server A and joins Server B or Server C, they will still be muted.
This applies to both Spigot and BungeeCord versions of the plugin.
A BungeeCord proxy counts as a server, and all servers under the BungeeCord proxy will also be affected by the plugin
(if the plugin is installed in the Bungee plugin folder).
JSON Support
LiteBans allows you to define custom hover text in all messages, including broadcasts.
Only players with permission (litebans.json.hover_text) will see the hover text.
All variables available to use in messages.yml can also be included in hover text, along with colors and newlines.
The only important thing is that the target is provided, and the reason is provided after the target. The duration can be provided anywhere, even after the reason.
If the duration is not provided, a permanent ban will be placed.
These flags can be used for bans, mutes, warnings, and kicks:
When a ban is placed, all online players who match the ban will be kicked.
You can ban online and offline players, including players that have never joined the server before.
Other commands that accept a target and reason (/mute and /warn) can be used in the same way as the ban command.
Arguments: <REQUIRED> [OPTIONAL]
Valid units: (s)econds, (m)inutes, (h)ours, (d)ays, (w)eeks, (mo)nths, years.
Time unit examples (All of these commands are valid):
Code (Text):
/ban Player 3 days [reason]
/ban Player 3d [reason]
/ban Player 3days [reason]
/ban Player 1 day [reason]
/ban Player 1day [reason]
The mute command (/mute [-s] <target> [duration] [reason] [server:*]) allows you to mute a player. While a player is muted, they cannot talk in chat or use blacklisted commands.
Related commands: /tempmute (requires duration), /ipmute, /unmute
The warn command (/warn [-s] <target> <reason> [server:*]) allows you to warn a player. Warnings expire after a configurable duration. When a player obtains a configurable amount of warnings, configurable commands can be executed.
Related commands: /unwarn (removes a player's last warning)
The history command (/history <target> [server:*]) shows bans, mutes, kicks, and warnings that a player has received recently, sorted by date.
You can view active warnings for a player by using /warnings <target>.
/staffhistory <target> can be used to show bans, mutes, kicks and warnings placed by a player.
/prunehistory <target> [duration] can be used to clear the punishment history of a player.
Example: /prunehistory Player 5 days
/staffrollback <target> [duration] can be used to rollback all staff actions (bans, mutes, warnings, kicks) with an optional duration.
For /prunehistory and /staffrollback, the duration provided means the time passed since today.
If you use "/staffrollback StaffMember 3 days", all punishments executed by StaffMember within the last 3 days will be removed.
Note: These two commands cannot be undone, unless you have backups.
The dupeip command (/dupeip <target>) allows you to view all accounts who have joined on the same IP as the target, and see whether they're online, offline, or banned.
You can also use /ipreport which executes a dupeip check for all online players.
You can also use /iphistory to check the recent IP addresses that a player has joined the server with. (Requires "delete_previous_history: false" in config.yml)
The checkban command (/checkban <target>) allows you to check if a target is banned. It will also tell you when the ban was placed, when it will expire, whether the ban was an IP ban, and if it was a silent ban.
Related commands: /checkmute
The kick command (/kick [-s] <player> <reason>) allows you to kick an online player. This will be recorded in the player's history.
You can also kick players from other servers running LiteBans connected to the same database.
This applies to both Spigot and BungeeCord versions of the plugin and does not strictly require BungeeCord.
If a player is on Proxy A and you use /kick from Proxy B, they will be kicked from Proxy A.
The geoip command (/geoip <target>), if enabled in the configuration, allows you to check which country a player comes from. This can also be used on offline players.
You can check the UUID of a player (online or not) using /lastuuid <target>.
Chat can be cleared with /clearchat. Players with the "litebans.notify.clearchat" permission will be notified when chat is cleared.
You can view a list of active bans by using /banlist [page].
You can reload the configuration at any time using /litebans reload.
This will reload config.yml and messages.yml, and apply new settings.
Reloading LiteBans will also make it reconnect to the database.
The server can be put into lockdown mode by using /lockdown <reason>. All players without the bypass permission will be kicked when the lockdown starts, and will be unable to join until it ends. It can be ended with /lockdown end.
Under BungeeCord, you can provide a server scope for /lockdown. Currently only one scope at a time can be affected by /lockdown.
Example: /lockdown <reason> server:Survival
Global lockdown for ALL servers on the same network: /lockdown <reason> server:*
Note: /togglechat can not be used with the BungeeCord version of the plugin.
Chat can be toggled for users with the litebans.togglechat permission using /togglechat. This command allows users to "toggle off" incoming messages from other players.
For exempt permissions to work, a player needs litebans.exempt or litebans.exempt.<type>. For example, if Admin is trying to ban Player, first Player is checked for litebans.exempt, then litebans.exempt.ban. If Player has either of those permissions, Admin is checked for litebans.exempt.bypass, then litebans.exempt.bypass.ban. If Admin has either of these permissions, Player is banned anyway.
Configuration
All options in the configuration work equally on both Spigot and BungeeCord versions of the plugin unless explicitly otherwise stated.
Plugin configuration (config.yml):
The default config.yml can be viewed here.
Custom messages (messages.yml):
The default messages.yml can be viewed here.
All variables are now documented in messages.yml and can be viewed above.
Database Configuration
The plugin is pre-configured for H2, so you don't need to configure anything if you don't have a MySQL database.
H2 does not require any configuration, and operates using files on disk.
To configure the plugin for MySQL, open config.yml, change 'driver' to "MySQL", and set 'username', 'password', 'address', and 'database' as needed.
Images
Requirements
For MySQL support in the plugin, a working MySQL database is required.
If you're running a single plugin instance and don't need the web interface, you do not need a MySQL server and the plugin will already work immediately without configuration after being installed.
Supported Java versions: Java 10, Java 9, Java 8, Java 7.
An active Internet connection is required, but only for the first time the plugin is started without access to needed database drivers.
LiteBans will download these drivers once and it will never download them again afterwards as long as they are stored in the LiteBans data folder.
When the plugin is updated, drivers may be updated as well.
If you want to use Cauldron, you may have to follow the instructions in this post if the plugin fails to load.
Cauldron 1.7.10 is supported.
Cauldron 1.6.4 is not supported and will never be supported.
Install
LiteBans can be installed in several ways. It can run on a single Spigot server, multiple Spigot servers linked to the same MySQL database, or it can be installed directly on BungeeCord.
If you are connecting the plugin to a MySQL database across multiple servers, do not copy server.yml. This file is uniquely generated for each server. If you have copied it, delete it and it will be re-generated.
If you want LiteBans to have a Spigot presence (Spigot permissions, usable with Spigot plugins that use /ban, /mute, /kick, etc), then you can install it on each Spigot server and link all plugin instances together with the same database.
Otherwise, if you're fine with using the Bungee permission system (e.g. BungeePerms or permission configuration in Bungee's config.yml) and don't have any Spigot plugins which need to use LiteBans commands, then you can install it on BungeeCord directly and you don't have to install it on any of the servers connected to the proxy.
After installing multiple instances of the plugin, you can check if everything is properly configured
by running the "/litebans info" command. It will tell you if multiple servers are connected to the database.
Remember not to copy the server.yml file across multiple servers.
Spigot version vs BungeeCord version
LiteBans can run directly under Spigot or BungeeCord -- it can be installed in either the Spigot plugin folder, or the BungeeCord plugin folder.
All commands and features of LiteBans are available under BungeeCord (except for /togglechat).
Features of the BungeeCord version:
LiteBans is a lightweight banning plugin supporting UUIDs which allows temporary and permanent bans.
When a player changes their Minecraft name through Mojang, they will still keep their bans, mutes, and warnings.
All punishments made through LiteBans will take effect globally across all servers linked to the same database.
Although LiteBans is designed to effectively synchronize between hundreds of servers, it can still work alone on a single server without a MySQL database.
LiteBans can run natively under Spigot and BungeeCord, offering the same features on both platforms.
(The plugin can be installed in the Spigot plugin folder or the BungeeCord plugin folder.)
Features
- Designed from the ground up with UUID support in mind. All punishments are UUID-based.
- Fully customizable kick screen for banned players, multiple lines and colours can be used, as well as ban information variables – duration until ban expires, reason, staff member who placed the ban, time since ban was placed, original ban duration, server which ban was placed on, etc.
- All messages are customizable in messages.yml. There are many useful variables available to place in any configurable message that involves a ban, mute, or warning. Hover-text is supported.
- Multiple types of databases are supported, including MySQL, MariaDB, and H2. H2 is used by default, meaning that MySQL is not needed to use LiteBans with a single-server setup.
- Advanced light cross-server synchronization system allows global punishments and broadcasts to instantly take effect across all servers connected to the same database.
- Offline players can receive warnings; they will see all of their new warnings when they join. This works across servers.
- When a player with a banned account on the same IP joins, all players with the right permissions will be notified.
- You can view punishment history for players (/history) and punishments issued by staff members (/staffhistory).
- Staff members can be "rolled back" – all punishments which they've issued can be removed at any time with a single command. Staff abuse has never been easier to deal with.
- Players cannot override punishments by setting very short bans or mutes unless they have permission.
- Bans can be imported from vanilla (including Essentials), and six popular free banning plugins, including MaxBans, BanManager, AdvancedBan, and BungeeAdminTools.
- Lightweight, multithreaded, and designed for performance. LiteBans uses a minimal amount of memory and does not block the main server thread with any database queries after startup.
One of the best features of LiteBans for networks is its cross-server synchronization system.
LiteBans does not store the full database in memory. It queries the database whenever a player joins. This means that the plugin is almost entirely stateless and most of the synchronization is already achieved by design, as plugin state does not have to be synchronized between servers.
It also means that there is no overhead. If there are 2 million active bans stored in the database, the plugin uses the same amount of memory as it would if there were no bans stored in the database at all. Plugin performance will mostly depend on your database server, since the plugin is multithreaded and uses connection pooling to get as much performance as possible.
The only active synchronization which has to be performed by LiteBans is for broadcasts and punishments affecting online players. Unbans are not synchronized since bans are not stored in memory.
Cross-server synchronization does not depend on BungeeCord since the plugin doesn't utilize plugin messaging channels.
Since the Spigot and BungeeCord versions of the plugin share the same code and are both equally stateless, they can synchronize with each other as well without any additional configuration. This works in both directions.
For example:
Server A, Server B and Server C are all running LiteBans, connected to the same MySQL database.
If a player who is on Server A is muted on Server B, it will immediately take effect on Server A, the player will be muted, and all players on Server A, B and C will see the broadcast indicating that the player was muted if they have permission and if broadcast synchronization is enabled. If the player leaves Server A and joins Server B or Server C, they will still be muted.
This applies to both Spigot and BungeeCord versions of the plugin.
A BungeeCord proxy counts as a server, and all servers under the BungeeCord proxy will also be affected by the plugin
(if the plugin is installed in the Bungee plugin folder).
JSON Support
LiteBans allows you to define custom hover text in all messages, including broadcasts.
Only players with permission (litebans.json.hover_text) will see the hover text.
All variables available to use in messages.yml can also be included in hover text, along with colors and newlines.
The only important thing is that the target is provided, and the reason is provided after the target. The duration can be provided anywhere, even after the reason.
If the duration is not provided, a permanent ban will be placed.
These flags can be used for bans, mutes, warnings, and kicks:
- -s for silent punishments. Only online players with the permission litebans.notify.silent will be able to see the broadcast.
- -S for extra silent punishments. Only the console will see the broadcast. Requires permission litebans.extrasilent to use.
- -N to prevent existing punishments from being overridden by new punishments unless (configurable) the duration of the new punishment is higher than the old one.
When a ban is placed, all online players who match the ban will be kicked.
You can ban online and offline players, including players that have never joined the server before.
Other commands that accept a target and reason (/mute and /warn) can be used in the same way as the ban command.
Arguments: <REQUIRED> [OPTIONAL]
Valid units: (s)econds, (m)inutes, (h)ours, (d)ays, (w)eeks, (mo)nths, years.
Time unit examples (All of these commands are valid):
Code (Text):
/ban Player 3 days [reason]
/ban Player 3d [reason]
/ban Player 3days [reason]
/ban Player 1 day [reason]
/ban Player 1day [reason]
The mute command (/mute [-s] <target> [duration] [reason] [server:*]) allows you to mute a player. While a player is muted, they cannot talk in chat or use blacklisted commands.
Related commands: /tempmute (requires duration), /ipmute, /unmute
The warn command (/warn [-s] <target> <reason> [server:*]) allows you to warn a player. Warnings expire after a configurable duration. When a player obtains a configurable amount of warnings, configurable commands can be executed.
Related commands: /unwarn (removes a player's last warning)
The history command (/history <target> [server:*]) shows bans, mutes, kicks, and warnings that a player has received recently, sorted by date.
You can view active warnings for a player by using /warnings <target>.
/staffhistory <target> can be used to show bans, mutes, kicks and warnings placed by a player.
/prunehistory <target> [duration] can be used to clear the punishment history of a player.
Example: /prunehistory Player 5 days
/staffrollback <target> [duration] can be used to rollback all staff actions (bans, mutes, warnings, kicks) with an optional duration.
For /prunehistory and /staffrollback, the duration provided means the time passed since today.
If you use "/staffrollback StaffMember 3 days", all punishments executed by StaffMember within the last 3 days will be removed.
Note: These two commands cannot be undone, unless you have backups.
The dupeip command (/dupeip <target>) allows you to view all accounts who have joined on the same IP as the target, and see whether they're online, offline, or banned.
You can also use /ipreport which executes a dupeip check for all online players.
You can also use /iphistory to check the recent IP addresses that a player has joined the server with. (Requires "delete_previous_history: false" in config.yml)
The checkban command (/checkban <target>) allows you to check if a target is banned. It will also tell you when the ban was placed, when it will expire, whether the ban was an IP ban, and if it was a silent ban.
Related commands: /checkmute
The kick command (/kick [-s] <player> <reason>) allows you to kick an online player. This will be recorded in the player's history.
You can also kick players from other servers running LiteBans connected to the same database.
This applies to both Spigot and BungeeCord versions of the plugin and does not strictly require BungeeCord.
If a player is on Proxy A and you use /kick from Proxy B, they will be kicked from Proxy A.
The geoip command (/geoip <target>), if enabled in the configuration, allows you to check which country a player comes from. This can also be used on offline players.
You can check the UUID of a player (online or not) using /lastuuid <target>.
Chat can be cleared with /clearchat. Players with the "litebans.notify.clearchat" permission will be notified when chat is cleared.
You can view a list of active bans by using /banlist [page].
You can reload the configuration at any time using /litebans reload.
This will reload config.yml and messages.yml, and apply new settings.
Reloading LiteBans will also make it reconnect to the database.
The server can be put into lockdown mode by using /lockdown <reason>. All players without the bypass permission will be kicked when the lockdown starts, and will be unable to join until it ends. It can be ended with /lockdown end.
Under BungeeCord, you can provide a server scope for /lockdown. Currently only one scope at a time can be affected by /lockdown.
Example: /lockdown <reason> server:Survival
Global lockdown for ALL servers on the same network: /lockdown <reason> server:*
Note: /togglechat can not be used with the BungeeCord version of the plugin.
Chat can be toggled for users with the litebans.togglechat permission using /togglechat. This command allows users to "toggle off" incoming messages from other players.
For exempt permissions to work, a player needs litebans.exempt or litebans.exempt.<type>. For example, if Admin is trying to ban Player, first Player is checked for litebans.exempt, then litebans.exempt.ban. If Player has either of those permissions, Admin is checked for litebans.exempt.bypass, then litebans.exempt.bypass.ban. If Admin has either of these permissions, Player is banned anyway.
Configuration
All options in the configuration work equally on both Spigot and BungeeCord versions of the plugin unless explicitly otherwise stated.
Plugin configuration (config.yml):
The default config.yml can be viewed here.
Custom messages (messages.yml):
The default messages.yml can be viewed here.
All variables are now documented in messages.yml and can be viewed above.
Database Configuration
The plugin is pre-configured for H2, so you don't need to configure anything if you don't have a MySQL database.
H2 does not require any configuration, and operates using files on disk.
To configure the plugin for MySQL, open config.yml, change 'driver' to "MySQL", and set 'username', 'password', 'address', and 'database' as needed.
Images
Requirements
For MySQL support in the plugin, a working MySQL database is required.
If you're running a single plugin instance and don't need the web interface, you do not need a MySQL server and the plugin will already work immediately without configuration after being installed.
Supported Java versions: Java 10, Java 9, Java 8, Java 7.
An active Internet connection is required, but only for the first time the plugin is started without access to needed database drivers.
LiteBans will download these drivers once and it will never download them again afterwards as long as they are stored in the LiteBans data folder.
When the plugin is updated, drivers may be updated as well.
If you want to use Cauldron, you may have to follow the instructions in this post if the plugin fails to load.
Cauldron 1.7.10 is supported.
Cauldron 1.6.4 is not supported and will never be supported.
Install
LiteBans can be installed in several ways. It can run on a single Spigot server, multiple Spigot servers linked to the same MySQL database, or it can be installed directly on BungeeCord.
If you are connecting the plugin to a MySQL database across multiple servers, do not copy server.yml. This file is uniquely generated for each server. If you have copied it, delete it and it will be re-generated.
If you want LiteBans to have a Spigot presence (Spigot permissions, usable with Spigot plugins that use /ban, /mute, /kick, etc), then you can install it on each Spigot server and link all plugin instances together with the same database.
Otherwise, if you're fine with using the Bungee permission system (e.g. BungeePerms or permission configuration in Bungee's config.yml) and don't have any Spigot plugins which need to use LiteBans commands, then you can install it on BungeeCord directly and you don't have to install it on any of the servers connected to the proxy.
After installing multiple instances of the plugin, you can check if everything is properly configured
by running the "/litebans info" command. It will tell you if multiple servers are connected to the database.
Remember not to copy the server.yml file across multiple servers.
Spigot version vs BungeeCord version
LiteBans can run directly under Spigot or BungeeCord -- it can be installed in either the Spigot plugin folder, or the BungeeCord plugin folder.
All commands and features of LiteBans are available under BungeeCord (except for /togglechat).
Features of the BungeeCord version:
- Players across all servers on the network are treated as if they are on the same server.
- No need to set up LiteBans across all servers with the same MySQL configuration. One setup on just the BungeeCord proxy is enough for bans to work across every server.
- The BungeeCord version can use a local file database (H2) and still work across multiple servers (with a single-proxy setup), however, there is no official web interface support for this.
- Spigot plugins cannot override what happens at the proxy level, so it's much less likely for other plugins to interfere with LiteBans.
- LiteBans doesn't mind what type of servers you're running behind the proxy - they don't have to be Spigot servers, and there is no "bridge" plugin required. If you can get a Vanilla server running behind Bungee, you can still use LiteBans on it!
![Gangs+ [1.8-1.19] 2.24.2](/data/resource_icons/16/16470.jpg?1782808321){kind=icon}
![Combat Tag Plus [1.8 Only] [Action Bar]](/data/resource_icons/5/5222.jpg?1782790862){kind=icon}
![EpicWorldGenerator MODERN [1.21.11 / 26.1.2] Now with Multiverse Support! (EWG)](/data/resource_icons/0/839.jpg?1782116339){kind=icon}