User Privileges System

Privileges are a way to limit a users usage/access of the bot.
Some commands in JJMumbleBot are restricted to only administrators of the bot so that regular users may not abuse them. These commands include blacklisting, whitelisting, quitting the bot, etc.

Setting User Privileges

To modify the user privileges of a user in your mumble server, follow these steps:

Changing Single User Privileges:

  1. As an administrator or super user, if the user doesn't already exist in the database,
    use the command: [!addprivileges 'username' 'level_number'] to add the user to the database with the given privilege level.
  2. As an administrator or super user,
    use the command: [!setprivileges 'username' 'level_number'] to set an individual user's privilege level. By default, any new users detected by the bot are set to default privilege levels.
NOTE: Only super users can modify the user privileges of an administrator through the command method. Administrators cannot modify another administrator's user privileges.
Users may also not modify their own user privileges (so an admin can't change his user privilege level to owner).

Changing Multiple User Privileges:

There are two methods of updating multiple user privileges: Local File Method or Remote URL Method.

Local File Method
  1. Utilizes single custom_user_privileges.csv file in the JJMumbleBot/cfg/ directory to update user privileges in the database
  2. Useful for local deployments and docker builds with a mounted /cfg/ folder.
  3. Use the command: [!refreshuserprivileges] to update the user privileges to the database with the given privilege level.
    4. NOTE: Only super users can modify the user privileges of an administrator through the command method. Administrators cannot modify another administrator's user privileges.
    Users may also not modify their own user privileges (so an admin can't change his user privilege level to owner).
Remote URL Method / Import Method
  1. Utilizes a csv file from a remote URL endpoint instead of a local file.
  2. Useful for remote/cloud deployments where access to the filesystem is limited.
  3. Use the command: [!importuserprivileges] to import user privileges from a csv file hosted at a URL.

Manually Update User Privileges:

  1. Access the jjmumblebot.db database file located under the cfg directory using a sqlite browsing software.
  2. Add the names of mumble users that you want if they don't already exist to the users table. Set their permission levels to whatever level number you wish in the permissions table. Make sure that the permission level you choose is a valid permission level from the permission_levels table.
    The default available user privilege levels are:
    • BLACKLIST - level 0
    • DEFAULT - level 1
    • ELEVATED - level 2
    • MODERATOR - level 3
    • ADMINISTRATOR - level 4
    • SUPER USER- level 5
  3. Save the file and start the bot.

Checking User Privileges At Runtime

There is a command available for checking the user privileges of all the registered users in the database at runtime.
Use [!showprivileges] as an administrator or super user to view the entire list of users and their privilege levels.
This is particularly useful when you need to quickly check a user's privilege level after modifying it recently.

Adding Users To The Blacklist

There are commands that are used in plugins which you may not want all users to be able to access.
For this purpose, administrators and owners are able to use the [!blacklistuser 'username' 'reason'] command to blacklist users from using certain commands.
To add a user to the blacklist, follow these steps:

Manual Method:
  1. Access the jjmumblebot.db database file located under the cfg directory using a sqlite browsing software.
  2. Add the names of mumble users that you want if they don't already exist to the users table. Set their permission levels to 0 in the permissions table.
  3. Save the file and start the bot.
Normal/Command Method:
  1. Use the [!blacklistuser 'username' 'reason'] command to blacklist specific users from using non-blacklist only commands.
    You can optionally provide a reason to the blacklist so that the user can know why he/she was blacklisted.
    2. For example: !blacklistuser baduser123
    This command is equivalent to [!setprivileges 'username' 0]
    For example, blacklisting with a reason: !blacklistuser baduser123 because you are bad!

Removing Users From The Blacklist [A.K.A Whitelisting]

If for whatever reason you want to remove a user from the blacklist, either modify the jjmumblebot.db database file manually and change their level to anything but 0. Or use the command [!whitelistuser 'username'].
For example: !whitelistuser notsobaduser123
This command is equivalent to [!setprivileges 'username' 1]