IMP Database Installation Guide                                docs/DATABASE
=--------------------------------------------------------------------------=

$Author: jon $
$Revision: 1.1.2.2 $
$Date: 2000/01/13 06:08:20 $

Purpose of this file
~~~~~~~~~~~~~~~~~~~~
This file will hopefully ease the installation and configuration of your
database for use with IMP.  The scope of the document deals primarily with
using your database with IMP and should not be considered a resource for
general database tasks.

Requirements for IMP 
~~~~~~~~~~~~~~~~~~~~
IMP Currently supports 4 databases:

    - MySQL         http://www.mysql.com/
    - PostgreSQL    http://www.postgresql.org/
    - Oracle        http://www.oracle.com/
    - Sybase        http://www.sybase.com/
    - Informix      http://www.informix.com/

MySQL was the original database supported by IMP and should at all times
(most likely) work for sure.  PostgreSQL I can verify works like a champ.
The others are more recent additions or those that have less support
currently.  For this reason (and the reason that I cannot verify personally
that they work or have ever configured them) they won't be mentioned much in
this file.  No one using Informix has contacted us for a while, but Oracle
and Sybase are both currently used and should work.

You will need to have your database preconfigured and working on your system
before you even get to this stage.  For help with this, please consult your
database specific help files.

Methods of Installation
~~~~~~~~~~~~~~~~~~~~~~~
There are 2 basic methods for configuring your database.  The first is
manually doing it yourself.  This is the method that will make sure that
things are setup as you can see step by step that things are being
configured properly.

The other method is to use one of the scripts that have been created to
automatically configure your database.  These scripts should work but there
are times when things may not work the way they are supposed to.  Also, when
using scripts you need to be aware that they may not be setup exactly for
your system so you need to verify them to make sure things are correct for
your particular install before using them.

Method 1: Manual Install
~~~~~~~~~~~~~~~~~~~~~~~~
For the 2.2.0 version of IMP you will need to setup 2 tables.  Here is a
breakdown of the tables and their elements:

Table 1:

   imp_pref (
       user         text
       sig          text
       fullname     text
       replyto      text
       lang         varchar(30) 
   )

   imp_addr (
       user         text
       address      text
       nickname     text
       fullname     text
   )

The database name itself should be "horde".  It should already have been
created when you installed the Horde module.


 *** Skip This piece if you already setup your user for HORDE ***

Next, you'll need to create a user or give a user access to this database.
This user will need pretty much full control over this database.  The
username we use for the most part is 'impmgr', or, in the case of
PostgreSQL, it's the name of the user who runs your web server (nobody on
most systems, www-data on stock Debian systems).  Here are a few
configuration tips for MySQL and PostgreSQL:

MySQL:

INSERT INTO user ( host, user, password )
   VALUES (
      'localhost',
      'hordemgr',
      password( 'hordemgr' )
      );

INSERT INTO db (
      host, db, user,
         Select_priv, Insert_priv, Update_priv, Delete_priv,
         Create_priv, Drop_priv )
      VALUES (
      'localhost',
      'horde',
      'hordemgr',
      'Y', 'Y', 'Y', 'Y',
      'Y', 'Y'
        );

This will setup a user named 'hordemgr' with password 'hordemgr'.  The user
has been given the necessary access rights to the 'horde' database.

After setting up your tables in MySQL, you will need to run this command:

     mysqladmin -u root -p reload

It is always a good idea to restart your MySQL process as well.
--

PostgreSQL:

GRANT SELECT, INSERT, UPDATE ON imp_pref, imp_addr TO nobody;

This will give the user 'nobody' access to these tables ('imp_pref' and
'imp_addr').  Note that with PostgreSQL you do not have to add a user to the
database because PostgreSQL uses a system account (the user who runs the web
server - 'nobody', in this case) as the form of authentication for the
database.

Also, you need to make sure you allow TCP connections to your database.
PostgreSQL has a switch in one of its configuration files ('postmaster.init',
or similar) that needs to be set to 'yes':

    PGALLOWTCPIP=yes

Without this set to 'yes', IMP won't be able to connect to your database,
and you'll thus receive tons of errors.

That's about it.  You should restart your database just to make sure
everything starts up the way it should.
--

Method 2: Scripted Install
~~~~~~~~~~~~~~~~~~~~~~~~~~

Note: The scripts are located in imp/config/scripts/.

The easier way of configuring your database is to use one of the scripts
that have been made available to you.  Here is a breakdown of how to use
each script:

MySQL:

MySQL's script is named 'mysql_create.sql'.  Use it by first logging into
an account that has full access to the database or by using a switch to
explicitly select one such user.  We'll demonstrate both methods below.

Before using any of these scripts, please look over them to ensure that any
system-specific settings (or personal choices) are set to your desired
settings (eg. 'username', etc.).

MySQL: 
------
# su - root

# mysql < mysql_create.sql
  - or -
# mysql -password=rootspasswordformysql < mysql_create.sql

Or, without changing to a priveliged user such as 'root':

% mysql -user=username < mysql_create.sql
  - or -
% mysql -user=username -password=rootspasswordformysql < mysql_create.sql

That's it.  Restart MySQL, and try it out.


PostgreSQL:
-----------
# su - postgres  (or whoever your database runs as... usually postgres)
# psql template1 < pgsql_create.sql

That's it.  Restart PostgreSQL, and try it out.


Oracle:
-------
Run 'sqlplus'.  Login, then run '@oracle_create.sql' (please note you may
not need the .sql at the end).

That should be it.  Restart Oracle just to be sure, and try it.


Sybase:
-------
First, you'll need to create the database.  From 'isql' run:

    create database horde

Next, you should (recommended) create a login to use with this database.
The 'isql' command for this is:

    sp_addlogin <username> <password>

Next you need to change the ownership of the database to this new user.  The
'isql' command for this is:

    sp_changedbowner <username>

After that, you just need to set up your tables within the database.  To do
that, just run this command from the command line:

    isql -i sybase_create.sql -U<username> -P<password>


Informix:
---------
Log into 'dbaccess' and run 'ifmx_create.sql'.

Restart Informix, and try it out.


Additional Notes
~~~~~~~~~~~~~~~~
This is by far no complete HOWTO.  This is just a compiled list of what
people have contributed so far.  If you have tips, ideas, suggestions or
anything else that you think could help others in setting up their database
for use with IMP, please let us know.
