Installation

Contents

2. The installation
    2.1 Language
    2.2 Installation type
    2.3 License
    2.4 Database
    2.5 Website
    2.6 User account
    2.7 Compatibility
    2.8 Confirmation
       2.8.1 Crossroads
    2.9 Finish
    2.10 Download configuration file
    2.11 E-mail alerts

3. Tips for a secure installation
    3.1 Program files and configuration file
    3.2 Data files
        3.2.1 Outside the document root
        3.2.2 Inside the document root

4. After the installation
    4.1 Virus scanning
    4.2 Session name
    4.3 Proxy friendly URLs
    4.4 Configuring cron.php

5. Errors
    5.1 Canceled installation
    5.2 Unable to write in data directory
    5.3 Config.php write problems

6. Upgrading

7. Concluding remarks

1. Introduction

We did our utmost to describe every detail of the installation. Please read this chapter. Comments and additions are welcome.

1.1 Conventions

1.1.1 General features

• Mouseovers: Almost every image, icon, button, link or data field has a mouseover text. Please hover over these items to see a short description, and explanation or shortcut key combination for an item. This user friendly feature is aimed at the novice user of a CMS.
• Shortcut keys: You do not need a mouse to work with Website@School. Items are accessible with shortcut keys that are mentioned in the mouseover. Your browsers manual will tell you which keys to press in conjunction with the shortcut keys.
• Yellow status bar: The yellow bar will give status messages, for example:

  Data folder (cannot be changed later on): filename not acceptable: 'grade 8'

  Confirmation or error messages will be displayed in this yellow bar. If necessary these messages can be copied and past in e-mail or forum posts for support.

• Pop up windows: Sometimes pop up windows are displayed together with the yellow status bar. They draw your attention and you have to turn them off to proceed. Read them, then click the [OK] button. The pop up messages are also displayed in the yellow status bar to cut and paste them.

1.1.2 Documentation conventions

• index.php, or for example Mrbh3ws!: monospaced text.
•  

  root@exemplum root]# mysql -h localhost -u root -p
  Enter password:
  

  An example of a text block with user input in bold text.
• Example: Add gray background-color: #B6B6B6; to... etc: A snippet code in a text.
• Name or, for example Expiry: The bold character of a field's title identifies the keyboard shortcut that can be used to access or modify the item. Your browsers manual will tell you which keys to press in conjunction with the bold underlined character.
• Acitve user [ ] Mark this user as active: The '[ ]' in a text indicates a checkbox.

1.1.3 web servers and folders

• The 'web server's Document Root' refers, as examples, on a Linux server to /home/httpd/htdocs or /var/www, or on Windows servers to C:\Program Files\Apache Group\Apache, i.e. the usual paths on those servers.
• The 'CMS Root Folder' is the folder that holds files like index.php, admin.php and the directory program. Usually the CMS Root Folder is the same as the web server's 'Document Root'. However, it is possible (but certainly not required) to use a subdirectory of the Document Root as the CMS Root Folder.
• The 'CMS Program Folder' only refers to the program folder and its contents.
• The 'CMS Data Folder' is the folder where all user files are stored, i.e. the files that are uploaded to the server via Website@School are kept there. This directory can be located 'anywhere' in the file system.
  It is highly recommended to place the CMS Data Folder outside the Document Root. This is a security feature.

1.2 Requirements

An easy way to install Website@School on a PC is XAMPP, described in Appendices XAMPP installation

1.2.1 Technical requirements

• Apache: version 2.0.53 or higher
• MySQL: version 4.1.x or higher
• PHP: version 4.3.10 or higher
• Memory: Enough memory to support multiple file upload. See chapter File Manager for details.

1.2.2 User requirements

You need some computer skills to install Website@School:

• Basic computer skills like downloading files and unpacking them, creating directories and copying files.
• You can work with an FTP (File Transfer Protocol) program to upload files to a server when you have no direct access to the server where Website@School will be installed. Filezilla is a good OSS/GPL FTP program. See http://filezilla-project.org/.
• You can create a database, either on the command line or with a program like phpMyAdmin. See http://www.phpMyAdmin.net/home_page/index.php.
• Working knowledge about file ownerships and permissions.
  NOTE: For security reasons it is really important to set these permissions correctly. You want a secure website at your school to protect the confidential information that will surely be stored in the data directory. Next to that you want to protect your Website@School installation and your server against intruders. Specially paragraph 3. Tips for a secure installation discusses this important subject.

When you are uncertain about your skills, it's better to ask help at a local Linux group. They are virtually everywhere and are willing to perform a small service for the school and (possibly) your kids. See http://en.wikipedia.org/wiki/Linux_User_Group

1.3 Preparations

