IPUserAccess 1.1.2

IP and User/UUID whitelist/blacklist plugin that works with BungeeCord proxies

  1. tk11
    IPUserAccess is a whitelist/blacklist plugin that filters by IPs and/or user/UUID, and it allows for proxy server connection on a BungeeCord network. This is similar to IPWhitelist but adds more whitelisting and blacklisting functionality, plus I plan on adding some more features in the future.

    The plugin has three files associated. It has a whitelist file that holds whitelisted IPs and users (as UUID:username), and a blacklist file that holds blacklisted IPs and users. There is also a config file that looks like this:

    plugin_enabled: true
    proxy_ip_enabled: true
    plugin_mode: no_list
    storage_type: text
    db_port: 3306
    db_name: ''
    db_user: ''
    db_pass: ''
    db_prefix: 'ipua'

    plugin_enabled is a flag that precedes any functionality (proxy or filtering) and basically enables/disables the plugin. Obviously you want this on for the plugin to work.

    proxy_ip_enabled enables proxy filtering for BungeeCord networks. You can use this plugin on any Bukkit/Spigot server with this disabled, or you can enable it so that the Bungee servers only accept connections from the proxy server.

    proxy_ip is the IP of the BungeeCord proxy server. This is independent of whitelisting/blacklisting in the plugin. If you have a BungeeCord setup, you should use this with the flag above to filter the proxy.

    proxy_kick_message and kick_message are the messages displayed when someone is denied access. Note: The proxy_kick_message is currently overridden on Bungee servers by a default IPForwarding message.

    plugin_mode sets how the plugin will treat filtering the whitelist and blacklist. When using BungeeCord, these filters are applied after the proxy check, so there are essentially two filters - connecting through the proxy and then how the user access is controlled by the lists. The settings are as follows:

    no_list - allows all connections regardless of the whitelist or blacklist
    blacklist_all - allows all connections except blacklisted IPs or users (checks both lists)
    blacklist_user - allows all connections except blacklisted users
    blacklist_ip - allows all connections except blacklisted IPs
    whitelist_all - blocks all connections except whitelisted IPs or users (checks both lists)
    whitelist_user - blocks all connections except whitelisted users
    whitelist_ip - blocks all connections except whitelisted IPs

    storage_type is how the lists are stored. It defaults to 'text', which stores in the generated text files. To use SQL (currently MySQL), change this to 'mysql' and use the settings below.

    db_url is the IP or URL for the SQL database

    db_port is the database port. Default is '3306'

    db_name is the name of the database

    db_user is the username to connect to the database

    db_pass is the password to connect to the database

    db_prefix is the table prefix. Default is 'ipua'

    Note: It occurred to me that blacklist_all and whitelist_all might be a little confusing out of context. Remember that 'all' is referring to the lists and not the people accessing the server. So whitelist_all means that it checks all of the whitelist (IPs and users). It DOES NOT mean whitelist everybody connecting. The modes refer to the lists.

    Also, user/UUID filtering checks both username and UUID. This is partially to set up for future functionality when people are getting name changes.

    I thought this might help show what each plugin mode does. Along the top are the modes and brief description, and down the left are how the player connects.

    For example, if the player connects with a whitelisted IP, he or she will be allowed if the mode is WLIP, blocked if WLUser, and allowed for everything else. This is because WLIP is specifically looking for whitelisted IPs and blocks everything else, where WLUser is looking only for whitelisted users and blocks everything else. Blacklisting ALLOWS everything but what is on the blacklist, so naturally the whitelisted IP will pass.

    The bottom two connection scenarios are what were fixed with version 1.1.2. Previously, a user coming from a specifically blacklisted IP but with a whitelisted name/UUID, or a user with a blacklisted name/UUID and coming from a whitelisted IP, would be able to connect to the server. While some server admins may not be using both lists and only focusing on one kind of user access (such as just whitelisting IPs), I felt that being able to maintain blacklisting should still be viable. If you maintain both lists but only use whitelisting modes, the filters will now check the blacklists as well to ensure that a user or IP is not disallowed, even if that connecting user is whitelisted otherwise.


    Drop the JAR in the plugins folder on the server (not the proxy server if using BungeeCord) and start the server.

    The default settings for the plugin are similar to above (with kick messages as well). If you are not on a BungeeCord network, disable the proxy_ip_enabled. If you ARE on a BungeeCord network, set the proxy_ip to the Bungee proxy.

    Beyond that, you need to decide how you want to filter users. Set the plugin_mode and start whitelisting/blacklisting as needed.

    For updates, replace the plugin with the new version, copy your config settings and delete the config, allowing the plugin to generate a new one.

    If using MySQL, The plugin defaults to text files for storage, so they will be generated with the first startup. Change the storage_type to 'mysql', set your DB settings and then reload the plugin ('/ipua reload' will work). The plugin will connect to the DB and create the tables.

    The primary command for this plugin is /ipuseraccess but you can also use /ipua.

    Whitelist commands:

    /ipua wlipadd <ip>
    - Add IP to whitelist.
    /ipua wlipdel <ip> - Delete IP from whitelist. (Can also use 'wlipdelete')
    /ipua wluseradd <username> - Add user/UUID to whitelist.
    /ipua wluserdel <username> - Delete user/UUID from whitelist. (Can also use 'wluserdelete')

    Blacklist commands:

    /ipua blipadd <ip>
    - Add IP to blacklist.
    /ipua blipdel <ip> - Delete IP from blacklist. (Can also use 'blipdelete')
    /ipua bluseradd <username> - Add user/UUID to blacklist.
    /ipua bluserdel <username> - Delete user/UUID from blacklist. (Can also use 'bluserdelete')

    Mode commands:
    Format: /ipua mode <plugin_mode>

    /ipua mode nolist
    - Turns off whitelisting and blacklisting functionality. (Can also use 'no_list')
    /ipua mode blall - Allows all connections except blacklisted IPs or users (checks both lists). (Can also use 'blacklist_all')
    /ipua mode bluser - Allows all connections except blacklisted users. (Can also use 'blacklist_user')"
    /ipua mode blip - Allows all connections except blacklisted IPs. (Can also use 'blacklist_ip')"
    /ipua mode wlall - Blocks all connections except whitelisted IPs or users (checks both lists) (Can also use 'whitelist_all')
    /ipua mode wluser - Blocks all connections except whitelisted users. (Can also use 'whitelist_user')"
    /ipua mode wlip - Blocks all connections except whitelisted IPs. (Can also use 'whitelist_ip')"
    /ipua mode show - Shows the current mode.

    List commands (shows list items):
    Format: /ipua list <list> [page]

    /ipua list bluser - Lists all users on the blacklist. (Can also use 'blacklist_user')
    /ipua list blip - Lists all IPs on the blacklist. (Can also use 'blacklist_ip')
    /ipua list wluser - Lists all users on the whitelist. (Can also use 'whitelist_user')
    /ipua list wlip - Lists all IPs on the whitelist. (Can also use 'whitelist_ip')

    Other commands:

    /ipua help
    - Shows commands
    /ipua mode help - Shows mode commands
    /ipua list help - Shows list commands
    /ipua reload - Reloads plugin

    Permission node

    Potential Issues:
    UUID fetching - I am trying to minimize the amount of UUID fetching requests made to the Mojang API. The plugin starts by looking at online players and then fetches if it does not find them. Mojang has a limit on requests (about 600 in 10 minutes and 100 at a time), so considering this plugin only does individual, on-call fetches, it should not be a problem.

    However, I am currently troubleshooting an issue I am having on one of my servers, where I am getting 429 errors (too many requests) when trying to list an offline user that requires a fetch. I realized that if you are being hosted and possibly sharing an IP, there may be others on the same IP that are flooding requests and causing Mojang to block the IP. I am hoping that caching functionality may help with this.

    Also, this is just to warn users of the plugin that the fetch may fail if the request cap is reached. Wait a bit and try again.

    In progress (as of 1/30/16):
    - Checking compatibility with new Bungee/Spigot.

    - Working on user access log for tracking and mitigating UUID Fetching.

    - Checking compatibility with KCauldron. Having issues with recognizing proxy IP.

    To do:

    - Working on a user cache. I debated the use of something like this because there is already some user caching (such as usercache.json), but realized that it may be beneficial for those using a common database for all of the Bungee servers. This will add a user cache table to the database (and probably a text file for those not using SQL), that will cache users in the onJoin process. This will help alleviate UUID fetching from Mojang, and give the admin more control over how long players are cached. There is a prune task that runs periodically but the length of time users are cached is determined by the admin.

    - Associating IP with user. The cache will retain username, UUID and IP. This will help with listing to any list and allow for potential lookups.

    - Working on a new config manager that will help update config files with plugin updates (just reload instead of delete/regen). Also should allow comments in the files for easier reference.

    - SQL support. Still going to add SQLite.

    - I am considering adding commands to set some of the other config settings, but I think certain settings are safer from accidents when you have to set them manually by going into the config file.

    - A command to clear the list files.

    - Possibly more permission nodes to allow access to different commands.

    This is my first plugin for Minecraft, so I am still getting familiar with the Bukkit/Spigot API. I am always looking for suggestions and input, so feel free to let me know what you think or if you have feature requests. Also, while I have done a lot of testing on this plugin, please let me know right away if you find bugs or any other issues.

    Thanks to roblabla and his IPWhitelist plugin for inspiration. Also, I used evilmidget38's UUIDFetcher and Goblom's ConfigManager for some functionality.
    DiscowZombie likes this.

Recent Updates

  1. SQL SUPPORT and made some updates