[pve-devel] [PATCH docs 2/3] expand and reword the authentication realm section

[Wolfgang Bumiller]

---
I've separated authentication realms into a realms and users section
mostly because that's how it's represented in the GUI. (Therefore also
redundantly mention the separation of users and realms.)

Also note that we use the word realms everywhere, yet the file is
called 'domains.cfg'... I wonder if we should "fix" that on the lower
end some day...

 pveum.adoc | 85 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 67 insertions(+), 18 deletions(-)

diff --git a/pveum.adoc b/pveum.adoc
index 2cb1b4e..db9fde7 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -27,32 +27,38 @@ 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 (VMs, storages, nodes, etc.) granular access can be defined.
 
 
-Authentication Realms
----------------------
+Users
+-----
 
-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.
+{pve} stores user attributes in `/etc/pve/user.cfg`. This file does not
+store passwords, but login name, email address, an optional expiration date,
+and users can be enabled or disabled.
 
-Microsoft Active Directory::
+While passwords are not stored here, users are instead associated
+with authentication realms described below, as well as keys for the
+optional two factor authentication configured for the realm.
 
-LDAP::
 
-Linux PAM standard authentication::
+Authentication Realms
+---------------------
 
-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.
+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 (eg. 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
@@ -62,10 +68,53 @@ 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 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 (eq.
+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/<realmname>.pw`
+(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+single line containing the raw password.
+
+Microsoft Active Directory::
 
-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.
+A server and authentication domain need to be specified. Like with
+ldap an optional fallback server, optional port, and SSL
+encryption can be configured.
 
 
 Terms and Definitions
-- 
2.1.4