Merge branch 'master' of https://github.com/tldev/simplesamlphp into feature/config-from-env

9 files changed, 155 insertions, 52 deletions

diff --git a/bin/memcacheSync.php b/bin/memcacheSync.php
index 0090f96..13dc7cc 100755
--- a/bin/memcacheSync.php
+++ b/bin/memcacheSync.php
@@ -24,7 +24,7 @@ $baseDir = dirname(dirname(__FILE__));
 require_once($baseDir . '/lib/_autoload.php');
 
 /* Initialize the configuration. */
-$configdir = $baseDir . '/config';
+$configdir = SimpleSAML\Utils\Config::getConfigDir();
 SimpleSAML_Configuration::setConfigDir($configdir);
 
 /* Things we should warn the user about. */
diff --git a/docs/simplesamlphp-install.txt b/docs/simplesamlphp-install.txt
index 9149673..11f6c23 100644
--- a/docs/simplesamlphp-install.txt
+++ b/docs/simplesamlphp-install.txt
@@ -1,4 +1,4 @@
-simpleSAMLphp Installation and Configuration
+SimpleSAMLphp Installation and Configuration
 ============================================
 
 <!-- 
@@ -11,21 +11,21 @@ simpleSAMLphp Installation and Configuration
 
 <!-- {{TOC}} -->
 
-simpleSAMLphp news and documentation
+SimpleSAMLphp news and documentation
 ------------------------------------
 
-This document is part of the simpleSAMLphp documentation suite.
+This document is part of the SimpleSAMLphp documentation suite.
 
