Revise locale and Kerberos documentation

This commit is contained in:
Peter Eisentraut 2000-07-15 21:35:47 +00:00
parent 3eec6ee145
commit b4c315ba9e
4 changed files with 199 additions and 335 deletions

View File

@ -1,31 +0,0 @@
Edit postgresql-7.0RC5/src/Makefile.global.in
Change PG_KRB_SRVTAB to somewhere useful for you, and PG_KRB_SRVNAM to
whatever you want your postgres kerberos service called.
Uncommment out KRBVERS=5 in Makefile.global.in.
Run configure, make, and install PostgreSQL.
Generate the keytab (PG_KRB_SRVTAB):
kadmin% ank -randkey postgres/server.my.domain.org
kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org
Make sure the keytab is read-only to the postgres user.
Make sure your client binaries can see the new libraries.
edit pg_hba.conf and change the authentication method to krb5.
Everything should then work. If you use mod_auth_krb and mod_perl on
your web server, you can use AuthType KerberosV5SaveCredentials with a
mod_perl script. This gives secure database access over the web. No
extra passwords required.
Cheers,
Mike Wyer,
Department of Computing, Imperial College
--
Mike Wyer <mw@doc.ic.ac.uk> || "Woof?"
http://www.doc.ic.ac.uk/~mw || Gaspode the Wonder Dog
Work: 020 7594 8440 || from "Moving Pictures"
Mobile: 07879 697119 || by Terry Pratchett

View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.2 2000/07/04 16:31:51 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.3 2000/07/15 21:35:47 petere Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
@ -295,7 +295,8 @@ host all 192.168.2.0 255.255.255.0 ident othermap
file after the <literal>password</> or <literal>crypt</> keyword,
respectively, in <filename>pg_hba.conf</>. If you do not use this
feature, then any user that is known to the database system can
connect (as long as he passes password authentication, of course).
connect to any database (as long as he passes password
authentication, of course).
</para>
<para>
@ -316,7 +317,7 @@ host all 192.168.2.0 255.255.255.0 ident othermap
<para>
Lines with and without passwords can be mixed in secondary
password files. Lines without password indicate use the main
password files. Lines without password indicate use of the main
password in <literal>pg_shadow</> that is managed by
<command>CREATE USER</> and <command>ALTER USER</>. Lines with
passwords will cause that password to be used. A password entry of
@ -348,14 +349,20 @@ host all 192.168.2.0 255.255.255.0 ident othermap
authentication system suitable for distributed computing over a
public network. A description of the
<productname>Kerberos</productname> system is far beyond the scope
of this document; in all generality it can be quite complex. The
<ulink url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos <acronym>FAQ</></ulink>
can be a good starting point for exploration.
of this document; in all generality it can be quite complex (yet
powerful). The <ulink
url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
<acronym>FAQ</></ulink> or <ulink
url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink> can be
a good starting point for exploration. Several sources for
<productname>Kerberos</> distributions exist.
</para>
<para>
In order to use <productname>Kerberos</>, support for it must be
enable at build time. Both Kerberos 4 and 5 are supported.
enable at build time. Both Kerberos 4 and 5 are supported
(<literal>./configure --with-krb4</> or <literal>./configure
--with-krb5</> respectively).
</para>
<para>
@ -365,14 +372,74 @@ host all 192.168.2.0 255.255.255.0 ident othermap
build. Make sure that your server keytab file is readable (and
preferrably only readable) by the Postgres server account (see
<xref linkend="postgres-user">). The location of the keytab file
is specified at build time. By default it is
is specified at build time; by default it is
<filename>/etc/srvtab</filename> in Kerberos 4 and
<filename>FILE:/usr/local/postgres/krb5.keytab</filename> in
<filename>FILE:/usr/local/pgsql/etc/krb5.keytab</filename> in
Kerberos 5.
</para>
<!-- Note from Peter E.: Some of the Kerberos usage information is
still in config.sgml and some in doc/README.kerberos. It should be
integrated here. -->
<para>
To generate the keytab file, use for example (with version 5)
<screen>
kadmin% <userinput>ank -randkey postgres/server.my.domain.org</>
kadmin% <userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
</screen>
Read the <productname>Kerberos</> documentation for defails.
</para>
<para>
In the <productname>Kerberos</> 5 hooks, the following assumptions
are made about user and service naming:
<itemizedlist>
<listitem>
<para>
User principal names (anames) are assumed to contain the actual
Unix/<productname>Postgres</> user name in the first component.
</para>
</listitem>
<listitem>
<para>
The <productname>Postgres</> service is assumed to be have two
components, the service name and a hostname, canonicalized as
in Version 4 (i.e., with all domain suffixes removed).
</para>
</listitem>
</itemizedlist>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Parameter</>
<entry>Example</>
</row>
</thead>
<tbody>
<row>
<entry>user</>
<entry>frew@S2K.ORG</>
</row>
<row>
<entry>user</>
<entry>aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG</>
</row>
<row>
<entry>host</>
<entry>postgres_dbms/ucbvax@S2K.ORG</>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
If you use mod_auth_krb and mod_perl on your Apache web server,
you can use AuthType KerberosV5SaveCredentials with a mod_perl
script. This gives secure database access over the web, no extra
passwords required.
</para>
</sect2>
<sect2>

