BW List

Intro

It can be very helpful to black- or white-list users and commands. Sibyl allows such rules to be created using the bw_list config opt. You should be aware that when using the rename config opt, you should use the new (renamed) command names when defining bw_list.

NOTE: When using XMPP, you should use "real" JIDs for the black/white list. For more details see the Notes section on the XMPP Protocol page.

Syntax

The bw_list option is a list of rules separated by semi-colons. Each rule must contain 3 values separated by spaces. The first value is either b or w to signify either blacklisting or whitelisting.

The second value, the "from" field, can be a user, room, protocol, or * (meaning all). Note that in general you should not include resources for users. Multiple "from" entries can be specified in a single rule by separating them with commas. The formats for "from" entries, along with examples, are shown below:

type      format                example
----------------------------------------------------------------------
user      u:protocol:username   u:xmpp:[email protected]
room      r:protocol:room       r:xmpp:[email protected]
protocol  p:protocol            p:xmpp

The third value, the "id" field, can be the name of a Sibyl command, plugin, or * (meaning all). Multiple "id" entries can be specified by separating them with commas. The formats for "id" entries, along with examples, are shown below:

type      format    example
------------------------------
command   cmdname   reboot
plugin    name.py   xbmc.py

In both of the above cases, you can mix different entry types in a single rule. For example, the following is a valid rule:

w u:xmpp:[email protected],r:xmpp:[email protected],p:socket reboot,xbmc.py

When Sibyl tries to execute a command, it searches through the bw_list until it reaches the last applicable rule (i.e. later rules override/supercede earlier rules). A rule matches if the user invoking the command matches an entry in the "from" field and the command matches an entry in the "id" field.

Sibyl always inserts the rule w * * at the beginning of the bw_list, which allows any user to execute any command. You can change the default to forbidding every user from executing any command by putting b * * as the first rule in your config. For example, the below rules would allow alice and bob to execute any command, only allow carol to execute play and pause, and not allow dave to execute anything. In a real example, u:alice would be replaced with a full username such as u:[email protected]. For the sake of this explanation, we will only be using users in the "from" fields and commands in the "id" fields.

bw_list = b * *;
          w u:alice,u:bob *;
          w u:carol play,pause

You can also use Python's SafeConfigParser syntax to make rules easier to define. You can create your own custom option and then reference it later with %(myopt)s. For example, the below is equivalent to the above:

users = u:alice,u:bob
cmds = play,pause

bw_list = b * *;
          w %(users)s *;
          w u:carol %(cmds)s

Using the above example, let's look at two commands from three users and see how the logic works. Remember, w * * is always the first rule, even if you don't specify it in the config. So we are effectively dealing with the following:

w * *;
b * *;
w u:alice,u:bob *;
w u:carol play,pause

First, bob tries to execute the play command. The last rule that matches is w u:alice,u:bob *, which allows him to execute play.

Now carol tries to execute the play command. The last rule that matches is w u:carol play,pause, which allows her to execute play.

Finally, carol tries to execute the stream command. The last rule that matches is b * *, which does not allow her to execute stream.

The black/white list shown in the readme is a good default to use, as there are commands you likely do not want other users able to execute, especially those that must be enabled with the chat_ctrl option. Ideally you want w * %(admin_usrs)s to be the very last rule to ensure that admins can, in fact, execute anything.

admin_cmds = config,die,join,leave,log,reboot,xbmc
admin_usrs = u:[email protected],u:[email protected]
bw_list = b %(admin_cmds)s *;
          w * %(admin_usrs)s