Before you can begin with the actual installation of Website@School, a few things have to be taken care of.
Depending on whether you have root (administrator) access to the server or your server is located at an ISP (Internet Service Provider), you have to follow different routes.

Start with creating some place to download files if it not already exists.

• Installing on a server with root access: For example, use the /tmp directory for the downloads.
• On a server without root access: When the server is located at an ISP (Internet Service Provider), you have to download and uncompress the files on your own computer. In your home directory create a directory for the downloads, for example downloads.

1.3.1 Downloads

• Browse to our download location at http://download.websiteatschool.eu and download the latest versions of:
• 1. The Website@School program, e.g. the file websiteatschool-<version>.zip or websiteatschool-<version>.tar.gz[ * ].
  2. The Website@School manual, e.g. the file websiteatschool-manuals-<language>-<version>.zip or websiteatschool-manuals-<language>-<version>.tar.gz[ * ].
  3. (Optional) Download additional W@S language packs, e.g. the file websiteatschool-languages-<language>-<version>.zip or websiteatschool-languages-<language>-<version>.tar.gz[ * ].

When on a server with root access, proceed to the next paragraph. When the server where Website@School is to be installed is located at an ISP (Internet Service Provider), proceed with paragraph 1.3.3 Installing on a server without root acces

1.3.2 Installing on a server with root (administrator) access

Now that you have downloaded the necessary files, you can unpack them on the right location, the web server Document Root, e.g. /home/httpd/htdocs or C:\Program Files\Apache Group\Apache\htdocs. Proceed as follows.

• Navigate to the web server Document Root.
• Use your favorite tool to unpack the program. Assuming you have saved the downloads in the /tmp directory, use the following command to unpack a .zip file:

  [root@exemplum htdocs]# unzip /tmp/websiteatschool-<version>.zip
  

  When using .tar file, unpack with:

  [root@exemplum htdocs]# tar xzvf  /tmp/websiteatschool-<version>.tar.gz
  

  NOTE: The file is unpacked in the current directory.

• Do the same with the manual and the (optional) language file(s).
• After this operation the following files and directory are created in the web server Document Root:
  

  -rw-r--r--  1 root  root     2210 Feb  1 14:00 admin.php
  -rw-r--r--  1 root  root     7827 Feb  1 14:00 config-example.php
  -rw-r--r--  1 root  root     2204 Feb  1 14:00 cron.php
  -rw-r--r--  1 root  root     2653 Feb  1 14:00 file.php
  -rw-r--r--  1 root  root     2675 Feb  1 14:00 index.php
  drwxr-xr-x  1 root  root      824 Feb  2 10:11 program
  

  We refer to this directory as the CMS Root Folder. In this case, the CMS Root Folder is the same as the web server Document Root.

  NOTE: Even though it is strongly recommended to install Website@School in the web server Document Root, it is perfectly possible to install the program in a subdirectory of the web server Document Root. In that case the web server Document Root and the CMS Root Folder are not the same, hence the special name.

  The program directory contains the program files and directories. The manual and optional language packs were uncompressed there.

• Create the CMS Data Folder. This is a directory that holds uploaded files like images, documents, etcetera. It is very important that this directory is located outside the Document Root Folder, i.e. is not directly accessible with a browser. Note that the web server must have sufficient permissions to read, create and write files in the CMS Data Folder.
  Examples of CMS Data Folders are: /home/httpd/wasdata or C:\Program Files\Apache Group\Apache\wasdata. The name wasdata is an example. You can use any name. Here is an example of minimal permissions and ownership on the CMS Data Folder:

  drwx------ 2 www www   48 Feb  2 10:49 wasdata
  
• Create a database. The installation program is not designed to create databases (for security reasons). Use a program like phpMyAdmin, see http://www.phpMyAdmin.net, or the command line.

  When you are familiar with the Linux command line, you know how to create a database. If not, try this example which we adapted from our ServerAtSchool documentation at http://http://serveratschool.net/doc/install/configuring.html#h7.

  Below the login procedure is shown. What you enter is emphasized. The password you enter is not visible:

  [root@exemplum root]# mysql -h localhost -u root -p
  Enter password:
  Welcome to the MySQL monitor.  Commands end with ; or \g.
  Your MySQL connection id is 121 to server version: 4.0.23a
  
  Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
  
  mysql>
  

  You are logged in now and ready to create a new database, with appropriate permissions and a new user, especially for the website database that will be accessed via the Webite@School content management system (CMS). Again, the commands to type are shown emphasized in the illustration below. The password 'ohF9quei' is used as an example. You should use a password of your own choice.

  mysql> create database www;
  
  Query OK, 1 row affected (0.00 sec)
  
  mysql> grant all on www.* to wasuser@localhost identified by 'ohF9quei';
  Query OK, 0 rows affected (0.02 sec)
  
  myssql> _
  

  At this point you have created a new database named www and a user named wasuser who has been given full access to this database (but only from the host 'localhost'), provided the user produces the correct password, 'ohF9quei'.

  The MySQL database is now ready for use. You can close the connection to the database and end the mysql program:

  mysql> exit
  Bye
  [root@exemplum root]# _
  

  Examples of database names: www or example_www.

