X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=95406c9874282224acd33e3583501b69a1df71e7;hp=294de43c342ed8b3ab9e20dc53de12872d12644b;hb=115aef16f8bedba9ea2016815e427d442b5ccb55;hpb=c80b9ee6b4bfec0ecc7398a443c9c89f8783646b diff --git a/pveum.adoc b/pveum.adoc index 294de43..95406c9 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -1,7 +1,9 @@ +[[chapter_user_management]] ifdef::manvolnum[] -PVE({manvolnum}) -================ +pveum(1) +======== include::attributes.txt[] +:pve-toplevel: NAME ---- @@ -9,7 +11,7 @@ NAME pveum - Proxmox VE User Manager -SYNOPSYS +SYNOPSIS -------- include::pveum.1-synopsis.adoc[] @@ -18,11 +20,11 @@ include::pveum.1-synopsis.adoc[] DESCRIPTION ----------- endif::manvolnum[] - ifndef::manvolnum[] User Management =============== include::attributes.txt[] +:pve-toplevel: endif::manvolnum[] // Copied from pve wiki: Revision as of 16:10, 27 October 2015 @@ -35,12 +37,13 @@ By using the role based user- and permission management for all objects (VMs, storages, nodes, etc.) granular access can be defined. +[[pveum_users]] Users ----- {pve} stores user attributes in `/etc/pve/user.cfg`. Passwords are not stored here, users are instead associated with -<> described below. +<> described below. Therefore a user is internally often identified by its name and realm in the form `@`. @@ -65,6 +68,7 @@ still be changed and system mails will be sent to the email address assigned to this user. +[[pveum_groups]] Groups ~~~~~~ @@ -74,7 +78,7 @@ to groups instead of using individual users. That way you will get a much shorter access control list which is easier to handle. -[[authentication-realms]] +[[pveum_authentication_realms]] Authentication Realms --------------------- @@ -183,18 +187,52 @@ https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation host your own verification server]. -Terms and Definitions +[[pveum_permission_management]] +Permission Management --------------------- +In order for a user to perform an action (such as listing, modifying or +deleting a parts of a VM configuration), the user needs to have the +appropriate permissions. -Objects and Paths -~~~~~~~~~~~~~~~~~ +{pve} uses a role and path based permission management system. An entry in +the permissions table allows a user or group to take on a specific role +when accessing an 'object' or 'path'. This means an such an access rule can +be represented as a triple of '(path, user, role)' or '(path, group, +role)', with the role containing a set of allowed actions, and the path +representing the target of these actions. + + +[[pveum_roles]] +Roles +~~~~~ + +A role is simply a list of privileges. Proxmox VE comes with a number +of predefined roles which satisfies most needs. + +* `Administrator`: has all privileges +* `NoAccess`: has no privileges (used to forbid access) +* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). +* `PVEAuditor`: read only access +* `PVEDatastoreAdmin`: create and allocate backup space and templates +* `PVEDatastoreUser`: allocate backup space and view storage +* `PVEPoolAdmin`: allocate pools +* `PVESysAdmin`: User ACLs, audit, system console and system logs +* `PVETemplateUser`: view and clone templates +* `PVEUserAdmin`: user administration +* `PVEVMAdmin`: fully administer VMs +* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management -Access permissions are assigned to objects, such as a virtual machines -(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of -resources (`/pool/{poolname}`). We use file system like paths to -address those objects. Those paths form a natural tree, and -permissions can be inherited down that hierarchy. +You can see the whole set of predefined roles on the GUI. + +Adding new roles can currently only be done from the command line, like +this: + +[source,bash] +---- +pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" +pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" +---- Privileges @@ -202,7 +240,8 @@ Privileges A privilege is the right to perform a specific action. To simplify management, lists of privileges are grouped into roles, which can then -be uses to set permissions. +be used in the permission table. Note that privileges cannot directly be +assigned to users and paths without being part of a role. We currently use the following privileges: @@ -247,48 +286,33 @@ Storage related privileges:: * `Datastore.Audit`: view/browse a datastore -Roles -~~~~~ - -A role is simply a list of privileges. Proxmox VE comes with a number -of predefined roles which satisfies most needs. - -* `Administrator`: has all privileges -* `NoAccess`: has no privileges (used to forbid access) -* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). -* `PVEAuditor`: read only access -* `PVEDatastoreAdmin`: create and allocate backup space and templates -* `PVEDatastoreUser`: allocate backup space and view storage -* `PVEPoolAdmin`: allocate pools -* `PVESysAdmin`: User ACLs, audit, system console and system logs -* `PVETemplateUser`: view and clone templates -* `PVEUserAdmin`: user administration -* `PVEVMAdmin`: fully administer VMs -* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management - -You can see the whole set of predefined roles on the GUI. - -Adding new roles using the CLI: - -[source,bash] ----- -pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" -pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" ----- +Objects and Paths +~~~~~~~~~~~~~~~~~ +Access permissions are assigned to objects, such as a virtual machines, +storages or pools of resources. +We use file system like paths to address these objects. These paths form a +natural tree, and permissions of higher levels (shorter path) can +optionally be propagated down within this hierarchy. -Permissions -~~~~~~~~~~~ +[[templated-paths]] +Paths can be templated. When an API call requires permissions on a +templated path, the path may contain references to parameters of the API +call. These references are specified in curly braces. Some parameters are +implicitly taken from the API call's URI. For instance the permission path +`/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on +`/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` +refers to the method's `path` parameter. -Permissions are the way we control access to objects. In technical -terms they are simply a triple containing ``. This -concept is also known as access control lists. Each permission -specifies a subject (user or group) and a role (set of privileges) on -a specific path. +Some examples are: -When a subject requests an action on an object, the framework looks up -the roles assigned to that subject (using the object path). The set of -roles defines the granted privileges. +* `/nodes/{node}`: Access to {pve} server machines +* `/vms`: Covers all VMs +* `/vms/{vmid}`: Access to specific VMs +* `/storage/{storeid}`: Access to a storages +* `/pool/{poolname}`: Access to VMs part of a < +* `/access/groups`: Group administration +* `/access/realms/{realmid}`: Administrative access to realms Inheritance @@ -303,6 +327,7 @@ by default). We use the following inheritance rules: * Permissions replace the ones inherited from an upper level. +[[pveum_pools]] Pools ~~~~~