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

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

Deactivate or reactivate an account:

1vh user update alice --disable2vh user update alice --enable

Delete:

1vh user delete alice                      # asks first; her vaults are destroyed2vh user delete alice --transfer-to bob    # asks first; her vaults go to bob3vh user delete alice --yes                # no question (scripts)

Deleting an account always asks: "Are you sure you wish to delete this user? The user's existing vaults will be destroyed unless ownership is transferred." The web console asks the same in its delete dialog, where you can pick who receives the vaults. Every vault is checked before anything changes, so a refused transfer or removal leaves the account and its vaults as they were.

Transferring vault ownership, here or with vh vault update <id> --owner <user> / the vault edit page, is limited to administrators: it needs an admin account, edit rights on the vault, and the right to create vaults for the new owner. The new owner can't already have a vault with the same name.

The built-in super admin user and role are protected from ordinary mutation paths. The super admin can't be renamed, because the daemon looks it up by name. Its web console password starts as a generated, per-install one; see Web Console. Change it with vh setup set-super-admin-password, run as the Linux user bound as the super admin.

Rules that apply on the CLI and in the web console alike:

• An account whose admin role grants anything beyond managing its owner's own vaults and keys is an admin account. Creating, editing, deleting or resetting the password of an admin account needs the admin.identities.admins.* permissions; plain accounts use admin.identities.users.*.
• Nobody can assign a role that grants admin permissions they don't hold. Nobody can edit, delete, deactivate or reset the password of an account whose role exceeds their own.
• Nobody can change their own role, Linux UID binding or active state, or delete their own account. Ask another administrator.
• An account's global vault policy (what it may do in vaults through no specific vault role) is seeded from its role when the role is assigned (the built-in role's preset), then belongs to the account. unprivileged grants none, and custom roles seed unprivileged: such accounts reach a vault, their own default vault included, through a vault role assignment.
• Deleting, deactivating, re-roling or resetting the password of an account ends all of its sessions immediately. A deactivated account can't log in.
• vh user create creates the account's default vault, as the web console does, and prints a generated password once.

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.
• Health and system stats (admin.stats.view, flag --allow-stats-view): the console's Health area and the server, daemon and system stats behind it. Built-in admin, auditor, platform_operator and super_admin have it. A vault's own stats don't need it; they follow the vault (its owner, or admin.vaults.*.view_stats).
• Admin management.

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

To start from an existing role, pass --from and then the flags that differ:

1vh role admin create support-lead --from support --allow-<permission> ...

--from copies that role's permissions into the new one as a starting point. Without it, a role starts from unprivileged. Once created, the role owns its own permissions: later changes to the role it came from don't reach it. The web console's role form does the same with its Start from list.

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 groups these under Access: Users, Groups, and Roles (admin and vault roles in one list, with a grouped permission editor). 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.