X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=pveum.adoc;h=1f7c69fb7a1a8b7ce8cdb2f00a89857afd4194c4;hb=40e6c80663d661debf3a3cff5de7779bf1d4691b;hp=c89d4b872caa7be377f8fe1fa222af3581c3f23b;hpb=a10a91c2882a868a715c42d1550d280b216eed1f;p=pve-docs.git diff --git a/pveum.adoc b/pveum.adoc index c89d4b8..1f7c69f 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -100,6 +100,20 @@ 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 --------------------- @@ -163,6 +177,12 @@ 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 doen over +the web interface. Microsoft Active Directory:: @@ -170,6 +190,63 @@ A server and authentication domain need to be specified. Like with ldap an optional fallback server, optional 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 @@ -222,7 +299,7 @@ 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/YubiKey_OTP/YubiCloud_Validation_Servers/[host +https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server]. [[pveum_user_configured_totp]] @@ -530,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): @@ -545,17 +622,17 @@ 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 @@ -571,17 +648,17 @@ 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 @@ -593,12 +670,12 @@ role to users or groups. 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 [source,bash] - pveum aclmod /vms -user joe@pve -role PVEAuditor + pveum acl modify /vms -user joe@pve -role PVEAuditor Delegate User Management @@ -608,7 +685,7 @@ 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 other user attributes. This is a very powerful role, and you most @@ -617,8 +694,8 @@ 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`. @@ -629,14 +706,14 @@ Limited API token for monitoring Given a user `joe@pve` with the PVEVMAdmin role on all VMs: [source,bash] - pveum aclmod /vms -user joe@pve -role PVEVMAdmin + 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 aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor + pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor Verify the permissions of the user and token: @@ -644,35 +721,33 @@ Verify the permissions of the user and token: pveum user permissions joe@pve pveum user token permissions joe@pve monitoring -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. +Resource Pools +~~~~~~~~~~~~~~ -Lets assume you have a software development department, so we first -create a group +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 groupadd developers -comment "Our software developers" + 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 -I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: +Then we create a resource pool for our development department to use + +[source,bash] + pveum pool add dev-pool --comment "IT development 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.