From 3c8533f240aa67db53ed1daa3a6c50270f9f2df1 Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Tue, 5 Jan 2016 10:16:10 +0100 Subject: [PATCH] import pveum docs --- pveum.adoc | 371 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 371 insertions(+) create mode 100644 pveum.adoc diff --git a/pveum.adoc b/pveum.adoc new file mode 100644 index 0000000..a3b1cff --- /dev/null +++ b/pveum.adoc @@ -0,0 +1,371 @@ +include::attributes.txt[] +ifdef::manvolnum[] +PVE({manvolnum}) +================ + +NAME +---- + +pveum - Proxmox VE User Manager + + +SYNOPSYS +-------- + +include::pveum.1-synopsis.adoc[] + + +DESCRIPTION +----------- +endif::manvolnum[] + +ifndef::manvolnum[] +User Management +=============== +endif::manvolnum[] + +// Copied from pve wiki: Revision as of 16:10, 27 October 2015 + +Proxmox VE supports multiple authentication sources, e.g. Microsoft +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. + +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:: + +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! + +[source,bash] +---- +useradd heinz +passwd heinz +groupadd watchman +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. Users are allowed to change passwords. + +Terms and Definitions +--------------------- + +Users +~~~~~ + +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'): + +* first name +* last name +* email address +* expiration date +* flag to enable/disable account +* comment + +Superuser +^^^^^^^^^ + +The traditional unix superuser account is called 'root@pam'. All +system mails are forwarded to the email assigned to that account. + +Groups +~~~~~~ + +Each user can be member of several groups. Groups are the preferred +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 +address those objects. Those paths form a natural tree, and +permissions can be inherited down that hierarchy. + +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. + +We currently use the following privileges: + +Node / System related privileges:: + +* `Permissions.Modify`: modify access permissions +* `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...) +* `Sys.Console`: console access to Node +* `Sys.Syslog`: view Syslog +* `Sys.Audit`: view node status/config +* `Sys.Modify`: create/remove/modify node network parameters +* `Group.Allocate`: create/remove/modify groups +* `Pool.Allocate`: create/remove/modify a pool +* `Realm.Allocate`: create/remove/modify authentication realms +* `Realm.AllocateUser`: assign user to a realm +* `User.Modify`: create/remove/modify user access and details. + +Virtual machine related privileges:: + +* `VM.Allocate`: create/remove new VM to server inventory +* `VM.Migrate`: migrate VM to alternate server on cluster +* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) +* `VM.Console`: console access to VM +* `VM.Monitor`: access to VM monitor (kvm) +* `VM.Backup`: backup/restore VMs +* `VM.Audit`: view VM config +* `VM.Clone`: clone/copy a VM +* `VM.Config.Disk`: add/modify/delete Disks +* `VM.Config.CDROM`: eject/change CDROM +* `VM.Config.CPU`: modify CPU settings +* `VM.Config.Memory`: modify Memory settings +* `VM.Config.Network`: add/modify/delete Network devices +* `VM.Config.HWType`: modify emulated HW type +* `VM.Config.Options`: modify any other VM configuration +* `VM.Snapshot`: create/remove VM snapshots + +Storage related privileges:: + +* `Datastore.Allocate`: create/remove/modify a data store, delete volumes +* `Datastore.AllocateSpace`: allocate space on a datastore +* `Datastore.AllocateTemplate`: allocate/upload templates and iso images +* `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" +---- + + +Permissions +~~~~~~~~~~~ + +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. + +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 +permissions can be inherited down that tree (the propagate flag is set +by default). We use the following inheritance rules: + +* permission for individual users always overwrite group permission. +* 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/ + +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}'), +which are inherited to all pool members. This is a great way simplify +access control. + +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. + +Here are some simple usage examples. To show help type: + +[source,bash] + pveum + +or (to show detailed help about a specific command) + +[source,bash] + pveum help useradd + +Create a new user: + +[source,bash] + pveum useradd testuser@pve -comment "Just a test" + +Set or Change the password (not all realms support that): + +[source,bash] + pveum passwd testuser@pve + +Disable a user: + +[source,bash] + pveum usermod testuser@pve -enable 0 + +Create a new group: + +[source,bash] + pveum groupadd testgroup + +Create a new role: + +[source,bash] + pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" + + +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). + +Define the group: + +[source,bash] + pveum groupadd admin -comment "System Administrators" + +Then add the permission: + +[source,bash] + pveum aclmod / -group admin -role Administrator + +You can finally add users to the new 'admin' group: + +[source,bash] + pveum usermod testuser@pve -group admin + + +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 + +[source,bash] + pveum aclmod / -user joe@pve -role PVEAuditor + +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 +that with: + +[source,bash] + pveum aclmod /access -user joe@pve -role PVEUserAdmin + +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': + +[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'. + +Pools +~~~~~ + +An enterprise is usually structured into several smaller departments, +and it is common that you want to assign resources to them and +delegate management tasks. A pool is simply a set of virtual machines +and data stores. You can create pools on the GUI. After that you can +add resources to the pool (VMs, Storage). + +You can also assign permissions to the pool. Those permissions are +inherited to all pool members. + +Lets assume you have a software development department, so we first +create a group + +[source,bash] + pveum groupadd developers -comment "Our software developers" + +Now we create a new user which is a member of that group + +[source,bash] + pveum useradd developer1@pve -group developers -password + +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: + +[source,bash] + pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin + +Our software developers can now administrate the resources assigned to +that pool. + + +ifdef::manvolnum[] +include::pve-copyright.adoc[] +endif::manvolnum[] + -- 2.39.2