Every administrator account is staff and holds a role. The level decides what staff see (every server and account); the role decides what they may do. Resellers and users have no staff role: their rules are their level, team roles and customer switches.
Built-in roles#
| Role | What it may do |
|---|---|
| Administrator | Everything, including permissions added in later releases |
| Support | Sees servers, customers, plans, nodes, networks, images, backups, tasks, sign-ins and the mail log. Starts, stops and reboots servers, opens consoles, and operates servers: rename, notes, ISO drives and boot order, hardware settings, root password reset, rescue. Deletes nothing, reads no secrets and changes no settings. |
| Read-only | Every "see" permission; changes nothing |
The built-in roles' permissions are fixed (their session rules can be changed). To make a variant, press Duplicate on a built-in role and edit the copy.
An administrator created with vmstack:create-admin, or one that existed before roles were installed, holds the Administrator role.
Making a role#
- Go to System › Staff roles › Add role.
- Give it a Name and an optional Description.
- Tick the permissions. There are 62, grouped by area: Servers, Customers, Staff, Nodes, Network, Images, Backups, Security, Logs, API, Settings and Billing. A permission that only reads is never one that reveals secrets (
servers.secretsis separate). - Under Sessions, optionally set Sign out after minutes without activity and One session at a time.
- Press Save changes.
Permissions you do not hold yourself are shown but cannot be ticked ("Your own role does not hold this").
Giving a role#
- Open the administrator under Customers › Users.
- With Level set to Administrator, choose the Role.
- Save.
Rules that stop privilege escalation:
- Only someone with the Staff permission (
staff.manage) whose own permissions cover a role can make, change, delete or give that role. Roles the editor may not give are disabled in the list. - The Administrator role is given, changed or taken away only by a full administrator, and a full administrator is managed only by another. A custom role with every permission ticked is still not the Administrator role: it does not receive permissions added later.
- Nobody changes their own role. The last administrator with the Administrator role keeps it, cannot be deleted and (if it is the last one not suspended) cannot be suspended.
- A role somebody holds cannot be deleted.
Where a role is enforced#
- Pages: the sidebar shows only the pages the role opens; any other page answers 403.
- Buttons and actions: a refused action shows "Your role (Support) does not allow this: …". Buttons are not all hidden; they refuse when pressed.
- API keys: a staff member's key is held to both its scopes and its owner's role (403
forbidden). The key form offers only scopes the role allows. See API keys. - Sign-in links made through a staff member's billing key stop working when the maker's role no longer allows them.
Refusals are written to the audit log as staff.refused (at most once a minute for the same thing). Role changes are staff_role.*, and a change of an account's role is in user.updated.
Session rules#
A role can set:
- Sign out after minutes without activity: the shorter of the role's and the panel's idle timeout applies. A role timeout also stops remember-me cookies from signing its holders in.
- One session at a time: signing in ends the holder's other sessions.
Panel-wide timeouts and One session at a time for every administrator or every account are under System › Settings › Sign-in; see Sign-in security. Every open session of the panel is listed under Customers › Sessions, where an administrator with the users.sessions permission can sign one out.
Not available#
Roles are managed in the panel only (there are no API endpoints for them). There is no role-level address allowlist: each staff member sets allowed addresses on their own account under Settings › Sign-ins.