The OpenPGP Public Key Server (PKS)


* Dependencies

  PKS requires Berkeley DB 4.1.25 or higher.  If Berkeley DB 4 is
found in either /usr or /usr/local, it will be used by default.  If
Berkeley DB 4 is not installed system-wide or is installed in a
non-standard location, the --with-db option to the configure script
can be used to specify the location of the files to use.

  PKS requires OpenSSL.  The minimum version of OpenSSL is not known
at this time.  It is recommended that you use version 0.9.7b or
later.  If OpenSSL is found in either /usr or /usr/local, it will be
used by default.  If OpenSSL is not installed system-wide or is
installed in a non-standard location, the --with-opensll option to
the configure script can be used to specify the location of the
files to use.


* Building Berkeley DB 4.1.25 (OPTIONAL)

  Alternatively, if Berkeley DB 4 is only going to be used for PKS
on your system, you may find it easiest to statically link PKS with
the Berkeley code.  To do so, unpack the db archive into the same
directory as you unpacked the pks archive into.  Build db without
installing it.  One file, hmac/sha1.c, may trigger some optimizier
bugs in GCC.  (Turning off optimization for this file may help.)  The
following commands will probably work for you:

      cd db-4.1.25/build_unix
      ../dist/configure
      make
      cd ../..


* Building OpenSSL 0.9.7b (OPTIONAL)

  Alternatively, if OpenSSL is only going to be used for PKS on your
system, you may find it easiest to statically link PKS with the
OpenSSL code.  To do so, unpack the openssl archive into the same
directory as you unpacked the pks archive into.  Build OpenSSL
without installing it.  The following commands will probably work for
you:

      cd openssl-0.9.7b
      ./configure
      make
      cd ..


* Installation Choices

  Choose a location to install the software.  The software itself
takes up very little space.  As the keyserver will be running fairly
constantly, the code doesn't need to be installed on a local disk if
installing on a networked drive works better in your situation.  By
default, PKS is installed under /usr/local.  This directory can be
changed by the --prefix option to the configure script.  Throughout,
this directory will be referred to as PREFIX.

  However, the key database can grow very large. If you plan on
running with a full key database, you should have at least 5 GB free.
The database is accessed frequently in a fairly random pattern, so it
should be stored on a local disk.  By default, the database is
installed in PREFIX/var.  This directory can be changed by the
--localstatedir option ot the configure script.  Throughout, this
directory will be referred to as LOCALSTATEDIR.

  Several situations require the software to be installed as root.
To lessen the impact of a security breach, PKS supports dropping root
privileges when they are no longer needed.  Also, PKS supports
running in a chroot() jail.


* Building PKS

  In the top level of the PKS source directory run the following
commands.  These commands do not require root privileges.

      ./configure
      make

  The configure script accepts several options which can be used to
customize your installation of PKS.  To see a list of all available
options, run the following command in the top level of the PKS
source directory.

      ./configure --help

  Common options for configure include:

      --prefix=PREFIX         Install the software under PREFIX
      --localstatedir=DIR     Install the database under DIR

      --enable-debug          Enable Debugging Mode
      --enable-optimizations  Enable Compiler Optimizations

      --with-db=DIR           Use Berkeley DB in DIR
      --with-ipv6             Enable IPv6 Support
      --with-libwrap          Use libwrap (TCP Wrappers)
      --with-openssl=DIR      Use OpenSSL in DIR


  On some systems, you may have to use GNU make.  If the build
process fails, try using GNU make.


* Installing PKS

  In the top level of the PKS source directory run the following
command.  This command will probably require root privileges.

	make install

  You can look in PREFIX/man for more detailed documentation on the
various programs.  An overview is in pks-intro(8).


* Configuring PKS

   After installing pks, the necessary directory hierarchy will be
