.. _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]_ This setup was run successfully on RedHat Enterprise Linux 6.2, 6.3 and CentOS 6. 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:: 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:: 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:: cd /opt/LINOTP source bin/activate 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:: 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 LSE customer portal. If you prefer to install a manually downloaded linotp package you may as well issue a command ``pip install linotp-.tar.gz``. If you want to enroll tokens via QR Code like the Google Authenticator you need to either install:: pip install pil Or on newer distributions you should install:: 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:: 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:: pip install pysqlite pip install psycopg2 pip install MySQL-python If you want to use SMS-Tokens you need to install the SMSProvider package:: pip install SMSProvider 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:: 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:: 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:: sqlalchemy.url = mysql://linotp:mySecret@localhost/L2demo You probably got no encryption key, yet. So generate a new encryption key:: dd if=/dev/urandom of=/etc/linotp2/encKey bs=1 count=96 .. note:: You can use the tool ``linotp-create-enckey -f `` to create the encryption key. Create the LinOTP log directory:: mkdir /var/log/linotp Now you can create the database tables:: 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 -u ``. You can test this setup easily as described in :ref:`testing_server`. .. _apache_webserver: LinOTP and the Apache webserver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ More information about setting up LinOTP with Apache2 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:: 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**:: mkdir /var/run/wsgi Now we can configure the apache server. Things get easier, when we create an authentication file ``/etc/[httpd|apache2]/linotp-auth.conf``, that can be included when need:: AuthType Digest AuthName “LinOTP2 admin area” AuthDigestProvider file AuthUserFile /etc/linotp2/admins Require valid-user The configuration for your LinOTP site whether you configure it in httpd.conf directly or in an sites-enabled directory should contain the following. You might need to adapt directory names:: Listen 443 WSGIPythonHome /opt/LINOTP WSGISocketPrefix /var/run/wsgi ServerAdmin webmaster@localhost DocumentRoot /var/www Options FollowSymLinks AllowOverride None Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all Alias /doc/html /usr/share/doc/linotpdoc/html WSGIScriptAlias / /etc/linotp2/linotpapp.wsgi # # The daemon is running as user 'linotp' # This user should have access to the encKey database encryption file WSGIDaemonProcess linotp processes=1 threads=15 display-name=%{GROUP} user=linotp WSGIProcessGroup linotp WSGIPassAuthorization On Include /etc/httpd/linotp-auth.conf Include /etc/httpd/linotp-auth.conf AuthType Digest AuthName "LinOTP2 gettoken" AuthDigestProvider file AuthUserFile /etc/linotp2/gettoken-api Require valid-user Include /etc/httpd/linotp-auth.conf # The authentication for selfservice is done from within the application Include /etc/httpd/linotp-auth.conf Include /etc/httpd/linotp-auth.conf # No Authentication ErrorLog /var/log/httpd/error.log LogLevel warn # Do not use %q! This will reveal all parameters, including setting PINs and Keys! # Using SSL_CLIENT_S_DN_CN will show you, which administrator did what task LogFormat "%h %l %u %t %>s \"%m %U %H\" %b \"%{Referer}i\" \"%{User-agent}i\" " LinOTP2 CustomLog /var/log/httpd/ssl_access.log LinOTP2 # SSL Engine Switch: # Enable/Disable SSL for this virtual host. SSLEngine on # If both key and certificate are stored in the same file, only the # SSLCertificateFile directive is needed. SSLCertificateFile /etc/ssl/certs/linotpserver.pem SSLCertificateKeyFile /etc/ssl/private/linotpserver.key SSLOptions +StdEnvVars SSLOptions +StdEnvVars BrowserMatch ".*MSIE.*" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 ErrorDocument 500 "

Internal Server Error

Possible reasons can be missing modules or bad access rights \ on LinOTP configuration files or log files. Please check the apache logfile \ 
/var/log/httpd/error_log
for more details." .. note:: On RHEL and CentOS ``mod_ssl`` comes with a file ``/etc/httpd/conf.d/ssl.conf`` that already contains a VirtualHost definition. You also can adapts this accordingly. .. note:: The example uses the SSL certificate linotpserver.pem. If you do not have a certificate authority that provides you the certificate, you might create a self signed test certificate as described in :ref:`creating_ssl_certs`. The WSGI daemon process will run as the user `linotp`. So you should have a system account or otherwise create it:: adduser -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 -u linotp``. You should now be able to restart the apache and login to the management web UI via ``https:///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:: 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:: paster serve /etc/linotp2/linotp.ini LinOTP will now listen on the port you configured in the ``linotp.ini`` file. If you configured Apache2 to serve LinOTP you just need to assure, that the apache server is started. Point your browser to ``http://: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_webserver` 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:: 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!