[PATCH] clarify username mapping in Kerberos and GSSAPI

Hello all,

I noticed what appears to be an ambiguity in this area, so I prepared a patch. It is included below. The issue is that the documentation does not make it crystal clear exactly what string is used for username mapping when authenticating with GSSAPI or Kerberos. It's possible that this issue also applies to the SSPI documentation, though I didn't check.

Cheers,

--Ian Turner
Senior UNIX Systems Engineer
D. E. Shaw & Co.

--- postgresql-8.4-8.4.1/doc/src/sgml/client-auth.sgml 2009-06-24 14:46:32.000000000 +0100
+++ postgresql-8.4-8.4.1-docfix/doc/src/sgml/client-auth.sgml 2009-10-23 20:41:28.000000000 +0100
@@ -801,23 +801,28 @@
The following configuration options are supported for <productname>GSSAPI</productname>:
<variablelist>
<varlistentry>
- <term><literal>map</literal></term>
+ <term><literal>include_realm</literal></term>
<listitem>
<para>
- Allows for mapping between system and database usernames. See
- <xref linkend="auth-username-maps"> for details.
+ If set to <literal>1</>, the realm name from the authenticated user
+ principal is included in the system user name that's passed through
+ username mapping (<xref linkend="auth-username-maps">). This is
+ useful for handling users from multiple realms.
</para>
</listitem>
</varlistentry>

<varlistentry>
- <term><literal>include_realm</literal></term>
+ <term><literal>map</literal></term>
<listitem>
<para>
- If set to <literal>1</>, the realm name from the authenticated user
- principal is included in the system user name that's passed through
- username mapping (<xref linkend="auth-username-maps">). This is
- useful for handling users from multiple realms.
+ Allows for mapping between system and database usernames. See
+ <xref linkend="auth-username-maps"> for details. For a Kerboros
+ principal <literal>username/hostbased(at)EXAMPLE(dot)COM</literal>, the
+ username used for mapping is <literal>username/hostbased</literal>
+ if <literal>include_realm</literal> is disabled, and
+ <literal>username/hostbased(at)EXAMPLE(dot)COM</literal> if
+ <literal>include_realm</literal> is enabled.
</para>
</listitem>
</varlistentry>
@@ -1003,10 +1008,10 @@
<para>
When connecting to the database make sure you have a ticket for a
principal matching the requested database user name. For example, for
- database user name <literal>fred</>, both principal
- <literal>fred(at)EXAMPLE(dot)COM</> and
- <literal>fred/users(dot)example(dot)com(at)EXAMPLE(dot)COM</> could be used to
- authenticate to the database server.
+ database user name <literal>fred</>, principal
+ <literal>fred(at)EXAMPLE(dot)COM</> would be able to connect. To also allow
+ principle <literal>fred/users(dot)example(dot)com(at)EXAMPLE(dot)COM</>, use a username
+ map, as described in <xref linkend="auth-username-maps">.
</para>

<para>