From d6d1ce2f8b1c81903115b018973c61fc71235b7b Mon Sep 17 00:00:00 2001
From: Sumit Bose <sbose@redhat.com>
Date: Fri, 29 Nov 2019 18:10:03 +0100
Subject: [PATCH] doc: extend user-principal section

Related to https://bugzilla.redhat.com/show_bug.cgi?id=1643814
---
 doc/manual/realm.xml       | 21 +++++++++++++++++++--
 doc/manual/realmd.conf.xml | 15 ++++++++++-----
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/doc/manual/realm.xml b/doc/manual/realm.xml
index 7b73331..55a7640 100644
--- a/doc/manual/realm.xml
+++ b/doc/manual/realm.xml
@@ -254,10 +254,27 @@ $ realm join --user=admin --computer-ou=OU=Special domain.example.com
 		</varlistentry>
 		<varlistentry>
 			<term><option>--user-principal=<parameter>host/name@REALM</parameter></option></term>
-			<listitem><para>Set the userPrincipalName field of the
+			<listitem><para>Set the
+			<option>userPrincipalName</option> field of the
 			computer account to this kerberos principal. If you omit
 			the value for this option, then a principal will be set
-			in the form of <literal>host/shortname@REALM</literal></para></listitem>
+			based on the defaults of the membership software.</para>
+			<para>AD makes a distinction between user and service
+			principals. Only with user principals you can request a
+			Kerberos Ticket-Granting-Ticket (TGT), i.e. only user
+			principals can be used with the <command>kinit</command>
+			command. By default the user principal and the canonical
+			principal name of an AD computer account is
+			<code>shortname$@AD.DOMAIN</code>, where shortname is
+			the NetBIOS name which is limited to 15 characters.</para>
+			<para>If there are applications which are not aware of
+			the AD default and are using a hard-coded default
+			principal the <option>--user-principal</option> can be
+			used to make AD aware of this principal. Please note
+			that <option>userPrincipalName</option> is a single
+			value LDAP attribute, i.e. only one alternative user
+			principal besides the AD default user principal can be
+			set.</para></listitem>
 		</varlistentry>
 	</variablelist>
 
diff --git a/doc/manual/realmd.conf.xml b/doc/manual/realmd.conf.xml
index f0b0879..a26a60c 100644
--- a/doc/manual/realmd.conf.xml
+++ b/doc/manual/realmd.conf.xml
@@ -365,12 +365,17 @@ computer-name = SERVER01
 	</listitem>
 	</varlistentry>
 	<varlistentry>
-	<term><option>user-prinicpal</option></term>
+	<term><option>user-principal</option></term>
 	<listitem>
-		<para>Set the <option>user-prinicpal</option> to <code>yes</code>
-		to create <option>userPrincipalName</option> attributes for the
-		computer account in the realm, in the form
-		<code>host/computer@REALM</code></para>
+		<para>Set the <option>user-principal</option> to <code>yes</code>
+		to create <option>userPrincipalName</option> attribute for the
+		computer accounts in the realm. The exact value depends on the
+		defaults of the used membership software. To have full control
+		over the value please use the
+		<option>--user-principal</option> option of the
+		<command>realm</command> command, see
+		<citerefentry><refentrytitle>realm</refentrytitle>
+		<manvolnum>8</manvolnum></citerefentry> for details.</para>
 
 		<informalexample>
 <programlisting language="js">
-- 
2.21.0