From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 6 May 2016 21:42:44 +0000 (-0400)
Subject: Docs: minor copy-editing for GSSAPI/SSPI authentication docs.
X-Git-Tag: REL9_6_BETA1~17
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=36db18eaa0def33b3f7ea5e3980c43431ca9c923;p=postgresql

Docs: minor copy-editing for GSSAPI/SSPI authentication docs.

Describe compat_realm = 0 as "disabled" not "enabled", per discussion
with Christian Ullrich.  I failed to resist the temptation to do some
other minor copy-editing in the same area.
---

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index e28d02eafe..1d0f0409a0 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -970,17 +970,18 @@ omicron         bryanh                  guest1
     strongly discouraged as it is then impossible to distinguish different users
     with the same user name but coming from different realms.  To enable this,
     set <literal>include_realm</> to 0.  For simple single-realm
-    installations, <literal>include_realm</> combined with the
-    <literal>krb_realm</> parameter (which checks that the realm provided
-    matches exactly what is in the <literal>krb_realm</literal> parameter) would be a secure but
-    less capable option compared to specifying an explicit mapping in
+    installations, doing that combined with setting the
+    <literal>krb_realm</> parameter (which checks that the principal's realm
+    matches exactly what is in the <literal>krb_realm</literal> parameter)
+    is still secure; but this is a
+    less capable approach compared to specifying an explicit mapping in
     <filename>pg_ident.conf</>.
    </para>
 
    <para>
     Make sure that your server keytab file is readable (and preferably
-    only readable) by the <productname>PostgreSQL</productname> server
-    account.  (See also <xref linkend="postgres-user">.) The location
+    only readable, not writable) by the <productname>PostgreSQL</productname>
+    server account.  (See also <xref linkend="postgres-user">.) The location
     of the key file is specified by the <xref
     linkend="guc-krb-server-keyfile"> configuration
     parameter. The default is
@@ -1019,10 +1020,12 @@ omicron         bryanh                  guest1
         If set to 0, the realm name from the authenticated user principal is
         stripped off before being passed through the user name mapping
         (<xref linkend="auth-username-maps">). This is discouraged and is
-        primarily available for backwards compatibility as it is not secure
-        in multi-realm environments unless <literal>krb_realm</literal> is also used.  Users
-        are recommended to leave include_realm set to the default (1) and to
-        provide an explicit mapping in <filename>pg_ident.conf</>.
+        primarily available for backwards compatibility, as it is not secure
+        in multi-realm environments unless <literal>krb_realm</literal> is
+        also used.  It is recommended to
+        leave <literal>include_realm</literal> set to the default (1) and to
+        provide an explicit mapping in <filename>pg_ident.conf</> to convert
+        principal names to <productname>PostgreSQL</> user names.
        </para>
       </listitem>
      </varlistentry>
@@ -1098,10 +1101,12 @@ omicron         bryanh                  guest1
         If set to 0, the realm name from the authenticated user principal is
         stripped off before being passed through the user name mapping
         (<xref linkend="auth-username-maps">). This is discouraged and is
-        primarily available for backwards compatibility as it is not secure
-        in multi-realm environments unless <literal>krb_realm</literal> is also used.  Users
-        are recommended to leave include_realm set to the default (1) and to
-        provide an explicit mapping in <filename>pg_ident.conf</>.
+        primarily available for backwards compatibility, as it is not secure
+        in multi-realm environments unless <literal>krb_realm</literal> is
+        also used.  It is recommended to
+        leave <literal>include_realm</literal> set to the default (1) and to
+        provide an explicit mapping in <filename>pg_ident.conf</> to convert
+        principal names to <productname>PostgreSQL</> user names.
        </para>
       </listitem>
      </varlistentry>
@@ -1116,7 +1121,7 @@ omicron         bryanh                  guest1
         the Kerberos user principal name is used.
        </para>
        <para>
-        Do not enable this option unless your server runs under a domain
+        Do not disable this option unless your server runs under a domain
         account (this includes virtual service accounts on a domain member
         system) and all clients authenticating through SSPI are also using
         domain accounts, or authentication will fail.