ACL_and_Groups.txt

{{Languages|ACL and Groups}}
= Mumble Access Control Vocabulary =
Mumble has a rich and powerful set of tools for controlling access. In order to understand those tools, it's essential to understand certain fundamental terms as follows:
'''Channel:''' The most basic tool for separating Mumble conversations is the "Channel". In its most basic configuration, Mumble servers create just one Channel, and all users communicate with one another simultaneously by entering and speaking within that channel. As simple Mumble servers attract more users, it is commonplace for them to be expanded with several distinct Channels, allowing different groups of people to isolate their conversations within those distinct Channels. In these simple situations, conversations within one Channel are not heard in any of the other Channels.

'''Channel Hierarchies:''' Related Mumble Channels can be organized Hierarchically, like members of a family. Channels can have "Children", "Parents", and "Siblings". This can go on for several "Generations", so that one Channel can be the Child of its Parent and it can also be the Parent of its own Children. The depth of this Parents/Children hierarchy can continue to grow. In large Mumble Channel hierarchies, we might refer to a channel's "Ancestors" and "Descendants", and we might refer to the common ancestry between two related Channels according to the number of "Generations" back to a common Ancestor.   Here is a picture of a very simple Channel Hierarchy:

               ----Team1
              |
     Mission1-|
              |
               ----Team2

In that example, the Channel named "Mission1" has two Children, named "Team1" and "Team2". The Channel named "Team1" has one Parent ("Mission1") and one Sibling ("Team2"). Following the same pattern, the Channel named "Team2" has one Parent ("Mission1") and one Sibling ("Team1"). Even though all three of these Mumble Channels have an obvious Hierarchical relationship, conversations within one of them are still isolated from the others unless additional Mumble tools are put into place.

'''Channel Links:''' After a Mumble server grows enough to support several channels, it is sometimes desirable for two or more channels to be "Linked" so that their conversations can be shared. For example, suppose that the simple Channel Hierarchy shown in the prior example grows into a larger Channel Hierarchy like this:
               ----Team1
              |
     Mission1-|
              |
               ----Team2

               ----Team1
              |
     Mission2-|
              |
               ----Team2

In this larger situation supporting two different Missions, it might be desirable for everybody participating in Mission1 to communicate with one another in one large group, without interfering with conversations associated with Mission2, and vice versa. Mumble allows this through a tool that it calls "Channel Links". By joining a Mumble Channel and then right-clicking on the name of one of its Children or Descendants, a Mumble Administrator is presented with a menu option that can be used to "Link" them. Two or more Linked Channels of this type are known as "Link Communities". Within one of these Link Communities, all conversations are heard by everybody in any of the Linked Channels. Referring to the diagram immediately above, it would be easy for a Mumble Administrator to create one Link Community for Mission1 with its Children, and a second Link Community for Mission2 with its Children, so that players participating in those missions can communicate within their own mission, regardless of the team they have joined, without interfering with the other mission. 

Channel Links of this type are, however, unsophisticated; they merge ALL conversations within the Link Community. As a Mumble server attracts more and more users for more and more advanced use, it can sometimes become desirable to restrict this merging of a Link Community's conversations. For example, suppose players of Mission1's "Team1" want to put together a secret plan, unknown to "Team2". In fact, in situations like that illustrated in the diagram above, it is commonplace for team-oriented players to want to speak in private on their own channel some of the time, while preserving the option to speak to the entire Link Community at other times. Mumble provides various different kinds of tools to help with this.

'''Access Control Lists ("ACLs"):''' Use of every Mumble Channel is restricted by a list of rules known as its "Access Control List" or "ACL". Upon initial creation of a new Channel, its ACL is populated with default rules that allow sensible access with few restrictions. Usually those rules are simply "inherited" from the Channel's Parent. However, authorized Mumble Administrators that right-click on the name of a Mumble Channel will see a pop-up menu allowing them to modify its ACL by eliminating or modifying existing rules, or by adding new ones.