View File

@ -262,297 +262,6 @@ PSTYLE= /home/tgl/SGML/db118.d/docbook/print
</para>
</sect1>
<sect1>
<title>Locale Support</title>
<para>
<note>
<para>
Written by Oleg Bartunov.
See <ulink url="http://www.sai.msu.su/~megera/postgres/">Oleg's web page</ulink>
for additional information on locale and Russian language support.
</para>
</note>
While doing a project for a company in Moscow, Russia,
I encountered the problem that postgresql had no
support of national alphabets. After looking for possible workarounds
I decided to develop support of locale myself.
I'm not a C-programer but already had some experience with locale programming
when I work with perl
(debugging) and glimpse. After several days of digging through
the <productname>Postgres</productname> source tree I made very minor corections to
src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed!
I did support only for
<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>,
but later <envar>LC_MONETARY</envar> was added by others. I got many
messages from people about this patch so I decided to send it to developers
and (to my surprise) it was
incorporated into the <productname>Postgres</productname> distribution.
</para>
<para>
People often complain that locale doesn't work for them.
There are several common mistakes:
<itemizedlist>
<listitem>
<para>
Didn't properly configure postgresql before compilation.
You must run configure with --enable-locale option to enable locale support.
Didn't setup environment correctly when starting postmaster.
You must define environment variables
<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>
before running postmaster
because backend gets information about locale from environment.
I use following shell script
(runpostgres):
<programlisting>
#!/bin/sh
export LC_CTYPE=koi8-r
export LC_COLLATE=koi8-r
postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'
</programlisting>
and run it from rc.local as
<programlisting>
/bin/su - postgres -c "/home/postgres/runpostgres"
</programlisting>
</para>
</listitem>
<listitem>
<para>
Broken locale support in OS (for example, locale support in libc
under Linux several times has changed
and this caused a lot of problems). Latest perl has also support of
locale and if locale is broken <command>perl -v</command> will
complain something like:
<programlisting>
8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
8:18[mira]:~/WWW/postgres>perl -v
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LC_ALL = (unset),
LC_CTYPE = "not_exist",
LANG = (unset)
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
</programlisting>
</para>
</listitem>
<listitem>
<para>
Wrong location of locale files!
Possible locations include:
<filename>/usr/lib/locale</filename>
(Linux, Solaris), <filename>/usr/share/locale</filename> (Linux),
<filename>/usr/lib/nls/loc</filename> (DUX 4.0).
Check <command>man locale</command> to find the correct location.
Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and
<filename>/usr/share/locale</filename> to be sure that
the next libc will not break my locale.
</para>
</listitem>
</itemizedlist>
</para>
<sect2>
<title>What are the Benefits?</title>
<para>
You can use ~* and order by operators for strings contain characters
from national alphabets. Non-english users
definitely need that. If you won't use locale stuff just undefine
the USE_LOCALE variable.
</para>
</sect2>
<sect2>
<title>What are the Drawbacks?</title>
<para>
There is one evident drawback of using locale - its speed!
So, use locale only if you really need it.
</para>
</sect2>
</sect1>
<sect1>
<title>Kerberos Authentication</title>
<para>
<productname>Kerberos</productname> is an industry-standard secure authentication
system suitable for distributed computing over a public network.
</para>
<sect2>
<title>Availability</title>
<para>
The
<productname>Kerberos</productname>
authentication system is not distributed with <productname>Postgres</productname>. Versions of
<productname>Kerberos</productname>
are typically available as optional software from operating system
vendors. In addition, a source code distribution may be obtained through
<ulink url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink>.
</para>
<note>
<para>
You may wish to obtain the MIT version even if your
vendor provides a version, since some vendor ports have been
deliberately crippled or rendered non-interoperable with the MIT
version.
</para>
</note>
<para>
Users located outside the United States of America and
Canada are warned that distribution of the actual encryption code in
<productname>Kerberos</productname>
is restricted by U. S. Government export regulations.
</para>
<para>
Inquiries regarding your <productname>Kerberos</productname>
should be directed to your vendor or
<ulink url="info-kerberos@athena.mit.edu">MIT Project Athena</ulink>.
Note that <acronym>FAQL</acronym>s
(Frequently-Asked Questions Lists) are periodically posted to the
<ulink url="mailto:kerberos@athena.mit.edu"><productname>Kerberos</productname> mailing list</ulink>
(send
<ulink url="mailto:kerberos-request@athena.mit.edu">mail to subscribe</ulink>),
and
<ulink url="news:comp.protocols.kerberos">USENET news group</ulink>.
</para>
</sect2>
<sect2>
<title>Installation</title>
<para>
Installation of
<productname>Kerberos</productname>
itself is covered in detail in the
<citetitle>Kerberos Installation Notes</citetitle> .
Make sure that the server key file (the <filename>srvtab</filename>
or <filename>keytab</filename>)
is somehow readable by the <productname>Postgres</productname> account.
</para>
<para>
<productname>Postgres</productname> and its clients can be compiled to use
either Version 4 or Version 5 of the MIT
<productname>Kerberos</productname>
protocols by setting the
<envar>KRBVERS</envar>
variable in the file <filename>src/Makefile.global</filename> to the
appropriate value. You can also change the location where
<productname>Postgres</productname>
expects to find the associated libraries, header files and its own
server key file.
</para>
<para>
After compilation is complete, <productname>Postgres</productname>
must be registered as a <productname>Kerberos</productname>
service. See the
<citetitle>Kerberos Operations Notes</citetitle>
and related manual pages for more details on registering services.
</para>
</sect2>
<sect2>
<title>Operation</title>
<para>
After initial installation, <productname>Postgres</productname>
should operate in all ways as a normal
<productname>Kerberos</productname>
service. For details on the use of authentication, see the
<citetitle>PostgreSQL User's Guide</citetitle> reference sections
for <application>postmaster</application>
and <application>psql</application>.
</para>
<para>
In the
<productname>Kerberos</productname>
Version 5 hooks, the following assumptions are made about user
and service naming:
<itemizedlist>
<listitem>
<para>
User principal names (anames) are assumed to
contain the actual Unix/<productname>Postgres</productname> user name
in the first component.
</para>
</listitem>
<listitem>
<para>
The <productname>Postgres</productname> service is assumed to be have two components,
the service name and a hostname, canonicalized as in Version 4 (i.e., with all domain
suffixes removed).
</para>
</listitem>
</itemizedlist>
</para>
<para>
<table tocentry="1">
<title>Kerberos Parameter Examples</title>
<titleabbrev>Kerberos</titleabbrev>
<tgroup cols="2">
<thead>
<row>
<entry>
Parameter
</entry>
<entry>
Example
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
user
</entry>
<entry>
frew@S2K.ORG
</entry>
</row>
<row>
<entry>
user
</entry>
<entry>
aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
</entry>
</row>
<row>
<entry>
host
</entry>
<entry>
postgres_dbms/ucbvax@S2K.ORG
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Support for Version 4 will disappear sometime after the production
release of Version 5 by MIT.
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file

