GGU OpenMod MySQL Permissions Setup Guide

[- Alex - 36]

GGU OpenMod MySQL Permissions Setup Guide
Roles, Inheritance, Grants, Denials, Assignments & Cache Management
GGU Public Technical Knowledge Base

Applies to GGU.OpenMod.MySqlPermissions v0.7.0 • Guide updated October 4, 2026

 

Public Knowledge Base
This guide documents GGU's internal GGU.OpenMod.MySqlPermissions permission system. The plugin itself is private and is not publicly distributed, but the technical information in this guide is public so other server operators can understand the permission-management concepts, command structure, and architecture GGU uses.

Introduction

GGU.OpenMod.MySqlPermissions is a private, in-house GGU OpenMod plugin that stores roles, inheritance, actor assignments, permission grants and denials, and role/actor metadata in MySQL. This makes permission data persistent outside individual server configuration files and allows the same permission structure to be shared or synchronized across GGU servers when they use the same configured scope.

Availability
The plugin is not a public download and is not offered as a supported third-party package. This documentation is public for transparency, technical reference, and knowledge-sharing purposes.

The plugin is designed to be administered through its own command interface rather than by manually editing permission YAML for routine role and player changes.

Command Aliases
/gguperms is the primary command. The aliases /gp and /ggup can be used in its place.

Prerequisites & Administrative Access

• OpenMod is installed and running.
• GGU.OpenMod.MySqlPermissions is installed on an authorized GGU-managed OpenMod server and connected to its MySQL database.
• The database schema has initialized successfully.
• You know the Steam64 ID of any player receiving a direct role or permission assignment.
• You have an authorized administrative path to execute the permission-management commands.

Administrative Permission Node

GGU.OpenMod.MySqlPermissions:commands.gguperms

Critical Access Warning
Do not remove your last working administrative path until a replacement role or account has been tested. Permission mistakes can lock administrators out of in-game management.

Understanding the Permission Model

• Role: a named collection of permissions and metadata.
• Parent role: a role inherited by another role.
• Grant: explicitly allows a permission node.
• Deny: explicitly denies a permission node.
• Actor: the player or other OpenMod actor receiving direct permissions or roles.
• Priority: an integer stored with a role for ordering/resolution.
• Auto role: a role configured for automatic assignment.
• Expiration: an optional end time on a player-role assignment; permanent assignments use no expiration.
• Role data: metadata such as prefixes, suffixes, colors, cooldown data, or other JSON-backed values consumed by compatible plugins.

Recommended Design
Build permissions from small reusable roles and inheritance. Avoid granting * broadly. Keep player perks and staff authority in separate branches unless staff are intentionally supposed to inherit the player-perk role.

Step 1: Verify the Plugin & Cache

Before creating roles, confirm the permission provider is responding.

/gguperms cache status

In the v0.7.0 configuration used by this guide, caching can be enabled with a fallback TTL of 300 seconds. External assignment and permission changes are also synchronized so affected cache entries are invalidated without waiting for the full fallback TTL.

Known v0.7.0 Cache/Scope Settings

scope:
  name: global

cache:
  enabled: true
  ttl_seconds: 300

Step 2: Create the Base Roles

The following example creates a clean role hierarchy. Names and permission nodes are examples; adapt them to the plugins and responsibilities on the GGU server being configured.

Create the Default Role

/gguperms role create default "Default"
/gguperms role priority default 0
/gguperms role auto default true

Create a Player-Perk Role

/gguperms role create vip "VIP"
/gguperms role priority vip 10
/gguperms role parent add vip default

Create a Staff Hierarchy

/gguperms role create helper "Helper"
/gguperms role priority helper 20
/gguperms role parent add helper default

/gguperms role create moderator "Moderator"
/gguperms role priority moderator 50
/gguperms role parent add moderator helper

/gguperms role create admin "Administrator"
/gguperms role priority admin 80
/gguperms role parent add admin moderator

Inheritance Principle
A child role should contain only the additional access needed beyond its parent. This keeps the permission tree readable and prevents the same nodes from being copied into every rank.

Step 3: Grant Permissions to Roles

Add only the permission nodes each role requires.

/gguperms role permission add default OpenMod.Core.Commands.help

/gguperms role permission add moderator RocketMod.Essentials.kick
/gguperms role permission add moderator RocketMod.Essentials.teleport