'''Groups:''' Mumble's "Groups" serve as a convenient way to define or limit the scope of the rules in an "Access Control List" or "ACL". Because each rule in each Access Control List operates on some group of users in order to grant or limit what can be done in a Mumble Channel, it's important to understand Mumble's Groups before creating any of those rules.

Whenever a Mumble Channel is created, Mumble automatically gives it several specially named Groups, each with a descriptive name and purpose. They are:
* "all": Everybody using this channel by any means.
* "admin": People with administrative authority for this channel.
* "in": Everybody tuned to this channel
* "out": Everybody NOT tuned to this channel.
* "sub": Everybody in a channel with parent or ancestor in common with this channel. Optional parameters designate maximum and minimum parental separation
* "~in":
* "~sub":
* "~out":

Those names suggest the purpose of each group and the scope of any rule written for that group. For example, any rule written for the "all" group of any channel will apply to everybody using the channel in any way, even if they have some kind of access to the channel without actually being tuned to it (such as access through a Mumble "Link"). Any rule written for the "in" group of that channel will apply only to everybody that is currently tuned to that channel. The tilde ("~") character limits the associated group to the channel in which it is defined, eliminating any effect of inheritance or links.

In addition to those predefined groups, appropriately authorized users can create additional ones, assigning descriptive names to help clarify their purpose. These allow specific groups of people, referenced by their Mumble usernames, to enjoy defined privileges or protection as defined by rules referencing those new groups.

Continuing our discussion of Groups, ACLs, Links, and Channels, let's return to our first little Channel Hierarchy diagram:
               ----Team1
              |
     Mission1-|
              |
               ----Team2

Suppose we want to isolate the two Siblings "Team1" and "Team2" from one another so that they can hold private conversations, but we DON'T want that isolation to apply to the Parent channel "Mission1". That way, it's easy to share mission-wide conversations by hopping into the "Mission1" channel. Anybody lurking in "Mission1" can hear and interact with every conversation throughout that Mission1 Link Community, but when all members of both teams retreat into their respective Team channels, they don't hear one another, so they can share team-related secrets. After setting up the Link Community across all three of those Channels as described above, the desired Sibling isolation can be achieved by appending two new Rules onto the end of the Access Control List for the Parent Channel ("Mission1"). Those rules are:

New Rule 1 of 2: For group "~sub 0,1":  deny speak, operating only on Children of "Mission1"

New Rule 2 of 2: For group "in":        allow speak, operating on "Mission1" and its Children ("Team1" and "Team2").

The first of those two new rules, expressed as "~sub 0,1" denies speaking privileges into the first-generation Children. Because it is propagated only to the Children of "Mission1", this prevents those tuned to the "Team1" channel from speaking to "Team2" and vice versa.

The second of those two new rules, expressed as "in", allows permits speaking privileges to those tuned in to "Mission1". Because it is propagated to Mission1 and its children, it permits those tuned in to the "Mission1" channel to converse freely with "Team1" and "Team2".

= Activating Group and ACL Editors =
You must activate the "[[Advanced client configuration|Advanced]]" checkbox in the Settings dialog (Configure → Settings) in order to see the Group and ACL editors for a channel.

To edit or create a new group, right click on the root channel and click "Edit" (usually you want to create groups from the root channel for easier management). Now click the "Groups" tab. You can now either select a group or add another one by clicking in the blank box called "Group", typing the group name and pressing enter. Now that the group is selected, add the users to the group by typing their registered name in the bottom left box and clicking "Add."

Groups are tied to a specific channel, but can also be inherited by subchannels, when the flag "Inheritable" is set in the parent channel and "Inherit" is set in the subchannel (usually you want these flags to be set). This opens a convenient way to administer channels and their ACLs; set up the ACLs on the top of the channel tree that should have a similar privilege structure, and just change the group memberships on subchannels.

