From b4c315ba9e46167ded6be89558787d0cdca50f6b Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Sat, 15 Jul 2000 21:35:47 +0000
Subject: [PATCH] Revise locale and Kerberos documentation
---
doc/README.kerberos | 31 ----
doc/src/sgml/client-auth.sgml | 91 +++++++++--
doc/src/sgml/config.sgml | 291 ----------------------------------
doc/src/sgml/runtime.sgml | 121 +++++++++++++-
4 files changed, 199 insertions(+), 335 deletions(-)
delete mode 100644 doc/README.kerberos
diff --git a/doc/README.kerberos b/doc/README.kerberos
deleted file mode 100644
index 189d035b912..00000000000
--- a/doc/README.kerberos
+++ /dev/null
@@ -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
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 500fc6ea3fa..f22b0af662f 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -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>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 59eda7a6377..c80a8beb800 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -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
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 0413fc11cc5..cc6900ece43 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -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>
--
GitLab