X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=8a8a6ae8c2852b72afcd0cc37db24124e79808cc;hp=00f260ad6e6ad2e7057dca2f104720161951434e;hb=d66142027ae5b57219bc0295d68667afe5416b2d;hpb=3b26ef9ed44063a6e65172a28b3e1f791af9713f diff --git a/pveum.adoc b/pveum.adoc index 00f260a..8a8a6ae 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -32,26 +32,22 @@ Active Directory, LDAP, Linux PAM or the integrated Proxmox VE authentication server. By using the role based user- and permission management for all -objects (VM´s, storages, nodes, etc.) granular access can be defined. +objects (VMs, storages, nodes, etc.) granular access can be defined. + +[[authentication-realms]] Authentication Realms --------------------- -Proxmox VE stores all user attributes in '/etc/pve/user.cfg'. So there -must be an entry for each user in that file. The password is not -stored, instead you can use configure several realms to verify -passwords. - -Microsoft Active Directory:: - -LDAP:: +As {pve} users are just counterparts for users existing on some external +realm, the realms have to be configured in `/etc/pve/domains.cfg`. +The following realms (authentication methods) are available: Linux PAM standard authentication:: - -You need to create the system users first with 'adduser' -(e.g. adduser heinz) and possibly the group as well. After that you -can create the user on the GUI! - +In this case a system user has to exist (eg. created via the `adduser` +command) on all nodes the user is allowed to login, and the user +authenticates with their usual system password. ++ [source,bash] ---- useradd heinz @@ -61,14 +57,59 @@ usermod -a -G watchman heinz ---- Proxmox VE authentication server:: +This is a unix like password store (`/etc/pve/priv/shadow.cfg`). +Password are encrypted using the SHA-256 hash method. +This is the most convenient method for for small (or even medium) +installations where users do not need access to anything outside of +{pve}. In this case users are fully managed by {pve} and are able to +change their own passwords via the GUI. + +LDAP:: +It is possible to authenticate users via an LDAP server (eq. +openldap). The server and an optional fallback server can be +configured and the connection can be encrypted via SSL. ++ +Users are searched under a 'Base Domain Name' (`base_dn`), with the +user name found in the attribute specified in the 'User Attribute Name' +(`user_attr`) field. ++ +For instance, if a user is represented via the +following ldif dataset: ++ +---- +# user1 of People at ldap-test.com +dn: uid=user1,ou=People,dc=ldap-test,dc=com +objectClass: top +objectClass: person +objectClass: organizationalPerson +objectClass: inetOrgPerson +uid: user1 +cn: Test User 1 +sn: Testers +description: This is the first test user. +---- ++ +The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user +attribute would be `uid`. ++ +If {pve} needs to authenticate (bind) to the ldap server before being +able to query and authenticate users, a bind domain name can be +configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its +password then has to be stored in `/etc/pve/priv/ldap/.pw` +(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a +single line containing the raw password. + +Microsoft Active Directory:: + +A server and authentication domain need to be specified. Like with +ldap an optional fallback server, optional port, and SSL +encryption can be configured. -This is a unix like password store -('/etc/pve/priv/shadow.cfg'). Password are encrypted using the SHA-256 -hash method. Users are allowed to change passwords. Terms and Definitions --------------------- + Users ~~~~~ @@ -76,7 +117,7 @@ A Proxmox VE user name consists of two parts: `@`. The login screen on the GUI shows them a separate items, but it is internally used as single string. -We store the following attribute for users ('/etc/pve/user.cfg'): +We store the following attribute for users (`/etc/pve/user.cfg`): * first name * last name @@ -85,12 +126,14 @@ We store the following attribute for users ('/etc/pve/user.cfg'): * flag to enable/disable account * comment + Superuser ^^^^^^^^^ -The traditional unix superuser account is called 'root@pam'. All +The traditional unix superuser account is called `root@pam`. All system mails are forwarded to the email assigned to that account. + Groups ~~~~~~ @@ -99,15 +142,17 @@ way to organize access permissions. You should always grant permission to groups instead of using individual users. That way you will get a much shorter access control list which is easier to handle. + Objects and Paths ~~~~~~~~~~~~~~~~~ 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 filesystem like paths to +(`/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. + Privileges ~~~~~~~~~~ @@ -157,6 +202,7 @@ Storage related privileges:: * `Datastore.AllocateTemplate`: allocate/upload templates and iso images * `Datastore.Audit`: view/browse a datastore + Roles ~~~~~ @@ -200,10 +246,11 @@ 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. + Inheritance ^^^^^^^^^^^ -As mentioned earlier, object paths forms a filesystem like tree, and +As mentioned earlier, object paths form a file system like tree, and permissions can be inherited down that tree (the propagate flag is set by default). We use the following inheritance rules: @@ -211,15 +258,19 @@ by default). We use the following inheritance rules: * permission for groups apply when the user is member of that group. * permission set at higher level always overwrites inherited permissions. + What permission do I need? ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The required API permissions are documented for each individual method, and can be found at http://pve.proxmox.com/pve2-api-doc/ + +The required API permissions are documented for each individual +method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ + Pools ~~~~~ Pools can be used to group a set of virtual machines and data -stores. You can then simply set permissions on pools ('/pool/\{poolid\}'), +stores. You can then simply set permissions on pools (`/pool/{poolid}`), which are inherited to all pool members. This is a great way simplify access control. @@ -227,11 +278,10 @@ Command Line Tool ----------------- Most users will simply use the GUI to manage users. But there is also -a full featured command line tool called 'pveum' (short for 'Proxmox -VE User Manager'). I will use that tool in the following -examples. Please note that all Proxmox VE command line tools are -wrappers around the API, so you can also access those function through -the REST API. +a full featured command line tool called `pveum` (short for ``**P**roxmox +**VE** **U**ser **M**anager''). Please note that all Proxmox VE command +line tools are wrappers around the API, so you can also access those +function through the REST API. Here are some simple usage examples. To show help type: @@ -272,11 +322,12 @@ Create a new role: Real World Examples ------------------- + Administrator Group ~~~~~~~~~~~~~~~~~~~ One of the most wanted features was the ability to define a group of -users with full administartor rights (without using the root account). +users with full administrator rights (without using the root account). Define the group: @@ -300,37 +351,39 @@ Auditors You can give read only access to users by assigning the `PVEAuditor` role to users or groups. -Example1: Allow user 'joe@pve' to see everything +Example1: Allow user `joe@pve` to see everything [source,bash] pveum aclmod / -user joe@pve -role PVEAuditor -Example1: Allow user 'joe@pve' to see all virtual machines +Example1: Allow user `joe@pve` to see all virtual machines [source,bash] pveum aclmod /vms -user joe@pve -role PVEAuditor + Delegate User Management ~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to delegate user managenent to user 'joe@pve' you can do +If you want to delegate user managenent to user `joe@pve` you can do that with: [source,bash] pveum aclmod /access -user joe@pve -role PVEUserAdmin -User 'joe@pve' can now add and remove users, change passwords and +User `joe@pve` can now add and remove users, change passwords and other user attributes. This is a very powerful role, and you most likely want to limit that to selected realms and groups. The following -example allows 'joe@pve' to modify users within realm 'pve' if they -are members of group 'customers': +example allows `joe@pve` to modify users within realm `pve` if they +are members of group `customers`: [source,bash] pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin NOTE: The user is able to add other users, but only if they are -members of group 'customers' and within realm 'pve'. +members of group `customers` and within realm `pve`. + Pools ~~~~~ @@ -357,7 +410,7 @@ Now we create a new user which is a member of that group NOTE: The -password parameter will prompt you for a password -I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool: +I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: [source,bash] pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin