.. _pip_install:

LinOTP Server Installation – the tar.gz, virtualenv and pip way
---------------------------------------------------------------

LinOTP can also run on many other distributions using the virtualenv for python.
"virtualenv is a tool to create isolated python environments." [#virtualenv]_
Currently, LinOTP has dependencies that require python 2.7.

This setup was run successfully on RedHat Enterprise Linux 7 and CentOS 7.
But due to the isolated environment it could run an many other distributions.

First you need to create a directory where the whole LinOTP installation will
be located. We choose ``/opt/LINOTP``. You might need to download the
virtualenv tool here [#virtualenv_download]_

If you activated the EPEL repository [#epel]_ you may simply install the
package:

.. code:: bash

 yum install python-virtualenv

.. [#virtualenv] http://www.virtualenv.org
.. [#virtualenv_download] http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.7.1.2.tar.gz#md5=3be8a014c27340f48b56465f9109d9fa
.. [#epel] https://fedoraproject.org/wiki/EPEL

|

Create the virtualenv:

.. code:: bash

 mkdir -p /opt/LINOTP
 virtualenv --no-site-packages /opt/LINOTP

This will create an environment that does not use any python packages of your
base linux installation.

Now enter this virtual environment:

.. code:: bash

 cd /opt/LINOTP
 source bin/activate

.. note:: You should update your pip before you proceed:

.. code:: bash

 pip install --upgrade pip pip-tools

In fact this virtual environment is just a rewriting of several environment
variables.  You can leave this virtual environment any time by issuing the
command ``deactivate``.  To be able to install all packages to this virtual
environment you first need to install the following packages in your
distribution using the required tool like apt-get, yum or yast...

  * python-dev or python-devel
  * swig
  * gcc
  * libssl-dev or openssl-devel
  * openldap-dev, libldap2-dev or openldap-devel
  * mysql-server and libmysqlclient-dev or mysql-devel if you want to use mysql as token database
  * On Ubuntu 13.10 (possibly other OS's) you need to install libsasl2-dev as well

Depending on your distribution the names may vary.

Now we are going to install all LinOTP stuff:

.. code:: bash

 pip install linotp

...will install the LinOTP base packages with the base useridresolver from the
python package index pypi.python.org. This public package index holds the same
packages online as you might download from the KeyIdentity customer portal. If
you prefer to install a manually downloaded linotp package you may as well
issue a command ``pip install linotp-<current-version>.tar.gz``.

If you want to enroll tokens via QR Code like the Google Authenticator you need
to either install:

.. code:: bash

 pip install pil

Or on newer distributions you should install:

.. code:: bash

 pip install pillow
 pip install pillow-pil

pillow-pil may fail to install since as of April 2014 there only is an unstable
version available. If you want to install it anyway use the ``--pre`` option
for pip.

If you want to use the Audit module, you need to install:

.. code:: bash

 pip install m2crypto

On some distributions (known with Ubuntu) m2crypto may fail to install. Then
you can install python-m2crypto in your distribution and copy the corresponding
files to ``/opt/LINOTP/lib/python2.7/site-packages``.

To configure and activate the audit trail see Audit Trail :ref:`audit_trail_config`.

Depending on where you want to store your token database you need to install
database packages:

.. code:: bash

 pip install pysqlite
 pip install psycopg2
 pip install MySQL-python

If you want to use SMS-Tokens you need to install the SMSProvider package:

.. code:: bash

 pip install SMSProvider

You should update your pip environment with the help of the script
``linotp-pip-update``:

.. code:: bash

 linotp-pip-update

At this very moment you got a full working LinOTP. To check which packages are
installed in your virtual environment you can issue the command:

.. code:: bash

 pip freeze

.. note:: In this example we assume that you copy all config files to
 ``/etc/linotp2/``. You could also use the directory ``/opt/LINOTP/etc/linotp2``
 where some example files already exist. On some systems you may find the files
 under /usr/etc/linotp2/.


.. warning:: The pip installation does not update itself automatically. LinOTP
 comes with a helper script ``linotp-pip-update`` which you can run to update
 your virtualenv. Of course you first need to enter the virtualenv before you
 can run the script.

.. _setup_token_database:

Setup token database
~~~~~~~~~~~~~~~~~~~~

You need to create the database, where the token information will be stored.
This database can also be on a remote database server.

If you e.g. want to use mysql you could do it like this:

.. code:: bash

 mysql -u root -p mysql
 create database L2demo;
 grant all privileges on L2demo.* to 'linotp'@'localhost' identified by 'mySecret';
 flush privileges;
 quit;

.. note:: The linotp package came with a config file ``/etc/linotp2/linotp.ini.example``.
 You need to copy this file to your preferred location like ``/etc/linotp2/linotp.ini``.

Change the following line accordingly:

.. code:: bash

 sqlalchemy.url = mysql://linotp:mySecret@localhost/L2demo

You probably got no encryption key yet. So generate a new encryption key:

.. code:: bash

 dd if=/dev/urandom of=/etc/linotp2/encKey bs=1 count=96

.. note:: You can use the tool ``linotp-create-enckey -f <linotp.ini file>`` to
 create the encryption key.

Create the LinOTP log directory:

.. code:: bash

 mkdir /var/log/linotp

Now you can create the database tables:

.. code:: bash

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

Check the ownership of the files

 * ``/etc/linotp2/encKey`` (only readable for owner)
 * ``/etc/linotp2/token.db`` (if used)
 * ``/var/log/linotp/`` and ``/var/log/linotp/linotp.log``.

These files should be owned by the service account ``linotp``.

.. note:: You can fix ownership and access rights using the tool
 ``linotp-fix-access-rights -f <linotp.ini file> -u <linotp user>``.

You can test this setup easily as described in :ref:`testing_server`.

.. _apache_web_server:

LinOTP and the Apache web server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

More information about setting up LinOTP with an Apache web server can be found
in section :ref:`apache_configuration`.

The configuration depends on the distribution you are using. Debian based
distributions split up the configuration in many different files for each site
while RedHat based distributions use one big ``httpd.conf`` file.

With Apache we want to use authentication to the management web UI. For
starters we choose to do digest authentication and create a file accordingly:

.. code:: bash

 htdigest /etc/linotp2/admins "LinOTP2 admin area" admin

The following modules need to be installed and activated:

 * mod_wsgi
 * mod_ssl


.. note:: On systems using SELinux like RedHat 6 you need to deactivate SELinux
 to get LinOTP up and running. You may activate and reconfigure SELinux later
 on. In ``/etc/sysconfig/selinux`` set ``permissive`` and reboot the machine.

.. index:: Service Temporarily Unavailable

On RedHat 6 based systems you need to create a directory, otherwise the WSGI
module will fail with **Service Temporarily Unavailable**:

.. code:: bash

 mkdir /var/run/wsgi

Now we can configure the Apache web server. LinOTP provides an example
configuration file, ``linotp2.conf``, for a server based on Debian GNU/Linux.
It can be adapted to suit your distribution. See :ref:`apache_configuration` for
a detailed explanation of the configuration.

The WSGI daemon process is configured to run as the user `linotp`. So you
should have a matching system account or otherwise create it:

.. code:: bash

 useradd -r linotp -d /opt/LINOTP


Copy the ``linotpapp.wsgi`` file from the local ``etc`` directory in your virtualenv
to ``/etc/linotp2`` or adapt the ``WSGIScriptAlias`` in the Apache
configuration accordingly.

Check the permissions of the files

   * ``/etc/linotp2/linotp.ini`` - ``linotp`` should have read access
   * ``/etc/linotp2/encKey`` - ``linotp`` should have read access
   * ``/etc/linotp2/data/`` - This is a template directory, ``linotp`` should have write access
   * ``/var/log/linotp/`` - ``linotp`` should have write access

.. note:: You can add the user ``linotp`` and fix the access rights using the tool ``linotp-fix-access-rights -f <linotp.ini file> -u linotp``.

You should now be able to restart the Apache web server and login to the management web UI
via ``https://<yourserver>/manage``.

Further changes for RedHat and CentOS 6
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You might want to adapt your firewall configuration in
``/etc/sysconfig/iptables`` to allow port 443 to be accessed.

Moreover you should verify, that your services ``httpd`` and ``mysqld`` (if you
are using MySQL) are running after a reboot:

.. code:: bash

 chkconfig mysqld on
 chkconfig httpd on


.. _testing_server:

Testing LinOTP Server installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You are now ready to go. You might now want to start LinOTP temporarily from
the command line:

.. code:: bash

 paster serve /etc/linotp2/linotp.ini

LinOTP will now listen on the port you configured in the ``linotp.ini`` file.

If you have configured Apache to serve LinOTP, you just need to ensure that the
Apache web server is started. Point your browser to
``http://<yourserverIP>:5001/manage`` and you will get the Management
Interface.

.. warning:: In the case of using paster serve, there is no authentication and
 encryption while talking to the LinOTP server. You should use this only for
 testing purposes! Please read the section :ref:`apache_web_server` and
 :ref:`apache_configuration` on how to setup encryption and authentication.

.. _creating_ssl_certs:

Creating self signed SSL certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For testing purposes you can create a self signed certificate like this:

.. code:: bash

 openssl req -new -x509 -key /etc/ssl/private/linotpserver.key \
         -out /etc/ssl/certs/linotpserver.pem -days 365

You should adapt the access rights of the private key!