zPermissions — A Superperms plugin for Bukkit

zPermissions is primarily an SQL database-backed Superperms (aka Bukkit permissions) implementation. It also supports flat-file storage. Notable features are: multi-world support, ranks with multiple tracks/ladders, group inheritance of arbitrary depth (within reason), and optional region-specific permissions using WorldGuard regions or Residence residences.

There is no built-in build protection (I rely on other plugins for that). zPermissions focuses on permissions and only permissions.

I aim to keep zPermissions a simple, yet feature-rich, Superperms provider.

Please post bugs and/or feature requests as dev.bukkit.org tickets.

[ Quick start documentation | For Server Admins | FAQ ]

Features

A variety of storage options, from SQL to flat-file. Uses Bukkit database to store permissions (i.e. settings in bukkit.yml). Should work with most databases supported by Avaje Ebean — I've specifically tested with PostgreSQL, MySQL, and H2. The default Bukkit database, SQLite, is not supported. zPermissions will automatically fall back to flat-file storage if it is used.
Group inheritance. Groups may inherit permissions from a single parent group.
Players may be members of more than one group. The order of which group permissions are applied is well defined and based on group weight (which is configurable, of course).
Multi-world support. Permissions granted to players and groups may be associated with a specific world.
Optional region support. Permissions may also be associated with WorldGuard regions or Residence residences.
Multiple promotion tracks! Using permissions, you can also limit who can promote/demote others and which tracks they may use.
Short-term temporary permissions. Give a player a permission node that lasts anywhere from a few seconds to a few minutes.
Temporary group assignments. Assign a group to a player and have their membership expire after 1 day... a few months... or a year! Whatever duration you want.
Players and groups can be assigned chat prefixes and suffixes. A Vault-compatible chat-formatting plugin is still required, like Herochat, zChat, etc.
API. zPermissions offers a comprehensive read-only API that other plugins can use. (Though I would recommend coding against Vault instead.)
Metadata support. Players and groups may have arbitrary metadata associated with them. Metadata values may be strings, integers, reals (floating point), and booleans. Metadata may be queried via the native API or Vault Chat API.
Automatic group permissions. With the advent of Superperms/Bukkit permissions, the recommended way of testing group membership is by using permissions. zPermissions can automatically set a permission based on the group's name for each group. By default, this configurable permission is group.<groupname> (compatible out-of-the-box with WorldEdit and WorldGuard!).
Re-assignable default group. The default group (the group assigned to players who have not been explicitly placed into any groups) is named default. This may be changed.

Concepts

Groups are "universal" — across all worlds. There are no plans to introduce world-specific groups.
However, players and groups may have world-specific and/or region-specific permissions. These permissions are only in effect when the player is in that particular world and/or region.
There are 4 "levels" of permissions: universal, world-specific, region-specific, and finally region- and world-specific. The most general permissions are applied first, with player permissions overriding group permissions at the same level:
1. Universal group permissions
2. Universal player permissions
3. World-specific group permissions
4. World-specific player permissions
5. Region-specific group permissions
6. Region-specific player permissions
7. Region- and world-specific group permissions
8. Region- and world-specific player permissions
Players may be members of multiple groups. Groups may be assigned a weight — a higher weight means the group is applied later so it overrides earlier groups. Groups with the same weight are applied alphabetically.

Installation & Usage

Put zPermissions.jar in your server's plugins directory. Start up your server. This will create the file config.yml in your server's plugins/zPermissions directory. You may want to edit this file to set your default group and default track. You may also want to create your tracks.

Type /permissions to get started. (/perm or /p may also work, if those aliases are available.)

The permission nodes in the get, set, and unset sub-commands may be specified as:

<permission> — An unqualified permission node applies to all worlds and all regions.
<world>:<permission> — To make a permission world-specific, prefix it with the world name followed by a colon.
<region>/<permission> — To make a permission region-specific, prefix it with the region name followed by a slash.
<region>/<world>:<permission> — You may also make a permission both region- and world-specific by combining the two qualifiers. For now, the region qualifier must always come first.

The rank commands are /promote, /demote, /setrank, and /unsetrank and will normally broadcast changes to all admins. The rank commands have an option -q to operate silently, e.g. when being called by automated processes. They will, however, still log their actions to the server log for security audit purposes. Opposite of -q, they will also take -Q which causes the rank commands to broadcast changes to all users.

License & Source

zPermissions is released under the Apache License, Version 2.0.

Sources may be found on GitHub:

Development builds of this project can be acquired at the provided continuous integration server.
These builds have not been approved by the BukkitDev staff. Use them at your own risk.

zPermissions (Requires ToHPluginUtils.jar)
zPermissions-standlone (includes ToHPluginUtils, like the version distributed on dev.bukkit.org)

To Do

More extensive unit tests, especially on the service interface.
Better organized docs.

You must login to post a comment. Don't have an account? Register to get one!

262 comments
1
2
3
7
11
15
19
23
25
26
27
Next →

- Reply
- #264
ZerothAngel May 18, 2013 at 02:47 UTC - 0 likes
@TheFluffey: Go

