Users, roles and permissions

Everyone who administers a VM2Cloud VE node should have their own account. Sharing the root sign-in means no audit trail, no way to remove one person’s access, and no way to limit what someone can reach.

This guide adds a user, grants them scoped access, and turns on two-factor authentication.

How access is decided

Three things combine to grant access:

Concept	What it is
User	Who is signing in, written as name@realm — for example jsmith@pve.
Role	A named bundle of privileges, such as VM2CloudVMAdmin.
Permission	A role granted to a user or group, at a path — for example /vms/101.

The path is what makes access specific. Granting a role at / covers everything; granting the same role at /vms/101 covers only that one machine. Always grant at the narrowest path that still lets the person do their job.

Realms

• Linux PAM standard authentication (pam) — accounts that also exist on the node’s operating system. root@pam is the account created during installation.
• VM2Cloud Virtual Environment authentication server (pve) — accounts that exist only inside VM2Cloud VE. Use this for everyday administrators: no operating-system account is created, so the account cannot be used to log into the server itself.

Additional realms for a central directory can be added under Datacenter → Permissions → Realms.

1. Create a group

Grant permissions to groups rather than to individuals — then adding or removing a person is one change in one place.

1. Open Datacenter → Permissions → Groups.
2. Click Create.
3. Enter a Name, for example vm-operators, and an optional comment.
4. Click Create.

2. Create a user

1. Open Datacenter → Permissions → Users.
2. Click Add.
3. Enter a User name.
4. Set Realm to VM2Cloud Virtual Environment authentication server. Do this before the next step — the password fields only appear once this realm is selected, because pam accounts use the operating system’s own password.
5. Set a Password, and fill in the name and e-mail fields if you want them recorded.
6. Set Group to the group you just created.
7. Leave Enabled ticked, and set an Expire date if the access should lapse.
8. Click Add.

The user exists but can see nothing yet — a new account carries no permissions at all.

3. Grant permissions

1. Open Datacenter → Permissions.
2. Click Add, then Group Permission.
3. Set Path to the scope being granted:
   • / — the whole system
   • /vms — all virtual machines
   • /vms/101 — one specific machine
   • /storage/local — one storage
   • /nodes/vm2cloud-node01 — one node
4. Set Group to your group.
5. Set Role — see the table below.
6. Tick Propagate so the permission applies to everything beneath the path.
7. Click Add.

Commonly used roles

Role	What it allows
VM2CloudAuditor	Read-only. Can view configuration and status, change nothing.
VM2CloudVMUser	Day-to-day use of a machine: start, stop, open the console, and back up or restore it. Also allows changing the CD/DVD media, editing cloud-init — which sets the guest’s user, password, SSH keys and IP addressing — and, where the guest agent is installed, reading and writing files inside the guest. It cannot change CPU, memory, disks or network adapters.
VM2CloudVMAdmin	Full control of a machine, including its hardware and disks.
VM2CloudTemplateUser	Clone from a template, and view it. Nothing else.
VM2CloudDatastoreUser	Allocate space on a storage — enough to create virtual machine disks. Uploading ISO images needs VM2CloudDatastoreAdmin.
VM2CloudAdmin	Broad administration of guests, storage, pools, SDN, users and groups. Cannot grant permissions, add authentication realms, edit device mappings, change a node’s system or network settings, power-manage a node, or use Download from URL.
Administrator	Everything, including changing other people’s access.

There are matching VM2Cloud…Admin roles for the other areas — Sys, Datastore, SDN, User, Pool and Mapping — for delegating one part of the platform without granting the rest.

What VM2CloudAdmin deliberately leaves out

VM2CloudAdmin covers the platform’s contents, not the server underneath it. Node network and system settings, node reboot and shutdown, adding a realm under Datacenter → Permissions → Realms, and Download from URL on a storage all need Administrator; editing device mappings needs Administrator or VM2CloudMappingAdmin. Guest power management is included, so holders can still start, stop and reboot virtual machines.