/gguperms role permission add admin RocketMod.Essentials.ban
/gguperms role permission add admin RocketMod.Essentials.unban

Explicit Denials

/gguperms role permission deny moderator RocketMod.Essentials.shutdown

To remove an explicit role permission entry, use:

/gguperms role permission remove moderator RocketMod.Essentials.shutdown

Use Denials Carefully
The plugin supports grants, explicit denials, inheritance, and wildcard-style permission structures. Keep deny rules limited and test inherited combinations before rolling them out broadly.

Step 4: Assign Players to Roles

Permanent player assignments should use the player's Steam64 ID rather than a display name.

/gguperms player role add 76561198090988183 moderator

Remove the role with:

/gguperms player role remove 76561198090988183 moderator

Step 5: Temporary / Expiring Roles

Role assignments can carry an expiration time. This is useful for temporary staff access, timed VIP access, event roles, testing access, or contractor/partner permissions.

/gguperms player role expiry set 76561198090988183 vip 2026-10-31T23:59:59Z

Inspect or remove the expiration with:

/gguperms player role expiry show 76561198090988183 vip
/gguperms player role expiry clear 76561198090988183 vip

Expiration Format
Use an explicit UTC timestamp such as 2026-10-31T23:59:59Z. Permanent assignments are stored without an expiration.

Step 6: Direct Player Permissions

Direct player permissions are best used for narrow exceptions. If several players need the same access, create a role instead.

/gguperms player permission add 76561198090988183 Example.Plugin:commands.example
/gguperms player permission deny 76561198090988183 Example.Plugin:commands.dangerous
/gguperms player permission remove 76561198090988183 Example.Plugin:commands.example

Step 7: Inspect Roles Before Changing Them

/gguperms role list
/gguperms role show moderator

Use role show before modifying an existing production role so you understand its current parents, priority, automatic-assignment state, and permission entries.

Step 8: Manage Role Inheritance

Add or remove parent relationships with:

/gguperms role parent add moderator helper
/gguperms role parent remove moderator helper

Avoid Inheritance Loops
Keep the role tree one-directional. A parent should never inherit from one of its own children.

Step 9: Role Metadata & Plugin Data

The permission store can associate data with roles. Common uses include prefixes, suffixes, colors, cooldown definitions, or arbitrary JSON consumed by another plugin.

Inspect Role Data

/gguperms role data list default
/gguperms role data show default cooldowns

Set Role Data

/gguperms role data set default cooldowns [{"command":"Rocket.pvp","cooldown":"1 minute 30 seconds"}]

Remove Role Data

/gguperms role data remove default cooldowns

Metadata Is Consumer-Dependent
Storing a key does not automatically make it visible in chat or change plugin behavior. Another plugin must read and use that role data.

Step 10: Cache & Synchronization

v0.7.0 caches effective roles, inherited roles, grants, and denials. Changes made through the permission system invalidate the affected cache. The synchronization path also detects externally changed assignments and direct permissions so multiple servers using the same permission data do not need to wait for the entire cache TTL.

Check Cache State

/gguperms cache status

Force a Cache Clear

/gguperms cache clear

Use a manual cache clear when troubleshooting stale access, after emergency database work, or when verifying a synchronization issue.

Recommended Role Layout

default
├── vip

default
└── helper
    └── moderator
        └── admin

This model keeps optional player perks separate from staff authority. If your organization intentionally gives staff the same perks as VIPs, add the appropriate parent relationship or grant those permissions through a shared parent role rather than duplicating nodes.

Quick Start Example

A minimal working setup could look like this:

/gguperms role create default "Default"
/gguperms role priority default 0
/gguperms role auto default true
/gguperms role permission add default OpenMod.Core.Commands.help

/gguperms role create moderator "Moderator"
/gguperms role priority moderator 50
/gguperms role parent add moderator default
/gguperms role permission add moderator RocketMod.Essentials.kick

/gguperms role create admin "Administrator"
/gguperms role priority admin 80
/gguperms role parent add admin moderator
/gguperms role permission add admin GGU.OpenMod.MySqlPermissions:commands.gguperms

/gguperms player role add 76561198090988183 admin
/gguperms role show admin
/gguperms cache status

Do Not Copy Example IDs into Production
Replace all example Steam64 IDs, role names, and plugin permission nodes with the values appropriate for the GGU server or environment being configured.

Role Administration Command Reference

View Procedure

