From e385014ba9ee1213ad404e1964b36f4529bdc988 Mon Sep 17 00:00:00 2001 From: catborise Date: Fri, 2 Oct 2026 20:36:24 +0300 Subject: [PATCH] docs(readme): document users, roles and permissions Describe the access model: superuser, the global permissions (view_instances as a read-only auditor role, clone_instances, snapshot_instances, passwordless_console, change_password) and per-VM ownership flags (is_change, is_delete, is_vnc), with a table of which VM actions each combination allows. The table describes the state after all Wave 0 branches are merged: disk/media views are superuser-only (fix/wave0-disk-tenant-isolation) and clone requires is_change except for templates (fix/wave0-clone-permission). --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 2239f0cc..cf8f67a4 100644 --- a/README.md +++ b/README.md @@ -439,6 +439,38 @@ python -m unittest discover -s vrtManager -p "test_*.py" > python manage.py test > ``` +## Users, Roles and Permissions + +WebVirtCloud combines three kinds of access rights: + +- **Superuser** (`is_superuser`): full administration — computes, storage pools, networks, interfaces, nwfilters, secrets, app settings, users, and every VM. +- **Global permissions** (Django permissions, set per user or group in the admin pages): + - `instances.view_instances` — **read-only auditor role**: sees every VM in lists and detail pages, but cannot change them and cannot open their consoles. + - `instances.clone_instances` — may clone VMs (see the table for which ones). + - `instances.snapshot_instances` — may create, revert and delete snapshots of VMs they may change. + - `instances.passwordless_console` — the console page fills in the VNC password automatically (granted to all users by default). + - `accounts.change_password` — may change their own password. +- **Per-VM ownership** (an owner entry for a user on a VM, managed by a superuser on the VM's page) with three flags: `is_change`, `is_delete`, `is_vnc`. An owner without flags may see, start and stop the VM and open its console. + +| Action on a VM | Superuser | Owner | Owner flag / permission needed | `view_instances` only | +|---|---|---|---|---| +| See the VM (list, detail) | ✅ | ✅ | — | ✅ | +| Start, shut down, power cycle, force off | ✅ | ✅ | — | ❌ | +| Open the console (noVNC, `.vv` file for virt-viewer, VDI URL) | ✅ | ✅ | — | ❌ | +| Resize CPU/memory/disk, set root password, add SSH key, change title/description | ✅ | ✅ | `is_change` | ❌ | +| Change console settings (type, VNC password, keymap) | ✅ | ✅ | `is_change` and `is_vnc` | ❌ | +| Snapshots | ✅ | ✅ | `is_change` and `instances.snapshot_instances` | ❌ | +| Clone | ✅ | ✅ | `is_change` and `instances.clone_instances` (templates: viewing the template is enough) | templates only, with `instances.clone_instances` | +| Delete the VM | ✅ | ✅ | `is_delete` | ❌ | +| Disks and media (add, attach, edit, detach, delete volumes; CD-ROM/ISO) | ✅ | ❌ | — | ❌ | +| Network interfaces, boot options, vCPU hotplug, autostart, guest agent, suspend/resume, migrate, raw XML, owners | ✅ | ❌ | — | ❌ | + +Notes: + +- Only superusers choose disk names and MAC addresses when cloning; for other users the server derives them. +- `is_staff` gives no access to VMs by itself. +- Users without ownership or `view_instances` get **404** for a VM (its existence is not revealed); users who can see a VM but lack the right for an action get **403**. + ## LDAP Configuration The config options below can be changed in `webvirtcloud/settings.py` file. Variants for Active Directory and OpenLDAP are shown. This is a minimal config to get LDAP running, for further info read the [django-auth-ldap documentation](https://django-auth-ldap.readthedocs.io).