BungeeSafeguard - UUID-based whitelist plugin

BungeeSafeguard

A blacklist and whitelist BungeeCord plugin with support of UUID look up.

This plugin was formerly named BungeeGuard. In order not to conflict with the existing plugin BungeeGuard, this plugin is renamed to BungeeSafeguard from v2.0.

Tested with bsgtest on Waterfall, version: git:Waterfall-Bootstrap:1.19-R0.1-SNAPSHOT:8a03f3d:515.

BungeeCord/Waterfall 1.18-R0.1 should be working because I see 82.5% of the BungeeSafeguard users are using that version. I personally haven't conducted a full test against 1.18 but as you know BungeeCord's APIs are much more stable than APIs of MC servers (because it's just a proxy), which means BungeeCord plugins can migrate to higher versions of BungeeCord without compatibility issues most of the time. That said, it's highly recommended to do a local test after the upgrade and before going back to the normal operation mode to make sure 1) your configuration is taking effect using /bsg status and /bsg dump, 2) BungeeSafeguard is blocking you if you remove yourself from the whitelist or add yourself to the blacklist when the corresponding list is enabled. If the test fails, roll back to an old but working version and report the issue to me.

• BungeeSafeguard
  • Features
  • Usage
  • New Features of v3.0 and How To Migrate
  • Migrate to v2.0
  • XBOX Live Player Support (Bedrock Edition Support)
  • Replaceable Storage Backend for Lists
  • Optional Extension Plugins
  • Configuration
  • Commands
    • Whitelist
      • whitelist add
      • whitelist x-add
      • whitelist lazy-add
      • whitelist remove
      • whitelist x-remove
      • whitelist lazy-remove
      • whitelist import
      • whitelist on
      • whitelist off
      • whitelist confirm
      • whitelist list
    • Blacklist
      • blacklist add
      • blacklist x-add
      • blacklist lazy-add
      • blacklist remove
      • blacklist x-remove
      • blacklist lazy-remove
      • blacklist import
      • blacklist on
      • blacklist off
      • blacklist confirm
      • blacklist list
    • Main Command
      • bungeesafeguard load
      • bungeesafeguard reload
      • bungeesafeguard status
      • bungeesafeguard dump
      • bungeesafeguard import
      • bungeesafeguard merge
      • bungeesafeguard export
  • Permission Nodes
  • Lazy Lists
  • Operation Confirmation
  • Important Notes

Features

• First UUID-based blacklist and whitelist plugin for BungeeCord
• Add and remove players by their username or UUID (username-change-proof)
• Add and remove XBOX Live players by their Gamer Tag or UUID (Gamertag-change-proof) (from v2.3, see XBOX Live Player Support for more details)
• Lazy translation from username to UUID (from v1.2, offline server friendly, see lazy lists for details)
• Switch between multiple configuration files (e.g., a config for maintenance mode which whitelists administrators only; from v2.4)
• Optional confirmation before adding or removing list entries (from v2.4, see Operation Confirmation for more details)
• Import from old whitelist.json or banned-players.json (from v2.5, resolves issue #7; see whitelist import and blacklist import for more details)
• API support backed by (possibly) well-structured and documented code base (from v3.0; see Developing Extension Plugin for BungeeSafeguard for more details)
  • Manage the lists via a GUI Web interface (TODO)
  • SQL database storage support (TODO)
  • Redis storage support (Redis-BSG)

Usage

Download pre-compiled jar file from this page or the release page. Put downloaded jar file under <path/to/BungeeCord/plugins>.

New Features of v3.0 and How To Migrate

If you are a developer who has been using the unannounced API, breaking changes in v3.0:

• Internal package name (from vip.untitled.bungeeguard to cyou.untitled.bungeesafeguard)
• Other massive internal refactoring

Otherwise, v3.0 is a major remastered version with backward compatibility. You don't need to do anything to upgrade from older versions.
However, you may want to know some new features brought by v3.0.

For normal users, we have the followings:

• Replaceable Storage Backend for Lists
• Optional Extension Plugins

For developers who want to interact with BungeeSafeguard gracefully, please refer to Developing Extension Plugin for BungeeSafeguard.

Migrate to v2.0

Breaking changes in v2.0:

• Plugin name (from BungeeGuard to BungeeSafeguard)
• Internal package name (from vip.untitled.bungeeguard to vip.untitled.bungeesafeguard)
• Internal class names
• Main command name (from bungeesafeguard to bungeesafeguard, from bg to bsg)
• Configuration directory (from plugins/BungeeGuard to plugins/BungeeSafeguard)

To migrate to v2.0 from lower versions, do the following:

1. Remove old plugin jar file
2. Install new plugin jar file
3. Rename old plugins/BungeeGuard directory to plugins/BungeeSafeguard
4. Update assigned permissions, change bungeeguard to bungeesafeguard in permission nodes

You are now good to go.

XBOX Live Player Support (Bedrock Edition Support)

Since version v2.3, BungeeSafeguard now supports automatic conversion from XBOX Live Gamer Tag to Minecraft-compatible UUID following the conversion rule as defined by Geyser. This new feature hopefully resolves the issue #5.
XBOX Live Gamer Tags are now added via the command x-add and removed via the command x-rm.
There is no need to implement lazy lists for XBOX Live players because current lazy lists are compatible with XBOX Live players.

Note that you need to specify an xbl-web-api instance (you can either deploy your own or use the public one provided by xbl-web-api) by setting its URL as the value of the configuration entry xbl-web-api (see section Configuration).

Replaceable Storage Backend for Lists

Start from v3.0, BungeeSafeguard supports custom storage backend for the lists. That is, you can store the list records in the config file, the database, or wherever you want.
The use case of custom storage backend is when you have really large lists, or when you want to share lists among multiple networks, you will want a non-toy, dedicated, professional backend.

Current available storage backend extension plugins:

1. Name Feature
2. Redis-BSG Store the whitelist/blacklist in a Redis store

Optional Extension Plugins

Start from v3.0, BungeeSafeguard exposes a handful of APIs for third-party plugins to manipulate the lists or register custom backend.
For example, you can now implement a standalone plugin that programmatically whitelist or blacklist someone; or a plugin that wraps BungeeSafeguard APIs and exposes them as RESTful API.

Current available extension plugins (storage backend not included):

1. Name Feature
2. RESTful-BSG Access the whitelist/blacklist via RESTful API

Configuration

The configuration file for BungeeSafeguard is plugins/BungeeSafeguard/config.yml.

#########################################
#     BungeeSafeguard Configuration     #
#            Version: 3.1               #
#          Author: Untitled             #
#########################################

# You can safely ignore this
version: "3.1"

# Message to be sent to the player when that player is blocked for not being whitelisted
whitelist-message: :( You are not whitelisted on this server

# Message to be sent to the player when that player is blocked for being blacklisted
blacklist-message: :( We can't let you enter this server

# Message to be sent to the player when that player is blocked for not having a UUID
no-uuid-message: :( Name yourself

# Whether to use whitelist
enable-whitelist: true

# Lazy-whitelist (array of usernames)
# lazy-whitelist:
# - <lazy-whitelisted username>
lazy-whitelist:

# Whitelist (array of UUIDs)
# whitelist:
# - <whitelisted UUID>
whitelist:

# Whether to use blacklist
enable-blacklist: false

# Lazy-blacklist (array of usernames)
# lazy-blacklist:
# - <lazy-blacklisted username>
lazy-blacklist:

# Blacklist (array of UUIDs)
# blacklist:
# - <banned UUID>
blacklist:

# xbl-web-api: <a deployment of https://github.com/Prouser123/xbl-web-api>
xbl-web-api: https://xbl-api.prouser123.me

# confirm: <should request confirmation for add/remove operation?>
confirm: false

Note that if you enable both blacklist and whitelist (which is weird, but it is possible to do that), player in both lists will be blocked because blacklist has a higher priority over whitelist.

Commands

Whitelist

Alias: wlist.

whitelist add

Add player(s) to whitelist:

whitelist add <space separated usernames or UUIDs>

Example:

whitelist add DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

whitelist x-add

Alias: xadd.

Add XBOX Live player(s) to whitelist:

whitelist x-add <space separated GamerTags or converted UUIDs>

Example:

whitelist x-add DummyPlayer0 DummyPlayer1 00000000-0000-0000-852b-afab3ec1e2ff DummyPlayer2

whitelist lazy-add

Alias: whitelist lazyadd or whitelist ladd.

Add player(s) to lazy-whitelist:

whitelist lazy-add <space separated usernames or UUIDs>

Example:

whitelist lazy-add DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

whitelist remove

Alias: whitelist rm.

Remove player(s) from whitelist:

whitelist remove <space separated usernames or UUIDs>

Example:

whitelist remove DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

whitelist x-remove

Alias: whitelist xremove, whitelist x-rm or whitelist xrm.

Remove XBOX Live player(s) from whitelist:

whitelist x-remove <space separated GamerTags or converted UUIDs>

Example:

whitelist x-remove DummyPlayer0 DummyPlayer1 00000000-0000-0000-852b-afab3ec1e2ff DummyPlayer2

whitelist lazy-remove

Alias: whitelist lazyremove, whitelist lremove or whitelist lrm.

Remove player(s) from lazy-whitelist:

whitelist lazy-remove <space separated usernames or UUIDs>

Example:

whitelist lazy-remove DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

whitelist import

Import UUID(s) from an existing JSON file, e.g. your old whitelist.json, to the whitelist.

whitelist import <path to whitelist.json>

Note that <path to whitelist.json> could be either an absolute path, e.g. /home/mc/old-mc-server/whitelist.json,
or a path relative to the working directory of the running BungeeCord process, e.g. ../old-mc-server/whitelist.json.

Example:

whitelist import whitelist.json

This feature is added as requested by issue #7.

whitelist on

Turn on whitelist:

whitelist on

whitelist off

Turn off whitelist:

whitelist off

whitelist confirm

Confirm the last issued whitelist command:

whitelist confirm

whitelist list

Alias: whitelist ls, whitelist show or whitelist dump.

Dump whitelist and lazy whitelist with at most 10 last known usernames:

whitelist list

Example output:

Whitelist ENABLED
2 lazy record(s)
  foo
  bar
3 UUID record(s) and the last known names (in reverse chronological order)
  00000000-1111-2222-3333-666666666666 LatestName, OldNameLastMonth, OldNameLastYear
  ffffffff-1111-2222-3333-666666666666
  eeeeeeee-1111-2222-3333-666666666666 LatestName123

This feature is added as requested by issue #8.

Blacklist

Alias: blist.

blacklist add

Add player(s) to blacklist:

blacklist add <space separated usernames or UUIDs>

Example:

blacklist add DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

blacklist x-add

Alias: blacklist xadd.

Add XBOX Live player(s) to blacklist:

blacklist x-add <space separated GamerTags or converted UUIDs>

Example:

blacklist x-add DummyPlayer0 DummyPlayer1 00000000-0000-0000-852b-afab3ec1e2ff DummyPlayer2

blacklist lazy-add

Alias: blacklist lazyadd or blacklist ladd.

Add player(s) to lazy-blacklist:

blacklist lazy-add <space separated usernames or UUIDs>

Example:

blacklist lazy-add DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

blacklist remove

Alias: blacklist rm.

Remove player(s) from blacklist:

blacklist remove <space separated usernames or UUIDs>

Example:

blacklist remove DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

blacklist x-remove

Alias: blacklist xremove, blacklist x-rm, blacklist xrm.

Remove XBOX Live player(s) from blacklist:

blacklist x-remove <space separated GamerTags or converted UUIDs>

Example:

blacklist x-remove DummyPlayer0 DummyPlayer1 00000000-0000-0000-852b-afab3ec1e2ff DummyPlayer2

blacklist lazy-remove

Alias: blacklist lazyremove, blacklist lremove or blacklist lrm.

Remove player(s) from lazy-blacklist:

blacklist lazy-remove <space separated usernames or UUIDs>

Example:

blacklist lazy-remove DummyPlayer0 DummyPlayer1 7be767e5-327c-4abd-852b-afab3ec1e2ff DummyPlayer2

blacklist import

Import UUID(s) from an existing JSON file, e.g. your old banned-players.json, to the blacklist.

blacklist import <path to banned-players.json>

Note that <path to banned-players.json> could be either an absolute path, e.g. /home/mc/old-mc-server/banned-players.json,
or a path relative to the working directory of the running BungeeCord process, e.g. ../old-mc-server/banned-players.json.

Example:

blacklist import banned-players.json

This feature is added as requested by issue #7.

blacklist on

Turn on blacklist:

blacklist on

blacklist off

Turn off blacklist:

blacklist off

blacklist confirm

Confirm the last issued blacklist command:

blacklist confirm

blacklist list

Alias: blacklist ls, blacklist show or blacklist dump.

Dump blacklist and lazy blacklist with at most 10 last known usernames:

whitelist list

Example output:

Blacklist ENABLED
2 lazy record(s)
  foo
  bar
3 UUID record(s) and the last known names (in reverse chronological order)
  00000000-1111-2222-3333-666666666666 LatestName, OldNameLastMonth, OldNameLastYear
  ffffffff-1111-2222-3333-666666666666
  eeeeeeee-1111-2222-3333-666666666666 LatestName123

This feature is added as requested by issue #8.

Main Command

Alias: bsg.

bungeesafeguard load

Alias: bsg use.

Load configuration from a specific .yml file under plugins/BungeeSafeguard/ (the extension .yml can be omitted):

bungeesafeguard load <config file>

Example:

bungeesafeguard load maintenance-config.yml

Note: enabling confirmation is suggested in order not to modify an unexpected configuration file if you are to use multiple configuration files.

This feature is added as requested by issue #6.