From b4c315ba9e46167ded6be89558787d0cdca50f6b Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 15 Jul 2000 21:35:47 +0000 Subject: Revise locale and Kerberos documentation --- doc/src/sgml/client-auth.sgml | 91 +++++++++++-- doc/src/sgml/config.sgml | 291 ------------------------------------------ doc/src/sgml/runtime.sgml | 121 +++++++++++++++++- 3 files changed, 199 insertions(+), 304 deletions(-) (limited to 'doc/src') 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 @@ - + Client Authentication @@ -295,7 +295,8 @@ host all 192.168.2.0 255.255.255.0 ident othermap file after the password or crypt keyword, respectively, in 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). @@ -316,7 +317,7 @@ host all 192.168.2.0 255.255.255.0 ident othermap 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 pg_shadow that is managed by CREATE USER and 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 Kerberos system is far beyond the scope - of this document; in all generality it can be quite complex. The - Kerberos FAQ - can be a good starting point for exploration. + of this document; in all generality it can be quite complex (yet + powerful). The Kerberos + FAQ or MIT Project Athena can be + a good starting point for exploration. Several sources for + Kerberos distributions exist. In order to use 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 + (./configure --with-krb4 or ./configure + --with-krb5 respectively). @@ -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 ). The location of the keytab file - is specified at build time. By default it is + is specified at build time; by default it is /etc/srvtab in Kerberos 4 and - FILE:/usr/local/postgres/krb5.keytab in + FILE:/usr/local/pgsql/etc/krb5.keytab in Kerberos 5. - + + + To generate the keytab file, use for example (with version 5) + +kadmin% ank -randkey postgres/server.my.domain.org +kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org + + Read the Kerberos documentation for defails. + + + + In the Kerberos 5 hooks, the following assumptions + are made about user and service naming: + + + + + User principal names (anames) are assumed to contain the actual + Unix/Postgres user name in the first component. + + + + + The 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). + + + + + + + + + Parameter + Example + + + + + user + frew@S2K.ORG + + + user + aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG + + + host + postgres_dbms/ucbvax@S2K.ORG + + + + + + + + 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. + + 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 - - Locale Support - - - - - Written by Oleg Bartunov. - See Oleg's web page - for additional information on locale and Russian language support. - - - - 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 Postgres 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 - LC_CTYPE and LC_COLLATE, - but later LC_MONETARY 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 Postgres distribution. - - - People often complain that locale doesn't work for them. - There are several common mistakes: - - - - - 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 - LC_CTYPE and LC_COLLATE - before running postmaster - because backend gets information about locale from environment. - I use following shell script - (runpostgres): - - - #!/bin/sh - - export LC_CTYPE=koi8-r - export LC_COLLATE=koi8-r - postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' - - - and run it from rc.local as - - - /bin/su - postgres -c "/home/postgres/runpostgres" - - - - - - - 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 perl -v will - complain something like: - - - 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"). - - - - - - - Wrong location of locale files! - - Possible locations include: - /usr/lib/locale - (Linux, Solaris), /usr/share/locale (Linux), - /usr/lib/nls/loc (DUX 4.0). - - Check man locale to find the correct location. - Under Linux I did a symbolic link between /usr/lib/locale and - /usr/share/locale to be sure that - the next libc will not break my locale. - - - - - - - What are the Benefits? - - - 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. - - - - - What are the Drawbacks? - - - There is one evident drawback of using locale - its speed! - So, use locale only if you really need it. - - - - - - Kerberos Authentication - - - Kerberos is an industry-standard secure authentication - system suitable for distributed computing over a public network. - - - - Availability - - - The - Kerberos - authentication system is not distributed with Postgres. Versions of - Kerberos - are typically available as optional software from operating system - vendors. In addition, a source code distribution may be obtained through - MIT Project Athena. - - - - 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. - - - - Users located outside the United States of America and - Canada are warned that distribution of the actual encryption code in - Kerberos - is restricted by U. S. Government export regulations. - - - Inquiries regarding your Kerberos - should be directed to your vendor or - MIT Project Athena. - Note that FAQLs - (Frequently-Asked Questions Lists) are periodically posted to the - Kerberos mailing list - (send - mail to subscribe), - and - USENET news group. - - - - - Installation - - - Installation of - Kerberos - itself is covered in detail in the - Kerberos Installation Notes . - Make sure that the server key file (the srvtab - or keytab) - is somehow readable by the Postgres account. - - - Postgres and its clients can be compiled to use - either Version 4 or Version 5 of the MIT - Kerberos - protocols by setting the - KRBVERS - variable in the file src/Makefile.global to the - appropriate value. You can also change the location where - Postgres - expects to find the associated libraries, header files and its own - server key file. - - - After compilation is complete, Postgres - must be registered as a Kerberos - service. See the - Kerberos Operations Notes - and related manual pages for more details on registering services. - - - - - Operation - - - After initial installation, Postgres - should operate in all ways as a normal - Kerberos - service. For details on the use of authentication, see the - PostgreSQL User's Guide reference sections - for postmaster - and psql. - - - In the - Kerberos - Version 5 hooks, the following assumptions are made about user - and service naming: - - - - - User principal names (anames) are assumed to - contain the actual Unix/Postgres user name - in the first component. - - - - - The 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). - - - - - - - - - Kerberos Parameter Examples - Kerberos - - - - - - Parameter - - - Example - - - - - - - user - - - frew@S2K.ORG - - - - - user - - - aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG - - - - - host - - - postgres_dbms/ucbvax@S2K.ORG - - - - -
- - - Support for Version 4 will disappear sometime after the production - release of Version 5 by MIT. - - - @@ -1036,6 +1036,125 @@ env PGOPTIONS='--geqo=off' psql + + + Locale Support + + + Acknowledgement + + Written by Oleg Bartunov. See Oleg's web + page for additional information on locale and Russian + language support. + + + + + While doing a project for a company in Moscow, Russia, I + encountered the problem that 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 Perl (debugging) and + Glimpse. After several days of digging through the + Postgres 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 LC_CTYPE and + LC_COLLATE, but later LC_MONETARY 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 Postgres distribution. + + + + People often complain that locale doesn't work for them. There are + several common mistakes: + + + + + Didn't properly configure Postgres before + compilation. You must run configure with the + + + + + + Didn't setup environment correctly when starting postmaster. You + must define environment variables LC_CTYPE and + LC_COLLATE before running postmaster because + backend gets information about locale from environment. I use + following shell script: + +#!/bin/sh + +export LC_CTYPE=koi8-r +export LC_COLLATE=koi8-r +postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' + + + + + + + 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 perl -v will complain + something like: + +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"). + + + + + + + Wrong location of locale files. Possible locations include: + /usr/lib/locale (Linux, Solaris), + /usr/share/locale (Linux), + /usr/lib/nls/loc (DUX 4.0). + + Check man locale to find the correct + location. Under Linux I made a symbolic link between + /usr/lib/locale and + /usr/share/locale to be sure that the next + libc will not break my locale. + + + + + + + What are the Benefits? + + You can use ~* and order by operators for strings contain + characters from national alphabets. Non-english users definitely + need that. + + + + + What are the Drawbacks? + + There is one evident drawback of using locale - its speed! So, use + locale only if you really need it. + + + + + Shutting down the server -- cgit v1.2.3