- * [List of all simpleSAMLphp documentation](http://simplesamlphp.org/docs)
- * [Latest news about simpleSAMLphp](http://rnd.feide.no/taxonomy/term/4). (Also contains an RSS feed)
- * [simpleSAMLphp homepage](https://simplesamlphp.org)
+ * [List of all SimpleSAMLphp documentation](http://simplesamlphp.org/docs)
+ * [Latest news about SimpleSAMLphp](http://rnd.feide.no/taxonomy/term/4). (Also contains an RSS feed)
+ * [SimpleSAMLphp homepage](https://simplesamlphp.org)
 
 
 Development version
 --------------------
 
-This document is about the latest stable version of simpleSAMLphp.
-If you want to install the development version, look at the instructions for [installing simpleSAMLphp from the repository](simplesamlphp-install-repo).
+This document is about the latest stable version of SimpleSAMLphp.
+If you want to install the development version, look at the instructions for [installing SimpleSAMLphp from the repository](simplesamlphp-install-repo).
 
 
 Prerequisites
@@ -46,25 +46,26 @@ Prerequisites
 What actual packages are required for the various extensions varies between different platforms and distributions.
 
 
-Download and install simpleSAMLphp
+Download and install SimpleSAMLphp
 ----------------------------------
 
-The most recent release of simpleSAMLphp is found at [https://simplesamlphp.org/download](https://simplesamlphp.org/download).
+The most recent release of SimpleSAMLphp is found at [https://simplesamlphp.org/download](https://simplesamlphp.org/download).
 
-Go to the directory where you want to install simpleSAMLphp, and extract the archive file you just downloaded:
+Go to the directory where you want to install SimpleSAMLphp, and extract the archive file you just downloaded:
 
     cd /var
     tar xzf simplesamlphp-1.x.y.tar.gz
     mv simplesamlphp-1.x.y simplesamlphp
 
-## Upgrading from a previous version of simpleSAMLphp
+## Upgrading from a previous version of SimpleSAMLphp
 
 Extract the new version:
 
     cd /var
     tar xzf simplesamlphp-1.x.y.tar.gz
 
-Copy the configuration files from the previous version:
+Copy the configuration files from the previous version (in case the configuration directory is inside SimpleSAMLphp,
+keep reading for other alternatives):
 
     cd /var/simplesamlphp-1.x.y
     rm -rf config metadata
@@ -78,7 +79,7 @@ Replace the old version with the new version:
     mv simplesamlphp-1.x.y simplesamlphp
 
 
-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:
+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
@@ -91,42 +92,62 @@ This will ensure that all new entries in the latest version of config.php are in
 
 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.
 
+### Alternative location for configuration files
+
+By default, SimpleSAMLphp looks for its configuration in the `config` directory in the root of its own directory. This
+has some drawbacks, like making it harder to use SimpleSAMLphp as a composer dependency, or to package it for different
+operating systems.
+
+However, it is now possible to specify an alternate location for the configuration directory by setting an environment
+variable with this location. This way, the configuration directory doesn't need to be inside the library's directory,
+making it easier to manage and to update. The simplest way to set this environment variable is to set it in your web
+server's configuration. See the next section for more information.
+
 
 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 for details ‹Installing simpleSAMLphp in alternative locations›.
+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 for details ‹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.
+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:
+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
-    
+
+            SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
+
             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`:
+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`:
 
     $config = array (
     [...]
             'baseurlpath'                   => 'simplesaml/',
 
-simpleSAMLphp configuration: config.php
+Note also the `SetEnv` directive. It sets the `SIMPLESAMLPHP_CONFIG_DIR` environment variable, in this case, to the
+default location for the configuration directory. You can always omit this environment variable, and SimpleSAMLphp will
+then look for the `config` directory inside its own directory. If you need to move your configuration to a different
+location, you can use this environment variable to tell SimpleSAMLphp where to look for configuration files. Remember
+this works only for the `config` directory. If you need your metadata to be in a different directory too, use the
+`metadatadir` configuration option to specify the location.
+
+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.
+-  Set a administrator password. This is needed to access some of the pages in your SimpleSAMLphp installation web interface.
 
 		'auth.adminpassword'        => 'setnewpasswordhere',
 
    Hashed passwords can also be used here. See the [`authcrypt`](./authcrypt:authcrypt) documentation for more information.
 
--  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:
+-  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
 
@@ -138,13 +159,13 @@ file, `config.php`, right away:
     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:
+    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
+    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:
 
@@ -163,13 +184,13 @@ Configuring PHP
 
 ### Sending e-mails from PHP
 
-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.
+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`.
+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
@@ -185,10 +206,10 @@ to `disable`.
 
 
 
-The simpleSAMLphp installation webpage
+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.:
+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/
 
@@ -197,13 +218,13 @@ The exact link depends on how you set it up with Apache, and of course on your h
 ### 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
+either have setup SimpleSAMLphp as an Service Provider or as an
 Identity Provider.
 
-Here is an example screenshot of what the simpleSAMLphp page looks
+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)
+![Screenshot of the SimpleSAMLphp installation page.](http://rnd.feide.no/doc/resources/simplesamlphp-install/screenshot-installationpage.png)
 
 ### Check your PHP environment
 
@@ -211,9 +232,9 @@ At the bottom of the installation page are some green lights. simpleSAML runs so
 
 ## 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.
+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.
 
- * [Using simpleSAMLphp as a SAML Service Provider](simplesamlphp-sp)
+ * [Using SimpleSAMLphp as a SAML Service Provider](simplesamlphp-sp)
   * [Hosted SP Configuration Reference](./saml:sp)
   * [IdP remote reference](simplesamlphp-reference-idp-remote)
   * [Connecting SimpleSAMLphp as a SP to UK Access Federation or InCommon](simplesamlphp-ukaccess)
@@ -229,24 +250,24 @@ You have now successfully installed simpleSAMLphp, and the next steps depends on
 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.
+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](https://simplesamlphp.org)
--  [List of all available simpleSAMLphp documentation](https://simplesamlphp.org/docs/)
--  [Join the simpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)
+-  [SimpleSAMLphp homepage](https://simplesamlphp.org)
+-  [List of all available SimpleSAMLphp documentation](https://simplesamlphp.org/docs/)
+-  [Join the SimpleSAMLphp user's mailing list](https://simplesamlphp.org/lists)
 
 
 
 
-Installing simpleSAMLphp in alternative locations
+Installing SimpleSAMLphp in alternative locations
 -------------------------------------------------
 
-There may be several reasons why you want to install simpleSAMLphp
+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
+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.
+	Still you can install SimpleSAMLphp - keep on reading.
 
 2.	You have full permissions to the server, but cannot edit Apache
 	configuration for some reason, politics, policy or whatever.
@@ -254,9 +275,9 @@ in an alternative way.
 
 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 recommended 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 shared hosting server.
+As an example, let's see how you can install SimpleSAMLphp in your home directory on a shared hosting server.
 
-Extract the simpleSAMLphp archive in your home directory:
+Extract the SimpleSAMLphp archive in your home directory:
 
     cd ~
     tar xzf simplesamlphp-1.x.y.tar.gz
@@ -319,4 +340,4 @@ to:
 
 ### 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.
+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.
diff --git a/lib/SimpleSAML/Configuration.php b/lib/SimpleSAML/Configuration.php
index 4ba1b5d..4f9bf36 100644
--- a/lib/SimpleSAML/Configuration.php
+++ b/lib/SimpleSAML/Configuration.php
@@ -167,7 +167,7 @@ class SimpleSAML_Configuration
             if ($configSet !== 'simplesaml') {
                 throw new Exception('Configuration set \''.$configSet.'\' not initialized.');
             } else {
-                self::$configDirs['simplesaml'] = dirname(dirname(dirname(__FILE__))).'/config';
+                self::$configDirs['simplesaml'] = SimpleSAML\Utils\Config::getConfigDir();
             }
         }
 
@@ -197,7 +197,7 @@ class SimpleSAML_Configuration
             if ($configSet !== 'simplesaml') {
                 throw new Exception('Configuration set \''.$configSet.'\' not initialized.');
             } else {
-                self::$configDirs['simplesaml'] = dirname(dirname(dirname(__FILE__))).'/config';
+                self::$configDirs['simplesaml'] = SimpleSAML\Utils\Config::getConfigDir();
             }
         }
 
diff --git a/lib/SimpleSAML/Utils/Config.php b/lib/SimpleSAML/Utils/Config.php
index e0c3f57..c181ba9 100644
--- a/lib/SimpleSAML/Utils/Config.php
+++ b/lib/SimpleSAML/Utils/Config.php
@@ -55,4 +55,34 @@ class Config
 
         return $secretSalt;
     }
-}
\ No newline at end of file
+
+    /**
+     * Returns the path to the config dir
+     *
+     * If the SIMPLESAMLPHP_CONFIG_DIR environment variable has been set, it takes precedence over the default
+     * $simplesamldir/config directory.
+     *
+     * @return string The path to the configuration directory.
+     */
+    public static function getConfigDir()
+    {
+        $configDir    = dirname(dirname(dirname(__DIR__))) . '/config';
+        $configDirEnv = getenv('SIMPLESAMLPHP_CONFIG_DIR');
+        if ($configDirEnv !== false) {
+            if (!is_dir($configDirEnv)) {
+                // this error is fatal, make sure the user can read it at least
+                header('Content-Type: text/plain');
+                throw new \InvalidArgumentException(
+                    sprintf(
+                        'Config directory specified by environment variable SIMPLESAMLPHP_CONFIG_DIR is not a ' .
+                        'directory.  Given: "%s"',
+                        $configDirEnv
+                    )
+                );
+            }
+            $configDir = $configDirEnv;
+        }
+
+        return $configDir;
+    }
+}
diff --git a/modules/metarefresh/bin/metarefresh.php b/modules/metarefresh/bin/metarefresh.php
index 2e351f3..b31fff5 100755
--- a/modules/metarefresh/bin/metarefresh.php
+++ b/modules/metarefresh/bin/metarefresh.php
@@ -23,7 +23,8 @@ if(!SimpleSAML_Module::isModuleEnabled('metarefresh')) {
 }
 
 /* Initialize the configuration. */
-SimpleSAML_Configuration::setConfigDir($baseDir . '/config');
+$configdir = SimpleSAML\Utils\Config::getConfigDir();
+SimpleSAML_Configuration::setConfigDir($configdir);
 
 /* $outputDir contains the directory we will store the generated metadata in. */
 $outputDir = $baseDir . '/metadata-generated';
diff --git a/modules/statistics/bin/loganalyzer.php b/modules/statistics/bin/loganalyzer.php
index 7186890..f64fa99 100755
--- a/modules/statistics/bin/loganalyzer.php
+++ b/modules/statistics/bin/loganalyzer.php
@@ -9,7 +9,8 @@ $baseDir = dirname(dirname(dirname(dirname(__FILE__))));
 require_once($baseDir . '/lib/_autoload.php');
 
 /* Initialize the configuration. */
-SimpleSAML_Configuration::setConfigDir($baseDir . '/config');
+$configdir = SimpleSAML\Utils\Config::getConfigDir();
+SimpleSAML_Configuration::setConfigDir($configdir);
 
 SimpleSAML\Utils\Time::initTimezone();
 
diff --git a/modules/statistics/bin/logcleaner.php b/modules/statistics/bin/logcleaner.php
index ffa1ecd..4bdad96 100755
--- a/modules/statistics/bin/logcleaner.php
+++ b/modules/statistics/bin/logcleaner.php
@@ -9,7 +9,8 @@ $baseDir = dirname(dirname(dirname(dirname(__FILE__))));
 require_once($baseDir . '/lib/_autoload.php');
 
 /* Initialize the configuration. */
-SimpleSAML_Configuration::setConfigDir($baseDir . '/config');
+$configdir = SimpleSAML\Utils\Config::getConfigDir();
+SimpleSAML_Configuration::setConfigDir($configdir);
 
 
 
diff --git a/tests/lib/SimpleSAML/Utils/ConfigTest.php b/tests/lib/SimpleSAML/Utils/ConfigTest.php
new file mode 100644
index 0000000..2fdc080
--- /dev/null
+++ b/tests/lib/SimpleSAML/Utils/ConfigTest.php
@@ -0,0 +1,49 @@
+<?php

+

+/**

+ * Tests for SimpleSAML\Utils\Config

+ */

+class Utils_ConfigTest extends PHPUnit_Framework_TestCase

+{

+

+    /**

+     * Test default config dir with not environment variable

+     */

+    public function testDefaultConfigDir()

+    {

+        // clear env var

+        putenv('SIMPLESAMLPHP_CONFIG_DIR');

+        $configDir = \SimpleSAML\Utils\Config::getConfigDir();

+

+        $this->assertEquals($configDir, dirname(dirname(dirname(dirname(__DIR__)))) . '/config');

+    }

+

+    /**

+     * Test valid dir specified by env var overrides default config dir

+     */

+    public function testEnvVariableConfigDir()

+    {

+        putenv('SIMPLESAMLPHP_CONFIG_DIR=' . __DIR__);

+        $configDir = \SimpleSAML\Utils\Config::getConfigDir();

+

+        $this->assertEquals($configDir, __DIR__);

+    }

+

+    /**

+     * Test invalid dir specified by env var results in a thrown exception

+     */

+    public function testInvalidEnvVariableConfigDirThrowsException()

+    {

+        // I used a random hash to ensure this test directory is always invalid

+        $invalidDir = __DIR__ . '/e9826ad19cbc4f5bf20c0913ffcd2ce6';

+        putenv('SIMPLESAMLPHP_CONFIG_DIR=' . $invalidDir);

+

+        $this->setExpectedException(

+            'InvalidArgumentException',

+            'Config directory specified by environment variable SIMPLESAMLPHP_CONFIG_DIR is not a directory.  ' .

+            'Given: "' . $invalidDir . '"'

+        );

+

+        \SimpleSAML\Utils\Config::getConfigDir();

+    }

+}

diff --git a/www/_include.php b/www/_include.php
index b6d81f1..7b65e92 100644
--- a/www/_include.php
+++ b/www/_include.php
@@ -81,7 +81,7 @@ function SimpleSAML_error_handler($errno, $errstr, $errfile = null, $errline = 0
 
 set_error_handler('SimpleSAML_error_handler');
 
-$configdir = dirname(dirname(__FILE__)).'/config';
+$configdir = SimpleSAML\Utils\Config::getConfigDir();
 if (!file_exists($configdir.'/config.php')) {
     header('Content-Type: text/plain');
     echo("You have not yet created the simpleSAMLphp configuration files.\n");