Converted simpleSAMLphp installation doc to markdown

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1132 44740490-163a-0410-bde0-09ae8108e29a

docs/source/simplesamlphp-authproc.txt

@@ -7,6 +7,8 @@ Authentication Processing Filters in SimpleSAMLphp
 	http://daringfireball.net/projects/markdown/syntax
 -->
 
+  * Version: `$Id$`
+
 In SimpleSAMLphp, there is an API where you can *do stuff* at the IdP after authentication is complete, and just before you are sent back to the SP. The same API is available on the SP, after you have received a successfull Authentication Response from the IdP and before you are sent back to the SP application.
 
 Examples of neat things to do using Authentication Processing Filters:

docs/source/simplesamlphp-install.txt

+simpleSAMLphp Installation and Configuration
+============================================
+
+<!-- 
+	This file is written in Markdown syntax. 
+	For more information about how to use the Markdown syntax, read here:
+	http://daringfireball.net/projects/markdown/syntax
+-->
+
+  * Version: `$Id$`
+
+
+
+simpleSAMLphp documentation
+---------------------------
+
+This document is part of the simpleSAMLphp documentation suite.
+
+- [List of all simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
+
+This document is the first step.
+
+News about simpleSAMLphp
+------------------------
+
+To get the latest news about simpleSAMLphp you can follow this url:
+[http://rnd.feide.no/taxonomy/term/4](http://rnd.feide.no/taxonomy/term/4).
+It also conatins an RSS feed.
+
+Here is the simpleSAMLphp homepage:
+[http://rnd.feide.no/simplesamlphp](http://rnd.feide.no/simplesamlphp)
+
+
+Prerequisites
+-------------
+
+PHP version >= 5.1.2. If you want to run the *Shibboleth 1.3* part of simpleSAMLphp, you must have PHP >= 5.2.
+
+Apache or some other webserver that allows you to run PHP.
+
+simpleSAMLphp is has been tested most thoroughly on different Linux versions, Unix, and Mac OS X. It also runs on Windows, but at the time of writing, testing has been less thorough.
+
+
+Download and install simpleSAMLphp
+----------------------------------
+
+The most recent relase of simpleSAMLphp is found at
+[code.google.com/p/simplesamlphp/.](http://code.google.com/p/simplesamlphp/)
+To obtain a stable version, you may download the zipped
+`simplesamlphp` zip file listed under Featured Dowloads, or you may
+check out the last version includeing the most recent updates from
+the subversion repository.
+
+### Get a working copy of simpleSAMLphp from subversion
+
+Go to the directory where you want to install simpleSAMLphp:
+
+    cd /var
+
+Then do a subversion checkout:
+
+    svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp
+
+Using subversion, you can view logs and review changes to the
+files. To update the version you have checked out, enter:
+
+    cd /var/simplesamlphp
+    svn up
+
+## Upgrading from a previous version of simpleSAMLphp
+
+*If you have downloaded a version from the subversion repository:*
+
+Type, while located in the root folder of your simpleSAMLphp
+installation:
+
+    svn update
+
+*If you download and install the zipped version:*
+
+-   Make a backup of the `config` and the `metadata` directories.
+
+-   Delete all files from your current simpleSAMLphp directory .
+
+-   Unzip the new version in the simpleSAMLphp directory.
+
+-  
+    Install the backups of `config` and the `metadata` directories in
+    the simpleSAMLphp directory.
+
+
+If the format of the config files or metadata has changed from your
+previous version of simpleSAMLphp (check the revision log), you may
+have to update your configuration and metadata after updating the
+simpleSAMLphp code:
+
+### Upgrading configuration files
+
+A good approach is to run a `diff` between your preivous
+`config.php` file and the new `config.php` file located in
+`config-templates/config.php`, and apply relevant modifications to
+the new template. This will ensure that all new entries in the
+latest version of config.php are included, as well as preserve your
+local modifications.
+
+There is a link to a configuration check utility from the frontpage
+of your simpleSAMLphp installation page. The name of the link is
+"simpleSAMLphp configuration check". Then you will get a list of
+all configuration files in your `config/` directory. Click through
+the files, and you will get a report on superfluous and missing
+entries in the configuration file. What is done under the hood is
+that simpleSAMLphp looks up the `config-templates/` directory and
+compares to your real config. Although not all option is required
+to have in the configuration files, it's a good thumb rule to
+include them nontheless, so you simply see what configuration is
+possible.
+
+### Upgrading metadata files
+
+Most likely the metadata format is backwards compatible. If not,
+you should receive a very clear error message at startup indicating
+how and what you need to update. You should look through the
+metadata in the metadata-templates directory after the upgrade to
+see whether recommended defaults have been changed.
+
+
+
+
+Making configuration and metadata files
+---------------------------------------
+
+### Tip
+
+You do not need to read this section if you are upgrading
+simpleSAMLphp from an earlier version, then see
+[the section called “Upgrading from a previous version of simpleSAMLphp”](#sect.upgrading "Upgrading from a previous version of simpleSAMLphp").
+
+Configuration and metadata files are distributed as templates; you
+should make local copies to directories `config` and `metadata` and
+edit these copies to suit your local requirements. When you later
+upgrade, through a subversion `svn     up` command or by installing
+a new zip file, your existing configuration data will not not be
+overwritten.
+
+Here are the steps you need to do to create local configuration
+files:
+
+    cd /var/simplesamlphp
+    cp -r config-templates/*.php config/
+    cp -r metadata-templates/*.php metadata/
+
+
+
+Configuring Apache
+------------------
+
+Examples below assume that simpleSAMLphp is installed in the
+default location, `/var/simplesamlphp`. You may choose another
+location, but this requires a path update in a few files.
+[See Appendix A for details](#sect.altlocations "A. Installing simpleSAMLphp in alternative locations").
+
+The only subdirectories of `simpleSAMLphp` that needs to be
+accessible from the web is `www`. There are several ways of putting
+the simpleSAMLphp depending on the way web sites are structured on
+your apache web server. Here is what I believe is the best
+configuration.
+
+Find the Apache configuration file for the virtual hosts where you
+want to run simpleSAMLphp. The configuration may look like this:
+
+    <VirtualHost *>
+            ServerName service.example.com
+            DocumentRoot /var/www/service.example.com
+    
+            Alias /simplesaml /var/simplesamlphp/www
+    </VirtualHost>
+
+Note the `Alias` directive, which gives control to simpleSAMLphp
+for all urls matching `http(s)://service.example.com/simplesaml/*`.
+simpleSAMLphp makes several SAML interfaces available on the web;
+all of them are included in the `www` subdirectory of your
+simpleSAMLphp installation. You can name the alias whatever you
+want, but the name must be specified in the `config.php` file of
+simpleSAML as described in
+[the section called “simpleSAMLphp configuration: config.php”](#sect.config "simpleSAMLphp configuration: config.php").
+Here is an example of how this configuration may look like in
+`config.php`:h
+
+    $config = array (
+    [...]
+            'baseurlpath'                   => 'simplesaml/',
+
+simpleSAMLphp configuration: config.php
+---------------------------------------
+
+There is a few steps that you should edit in the main configuration
+file, `config.php`, right away:
+
+-  
+    Set a administrator password. This is needed to access some of the
+    pages in your simpleSAMLphp installation web interface.
+
+		'auth.adminpassword'        => 'setnewpasswordhere',
+
+-  
+    Set a secret salt. This should be a random string. Some parts of
+    the simpleSAMLphp needs this salt to generate cryptographically
+    secure hashes. SimpleSAMLphp will give an error if the salt is not
+    changed from the default value. The command below can help you to
+    generated a random string on (some) unix systems:
+
+		tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
+
+    Here is an example of the config option:
+
+		'secretsalt' => 'randombytesinsertedhere',
+
+-  
+    Set technical contact information. This information will be
+    available in the generated metadata. The e-mail address will also
+    be used for receiving error reports sent automatically by
+    simpleSAMLphp. Here is an example:
+
+		'technicalcontact_name'     => 'Andreas Åkre Solberg',
+		'technicalcontact_email'    => 'andreas.solberg@uninett.no',
+
+-  
+    If you use simpleSAMLphp in a country where english is not
+    widespread, you may want to change the default language from
+    english to something else:
+
+		'language.default'      => 'no',
+
+
+Configure PHP to be able to send e-mails
+----------------------------------------
+
+Some parts of simpleSAMLphp will allow you to send e-mails. In
+example sending error reports to technical admin, as well as
+sending in metadata to the federation administrators. If you want
+to make use of this functionality, you should make sure your PHP
+installation is configured to be able to send e-mails. It's a
+common problem that PHP is not configured to send e-mails properly.
+The configuration differs from system to system. On UNIX, PHP is
+using sendmail, on Windows SMTP.
+
+
+
+Enable modules
+--------------
+
+If you want to enable some of the modules that are installed with
+simpleSAMLphp, but are disabled by default, you should create an
+empty file in the module directory named `enable`.
+
+    # Enabling the consent module
+    cd modules
+    ls -l
+    cd consent
+    touch enable
+
+If you later want to disable the module, rename the `enable` file
+to `disable`.
+
+    cd modules/consent
+    mv enable disable
+
+
+
+The simpleSAMLphp installation webpage
+--------------------------------------
+
+After installing simpleSAMLphp, you can access the homepage of your
+installation, which contains some information and a few links to
+the test services. The url of an installation can be e.g.:
+
+https://service.example.org/simplesaml/
+
+The exact link depends on how you set it up with Apache, and off
+course on your hostname.
+
+### Warning
+
+Don't click on any of the links yet, because they require you to
+either have setup simpleSAMLphp as an Service Provider or as an
+Identity Provider.
+
+Here is an example screenshot of what the simpleSAMLphp page looks
+like:
+
+![Screenshot of the simpleSAMLphp installation page.](http://rnd.feide.no/doc/resources/simplesamlphp-install/screenshot-installationpage.png)
+
+### Check your PHP environment
+
+At the bottom of the installation page are some green lights.
+simpleSAML runs some tests to see whether required and recommended
+prerequisites are met. If any of the lights are red, you may have
+to add some extensions or modules to PHP, e.g. you need the PHP
+LDAP extension to use the LDAP authentication module.
+
+## Next steps
+
+You have now successfully installed simpleSAMLphp, and the next
+steps depends on whether you want to setup a service provider, to
+protect a website by authentication or if you want to setup an
+identity provider and connect it to a user catalog. Documentation
+on bridging between federation protocols is found in a separate
+document.
+
+-  
+    [Setting up simpleSAMLphp as a service provider](http://rnd.feide.no/content/using-simplesamlphp-service-provider)
+
+-  
+    [Setting up simpleSAMLphp as an identity provider](http://rnd.feide.no/content/using-simplesamlphp-identity-provider)
+
+-  
+    [Setting up simpleSAMLphp with Google Apps for Eduation](http://rnd.feide.no/content/simplesamlphp-idp-google-apps-education)
+
+-  
+    [Advanced simpleSAMLphp features](http://rnd.feide.no/content/simplesamlphp-advanced-features)
+
+-  
+    [simpleSAMLphp maintenance and configuration](http://rnd.feide.no/content/simplesamlphp-maintenance-and-configuration)
+
+
+Support
+-------
+
+If you need help to make this work, or want to discuss simpleSAMLphp with other users of the software, you are fortunate: Around simpleSAMLphp there is a great Open source community, and you are welcome to join! The forums are open for you to ask questions, contribute answers other further questions, request improvements or contribute with code or plugins of your own.
+
+-  [simpleSAMLphp homepage (at Feide RnD)](http://rnd.feide.no/simplesamlphp)
+-  [List of all available simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
+-  [Join the simpleSAMLphp user's mailing list](http://rnd.feide.no/content/simplesamlphp-users-mailinglist)
+-  [Visit and contribute to the simpleSAMLphp wiki](https://ow.feide.no/simplesamlphp:start)
+
+
+
+
+Installing simpleSAMLphp in alternative locations
+-------------------------------------------------
+
+There may be several reasons why you want to install simpleSAMLphp
+in an alternative way.
+
+1.	You are installing simpleSAMLphp in a hosted environment where you
+	do not have root access, and cannot change Apache configuration.
+	Still you can install simpleSAMLphp - keep on reading.
+
+2.	You have full permissions to the server, but cannot edit Apache
+	configuration for some reason, polictics, policy or whatever.
+
+
+The SimpleSAMLphp code contains one folder named `simplesamlphp`. In this folder there are a lot of subfolders for library, metadata, configuration and much more. One of these folders is named `www`. This and *only this* folder should be exposed on the web. The reccomended configuration is to put the whole `simplesamlphp` folder outside the webroot, and then link in the `www` folder by using the `Alias` directive, as described in [the section called “Configuring Apache”](#sect.apacheconfig "Configuring Apache"). But this is not the only possible way.
+
+As an example, let's see how you can install simpleSAMLphp in your home directory on a shosted server.
+
+Check out simpleSAMLphp in your home directory, and move or symlink the www folder into the `public_html` folder.
+
+    cd ~
+    svn checkout [snipp] simplesamlphp
+
+Then you can try to make a symlink into the public\_html
+directory.
+
+    cd ~/public_html
+    ln -s ../simplesamlphp/www simplesaml
+
+### Tip
+
+Symlinking may fail, because some apache configurations do not allow you to link in files from outside the public\_html folder. If so, move the folder instead of symlinking:
+
+    cd ~/public_html
+    mv ../simplesamlphp/www simplesaml
+
+Now you have the following directory structure.
+
+-   `~/simplesamlphp`
+
+-  
+    `~/public_html/simplesaml` where `simplesaml` is the `www`
+    directory from the `simplesamlphp` installation directory, either
+    moved or a symlink.
+
+
+Now, we need to make a few configuration changes. First, let's edit
+`~/public_html/simplesaml/_include.php`:
+
+Change the two lines from:
+
+    require_once(dirname(dirname(__FILE__)) . '/lib/_autoload.php');
+    $path_extra = dirname(dirname(__FILE__)) . '/lib';
+
+to something like:
+
+    require_once('/home/andreas/simplesamlphp/lib/_autoload.php');
+    $path_extra = '/home/andreas/simplesamlphp/lib';
+
+And then at the end of the file, you need to change another line
+from:
+
+    $configdir = dirname(dirname(__FILE__)) . '/config';
+
+to:
+
+    $configdir = '/home/andreas/simplesamlphp/config';
+
+
+
+### Note
+
+In a future version of simpleSAMLphp we'll make this a bit easier, and let you only change the path one place, instead of three as described above.
+
+Next, you need to update the configuration of paths in `simplesamlphp/config/config.php`:
+
+Set the `basedir` parameter to the path of your simplesamlphp folder:
+
+	'basedir' => '/home/andreas/simplesamlphp/',
+
+And, then we need to set the `baseurlpath` parameter to match the base path of the URLs to the content of your `www` folder:
+
+	'baseurlpath'           => '~andreas/simplesaml/',
+
+Now, you can go to the URL of your installation and check if things work:
+
+	http://yourcompany.com/~andreas/simplesaml/
+
+
+

docs/source/simplesamlphp-install.xml

-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<article>
-  <title>simpleSAMLphp Installation and Configuration</title>
-
-  <articleinfo>
-    <date>2007-08-30</date>
-
-    <pubdate>Sun Nov  2 14:45:21 2008</pubdate>
-
-    <author>
-      <firstname>Andreas Åkre</firstname>
-
-      <surname>Solberg</surname>
-
-      <email>andreas.solberg@uninett.no</email>
-    </author>
-  </articleinfo>
-
-  <section>
-    <title>simpleSAMLphp documentation</title>
-
-    <para>This document is part of the
-    <application>simpleSAMLphp</application> documentation suite.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
-        all <application>simpleSAMLphp</application>
-        documentation</ulink></para>
-      </listitem>
-    </itemizedlist>
-  </section>
-
-  <section>
-    <title>News about simpleSAMLphp</title>
-
-    <para>To get the latest news about
-    <application>simpleSAMLphp</application> you can follow this url: <ulink
-    url="http://rnd.feide.no/taxonomy/term/4">http://rnd.feide.no/taxonomy/term/4</ulink>.
-    It also conatins an RSS feed.</para>
-
-    <para>Here is the <application>simpleSAMLphp</application> homepage:
-    <ulink
-    url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
-  </section>
-
-  <section>
-    <title>Prerequisites</title>
-
-    <para><application>PHP</application> version &gt;= 5.1.2. If you want to
-    run the <emphasis>Shibboleth 1.3</emphasis> part of
-    <application>simpleSAMLphp</application>, you must have
-    <application>PHP</application> &gt;= 5.2.</para>
-
-    <para>Apache or some other webserver that allows you to run PHP.</para>
-
-    <para><application>simpleSAMLphp</application> is has been tested most
-    thoroughly on different Linux versions, Unix, and Mac OS X. It also runs
-    on Windows, but at the time of writing, testing has been less
-    thorough.</para>
-  </section>
-
-  <section>
-    <title>Download and install simpleSAMLphp</title>
-
-    <para>The most recent relase of <application>simpleSAMLphp</application>
-    is found at <ulink
-    url="http://code.google.com/p/simplesamlphp/">code.google.com/p/simplesamlphp/.</ulink>
-    To obtain a stable version, you may download the zipped
-    <filename>simplesamlphp</filename> zip file listed under Featured
-    Dowloads, or you may check out the last version includeing the most recent
-    updates from the subversion repository.</para>
-
-    <section>
-      <title>Get a working copy of simpleSAMLphp from subversion</title>
-
-      <para>Go to the directory where you want to install
-      <application>simpleSAMLphp</application>:</para>
-
-      <screen>cd /var</screen>
-
-      <para>Then do a subversion checkout:</para>
-
-      <screen>svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp</screen>
-
-      <para>Using subversion, you can view logs and review changes to the
-      files. To update the version you have checked out, enter:</para>
-
-      <screen>cd /var/simplesamlphp
-svn up</screen>
-    </section>
-  </section>
-
-  <section id="sect.upgrading">
-    <title>Upgrading from a previous version of
-    <application>simpleSAMLphp</application></title>
-
-    <para><emphasis>If you have downloaded a version from the subversion
-    repository:</emphasis></para>
-
-    <para>Type, while located in the root folder of your
-    <application>simpleSAMLphp</application> installation:</para>
-
-    <screen>svn update</screen>
-
-    <para><emphasis>If you download and install the zipped version:
-    </emphasis></para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para>Make a backup of the <filename>config</filename> and the
-          <filename>metadata</filename> directories.</para>
-        </listitem>
-
-        <listitem>
-          <para>Delete all files from your current simpleSAMLphp directory
-          .</para>
-        </listitem>
-
-        <listitem>
-          <para>Unzip the new version in the simpleSAMLphp directory.</para>
-        </listitem>
-
-        <listitem>
-          <para>Install the backups of <filename>config</filename> and the
-          <filename>metadata</filename> directories in the simpleSAMLphp
-          directory.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>If the format of the config files or metadata has changed from your
-    previous version of <application>simpleSAMLphp</application> (check the
-    revision log), you may have to update your configuration and metadata
-    after updating the <application>simpleSAMLphp</application> code:</para>
-
-    <section>
-      <title>Upgrading configuration files</title>
-
-      <para>A good approach is to run a <literal>diff</literal> between your
-      preivous <filename>config.php</filename> file and the new
-      <filename>config.php</filename> file located in
-      <filename>config-templates/config.php</filename>, and apply relevant
-      modifications to the new template. This will ensure that all new entries
-      in the latest version of config.php are included, as well as preserve
-      your local modifications.</para>
-
-      <para>There is a link to a configuration check utility from the
-      frontpage of your simpleSAMLphp installation page. The name of the link
-      is "simpleSAMLphp configuration check". Then you will get a list of all
-      configuration files in your <filename>config/</filename> directory.
-      Click through the files, and you will get a report on superfluous and
-      missing entries in the configuration file. What is done under the hood
-      is that simpleSAMLphp looks up the
-      <filename>config-templates/</filename> directory and compares to your
-      real config. Although not all option is required to have in the
-      configuration files, it's a good thumb rule to include them nontheless,
-      so you simply see what configuration is possible.</para>
-    </section>
-
-    <section>
-      <title>Upgrading metadata files</title>
-
-      <para>Most likely the metadata format is backwards compatible. If not,
-      you should receive a very clear error message at startup indicating how
-      and what you need to update. You should look through the metadata in the
-      metadata-templates directory after the upgrade to see whether
-      recommended defaults have been changed.</para>
-    </section>
-  </section>
-
-  <section>
-    <title>Making configuration and metadata files</title>
-
-    <tip>
-      <para>You do not need to read this section if you are upgrading
-      <application>simpleSAMLphp</application> from an earlier version, then
-      see <xref linkend="sect.upgrading" />.</para>
-    </tip>
-
-    <para>Configuration and metadata files are distributed as templates; you
-    should make local copies to directories <filename>config</filename> and
-    <filename>metadata</filename> and edit these copies to suit your local
-    requirements. When you later upgrade, through a subversion <literal>svn
-    up</literal> command or by installing a new zip file, your existing
-    configuration data will not not be overwritten.</para>
-
-    <para>Here are the steps you need to do to create local configuration
-    files:</para>
-
-    <screen>cd /var/simplesamlphp
-cp -r config-templates/*.php config/
-cp -r metadata-templates/*.php metadata/
-</screen>
-  </section>
-
-  <section id="sect.apacheconfig">
-    <title>Configuring Apache</title>
-
-    <para>Examples below assume that <application>simpleSAMLphp</application>
-    is installed in the default location,
-    <filename>/var/simplesamlphp</filename>. You may choose another location,
-    but this requires a path update in a few files. <link
-    linkend="sect.altlocations">See Appendix A for details</link>.</para>
-
-    <para>The only subdirectories of <filename>simpleSAMLphp</filename> that
-    needs to be accessible from the web is <filename>www</filename>. There are
-    several ways of putting the <application>simpleSAMLphp</application>
-    depending on the way web sites are structured on your apache web server.
-    Here is what I believe is the best configuration.</para>
-
-    <para>Find the Apache configuration file for the virtual hosts where you
-    want to run <application>simpleSAMLphp</application>. The configuration
-    may look like this:</para>
-
-    <programlisting>&lt;VirtualHost *&gt;
-        ServerName service.example.com
-        DocumentRoot /var/www/service.example.com
-
-        Alias /simplesaml /var/simplesamlphp/www
-&lt;/VirtualHost&gt;
-</programlisting>
-
-    <para>Note the <literal>Alias</literal> directive, which gives control to
-    <application>simpleSAMLphp</application> for all urls matching
-    <literal>http(s)://service.example.com/simplesaml/*</literal>.
-    <application>simpleSAMLphp</application> makes several SAML interfaces
-    available on the web; all of them are included in the
-    <filename>www</filename> subdirectory of your
-    <application>simpleSAMLphp</application> installation. You can name the
-    alias whatever you want, but the name must be specified in the
-    <filename>config.php</filename> file of simpleSAML as described in <xref
-    linkend="sect.config" />. Here is an example of how this configuration may
-    look like in <filename>config.php</filename>:h</para>
-
-    <programlisting>$config = array (
-[...]
-        'baseurlpath'                   =&gt; 'simplesaml/',</programlisting>
-  </section>
-
-  <section id="sect.config">
-    <title>simpleSAMLphp configuration: config.php</title>
-
-    <para>There is a few steps that you should edit in the main configuration
-    file, <filename>config.php</filename>, right away:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para>Set a administrator password. This is needed to access some of
-        the pages in your simpleSAMLphp installation web interface.</para>
-
-        <programlisting>	'auth.adminpassword'		=&gt; 'setnewpasswordhere',</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>Set a secret salt. This should be a random string. Some parts of
-        the simpleSAMLphp needs this salt to generate cryptographically secure
-        hashes. SimpleSAMLphp will give an error if the salt is not changed
-        from the default value. The command below can help you to generated a
-        random string on (some) unix systems:</para>
-
-        <programlisting>tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' &lt;/dev/urandom | dd bs=32 count=1 2&gt;/dev/null;echo</programlisting>
-
-        <para>Here is an example of the config option:</para>
-
-        <programlisting>	'secretsalt' =&gt; 'randombytesinsertedhere',</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>Set technical contact information. This information will be
-        available in the generated metadata. The e-mail address will also be
-        used for receiving error reports sent automatically by simpleSAMLphp.
-        Here is an example:</para>
-
-        <programlisting>	'technicalcontact_name'     =&gt; 'Andreas Åkre Solberg',
-	'technicalcontact_email'    =&gt; 'andreas.solberg@uninett.no',</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>If you use simpleSAMLphp in a country where english is not
-        widespread, you may want to change the default language from english
-        to something else:</para>
-
-        <programlisting>	'language.default'		=&gt; 'no',</programlisting>
-      </listitem>
-    </itemizedlist>
-  </section>
-
-  <section>
-    <title>Configure PHP to be able to send e-mails</title>
-
-    <para>Some parts of simpleSAMLphp will allow you to send e-mails. In
-    example sending error reports to technical admin, as well as sending in
-    metadata to the federation administrators. If you want to make use of this
-    functionality, you should make sure your PHP installation is configured to
-    be able to send e-mails. It's a common problem that PHP is not configured
-    to send e-mails properly. The configuration differs from system to system.
-    On UNIX, PHP is using sendmail, on Windows SMTP. </para>
-  </section>
-
-  <section>
-    <title>Enable modules</title>
-
-    <para>If you want to enable some of the modules that are installed with
-    simpleSAMLphp, but are disabled by default, you should create an empty
-    file in the module directory named <filename>enable</filename>.</para>
-
-    <programlisting># Enabling the consent module
-cd modules
-ls -l
-cd consent
-touch enable
-</programlisting>
-
-    <para>If you later want to disable the module, rename the
-    <filename>enable</filename> file to <filename>disable</filename>.</para>
-
-    <programlisting>cd modules/consent
-mv enable disable
-</programlisting>
-  </section>
-
-  <section>
-    <title>The simpleSAMLphp installation webpage</title>
-
-    <para>After installing <application>simpleSAMLphp</application>, you can
-    access the homepage of your installation, which contains some information
-    and a few links to the test services. The url of an installation can be
-    e.g.:</para>
-
-    <literallayout>https://service.example.com/simplesaml/</literallayout>
-
-    <para>The exact link depends on how you set it up with Apache, and off
-    course on your hostname.</para>
-
-    <warning>
-      <para>Don't click on any of the links yet, because they require you to
-      either have setup <application>simpleSAMLphp</application> as an Service
-      Provider or as an Identity Provider.</para>
-    </warning>
-
-    <para>Here is an example screenshot of what the
-    <application>simpleSAMLphp</application> page looks like:</para>
-
-    <figure>
-      <title>Screenshot of the simpleSAMLphp installation page.</title>
-
-      <screenshot>
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="resources/simplesamlphp-install/screenshot-installationpage.png" />
-          </imageobject>
-        </mediaobject>
-      </screenshot>
-    </figure>
-
-    <section>
-      <title>Check your PHP environment</title>
-
-      <para>At the bottom of the installation page are some green lights.
-      simpleSAML runs some tests to see whether required and recommended
-      prerequisites are met. If any of the lights are red, you may have to add
-      some extensions or modules to <application>PHP</application>, e.g. you
-      need the PHP LDAP extension to use the LDAP authentication
-      module.</para>
-    </section>
-  </section>
-
-  <section>
-    <title>Next steps</title>
-
-    <para>You have now successfully installed
-    <application>simpleSAMLphp</application>, and the next steps depends on
-    whether you want to setup a service provider, to protect a website by
-    authentication or if you want to setup an identity provider and connect it
-    to a user catalog. Documentation on bridging between federation protocols
-    is found in a separate document.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/using-simplesamlphp-service-provider">Setting
-        up simpleSAMLphp as a service provider</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/using-simplesamlphp-identity-provider">Setting
-        up simpleSAMLphp as an identity provider</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/simplesamlphp-idp-google-apps-education">Setting
-        up simpleSAMLphp with Google Apps for Eduation</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/simplesamlphp-advanced-features">Advanced
-        simpleSAMLphp features</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/simplesamlphp-maintenance-and-configuration">simpleSAMLphp
-        maintenance and configuration</ulink></para>
-      </listitem>
-    </itemizedlist>
-  </section>
-
-  <section>
-    <title>Support</title>
-
-    <para>If you need help to make this work, or want to discuss
-    <application>simpleSAMLphp</application> with other users of the software,
-    you are fortunate: Around <application>simpleSAMLphp</application> there
-    is a great Open source community, and you are welcome to join! The forums
-    are open for you to ask questions, contribute answers other further
-    questions, request improvements or contribute with code or plugins of your
-    own.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/simplesamlphp"><application>simpleSAMLphp</application>
-        homepage (at Feide RnD)</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
-        all available <application>simpleSAMLphp</application>
-        documentation</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink
-        url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
-        the <application>simpleSAMLphp</application> user's mailing
-        list</ulink></para>
-      </listitem>
-
-      <listitem>
-        <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
-        contribute to the <application>simpleSAMLphp</application>
-        wiki</ulink></para>
-      </listitem>
-    </itemizedlist>
-  </section>
-
-  <appendix id="sect.altlocations">
-    <title>Installing simpleSAMLphp in alternative locations</title>
-
-    <para>There may be several reasons why you want to install simpleSAMLphp
-    in an alternative way.</para>
-
-    <orderedlist>
-      <listitem>
-        <para>You are installing simpleSAMLphp in a hosted environment where
-        you do not have root access, and cannot change Apache configuration.
-        Still you can install simpleSAMLphp - keep on reading.</para>
-      </listitem>
-
-      <listitem>
-        <para>You have full permissions to the server, but cannot edit Apache
-        configuration for some reason, polictics, policy or whatever.</para>
-      </listitem>
-    </orderedlist>
-
-    <para>The SimpleSAMLphp code contains one folder named
-    <filename>simplesamlphp</filename>. In this folder there are a lot of
-    subfolders for library, metadata, configuration and much more. One of
-    these folders is named <filename>www</filename>. This and <emphasis>only
-    this</emphasis> folder should be exposed on the web. The reccomended
-    configuration is to put the whole <filename>simplesamlphp</filename>
-    folder outside the webroot, and then link in the <filename>www</filename>
-    folder by using the <literal>Alias</literal> directive, as described in
-    <xref linkend="sect.apacheconfig" />. But this is not the only possible
-    way.</para>
-
-    <para>As an example, let's see how you can install simpleSAMLphp in your
-    home directory on a shosted server.</para>
-
-    <para>Check out simpleSAMLphp in your home directory, and move or symlink
-    the www folder into the <filename>public_html</filename> folder.</para>
-
-    <screen>cd ~
-svn checkout [snipp] simplesamlphp
-</screen>
-
-    <para>Then you can try to make a symlink into the public_html
-    directory.</para>
-
-    <screen>cd ~/public_html
-ln -s ../simplesamlphp/www simplesaml
-</screen>
-
-    <tip>
-      <para>Symlinking may fail, because some apache configurations do not
-      allow you to link in files from outside the public_html folder. If so,
-      move the folder instead of symlinking:</para>
-
-      <screen>cd ~/public_html
-mv ../simplesamlphp/www simplesaml</screen>
-    </tip>
-
-    <para>Now you have the following directory structure.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><filename>~/simplesamlphp</filename></para>
-      </listitem>
-
-      <listitem>
-        <para><filename>~/public_html/simplesaml</filename> where
-        <filename>simplesaml</filename> is the <filename>www</filename>
-        directory from the <filename>simplesamlphp</filename> installation
-        directory, either moved or a symlink.</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>Now, we need to make a few configuration changes. First, let's edit
-    <filename>~/public_html/simplesaml/_include.php</filename>:</para>
-
-    <para>Change the two lines from:</para>
-
-    <programlisting>require_once(dirname(dirname(__FILE__)) . '/lib/_autoload.php');
-$path_extra = dirname(dirname(__FILE__)) . '/lib';</programlisting>
-
-    <para>to something like:</para>
-
-    <programlisting>require_once('/home/andreas/simplesamlphp/lib/_autoload.php');
-$path_extra = '/home/andreas/simplesamlphp/lib';</programlisting>
-
-    <para>And then at the end of the file, you need to change another line
-    from:</para>
-
-    <programlisting>$configdir = dirname(dirname(__FILE__)) . '/config';</programlisting>
-
-    <para>to:</para>
-
-    <programlisting>$configdir = '/home/andreas/simplesamlphp/config';</programlisting>
-
-    <note>
-      <para>In a future version of simpleSAMLphp we'll make this a bit easier,
-      and let you only change the path one place, instead of three as
-      described above.</para>
-    </note>
-
-    <para>Next, you need to update the configuration of paths in
-    <filename>simplesamlphp/config/config.php</filename>:</para>
-
-    <para>Set the <literal>basedir</literal> parameter to the path of your
-    simplesamlphp folder:</para>
-
-    <programlisting>	'basedir' =&gt; '/home/andreas/simplesamlphp/',</programlisting>
-
-    <para>And, then we need to set the <literal>baseurlpath</literal>
-    parameter to match the base path of the URLs to the content of your
-    <filename>www</filename> folder:</para>
-
-    <programlisting>	'baseurlpath'           =&gt; '~andreas/simplesaml/',</programlisting>
-
-    <para>Now, you can go to the URL of your installation and check if things
-    work:</para>
-
-    <literallayout>http://yourcompany.com/~andreas/simplesaml/</literallayout>
-  </appendix>
-</article>
\ No newline at end of file