Permissions - StellarStack

Overview

StellarStack uses a hierarchical permission system to control user access to server features. With 45+ permission nodes across 12 categories, you can create roles from view-only to full administrator access.

45+ Permission Nodes

Fine-grained control over every server action

Hierarchical Structure

Category-based organization with wildcard support

Preset Roles

Viewer, Operator, and Admin presets for quick setup

Subuser Management

Invite users with custom permission sets

Permission Structure

Permissions follow a hierarchical pattern:

category.action

Examples:

control.start - Start server
files.delete - Delete files
backups.restore - Restore from backup

Wildcard Permissions

Grant all permissions in a category:

control.* - All power control actions
files.* - All file operations
* - Full admin access to everything

Permission Matching

The system checks permissions in order:

Wildcard *: Full access, skip other checks
Category wildcard (e.g., control.*): All actions in category
Exact permission (e.g., control.start): Specific action only

Permission Categories

StellarStack organizes permissions into 12 categories:

1. Power Controls

Manage server power state:

Permission	Description
`control.start`	Start the server
`control.stop`	Stop the server gracefully
`control.restart`	Restart the server
`control.kill`	Forcefully kill server process

Wildcard: control.*

2. Console

Access server console:

Permission	Description
`console.read`	View server console output
`console.write`	Send commands to server console

Wildcard: console.*

3. File Manager

Manage server files:

Permission	Description
`files.read`	View and download files
`files.write`	Edit existing files
`files.create`	Create new files and folders
`files.delete`	Delete files and folders
`files.archive`	Create and extract archives
`files.sftp`	Connect via SFTP

Wildcard: files.*

4. Backups

Manage server backups:

Permission	Description
`backups.read`	View list of backups
`backups.create`	Create new backups (also lock/unlock)
`backups.delete`	Delete unlocked backups
`backups.restore`	Restore server from backup
`backups.download`	Download backup files

Wildcard: backups.*

5. Network Allocations

Manage IP:Port allocations:

Permission	Description
`allocations.read`	View server allocations
`allocations.create`	Add new allocations to server
`allocations.delete`	Remove allocations from server
`allocations.update`	Set primary allocation

Wildcard: allocations.*

6. Startup Configuration

Modify startup settings:

Permission	Description
`startup.read`	View startup configuration
`startup.update`	Edit startup variables
`startup.docker-image`	Change server’s Docker image

Wildcard: startup.*

7. Server Settings

Manage server metadata:

Permission	Description
`settings.read`	View server settings
`settings.rename`	Change server name
`settings.description`	Edit server description
`settings.reinstall`	Reinstall the server (destructive)

Wildcard: settings.*

8. Activity Logs

View audit trail:

Permission	Description
`activity.read`	View server activity logs

Wildcard: activity.*

9. Schedules

Manage scheduled tasks:

Permission	Description
`schedules.read`	View scheduled tasks
`schedules.create`	Create new scheduled tasks
`schedules.update`	Edit existing scheduled tasks
`schedules.delete`	Delete scheduled tasks

Wildcard: schedules.*

10. Subusers

Manage server access:

Permission	Description
`users.read`	View server subusers
`users.create`	Invite new subusers
`users.update`	Edit subuser permissions
`users.delete`	Remove subusers from server

Wildcard: users.*

11. Databases

Manage server databases:

Permission	Description
`database.read`	View database list
`database.create`	Create new databases
`database.delete`	Delete databases
`database.view-password`	View database passwords

Wildcard: database.*

12. Server Splitting

Split server resources:

Permission	Description
`split.read`	View child servers from splitting
`split.create`	Create child servers by splitting resources
`split.delete`	Delete child servers

Wildcard: split.*

Preset Roles

StellarStack provides three preset permission sets:

Viewer

Read-only access to server information:

[
  "console.read",
  "files.read",
  "backups.read",
  "allocations.read",
  "startup.read",
  "settings.read",
  "activity.read",
  "schedules.read",
  "users.read"
]

