@@ -944,7 +944,12 @@ omicron bryanh guest1
944944 If set to 1, the realm name from the authenticated user
945945 principal is included in the system user name that's passed through
946946 user name mapping (<xref linkend="auth-username-maps">). This is
947- useful for handling users from multiple realms.
947+ the recommended configuration as, otherwise, it is impossible to
948+ differentiate users with the same username who are from different
949+ realms. The default for this parameter is 0 (meaning to not include
950+ the realm in the system user name) but may change to 1 in a future
951+ version of <productname>PostgreSQL</productname>. Users can set it
952+ explicitly to avoid any issues when upgrading.
948953 </para>
949954 </listitem>
950955 </varlistentry>
@@ -954,12 +959,16 @@ omicron bryanh guest1
954959 <listitem>
955960 <para>
956961 Allows for mapping between system and database user names. See
957- <xref linkend="auth-username-maps"> for details. For a Kerberos
958- principal <literal>username/hostbased@EXAMPLE.COM</literal>, the
959- user name used for mapping is <literal>username/hostbased</literal>
960- if <literal>include_realm</literal> is disabled, and
961- <literal>username/hostbased@EXAMPLE.COM</literal> if
962- <literal>include_realm</literal> is enabled.
962+ <xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos
963+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
964+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
965+ default user name used for mapping is
966+ <literal>username</literal> (or <literal>username/hostbased</literal>,
967+ respectfully), unless <literal>include_realm</literal> has been set to
968+ 1 (as recommended, see above), in which case
969+ <literal>username@EXAMPLE.COM</literal> (or
970+ <literal>username/hostbased@EXAMPLE.COM</literal>)
971+ is what is seen as the system username when mapping.
963972 </para>
964973 </listitem>
965974 </varlistentry>
@@ -1017,7 +1026,12 @@ omicron bryanh guest1
10171026 If set to 1, the realm name from the authenticated user
10181027 principal is included in the system user name that's passed through
10191028 user name mapping (<xref linkend="auth-username-maps">). This is
1020- useful for handling users from multiple realms.
1029+ the recommended configuration as, otherwise, it is impossible to
1030+ differentiate users with the same username who are from different
1031+ realms. The default for this parameter is 0 (meaning to not include
1032+ the realm in the system user name) but may change to 1 in a future
1033+ version of <productname>PostgreSQL</productname>. Users can set it
1034+ explicitly to avoid any issues when upgrading.
10211035 </para>
10221036 </listitem>
10231037 </varlistentry>
@@ -1027,7 +1041,16 @@ omicron bryanh guest1
10271041 <listitem>
10281042 <para>
10291043 Allows for mapping between system and database user names. See
1030- <xref linkend="auth-username-maps"> for details.
1044+ <xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos
1045+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
1046+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
1047+ default user name used for mapping is
1048+ <literal>username</literal> (or <literal>username/hostbased</literal>,
1049+ respectfully), unless <literal>include_realm</literal> has been set to
1050+ 1 (as recommended, see above), in which case
1051+ <literal>username@EXAMPLE.COM</literal> (or
1052+ <literal>username/hostbased@EXAMPLE.COM</literal>)
1053+ is what is seen as the system username when mapping.
10311054 </para>
10321055 </listitem>
10331056 </varlistentry>