Vaulthalla Logo

Users, Groups, And Roles

Manage Vaulthalla users, Linux UID mappings, groups, admin roles, vault roles, and vault assignments.

Users, Groups, And Roles

Vaulthalla uses application users, groups, admin roles, vault roles, and optional Linux UID/GID mappings. The CLI also depends on local Linux identity for trusted operator access.

Identity Model

ItemPurpose
Linux userControls local host login and access to the CLI socket.
Application userVaulthalla identity used for permissions and audit records.
linux_uidOptional mapping from Linux UID to an application user.
GroupTeam-level permission subject.
Admin roleInstance-level administration permissions.
Vault roleVault-level data and management permissions.

The first CLI admin should be bound intentionally with First Run.

Users

Create a user:

1vh user create alice --role admin --email [email protected] --linux-uid 1001

Inspect and update:

1vh user info alice2vh user update alice --email [email protected]3vh user update alice --linux-uid 1001

Delete:

1vh user delete alice

The built-in super admin user and role are protected from ordinary mutation paths.

Groups

Create a group:

1vh group create operators --desc "Operations team" --linux-gid 2001

Manage membership:

1vh group user add operators alice2vh group user remove operators alice3vh group users operators

Use groups for vault access whenever more than one person should receive the same vault permissions.

Admin Roles

List supported admin permissions:

1vh permissions --type user

Create an admin role:

1vh role admin create operations-admin \2  --manage-users \3  --manage-groups \4  --manage-vaults \5  --manage-api-keys \6  --audit-log-access

Useful admin permission areas include:

  • User management.
  • Group management.
  • Vault management.
  • Role management.
  • API key management.
  • Encryption key export.
  • Audit log access.
  • Admin management.

Grant only the permissions needed for the operator's job.

Vault Roles

List supported vault permissions:

1vh permissions --type vault

Create a vault role:

1vh role vault create read-share \2  --list \3  --download \4  --share

Vault permission areas include:

  • List and browse.
  • Create, download, delete, rename, and move.
  • Share.
  • Sync.
  • Tags, metadata, versions, and file locks.
  • Vault access and vault management.

Assign Vault Roles

Assign to a user:

1vh vault role assign archive <role-id> --user alice

Assign to a group:

1vh vault role assign archive <role-id> --group operators

List assignments:

1vh vault role list archive

Remove an assignment:

1vh vault role unassign archive <role-id> --user alice

Path Overrides

Use overrides when a subject needs a different permission result for a path pattern:

1vh vault role override add archive \2  --user alice \3  --pattern "/finance/*" \4  --download \5  --disable

List and remove:

1vh vault role override list archive2vh vault role override remove archive <override-id>

Keep overrides rare. They are powerful but harder to audit than simple role assignments.

Web Console

The web console includes Users, Groups, Admin Roles, and Vault Roles pages. Use them for interactive administration and use vh for scriptable or recovery-oriented operations.

Troubleshooting Access

If a user cannot use the CLI:

1id2getent group vaulthalla3ls -l /run/vaulthalla/cli.sock4vh user info <username>

If a user can log in but cannot see vault content:

1vh vault role list <vault>2vh permissions --type vault

Check group assignments and path overrides before changing broad admin roles.