• At this point no config.php file exists. It is created during the installation.

  NOTE: After finishing the installation and uploading the config.php file, change its permissions to read for owner and group. Do not forget this! Paragraph 3. Tips for a secure installation discusses this important subject.

You are now almost ready to install Website@School. Please first read paragraph 1.4 On secure passwords, before proceeding to 2. The installation.

1.3.3 Installing on a server without root access

When your server is, for example, located at an ISP (Internet Service Provider) and you have no root access to the server, you have to upload the files and directories to the server from your computer.

We assume you have downloaded the files in the downloads directory as described in paragraph 1.3.1 Downloads, i.e. the downloads directory is in the users home directory.

• Navigate to your home directory.
• Create a directory, for example was, in which you will unpack the downloaded files.
• Navigate to the was directory.
• Use your favorite tool to unpack the program. Assuming you have the downloads in the downloads directory use your favorite tool or the command line to unzip:

  [wblade@exemplum was]$ unzip ../downloads/websiteatschool-<version>.zip
  

  And to untar:

  [wblade@exemplum was]$ tar xvzf  ../downloads/websiteatschool-<version>.tar.gz
  

  NOTE: The file is unpacked in the current directory.

• Do the same with the manual and the (optional) language file(s).
• After this operation the following files and directory are created in the current directory:

  [wblade@exemplum was]$ ls -l
  total 25
  -rw-r--r--    1 wblade  wblade   2204 Feb  3 15:04 admin.php
  -rw-r--r--    1 wblade  wblade   7821 Feb  3 15:04 config-example.php
  -rw-r--r--    1 wblade  wblade   2198 Feb  3 15:04 cron.php
  -rw-r--r--    1 wblade  wblade   2647 Feb  3 15:04 file.php
  -rw-r--r--    1 wblade  wblade   2669 Feb  3 15:04 index.php
  drwxr-xr-x   11 wblade  wblade    824 Feb  9 01:46 program
  [wblade@exemplum was]$_
  

  The program directory contains the program files and directories. The manual and optional language packs were unpacked there.

• Login to the server with an an FTP (File Transfer Protocol) program like Filezilla http://filezilla-project.org/.

  NOTE: Depending on the ISP the name of the Document Root, i.e. the directory to put the Website@School program files and directory in, differs from ISP to ISP.

• With the FTP program, navigate to the Document Root directory that will become the CMS Root Folder. In this case, the Document Root is the same as the CMS Root Folder.
• Upload all files and the directory from was to the CMS Root Folder on the server. Do not forget underlaying subdirectories in program
• Create the Data Directory. This is the directory where the CMS Data Folder will be created by the Install Wizard. The CMS Data Folder will hold images, documents, etcetera. Read the NOTEs!

  NOTE 1:
  Create the Data Directory, if possible, outside the Document Root and outside the CMS Root Folder.

  NOTE 2:
  If it is not possible to follow the NOTE 1 above, the Data Directory must be created in the Document Root.
  Give this Data Directory a difficult to guess name,'for example b27b7d81c9ea26q4885734564qda2e12. Do not use this example, but create a difficult to guess directory name.

• In the CMS Root Folder, give all files, also those in the program directory and the directories under it, read permissions for owner, group and world.
• Also in the CMS Root Folder, give all directories read and execute permissions for owner, group and world.
• Give the Data Directory enough permissions (if only temporarily) to allow the Install Wizard to create the CMS Data Root.

  NOTE
  Necessary permissions are: read, write and execute for owner, group and perhaps world, too. Once installation is complete, all write permissions of the Data Directory can be revoked again.

• At this point no config.php file exists. It is created during the installation.

  NOTE: After finishing the installation and uploading the config.php file, change its permissions to read for owner and group. Do not forget this! Paragrapfh 3. Tips for a secure installation discusses this important subject.

• Create a database, or ask your ISP to provide you with one. The installation program is not designed to create databases (for security reasons).
  Examples of database names: www or example_www.

  To create a database, you can use a program like phpMyAdmin. phpMyAdmin is a free software tool written in PHP intended to handle the administration of MySQL over the World Wide Web. It can be downloaded at http://www.phpMyAdmin.net.

  NOTE: Using a web based program like phpMyAdmin is a security risk. Do not forget to (re)move phpMyAdmin to a place where the web server has no accces to.

You are now almost ready to install Website@School. Please first read the next paragraph 1.4 On secure passwords, before proceeding to 2. The installation.

