1.3

The UUID update.

Developed against Bukkit 1.7.8+. May work with 1.7.5, but not recommended.

Migration Procedure

Your data WILL be automatically migrated. However, it is recommended you do the following before running the new version.

(You may want to try this procedure out on a test server and test database first, using zPermission tables copied from production.)

1. (Optional, but highly recommended) Back up your zPermissions database or the zPermissions data.yml depending on which storage option you're using. See your database server docs for the specifics.
2. With your server on the old version of zPermissions (1.1.1, 1.2), issue the command: /perm export <filename>
<filename> can be anything, e.g. uuid-backup.txt or whatever.

Once done, shut down your server, switch to the new version of zPermissions, and start it up again. zPermissions will automatically migrate any existing players. Keep an eye on the server log while it is doing so — if a player's UUID cannot be determined after querying Mojang's servers, they will be deleted.

If anything should go horribly wrong (e.g. network problems while querying Mojang's servers), restore from database backup (or data.yml backup) and try again.

Alternatively, switch to an older version of zPermissions, run /perm purge, switch back to a new version, and then attempt to /perm import the backup export you made above.

Sample Migration Log

[zPermissions] 150 entities to migrate
[zPermissions] 499 memberships to migrate
[zPermissions] Looking up 449 UUIDs...
[zPermissions] Migrating entities...
[zPermissions] Unable to migrate 'xxx' -- failed to lookup UUID
[zPermissions] Migrating memberships...
[zPermissions] Unable to migrate 'yyy' (member of 'resident') -- failed to lookup UUID
[zPermissions] Unable to migrate 'zzz' (member of 'resident') -- failed to lookup UUID
[zPermissions] Deleting entities that failed to migrate...
[zPermissions] Deleting memberships that failed to migrate...
[zPermissions] Migration done

UUID Notes

• The name column in the entities table will now hold the 16-byte hex representation of a player's UUID. The display_name column will continue to hold the player's name, but it will only be used for display in order to avoid a reverse-UUID lookup.

• The memberships table adds a display_name column, serving the same purpose as above.

• The member column in the memberships table will now hold the hex UUID of the player.

• When a player logs in, the display_name columns in both of these tables are updated with their current name, if different.

• All commands that accept a player name will now also accept a UUID in four forms:

  • ef046b514ef44e15bb1a3d21f9da0ebc
  • ef046b51-4ef4-4e15-bb1a-3d21f9da0ebc
  • ef046b514ef44e15bb1a3d21f9da0ebc/ZerothAngel
  • ef046b51-4ef4-4e15-bb1a-3d21f9da0ebc/ZerothAngel

  The latter two are for (temporarily) setting their display name. (Remember, their display name is updated whenever they log in, so it's just there for your convenience.) If you don't set a display name and they aren't online, it will simply set it to the same as their UUID.

• The /perm export command will now always export commands using UUID.

• All commands that accept a player name will do the following:

  1. If it is already a UUID (one of the above forms), then use that
  2. If the named player is online, use their UUID
  3. Otherwise, perform a (possibly remote) lookup. Since this has the potential to block the main thread, it will be done in the background. This means that if a lookup is performed, the command will return right away but you may not get the results until some time later.

• Commands that display lists of players — /perm list, /perm search, /perm group ... members — will accept a new option: -U or --uuid. With this option, the players will be displayed as "UUID/LastKnownName"

• The native zPermissions API (ZPermissionsService) has added new methods that take and return UUIDs for anything that involves players. The old player-related methods have been deprecated, and simply map usernames to UUIDs by using Bukkit.getOfflinePlayer(String). Note that in Bukkit 1.7.8+, this is now a potentially blocking method.

• The Vault API implementation included with zPermissions maps usernames to UUIDs by using Bukkit.getOfflinePlayer(String), a potentially blocking method in Bukkit 1.7.8+. This is just a stopgap measure until if/when Vault adds direct UUID support.

Breaking Changes

• The player..rename command has been removed for obvious reasons. The player..clone command remains.
• For the /perm diff command: the <player> and <other-player> arguments no longer take "qualified" player names (e.g. qualified by world). Instead, the command takes an explicit -w or -W option to specify the world for <player> and/or <other-player> respectively.

Known issues affecting 1.3beta1:

• Not compatible with offline mode at all. Note the UUID spoofing available with BungeeCord/Spigot should work fine as long as the BungeeCord server is online.
• When a player logs in, their name -> UUID mapping is cached (default 5 minutes). This is a bit useless since they typically will still be online when you issue commands. Dev build #526+ fixes this by caching after the player logs out instead.
• When configured in read-only mode, you will see stack traces whenever someone logs in. While a bug, this is harmless. It has been fixed in dev build #528+.
• When using flat-files, during migration, should the lookup of any player with a temporary membership fail, zPermissions will fail to load the migrated data.yml. You can restore from backup and use dev build #532+ or follow the instructions in this comment to salvage your data.yml.