created, but there are some things you may need to do yourself.
Actions marked with [*] may be different for your operating system.

  Create an empty database as follows:
      cd /home/pksd
      ./bin/pksclient var/db create 1

  Import keys.  (Repeat for each KEYDUMP file.)
	./bin/pksclient var/db add /PATH/TO/KEYDUMP -dt
	./bin/pksclient var/db recover

  NOTE: A full keyring contains over 1.8 million keys.  Importing
such a large number of keys takes a long time (just under 3 days on
an idle machine), even with transactions turned off (using -dt flag
as specified above).  The following log snippets help to illustrate
this process:

      [Thu Feb 13 23:37:00 2003] kd_open: completed successfully
      [Thu Feb 13 23:37:00 2003] kd_add: flags=100000
      [Thu Feb 13 23:37:00 2003] display_new_key: new keyid 1 869B5F7C
      ...
      [Sun Feb 16 20:48:49 2003] display_new_key: new keyid 1801882 8A90ADBD
      [Sun Feb 16 20:48:50 2003] display_new_key: new keyid 1801883 C56B6758
      [Sun Feb 16 20:49:31 2003] kd_add: pub+1801883 sig+0 sig=0 uid+0 uid=0 rev+0 rev!0

  If you're planning on letting pksd setuid/setgid itself to a
special pksd uid and/or gid, create the appropriate user and group
and set the permissions as follows:

      groupadd pksd                                            [*]
      useradd -g pksd -d /home/pksd -s /sbin/nologin pksd      [*]
      chown -R pksd:pksd LOCALSTATEDIR/db LOCALSTATEDIR/incoming

  To run PKS inside a chroot() jail, you will need to add an
additional log socket inside the chroot dir.
	mkdir /PATH/TO/CHROOT/JAIL/dev
	kill `cat /var/run/syslogd.pid`
	syslogd -a /PATH/TO/CHROOT/JAIL/dev/log                [*]

  As a part of the installation, a template configuration file was
installed in PREFIX/etc/pksd.conf.  This file is fully documented in
pksd.conf(5).  PKS may not give you useful output unless you
configure the following options:

      www_readonly
      max_last
      max_last_reply_keys
      max_reply_keys

  The key server uses syslog for logging.  It logs using the local2
facility (if available), and various priority levels as described in
pksd(8).  If you want to get any logging, you should add an
appropriate entry to /etc/syslog.conf on your machine.

  If you have configured the mail server component of the key
server, there is one more step you need to take so that the server
can actually handle mail.  In your aliases file (usually one of
/etc/aliases or /etc/mail/aliases), create the following lines:

      pgp-public-keys: "|PREFIX/bin/pks-mail.sh PREFIX/etc/pksd.conf"
      pgp: pgp-public-keys

  You might also need to add aliases for the mail addresses you
configured in pksd.conf.  You will also need to make sure the
permissions on PREFIX/var/incoming allow both the mailer and whatever
user the pksd program runs as to insert and delete files.

  By default, PKS installs index.html into the configured
localstatedir (the location of the database).  The key server does
not server arbitrary files.  At most, it will serve this index.html
file.  Tranlated versions of this file are included in the source
distribution as pks-commands.html.XX, where XX is the ISO language
code of the translation.


* Running PKS

   Before running the server, read and familiarize yourself with the
information in the DATABASE ADMINISTRATION section of pks-intro(8)
(PREFIX/man/man8/pks-intro.8), in particular the section on
checkpointing.

  To have the daemon run when the system boots, you should run the
following commands in your /etc/rc.local or equivalent file:

      PREFIX/bin/pksd PREFIX/etc/pksd.conf
      sleep 5
      PREFIX/bin/pks-queue-run.sh PREFIX/etc/pksd.conf &

   You can always run this command by hand if you want.

  Alternatively, a System V style init script is provided in the
source distribution as pks.init.


* Obtaining Support

  Send an e-mail to pgp-keyserver-folk@flame.org.  This is a public
listserv dedicated to all keyserver issues, regardless of keyserver
software. As such, normal listserv etiquette is expected.  Be sure
to mention that you're running PKS and provide the version number.



$Id: README,v 1.8 2003/07/31 18:25:09 rlaager Exp $