path: root/doc/src/sgml/config.sgml

<chapter id="config">
<title id="install-config">Configuration Options</title>

<sect1>
<title>Parameters for Configuration (<application>configure</application>)</title>

<para>
The full set of parameters available in <application>configure</application>
can be obtained by typing

<programlisting>
$ ./configure --help
</programlisting>

<para>
The following parameters may be of interest to most installers:

<programlisting>
Directory and file names:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local/pgsql]
  --bindir=DIR            user executables in DIR [EPREFIX/bin]
  --datadir=DIR           read-only architecture-independent data in DIR
                          [PREFIX/share]
  --sysconfdir=DIR        read-only single-machine data in DIR [PREFIX/etc]
  --sharedstatedir=DIR    modifiable architecture-independent data in DIR
                          [PREFIX/com]
  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
  --includedir=DIR        C header files in DIR [PREFIX/include]
  --mandir=DIR            man documentation in DIR [PREFIX/man]
  --srcdir=DIR            find the sources in DIR [configure dir or ..]
Features and packages:
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
--enable and --with options recognized:
  --with-template=<replaceable>template</replaceable>
                          use operating system template file
                              see template directory
  --with-includes=<replaceable>incdir</replaceable>  site header files for tk/tcl, etc in DIR
  --with-libs=<replaceable>incdir</replaceable>      also search for libraries in DIR
  --with-libraries=<replaceable>libdir</replaceable> also search for libraries in DIR
  --enable-locale         enable locale support
  --enable-recode         enable cyrillic recode support
  --with-mb=<replaceable>encoding</replaceable>    enable multi-byte support
  --with-pgport=<replaceable>portnum</replaceable> change default startup port
  --with-tcl              use tcl
  --with-tclconfig=<replaceable>tcldir</replaceable> tclConfig.sh and tkConfig.sh are in DIR
  --with-perl             use perl
  --with-odbc             build ODBC driver package
  --with-odbcinst=<replaceable>odbcdir</replaceable> change default directory for odbcinst.ini
  --enable-cassert        enable assertion checks (debugging)
  --with-CC=<replaceable>compiler</replaceable>      use specific C compiler
  --with-CXX=<replaceable>compiler</replaceable>     use specific C++ compiler
  --with-x                use the X Window System
</programlisting>

<sect1>
<title>Parameters for Building (<application>make</application>)</title>

<para>
Many installation-related parameters can be set in the building
stage of <productname>Postgres</productname> installation.

<para>
In most cases, these parameters should be place in a file,
<filename>Makefile.custom</filename>, intended just for that purpose.
The default distribution does not contain this optional file, so you
will create it using a text editor of your choice. When upgrading installations,
you can simply copy your old Makefile.custom to the new installation before
doing the build.

<synopsis>
make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ]
</synopsis>

<para>
A few of the many variables which can be specified are:

<variablelist>
<varlistentry>
<term>
<envar>POSTGRESDIR</envar>

<listitem>
<para>
Top of the installation tree.

<varlistentry>
<term>
<envar>BINDIR</envar>

<listitem>
<para>
Location of applications and utilities.

<varlistentry>
<term>
<envar>LIBDIR</envar>

<listitem>
<para>
Location of object libraries, including shared libraries.

<varlistentry>
<term>
<envar>HEADERDIR</envar>

<listitem>
<para>
Location of include files.

<varlistentry>
<term>
<envar>ODBCINST</envar>

<listitem>
<para>
Location of installation-wide <application>psqlODBC</application>
(<acronym>ODBC</acronym>) configuration file.

</variablelist>

<para>
There are other optional parameters which are not as commonly used.
Many of those listed below are appropriate when doing 
<application>Postgres</application> server code development.

<variablelist>
<varlistentry>
<term>
<envar>CFLAGS</envar>

<listitem>
<para>
Set flags for the C compiler. 
Should be assigned with "+=" to retain relevant default parameters.

<varlistentry>
<term>
YFLAGS

<listitem>
<para>
Set flags for the yacc/bison parser. <option>-v</option> might be
used to help diagnose problems building a new parser.
Should be assigned with "+=" to retain relevant default parameters.

<varlistentry>
<term>
<envar>USE_TCL</envar>

<listitem>
<para>
Enable Tcl interface building.

<varlistentry>
<term>
<envar>HSTYLE</envar>

<listitem>
<para>
DocBook <acronym>HTML</acronym> style sheets for building the 
documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.

<varlistentry>
<term>
<envar>PSTYLE</envar>

<listitem>
<para>
DocBook style sheets for building printed documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.

</variablelist>

<para>
Here is an example <filename>Makefile.custom</filename> for a
PentiumPro Linux system:

<programlisting>
# Makefile.custom
# Thomas Lockhart 1998-03-01

POSTGRESDIR= /opt/postgres/current
CFLAGS+= -m486 # -g -O0
USE_TCL= true
TCL_LIB= -ltcl
X_LIBS= -L/usr/X11/lib
TK_LIB= -ltk

# documentation

HSTYLE= /home/tgl/SGML/db118.d/docbook/html
PSTYLE= /home/tgl/SGML/db118.d/docbook/print
</programlisting>

<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>
 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>

<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. 

<Sect2>
<Title>What are the Drawbacks?</Title>

<Para>
There is one evident drawback of using locale - it's speed! 
So, use locale only if you really need it. 


<Sect1>
<Title>Kerberos Authentication</Title>

<Para>
<productname>Kerberos</productname> is an industry-standard secure authentication
system suitable for distributed computing over a public network.

<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>.

<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.
</note>
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>
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>.

<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>
<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>
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.

<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>
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.

<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).

</itemizedlist>

<para>
<table tocentry="1">
<title>Kerberos Parameter Examples</title>
<titleabbrev>Kerberos</titleabbrev>

<tgroup cols="2">
<thead>
<row>
<entry>
Parameter
</entry>
<entry>
Example
</entry>

<tbody>
<row>
<entry>
user
</entry>
<entry>
frew@S2K.ORG
</entry>

<row>
<entry>
user
</entry>
<entry>
aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
</entry>

<row>
<entry>
host
</entry>
<entry>
postgres_dbms/ucbvax@S2K.ORG
</entry>
</tbody>
</tgroup>
</table>

<para>
Support for Version 4 will disappear sometime after the production
release of Version 5 by MIT.