The configuration file ================================== The configuration file allows you to specify how PiAnoS connects to the database, and change a few settings to enable/disable some features and/or alter how some work. The configuration file is named ``settings-local.php`` and lives in the ``backend/`` directory. Note that this directory is not directly visible to the clients, thanks to a ``.htaccess`` file. All options have defaults that are defined in ``Pianos4.php``, but you are not supposed to edit this file (in fact, if you do, you will not be able to upgrade PiAnoS because this would overwrite your changes). Instead, open ``settings-local.php`` and add a line of the form .. code-block:: php Application::set('setting_name', 'setting_value'); Using the :doc:`install/webinstall`, a configuration file was created. It contains the database parameters and a couple of other site-specific settings. You can change or remove these, or add new settings at any time. Those changes take immediate effect. For the record, here is a simple configuration file produced by the :doc:`install/webinstall`: .. code-block:: php '); // Misc settings Application::set('cookie_params', '/'); Application::set('session_timeout', 3600); Application::set('backend_app_settings', array('hasSearchBox' => true)); } ?> Settings reference ------------------------------ Following is the reference list of all settings that you can safely modify. There are other settings, defined in ``Pianos4.php``, but they are considered internal settings for the time being. =============================== =============== ====================================================================================================== Setting Default Explanation =============================== =============== ====================================================================================================== db_host 'localhost' Hostname to connect to db_port 5432 Port db_name 'pianos4' Name of the database db_user 'pianos' Username of the database role db_password 'pianos' Password for this role cookie_params NULL Session cookie parameters. While these can be left to NULL on development servers production installation should set them appropriately. There is a security risk if they are not set: 2 installations on the same server and/or domain will potentially use the same cookie (e.g. log on as 'admin' on ``/pianos-a``, go to ``/pianos-b`` and you are still logged on as admin!) This can be set to: - ``NULL`` (development only): no session cookie parameters are set - a string: the base path of the installation (e.g. ``/pianos4``) - an array of 2 strings: the base path and the domain (e.g. ``array('/pianos4','.unil.ch')``) session_lifetime NULL Session timeout. If not set (i.e. set to ``NULL``), let PHP manage the session lifetime (set through the session.gc_maxlifetime parameter). If set to a value, (number of seconds), overrides the session lifetime locally, using session variables and access timestamps. Since the session might be let unmodified for a long time while the user is working, setting this is a preferred method over configuring PHP to manage the session lifetime. shibboleth_login false Use Shibboleth login mechanism. Set to ``false`` or ``NULL`` to disable. Set to an array to enable. The detailed structure of the expected array is given in the next table. use_minified_pianos4 false Minified scripts. Set these to the name of the minified versions of PiAnoS 4 (main and backend) javascript files. Note that in released versions this **needs** to be defined in your local configuration, and point to the appropriate ``.min.js`` file [#f1]_. use_minified_pianos4_backend false Same as above for the backend javascript file. user_manual_url NULL URL to the user manual. If left to ``NULL``, no link to the user manual will be shown. Otherwise, it will appear under the help menu. imagick NULL Some features require ImageMagick, which can be provided by PHP itself, or by external scripts (e.g. ``convert[.exe]``, ``mogrify[.exe]``, etc.). If this variable is unset, or set to anything else but a string, it means that PHP Imagick is to be used. If set to a string, it is the base path to the utilities of ImageMagick (e.g. ``c:\\program files\\imagemagick``) convert_images false Convert image types before storage. This is needed e.g. because although PiAnoS can accept TIFFs on upload, some browsers (Firefox!) will not accept them (but IE will). Set to ``false`` to disable image conversion. Set to an associative array to enable - keys are "from" mimetypes, and values are "to" extensions. E.g. to enable on-the-fly conversion for TIFFs to PNGs, set to ``array('image/tiff'=>'png')``. Note that this feature requires ImageMagick PHP extension (see the 'imagick' option above) Implementation note: the values will be used as argument to ImageMagick::setImageFormat archive_results false There exist the possibility to log ALL saved results to a dedicated table named ``result_history``. By default (set to ``false``), this table will not be used. If set to ``true``, results will be continuously inserted into the table. It is your responsibility to manage this table (delete rows, etc.) =============================== =============== ====================================================================================================== Single sign-on using Shibboleth ------------------------------------------ PiAnoS supports a primitive form of single sign-on. Because UNIL uses Shibboleth, an adapter has been written for PiAnoS so our students can log-in using their institutional credentials. Supporting other external authentication mechanism is feasible but requires modifying the source code. **Settings** ============ ============================================================================== Key Value ============ ============================================================================== url URL to the shibboleth-protected area. The file pointed to must perform the appropriate redirect once the login has been performed (i.e. returning to index.php). Note: use 'shibboleth-simulate.php' to simulate a login on a development machine that is not Shibboleth-enabled. login_prompt title of the login form e.g. 'Students login with Shibboleth' login_image URL to the image to display in the login box itself. Do not set or set to NULL when no image should be displayed login_text text inside the login form. Do not set or set to NULL when no text should be displayed username the $_SERVER field containing the username display_name array of 2 $_SERVER fields containing the first and last names email the $_SERVER field containing the email groups array of 3-tuples: ($_SERVER field, regexp, target group name). If this is set, users will be accepted only if the specified field matches the regexp, and they will be assigned the target group. return the URL to return to after successfull authentication ============ ============================================================================== **Example**: .. code-block:: php Application::set('shibboleth_login',array( 'login_text' => 'Follow the link to use your ORG crendentials', 'login_prompt' => 'ORG student login', 'login_image' => 'shibboleth_buttonflat.gif', 'url' => 'shibboleth_auth/', 'username' => 'Shib-SwissEP-UniqueID', 'display_name' => array('Shib-InetOrgPerson-givenName','Shib-Person-surname'), 'email' => 'Shib-InetOrgPerson-mail', 'groups' => array( array('Shib-EP-Entitlement', '/http:\\/\\/groups.org.ch\\/etu-bachelor/', 'Bachelor 2012'), array('Shib-EP-Entitlement', '/http:\\/\\/groups.org.ch\\/etu-master/', 'Master 2012'), ), 'return' => '../index.php', )); Note the weird syntax of the groups patterns - this is because our organization uses URLs to define subgroups, which uses slashes ``/``, and those need to be escaped to be recognized by PHP. **Apache configuration** For all of the above to be effective, due to how Shibboleth works, we need to: - create a subdirectory (sibling of ``backend``, ``js``, etc.) named ``shibboleth_auth`` - tell Apache that ``shibboleth_auth`` is protected by Shibboleth using a ``.htaccess`` file: .. code:: Order allow,deny Allow from all AuthType shibboleth ShibRequireSession On ShibRedirectToSSL 443 require valid-user And of course, all of this only works if Shibboleth is set-up properly on your system, and already integrated into Apache. The apache ``rewrite`` module shall be enabled to activate the use of the ``.htaccess`` file; if not, the ``.htaccess`` file will not be loaded and the shibboleth authentication will not be triggered. In this situation, the ``shibboleth_auth/index.php`` page will try to load without triggering the ``AuthType shibboleth`` access restribtion, and will not be able to find the shibboleth related ``$_SERVER`` variables. .. rubric:: Footnotes .. [#f1] These settings are mandatory in `released` versions because you would otherwise need the `debugging` versions of individual files (that you don't have), that are grouped together in the ``.min.js`` files (that you do have).