Skip to content
Snippets Groups Projects
Commit e2ac4392 authored by Andreas Åkre Solberg's avatar Andreas Åkre Solberg
Browse files

Updating maintenance document and converting to markdown 

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1297 44740490-163a-0410-bde0-09ae8108e29a
parent 3d189083
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/simplesamlphp-install.txt
+ 1
− 3
View file @ e2ac4392
......@@ -22,8 +22,6 @@ This document is part of the simpleSAMLphp documentation suite.
Prerequisites
-------------
......@@ -31,7 +29,7 @@ PHP version >= 5.1.2. If you want to run the *Shibboleth 1.3* part of simpleSAML
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.
simpleSAMLphp is has been tested most thoroughly on different Linux versions, Unix, and Mac OS X. It also runs on Windows.
Download and install simpleSAMLphp
......
docs/simplesamlphp-maintenance.txt 0 → 100644
+ 203
− 0
View file @ e2ac4392
simpleSAMLphp Maintenance
=========================
<!--
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 news and documentation
------------------------------------
This document is part of the simpleSAMLphp documentation suite.
* [List of all simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
* [Latest news about simpleSAMLphp](http://rnd.feide.no/taxonomy/term/4). (Also conatins an RSS feed)
* [simpleSAMLphp homepage](http://rnd.feide.no/simplesamlphp)
## Session management
simpleSAMLphp has an abstraction layer for session management. That means it is possible to choose between different kind of session stores, as well as write new session store plugins.
The `session.handler` configuration option in `config.php` allows you to select which session handler SimpleSAMLphp should use to store the session information. Currently, two session handlers are included in the distribution:
* `phpsession` uses the built in session management in PHP. This is the default, and is simplest to use. It will not work in a load-balanced environement.
* `memcache` uses the memcache software to cache sessions in memory. Sessions can be distributed and replicated among several memcache servers, enabling both load-balancing and fail-over.
'session.handler' => 'phpsession',
### Configuring memcache
To use the memcache session handler, set the `session.handler` parameter in `config.php`:
'session.handler' => 'memcache',
memcache allows you to store multiple redudant copies of sessions on different memcache servers.
The configuration parameter `memcache_store.servers` is an array of server groups. Every data item will be mirrored in every server group.
Each server group is an array of servers. The data items will be load-balanced between all servers in each server group.
Each server is an array of parameters for the server. The following options are available:
`hostname`
: Host name or ip address of a memcache server runs. This is the
only required option.
`port`
: Port number of the memcache server. If not set, the
`memcache.default_port` ini setting is used. This is 11211 by
default.
`weight`
: Weight of this server in this server group.
[http://php.net/manual/en/function.Memcache-addServer.php](http://php.net/manual/en/function.Memcache-addServer.php)
has more information about the weight option.
`timeout`
: Timeout for this server. By default, the timeout is 3
seconds.
Here are two examples of configuration of memcache session handling:
**Example&nbsp;1.&nbsp;Example of redudant configuration with load balancing**
Example of redudant configuration with load balancing: This configuration makes it possible to lose both servers in the a-group or both servers in the b-group without losing any sessions. Note that sessions will be lost if one server is lost from both the a-group and the b-group.
'memcache_store.servers' => array(
array(
array('hostname' => 'mc_a1'),
array('hostname' => 'mc_a2'),
),
array(
array('hostname' => 'mc_b1'),
array('hostname' => 'mc_b2'),
),
),
**Example&nbsp;2.&nbsp;Example of simple configuration with only one memcache server**
Example of simple configuration with only one memcache server, running on the same computer as the web server: Note that all sessions will be lost if the memcache server crashes.
'memcache_store.servers' => array(
array(
array('hostname' => 'localhost'),
),
),
The expiration value (`memcache_store.expires`) is the duration for which data should be retained in memcache. Data are dropped from the memcache servers when this time expires. The time will be reset every time the data is written to the memcache servers.
This value should always be larger than the `session.duration` option. Not doing this may result in the session being deleted from the memcache servers while it is still in use.
Set this value to 0 if you don't want data to expire.
### Note
The oldest data will always be deleted if the memcache server runs
out of storage space.
**Example&nbsp;3.&nbsp;Example of configuration setting for session expiration**
Here is an example of this configuration parameter:
'memcache_store.expires' => 36 * (60*60), // 36 hours.
#### Memcache PHP configuration
Configure memcahce to not do internal failover. This parameter is
configured in `php.ini`.
memcache.allow_failover = Off
#### Environmental configuration
Setup a firewall restricting access to the memcache server.
Because simpleSAMLphp uses a timestamp to check which session is most recent in a fail-over setup, it is very important to run syncrhonized clocks on all webservers where you run simpleSAMLphp.
## Load balancing and failover
## Logging and statistics
simpleSAMLphp supports standard `syslog` logging. As an
alternative, you may log to flat files.
## Apache configuration
## PHP configuration
Secure cookies (if you run HTTPS).
Turn off PHPSESSID in query string.
## Getting ready for production
Here are some checkpoints
1. Remove all entities in metadata files that you do not trust. It is easy to forget about some of the entities that were used for test.
2. If you during testing have been using a certificate that has been exposed (notably: the one found in the simpleSAMLphp distribution): Obtain and install a new one.
3. Make sure you have installed the latest security upgrades for your OS.
4. Make sure to use HTTPS rather than HTTP.
5. Block access to your servers on anything except port 443. simpleSAMLphp only uses plain HTTP(S), so there is no need to open ports for SOAP or other communication.
## Error handling, error reporting and metadata reporting
SimpleSAMLphp supports allowing the user when encountering errors to send an e-mail to the administrator. You can turn off this feature in the config.php file.
## Multi-language support
To add support for a new language, add your new language to the `language.available` configuration parameter in `config.php`:
/*
* Languages available and which language is default
*/
'language.available' => array('en', 'no', 'da', 'es', 'xx'),
'language.default' => 'en',
Please use the standarized two-character
[language codes as specified in ISO-639-1](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
You also can set the default language. You should ensure that the default language is complete, as it is used as a fallback when a text is not available in the language selected by the user.
Translation of simpleSAMLphp is done through the SimpleSAMLphp translation portal. To translate simpleSAMLphp to a new language, please contact the authors at the mailinglist, and the new language may be added to the translation portal.
* [Visit the SimpleSAMLphp translation portal](https://translation.rnd.feide.no/?aid=simplesamlphp)
All strings that can be localized are found in the files `dictionaries/`. Add a new entry for each string, with your language code, like this:
'user_pass_header' => array(
'en' => 'Enter your username and password',
'no' => 'Skriv inn brukernavn og passord',
'xx' => 'Pooa jujjique jamba',
),
You can translate as many of the texts as you would like; a full translation is not required unless you want to make this the default language. From the end users point of view, it looks best if all text fragments used in a given screen or form is in one single language.
## Customizing the web frontend with themes
Documentation on theming is moved [to a separate document](http://rnd.feide.no/content/theming-simplesamlphp).
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)
docs/source/simplesamlphp-maintenance.xml deleted 100644 → 0
+ 0
− 405
View file @ 3d189083
<?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>Advanced configuration and maintainance of simpleSAMLphp</title>
<articleinfo>
<date>2007-08-30</date>
<pubdate>Thu Jun 19 08:34:38 2008</pubdate>
<author>
<firstname>Andreas Åkre</firstname>
<surname>Solberg</surname>
<email>andreas.solberg@uninett.no</email>
</author>
</articleinfo>
<warning>
<para>This document is still in progress.</para>
</warning>
<section>
<title>simpleSAMLphp documentation</title>
<para>This document is part of the simpleSAMLphp documentation
suite.</para>
<itemizedlist>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all simpleSAMLphp documentation</ulink></para>
</listitem>
</itemizedlist>
<para>This document assumes that you already have a installation of
simpleSAMLphp running, configured and working. This is the next step
:)</para>
</section>
<section>
<title>Session management</title>
<para>simpleSAMLphp has an abstraction layer for session management. That
means it is possible to choose between different kind of session stores,
as well as write new session store plugins.</para>
<para>The <literal>session.handler</literal> configuration option in
<filename>config.php</filename> allows you to select which session handler
SimpleSAMLphp should use to store the session information. Currently, two
session handlers are included in the distribution:</para>
<itemizedlist>
<listitem>
<para><literal>phpsession</literal> uses the built in session
management in PHP. This is the default, and is simplest to use. It
will not work in a load-balanced environement.</para>
</listitem>
<listitem>
<para><literal>memcache</literal> uses the memcache software to cache
sessions in memory. Sessions can be distributed and replicated among
several memcache servers, enabling both load-balancing and
fail-over.</para>
</listitem>
</itemizedlist>
<programlisting> 'session.handler' =&gt; 'phpsession',</programlisting>
<section>
<title>Configuring memcache</title>
<para>To use the memcache session handler, set the
<literal>session.handler</literal> parameter in
<literal>config.php</literal>:</para>
<programlisting>'session.handler' =&gt; 'memcache',</programlisting>
<para>memcache allows you to store multiple redudant copies of sessions
on different memcache servers.</para>
<para>The configuration parameter
<literal>memcache_store.servers</literal> is an array of server groups.
Every data item will be mirrored in every server group.</para>
<para>Each server group is an array of servers. The data items will be
load-balanced between all servers in each server group.</para>
<para>Each server is an array of parameters for the server. The
following options are available:</para>
<glosslist>
<glossentry>
<glossterm><literal>hostname</literal></glossterm>
<glossdef>
<para>Host name or ip address of a memcache server runs. This is
the only required option.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><literal>port</literal></glossterm>
<glossdef>
<para>Port number of the memcache server. If not set, the
<literal>memcache.default_port</literal> ini setting is used. This
is 11211 by default.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><literal>weight</literal></glossterm>
<glossdef>
<para>Weight of this server in this server group. <ulink
url="http://php.net/manual/en/function.Memcache-addServer.php">http://php.net/manual/en/function.Memcache-addServer.php</ulink>
has more information about the weight option.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm><literal>timeout</literal></glossterm>
<glossdef>
<para>Timeout for this server. By default, the timeout is 3
seconds.</para>
</glossdef>
</glossentry>
</glosslist>
<para>Here are two examples of configuration of memcache session
handling:</para>
<example>
<title>Example of redudant configuration with load balancing</title>
<para>Example of redudant configuration with load balancing: This
configuration makes it possible to lose both servers in the a-group or
both servers in the b-group without losing any sessions. Note that
sessions will be lost if one server is lost from both the a-group and
the b-group.</para>
<programlisting>'memcache_store.servers' =&gt; array(
array(
array('hostname' =&gt; 'mc_a1'),
array('hostname' =&gt; 'mc_a2'),
),
array(
array('hostname' =&gt; 'mc_b1'),
array('hostname' =&gt; 'mc_b2'),
),
),</programlisting>
</example>
<example>
<title>Example of simple configuration with only one memcache
server</title>
<para>Example of simple configuration with only one memcache server,
running on the same computer as the web server: Note that all sessions
will be lost if the memcache server crashes.</para>
<programlisting>'memcache_store.servers' =&gt; array(
array(
array('hostname' =&gt; 'localhost'),
),
),</programlisting>
</example>
<para>The expiration value (<literal>memcache_store.expires</literal>)
is the duration for which data should be retained in memcache. Data are
dropped from the memcache servers when this time expires. The time will
be reset every time the data is written to the memcache servers.</para>
<para>This value should always be larger than the
<literal>session.duration</literal> option. Not doing this may result in
the session being deleted from the memcache servers while it is still in
use.</para>
<para>Set this value to 0 if you don't want data to expire.</para>
<note>
<para>The oldest data will always be deleted if the memcache server
runs out of storage space.</para>
</note>
<example>
<title>Example of configuration setting for session expiration</title>
<para>Here is an example of this configuration parameter:</para>
<programlisting>'memcache_store.expires' =&gt; 36 * (60*60), // 36 hours.</programlisting>
</example>
<section>
<title>Memcache PHP configuration</title>
<para>Configure memcahce to not do internal failover. This parameter
is configured in <filename>php.ini</filename>.</para>
<programlisting>memcache.allow_failover = Off</programlisting>
</section>
<section>
<title>Environmental configuration</title>
<para>Setup a firewall restricting access to the memcache
server.</para>
<para>Because simpleSAMLphp uses a timestamp to check which session is
most recent in a fail-over setup, it is very important to run
syncrhonized clocks on all webservers where you run
simpleSAMLphp.</para>
</section>
</section>
</section>
<section>
<title>Load balancing and failover</title>
<para></para>
</section>
<section>
<title>Logging and statistics</title>
<para>simpleSAMLphp supports standard <literal>syslog</literal> logging.
As an alternative, you may log to flat files.</para>
</section>
<section>
<title>Apache configuration</title>
<para></para>
</section>
<section>
<title>PHP configuration</title>
<para>Secure cookies (if you run HTTPS).</para>
<para>Turn off PHPSESSID in query string.</para>
</section>
<section>
<title>Getting ready for production</title>
<para>Here are some checkpoints</para>
<itemizedlist>
<listitem>
<para>Remove all entities in metadata files that you do not trust. It
is easy to forget about some of the entities that were used for
test.</para>
</listitem>
<listitem>
<para>If you during testing have been using a certificate that has
been exposed (notably: the one found in the simpleSAMLphp
distribution): Obtain and install a new one.</para>
</listitem>
<listitem>
<para>Make sure you have installed the latest security upgrades for
your OS.</para>
</listitem>
<listitem>
<para>Make sure to use HTTPS rather than HTTP.</para>
</listitem>
<listitem>
<para>Block access to your servers on anything except port 443.
simpleSAMLphp only uses plain HTTP(S), so there is no need to open
ports for SOAP or other communication.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Error handling, error reporting and metadata reporting</title>
<para>Check out the extras folder for a script that can be embedded in a
webpage and enable the possibility of sending UI errors to the
administrators.</para>
</section>
<section>
<title>Multi-language support</title>
<para>To add support for a new language, add your new language to the
<literal>language.available</literal> configuration parameter in
<filename>config.php</filename>:</para>
<programlisting> /*
* Languages available and which language is default
*/
'language.available' =&gt; array('en', 'no', 'da', 'es', 'xx'),
'language.default' =&gt; 'en',</programlisting>
<para>Please use the standarized two-character <ulink
url="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">language codes
as specified in ISO-639-1</ulink>.</para>
<para>You also can set the default language. You should ensure that the
default language is complete, as it is used as a fallback when a text is
not available in the language selected by the user.</para>
<tip>
<para>This may change in the future. We may distinguish between the
fallback-lanauge (which is usually English) and the default
language.</para>
</tip>
<para>All strings that can be localized are found in the files
<filename>dictionaries/</filename>. Add a new entry for each string, with
your language code, like this:</para>
<programlisting>'user_pass_header' =&gt; array(
'en' =&gt; 'Enter your username and password',
'no' =&gt; 'Skriv inn brukernavn og passord',
'xx' =&gt; 'Pooa jujjique jamba',
),</programlisting>
<para>You can translate as many of the texts as you would like; a full
translation is not required unless you want to make this the default
language. From the end users point of view, it looks best if all text
fragments used in a given screen or form is in one single language.</para>
<para>Note that themes used for customization of the web frontend (see
below) also may contain language specific texts which you would like to
include in your translation. Language independent themes may be created by
putting all theme texts in a file in the <filename>dictionaries</filename>
directory.</para>
</section>
<section>
<title>Customizing the web frontend with themes</title>
<para>All XHTML templates are stored in the
<filename>templates/</filename> directory, one subdirectory for each
theme. The default theme is named <literal>default</literal>. An sample
theme is provided, named <literal>feidernd</literal>.</para>
<para>It is possible to define a new theme, where only some of the pages
are customized. For the rest of the pages, the default theme is used. The
<literal>feidernd</literal> theme is a good example of this: Only the
login page is customized.</para>
<para>In <filename>config.php</filename> you specify the theme to use, as
well as a theme base. The theme base is the fallback theme that should be
used when the selected theme does not include the specific template needed
to render a page. Here is an example of a configuration:</para>
<programlisting> /*
* Which theme directory should be used? The base is fallback (leave it to default).
*/
'theme.use' =&gt; 'feidernd',
'theme.base' =&gt; 'default',</programlisting>
<important>
<para>The feidernd theme is based on the wordpress login form style.
Feel free to use this as a base for making your own login form. However:
Please do not use the feidernd theme unmodified - it contains the Feide
logo, which of course should be used to identify Feide services, not
services provided by your institution.</para>
</important>
</section>
<section>
<title>Support</title>
<para>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! Both
for asking question, answer other questions, request improvements or
contribute with code or plugins of your own.</para>
<itemizedlist>
<listitem>
<para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
homepage (at Feide RnD)</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
all available simpleSAMLphp documentation</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
the simpleSAMLphp user's mailing list</ulink></para>
</listitem>
<listitem>
<para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
contribute to the simpleSAMLphp wiki</ulink></para>
</listitem>
</itemizedlist>
</section>
</article>
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment