Requirements posed upon the user:

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

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 and virtual machine management.
- an open and positive mind (for a more pleasent interaction with the
  world as a whole). This has nothing to do with Confusa

To install Confusa

=== Requirements: ===
 - 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)
     mysql-server-5.0
     mysql-client-5.0 (you need this for bootstrapping the tables)

3) PHP

     libapache2-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)
    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/disco/idpdisco.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).

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.
