Skip to content
Esc

Permissions

How access works in Dockmesh - roles as a level per area plus extras, assignments of a role on a scope, the built-in roles, API tokens and identity provider groups.

Access in Dockmesh comes from assignments. An assignment gives a user a role on a scope: everything, one host, all hosts with a host tag, or one stack. A user can have several assignments; they add up, and none of them can take away what another gives. Roles, custom roles and assignments are part of the open-source build.

Manage them under Users & roles. The page has the tabs Users, Roles and Invites. Each user has a detail page whose Access tab lists the assignments, shows what the user can do where, and has an Access check that answers “Can this user do X on Y?” with the assignment that allows it.

A role picks one level per area. Levels are cumulative: Deploy includes Operate and View.

AreaLevelsWhat each level adds
StacksNone, View, Operate, Deploy, ManageView: stacks, services and compose, logs, templates. Operate: stop stacks, start, stop and restart their containers. Deploy: deploy and redeploy, edit compose and .env, roll back to an earlier deploy, deploy from a template. Manage: create and delete stacks, migrate to another host, adopt existing containers, connect git repositories, create, edit and delete templates
ContainersNone, View, Operate, ManageView: containers and their metrics, logs. Operate: start, stop, restart, pause. Manage: remove containers, update and roll back images
Images, volumes, networks & registriesNone, View, ManageView: images, volumes, networks, the registry list. Manage: pull, remove and prune, create volumes and networks, vulnerability scans, add, edit and remove registries
HostsNone, View, ManageView: hosts and host metrics. Manage: add and revoke hosts, edit host tags, drain hosts and upgrade agents
ProxyNone, View, ManageView: routes and certificates. Manage: add, edit and delete routes, start and stop the proxy
BackupsNone, View, Operate, ManageView: jobs, runs and targets. Operate: run jobs now, restore a run. Manage: create and edit jobs and targets
AlertsNone, View, ManageView: rules and alert history. Manage: rules and notification channels
Users & rolesNone, View, ManageView: users, roles and assignments. Manage: invite, edit and remove users, edit roles and assignments, revoke other users’ API tokens
Settings & auditNone, Metrics, View, ManageMetrics: the Prometheus /metrics scrape. View: also the audit log. Manage: instance settings, sign-in and identity providers, audit retention, export and webhook, update checks, rotating the encryption key, restoring a system backup

On top of the levels, a role can hold extras. No level includes them:

ExtraWhat it allows
Open a terminal in containersA shell in containers. Together with the files extra: upload, edit and delete container files
Browse and read files in containers and volumesThe container Files tab and the volume browser, read-only
See environment values (inspect, .env)Environment values in container inspect and a stack’s .env. Stacks: Deploy shows a stack’s .env too
Download backup archivesDownload decrypted backup archives
Export the backup encryption keyExport the key that decrypts every backup. Only on an assignment on everything
RoleLevelsExtras
Adminevery area at its top levelall five
Host AdminStacks, Containers, Images/volumes/networks & registries, Hosts, Proxy, Backups, Alerts: Manage; Settings & audit: Viewterminal, files, environment values, download backups
DeployerStacks: Deploy; Containers: Operate; Images/volumes/networks & registries, Hosts, Proxy, Backups, Alerts: Viewnone
OperatorStacks, Containers: Operate; Images/volumes/networks & registries, Hosts, Backups, Alerts: Viewterminal
Viewerevery area except Users & roles: Viewnone

Built-in roles can’t be changed. Duplicate one, or click New role, to make a custom role.

Other pages, API error messages and dmctl whoami -o json name single permissions by key. Each key belongs to the lowest level or extra that grants it:

