@@ -834,7 +834,12 @@ omicron bryanh guest1
834834 If set to <literal>1</>, the realm name from the authenticated user
835835 principal is included in the system user name that's passed through
836836 user name mapping (<xref linkend="auth-username-maps">). This is
837- useful for handling users from multiple realms.
837+ the recommended configuration as, otherwise, it is impossible to
838+ differentiate users with the same username who are from different
839+ realms. The default for this parameter is 0 (meaning to not include
840+ the realm in the system user name) but may change to 1 in a future
841+ version of <productname>PostgreSQL</productname>. Users can set it
842+ explicitly to avoid any issues when upgrading.
838843 </para>
839844 </listitem>
840845 </varlistentry>
@@ -844,12 +849,16 @@ omicron bryanh guest1
844849 <listitem>
845850 <para>
846851 Allows for mapping between system and database user names. See
847- <xref linkend="auth-username-maps"> for details. For a Kerberos
848- principal <literal>username/hostbased@EXAMPLE.COM</literal>, the
849- user name used for mapping is <literal>username/hostbased</literal>
850- if <literal>include_realm</literal> is disabled, and
851- <literal>username/hostbased@EXAMPLE.COM</literal> if
852- <literal>include_realm</literal> is enabled.
852+ <xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos
853+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
854+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
855+ default user name used for mapping is
856+ <literal>username</literal> (or <literal>username/hostbased</literal>,
857+ respectfully), unless <literal>include_realm</literal> has been set to
858+ 1 (as recommended, see above), in which case
859+ <literal>username@EXAMPLE.COM</literal> (or
860+ <literal>username/hostbased@EXAMPLE.COM</literal>)
861+ is what is seen as the system username when mapping.
853862 </para>
854863 </listitem>
855864 </varlistentry>
@@ -905,7 +914,12 @@ omicron bryanh guest1
905914 If set to <literal>1</>, the realm name from the authenticated user
906915 principal is included in the system user name that's passed through
907916 user name mapping (<xref linkend="auth-username-maps">). This is
908- useful for handling users from multiple realms.
917+ the recommended configuration as, otherwise, it is impossible to
918+ differentiate users with the same username who are from different
919+ realms. The default for this parameter is 0 (meaning to not include
920+ the realm in the system user name) but may change to 1 in a future
921+ version of <productname>PostgreSQL</productname>. Users can set it
922+ explicitly to avoid any issues when upgrading.
909923 </para>
910924 </listitem>
911925 </varlistentry>
@@ -915,7 +929,16 @@ omicron bryanh guest1
915929 <listitem>
916930 <para>
917931 Allows for mapping between system and database user names. See
918- <xref linkend="auth-username-maps"> for details.
932+ <xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos
933+ principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
934+ commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
935+ default user name used for mapping is
936+ <literal>username</literal> (or <literal>username/hostbased</literal>,
937+ respectfully), unless <literal>include_realm</literal> has been set to
938+ 1 (as recommended, see above), in which case
939+ <literal>username@EXAMPLE.COM</literal> (or
940+ <literal>username/hostbased@EXAMPLE.COM</literal>)
941+ is what is seen as the system username when mapping.
919942 </para>
920943 </listitem>
921944 </varlistentry>