YAML would definitely be easier. But after browsing through the PEX wiki on its file format, at best, a converter would only be able to deal with the group assignments and only some of the group structure. Converting the permissions themselves is iffy because any permissions plugin that adheres strictly to the Bukkit permissions API (such as zPerms) cannot:
- Have a '*' node
- Support wildcards intrinsically, such as 'myplugin.*'
- Have regex permission nodes (technically the same as #2, I guess)
Also PEX does this thing where it matches permission nodes from top to bottom, stopping on first match. I don't really think this can be simulated purely with the Bukkit API since the permissions need to be fully evaluated (to true/false) before being handed off to Bukkit via a PermissionAttachment.

Additionally, the zPerms permission model is lacking in at least 2 areas (vis-à-vis PEX):
- Groups in zPerms can only inherit from a single parent
- There's no world inheritance (though this can probably be fudged at conversion time)
Anyway, if you're still interested, PM me a link to your YAML. I'll probably prototype something in Python since I have something already halfway there. Or feel free to take a stab at it yourself.

But again, at best, any sort of conversion would probably only be able to deal with group structure/membership and even then, the structure will only be partial (due to multiple inheritance).

Edit: Also, I'd like to add, the only sort of donations I'm interested in are code and time (testing, tech writing, etc.) ;)
Last edited May 18, 2013 by ZerothAngel

BFAK:ZerothAngel,90566764,079d521650974a1ac3fb552228a2240d1310edef5ea774c56eecb3ea3ffeab59
- Reply
- #263
TheFluffey May 18, 2013 at 00:23 UTC - 0 likes
@ZerothAngel: Go

Well, pEx has a converter for yml -> sql and sql -> yml. Perhaps yml would be easier to convert to ZPerms? My problem is the 1000+ users with donor ranks in my PEx file which I would rather not copy paste for 4 hours.

Last edited May 18, 2013 by TheFluffey
- Reply
- #262
ZerothAngel May 17, 2013 at 23:39 UTC - 0 likes
@TheFluffey: Go

Does PEX not have some sort of export or backup feature? (I really don't know, as I've never used it.) Seems like it would be easier to convert from that format, if it exists.

Converting from an SQL dump just sounds... insane. ;) (SQL parsing and what not.) Given the choice, I'd rather convert directly from the database.

The zPerms export/backup format is really simple (just a list of zPerms commands to re-create your set up). I don't think it would be hard for someone more familiar with PEX to write a converter.
- Reply
- #261
TheFluffey May 17, 2013 at 23:05 UTC - 0 likes
@ZerothAngel: Go

A plugin to convert from PEX would be a lifesaver (or just runnable jar, which would convert pex sql downloaded directly from phpma to zPerms). Why? Most people who use Pex are moving away from it, as its mysql is super-inconsistent and it is generally outdated.

You are the best option for MySQL other than Pex, so a conversion to your plugin would literally save my life.

I will donate $25 for you to do this, if you need a Pex .sql file for testing, I can provide.
- Reply
- #260
lANTHONYl May 15, 2013 at 20:29 UTC - 0 likes
@ZerothAngel: Go

I use Spigot which has builtin /timings

Check our Forum Post
- Reply
- #259
ZerothAngel May 15, 2013 at 19:39 UTC - 0 likes
@lANTHONYl: Go

Yes to both your scenarios: only really useful for multi-server setups or when some external process is modifying the database. And even then, I would probably recommend setting things up so it does a /perm refresh on the console when a change has actually occurred.

So yes, I do recommend turning it off.

What are you using to get those timings, BTW? The bulk of the work should be happening asynchronously, outside of the main thread. So it's gotten me curious...

@ayantwan: Go

Herochat, zChat (a fork of bChatManager), bChatManager (w/ dev version of Vault). There might be others (like RoyalChat) - they just have to use the Vault Chat API.

The chat plugins that store prefix/suffix information themselves should also work (so you wouldn't use the zPerms metadata commands). SimpleChat and mChatSuite are the ones I remember.
- Reply
- #258
ayantwan May 15, 2013 at 18:59 UTC - 0 likes
What chat plugin do you recommend to use with zPermissions?
- Reply
- #257
lANTHONYl May 15, 2013 at 18:58 UTC - 0 likes
I understand that the auto-refresh-interval will re-read the perm database every so often. What is the benefit/purpose of this? Would this be useful for multi-server setups, or if the database is being edited manually or through an external source? If i am not doing any of these things is it recommended to turn it off? Only reason i even i'm mentioning this is because having it set to refresh every 10 minutes is having an effect on timings.
zPermissions v0.9.19 Total: 0.01 s Pct: 0.00% Pct Total Pct Tick Total Avg Count Event 0.00% 10.30% 0.005 s 5.1488 ms 0.00k Task: interval 12000 0.00% 4.62% 0.005 s 2.3084 ms 0.00k Task: Single
Nothing major, but it is a noticeable blip considering it's set to refresh every 10 minutes. I didn't expect to see anything on that interval.
- Reply
- #256
ZerothAngel May 15, 2013 at 14:47 UTC - 0 likes
@legomankyle: Go

Weird. Did you perm reload or restart the server after editing config.yml?

What happens if you promote or demote instead?

Also, if it's not obvious, all the groups in any given track need to already exist beforehand:
/perm group default create /perm group user create etc.
I'll have a quick look at setrank's error messages. Maybe it's doing something weird.

Edit: I found a minor bug in setrank where the rank is needlessly case-sensitive. (Which is now fixed.) Not sure if it's the problem you're running into. But as a workaround, make sure the rank you give setrank has the same capitalization as in config.yml.
Last edited May 15, 2013 by ZerothAngel
- Reply
- #255
legomankyle May 15, 2013 at 13:00 UTC - 0 likes
1. Track definitions. Each key should be the name of the track. The value
2. should be a list of group names in ascending order. tracks: default: - default - user - somegroup - someothergroup I have my tracks like that. Then I use the command "/setrank legomankyle default[name of rank] default[track?] And it says "Rank not in track" and if I leave it blank it says the same thing