KeyGranted by
stacks.view, templates.viewStacks: View
containers.logsStacks: View or Containers: View
stacks.operateStacks: Operate
containers.updateStacks: Operate or Containers: Operate
stacks.deploy, stacks.updateStacks: Deploy
stacks.create, stacks.delete, stacks.migrate, stacks.adopt, stacks.git, templates.create, templates.update, templates.deleteStacks: Manage
containers.viewContainers: View
containers.delete, containers.upgradeContainers: Manage
images.view, volumes.view, networks.view, registries.viewImages, volumes, networks & registries: View
images.create, images.delete, images.scan, volumes.create, volumes.delete, networks.create, networks.delete, registries.create, registries.update, registries.deleteImages, volumes, networks & registries: Manage
hosts.viewHosts: View
hosts.create, hosts.update, hosts.delete, hosts.tagHosts: Manage
proxy.viewProxy: View
proxy.create, proxy.update, proxy.deleteProxy: Manage
backups.viewBackups: View
backups.run, backups.restoreBackups: Operate
backups.create, backups.update, backups.deleteBackups: Manage
alerts.view, alerts.historyAlerts: View
alerts.create, alerts.update, alerts.deleteAlerts: Manage
users.view, roles.viewUsers & roles: View
users.create, users.update, users.delete, roles.create, roles.update, roles.delete, tokens.manage_othersUsers & roles: Manage
metrics.viewSettings & audit: Metrics
audit.viewSettings & audit: View
audit.export, audit.write, system.update, system.upgradeSettings & audit: Manage
containers.execextra Open a terminal in containers
containers.files, volumes.browseextra Browse and read files in containers and volumes
containers.envextra See environment values (inspect, .env)
backups.downloadextra Download backup archives
backups.key_exportextra Export the backup encryption key
tokens.view, tokens.create, tokens.delete, system.viewevery signed-in user (own tokens, server status)
ScopeCovers
Everythingevery host and stack, and the instance-wide areas
Hostone host, its containers, images, volumes, networks and stacks
Host tagevery host carrying the tag, now and later
Stackone stack. Stack names are unique; a stack scope with a host covers the stack while it runs there, one without a host covers it anywhere, also before it is deployed

Proxy, alert rules and notification channels, users and roles, settings, the audit log and the /metrics scrape are instance-wide. Only an assignment on everything grants them; a narrower assignment of the same role does not. Editing host tags, adding new hosts, adding, editing and removing registries, creating, editing and deleting templates, other users’ API tokens and the backup key are instance-wide for the same reason. Alert history, the registry list and hosts follow the scope.

Changing the Base URL in Settings needs Users & roles: Manage on everything in addition to Settings & audit: Manage, because invite links and SSO callback URLs are built from it. Every change is written to the audit log with the old and the new address.

A stack that exists only as files and was never deployed has no host yet. Only assignments on everything or on that stack without a host see it, change it or deploy it.

Every signed-in user can always see their own profile, sessions, 2FA and API tokens, server health and version, and receive live updates. With Users & roles: Manage you can also see and end another user’s sessions on their Sessions & 2FA tab, as long as you could grant each of their assignments yourself. A page none of your roles allows shows a no-access message.

To add or remove an assignment you need Users & roles: Manage on everything, and you must hold every permission of the role everywhere the scope reaches. Instance-wide permissions don’t count for a narrower scope, because the assignment can’t grant them there. Roles follow the same rule on everything: you can only create, change or delete a role whose levels and extras you hold yourself on everything. Managing a user (editing, unlocking, sessions, turning off 2FA) needs that you could grant each of the user’s current assignments.

The last assignment of an admin role on everything can’t be removed, and such a role can’t be narrowed while it is the last one. An admin role is one that can change instance settings and view, invite, edit and remove users.

A token acts with its owner’s current access. When you create it you can restrict it further to a role on a scope; it never gets more than the owner has. See API tokens.

Group mappings on an OIDC, SAML, LDAP or OAuth2 provider map a group to a role on a scope. At every sign-in Dockmesh replaces the user’s identity provider assignments with one per matching group; with no match, the provider’s Default role applies on everything. Assignments you add by hand stay. Saving a provider needs that you could grant its default role and every mapping yourself.

On the user’s Overview tab, Stop updating from groups keeps sign-ins from changing the account’s access; Update from groups at sign-in turns it back on.

If a sign-in would remove the last admin assignment on everything, Dockmesh keeps it and tells admins in a notice.

Adding or removing an assignment, creating, changing or deleting a role, and creating an API token are recorded in the audit log under the Access category. See Audit log.

The upgrade moves every user’s role, the role’s scopes and the user’s host tags onto assignments that give the same access. Where that isn’t possible, for example a scoped role combined with user host tags, the access is narrowed: such users get one assignment per host that matched at upgrade time. Custom roles get, per area, the highest level their old permissions fully covered. API tokens whose role was limited to more than one scope are revoked, because a token restriction holds one scope. Nothing gains access, except that the built-in roles follow the new definitions above. An admin notice lists every account, role and token that changed, with before and after.