A full guide for installing, configuring and running BanManager for use in production on a Minecraft Server
The recommended installation requires the following stack:
Java 8+
Optionally MySQL or MariaDB for WebUI or cross-server synchronisation support
-
Shut down your minecraft server if running
Copy downloaded BanManager jar file to /plugins directory or /mods directory depending on server implementation
Start Minecraft server. After startup this will generate the configuration .yml files in /plugins/BanManager
or /mods/BanManager
-
By default, BanManager works without any configuration using H2. In order to leverage features such as cross server punishments and the WebUI, a MySQL or MariaDB database is required.
databases:
# Local Database is always required. If not enabled, plugin will disable on startup.
local:
enabled: true
storageType: 'h2'
host: 127.0.0.1
port: 3306
name: local_bans
user: root
password: ''
maxConnections: 10
useSSL: false
verifyServerCertificate: false
Ensure enabled
is set to true. Skip the next steps if using H2.
If using MariaDB change storageType
from mysql
to mariadb
Change connection details to match that of your database
Restart server and check logs to confirm plugin enabled
Please see FAQ for common database connection issues
Muted players will be blocked from using commands within this list. Command aliases will automatically be found and blocked, e.g. msg will block tell. Do not prefix commands here with /
Similar to mutedCommandBlacklist, but only affects players who are soft muted
Displays a warning to those with bm.notify.duplicateips permission if joining players have the same ip as a banned player
A list of IPs to exclude from the banned player duplicate check
Whether to log /kick to the database
Log join/leave history of players, if disabled only the most recent ip address will be stored
Broadcasts punishment events to those with bm.notify.X permissions
Broadcasts a message when new punishments are synced between the database and Minecraft server
Creates a custom permission to limit the length a player can punish another player for. Once configured, assign the player with the appropriate permission e.g. bm.timelimit.X.Y where X is the punishment type and Y is the custom name you have provided.
As an example, granting a player the bm.timelimit.playerBans.Moderator permission with the following configuration will only allow them to temporary ban a player for up to 1 day:
timeLimits:
playerMutes:
Moderator: 1h
playerBans:
Moderator: 1d
playerWarnings:
Moderator: 30d
ipBans:
Moderator: 1d
ipMutes:
Moderator: 1d
rollbacks:
Moderator: 1d
nameBans:
Moderator: 1d
To prevent duplicate reports you can set a cooldown to limit the amount in seconds before a player can be reported again. Set to 0 to disable.
To prevent duplicate warnings you can set a cooldown to limit the amount in seconds before a player can be warned again. Set to 0 to disable.
Execute a list of commands against a player when they reach a warning point threshold. By default, a single warning is worth 1 point. Use the -p flag when warning a player to change this, e.g. /warn confuser -p 5 Hacking.
A list of commands to execute when a player reaches a certain number of warning points. For example, the following will mute a player immediately and ban a player after 10 seconds:
actions:
'10':
- cmd: ban [player] [reason]
delay: 10
- cmd: mute [player] [reason]
Forces players to type the reason of their most recent warning before being allowed to speak in chat again. Removed on server restart or when player leaves.
This allows running commands before and after punishments
The following types are supported:
ban
tempban
unban
mute
tempmute
unmute
warn
tempwarn
ipban
tempipban
unbanip
iprangeban
A list of commands to execute either before or after a particular punishment. For example, the following will ip ban a player immediately and kick them after 10 seconds before the ban applies; after the player is banned a message will be broadcasted:
events:
ban:
pre:
- cmd: kick [player] [reason]
delay: 10
- cmd: banip [player] [reason]
post:
- cmd: broadcast [player] banned
Checks for new versions of the plugin
Includes players who are offline when using tab to autocomplete command arguments
Automatically apply the same punishments to alts on join based on ip address. This is disabled by default as this could block siblings or those on shared networks.
Automatically deny players from joining that have the same ip address as a banned player
Number of days to keep a player's previous kicks, set to 0 to disable
Number of days to keep a player's previous bans, set to 0 to disable
Number of days to keep an ip's previous bans, set to 0 to disable
Number of days to keep an ip's previous mutes, set to 0 to disable
Number of days to keep a player's previous mutes, set to 0 to disable
Number of days to keep record of warnings which have been read, set to 0 to disable
Number of days to keep unread warnings for, set to 0 to disable
Number of days to keep player join/leave records for, set to 0 to disable. Only purges ip addresses that are not actively banned.
Maximum amount of players allowed from a single ip, set to 0 to disable
Maximum amount of players allowed from a single ip (recently logged in), set to 0 to disable. The time interval to check is set within multiaccountsTime.
Time interval to look up for recently joined players (in seconds)
Whether to check the database to see if the player is banned on join or not. Recommended to be disabled, the schedule sync tasks should suffice. If after modifying the schedules.yml syncing is not quick enough, enable this option
Enables creation of notes based on text in between ( ). E.g. /ban confuser testing (too good)
will ban for 'testing' and create a note 'too good'
Disable for name case sensitive UUIDs instead of online UUIDs. If you are using a proxy in online mode such as bungeecord, set this to true
Change if muted messages are still showing. The following options are supported:
lowest
low
normal
high
highest
monitor
You should only change the name value in this file
This is used to identify the server when it issues punishments via the console
This is automatically generated and must not be changed. When syncing multiple servers ensure you allow the plugin to generate this file from scratch, do not copy it.
Allows sending messages to Discord server channels when a punishment occurs. Bukkit requires DiscordSRV and Sponge requires MagiBridge.
enabled: true
punishments:
ban:
channel: global
message: '&6[player] has been permanently banned by [actor] for &4[reason]'
tempban:
channel: global
message: '&6[player] has been temporarily banned for [expires] by [actor] for
&4[reason]'
mute:
channel: global
message: '&6[player] has been permanently muted by [actor] for &4[reason]'
tempmute:
channel: global
message: '&6[player] has been temporarily muted for [expires] by [actor] for &4[reason]'
warning:
channel: global
message: '&6[player] has been warned by [actor] for &4[reason]'
Set to true to enable discord integration
The name (for DiscordSRV) or ID (for MagiBridge) of the Discord channel specified in your DiscordSRV config.yml file
Supports Discord Markdown, use
to represent a new line
The name (for DiscordSRV) or ID (for MagiBridge) of the Discord channel specified in your DiscordSRV config.yml file
Supports Discord Markdown, use
to represent a new line
The name (for DiscordSRV) or ID (for MagiBridge) of the Discord channel specified in your DiscordSRV config.yml file
Supports Discord Markdown, use
to represent a new line
The name (for DiscordSRV) or ID (for MagiBridge) of the Discord channel specified in your DiscordSRV config.yml file
Supports Discord Markdown, use
to represent a new line
The name (for DiscordSRV) or ID (for MagiBridge) of the Discord channel specified in your DiscordSRV config.yml file
Supports Discord Markdown, use
to represent a new line
Players listed here are exempt from certain punishments even when offline. This is required as Bukkit's permission system does not support offline players.
b55249d4-9226-4c11-9877-d757c3fe180f:
ban: true
tempban: true
mute: true
tempmute: true
warn: true
tempwarn: true
alts: true
ae51c849-3f2a-4a37-986d-55ed5b02307f:
ban: true
tempban: true
mute: true
tempmute: true
warn: true
tempwarn: true
alts: true
Set to true to exempt this player from being banned
Set to true to exempt this player from being temporarily banned
Set to true to exempt this player from being muted
Set to true to exempt this player from being temporarily muted
Set to true to exempt this player from being warned
Set to true to exempt this player from being temporarily warned
Set to true to exempt this player from showing in alt detections, e.g. /alts and /bminfo
Enables location based information, such as showing which country a player is connected from on join or via /bminfo and allows/blocks certain countries from connecting
Please note this now requires a license key from MaxMind. Please follow these instructions to generate a license key to paste into licenseKey
within your BanManager/geoip.yml
enabled: true
download:
city: 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=[licenseKey]&suffix=tar.gz'
country: 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=[licenseKey]&suffix=tar.gz'
lastUpdated: 0
licenseKey: 'yourLicenseKeyHere'
countries:
type: 'whitelist'
list:
- GB
- FR
Set to true to enable geoip functionality
URL of a Maxmind DB format city data dump
URL of Maxmind DB format country data dump
A timestamp of when the local Maxmind database copies were last updated. BanManager will automatically download a new copy every week on plugin startup.
Either blacklist or whitelist. Players connecting from these countries will be denied or allowed to join
This contains all of the plugin messages sent to players. Format as desired. Text wrapped inside [] are tokens which will be replaced e.g. [reason]
and can be removed if necessary. Use \n
for new lines. Supports colours using & format, e.g. &c
. Set a message to an empty string if you do not want it to be sent.
Setup shortcuts for reasons to punish players quickly. Use the below examples like /ban confuser #hacking
which will ban the player for the reason Using a hacked client
.
You can combine multiple shortcuts or append/prepend them to reasons, e.g. /ban confuser #hacking & #swearing
will ban the player for Using a hacked client & Swearing in chat
hacking: "Using a hacked client"
swearing: "Swearing in chat"
The key should be what you would like to use as a shortcut and the value should be the punishment reason
Controls how often data is synced between the database and Minecraft server to punish players across multiple servers. If you are updating punishments directly via the database, ensure you update the timestamps of the relevant punishments to correctly sync back to the Minecraft server.
scheduler:
expiresCheck: 30
playerBans: 30
playerMutes: 30
playerWarnings: 30
ipBans: 30
ipRangeBans: 30
rollbacks: 30
nameBans: 30
externalPlayerBans: 120
externalPlayerMutes: 120
externalPlayerNotes: 120
externalIpBans: 120
saveLastChecked: 60
The number of seconds the server will check for expired punishments
The number of seconds the server will check for for player bans changes
The number of seconds the server will check for player mutes changes
The number of seconds the server will check for player warnings changes
The number of seconds the server will check for ip bans changes
The number of seconds the server will check for ip range changes bans
The number of seconds the server will check for /bmrollback uses
The number of seconds the server will check for name bans changes
The number of seconds the server will check for global player ban changes
The number of seconds the server will check for global player mute changes
The number of seconds the server will check for global player note changes
The number of seconds the server will check for global player ip changes
The number of seconds the server will update lastChecked values in this file
These values represent the timestamp of when the server last checked for data changes, you should not change these values
-
BanManager supports sharing punishments across multiple servers, often refered to as data syncing in the documentation. This is not dependent on a particular proxy e.g. Bungeecord or Lilypad and there are a number of ways you can achieve this.
Check out the Cross-Server Syncing Guides for more information.