[pve-devel] [PATCH docs 2/2] pveum: Document reserved characters and quoting of LDAP DNs

[Christoph Heiss <c.heiss@proxmox.com>]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pveum.adoc | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/pveum.adoc b/pveum.adoc
index 65d874a..1562b6c 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -390,6 +390,39 @@ The main options for syncing are:
 * `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 and cannot be easily used in attribute values
+in DNs without being escaped properly.
+
+Following characters need escaping:
+
+* Space (` `)
+
+* 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
--
2.34.1