	Installation instructions for Confusa

In this document, with user, we mean *you*, the person that downloads,
configures and installs Confusa on a server. From source.

You should have
- some experience with Apache-configuration
- basic knowledge about cryptography (i.e. what a certificate is, and
  how it's used) but not much more is required
- some, but not excessive, knowledge about PHP and bash-scripting, as
  this will help both *you* and *us* to track down bugs
- Some knowlegde about server administration
- an open and positive mind (for a more pleasent interaction with the
  world as a whole). This has nothing to do with Confusa

Installing Confusa

=== Requirements (shortlist): ===
 - git (for latest checkout of confusa source code). *not* required, but handy
 - svn (for latest simplesamlphp checkout). *not* required, but handy
 - Apache2
 - PHP5
 - PEAR with MDB2.MySQL
 - Smarty (the PHP template engine)
 - openssl

=== Install process ===
0) Using UvT's apt repository. If you choose this, move to step 4 when
   you have completed step 0.

   a) Add to /etc/apt/sources.list

     deb http://non-gnu.uvt.nl/debian lenny uvt simplesamlphp confusa
     deb-src http://non-gnu.uvt.nl/debian lenny uvt simplesamlphp confusa

  b) update apt (apt-get update)

  c) apt-get install confusa

1) Webserver (apache)

     apache2

2) Database (MySQL)

   We're not that strict with the MySQL version, older version will
   probably work, but as a general rule of thumb, you should always pick
   the most up-to-date version

     mysql-server-5.x
     mysql-client-5.x (you need this for bootstrapping the tables)

3) PHP

     libapache2-mod-php5
     php5-mysql
     libphp-phpmailer
     php-pear (PEAR::MDB2_mysql_driver (note: pear and MDB2_Mysql_Driver is
		     available through the backports, but we
		     refrain from using this here)
	       pear install MDB2_Driver_mysql

    smarty (*not* smarty-gettext)

3 a) When using Comodo, you will also need the mcrypt and curl libraries:

     php5-mcrypt
     php5-curl

3 b)
     Then, to make sure that the uploaded keys are not vulnerable, you
     will need the blacklist-package:

     openssl-blacklist


4) Configure Apache to use SSL, use the following lines in your
   apache2/sites-enabled/appropriate.config.file and php5-openssl
   (you will have to add Confsua-specific settings, see 6b for
   details).

   # Redirect http to https
   <VirtualHost your.host.org:80>
           Servername your.server.org
           Redirect permanent / https://your.host.org/
   </VirtualHost>

   <VirtualHost your.host.org:443>
           Servername your.server.org
           SSLEngine On
           SSLProtocol All -SSLv2
           SSLCipherSuite ALL:!ADH:!EXPORT56:!EXPORT40:RC4+RSA:!SSLv2:+HIGH:+MEDIUM:+LOW:+EXP
           SSLOptions +StdEnvVars +ExportCertData
           SSLCertificateFile /etc/apache2/ssl/your_host.crt
           SSLCertificateKeyFile /etc/apache2/ssl/your_host.key
	   ...
	   Alias /confusa "/var/www/confusa/www/"
	   <Directory /var/www/confusa/www/>
	        SSLVerifyClient optional_no_ca
		SSLVerifyDepth 10
		Order allow,deny
		deny from all
		allow from localhost 127.0.0.0/255.0.0.0 ::/128
	   </Directory>
   </VirtualHost>

   Set Apache to listen on port 443 as well in /etc/apache2/ports.conf

   Load ssl-mod:

	a2enmod ssl

   This is a *sample* configuration. If you know your way around an Apache
   configuration, this should be more of a guideline than anything else.

5) simpleSAMLphp
   Confusa uses simpleSAMLphp to handle AuthN, and thus, you should
   configure simpleSAMLphp before venturing on.

   http://simplesamlphp.org/docs

   Contains excellent guides on how to configure simpelSAMLphp, and is
   *required* reading.

   If you want to use Confusa's IdP-discovery functionality, you must
   configure Confusa's IdP-disco implementation  E.g. add/edit
   the following line to <simplesamlphp-dir>/config/authsources.php:

   'default-sp' => array(
                         'saml:SP',
                         'discoURL' => 'https://beta.confusa.org/confusa/idpselect.php',
                         /* fill in other values found via the documentation */
    ),

    If you are using Confusa 0.7 and the associated IdP-disco and want to use
    simplesamlphp 1.6, you *need to* apply the patch included in the
    simplesamlphp16 directory in Confusa to simplesamlphp. The README in the
    same directory explains the reasons.