VM2CloudSysAdmin is not a substitute here — it grants viewing, the node shell and the system log, but not the ability to change node settings or power a node off. Changing the server itself is reserved for Administrator.

VM2CloudVMUser is not a look-but-don’t-touch role

It can edit cloud-init and use the guest agent, so it can set a login password, add an SSH key, and read or write files inside the guest. Treat it as access to the operating system running on that machine, not just to its power buttons. Where someone genuinely needs only power and console, build a custom role under Datacenter → Permissions → Roles with just VM.Audit, VM.Console and VM.PowerMgmt.

Grant Administrator at / sparingly

That combination is equivalent to root. Someone who needs to manage machines but not the platform is better served by VM2CloudVMAdmin on /vms.

Older role names still work

The VM2Cloud… roles are the ones the interface lists. A matching set of older names is still accepted for compatibility, so configurations written against them keep working — but they are not shown, so use the VM2Cloud… names for anything new.

To see exactly what a role covers, or to build one with a narrower set of privileges, open Datacenter → Permissions → Roles. Each role lists the individual privileges it grants.

4. Check the result

The honest test is to sign in as the user.

1. Open a private browser window.
2. Go to the node and sign in as the new user, choosing the VM2Cloud Virtual Environment authentication server realm.
3. Confirm they can see what they should — and cannot see anything else.

A user who signs in successfully but sees an empty Server View has no permissions granted yet; re-check the path in step 3.

5. Turn on two-factor authentication

Strongly recommended for every account that can change anything.

1. Open Datacenter → Permissions → Two Factor.
2. Click Add, then choose the method:
   • TOTP — a code from an authenticator app.
   • WebAuthn — a hardware security key or platform authenticator.
   • Recovery Keys — a set of one-time codes to store somewhere safe.
   • Yubico OTP — a YubiKey validated against a Yubico validation server.
3. Follow the prompts to enrol, and confirm with a code from the device.

Configure WebAuthn before enrolling keys

Set Datacenter → Options → WebAuthn Settings first. Enrolments are tied to those settings, so changing them later can invalidate keys that were already registered.

Generate recovery keys and store them offline

If the enrolled device is lost and no recovery key exists, that account cannot sign in. Generate recovery keys at the same time as enrolling, and keep them somewhere separate from the device.

API tokens — for scripts and automation

A token authenticates a program without embedding someone’s password.

1. Open Datacenter → Permissions → API Tokens.
2. Click Add.
3. Select the User the token belongs to and give it a Token ID naming its purpose.
4. Leave Privilege Separation ticked, so the token gets only the permissions you give it.
5. Click Add, and copy the secret that is shown.
6. Give the token its own permissions: open Datacenter → Permissions, click Add and choose API Token Permission. Set the Path, select the token under API Token, choose a Role and click Add.

The secret is shown once

Copy it immediately and store it in a secrets manager. It cannot be retrieved afterwards. If it is lost, select the token and click Regenerate Secret: a new secret is issued, the old one stops working, and the token keeps its permissions.

Revoke a token by deleting it. Nothing else about the user’s access changes.

Good practice

• Give each person their own account; keep root for recovery only.
• Grant to groups, at the narrowest path that works.
• Turn on two-factor authentication for anyone who can change things.
• Use a separate token per integration, so one can be revoked without affecting the rest.
• Review Datacenter → Permissions when someone changes role or leaves.

If something goes wrong

What you see	What to do
The user signs in but the Server View is empty	No permissions are granted. Add one at the right path, with Propagate ticked.
“Permission denied” on a specific action	The role does not include that privilege. Check it under Datacenter → Permissions → Roles.
The user cannot open a console	Console access needs at least VM2CloudVMUser on that machine.
A locked-out account after losing a 2FA device	Sign in as another administrator and remove that account’s second factor under Two Factor.
A script stops working after a token change	Tokens with privilege separation need their own permissions — granting the user access is not enough.

Still stuck? Contact VM2Cloud support.