+----
+pveum realm sync <realm>
+----
+
+Users and groups are synced to the cluster-wide configuration file,
+`/etc/pve/user.cfg`.
+
+
+Attributes to Properties
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the sync response includes user attributes, they will be synced into the
+matching user property in the `user.cfg`. For example: `firstname` or
+`lastname`.
+
+If the names of the attributes are not matching the {pve} properties, you can
+set a custom field-to-field map in the config by using the `sync_attributes`
+option.
+
+How such properties are handled if anything vanishes can be controlled via the
+sync options, see below.
+
+Sync Configuration
+^^^^^^^^^^^^^^^^^^
+
+The configuration options for syncing LDAP-based realms can be found in the
+`Sync Options` tab of the Add/Edit window.
+
+The configuration options are as follows:
+
+* `Bind User` (`bind_dn`): Refers to the LDAP account used to query users
+ and groups. This account needs access to all desired entries. If it's set, the
+ search will be carried out via binding; otherwise, the search will be carried
+ out anonymously. The user must be a complete LDAP formatted distinguished name
+ (DN), for example, `cn=admin,dc=example,dc=com`.
+
+* Groupname attr. (group_name_attr): Represents the
+ users' groups. Only entries which adhere to the usual character limitations of
+ the `user.cfg` are synced. Groups are synced with `-$realm` attached to the
+ name, in order to avoid naming conflicts. Please ensure that a sync does not
+ overwrite manually created groups.
+
+* `User classes` (`user_classes`): Objects classes associated with users.
+
+* `Group classes` (`group_classes`): Objects classes associated with groups.
+
+* `E-Mail attribute`: If the LDAP-based server specifies user email addresses,
+ these can also be included in the sync by setting the associated attribute
+ here. From the command line, this is achievable through the
+ `--sync_attributes` parameter.
+
+* `User Filter` (`filter`): For further filter options to target specific users.
+
+* `Group Filter` (`group_filter`): For further filter options to target specific
+ groups.
+
+NOTE: Filters allow you to create a set of additional match criteria, to narrow
+down the scope of a sync. Information on available LDAP filter types and their
+usage can be found at https://ldap.com/ldap-filters/[ldap.com].
+
+[[pveum_ldap_sync_options]]
+Sync Options
+^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
+
+In addition to the options specified in the previous section, you can also
+configure further options that describe the behavior of the sync operation.
+
+These options are either set as parameters before the sync, or as defaults via
+the realm option `sync-defaults-options`.
+
+The main options for syncing are:
+
+* `Scope` (`scope`): The scope of what to sync. It can be either `users`,
+ `groups` or `both`.
+
+* `Enable new` (`enable-new`): If set, the newly synced users are enabled and
+ can log in. The default is `true`.
+
+* `Remove Vanished` (`remove-vanished`): This is a list of options which, when
+ activated, determine if they are removed when they are not returned from
+ the sync response. The options are:
+
+ - `ACL` (`acl)`: Remove ACLs of users and groups which were not returned
+ returned in the sync response. This most often makes sense together with
+ `Entry`.
+
+ - `Entry` (`entry`): Removes entries (i.e. users and groups) when they are
+ not returned in the sync response.
+
+ - `Properties` (`properties`): Removes properties of entries where the user
+ in the sync response did not contain those attributes. This includes
+ all properties, even those never set by a sync. Exceptions are tokens
+ and the enable flag, these will be retained even with this option enabled.
+
+* `Preview` (`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`.
+
+[[pveum_ldap_reserved_characters]]
+Reserved characters
+^^^^^^^^^^^^^^^^^^^
+
+Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be
+easily used in attribute values in DNs without being escaped properly.
+
+Following characters need escaping:
+
+* Space ( ) at the beginning or end
+* Number sign (`#`) at the beginning
+* Comma (`,`)
+* Plus sign (`+`)
+* Double quote (`"`)
+* Forward slashes (`/`)
+* Angle brackets (`<>`)
+* Semicolon (`;`)
+* Equals sign (`=`)
+
+To use such characters in DNs, surround the attribute value in double quotes.
+For example, to bind with a user with the CN (Common Name) `Example, User`, use
+`CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`.
+
+This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes.
+
+NOTE: Users with colons and forward slashes cannot be synced since these are
+reserved characters in usernames.
+
+[[pveum_openid]]
+OpenID Connect
+~~~~~~~~~~~~~~
+
+The main OpenID Connect configuration options are:
+
+* `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
+Proxmox uses the OpenID Connect Discovery protocol to automatically configure
+further details.
++
+While it is possible to use unencrypted `http://` URLs, we strongly recommend to
+use encrypted `https://` connections.
+
+* `Realm` (`realm`): The realm identifier for {pve} users
+
+* `Client ID` (`client-id`): OpenID Client ID.
+
+* `Client Key` (`client-key`): Optional OpenID Client Key.
+
+* `Autocreate Users` (`autocreate`): Automatically create users if they do not
+exist. While authentication is done at the OpenID server, all users still need
+an entry in the {pve} user configuration. You can either add them manually, or
+use the `autocreate` option to automatically add new users.
+
+* `Username Claim` (`username-claim`): OpenID claim used to generate the unique
+username (`subject`, `username` or `email`).
+
+Username mapping
+^^^^^^^^^^^^^^^^
+
+The OpenID Connect specification defines a single unique attribute
+('claim' in OpenID terms) named `subject`. By default, we use the
+value of this attribute to generate {pve} usernames, by simple adding
+`@` and the realm name: `${subject}@${realm}`.
+
+Unfortunately, most OpenID servers use random strings for `subject`, like
+`DGH76OKH34BNG3245SB`, so a typical username would look like
+`DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
+humans to remember such random strings, making it quite impossible to
+associate real users with this.
+
+The `username-claim` setting allows you to use other attributes for
+the username mapping. Setting it to `username` is preferred if the
+OpenID Connect server provides that attribute and guarantees its
+uniqueness.
+
+Another option is to use `email`, which also yields human readable
+usernames. Again, only use this setting if the server guarantees the
+uniqueness of this attribute.
+
+Examples
+^^^^^^^^
+
+Here is an example of creating an OpenID realm using Google. You need to
+replace `--client-id` and `--client-key` with the values
+from your Google OpenID settings.
+
+----
+pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email
+----
+
+The above command uses `--username-claim email`, so that the usernames on the
+{pve} side look like `example.user@google.com@myrealm1`.
+
+Keycloak (https://www.keycloak.org/) is a popular open source Identity
+and Access Management tool, which supports OpenID Connect. In the following
+example, you need to replace the `--issuer-url` and `--client-id` with
+your information:
+
+----
+pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
+----