6) Install and configure Confusa

   a) Put Confusa in a directory, say /var/www/confusa/

   b) Configure Apache with something along the following line:

      For the normal webservice:

             Alias /confusa "/var/www/confusa/www/"
	     Alias /simplesaml "/var/www/simplesamlphp/www/"
             <Directory /var/www/confusa/www>
                        Options Indexes MultiViews
                        AllowOverride None
                        Order allow,deny
                        Allow from all
             </Directory>

   Then reload apache:

	/etc/init.d/apache2 reload (or httpd (or

c) Configure the confusa_config.php file (copy the
   confusa_config_template.php and modify with values that makes sense
   to you - the template explaines the attributes).

   Also; the templates will look for 2 directories for compiles
   templates and smarty-cache. You need to create these and give them to
   the webserver-user (www-data in most cases):

       mkdir -p /var/cache/confusa/templates_c/
       mkdir -p /var/cache/confusa/smarty_cache/
       chown -R www-data:www-data /var/cache/confusa/templates_c/
       chown -R www-data:www-data /var/cache/confusa/smarty_cache/
       chmod 0700 /var/cache/confusa/templates_c/
       chmod 0700 /var/cache/confusa/smarty_cache/

d) Run the create_database.sh script in the confusa/bin/ folder
   This will create the database, the user and the tables. it will use
   the confusa_config.php file, so make sure that this is configured
   properly before you run this script.

e) Add a cron-job of the following type:
   */5 *   * * * /var/www/confusa/programs/clean_db.sh

   This will run the clean_db script every 5 minutes and keep the
   database nice and tidy.

f) Add a cron-job that takes backup of the database. The most critical
   part is the certificate hash part.
   A sample script lies in confusa/programs. Note that this is a simple
   mysqldump script that dumps the database specified in confusa_config

7) If you want NREN-admins to be able to customize the appearance of
   Confusa, you have to give the apache user write permissions to the
   "custom" folders:

	- www/css
	- www/graphics.

   The apache user is often called 'www-data', sometimes also 'apache2'
   or something else.  If you are unsure about the username and have
   apache running, try to find it out by executing

	ps aux | grep -e "apache" -e "http" | awk '{print $1}'

   If your apache username is www-data, execute

   chown -R www-data /usr/share/confusa/www/css/custom
   chown -R www-data /usr/share/confusa/www/graphics/custom
   chmod -R 0755 /usr/share/confusa/www/css/custom
   chmod -R 0755 /usr/share/confusa/www/graphics/custom

8) Test and verify that the system is operational before you allow
   public access.

=== Optional ===

9*) Enable OAuth authorization for third party applications. OAuth has
    the advantage that Confusa-based non-browser applications won't need
    to maintain cookies any more and that it protects against replay
    attacks. Simplesamlphp supports OAuth in more recent versions.

    Another application for OAuth is the planned server-to-server
    backend communication channel. Since we are dealing with
    user-credentials, it is important that this channels is
    - secure
    - short lived
    - approved by the user

    In order to enable OAuth in Confusa, it must first be enabled in
    simplesamlphp.

    touch <simplesaml-dir>/modules/oauth/enable

    OAuth uses the SAML2 AuthN module for the authentication
    phase. This should have been done at step 5.

    OAuth may oblige you to create a directory /tmp/oauth with write
    permissions for the webserver-process, which it will use as a token
    store.

10*) Enable tests

    Confusa comes bundled with a test-suite and you can enable this via apache if you are so inclined.

             Alias /confusa_test "/var/www/confusa/tests"
             <Directory /var/www/confusa/tests/>
                        Options Indexes MultiViews
                        AllowOverride None
                        Order deny,allow
                        Deny from all
			Allow from localhost 127.0.0.0/255.0.0.0 ::/128
             </Directory>

    You can also run the tests from the commandline:

       cd /var/www/confusa/tests && php -f all_tests.php

    This should print a short summary of the tests and whether or not they passed.
