@@ -1000,7 +1000,12 @@ omicron bryanh guest1
10001000 If set to 1, the realm name from the authenticated user
10011001 principal is included in the system user name that's passed through
10021002 user name mapping (<xref linkend="auth-username-maps">). This is
1003- useful for handling users from multiple realms.
1003+ the recommended configuration as, otherwise, it is impossible to
1004+ differentiate users with the same username who are from different
1005+ realms. The default for this parameter is 0 (meaning to not include
1006+ the realm in the system user name) but may change to 1 in a future
1007+ version of <productname>PostgreSQL</productname>. Users can set it
1008+ explicitly to avoid any issues when upgrading.
10041009 </para>
10051010 </listitem>
10061011 </varlistentry>
@@ -1010,12 +1015,16 @@ omicron bryanh guest1
10101015 <listitem>
10111016 <para>
10121017 Allows for mapping between system and database user names. See
1013- <xref linkend="auth-username-maps"> for details. For a Kerberos
1014- principal <literal>username/hostbased@EXAMPLE.COM</literal>, the
1015- user name used for mapping is <literal>username/hostbased</literal>
1016- if <literal>include_realm</literal> is disabled, and
1017- <literal>username/hostbased@EXAMPLE.COM</literal> if
1018- <literal>include_realm</literal> is enabled.
1018+ <xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos
1019+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
1020+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
1021+ default user name used for mapping is
1022+ <literal>username</literal> (or <literal>username/hostbased</literal>,
1023+ respectfully), unless <literal>include_realm</literal> has been set to
1024+ 1 (as recommended, see above), in which case
1025+ <literal>username@EXAMPLE.COM</literal> (or
1026+ <literal>username/hostbased@EXAMPLE.COM</literal>)
1027+ is what is seen as the system username when mapping.
10191028 </para>
10201029 </listitem>
10211030 </varlistentry>
@@ -1073,7 +1082,12 @@ omicron bryanh guest1
10731082 If set to 1, the realm name from the authenticated user
10741083 principal is included in the system user name that's passed through
10751084 user name mapping (<xref linkend="auth-username-maps">). This is
1076- useful for handling users from multiple realms.
1085+ the recommended configuration as, otherwise, it is impossible to
1086+ differentiate users with the same username who are from different
1087+ realms. The default for this parameter is 0 (meaning to not include
1088+ the realm in the system user name) but may change to 1 in a future
1089+ version of <productname>PostgreSQL</productname>. Users can set it
1090+ explicitly to avoid any issues when upgrading.
10771091 </para>
10781092 </listitem>
10791093 </varlistentry>
@@ -1083,7 +1097,16 @@ omicron bryanh guest1
10831097 <listitem>
10841098 <para>
10851099 Allows for mapping between system and database user names. See
1086- <xref linkend="auth-username-maps"> for details.
1100+ <xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos
1101+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
1102+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
1103+ default user name used for mapping is
1104+ <literal>username</literal> (or <literal>username/hostbased</literal>,
1105+ respectfully), unless <literal>include_realm</literal> has been set to
1106+ 1 (as recommended, see above), in which case
1107+ <literal>username@EXAMPLE.COM</literal> (or
1108+ <literal>username/hostbased@EXAMPLE.COM</literal>)
1109+ is what is seen as the system username when mapping.
10871110 </para>
10881111 </listitem>
10891112 </varlistentry>