postgresql/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>
  <para>
   The following parameters may be of interest to installers:
   
   <programlisting>
Directories to install PostgreSQL in:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local/pgsql]
  --bindir=DIR            user executables in DIR [EPREFIX/bin]
  --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]
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>dirs</replaceable>    look for header files for tcl/tk, etc in DIRS
  --with-libraries=<replaceable>dirs</replaceable>   look for additional libraries in DIRS
  --with-libs=<replaceable>dirs</replaceable>        alternate spelling of --with-libraries
  --enable-locale         enable locale support
  --enable-recode         enable cyrillic recode support
  --enable-multibyte      enable multibyte character support
  --with-pgport=<replaceable>portnum</replaceable>   change default postmaster port
  --with-maxbackends=<replaceable>n</replaceable>    set default maximum number of server processes 
  --with-tcl              build Tcl interfaces and pgtclsh
  --with-tclconfig=<replaceable>tcldir</replaceable>
                          tclConfig.sh and tkConfig.sh are in DIR
  --with-perl             build Perl interface and plperl
  --with-odbc             build ODBC driver package
  --with-odbcinst=<replaceable>odbcdir</replaceable>
                          change default directory for odbcinst.ini
  --enable-cassert        enable assertion checks (for debugging)
  --enable-debug          build with debugging symbols (-g) 
  --with-CC=<replaceable>compiler</replaceable>
                          use specific C compiler
  --with-CXX=<replaceable>compiler</replaceable>
                          use specific C++ compiler
  --without-CXX           prevent building C++ code 
   </programlisting>
  </para>
  <para>
   Some systems may have trouble building a specific feature of
   <productname>Postgres</productname>. For example, systems with a damaged
   C++ compiler may need to specify <option>--without-CXX</option> to instruct
   the build procedure to skip construction of <filename>libpq++</filename>.
  </para>
  <para>
   Use the <option>--with-includes</option> and
   <option>--with-libraries</option> options if you want to build
   <productname>Postgres</productname> using include files or libraries
   that are not installed in your system's standard search path.  For
   example, you might use these to build with an experimental version of
   Tcl.  If you need to specify more than one nonstandard directory for
   include files or libraries, do it like this:
   <programlisting>
   --with-includes="/opt/tcl/include /opt/perl5/include"
   </programlisting>
  </para>
  <para>
  </para>
 </sect1>
 <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>
  <para>
   In most cases, these parameters should be placed 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.
  </para>
  <para>
   Alternatively, you can set variables on the <application>make</application>
   command line:
   <synopsis>
    make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ]
   </synopsis>
  </para>
  <para>
   A few of the many variables which can be specified are:
   
   <variablelist>
    <varlistentry>
     <term>
      <envar>POSTGRESDIR</envar>
     </term>
     <listitem>
      <para>
       Top of the installation tree.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>BINDIR</envar>
     </term>
     <listitem>
      <para>
       Location of applications and utilities.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>LIBDIR</envar>
     </term>
     <listitem>
      <para>
       Location of object libraries, including shared libraries.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>HEADERDIR</envar>
     </term>
     <listitem>
      <para>
       Location of include files.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>ODBCINST</envar>
     </term>
     <listitem>
      <para>
       Location of installation-wide <application>psqlODBC</application>
       (<acronym>ODBC</acronym>) configuration file.
      </para>
     </listitem>
    </varlistentry>
    
   </variablelist>
  </para>
  <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>
     </term>
     <listitem>
      <para>
       Set flags for the C compiler. 
       Should be assigned with "+=" to retain relevant default parameters.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      YFLAGS
     </term>
     <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.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>USE_TCL</envar>
     </term>
     <listitem>
      <para>
       Enable Tcl interface building.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>HSTYLE</envar>
     </term>
     <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>.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <envar>PSTYLE</envar>
     </term>
     <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>.
      </para>
     </listitem>
    </varlistentry>
    
   </variablelist>
  </para>
  <para>
   Here is an example <filename>Makefile.custom</filename> for a
   PentiumPro Linux system:
   
   <programlisting>
# Makefile.custom
# Thomas Lockhart 1999-06-01

POSTGRESDIR= /opt/postgres/current
CFLAGS+= -m486 -O2

# documentation

HSTYLE= /home/tgl/SGML/db118.d/docbook/html
PSTYLE= /home/tgl/SGML/db118.d/docbook/print
   </programlisting>
  </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>