X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=pveum.adoc;h=7120db7e7268d949d77dca8ccfc947d3f9ac6916;hb=a55d30db1d805960001a2fd3b43d7fb63d9aa8c5;hp=3f7e789d51b3cb3283ea07920d39f5f72968b2e1;hpb=38fd0958719a329859b3d0d719c37d5df15a2d8d;p=pve-docs.git diff --git a/pveum.adoc b/pveum.adoc index 3f7e789..7120db7 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -1,7 +1,8 @@ +[[chapter_user_management]] ifdef::manvolnum[] -PVE({manvolnum}) -================ -include::attributes.txt[] +pveum(1) +======== +:pve-toplevel: NAME ---- @@ -9,7 +10,7 @@ NAME pveum - Proxmox VE User Manager -SYNOPSYS +SYNOPSIS -------- include::pveum.1-synopsis.adoc[] @@ -18,40 +19,114 @@ 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 -Proxmox VE supports multiple authentication sources, e.g. Microsoft -Active Directory, LDAP, Linux PAM or the integrated Proxmox VE -authentication server. +Proxmox VE supports multiple authentication sources, e.g. Linux PAM, +an integrated Proxmox VE authentication server, LDAP, Microsoft Active +Directory. 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 ---------------------- -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. +[[pveum_users]] +Users +----- + +{pve} stores user attributes in `/etc/pve/user.cfg`. +Passwords are not stored here, users are instead associated with +<> described below. +Therefore a user is internally often identified by its name and +realm in the form `@`. -Microsoft Active Directory:: +Each user entry in this file contains the following information: -LDAP:: +* First name +* Last name +* E-mail address +* Group memberships +* An optional Expiration date +* A comment or note about this user +* Whether this user is enabled or disabled +* Optional two-factor authentication keys -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! +System administrator +~~~~~~~~~~~~~~~~~~~~ + +The system's root user can always log in via the Linux PAM realm and is an +unconfined administrator. This user cannot be deleted, but attributes can +still be changed and system mails will be sent to the email address +assigned to this user. + + +[[pveum_groups]] +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. + +[[pveum_tokens]] +API Tokens +---------- + +API tokens allow stateless access to most parts of the REST API by another +system, software or API client. Tokens can be generated for individual users +and can be given separate permissions and expiration dates to limit the scope +and duration of the access. Should the API token get compromised it can be +revoked without disabling the user itself. + +API tokens come in two basic types: + +* separated privileges: the token needs to be given explicit access with ACLs, + its effective permissions are calculated by intersecting user and token + permissions. +* full privileges: the token permissions are identical to that of the + associated user. + +CAUTION: The token value is only displayed/returned once when the token is +generated. It cannot be retrieved again over the API at a later time! + +To use an API token, set the HTTP header 'Authorization' to the displayed value +of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or +refer to your API client documentation. + +[[pveum_resource_pools]] +Resource Pools +-------------- +[thumbnail="screenshot/gui-datacenter-pool-window.png"] + +A resource pool is a set of virtual machines, containers, and storage +devices. It is useful for permission handling in cases where certain users +should have controlled access to a specific set of resources, as it allows for a +single permission to be applied to a set of elements, rather than having to +manage this on a per resource basis. Resource pools are often used in tandem +with groups so that the members of a group have permissions on a set of machines +and storage. + +[[pveum_authentication_realms]] +Authentication Realms +--------------------- + +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:: +In this case a system user has to exist (e.g. 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,59 +136,306 @@ 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 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 (e.g. +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` +(e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a +single line containing the raw password. ++ +To verify certificates, you need to to set `capath`. You can set it either +directly to the CA certificate of your LDAP server, or to the system path +containing all trusted CA certificates (`/etc/ssl/certs`). +Additionally, you need to set the `verify` option, which can also be done over +the web interface. + +Microsoft Active Directory:: + +A server and authentication domain need to be specified. Like with LDAP, an +optional fallback server, port, and SSL encryption can be configured. + +[[pveum_ldap_sync]] +Syncing LDAP-based realms +~~~~~~~~~~~~~~~~~~~~~~~~~ + +[thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"] + +It is possible to sync users and groups for LDAP based realms. You can use the +CLI command + +---- + pveum realm sync +---- +or in the `Authentication` panel of the GUI. Users and groups are synced to the +cluster-wide user configuration file `/etc/pve/user.cfg`. + +Requirements and limitations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `bind_dn` is used to query the users and groups. This account needs access +to all desired entries. + +The fields which represent the names of the users and groups can be configured +via the `user_attr` and `group_name_attr` respectively. Only entries which +adhere to the usual character limitations of the user.cfg are synced. + +Groups are synced with `-$realm` attached to the name, to avoid naming +conflicts. Please make sure that a sync does not overwrite manually created +groups. + +[[pveum_ldap_sync_options]] +Options +^^^^^^^ + +[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"] + +The main options for syncing are: + +* `dry-run`: No data is written to the config. This is useful if you want to + see which users and groups would get synced to the user.cfg. This is set + when you click `Preview` in the GUI. + +* `enable-new`: If set, the newly synced users are enabled and can login. + The default is `true`. + +* `full`: If set, the sync uses the LDAP Directory as a source of truth, + overwriting information set manually in the user.cfg and deletes users + and groups which are not present in the LDAP directory. If not set, + only new data is written to the config, and no stale users are deleted. + +* `purge`: If set, sync removes all corresponding ACLs when removing users + and groups. This is only useful with the option `full`. + +* `scope`: The scope of what to sync. It can be either `users`, `groups` or + `both`. + +These options are either set as parameters or as defaults, via the +realm option `sync-defaults-options`. + +[[pveum_tfa_auth]] +Two-factor authentication +------------------------- + +There are two ways to use two-factor authentication: + +It can be required by the authentication realm, either via 'TOTP' +(Time-based One-Time Password) or 'YubiKey OTP'. In this case a newly +created user needs their keys added immediately as there is no way to +log in without the second factor. In the case of 'TOTP', users can +also change the 'TOTP' later on, provided they can log in first. + +Alternatively, users can choose to opt in to two-factor authentication +via 'TOTP' later on, even if the realm does not enforce it. As another +option, if the server has an 'AppId' configured, a user can opt into +'U2F' authentication, provided the realm does not enforce any other +second factor. + +Realm enforced two-factor authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This can be done by selecting one of the available methods via the +'TFA' dropdown box when adding or editing an Authentication Realm. +When a realm has TFA enabled it becomes a requirement and only users +with configured TFA will be able to login. + +Currently there are two methods available: + +Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm +where the current time is hashed with the user's configured key. The +time step and password length parameters are configured. ++ +A user can have multiple keys configured (separated by spaces), and the keys +can be specified in Base32 (RFC3548) or hexadecimal notation. ++ +{pve} provides a key generation tool (`oathkeygen`) which prints out a random +key in Base32 notation which can be used directly with various OTP tools, such +as the `oathtool` command line tool, or on Android Google Authenticator, +FreeOTP, andOTP or similar applications. + +YubiKey OTP:: +For authenticating via a YubiKey a Yubico API ID, API KEY and validation +server URL must be configured, and users must have a YubiKey available. In +order to get the key ID from a YubiKey, you can trigger the YubiKey once +after connecting it to USB and copy the first 12 characters of the typed +password into the user's 'Key IDs' field. + ++ +Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP] +documentation for how to use the +https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or +https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host +your own verification server]. + +[[pveum_user_configured_totp]] +User configured TOTP authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users can choose to enable 'TOTP' as a second factor on login via the 'TFA' +button in the user list (unless the realm enforces 'YubiKey OTP'). + +[thumbnail="screenshot/gui-datacenter-users-tfa.png"] + +After opening the 'TFA' window, the user is presented with a dialog to setup +'TOTP' authentication. The 'Secret' field contains the key, which can simply be +generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be +added to provide information to the 'TOTP' app what the key belongs to. +Most 'TOTP' apps will show the issuer name together with the corresponding +'OTP' values. The user name is also included in the QR code for the 'TOTP' app. + +After generating a key, a QR code will be displayed which can be used with most +OTP apps such as FreeOTP. Now the user needs to verify both the current user +password (unless logged in as 'root'), as well as the ability to correctly use +the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code' +field before pressing the 'Apply' button. + +[[pveum_configure_u2f]] +Server side U2F configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To allow users to use 'U2F' authentication, it may be necessary to use a valid +domain with a valid https certificate, otherwise some browsers may print +a warning or reject U2F usage altogether. Initially an 'AppId' +footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] +needs to be configured. + +NOTE: Changing the 'AppId' will render all existing 'U2F' registrations +unusable! + +This is done via `/etc/pve/datacenter.cfg`, for instance: + +---- +u2f: appid=https://mypve.example.com:8006 +---- -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. +For a single node, the 'AppId' can simply be the web UI address exactly as it +is used in the browser, including the 'https://' and the port as shown above. +Please note that some browsers may be more strict than others when matching +'AppIds'. + +When using multiple nodes, it is best to have a separate `https` server +providing an `appid.json` +footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html] +file, as it seems to be compatible with most +browsers. If all nodes use subdomains of the same top level domain, it may be +enough to use the TLD as 'AppId', but note that some browsers may not accept +this. + +NOTE: A bad 'AppId' will usually produce an error, but we have encountered +situation where this does not happen, particularly when using a top level domain +'AppId' for a node accessed via a subdomain in Chromium. For this reason it is +recommended to test the configuration with multiple browsers, as changing the +'AppId' later will render existing 'U2F' registrations unusable. + +[[pveum_user_configured_u2f]] +Activating U2F as a user +~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the +current password (unless logged in as root), and press the 'Register' button. +If the server is setup correctly and the browser accepted the server's provided +'AppId', a message will appear prompting the user to press the button on the +'U2F' device (if it is a 'YubiKey' the button light should be toggling off and +on steadily around twice per second). -Terms and Definitions +Firefox users may need to enable 'security.webauth.u2f' via 'about:config' +before they can use a 'U2F' token. + +[[pveum_permission_management]] +Permission Management --------------------- -Users -~~~~~ +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. -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. +{pve} uses a role and path based permission management system. An entry in +the permissions table allows a user, group or token 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)', '(path, group, +role)' or '(path, token, role)', with the role containing a set of allowed +actions, and the path representing the target of these actions. -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 +[[pveum_roles]] +Roles +~~~~~ -Superuser -^^^^^^^^^ +A role is simply a list of privileges. Proxmox VE comes with a number +of predefined roles which satisfies most needs. -The traditional unix superuser account is called 'root@pam'. All -system mails are forwarded to the email assigned to that account. +* `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 CD-ROM, VM console, VM power management -Groups -~~~~~~ +You can see the whole set of predefined roles on the GUI. -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. +Adding new roles can be done via both GUI and the command line. -Objects and Paths -~~~~~~~~~~~~~~~~~ +[thumbnail="screenshot/gui-datacenter-role-add.png"] +For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and +click on the 'Create' button, there you can set a name and select all desired +roles from the 'Privileges' dropdown box. + +To add a role through the command line you can use the 'pveum' CLI tool, like +this: +[source,bash] +---- +pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" +pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" +---- -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. +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: @@ -123,7 +445,7 @@ Node / System related privileges:: * `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.Audit`: view node status/config, Corosync cluster config and HA config * `Sys.Modify`: create/remove/modify node network parameters * `Group.Allocate`: create/remove/modify groups * `Pool.Allocate`: create/remove/modify a pool @@ -142,7 +464,7 @@ Virtual machine related privileges:: * `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.CDROM`: eject/change CD-ROM * `VM.Config.CPU`: modify CPU settings * `VM.Config.Memory`: modify Memory settings * `VM.Config.Network`: add/modify/delete Network devices @@ -157,81 +479,125 @@ Storage related privileges:: * `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: +Objects and Paths +~~~~~~~~~~~~~~~~~ -[source,bash] ----- -pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" -pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" ----- +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. +[[pveum_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 -~~~~~~~~~~~ +Some examples are: -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. +* `/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 -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: -* 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. +* Permissions for individual users always replace group permissions. +* Permissions for groups apply when the user is member of that group. +* Permissions replace the ones inherited from an upper level. -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/ +Additionally, privilege separated tokens can never have a permission on any +given path that their associated user does not have. +[[pveum_pools]] 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. + +What permission do I need? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The required API permissions are documented for each individual +method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/ + +The permissions are specified as a list which can be interpreted as a +tree of logic and access-check functions: + +`["and", ...]` and `["or", ...]`:: +Each(`and`) or any(`or`) further element in the current list has to be true. + +`["perm", , [ ... ], ...]`:: +The `path` is a templated parameter (see +<>). All (or, if the `any` +option is used, any) of the listed +privileges must be allowed on the specified path. If a `require-param` +option is specified, then its specified parameter is required even if the +API call's schema otherwise lists it as being optional. + +`["userid-group", [ ... ], ...]`:: +The caller must have any of the listed privileges on `/access/groups`. In +addition there are two possible checks depending on whether the +`groups_param` option is set: ++ +* `groups_param` is set: The API call has a non-optional `groups` parameter +and the caller must have any of the listed privileges on all of the listed +groups. +* `groups_param` is not set: The user passed via the `userid` parameter +must exist and be part of a group on which the caller has any of the listed +privileges (via the `/access/groups/` path). + +`["userid-param", "self"]`:: +The value provided for the API call's `userid` parameter must refer to the +user performing the action. (Usually in conjunction with `or`, to allow +users to perform an action on themselves even if they don't have elevated +privileges.) + +`["userid-param", "Realm.AllocateUser"]`:: +The user needs `Realm.AllocateUser` access to `/access/realm/`, with +`` referring to the realm of the user passed via the `userid` +parameter. Note that the user does not need to exist in order to be +associated with a realm, since user IDs are passed in the form of +`@`. + +`["perm-modify", ]`:: +The `path` is a templated parameter (see +<>). The user needs either the +`Permissions.Modify` privilege, or, +depending on the path, the following privileges as a possible substitute: ++ +* `/storage/...`: additionally requires 'Datastore.Allocate` +* `/vms/...`: additionally requires 'VM.Allocate` +* `/pool/...`: additionally requires 'Pool.Allocate` ++ +If the path is empty, `Permission.Modify` on `/access` is required. + 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 fully 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 +functions through the REST API. Here are some simple usage examples. To show help type: @@ -241,12 +607,12 @@ Here are some simple usage examples. To show help type: or (to show detailed help about a specific command) [source,bash] - pveum help useradd + pveum help user add Create a new user: [source,bash] - pveum useradd testuser@pve -comment "Just a test" + pveum user add testuser@pve -comment "Just a test" Set or Change the password (not all realms support that): @@ -256,42 +622,43 @@ Set or Change the password (not all realms support that): Disable a user: [source,bash] - pveum usermod testuser@pve -enable 0 + pveum user modify testuser@pve -enable 0 Create a new group: [source,bash] - pveum groupadd testgroup + pveum group add testgroup Create a new role: [source,bash] - pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" + pveum role add 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). +users with full administrator rights (without using the root account). Define the group: [source,bash] - pveum groupadd admin -comment "System Administrators" + pveum group add admin -comment "System Administrators" Then add the permission: [source,bash] - pveum aclmod / -group admin -role Administrator + pveum acl modify / -group admin -role Administrator You can finally add users to the new 'admin' group: [source,bash] - pveum usermod testuser@pve -group admin + pveum user modify testuser@pve -group admin Auditors @@ -300,67 +667,87 @@ 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 + pveum acl modify / -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 + pveum acl modify /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 management to user `joe@pve` you can do that with: [source,bash] - pveum aclmod /access -user joe@pve -role PVEUserAdmin + pveum acl modify /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 + pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin + pveum acl modify /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'. +NOTE: The user is able to add other users, but only if they are +members of group `customers` and within realm `pve`. -Pools -~~~~~ +Limited API token for monitoring +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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). +Given a user `joe@pve` with the PVEVMAdmin role on all VMs: -You can also assign permissions to the pool. Those permissions are -inherited to all pool members. +[source,bash] + pveum acl modify /vms -user joe@pve -role PVEVMAdmin + +Add a new API token with separate privileges, which is only allowed to view VM +information (e.g., for monitoring purposes): + +[source,bash] + pveum user token add joe@pve monitoring -privsep 1 + pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor -Lets assume you have a software development department, so we first -create a group +Verify the permissions of the user and token: [source,bash] - pveum groupadd developers -comment "Our software developers" + pveum user permissions joe@pve + pveum user token permissions joe@pve monitoring + +Resource Pools +~~~~~~~~~~~~~~ + +An enterprise is usually structured into several smaller departments, and it is +common that you want to assign resources and delegate management tasks to each +of these. Let's assume that you want to set up a pool for a software development +department. First, create a group + +[source,bash] + pveum group add 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 + pveum user add developer1@pve -group developers -password -Note: The -password parameter will prompt you for a password +NOTE: The -password parameter will prompt you for a password + +Then we create a resource pool for our development department to use + +[source,bash] + pveum pool add dev-pool --comment "IT development pool" -I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool: +Finally, we can assign permissions to that pool [source,bash] - pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin + pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin Our software developers can now administrate the resources assigned to that pool.