/gguperms role create <role> "<display name>"
/gguperms role delete <role>
/gguperms role list
/gguperms role show <role>
/gguperms role priority <role> <integer>
/gguperms role auto <role> <true|false>

/gguperms role parent add <role> <parent>
/gguperms role parent remove <role> <parent>

/gguperms role permission add <role> <permission>
/gguperms role permission deny <role> <permission>
/gguperms role permission remove <role> <permission>

/gguperms role data list <role>
/gguperms role data show <role> <key>
/gguperms role data set <role> <key> <value>
/gguperms role data remove <role> <key>

Player Administration Command Reference

View Procedure

/gguperms player role add <steam64> <role>
/gguperms player role remove <steam64> <role>

/gguperms player role expiry set <steam64> <role> <UTC timestamp>
/gguperms player role expiry show <steam64> <role>
/gguperms player role expiry clear <steam64> <role>

/gguperms player permission add <steam64> <permission>
/gguperms player permission deny <steam64> <permission>
/gguperms player permission remove <steam64> <permission>

Cache Command Reference

View Procedure

/gguperms cache status
/gguperms cache clear

Database Reference

The plugin's MySQL schema stores the permission model in separate tables. With the standard ggu_openmod_ prefix, the core data includes roles, role-parent relationships, actor-role assignments, permission entries, role data, and actor data.

• ggu_openmod_roles
• ggu_openmod_role_parents
• ggu_openmod_actor_roles
• ggu_openmod_permissions
• ggu_openmod_role_data
• ggu_openmod_actor_data

Direct SQL Changes
The database is the authoritative backing store, but routine GGU administration should use the plugin commands. Direct SQL is appropriate only when you understand the schema and synchronization implications. Back up production permission data before bulk changes.

Troubleshooting

A Player Did Not Receive a Role

• Verify the Steam64 ID.
• Confirm the role exists with /gguperms role show <role>.
• Check whether the assignment has expired.
• Confirm all servers are using the intended permission scope.
• Check the cache state and clear it if troubleshooting stale data.

A Permission Still Does Not Work

• Verify the permission node exposed by the target plugin.
• Check the role's parent chain.
• Look for an explicit deny on the role or player.
• Confirm the target plugin is loaded.
• Use a narrow direct grant temporarily to isolate whether the problem is the role hierarchy or the permission node itself.

A Database Change Is Not Visible Yet

• Allow the external synchronization poll to run.
• Use /gguperms cache status to inspect cache state.
• Use /gguperms cache clear when immediate troubleshooting is required.
• Verify that the servers are pointing at the same intended database and scope.

Permission Administration Is Locked Out

• Do not continue deleting or changing roles blindly.
• Use an already-authorized console or administrative recovery path.
• Restore the required management grant: GGU.OpenMod.MySqlPermissions:commands.gguperms.
• Clear the permission cache after emergency repair if needed.

Security & Best Practices

• Follow least privilege. Grant only what each role needs.
• Prefer role-based access over large numbers of direct player permissions.
• Use Steam64 IDs for permanent assignments.
• Use expiration timestamps for temporary access.
• Keep a clear, documented inheritance tree.
• Do not use * unless the account genuinely requires unrestricted access.
• Audit old staff, testing, partner, and temporary assignments regularly.
• Back up the permission database before bulk migrations or direct SQL work.
• Test high-risk permission changes with a non-owner account before applying them broadly.

GGU Operational Note
On GGU-managed servers, role and permission changes should follow the applicable access-control and change-management process. The MySQL permission store makes cross-server access easier to manage, but it also makes an incorrect global-scope change capable of affecting more than one server.

Verification Checklist

• The expected roles appear in /gguperms role list.
• Each role has the intended priority and automatic-assignment setting.
• Parent relationships form the intended hierarchy.
• Role permission grants and denials are correct.
• The test account receives the intended role.
• Inherited commands work.
• Denied commands remain blocked.
• Temporary-role expiration behaves as expected.
• Cache/synchronization behavior is healthy.
• No unnecessary wildcard permissions remain.

Conclusion

GGU.OpenMod.MySqlPermissions provides GGU with a centralized permission model for its OpenMod servers without requiring routine role management to be duplicated across local YAML files. A clean role hierarchy, narrow permission grants, stable Steam64 assignments, expirations for temporary access, and disciplined cache/database management provide a permission system that remains understandable as the server network grows.

 

Golden Gamers United
Bringing back the golden days, one server at a time.