DOCSEARCHbyAlgolia
Submit Docs

BanManager Documentation

website·Indexed 32 days ago

https://banmanagement.com/docs

Documentation for BanManager, a Minecraft punishment management plugin. Includes guides on installation for single servers and networks, configuration files (config.yml, messages.yml, webhooks.yml), command syntax, permission nodes, and developer API. Also covers the self-hosted WebUI for managing punishment data via Docker or web installer.

Tokens
45.1K
Snippets
311
Records
346
Agent score
54%

What's inside BanManager

  1. Overview of Ban Management moderation features

    Ban Management is a suite of open-source moderation plugins and apps for Minecraft servers designed to help staff moderate communities effectively. Key features include:

    • Flexible Banning: Ability to block players, IP addresses, and prevent profane usernames from joining.
    • Spam Reduction: Tools to mute players, including shadow muting.
    • Self Moderation: A reporting system allowing players to report behavior while staff are offline for later resolution.
    • Warning System: A system to notify players of misdeeds with the ability to automatically trigger commands after a specific number of warnings, increasing in severity.
    • Collaborative Records: Staff can write notes and view a player's full history (including unbans and the staff member responsible) to ensure consistent rule enforcement.
    • Localisation: Full customization of all messages, supporting color codes and JSON messages.

  2. Configure permanent and temporary ban messages

    Use these tokens to display details about a player's current ban. Temporary bans include an additional [expires] token.
    # Permanent Ban
"&6Currently banned for &4[reason]&6 by [actor] at [created]"

# Temporary Ban
"&6Currently banned for &4[reason]&6 by [actor] at [created] which expires in [expires]"

  4. Configure permanent and temporary IP ban messages

    Use these tokens to display details about an IP-based ban. Temporary IP bans include an additional [expires] token.
    # Permanent IP Ban
"&6Currently banned for &4[reason]&6 by [actor] at [created]"

# Temporary IP Ban
"&6Currently banned for &4[reason]&6 by [actor] at [created] which expires in [expires]"

  5. BanManagement Web UI Feature Overview

    The Web UI provides a comprehensive suite of tools for community management, including:

    • Player Lookup: Search for players to view their complete punishment records.
    • Ban Appeals: A system for players to submit appeals and for staff to review/respond.
    • Live Dashboard: Real-time server-wide statistics for bans, mutes, warnings, and player counts.
    • Multi-Server Support: A single dashboard to manage multiple connected servers.
    • In-Game Login: Secure authentication using a unique pin generated in-game.
    • Staff Roles: Granular permission controls to manage staff access and actions.
    • Public Access: Allows players to view their own history without requiring a login.
    • Mobile Ready: Fully responsive design for phones and tablets.

  6. BanManager available placeholders reference

    BanManager provides a variety of placeholders to retrieve server-wide statistics and player-specific punishment data. These include counts for bans, mutes, and warnings, as well as detailed information about the current active punishment (ID, timestamps, reasons, and actor details).

    Server-wide Statistics

    • %bm_player_bans%: Total number of player bans on the server
    • %bm_player_mutes%: Total number of player mutes on the server
    • %bm_ip_bans%: Total number of ip bans on the server
    • %bm_ip_mutes%: Total number of ip mutes on the server
    • %bm_iprange_bans%: Total number of ip range bans on the server

    Player Record Counts

    • %bm_banrecord_count%: Total number of ban records for the player
    • %bm_muterecord_count%: Total number of mute records for the player
    • %bm_warning_count%: Total number of warnings for the player
    • %bm_kick_count%: Total number of kicks for the player

    Current Player Ban Details

    • %bm_currentban_id%: The player's current ban id
    • %bm_currentban_created%: The player's current ban created timestamp
    • %bm_currentban_expires%: The player's current ban expiry timestamp
    • %bm_currentban_reason%: The player's current ban reason
    • %bm_currentban_actor_id%: The player id of who issued the ban
    • %bm_currentban_actor_name%: The player name of who issued the ban

    Current Player Mute Details

    • %bm_currentmute_id%: The player's current mute id
    • %bm_currentmute_created%: The player's current mute created timestamp
    • %bm_currentmute_expires%: The player's current mute expiry timestamp
    • %bm_currentmute_reason%: The player's current mute reason
    • %bm_currentmute_actor_id%: The player id of who issued the mute
    • %bm_currentmute_actor_name%: The player name of who issued the mute

    Current IP Ban Details

    • %bm_currentipban_id%: The player's current ip ban id
    • %bm_currentipban_created%: The player's current ip ban created timestamp
    • %bm_currentipban_expires%: The player's current ip ban expiry timestamp
    • %bm_currentipban_reason%: The player's current ip ban reason
    • %bm_currentipban_actor_id%: The player id of who issued the ban
    • %bm_currentipban_actor_name%: The player name of who issued the ban
    • %bm_currentipban_ip%: Banned IP address

    Current IP Mute Details

    • %bm_currentipmute_id%: The player's current ip mute id
    • %bm_currentipmute_created%: The player's current ip mute created timestamp
    • %bm_currentipmute_expires%: The player's current ip mute expiry timestamp
    • %bm_currentipmute_reason%: The player's current ip mute reason
    • %bm_currentipmute_actor_id%: The player id of who issued the mute
    • %bm_currentipmute_actor_name%: The player name of who issued the mute
    • %bm_currentipmute_ip%: Muted IP address

  7. Setup Caddy as a reverse proxy

    Caddy is recommended for new installations because it manages Let's Encrypt certificates automatically. The setup helper asks for your domain and optional sub-path, then writes a configuration snippet to /etc/caddy/Caddyfile.d/<domain>.caddy.
    npx bmwebui setup caddy

    Ensure your main /etc/caddy/Caddyfile includes the snippet directory:

    import Caddyfile.d/*.caddy

  9. Install BanManager on alternative networks (e.g., LilyPad)

    For networks using proxies other than BungeeCord or Velocity, install BanManager on each individual Minecraft instance (CraftBukkit, Spigot, Paper, Fabric, or Sponge) and connect them to a shared MySQL or MariaDB database to sync punishments across the network.
    # config.yml
databases:
  local:
    storageType: mysql # or mariadb
    host: "your-db-host"
    name: "your-db-name"
    user: "your-db-user"
    password: "your-db-password"

  10. Verify BanManager prerequisites

    Ensure your environment meets the following requirements based on your Minecraft version and platform:

    • Java 8+: Required for CraftBukkit/Spigot/Paper (Minecraft 1.7.2+) and Sponge API 7 (Minecraft 1.12.2).
    • Java 17+: Required for Sponge API 11+ (Minecraft 1.20+) and Fabric (Minecraft 1.20.1, 1.21.1, 1.21.4).

  11. Secure the BanManager WebUI installer

    The browser-based installer at /setup is unauthenticated by default. To prevent unauthorized users from becoming the admin on internet-reachable hosts, set a SETUP_TOKEN before starting. The setup screen will require this token as the first step. Once an admin user is created, the setup routes automatically return 404.
    SETUP_TOKEN=$(openssl rand -hex 24)

  12. Migrate from discord.yml to webhooks.yml

    For versions v7.10 and newer, the legacy discord.yml configuration is no longer supported. Users should migrate to webhooks.yml to gain the following features:

    • Support for any HTTP endpoint (not limited to Discord)
    • Ability to define custom HTTP methods and headers
    • Support for multiple webhooks per punishment type
    • Availability across all platforms, including Velocity and Fabric.