.. _db_redhat:

Running LinOTP with DB2 on RedHat
---------------------------------

This describes how to setup LinOTP with a connection to a DB2 database on a RedHat system.
On other distributions this may vary.

Overview
~~~~~~~~~~~~

You need to adapt the following config files:

 *  ``/etc/linotp2/linotp.ini``
 *  ``/etc/odbc.ini``
 *  ``/etc/odbcinst.ini``
 *  ``db2cli.ini`` or ``db2dsdriver.cfg``

You need to install the following packages:

 * dsdriver (out of the scope of this document)
 * unixODBC
 * ibm_db_sa_linotp (shipped by KeyIdentity)
 * pyODBC
 * LinOTP (shipped by KeyIdentity)
 
Installation
~~~~~~~~~~~~

Install unixODBC
................
You need to install unixODBC and the devel package as some parts of the python module pyODBC need to get compiled::

   yum install unixODBC unixODBC-devel gcc-c++

Install pyODBC
................
Given you installed LinOTP to a virtualenv like ``/opt/LinOTP``,  you now can install the ODBC python module::

   cd /opt/LINOTP
   source bin/activate
   pip install pyodbc

Install ibm_db_sa
.................
This is the extension for SQLAlchemy, so that SQLAlchemy is able to talk to DB2. You received this package from KeyIdentity.
To install in within the virtualenv issue the command::

   pip install /path/to/package/ibm_db_sa_linotp-0.2.2.tar.gz 

Install LinOTP
..............
Starting with version 2.5 LinOTP runs nicely with DB2. So install the latest LinOTP package::

   pip install --upgrade /path/to/package/LinOTP-*current-version*.tar.gz

Configuration
~~~~~~~~~~~~~

LinOTP
......

Adapt the config file ``/etc/linotp2/linotp.ini``::

   sqlalchemy.url = ibm_db_sa+pyodbc://linotp_db

"linotp_db" is an identifier you may choose to your flavor. This identifier references the configuration in the
following config files.

If you want to use the SQLAudit module, you can add a corresponding line accordingly.
If the audit data is supposed to be located in another database, you would need to choose a second identifier like
"audit_db".

ODBC
....
You need to tell ODBC that it is also capable of talking to DB2 databases. You can do this by adding the following
to the file ``/etc/odbcinst.ini``::

   [DB2]
   Description = DB2 ODBC driver
   Driver      = /usr/local/dsdriver/lib/libdb2.so

Now you can define a new database connection by adding an entry to the file ``/etc/odbc.ini`` with the corresponding
identifier from the ``linotp.ini`` file::

   [linotp_db]
   Driver=DB2
   Description=My LinOTP Database connection

DB2
...

Now you can define the connection to the database by editing the file ``db2dsdriver.cfg``.
This file can be located in a system wide directory or in the home directory of the LinOTP user which runs the LinOTP
wsgi process.

The file might look like this::

   <configuration>
      <dsncollection>
         <dsn alias="linotp_db" name="lotp22" host="172.16.200.148" port="50000">
            <parameter name="CommProtocol" value="TCPIP"/>
            <parameter name="LobAsLongDataMode" value="1" />    
            <parameter name="UserID" value="db2inst4" />
            <parameter name="Password" value="test123!" />
         </dsn>
      </dsncollection>
   </configuration>

.. note:: The `name` and the `alias` in the DSN configuration should be different. Otherwise you may experience
          problems (missing password) when connecting to the database.

Within this file you can also define a redundant database access.

To test the connection run::

   isql linotp_db

.. note:: If you defined the connection in the home directory of the LinOTP user, then you need to run the command as
          the LinOTP user.

.. note:: For more information on the ``db2bsdriver.cfg`` file see the IBM documentation like [#db2_dsdriver]_.

Create the database tables
..........................
.. note:: Please assure the following prerequisites: 

   * The database and the user for this database who has the right to create tables are already created.
   * The database needs to be created with code page "UTF-8".
   * You also need to create a temporary table space.
   * The minimum pagesize needs to be 16384.

Now you can create the database tables by issuing the command::

   paster setup-app /etc/linotp2/linotp.ini

.. [#db2_dsdriver] http://publib.boulder.ibm.com/infocenter/db2luw/v9r5/index.jsp?topic=/com.ibm.swg.im.dbclient.config.doc/doc/r0054557.html