[[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
[[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
password then has to be stored in `/etc/pve/priv/ldap/<realmname>.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::
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 <realm>
+----
+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
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]]