ACL and Groups/English
You can find an illustrated tutorial/quick guide on how to administer groups and permission here: ACL Tutorial
Groups are tied to a specific channel, but can also be inherited by subchannels. Groups are convenient ways to administer channels; set up the ACLs on the top of the tree that should have similar privilege structure, and just change the group memberships on subchannels.
For each channel, a group has 3 pieces of data. The list of players to add to the group, the list of players inherited from the same group on the parent channel, and the list of players to remove from the group.
A group will only inherit players from the parent if Inherit is set true and the group was marked Inheritable on the parent. Most of the time you want both of these to be set.
Let's take a practical example; the admin group. Every time a player makes a channel, he is automatically added to the admin group. This doesn't automatically give him any privileges, it just marks him as a member of that group, however Murmur's default installation installs an ACL that gives the admin group write bit (all access).
In a structure like this:
In Root, player "Big Boss" is alone in the admin group. In channel A, player "BossA" is in the Add list, and "BossB" is the same in channel B.
Since the admin group is inherited and inheritable, a player that is a member at any parent of the current channel is also a member in the current channel. So the total list of members in channel B is "Big Boss, BossA, BossB". The convenience of this system is that if we later att "Super Boss" to admin in Root, he'll automatically be in the admin group of every channel below.
Let's move on, and say that player "BossC" is in the Add list in channel C, but here admin is marked as not inherit. This means that "Big Boss" is not in the admin list, and any changes for admin in Root will not be seen here. Channel D will inherit the list from C, unless C also marks admin as not inheritable.
ACL (Access Control Lists) are all attached to a specific channel. A channel can specify if it wants to inherit the ACL on the parent, but it cannot specify which; it's a all or nothing deal. ACL are evaluated in order, from top to bottom along the chain of channels.
For each entry, either a user or a group will match. A user must be a specific, registered user, while a group can be any group valid in the channel the ACL is defined on. Note that group membership is evaluated in the channel the ACL is executed in, which is important for inherited ACLs. If a group begins with a !, it's membership is inverted, and if it begins with a ~, it is evaluated in the context of the channel the ACL is defined on (and not the active channel).
All authenticated users
All users inside current channel
All users outside current channel
For each entry, permissions are either allowed or denied; in case of a conflict the last entry takes precedence. Remember that all entries are evaluated in order, so if you have the following set of entries:
- @all deny speak
- @all allow speak
Then everyone will be allowed to speak. On the other hand
- @all allow speak
- @all deny speak
Will deny speak from everyone.
Each entry can be marked as either applying in the current channel, in subchannels or both. Most of the time you want both. Remember that for an entry to be applied on a subchannel, you have to apply it to subchannels and allow inheritance in the subchannels.
The @sub group
There is a special group called sub, which just like all has a special meaning. Sub is used as sub,a,b,c, where a is the minimum number of common parents, and b and c restrain the path depth:
- b is the minimum and c the maximum path length, measured from the channel referred by a.
- If any of those parameter is missing, then there will be no minimum/maximum path length.
It's somewhat complex, but also rather powerful. For example, assume the following tree:
Let's deny enter to all on Root to start with. Then, on A, we define
- @~sub,0,1 +enter
First of all, this ACL will be evaluated in the context of the defining channel, since the group starts with ~.
The first parameter (0) indicates how many additional elements of the path name must match. A zero means we require a match up to this point. This means that any player in a channel under the path Root.A will match. If the parameter had been 1 and we were in channel Sub2, the path of the player would need to match Root.A.Sub1. Setting this to positive values only makes sense for pinned groups (with the ~).
The second parameter requires the path of the evaluated channel to be at least one element longer than the path of the channel of the ACL. So this rule will match in anything that starts with Root.A and has at least one more element.
To sum it up; this rule allows anyone in one of A's descendants (but no A itself) to join A or any of its descendants (we assume subchannels inherit the rule).
If we don't use the ~, then it will allow people in any of A descendants to go up (ie, from Sub1 to A1 or A but not the other way) or, in other words, allow people in the descendant of a channel (any depth) to enter it.
Let's add a new rule to A1:
- @sub,-1,0 +link
This allows anyone that's in the parent (equal path up to -1 elements (the first parameter)) or any of the siblings (path length equal (the 0 parameter)) to link to this channel.
And finally, just to show how messed up it can get, let's add this on B:
- @~sub,-1,2,2 +enter
This lets anyone that's currently in a descendant of Root (B's parent) and has a path length of exactly 2 (length of Root.B -1 + 2) join, so this rule would match someone in A1, but not A or Sub1.
This gives total control over the channel, including the ability to edit ACLs. This privilege implies all other privileges.
Without this privlege, a player will be unable to access the channel or any subchannels in any way, regardless of privileges in the subchannel. Don't deny this unless you really know what you're doing; you can probably achieve the effect you want by denying a player the Enter privlege.
Allows player to enter channel. Even without this privilege, a player can be moved into the channel by a player with Move/Kick.
Allows player to speak in channel. For linked channels, only players with Speak privilege in the destination channels will be heard. This can be used to set up a hierarchy of linked channels where all players can hear all the leader of each group, but normal players will not be propageated outside their channel. This way, players will hear someone else is talkig to the group leader and (hopefully) stop talking for a short while.
If a player joins a channel he does not have Speak privilege in, he will be suppressed by the server, and will be unable to speak until someone unmutes him.
Mute / Deafen
Allows a player to mute or deafen another player. Note that mute status will follow a player until he is either manually unmuted or reconnects to the server.
Move / Kick
Allows a player to move another player to another channel or kick them off the server. Unless the target player has Enter privileges in the channel he's being moved to, Move privileges is required in both channels.
Allows a player to make a subchannel in the current channel. The player will automatically be added to the admin group in the new channel, so make the inheritable ACLs give the privileges you desire.
Allows a player to link or unlink, as well as push-to-link a channel. Unlinking requires Link privilege in either channel, and linking requires Link privilege in both.
Allows a player to speak in channel if he is holding the Alt Push-To-Talk key(can be configured in the Shortcuts tab of the options window). It works as Speak for linked channels, etc.
Group of servers with FPS game
In this example, we assume we have a group of public servers running FPS games. Each game has 2 competing sides, and each side consists of one or more squads. We want a hierarchy such as this:
- Team 1
- Squad 1
- Squad 2
- Team 2
- Squad 1
- Team 1
Let's assume we have a small script linked with qstat that puts the player in the channel of the right side, and once in there we want to give them the ability to switch between squad channels and link at will. However, we do not want them to gain access to the channels of the other side.
This is actually a very straightforward implementation; on the "Servers" channel, define an empty group called players. Then, add the following acls:
- @all deny enter
- @~sub,2,2 allow enter, allow link
The first rule denies enter privilege to all players, and the second rule allows anyone within a hierarchy at least 2 elements down from "Servers" to move and link at will. In practice, this means that once a player is inside "Team 1", he can move freely about in there but can't switch to the other team or another server subchannel.
Assume this setup:
- Damage Dealers
- Wussards and other pets
The desire is to have one leader of each group, plus a few people as raid leaders.
Set this up as follows: In "Raid", create a group called "groupleaders". Put the leader of each group in this group. In the same channel define "raidleaders", and put the raidleaders in this group.
In the Raid channel, define the following ACLS:
- @all deny enter, deny speak [Apply Here only]
- @raidleaders allow enter, allow speak, allow link, allow mute, allow kick [Apply Here and Apply Subs]
- @groupleaders allow speak, allow link [Apply Here only]
- @groupleaders allow link, allow mute, allow kick [Apply Subs only]
The first rule makes sure nobody can speak or enter the Raid channel. The second rule lifts this restriction from anyone in the raidleaders group as well as giving them broad permissions. The third rule makes sure groupleaders can link and speak to the raid channel, and the fourth gives them permission to link from the subchannel as well as get rid of troublesome players.
Normal players will not be able to join the raid channel, but as that denial only applied in the raid channel they can join any subchannel they wish. When the channels are linked, everyone in the linked channels will hear raid leaders and group leaders. However, raid leaders will only hear group leaders, they will not hear normal players. This way, players can stay quiet when they hear a command coming down (and also hear the command direct without the groupleader having to repeat it), and if they don't that won't bother the rest of the raid.