For each channel, a group has 3 pieces of data:<br>
1. "Members": the list of players to add to the group (i.e. because they are not members of the same group in the parent channel already),<br>
2. "Inherited members": the list of members inherited from the same group in the parent channel and<br>
3. "Excluded members": the list of inherited members to remove from the group.

'''Note: Only registered players can be added to groups.'''

== Example ==
Let's take a practical example, the ''admin'' group. Every time a player makes a channel, they are automatically added to its admin group. This doesn't automatically give them any privileges, it just marks them as a member of that group, however Murmur's default installation installs an ACL that grants the ''admin'' group the ''Write ACL'' (all access) permission.

In a structure like this:
* Root
** A
*** B
** C
*** D

player "Big Boss" is the only ''Member'' of the ''admin'' group in Root. In channel A, player "BossA" and in channel B, "BossB" are added to the ''Members'' of ''admin'',

In the channels Root, A and B the flags ''Inherit'' and ''Inheritable'' are set for the ''admin'' group (default setting in Murmur). A player being a member of that group in any of these channels thus is an ''inherited member'' in a subchannel. So the total list of members in channel B is "Big Boss, BossA, BossB". The convenience of this system is that if we later add "Super Boss" to admin in Root, he'll automatically be in the admin group of the channels A and B.

Let's move on, and say that player "BossC" is in the Members list in channel C, but here admin is not marked as ''inherit''. This means that "Big Boss" is not in the admin group 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 =
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 an all or nothing deal. ACL are evaluated in order, from top to bottom along the chain of channels. To add or remove an ACL, right click on the channel you wish to change ACL's on and click "Edit ACL." Once you add an ACL, you set the group the ACL defines by typing its name in the bottom left box labeled "Group." If you just want to set an ACL for a specific user, leave the Group box blank and type the name of the user in the box labeled "User ID."

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 ''!'', its 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
Everyone
: auth
All authenticated users
: in
All users inside current channel
: out
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:
* Root
** A
*** A1
**** Sub1
**** Sub2
*** A2
*** A3
** B
*** B1
*** B2

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 (so in all sub-channels).

If this first parameter had been 1 the evaluation would start one level below Root.A, where the ACL was defined. The second parameter with value 1 indicates all sub-channels (thus now of Root.A.*) are allowed to enter. So we would be allowed to enter Sub1 and Sub2.

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 not 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.

== Channel Passwords and Access Tokens ==
Beginning with Mumble 1.2, it is now possible to set access on channels based on "tokens" or "passwords". Passwords are stored in a tokens list in the client for each server, with the client using them as needed. From this point forward, we will refer to channel passwords as "tokens" instead, for clarity.

=== Configuring an Access Token ===
Access Tokens are configured by creating special groups, which consist of the token prefixed by a pound symbol. For example a token called "letmein" corresponds to a group called #letmein.

The Channel Editor dialog box contains a field called "password". Entering "letmein" in the password field will automatically create a token group called #letmein, then by default will deny "Enter" access to @all and allow "Enter" access to users in the group #letmein, which will consist of any user who has that token in their token list.

To create token groups manually, first enable the Advanced Channel Editor. Then Edit a channel and go to the ACL tab. On the bottom of the ACL list, select the @all entry and check the "Deny Enter" permissions box. Now click "Add", and in the "Group" combobox at the bottom write #letmein and press enter. Now check the "Allow Enter" permissions box, and click OK to dismiss the editor.

=== Using an Access Token ===
You may add access tokens to your client by selecting "Access Tokens" from the "Server" menu. Click add, type the token (e.g. "letmein") and click "OK". It should take effect immediately, granting you whatever permissions are associated with that token group. Remember that tokens are passwords, so treat them as such; pick a token name that is unique and hard to guess.

= Permission Definitions =
== Write ==
This gives total control over the channel, including the ability to edit ACLs. This privilege implies all other privileges.

== Traverse ==
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.

== Enter ==
Allows player to enter channel. Even without this privilege, a player can be moved into the channel by a player with Move/Kick.