1.3.4 Installing on an XS4ALL server

XS4ALL is a Dutch ISP that offers all Dutch schools very low priced Internett access, server space and a database. Their installation procedure has, like other ISP's, its own anomalies. This type of installation is discussed in Appendices XS4ALL installation.

1.3.5 Installing on a PC with XAMPP

1.4 On secure passwords

• have at least a minimum length of 8 (eight) characters,
• have at least 1 (one) uppercase character (A-Z),
• have at least 1 (one) lowercase character (a-z),
• have at least 1 (one) digit (0-9),
• preferably have special character like: at-sign '@', hash '#', dollar '$', percentage sign '%', caret '^', ampersand '&', asterisk '*', left parenthesis '(', right parenthesis ')', dash '-', underscore '_', plus '+', equals '=', left curly brace '{', right curly brace '}', opening bracket '[', closing bracket ']', semicolon ';', slash '/', dot '.' and question mark '?'.

Please bear this in mind when entering passwords during the installation. Nuff said, time to start!

(top)

2. The installation

2.1 Language

install_language.png

The installation starts with the selection of the language in the dropdown menu. Please select a language and click [Next] to continue or [Cancel] to abort the installation.

2.2 Installation type

install_installation_type.png

• Installation scenario
  • Standard: A standard installation will be the right choice for most schools. The installer will take care of finding the right values. But, take care, and check what the installer presents in the 'Confirmation' dialogue. If necessary, you can use the [Previous] button to correct errors.
  • Custom: A custom installation is necessary when you want multiple installations of Website@School in the same database. In the database dialogue 2.5 Database an extra field is added where a prefix for each installation can be added.
• High visibility [  ]: This is a feature for blind or visually impaired persons. The installation can be performed with a braille terminal and screen reader.
  Options:
  - Checked: use a text-only user interface during installation. After the installation the Textonly skin is the default for the webmaster (guru) account.
  - Unchecked: the default after installation is the Base skin, whereafter the Braille skin or another one (Lowvision, Big or another one) can be selected in the Account Manager.

2.3 License

install_license-top.png

install_license-bottom.png

To be able to install the program, you have to accept the license agreement by typing 'I agree' (without quotes) in the field. In languages other than English, the exact wording can be found at the bottom of the license agreement.

Click [Next] to continue, [Previous] to return to the previous dialogue or [Cancel] to abort the installation.

2.4 Database

install_database.png

• Type: Select one of the available database types. At this moment the database used is MySQL. A future version may support PostgreSQL too.
• Server: This is the database server address, usually localhost. Other examples: mysql.exemplum.eu or example.dbserver.provider.net:3306.
• Username: A valid username/password-combination is required to connect to the database server. Please do not use the root account of the database server but a less privileged one, e.g. wasuser or example_www.>
• Password: A valid username/password-combination is required to connect to the database server.
• Database name: This is the name of the database to use. Note that this database should already exist; this installation program is not designed to create databases (for security reasons). Examples: www or example_www.
• Prefix:

  NOTE: This option is not available in the Standard installation, but only applies to the Custom installation.

  All table names in the database start with this prefix. This allows for multiple installations in the same database. Note that the prefix must begin with a letter. Examples: was_ or cms2_.

Click [Next] to continue, [Previous] to return to the previous dialogue or [Cancel] to abort the installation.

2.5 Website

install_website-top.png

install_website-bottom.png

• Website title: The name of your website. This name is used as name in the e-mail From: address. The name can be changed later on. Example: Exemplum Primary School.
• From: address: This e-mail address is used for outgoing mail, e.g. alerts and password reminders. If an email address is already filled out here, it is taken from the Apache web server. The address can be changed now or later. Example: wblade@exemplum.eu
• Reply-To: address::

  NOTE: This option is not available in the Standard installation, but only applies to the Custom installation.

  This e-mail address is added to outgoing mail and can be used to specify a mailbox where replies are actually read (by you) and not discarded (by the web server software).

• Website Directory: This is the path to the CMS Root Folder, i.e the directory that holds index.php, config.php, etcetera, e.g. /home/httpd/htdocs or C:\Program Files\Apache Group\Apache\htdocs.
• Website URL: This is the main URL that leads to the schools website i.e. the place where index.php can be visited. Examples are: http://www.exemplum.eu or https://exemplum.eu:443/schoolsite.
• Program directory:

  NOTE: This option is not available in the Standard installation, but only applies to the Custom installation.

  The path to the CMS Program Folder. As default setting the path is not the same as the CMS Root Folder (usually the CMS Root Folder followed by /program). Examples /home/httpd/htdocs/program or C:\Program Files\Apache Group\Apache\htdocs\program

  NOTE: Do not change this path, unless you know exactly what you are doing!

  NOTE: The folder name program should not be changed.

• Program URL:

  NOTE: This option is not available in the Standard installation, but only applies to the Custom installation.

  This is the URL that leads to the program directory (usually the website URL followed by /program). Examples are: http://www.exemplum.eu/program or https://exemplum.eu:443/schoolsite/program.

• Data directory: The Data Directory is the place where the Install Wizard will create the CMS Data Folder. The CMS Data Folder will hold uploaded images, documents, et cetera. See also 1.3.2 Installing on a server with root access and 1.3.3 Installing on a server without root access.

  It is very important that this directory is located outside the web servers Document Root [1], i.e. is not directly accessible with a browser. Note that the web server must have sufficient permissions to read, create and write files here. Examples the the CMS Data Folder are: /home/httpd/wasdata or C:\Program Files\Apache Group\Apache\wasdata.

  [1] With many ISPs (Internet Service Providers) you have no access outside the Document Root.

• Populate database [  ]: Check this box if you want to start with your new website using demonstration data.

  NOTE: We strongly advise you to check this option. The demo data are excellent for trying the modules and the numerous management possibilities of Website@School. The demo data can be made invisible and erased later on if necessary.

  NOTE: When not installing demodata, you have to at least add one page to avoid a Fatal Error:

  
  

  install_fatal_error.png

  Please see the Page Manager chapter on adding a page.

• Demonstration password: The same demonstration password will be assigned to all demonstration user accounts. Please choose a good password as described in paragraph 1.4 On secure passwords. Minimum requirements are at least: characters: 8, digits: 1, lowercase: 1, uppercase: 1. You can leave this field blank if you did not check the Populate database box above.

Click [Next] to continue, [Previous] to return to the previous dialogue or [Cancel] to abort the installation.

2.6 User account

install_user_account.png

• Full name: Please enter your own name or, if you prefer, another (functional) name, e.g. Wilhelmina Bladergroen or Master Web.
• User name: Please enter the login name you want to use for this account. You need to type this name every time you want to login. Examples: wblade or webmaster.

  NOTE A user name consists of maximum 16 characters: lowercase (a-z), digits (0-9), underscore (_)and starts with a letter.

• Password: Please choose a good password as described in paragraph 1.4 On secure passwords. Do not share your password with others, but create additional accounts for your colleagues instead.
• E-mail address: Please enter your e-mail address here. You need this address whenever you need to request a new password. Make sure that only you have access to this mailbox (do not use a shared mailbox). Alerts are send to this address. Examples: w.bladergroen@exemplum.eu or webmaster@exemplum.eu.

Click [Next] to continue, [Previous] to return to the previous dialogue or [Cancel] to abort the installation.

2.7 Compatibility

install_compatibility.png

Below is an overview of required and desired settings. You need to make sure that the requirements are satisfied before you continue.

NOTE: Required items have an '*' asterisk.

• Website@School: Please check if you have the latest version. It could be necessary to upgrade after an installation.
• web server: * You need Apache version 2.0.53 or higher.
• Database server: * You need MySQL version 4.0.23a or higher.
• PHP version: * You need PHP version 4.3.10 or higher.
• Automatic session start: * The right value is 'NO'. If a wrong value is shown, you should edit the php.ini file.
• PHP Safe Mode: The PHP safe mode is an attempt to solve the shared-server security problem. It is architecturally incorrect to try to solve this problem at the PHP level, but since the alternatives at the web server and OS levels aren't very realistic, many people, especially ISP's, use safe mode for now. This feature has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged. Source: http://php.net/manual/en/features.safe-mode.php.

  NOTE: Not required but strongly advised. In php.ini set safe_mode = Off.

• File uploads: It must be possible to upload files to the CMS Data Folder. If not correct, the CMS Data Folder may have wrong ownership and/or permissions.

  NOTE: Take care! Do not set this folder world readable!

• GD Support: GD is an open source program for the dynamic creation of thumbnails. GD creates PNG, JPEG and GIF images, among other formats. The thumbnails are used in the FCK and CK editors.
• Clamscan anti-virus: Clamscan is used to scan uploaded files for viruses. It is highly recommended to scan all uploaded materials from those home or school computers, used by everyone, for viruses.

2.8 Confirmation

install_confirmation-top.png

install_confirmation-bottom.png

You are about to install your new website. Carefully check the configuration settings. Please do as suggested and print this page for future reference.
Thereafter you can press [Next] to start the actual installation process or press [Previous] to correct errors, or [Cancel] to abort the installation.

The installation process may take a while.

2.8.1 Crossroads

1. The configuration file config.php was automatically written to the CMS Root Folder. You see a picture as in 2.9 Finish. Proceed from there.
2. The configuration file config.php was not automatically written to the CMS Root Folder and it must be put there by hand. Please proceed with paragraph 2.10 Download configuration file.

2.9 Finish

install_finish.png

The installation is finished.
It's not a bad idea to check for updates or bug fixes. We assume your version is up to date. Proceed by selecting an item from the dropdown menu:

Jump to:

• admin.php: The default option to login.
• index.php: The location of the school website.
• manual.php: The location of the manual.
• http://websiteatschool.eu: Our location where you can find more about Website@School.

Or click [OK] to go to the default destination: the admin.php login dialogue.

install_login.png

2.10 Download configuration file

install_finish_download.png

To download the file config.php, proceed as follows:

• Click the Download config.php link.
• A download window opens on your computer:
  
  

  install_finish_download_save.png

  Select the was directory on your computer (see also 1.3.3 Installing on a server without root access) to save the config.php file.

• With an FTP program, upload the file to the CMS Root Folder.
• Check the file permissions and ownership. Permissions 0400 and user wwww and group root are safe. For further details on the security of this important file that contains your database password, see 3. Tips for a secure installation

Jump to:

• admin.php: The default option to login.
• index.php: The location of the schools website.
• manual.php: The location of the manual.
• http://websiteatschool.eu: Our location where you can find more about Website@SChool.

Or click [OK] to go to the default destination: the admin.php login dialogue:

install_login.png

2.11 E-mail alerts

  -------- E-mail Message --------
From: Exemplum Primary School <webmaster@exemplum.eu>
Subject: Alerts for website Exemplum Primary School: 1
To: webmaster@exemplum.eu (Wilhelmina Bladergroen)

2014-07-22 12:50:17
Initial installation of demodata, including this test message.
You will receive an alert at most once every 1440 minutes (1 day).
Alerts will trigger on a change in any area.
Alerts will be mailed to this address:
webmaster@exemplum.eu (Wilhelmina Bladergroen)

  -------- E-mail Message --------
From: Exemplum Primary School <a.cackle@exemplum.eu>
Subject: Alerts for website Exemplum Primary School: 1
To: a.cackle@exemplum.eu (Amelia Cackle)

2014-07-22 12:50:17
Initial installation of demodata, including this test message.
You will receive an alert at most once every 60 minutes (1 hour). 
Alerts will only be sent for changes on the intranet
Alerts will be mailed to this address:
a.cackle@exemplum.eu (Amelia Cackle)

(top)

3. Tips for a secure installation

This paragraph discusses the points to check for a secure installation. However, it is impossible to describe all possibilities and their exceptions. Do not hesitate to ask help from a local Linux group or ask for support.

All program files of Website@School are installed in the so called CMS Root Folder. The CMS Root Folder is often the same as the web server Document Root. However, it is also possible to use a subdirectory of the web server Document Root instead.

Furthermore, for a good installation a separate Data Directory is necessary. After installation is complete, this Data Directory will contain the CMS Data Folder.

3.1 Program files and configuration file

-rw-r--r--  1 root  root     2210 Feb  1 14:00 admin.php
-rw-r--r--  1 root  root     7827 Feb  1 14:00 config-example.php
-r--------  1 www   root      754 Feb  1 11:10 config.php
-rw-r--r--  1 root  root     2204 Feb  1 14:00 cron.php
-rw-r--r--  1 root  root     2653 Feb  1 14:00 file.php
-rw-r--r--  1 root  root     2675 Feb  1 14:00 index.php
drwxr-xr-x  1 root  root      824 Feb  2 10:11 program

The CMS Program Folder program/ contains dozens of files and subdirectories. Together these form the Website@School program.

Finally, there is the configuration file config.php. This file (which is created by the Install Wizard) must be placed in the same directory as the other files, i.e. in the CMS Root Folder.

It is sufficient for the web server (Apache) to only have read permissions on all these program files and subdirectories. This also applies to the configuration file config.php.

Security wise it is best to make sure that the web server (Apache) has no write permissions on these program files and (sub) directories. This also applies tot the configuration file config.php.

For additional security and protection of the data in config.php it makes sense to limit the permissions on that file even further.

On a Linux server it speaks for itself to set these read- and write permissions as follows:

- All files, with the exception of config.php, get permissions 0644 and are owned by user root and group root.
- Al directories get permissions 0755 and are owned by user root and group root.
- The file config.php gets permissions 0400 and becomes owned by user www and group root.

NOTE 1:
It is also possible to give the files (except config.php) permissions 0444 and the directories permissions 0555, but this adds factually little when the files are owned by user root, because anyhow user root has all permissions, also write permissions, on any file.

NOTE 2:
In this example user www is used as the account under which the web server (Apache) is running. Depending on the specific system, this can also be the user apache or nobody. Please consult the documentation and/or configuration of the web server.

NOTE 3:
The file config.php is a case on its own. This file contains the database password. For that reason it is good to only and exclusively give the web server (Apache) read permissions on this file and no other user or group.

NOTE 4:
If it is not possible to make the files (except config.php) and directories owned by user root and group root, then it is also possible to choose another user and group, as long as it is not the web server user and group for that purpose. Permissions 0644 or 0755 are usable.

3.2 Data files

For security reasons the installer creates a subdirectory inside this directory: This we call the CMS Data Folder. The full path of the CMS Data Folder is the Data Directory path followed by a difficult to guess directory name of 32 letters and digits, for example: /home/httpd/wasdata/b27b7d81c0ea26c4885784564bda2e11.

It is necessary that, during the installation, the web server (Apache) has read-, write- and execute permissions in the Data Directory (for example wasdata), in order to create the CMS Data Root.
After finishing the installation the write permissions can be minimized, as long the read and search permissions for the web server remain.

3.2.1 Outside the document root

Example 1:
On the Linux server /home/httpd/htdocs is the web server Document Root. In that case a secure choice for the Data Directory is /home/httpd/wasdata. This results in:
- Data Directory: /home/httpd/wasdata
- CMS Data Folder: /home/httpd/wasdata/fa0aff7743cd61f2afb473ca528fd431

During the installation, the Data Directory must have permissions 0700 with user www and group root. After finishing the installation, it is sufficient to set the permissions of this directory to 0500 with user www and group root.

Example 2:
On a Linux server /var/www is the web server Document Root. The Data Directory could be located in /var/wasdata. This results in:
- Data Directory: /var/wasdata
- CMS Data Folder: /var/wasdata/fa0aff7743cd61f2afb473ca528fd431

During the installation, this Data Directory should have sufficient file access permissions, e.g. by -- temporarily -- elevating permissionss to 0777, with user wblade and group users. After finishing the installation, it is sufficient to set the permissions of this directory to 0555 with user wblade and group users.

User wblade is Wilhelmina Bladergroen, the systems administrator of the Exemplum Primary School. For explanation on this user and the school see the ServerAtSchool documentation at http://serveratschool.net/doc/manual/overview.html#h2

NOTE: The permissions and ownership of the underlying directories created by the Installation Wizard, must remain as they are. Here is an example:

drwx------  3 www www    240 Feb  6 13:53 fa0aff7743cd61f2afb473ca528fd431

3.2.2 Inside the document root

Example 1:
On a Linux server /home/httpd/htdocs is the web servers Document Root. If the Data Directory and hence the CMS Data Folder is to stay in there, then b27b7d81c9ea26q4885734564qda2e12 looks like a good, difficult to guess subdirectory name. This results in:
- Data Directory /home/httpd/htdocs/b27b7d81c9ea26q4885734564qda2e12
- CMS Data Folder: /home/httpd/htdocs/b27b7d81c9ea26q4885734564qda2e12/fa0aff7743cd61f2afb473ca528fd431

The permissions of the Data Directory during the installation are 0700 with user www and group root. After the installation permissions 0500 with user www and group root are enough.

Example 2:
On a Linux server /var/www is the web servers Document Root. If the Data Directory and hence the CMS Data Folder is to stay in there, then b27b7d81c9ea26q4885734564qda2e12 looks like a good, difficult to guess directory name. This results in:
- Data Directory: /var/www/b27b7d81c9ea26q4885734564qda2e12
- CMS Data Folder: /var/www/b27b7d81c9ea26q4885734564qda2e12/fa0aff7743cd61f2afb473ca528fd431

During the installation, the Data Directory has --temporarily-- permissions 0777 with user wblade and group users. After the installation it is sufficient to set back the permissions of this directory to 0555 with user wblade and group users.

User wblade is Wilhelmina Bladergroen, the systems administrator on the Exemplum Primary School. For explanation on this user and the school see the ServerAtSchool Documentation at http://serveratschool.net/doc/manual/overview.html#h2

NOTE: The permissions and ownership of the underlying directories created by the installation wizard, must remain as they are.

3.3 Further information

NOTE: Before making use of your installation, please also read the next section to check some of the configuration items that affect security.

(top)

4. After the installation

4.1 Virus scanning

First check at [  ] Scan files for viruses on upload if the box is checked. Then perform the following test to verify the correct operation of the virus scanner by creating a special 'test virus'. There is a standard test, developed explicitly for testing anti-virus programs. It was developed by the European Institute for Computer Anti-Virus Research (EICAR). You can easily create this test using any text editor. The test file consists of 68 plain ASCII characters as shown below. Note that the 3rd character is a capital 'O' and not the digit '0'.

X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*

