SNAportal - Installation Guide
Table of Contents
Pre-Installation Tasks
Required deployment environment
- PHP 4.3 (or better) or PHP 5.1 (or better) with SSL support
- MySQL 4.1 (or better) or MySQL 5.0
- Apache 1.3.x/2.0/2.2 for Unix or IIS 6 for Windows
- WISEBEDaai Shibboleth Service Provider (WISEBEDaai Deployment Guides)
- mod_php for Apache or PHP ISAPI for IIS
Getting the distribution
The latest distribution is available from SourceForge
SNAportal download.
Installation
Unpack the distribution
Unpack the distribution sna-portal-<version>.tar.gz
in your installation directory (i.e. INSTALL_DIR is /opt or /usr/local).
root# mv sna-portal-<version>.tar.gz <INSTALL_DIR>
root# cd <INSTALL_DIR>
root# gunzip -c sna-portal-<version>.tar.gz | tar xvf -
This should create an installation with the following installation layout.
In the sequel $AAI_PORTAL_ROOT denotes the directory $INSTALL_DIR/sna-portal-<version>
sna-portal-<version>
\-README This file
CHANGE-LOG The change log
VERSION Version information
GPL GNU General Public License
+--config Configuration files
+--web The public web application files (PHP)
| +--user The user part of the portal
| +--admin The administrator part of the portal
| +--adapters Role adapters
| \--lookandfeel Look & feel specific libraries and components
+--include Libraries need by the web application
+--i18n Localized messages used in the web portals
| +--en English messages
| +--de German messages
| +--it Italian messages
| \--fr French messages
+--db Database SQL creation and update scripts
+--tools Admin PHP scripts
\--doc Documentation
Upgrade an existing database
The current version of SNAportal can be upgraded from previous versions 1.1.X, 1.2.X, and 1.3.X of SNAportal.
If you have already an old SNAportal installation, you may choose to
keep the existing roles, users and suscriptions stored in the MySQL database.
Note: An upgrade is only possible if you are running a MySQL database version 4.1 or never
Therefore, some database scripts are provided to update your existing database (i.e. PORTAL_DB)
to the new version.
Upgrade from SNAportal version 1.3.X to 1.4.X
If you are using an old SNAportal version 1.3.X, you can simply upgrade your database, without loosing any data, for version 1.4.X
- Go in the new 1.4.X db directory and apply the SQL update script to your existing 1.3.X database:
root# cd sna-portal-1.4.X/db
root# mysql -u root -p --database=PORTAL_DB < sna-portal-db-update-1.3.X.sql
Enter Password: ***********
Where PORTAL_DB is the name of your current 1.3.X database.
Upgrade from SNAportal version 1.0.X to 1.3.X
If you are using an SNAportal version 1.0.X, you can just upgrade it to version 1.3.X
Note: Some adapters configuration may be broken after the upgrade (in particular WebCT CE and Vista adapter configurations). Please review the role adapter parameters after the upgrade process.
- Copy the scripts sna-portal-db-update-1.0.X.sql and update_user_attributes.php
in your existing SNAportal 1.0.X db directory:
root# cd sna-portal-1.3.X/db
root# cp sna-portal-db-update-1.0.X.sql update_user_attributes.php \
../sna-portal-1.0.1/db
- Go to the 1.0.1 db directory and apply the SQL update script to your existing database:
root# cd ../sna-portal-1.0.1/db
root# mysql -u root -p --database=PORTAL_DB < sna-portal-db-update-1.0.X.sql
Enter Password: ************
Where PORTAL_DB is the name of your current 1.0.X database.
- And run the PHP script to update your existing database content:
root# php update_user_attributes.php
...
Upgrade from SNAportal version 0.9.X to 1.0.X
If you are still using an old SNAportal version 0.9.X, you must first upgrade it to version 1.0.1
- Copy the scripts sna-portal-db-update-0.9.X.sql and update_role_keys.php
in your old existing SNAportal db directory:
root# cd sna-portal-1.0.1/db
root# cp sna-portal-db-update-0.9.X.sql update_role_keys.php \
../sna-portal-<old_version>/db
- Go to your old db directory and apply the SQL update script to your existing database:
root# cd ../sna-portal-<old_version>/db
root# mysql -u root -p --database=PORTAL_DB < sna-portal-db-update-0.9.X.sql
Enter Password: ************
- Run the PHP script to update your existing database content:
root# php update_role_keys.php
...
Create a new database
A new SNAportal installation requires a running MySQL database instance.
We recommend to create a dedicated database for the SNAportal. Choose
an appropriate database name , i.e. snaportal,
and create the database.
root# mysqladmin -u root -p create snaportal
Enter Password: root-password
We recommend to create a dedicated database user which the SNAportal
web application will use to access the database.
Choose a user name, i.e.
snaportal, and create the user. If you
use a GRANT statement similar to that shown below,
the new database user is also restricted to submit data manipulation
statements only.
root# mysql -u root -p
Enter Password: root-password
mysql> GRANT DELETE, INSERT, SELECT, UPDATE
ON snaportal.*
TO snaportal@localhost IDENTIFIED BY 'your-password';
Finally, create and initialize the database schema for the SNAportal
database.
Switch to the directory db in the
distribution and load the SQL file sna-portal-db.sql
into the prepared database.
root# mysql -u root -p --database=snaportal < sna-portal-db.sql
Enter Password: root-password
root#
Configure PHP
SNAportal is implemented in PHP.
It requires at least PHP 4.3.2 because it relies on the fsockopen()
metho which understands the SSL URL schema, a feature, which was
introduced in PHP 4.3.2. In addition, the following modules have to
be compiled into PHP (we give a short canonical name for the module
and a reason, why this module is required)
Required PHP Modules:
- curl - for accessing VITELS role. This module allows WebService to be used.
- mhash - for generating checksums (MD5 or SHA-1 based).
- mysql - for accessing the SNAportal database
- openssl - for accessing roles protected by SSL. This module is only necessary if the Role Adapter for WebCT courses is installed and used.
- session - session handling
SNAportal also makes use of the following optional PHP features:
- Open Short Tag - PHP code in the SNAportal
starts with the short tag
<
instead of the
long tag <?php
- No Global Variables - HTTP request parameters
and other environment parameters are expected to be available in
global arrays rather than indiviual global parameters
- Cookie based PHP Session Support - SNAportal's session
handling relies on PHP sessions with cookies.
- PHP Include Path - SNAportal's include files must
be on the PHP include path.
There are different possible places to configure these features:
- httpd.conf - Apache Configuration File
Required PHP features can also be configured in the main Apache
configuration file httpd.conf.
# Allow the <? tag. Otherwise, only <?php and <script> tags
# are recognized.
php_flag short_open_tag On
# You should do your best to write your scripts so that they do not require
# register_globals to be on; Using form variables as globals can easily lead
# to possible security problems, if the code is not very well thought of.
php_flag register_globals Off
# Session uses cookies
php_value session.use_cookies 1
# PHP include path (Unix)
php_value include_path "/sna-portal-install-dir:/sna-portal-install-dir/web"
# PHP inlcude path (Windows)
#php_value include_path "C:\sna-portal-install-dir;C:\sna-portal-install-dir\web"
If the required PHP configuration values for the SNAportal differ from
PHP configuration values for other web applications on your server you
can configure PHP specifically for the SNAportal installation directory.
Here is an excerpt from the httpd.conf
file in which PHP configuration values are set within an
Apache <Directory> directive.
<Directory "/your/install/dir/sna-portal<version>/web">
# Allow the <? tag. Otherwise, only <?php and <script> tags
# are recognized.
php_flag short_open_tag On
# You should do your best to write your scripts so that they do not require
# register_globals to be on; Using form variables as globals can easily lead
# to possible security problems, if the code is not very well thought of.
php_flag register_globals Off
# Session uses cookies
php_value session.use_cookies 1
# PHP include path (Unix)
php_value include_path "/sna-portal-install-dir:/sna-portal-install-dir/web"
# PHP inlcude path (Windows)
#php_value include_path "C:\sna-portal-install-dir;C:\sna-portal-install-dir\web"
</Directory>
- .htaccess - Per-directory configuration
The third option is to configure PHP per directory. In this case, PHP
configuration values have to be written to the respective
.htaccess
file in the SNAportal
installation directory (or any sub directory thereof, if configuration
parameters in sub-directories differ from those in the parent directory).
First, in Apache configuration file httpd.conf,
we have to make sure that we can override PHP configuration
parameters per directory:
# configure the directory with the SNAportal web application
#
<Directory "/your/install/dir/sna-portal<version>/web">
#
# IMPORTANT ! Make sure we can override PHP configuration
# and Shibboleth authentication settings in .htaccess files
# in the web directory
#
AllowOverride AuthConfig Options
</Directory>
Second, we can create (or edit the existing) .htaccess
file in the
directory /your/install/dir/sna-portal<version>/web
and set PHP configuration parameters as follows:
# sample .htaccess file in the SNAportal web directory
#
# set the PHP include path (the directories 'include' and
# 'lookandfeel' should be on this path)
#
php_value include_path ".:.." # Unix path
#php_value include_path ".;.." # Windows path
# other PHP configuration values
#
php_flag register_globals Off
php_flag short_open_tag On
php_value session.use_cookies 1
Configure Apache
Depending on your Installation Layout, the apache configuration file has to be modified.
If the directory $AAI_PORTAL_ROOT/web
is not accessible by the web server or if you want to assign it an Alias,
then you have to edit the respective configuration sections in
the Apache configuration file
httpd.conf.
In the following example we define an Alias sna-portal
under which we want the SNAportal to be accessible.
The Apache configuration file is often found in
/etc/apache/httpd.conf
but your mileage may vary.
# define an Alias for the SNAportal
#
Alias /sna-portal "/your/install/dir/sna-portal-<version>/web"
# configure the directory with the SNAportal web application
#
<Directory "/your/install/dir/sna-portal-<version>/web">
DirectoryIndex index.php
#
# IMPORTANT ! Make sure we can override PHP configuration
# and Shibboleth authentication settings in .htaccess files
# in the web directory
#
AllowOverride All
Order allow,deny
Allow from all
</Directory>
Configure SNAportal
There is only one configuration file in the SNAportal distribution
which has to be modified according to your local settings.
Edit the file config/sna-portal.config
and modify the following configuration parameters:
<?php
/* ******************************************************** */
/* SNAportal Version */
/* ******************************************************** */
/**
* The SNAportal version
*/
define('SNA_PORTAL_VERSION', '1.0.5');
/* ******************************************************** */
/* Support and Helpdesk */
/* ******************************************************** */
/**
* The SNAportal support email displayed in error message.
*/
define('SUPPORT_EMAIL', 'support@example.ch');
/**
* The SNAportal support URL displayed in error message.
*/
define('SUPPORT_URL', 'http://www.example.ch/support');
/* ******************************************************** */
/* Database Connection */
/* ******************************************************** */
/**
* The hostname or IP address of the MySQL server.
*/
//define('MYSQL_HOST', 'localhost');
define('MYSQL_HOST', 'mysql.example.ch');
/**
* The name of the database
*/
define('MYSQL_BASE', 'snaportal_db');
/**
* The MySQL username used to connect to the SNAportal database.
*/
define('MYSQL_USER', 'snaportal');
/**
* The MySQL user password.
*/
define('MYSQL_PASS', 'snaportal_password');
/* ******************************************************** */
/* URLs and Paths */
/* ******************************************************** */
/** The portal base URL. Please enter an absolute URL. This URL is used
* in HTTP redirects which is required to send absolute URLs to the
* browser
*/
define('PORTAL_BASE_URL', 'https://snaportal.example.ch/sna-portal');
/** The URL to the login script for a portal user */
define('USER_PORTAL_LOGIN_URL', PORTAL_BASE_URL . '/user/index.php');
/** The URL to the login script for a admin user */
define('ADMIN_PORTAL_LOGIN_URL', PORTAL_BASE_URL . '/admin/index.php');
/* ******************************************************** */
/* Logging */
/* ******************************************************** */
/**
* The log filename should be writable by the webserver's user.
* LOGGER_FILENAME := (filename|syslog)
*/
// define('LOGGER_FILENAME', '/var/log/sna-portal.log');
define('LOGGER_FILENAME', 'syslog');
/**
* Set the log level (integer):
* 0 := DEBUG
* 1 := NOTICE
* 2 := INFO
* 3 := WARNING
* 4 := ERROR,
* 5 := CRITICAL
*/
define('LOGGER_LOGLEVEL', 2 );
/* ******************************************************** */
/* Events Viewer */
/* ******************************************************** */
/**
* You can disable the Events for performance reason (boolean)
* If disable, then the events are not stored in the DB anymore.
*/
define('ENABLE_EVENTS', true);
/* ******************************************************** */
/* Email and Notification */
/* ******************************************************** */
/**
* The mail server used to send emails (string):
* smtp.example.ch : uses that SMTP server
* mail : constant for the local MTA (sendmail, ...)
*/
//define('AAI_PORTAL_SMTP', 'smtp.example.ch');
define('AAI_PORTAL_SMTP', 'mail');
/**
* Set to true if you want to enable automatic notification (boolean).
* Otherwise set to false.
*/
define('ENABLE_NOTIFICATION', true);
/* Set to true if you want to use a email to sms gateway (boolean) */
define('USE_SMSGATEWAY', false);
/**
* Email address of sms gateway, where gets replaced
* by the corresponding mobile number (string)
*/
define('SMSGATEWAY', "<mobile>@sms.switch.ch");
/** Maximum characters per sms (integer) */
define('MAX_SMS_LENGTH', 120);
/* ******************************************************** */
/* Languages */
/* ******************************************************** */
$I18N_AVAILABLE_LOCALES = array(
"de" => "Deutsch",
"en" => "English",
"fr" => "Français",
"it" => "Italiano",
);
?>
Post-Installation Tasks
Changing default passwords
When the database is initialized some
default users are created in the SNAportal database:
- portaladmin is the default
Portal Administrator.
- roleadmin is a sample
Role Administrator.
- subscriptionadmin is a sample
Subscription Administrator.
The initial password for both users is changeme.
It is highly recommended to change these initial passwords !
To change the initial password for the user portaladmin
- point your browser to the URL
https://snaportal.example.ch/sna-portal/admin.php
- login as portaladmin (initial password is
changeme)
- select the menu item Change Password and set
a new password
Proceed likewise to change the initial password for the user
roleadmin and for the user
subscriptionadmin.
Launching the Portal
You can now launch the SNAportal start page at the URL
https://snaportal.example.ch/sna-portal/.
This will display a web page on which you can select whether you
want to login as User or as Administrator.