== Speak ==
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 they do not have Speak privilege in, they will be suppressed by the server, and will be unable to speak until someone unmutes them.

== Mute / Deafen ==
Allows a player to mute or deafen another player. Note that mute status will follow a player until they are 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.

== Make Channel ==
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.

== Make Temporary Channel ==
Allows a player to make a temporary subchannel in the current channel, which will automatically be deleted when the last user leaves it. The creator will automatically be moved into the channel after creating it.

== Link Channel ==
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.

== AltSpeak ==
Allows a player to speak in channel if they are 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. This may be used to broadcast to a hierarchy of channels without having to link to them.

= Examples =
An elaborative [[ACL Tutorial|ACL Tutorial is also available]].

== Channel Group - Speak to children but not siblings ==
Suppose we have a channel group of parent with two children.

             __Child1
            |         
 Parent-----|
            |__Child2

We want users in x to be able to talk to y:

# Parent --> Parent, Child1, Child2
# Child1 --> Parent, Child1
# Child2 --> Parent, Child2

In other words: Be able to talk to parent, current, and children, but not siblings.

First, we link all three channels together so they can hear each other, and then we will deny speak in siblings.

To link the three channels together:

# Join Parent
# For Child1 execute the Link action (from right click = context menu on it)
# For Child2 execute the Link action (from right click = context menu on it)

The channels should now be linked; indicated by italic channel names and link symbols on the other linked channels.

Everyone should hear each other now, from all three channels.

Now for the next step, we want to deny hearing from sibling channels while still maintaining hearing from the others.

As described in the Speak permission definition, the determining factor for that is whether the speaker has speak permission in the ''target'' channel. (Remember, we are talking about multiple channels now. When a user talks from one channel they have multiple target channels.)

<blockquote>
For linked channels, only players with Speak privilege in the destination channels will be heard.
</blockquote>

To do this we plan some ACL rules that overwrite each other in different aspects. Our plan is as follows:

# Deny speak within the child level (this means also within the child itself)
# Allow speak in parent and self

To do this we define the following ACL rules in Parent:
# [Apply to this AND sub channels] @all allow speak
# [Apply to sub channels] @~sub,0,1 deny speak.
# [Apply in this AND sub channels] @in allow speak

Make sure the rule shows up correctly in the AC list. You may have to press enter after changing the sub specifier and parameters for it to apply.

You can test that it works alone by using the Text message permission and action instead of Speak. If the Send text message action is enabled, you have permission.

The first rule defines a base state: allowed to speak.

For the second rule the ~ is used for the rule to be applied in the context of where it was defined; the Parent channel. It does however only apply in child channels.

The 0 parameter specifies that it applies from the current channel Parent. And the 1 parameter defines the minimum sub level to one, so all children below Parent.

The third rule has no ~, so the rule will apply in the context of the current channel. It is active in Parent as well as in sub channels, where it is inherited to.

So if we are in Child1:
# For Child1 the evaluation bottom to top
## The @in rule that is inherited will allow us to Speak within Child1
# For Child2 the evaluation bottom to top
## The @in rule is inherited into Child2, but does not apply because we are not in it
## The @~sub,0,1 rule is inherited into Child2, is evaluated in the context of Parent (~ prefix), and applies because Child2 is 1 level below Parent. It denies speak
# For Parent the evaluation bottom to top
## The @in rule does not apply because we are not in it (child does not count)
## The @~sub,0,1 rule does not apply because it is for a minimum of 1 below
## The @all rule allows speak

== 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:
* Servers
** "Servername"
*** Team 1
**** Squad 1
**** Squad 2
**** ...
*** Team 2
**** Squad 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", they can move freely about in there but can't switch to the other team or another server subchannel.

== MMORPG Raid ==
Assume this setup:
* Root
** Raid
*** Healers
*** Tanks
*** 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.

[[Category:Documentation English]]
[[Category:Needs Update for 1.2.0]]