Now store these 68 characters in a file. Do not name the file EICAR.COM as suggested by the Institute, because by default the file extension .com is a not allowed extension in Website@School. Maliciously we rename the file to image.png, so it will be accepted and uploaded to your My Files location.
The virus should be detected and an error message must be generated like:

install_after_install_virus.png

The virus scanner is properly installed and found during installation because the virus was detected and not uploaded.
However, if the virus scanner for some reason is not working properly during the upload, a message like the following is displayed. NOTE 'Error 2'.

Filename(1): Error 2 while scanning for viruses, file 'other_image.bmp'
Files added: 0, files ignored: 1 .

If a virus is found, the webmaster receives an e-mail like the one we found on our public Website@School test site. For details and login, please see chapter Basic procedures for beginners, paragraph 7.2 Our sandbox).

  -------- E-mail Message --------
From: Exemplum Test Site <jtester@wexample.org>
Subject: Virusalert for website Exemplum Test Site: attempt to upload virus
To: jtester@example.org (Exemplum Test Site)

There was an attempt to upload a file containing
a virus. The output of the virusscanner is as follows:

/tmp/php1DGFo: PHP.Trojan.Agent-8  FOUND

----------- SCAN SUMMARY -----------
Infected files: 1
Time: 0.002 sec (0 m 0 s)

The currently logged in user was

Jane Tester (jtester)

and the file was /tmp/phpP1DGFoj (b374k.php).

Kind regards,

Your automated webmaster

In a future release the senders IP address will be added, so you do not have to look up his IP address in the Website@School log file.

NOTE: Do not forget to keep the virus scanner on the server up to date!

More information on EICAR.COM can be found on the EICAR web site at http://www.eicar.org/anti_virus_test_file.htm.

Note that this EICAR.COM file in itself is a valid but harmless DOS program. When executed (in a DOS box), it simply displays the text 'EICAR-STANDARD-ANTIVIRUS-TEST-FILE!', nothing more.

This sub paragraph on testing with a virus is gracefully copied and slightly adapted from http://serveratschool.net/doc/, the ServerAtSchool Documentation, where the installation of a secure school server is discussed.

4.2 Session name

4.3 Proxy friendly URLs

4.4 Configuring cron.php

It is necessary for Website@School to periodically perform some housekeeping chores. This is done by calling or executing the file cron.php. The exact installation of the cron-job depends on the server where you installed Website@School and the privileges you have on that server.

A few options may exist:

• Root Access: if you have root privileges on the server, you can easily add a cron-job to the system's crontab.

  # websiteatschool cron.php runs every half hour 7,37 * * * * www /usr/bin/php /home/httpd/htdocs/cron.php

  In this case cron.php is called twice per hour, on .07 and .37 minutes after the hour. Note that this cronjob is executed as user www. This is a security measure.

• No Root Access: if you are limited to a regular user account, i.e. without direct access to the system's crontab, you can still add a cronjob to your personal crontab.

  # websiteatschool cron.php runs every half hour 7,37 * * * * /usr/bin/php /home/httpd/htdocs/cron.php

  Note that a personal crontab does not allow you to specify the user account to be used to run the cronjob; in this case cron.php is executed using your personal user account on the server instead of the www-user. This may or may not be possible due to file ownerships and privileges.

• wget: if the options mentioned above are not feasible, you can resort to using wget. This command line tool is able to download any file from the World Wide Web, including cron.php. Because wget accesses cron.php via the webserver, there is no problem with missing privileges or file ownership. You could add an entry to your personal crontab as follows.

  # websiteatschool cron.php runs every half hour 7,37 * * * * /usr/bin/wget -q -O /dev/null http://exemplum.eu/cron.php

• Ask you ISP: if all else fails, you could ask you ISP or your systems administrator for help with installing a cronjob that periodically calls your cron.php.

NOTICE:
It is not necessary to call cron.php from the same server that hosts your Website@School installation; you can easily use wget from any other server in the world to periodically execute cron.php.

See also section 4.1 Site configuration in chapter Configuration manager for two configuration items dealing with cron.php.

(top)

5. Errors

5.1 Canceled installation

Click [OK] to return to the language selection. It is possible to download the config.php file. See paragraph 2.10 Download configuratoin file.

5.2 Unable to write in Data Directory

Error: Data directory: directory can not be created: /home/httpd/htdocs/wasdata/6a69137e2689c8f91873e0634ca46bda.

You get the same type of errors when the file permissions are too low (for example 000 or 600). Here is an example of minimal permissions and ownership:

drwx------ 2 www www  48 Feb  3 16:49 wasdata

5.3 Config.php write problems

[1] For example when Website@Schools CMS Root Folder has permissions like:

dr-x------  3 www www    240 Oct 21 13:53 htdocs

It is impossible to write in the directory.

(top)

6. Upgrading

(top)

7. Concluding remarks

(top)