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

updates to installation doc 

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1135 44740490-163a-0410-bde0-09ae8108e29a
parent ed620dd9
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/simplesamlphp-install.txt
+ 33
− 134
View file @ bcd6fd2d
...@@ -11,24 +11,17 @@ simpleSAMLphp Installation and Configuration ...@@ -11,24 +11,17 @@ simpleSAMLphp Installation and Configuration
simpleSAMLphp 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://rnd.feide.no/view/simplesamlphpdocs) * [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)
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 Prerequisites
...@@ -44,12 +37,7 @@ simpleSAMLphp is has been tested most thoroughly on different Linux versions, Un ...@@ -44,12 +37,7 @@ simpleSAMLphp is has been tested most thoroughly on different Linux versions, Un
Download and install simpleSAMLphp Download and install simpleSAMLphp
---------------------------------- ----------------------------------
The most recent relase of simpleSAMLphp is found at 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.
[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 ### Get a working copy of simpleSAMLphp from subversion
...@@ -79,49 +67,22 @@ installation: ...@@ -79,49 +67,22 @@ installation:
*If you download and install the zipped version:* *If you download and install the zipped version:*
- Make a backup of the `config` and the `metadata` directories. - Make a backup of the `config` and the `metadata` directories.
- Delete all files from your current simpleSAMLphp directory . - Delete all files from your current simpleSAMLphp directory .
- Unzip the new version in the simpleSAMLphp directory. - Unzip the new version in the simpleSAMLphp directory.
- Install the backups of `config` and the `metadata` directories 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 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:
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 ### Upgrading configuration files
A good approach is to run a `diff` between your preivous 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.
`config.php` file and the new `config.php` file located in
`config-templates/config.php`, and apply relevant modifications to 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.
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 ### Upgrading metadata files
Most likely the metadata format is backwards compatible. If not, 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.
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.
...@@ -131,19 +92,11 @@ Making configuration and metadata files ...@@ -131,19 +92,11 @@ Making configuration and metadata files
### Tip ### Tip
You do not need to read this section if you are upgrading 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›.
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 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.
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 Here are the steps you need to do to create local configuration files:
files:
cd /var/simplesamlphp cd /var/simplesamlphp
cp -r config-templates/*.php config/ cp -r config-templates/*.php config/
...@@ -154,19 +107,11 @@ files: ...@@ -154,19 +107,11 @@ files:
Configuring Apache Configuring Apache
------------------ ------------------
Examples below assume that simpleSAMLphp is installed in the 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›.
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 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.
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 Find the Apache configuration file for the virtual hosts where you want to run simpleSAMLphp. The configuration may look like this:
want to run simpleSAMLphp. The configuration may look like this:
<VirtualHost *> <VirtualHost *>
ServerName service.example.com ServerName service.example.com
...@@ -175,16 +120,7 @@ want to run simpleSAMLphp. The configuration may look like this: ...@@ -175,16 +120,7 @@ want to run simpleSAMLphp. The configuration may look like this:
Alias /simplesaml /var/simplesamlphp/www Alias /simplesaml /var/simplesamlphp/www
</VirtualHost> </VirtualHost>
Note the `Alias` directive, which gives control to simpleSAMLphp 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`:
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 ( $config = array (
[...] [...]
...@@ -196,18 +132,11 @@ simpleSAMLphp configuration: config.php ...@@ -196,18 +132,11 @@ simpleSAMLphp configuration: config.php
There is a few steps that you should edit in the main configuration There is a few steps that you should edit in the main configuration
file, `config.php`, right away: 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', '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:
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 tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo
...@@ -235,23 +164,14 @@ file, `config.php`, right away: ...@@ -235,23 +164,14 @@ file, `config.php`, right away:
Configure PHP to be able to send e-mails Configure PHP to be able to send e-mails
---------------------------------------- ----------------------------------------
Some parts of simpleSAMLphp will allow you to send e-mails. In 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.
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 Enable modules
-------------- --------------
If you want to enable some of the modules that are installed with 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`.
simpleSAMLphp, but are disabled by default, you should create an
empty file in the module directory named `enable`.
# Enabling the consent module # Enabling the consent module
cd modules cd modules
...@@ -270,14 +190,11 @@ to `disable`. ...@@ -270,14 +190,11 @@ to `disable`.
The simpleSAMLphp installation webpage The simpleSAMLphp installation webpage
-------------------------------------- --------------------------------------
After installing simpleSAMLphp, you can access the homepage of your 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.:
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/ https://service.example.org/simplesaml/
The exact link depends on how you set it up with Apache, and off The exact link depends on how you set it up with Apache, and off course on your hostname.
course on your hostname.
### Warning ### Warning
...@@ -292,35 +209,17 @@ like: ...@@ -292,35 +209,17 @@ like:
### Check your PHP environment ### Check your PHP environment
At the bottom of the installation page are some green lights. 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.
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 ## Next steps
You have now successfully installed simpleSAMLphp, and the next 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.
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 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)
[Setting up simpleSAMLphp as an identity provider](http://rnd.feide.no/content/using-simplesamlphp-identity-provider) - [simpleSAMLphp maintenance and configuration](http://rnd.feide.no/content/simplesamlphp-maintenance-and-configuration)
-
[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 Support
......
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