Use Cases:

Monitoring server status
Viewing logs and files
Checking configurations
Auditing activity

Operator

Manage day-to-day server operations:

[
  "control.start",
  "control.stop",
  "control.restart",
  "console.read",
  "console.write",
  "files.read",
  "files.write",
  "files.create",
  "backups.read",
  "backups.create",
  "allocations.read",
  "startup.read",
  "settings.read",
  "activity.read",
  "schedules.read",
  "schedules.create"
]

Use Cases:

Server restarts and management
File editing and uploads
Console command execution
Creating backups
Managing schedules

Admin

Full server access:

["*"]

Use Cases:

Server ownership
Complete control
Can manage subusers
Can delete/modify anything

Managing Subusers

Server owners can invite users with custom permissions:

Inviting a Subuser

Navigate to Subusers

Server → Subusers → Add Subuser

Enter Email

Email address of the user to invite (must have a panel account)

Select Permissions

Choose from:

Preset roles (Viewer, Operator, Admin)
Custom permission set
Individual permission nodes

Send Invitation

User receives email notification and gains access immediately

Required Permission: users.create

Editing Subuser Permissions

Navigate to Server → Subusers
Click Edit on target subuser
Modify permissions:
- Add/remove individual permissions
- Switch to different preset
- Grant/revoke category wildcards
Click Save
Changes apply immediately

Required Permission: users.update

Removing Subusers

Navigate to Server → Subusers
Click Delete on target subuser
Confirm removal
User loses all access to server

Required Permission: users.delete

Permission Use Cases

Example 1: Moderator Role

Allow moderators to manage players but not server configuration:

[
  "console.read",
  "console.write",
  "activity.read"
]

Can Do:

View console output
Execute commands (kick, ban, teleport)
View activity logs

Cannot Do:

Start/stop server
Edit files
Create backups
Modify settings

Example 2: Developer Role

Allow developers to edit files and view logs:

[
  "console.read",
  "files.read",
  "files.write",
  "files.create",
  "files.sftp",
  "backups.read",
  "backups.create"
]

Can Do:

View console
Edit configuration files
Upload plugins/mods via SFTP
Create backups before changes

Cannot Do:

Start/stop server (ask operator)
Delete files (safety)
Restore backups (destructive)

Example 3: Backup Manager

Dedicated role for backup management:

[
  "backups.*",
  "files.read"
]

Can Do:

Create backups
Download backups
Restore from backups
Lock/unlock backups
View files (for backup verification)

Cannot Do:

Edit files
Execute console commands
Change server settings

Example 4: Network Administrator

Manage allocations and network settings:

[
  "allocations.*",
  "settings.read"
]

Can Do:

Add/remove port allocations
Set primary allocation
View server settings

Cannot Do:

Start/stop server
Edit files
Execute commands

Permission Validation

The system validates permissions on every action:

Client-Side (UI)

Buttons and features are hidden/disabled based on permissions:

{hasPermission("control.start") && (
  <Button onClick={startServer}>Start Server</Button>
)}

If user lacks permission, UI elements don’t appear.

Server-Side (API)

All API endpoints enforce permissions:

// Example: Start server endpoint
servers.post("/:serverId/start", requireServerAccess, async (c) => {
  const user = c.get("user")
  const server = c.get("server")
  
  if (!hasPermission(user.permissions, "control.start")) {
    return c.json({ error: "Missing permission: control.start" }, 403)
  }
  
  // Start server...
})

Attempting unauthorized actions returns:

{
  "error": "Missing permission: control.start",
  "code": 403
}

Server Ownership

The server owner (creator) has implicit permissions:

Automatic * Wildcard: Owner has all permissions
Cannot Be Removed: Owner cannot be deleted as a subuser
Cannot Be Downgraded: Owner permissions cannot be reduced
Can Transfer Ownership: Admin can change server owner

Ownership is tracked via ownerId field on server record.

Best Practices

Principle of Least Privilege

Grant only the permissions users need:

Start with Viewer role
Add permissions as needed
Avoid blanket * wildcard
Review permissions regularly

Use Preset Roles

Leverage presets when possible:

Faster setup
Well-tested permission sets
Easy to understand
Customize from preset baseline

Separate Concerns

Create role-specific permission sets:

Moderators: Console + activity
Developers: Files + backups
Operators: Power + console + files
Backup managers: Backups only

Audit Subuser Access

Regularly review who has access:

Remove inactive subusers
Downgrade over-privileged users
Check activity logs
Rotate access for contractors

Protect Destructive Permissions

Be cautious with:

settings.reinstall - Wipes server data
backups.restore - Replaces current files
files.delete - Permanent file deletion
users.delete - Remove team members

Grant only to trusted users.

Troubleshooting

User Cannot Access Feature

Symptoms: Button grayed out or feature missing Solution:

Check user’s permission list
Verify required permission exists
Grant missing permission
User may need to refresh page

Permission Changes Not Applied

Symptoms: User still has old permissions after edit Solution:

Verify changes were saved
Ask user to log out and back in
Check for client-side caching
Clear browser cookies/storage

Cannot Grant Permission

Symptoms: Permission option not available when editing Cause: You lack users.update permission yourself Solution: Ask server owner or admin to grant permission

Subuser Invite Not Working

Symptoms: Cannot add subuser Causes:

No users.create permission: Ask owner to grant
Email not registered: User must create panel account first
Already a subuser: Cannot invite same user twice

Future Enhancements

Planned permission features:

Permission Templates: Save/load custom permission sets
Time-Based Permissions: Grant access for limited duration
IP Restrictions: Limit access to specific IP ranges
2FA Requirement: Require two-factor auth for sensitive permissions
Audit Logs: Detailed permission change history

Overview

Getting Started

Core Features

User Management

Automation

Advanced

Deployment

​Overview

45+ Permission Nodes

Hierarchical Structure

Preset Roles

Subuser Management

​Permission Structure

​Wildcard Permissions

​Permission Matching

​Permission Categories

​1. Power Controls

​2. Console

​3. File Manager

​4. Backups

​5. Network Allocations

​6. Startup Configuration

​7. Server Settings

​8. Activity Logs

​9. Schedules

​10. Subusers

​11. Databases

​12. Server Splitting

​Preset Roles

​Viewer

​Operator

​Admin

​Managing Subusers

​Inviting a Subuser

​Editing Subuser Permissions

​Removing Subusers

​Permission Use Cases

​Example 1: Moderator Role

​Example 2: Developer Role

​Example 3: Backup Manager

​Example 4: Network Administrator

​Permission Validation

​Client-Side (UI)

​Server-Side (API)

​Server Ownership

​Best Practices

​Troubleshooting

​User Cannot Access Feature

​Permission Changes Not Applied

​Cannot Grant Permission

​Subuser Invite Not Working

​Future Enhancements

Build docs developers (and LLMs) love

Overview

Permission Structure

Wildcard Permissions

Permission Matching

Permission Categories

1. Power Controls

2. Console

3. File Manager

4. Backups

5. Network Allocations

6. Startup Configuration

7. Server Settings

8. Activity Logs

9. Schedules

10. Subusers

11. Databases

12. Server Splitting

Preset Roles

Viewer

Operator

Admin

Managing Subusers

Inviting a Subuser

Editing Subuser Permissions

Removing Subusers

Permission Use Cases

Example 1: Moderator Role

Example 2: Developer Role

Example 3: Backup Manager

Example 4: Network Administrator

Permission Validation

Client-Side (UI)

Server-Side (API)

Server Ownership

Best Practices

Troubleshooting

User Cannot Access Feature

Permission Changes Not Applied

Cannot Grant Permission

Subuser Invite Not Working

Future Enhancements