Administration & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
The Administration and Permissions systems manage bot behavior and command accessibility across different contexts. The Administration system provides server-level utilities like role management, self-roles, and global announcements. The Permissions system extends the default security model, allowing guild owners and bot owners to define granular Access Control Lists (ACLs) for users, roles, and channels. Together, these components ensure secure operation while providing flexibility for server customization.
Sources: redbot/cogs/admin/admin.py, redbot/cogs/permissions/permissions.py
Administrative Utilities
The Admin module provides essential tools for managing server roles and cross-server communication. It enforces Discord's role hierarchy to prevent security escalations and ensures that neither the bot nor a user can grant roles higher than their own position in the hierarchy.
Sources: redbot/cogs/admin/admin.py:72-114
Role Management and Self-Roles
The bot facilitates role assignment through administrative commands and a self-role system. Administrators can designate specific roles as "user-settable," allowing members to add or remove them without administrative intervention.
- Hierarchy Checks: The system validates
ctx.guild.me.top_role > rolefor bot actions andctx.author.top_role > rolefor user actions. - Self-Role List: Maintained via
Config.register_guild(selfroles=[]). - Administrative Roles: Configured via
redbot/core/core_commands.pyusingaddadminroleandaddmodrole.
Sources: redbot/cogs/admin/admin.py:116-200, redbot/core/core_commands.py:1268-1320
Global and Local Announcements
The Admin cog includes an Announcer system that broadcasts messages to all servers or specific designated channels.
- Serverlock: A global setting that restricts the bot to its current servers, causing it to automatically leave any new servers it joins.
- Announcement Channels: Guilds can specify a channel for receiving announcements using
[p]announceset channel.
Sources: redbot/cogs/admin/admin.py:276-302, redbot/cogs/admin/admin.py:465-485
Permissions System Architecture
The Permissions system uses a custom Config schema to store rules for both individual commands and entire cogs. It operates on a hierarchy of checks that prioritize specific rules over general settings.
Rule Hierarchy and Processing Order
When a command is invoked, the system evaluates rules in a specific sequence. Global rules set by the bot owner are checked before server-specific rules.
The system checks rules in decreasing order of specificity: User > Voice Channel > Text Channel > Highest Role > Server.
Sources: redbot/cogs/permissions/permissions.py:165-177
Configuration Data Structure
Rules are stored using custom IDs (0 for Global) and mapped to booleans (true for allow, false for deny).
| Component | Key Level 1 | Key Level 2 | Key Level 3 | Value |
|---|---|---|---|---|
| COMMAND | Name (str) | Guild ID (int/0) | Model ID (int/default) | bool |
| COG | Name (str) | Guild ID (int/0) | Model ID (int/default) | bool |
Sources: redbot/cogs/permissions/permissions.py:90-105
Command Execution & Verification
The core command logic integrates permission checks during the prepare phase of command invocation.
Verification Flow
The Command.can_run method performs multi-stage verification:
- Discord.py Checks: Standard
@commands.checkpredicates. - Cog Level: Cog-wide requirements if the command belongs to a cog.
- Hierarchy: Checks all parent commands if it is a subcommand.
- Permissions Cog: Dynamic rules stored in the permissions database.
Sources: redbot/core/commands/commands.py:284-338
Rule Re-evaluation
When rules are cleared or modified, the system re-evaluates the "passive" and "active" states of parent groups and cogs to maintain consistency.
Issue Diagnosis
The IssueDiagnoser provides a structured way to identify why a specific user cannot run a command in a specific channel.
Diagnostic Tests
| Test | Description |
|---|---|
| Author Bot | Verifies the caller is not a bot. |
| Bot Permissions | Ensures the bot can send messages in the target channel. |
| Ignore List | Checks if the channel, category, or server is ignored. |
| Allowlist/Blocklist | Validates global and local user/role blocklists. |
| Permissions Rules | Inspects rules set via the Permissions cog. |
Sources: redbot/core/_diagnoser.py:84-230
Resolution Logic
The diagnoser provides actionable solutions, such as specific commands to run ([p]allowlist clear) or documentation links for Discord's hierarchy.
Sources: redbot/core/_diagnoser.py:328-360
Configuration and Management Commands
Administrators interact with these systems via specific command groups.
| Command Group | Purpose | Required Permission |
|---|---|---|
[p]permissions | Manage rule-based ACLs | Guild Owner / Administrator |
[p]permissions acl | YAML-based bulk rule management | Guild Owner / Administrator |
[p]allowlist | Global command access list | Bot Owner |
[p]blocklist | Global command denial list | Bot Owner |
[p]localallowlist | Server command access list | Administrator |
[p]admin | Server role utilities | Administrator / Manage Roles |
Sources: redbot/cogs/permissions/permissions.py:192-250, redbot/core/core_commands.py:1658-1850
Summary
The Administration and Permissions systems provide a layered approach to bot security. Administration handles role hierarchy and server-level settings, while the Permissions cog allows for granular, context-aware command overrides. The integration of an automated IssueDiagnoser ensures that complex rule configurations remain manageable for administrators and bot owners.
Sources: redbot/cogs/permissions/permissions.py:155-163, redbot/core/_diagnoser.py:650-680