View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.13 2000/07/12 17:38:41 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.14 2000/07/15 21:35:47 petere Exp $
-->
<Chapter Id="runtime">
@ -1036,6 +1036,125 @@ env PGOPTIONS='--geqo=off' psql
</sect2>
</sect1>
<sect1 id="locale">
<title>Locale Support</title>
<note>
<title>Acknowledgement</title>
<para>
Written by Oleg Bartunov. See <ulink
url="http://www.sai.msu.su/~megera/postgres/">Oleg's web
page</ulink> for additional information on locale and Russian
language support.
</para>
</note>
<para>
While doing a project for a company in Moscow, Russia, I
encountered the problem that <productname>Postgres</> had no
support of national alphabets. After looking for possible
workarounds I decided to develop support of locale myself. I'm not
a C programmer but already had some experience with locale
programming when I work with <productname>Perl</> (debugging) and
<productname>Glimpse</>. After several days of digging through the
<productname>Postgres</> source tree I made very minor corections
to <filename>src/backend/utils/adt/varlena.c</> and
<filename>src/backend/main/main.c</> and got what I needed! I did
support only for <envar>LC_CTYPE</envar> and
<envar>LC_COLLATE</envar>, but later <envar>LC_MONETARY</envar> was
added by others. I got many messages from people about this patch
so I decided to send it to developers and (to my surprise) it was
incorporated into the <productname>Postgres</> distribution.
</para>
<para>
People often complain that locale doesn't work for them. There are
several common mistakes:
<itemizedlist>
<listitem>
<para>
Didn't properly configure <productname>Postgres</> before
compilation. You must run <filename>configure</> with the
<option>--enable-locale</> option to enable locale support.
</para>
</listitem>
<listitem>
<para>
Didn't setup environment correctly when starting postmaster. You
must define environment variables <envar>LC_CTYPE</envar> and
<envar>LC_COLLATE</envar> before running postmaster because
backend gets information about locale from environment. I use
following shell script:
<programlisting>
#!/bin/sh
export LC_CTYPE=koi8-r
export LC_COLLATE=koi8-r
postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'
</programlisting>
</para>
</listitem>
<listitem>
<para>
Broken locale support in the operating system (for example,
locale support in libc under Linux several times has changed and
this caused a lot of problems). Perl has also support of locale
and if locale is broken <command>perl -v</> will complain
something like:
<screen>
8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
8:18[mira]:~/WWW/postgres>perl -v
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LC_ALL = (unset),
LC_CTYPE = "not_exist",
LANG = (unset)
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
</screen>
</para>
</listitem>
<listitem>
<para>
Wrong location of locale files. Possible locations include:
<filename>/usr/lib/locale</filename> (Linux, Solaris),
<filename>/usr/share/locale</filename> (Linux),
<filename>/usr/lib/nls/loc</filename> (DUX 4.0).
Check <command>man locale</command> to find the correct
location. Under Linux I made a symbolic link between
<filename>/usr/lib/locale</filename> and
<filename>/usr/share/locale</filename> to be sure that the next
libc will not break my locale.
</para>
</listitem>
</itemizedlist>
</para>
<formalpara>
<title>What are the Benefits?</title>
<para>
You can use ~* and order by operators for strings contain
characters from national alphabets. Non-english users definitely
need that.
</para>
</formalpara>
<formalpara>
<title>What are the Drawbacks?</title>
<para>
There is one evident drawback of using locale - its speed! So, use
locale only if you really need it.
</para>
</formalpara>
</sect1>
<sect1 id="postmaster-shutdown">
<title>Shutting down the server</title>