Workshop (CREW)

2. CREW for pupils and teachers
    2.1 Add a CREW page
        2.1.1 Header and Introduction
        2.1.2 Visibility: World or Authenticated
        2.1.3 Visibility: Individuals
    2.2 Who sees what?
    2.3 Enter CREW
    2.4 "It does'nt work!"
    2.5 Advanced options

3. CREW for the webmaster
    3.1 Configure CREW
    3.2 Check your work

4. CREW for the systems administrator
    4.1 Which server and port?
    4.2 Firewalls
    4.3 Server installation
        4.3.1 The readme.txt
        4.3.2 The crewserver-example.conf text
        4.3.3 Init script
        4.3.4 /var/log/messages
        4.3.5 Help!
    4.4 "After x I got y"

1. Introduction

1.1 Assumptions

1.2 NOTICE!

1.3 Features and limitations

• Collaborate in the school's own cloud (when the CREW server is installed on the school server).
• CREW page access permissions can be changed by members of the workgroup, i.e. non-webmasters. This feature enables the group to publish pages.
• Each user has their own text color and cursor.
• Skins to accomodate visually impaired users.
• Created texts can be cut and paste from the page. Other tools on the Internet can be used to convert the content. In this way it is, for example, possible to collaborate in LaTeX.
• Password security on server and client.
• Maximum number of workshops: in the configuration file set at 7; maximum: 32.
• Maximum number of users per workshop: in the configuration file set at 3; maximum: 26.
• Built-in chat with on/off audio signal when messages arrive. Chat messages cannot be saved.
• Full UTF-8. BMP (please see 1.4 Backgrounds below) is supported.
• Pure JavaScript is used. No JQuery, Pyjamas or other frameworks or (tool)kits.
• Only PHP, JavaScript, HTML5 and BSS (Bazaar Style Style) are used (please see 1.4 Backgrounds. below)

• CREW opens in a new window. This requires enabling popup windows in the browser.
• Maximum text length: 65536 characters (64 kB). This is about 30 A4 pages of unformatted text. For details, please see 2.3 Enter CREW,
• The way CREW opeates, somtimes causes a short lag.
• CREW sends its data unencrypted over the Internet. In the next version we will use encryption.
• CREW is designeed to operate with the Firefox browser, which is available for Linux, Mac and Winodows. Firefox uses OS (Open Standards) and is OSS (Open Source Software), complying to W3C standards, which cannot be said for Window's' Internet Explorer and Mac's Safari.
  Preferably use the latest version. For a list of versions that support the websocket protocol, please see http://caniuse.com/websockets.
• To our regret, the use of JavaScript makes CREW unusable for text-only browsers used by blind users. Hopefully this will change in the near future.

1.4 Backgrounds

(top)

2. CREW for pupils and teachers

• you have read and done the Basic procedures for beginners,
• the schools systems administrator has correctly setup and configured the CREW server,
• the schools webmaster has correctly configured CREW in the Module Manager and,
• last but not least, to be able to read with certain privileges and to edit you must have an account.

2.1 Add a CREW page

In the Page Manager, select the Area or section and click on the Add a page link to enter the Add a page dialogue:

workshop_CREW_module_add.png

Fill out the fields as described in Page Manager, paragraph 3.1 Add a page.
In the Module dropdown menu, select the module. Do not forget to select Visible, Hidden or Embargo. Click [Save] to save your work and return to the Page Manager.
Now click on the Page Name to enter the Module Name (modulename) configuration dialogue. In the next paragraph the module will be configured.

2.1.1 Header and introduction

workshop_CREW_page_configuration_header_intro.png

in the Menu the link Content is selected.

• Header: example Dolphins. Enter a short text that will be visible as header for this page. If nothing is entered, there will be no header. When selecting the Advanced link, you can add style elements to the header in the 'Extra style at page/section level', for example:
  

  /* Blue header text */ .crew_header { color: #0000FF; }

  to create a blue font color.
• Introduction: Enter an introduction text. If nothing is entered, there will be no introduction. HTML markup can be used, as example:

  Hi there!<br> We, Catherine, Honorine and Herbert, are working on a text about dolphins. Maybe you know more about them. <p> <strong>Please</strong> help us! </p>

  Later on we will hear more about Honorine Hermelin Grønbech (username honorine), the dolphins expert.

2.1.2 Visibility: World or Authenticated

workshop_CREW_page_configuration_visibility_world_authenticated.png

• World: On a public Area, any visitor can view this page. On a Private Area (Intranet) those visitors who can login can view this page.
• Authenticated: Anyone who can login on the site can view this page. On a Private Area (Intranet) anyone who can login and has read permission can read this page.

2.1.3 Visibility: Individuals

workshop_CREW_page_configuration_visibility_individuals.png

Explanation:

• Individuals: Only when this option is selected, the options for the users and their permissions are applicable.

  In the screenshot above, the webmaster and Guru Wilhelmina Bladergroen has created this CREW page. This has the following consequences for the:
  List of users and permissions:

  Users:

  • For the GURU, all accounts in the EPS school (i.e. the demonstration data) are displayed and permissions can be set.
  • Wilhelmina appears in the list twice. Once as normal user, having selectable permissions and once as Guru (greyed out because of her role as webmaster, thus Guru, thus by default always having all permissions).

  Permissions:

  • --: This user has no permissions at all, cannot read, cannot edit.
  • Read: This user has read permission and can read this page.
  • Read and edit: This user has read and write permissions. This means that she has access to selecting a skin and she has an [edit] button to enter the CREW editor, edit texts and chat.
  • Guru: In this module this option is not used.
• Greyed out user and dropdown menu with 'Guru': This user is the webmaster account, i.e. the person that installed Website@School, i.e. Guru, i.e. Wilhelmina Bladergroen. She is Guru by default, can read everything, which cannot be changed. This is normal.
• Save: After saving your work, you return to the Page Manager opening screen. The page is added.
• Cancel: To cancel your action and return to the Page Manager opening screen

workshop_CREW_page_configuration_visibility_individuals-herbert.png

Herbert belongs to the group Juniors which consists of pupil Georgina and teacher Helen. Herbert can change these permissions.
However, he does not belong to the group Seniors, so he can neither change the permissions of Catherine Hayes or any other member of that group, nor can he change the permissions of Honorine, the dolphins expert, who just received an account to visit the website and get access to the dolphins page via MyPage on the site. Honorine did not receive any permissions in her Admin and Page Manager.
For details of the EPS groups, please see 1.3 The Exemplum Primary School in the Account Manager.

2.2 Who sees what?

For the Dolphins project Wilhelmina has set the page permissions as follows:

workshop_CREW_page_dolphins_perms_set-wblade.png

Individuals selected, Catherine, Herbert and Honorine have Read and edit permissions, all other EPS users have none.

workshop_page_conf_anon_visitor.png

CREW page on the Area of Grade 8. No header, no introduction, no text, just: Sorry, you currently have no permissions to view this page.

This is the Dolphnins page as seen by:

• an anonymous visitor visiting the page. When the visibility is set to Authenticated (only users with an account) or Individuals (only users in the list); and
• Helen Parkhurst. Why? She can login, has read permissions on the Exemplum Intranet, because she is a member of the faculty group, but ...
  her permissions were accidentally left on -- (none) in the CREW configuration page.

workshop_page_conf_read_perms.png

Same page. The header, introduction and text are visible.

This is the Dolphins page as seen by:

• Helen Parkhurst when her permission was finally set to Read and edit in the CREW page configuration, and
• Freddie Frinton, i.e a user who can login and
• an anonymous visitor AFTER the visibility is set to World.

workshop_page_conf_readwrite_perms.png

Yellow status message: Last updated: yyyy-mm-dd hh:mm:ss by Firstname Lastname (username), header, introduction, text, Last updated: yyyy-mm-dd hh:mm:ss by Firstname Lastname (username), Skins dropdown menu (default: Base), [Edit] button.

This is the Dolphins page as seen by:

• Catherine, Honorine and Herbert, i.e. the users that have Read and edit permissions on the page, set in the Workshop (CREW) configuration.

2.3 Enter CREW

workshop_CREW_skin_base_catherine.png

Explanation:

• Text pane: Most of the screen space is used to create or modify text. Each user has her/his own cursor and text color.

  Occasionally, when typing text, there is a short lag, for example, , disappearing within a second or so.

  Maximum text length: 65536 characters (64 kB). This is about 30 A4 pages of unformatted text. If a document exceeds this limit, the buttons [Save] and [Save+Edit] refuse to save the text above the 64 kB. An error message in the chat pane; example:
  hh:mm ERROR: document is too large (67568 characters), maximum is 65536. Nothing is saved but the already written text is retained and the user remains in the CREW editor.

• Users pane:
  • CREW: The name of the editor. A mouseover shows the unabridged name of the editor, its version number and date.
  • Workshop name: The header text is used. A mouseover shows the full URL path to the page.
  • Full user name: The name of the user. The color of the name indicates the cursor color for this user. A mouseover shows this user's IP address, port number and color=A.

    color=A is the color of the first user. The maximum number of users is 26 (a-z), each with their own color.

  • Full user name + login name: The (small) user name is not colored, the user name has the cursor color as background to emphasize it. The list of users can be longer. Default in the configuration file is 3. A mouseover shows the full user name, the user name and color A.
  • Save: To save your work and return to the page with header, description and saved text. A mouseover gives a short explanation of the buttons function.
  • Save+Edit: When saving, you stay in the CREW workshop. Because all your modifications, and those of others, travle over the Internet, it is a good idea to often save your work. A mouseover gives a short explanation of the buttons function.
  • Cancel: Your last changes are not saved. You return to the page with the header and introduction. A mouseover gives a short explanation of the buttons function.
  • Refresh: Retrieve a fresh work copy of the document that is currently edited by all the page users. A mouseover gives a short explanation of the buttons function.
• Chat pane: The chat can be used to send messages about the text, thus keeping the text clean.
  • Chat text entry field: Type your text here and hit the [Enter] key on your keyboard to send text to all participants.
  • Send: Sends your message to all participants. It is much easier to hit the [Enter] key on your keyboard. A mouseover gives a short explanation of the buttons function.
  • Speaker icon: On/off toggle for the beep. If off, a red cross is visible in the speaker icon. A mouseover gives a short explanation of the buttons function.
  • Messages field: Chat messages cannot be saved. This is a feature. The window of the chat messages is 120, whereafter the oldest disappears as the newest is added. The 120 messages can of course be saved with cut and paste.

    The messages field shows:

    • Chat messages sent by you and the other users of this page.
    • System status and error messages.

Herbert has also entered the CREW page and gives his input. He uses the LowVision skin:

workshop_CREW_skin_lowvision_herbert.png

And Honorine uses the RedGreyBlue skin:

workshop_CREW_skin_redgrayblue_onorine.png

When they terminate the session, Catherine was the last one who edited and saved. Also notice the yellow status message:

workshop_CREW_page_dolpins_savedby_catherine.png

Try the Mondriaan skin, named after the famous Dutch painter Piet Mondriaan (Amersfoort, 7 maart 1872 - New York, 1 februari 1944) yourself.

2.4 "It doesn't work!"

Some reasons why CREW does not work, even with Firefox:

• Popup windows disabled: This is the most common error. CREW opens in a new window. Popup windows were blocked and maybe you overlooked the message in the upper part of the browser:
  

  workshop_CREW_popup_disabled.png

  To enable popup windows, click on the Preferences button and select: Allow popups for (for example) exemplum.eu.
  To enable popup windows permanently, go: Menu > Edit > Preferences > Content: uncheck 'Block popup windows'.

• Browser support: Does your version of Firefox support the websocket protocol? Check your current version by, in the menu selecting Help > About Firefox to find out the version number. Next, check the list on the Can I use Websockets? page.
• Javascript: Javascript must be enabled. See Firefox: Menu > Edit > Preferences > Content: check 'Enable Javascript'.
• CREW does not work with Windows Internet Explorer (IE is not standards compliant (as usual)), on Mac's Safari (it seems unable to open specific ports, even Mac users complain), Chrome (unknown causes, please tell us).
• Check if the CREW server is actually running. Go to the website where the server is located and enter URL; if the port number is not 80, the port number in the browser, for example http://exemple.eu:8008 or http://anotherserver.org. When you receive the message '404 Bad request', the CREW server is functioning because this message is generated by the CREW server.
• If you do not happen to have a CREW server at all, you can do a simple browser test on:
  http://www.websocket.org/echo.html.

2.5 Advanced options

(top)

3. CREW for the webamaster

3.1 Configure CREW

workshop_module_configuration.png

Explanation:

• Origin: For example http://exemplum.eu. This parameter MUST match the location of the website as seen in the browser of a website visitor.

  NOTICE:
  If Website@School is not installed in the servers document root or operates on a port differing from port 80 but, for examples in: http://exampleschool.org/was or http://exampleschool.org:8008 or http://exampleschool.org:8008/was.

  In those cases http://exampleschool.org or http://exempleschool:8008 must be entered in this field.

• Location: For example ws://exemplum.eu:8008. This URL MUST point to the CREW Websocket server you are using for this module.
  This could be the school server, using another port than port 80, for example a non-standard port 8008 ws://www.yourserver.org:8008 or another server at standard port 80, as example ws://www.anotherserver.org.
• Secret key: example ThisIsTheSharedSecret.
  This entry MUST match the secret code in the CREW Websocket server the school is using. If this server is not under your control you have to ask the owner of the server to obtain a valid secret code.
  

  NOTICE:
  The secret key is visible in plain text, not masked with asterisks. This feature enables you to check and coordinate this code with the systems administrator.

• Save: After saving your work, you return to the Module Manager opening screen.
• Cancel: To cancel your action and return to the Module Manager opening screen

3.2 Check your work

NOTICE:
This test must be done on two workstations, each with their own browser. One for the webmaster Wilhelmina Bladergroen (username: wblader) and one for user Herbert Spencer (username: herbert).
Reason for two PC's: you cannot be logged in and, at the same time on the same browser, be logged out. This is a feature of the browser.
The workstation for the webmaster can be an old one, with an old browser that does not support CREW.

Proceed as follows:

• As wblader, login on the old workstation.
• Use the 'Exemplum Inactive' Area to create a new CREW page. Make the Area active so it can be seen by anyone.
• In the CREW page content, set 'Visibility' on 'Individual'. Do not give anyone any permissions (--) on the CREW page.
• In the Page Manager, in the Area 'Exemplum Inactive', grant Herbert permissions to manage the page, for example Sectionmaster.
• Go to the new workstation and, as anonymous visitor, select the 'Exemplum Inactive' Area and check the newly created CREW page. You should see:
  

  workshop_CREW_test_anon_visitor.png

  Notice that only the page name is visible for the anonymous visitor.

• In the CREW page content, set the visibility of the page to 'Authenticated'.
• Go to the site and refresh the page (F5) and check that the anonymous visitor still has no information, just the page name.
• Now login as Herbert Spencer (username herbert). This can be done in two ways:
  • Use the Area selector, got to the Exemplum Primary School Area, use the MyPage link to log in. Then switch to 'Exemplum Inactive'.
  • In the URL bar, type as example http://exemplum.eu/index.php?login=1. You are on the log in screen and can log in.
  Do not login via http://exemplum.eu/admin.php which gives access to Website@School management.
• After logging in, surf to the CREW page and observe:
  

  workshop_CREW_test_auth_visitor.png

  Herbert can see some information, i.e. the header and the introduction. There is no text in the rectangle because Wilhelmina hasn't put any text in there.
  Notice: there is no dropdown menu for the skins and no [Edit] button.

• Now in the Workshop (CREW) configuration, grant Herbert 'Read and edit' permissions. Save your work.
• Surf to the CREW page on the site or press F5:
  

  workshop_CREW_test_auth_read-write_visitor.png

  Herbert now has permissions to edit the page and can also see when and by whom the page was changed the last time.

  Wilhelmina does a short test:

  

  workshop_CREW_test_auth_read-write_visitor_edited.png

Wilhelmina doesn't forget to set the test area to inactive.

(top)

4. CREW for the systems administrator

4.1 Which server and port?

The CREW websocket server is in fact a small server program. It can be installed on several locations:

• When installing on the school server, port 80 is already occupied by the existing Apache webserver, serving Website@SChool. Thus the CREW server must make use of another free and unassigned port. Default configuration for the CREW websocket server is port 8008.
  

  NOTICE:
  The firewall must be opened for this port. See paragraph 4.2 Firewalls below.

  NOTICE:
  Some website visitor have modems that are configured to block traffic on certain ports. Experience indicated that these users cannot make use of Workshop CREW on port 8008. If you want to avoid this problem, you have to use the next option.

• Run the CREW server on another server on port 80. Perhaps the school has more IP adresses and can setup another server, or maybe the Board's office has extra IP adresses to facilitate all the schools under their jurisdiction.
• A second IP address on the same server, serving port 80. You are an experienced Linux Guru and perfectly know how to do this. Unexperienced users, Google and search for ifcfg multiple ip address and go to your local Linux User Group (LUG). They are virtually everywhere and are most willing to perform a small service for the school that (probably) teaches their children.
• There may be other solutions. Please tell us.

4.2 Firewalls

ServerAtSchool uses the GIPTables firewall. From the blurb: "GIPTables Firewall is a free set of shell scripts that helps you generate iptables rules for Linux 2.4.x and newer kernels. It is very easy to configure and at present, designed to run on hosts with one or two network cards. It doesn't require you to install any additional components to make it work with your GNU/Linux system. All you need to set-up a very secure firewall for your GNU/Linux machines its iptables and GIPTables Firewall."

When you you use GIPTables, you only have to add this to your /etc/rc.d/rc.giptables.custom file, before the line
# ---- THE END OF THE FIREWALL ----, save and restart the firewall with service giptables restart.

# --- begin open poort 8008 ---
# 2012-12-19/PF

for WS_PORT in 8008; do
   echo -ne "\n - with support for port $WS_PORT on $INTERFACE1_IPADDR
 and $INTERFACE0_IPADDR"

    $IPTABLES -A interface1_in -p TCP \
        -s $ANY_IPADDR --sport $UNPRIV_PORTS \
        -d $INTERFACE1_IPADDR --dport $WS_PORT \
        -m state --state NEW,ESTABLISHED \
        -j ACCEPT

    $IPTABLES -A interface1_out -p TCP \
        -s $INTERFACE1_IPADDR --sport $WS_PORT \
        -d $ANY_IPADDR --dport $UNPRIV_PORTS \
        -m state --state ESTABLISHED \
        -j ACCEPT
        
    $IPTABLES -A interface0_in -p TCP \
        -s $ANY_IPADDR --sport $UNPRIV_PORTS \
        -d $INTERFACE0_IPADDR --dport $WS_PORT \
        -m state --state NEW,ESTABLISHED \
        -j ACCEPT

    $IPTABLES -A interface0_out -p TCP \
        -s $INTERFACE0_IPADDR --sport $WS_PORT \
        -d $ANY_IPADDR --dport $UNPRIV_PORTS \
        -m state --state ESTABLISHED \
        -j ACCEPT
 done
# ---end open poort 8008 ---

The above 4 rules appear, and we explain the first one, line by line:

Allow on eth1 inbound TCP traffic
from any IP address and from any unprivileged source port [*],
destinated for eht1's IP address' for port 8008
for new and established connections

Now the other three rules can be interpreted in the same way.

[*] Privileged ports (0-1023) are for certain services and can only be used by root. Unprivileged ports (1024-65534) can be used by any user.

More on this subject can be found in: Securing and Optimizing Linux: The Hacking Solution, Gerhard Mourani, 2002, Open Network Architecture, Inc., Montreal, Canada, ISBN 0-9688793-1-4
With its 47 chapters and 1200+ pages this book is the ultimate reference documentation for OpenNA Linux. In a simple and structured way the book explains the ways a server can be configured in a safe way. A lot of popular Linux-based services are discussed in extenso. Nowadayas the book can be downloaded in PDF format from: http://www.openna.com/pdfs/Securing-Optimizing-Linux-The-Hacking-Solution-v3.0.pdf. Highly recommended.

NOTICE: There might be a pitfall. When the server is behind a router, the schools IP address and the IP address of eth0 can differ. In that case, traffic from the outside world to the router must be forwarded to the servers IP address with port forwarding in the router.

Some tests:
We assume the websockets server is properly working, and some user in the world has already successfully used the CREW page, for example Wilhelmina Bladergroen from her home address.

Start the browser and surf to, for example: http://exemplum.eu. The school page must be visible. Then add the port, i.e. http://exemplum.eu:8008. When you don't receive the message '404 Bad request' (a CREW server message), you have a problem on your side, probably the browser or the modem refuses traffic on port 8008.

• Websockets really working on your browser: simple browser test on: http://www.websocket.org/echo.html. Result: probably OK because the simple browser test only uses port 80.
• On the server: # tail -f /var/log/messages
  Let the user surf to http://exemplum.eu:8008

4.3 Server installation

[root@jh crewserver]# ls -l
total 277
-rw-r--r--    1 freddie     freddie         4706 Jun 11 13:25 about.html
-rw-r--r--    1 freddie     freddie         7219 Jun 12 15:06 crewserver-example.conf
-r--------    1 freddie     freddie         7382 Jun 13 11:16 crewserver.conf
-r-x------    1 freddie     freddie        45825 Jun 12 15:06 crewserver.php
drwxr-xr-x    2 freddie     freddie           88 Jun 12 23:07 graphics
-rw-r--r--    1 freddie     freddie        37466 Jun 11 13:25 license.html
-rw-rw----    1 freddie     freddie          395 Jun 13 18:53 logfile.log
-rw-r--r--    1 freddie     freddie         4812 Jun 12 15:06 readme.txt
-rw-r--r--    1 freddie     freddie       120659 Jun 11 13:26 utf8lib.php
-rw-r--r--    1 freddie     freddie        30954 Jun 11 13:26 zip.class.php
[root@jh crewserver]#

4.3.1 The readme.txt

Date: 2013-06-12
Auth: Peter Fokker <peter@berestijn.nl>
File: readme.txt
Subj: Notes for CREW-server
Vers: 0.90.5


Download and install
====================

You can install the crewserver as follows:

1. Download the crewserver.zip file from your own Website@School website,
   e.g. from http://www.yourserver.org/program/modules/crew/crewserver.zip

2. Find a quiet place to unzip this file, perhaps your $HOME directory.
   Note that the file crewserver.zip unpacks into a subdirectory called
   crewserver

   $ cd  $HOME
   $ unzip  /path/to/crewserver.zip

   At this point you have all relevant files together in the directory
   $HOME/crewserver/.

   NOTE:
   Do NOT unpack this .ZIP-file in a directory that is accessible from the
   outside world and certainly not under the webserver's document root or the
   CMS Root Folder (where admin.php and index.php live).

3. Create crewserver.conf in the directory that was created while unzipping,
   i.e. in the same directory where crewserver.php resides. If you want you
   can use the example-configuration file as guidance and/or documentation.

   $ cd  crewserver/
   $ cp  crewserver-example.conf  crewserver.conf

   You can now edit crewserver.conf with your favourite editor. At the very
   least you MUST add an origin-line with the details for your server
   environment.

4. If you are concerned about the confidentiality of the shared keys in your
   crewserver.conf, you can minimise the permissions to say 0600 or even 0400
   as long as that file is owned by the user that will be running the
   crewserver process. (The crewserver process periodically re-reads the
   configuration file that hence needs read permissions on that file)


Starting the server
===================

You can now run the server as follows.

5. Check the permissions of the file crewserver.php and make sure that the
   read and execute permissions are set, at least for the user who will be
   running the crewserver process. The minimal permissions are 0500 but it is
   perfectly acceptable to set the permissions to 0700, 0750 or even 0755
   (there are no secrets in crewserver.php). Also make sure that the other
   files are readable by the server process, e.g. same owner and at least
   0400 or 0640 or 0644 if you want.

   NOTE:
   The file crewserver.conf DOES contain privileged information; make sure
   permissions are as minimal as possible (preferably 0400).

6. Start the server (as ordinary user, you can do that!) by descending into
   the crewserver directory if you did not already do that in the previous
   step and execute the main program:

   $ cd  $HOME/crewserver
   $ ./crewserver.php  &

   The server will start in the background and -- with the default
   configuration -- a few messages will be written to the system's 
   log ('syslog'). You can check to see if the server is running by
   checking the entries in the system logfiles, e.g. /var/log/messages.

   NOTE:
   If you have configured the server to write logmessages to stderr,
   the messages will be written on your screen.

   If the server does not start you may have to change the path to the
   PHP-interpreter on the first line of crewserver.php (see below).


Notes and troubleshooting
=========================

If you have configured the server to log information to stderr, you can
capture the output of the server as follows:

  $ ./crewserver.php 2>&1 | tee -a logfile.log

Alternatively you can script your session:

  $ script logfile.log
  $ ./crewserver.php

If you want to run crewserver.php in the background while keeping an eye
on the log use this:

  $ ./crewserver.php >logfile.log 2>&1 &
  $ tail -f logfile.log

You can use Ctrl-C to kill the server (or use kill if it is running in
the background).

If you have configured the server to log information to syslog, you can try to
follow the tail of the logfile, e.g. tail -f /var/log/message.

Note that the crewserver.php file is configured to use the php command line
interpreter located in /usr/bin/php. If php is located elsewhere on your
machine, you need to adjust the first line in crewserver.php accordingly.

If you use the crewserver on a non-standard port (like the proposed port 8008
in the example configuration) you may need to adjust your firewall too before
the server can be used.


Source code
===========

The source code of the crewserver program is served by the crewserver program
itself if you know where to look. If you point your browser at
http://yourserver.org:8008/crewserver/program you receive a .ZIP-file with the
code, in compliance with the GNU AGPLv3+Additional Terms (see about.html and
license.html). Note that this works best if you leave all supporting files
(about.html, crewserver-example.conf, etc.) exactly where you unpacked them in
step 2 above. Note: your private configuration file crewserver.conf is never
made available to the outside world via this mechanism.


More information
================

Please refer to the manual that documents CREW for more information.

[eof readme.txt]

4.3.2 The crewserver-example.conf file

# crewserver-example.conf -- example configuration file for crewserver.php
# Peter Fokker -- 2013-06-12
#
# This file contains the configuration information for the
# websocket server contained in crewserver.php. The following
# parameters can be configured:
#
# ORIGIN = url, secret, shops, workers
# DEBUG = level
# SERVER_ADDRESS = ip-address
# SERVER_PORT = port-number
# LOG2SYSLOG = flag
# MARK_TIME = interval-in-seconds
# MAX_DELTA = time-window-in-seconds
#
# See below for more information per item.
#
# The format of this file is as follows.
#
# - leading and trailing spaces are not significant
# - empty lines are discarded
# - lines starting with a hash character '#' are comments
# - comment lines are ignored
# - parameters are specified as key=value-pairs
# - keys are caseINsensitive
# - key=value-pairs cannot span lines (i.e. no line continuation with backslash)
#

# ORIGIN
# 
#   Format: ORIGIN = url, secret, shops, workers
#
#   with
#
#   url        origin, e.g. http://www.exemplum.eu
#   secret     plain text password (see below)
#   shops      maximum # of workshops allowed for this origin (default 1)
#   workers    maximum # of concurrent members per workshop (default 4)
#
#   The origin must match the origin as it is presented to the socket server
#   by the user's browser. It is used as part of the authentication of users.
#   This means that you cannot just use any random URL; it must match the URL
#   of your webserver as it is seen by the user's browser.
#
#   The password (indicated with secret above) is the plain text password
#   used for authentication. This password must be shared between the
#   webserver and the socket server and therefore it must --unfortunately--
#   be stored in plain text. Because of the format of the configuration file
#   the password should not contain commas or spaces. If you wish you could
#   substitute the hexadecimal value ('%20' for space, '%2C' for a comma).
#   You could also use a password consisting of only hexadecimal values, e.g.
#   '%53%65%63%72%65%74' for 'Secret'. However, it is important that both
#   the websocket server and the webserver agree on the password.
#
#   The shops parameter indicates the maximum number of workshops that
#   can be used concurrently with this origin. The default value is 1 and
#   the value should be between 1 and 32 inclusive.
#
#   The workers parameter indicates the maximum number of workshop members.
#   This number must lie between 1 and 26.
#
#   Note:
#   If your server can be reached under different names, you should add
#   an entry for every name. However, the workshops will be considered
#   distinct, ie. the workshop http://exemplum.eu/55/workshop5.html is
#   not the same as workshop http://www.exemplum.eu/55/workshop5.html.
#
#   Also note that an origin entry is valid per server, i.e. if there are two
#   different installations of Website@School on the same server, e.g.
#   http://exemplum.eu/pupils and http://exemplum.eu/teachers, both 
#   installations share a single origin-entry and hence a single password.
#
#   Note: the url in the ORIGIN identifies the webserver, not
#   the socket server.
#
#   The line below has an example entry for http://exemplum.eu. This
#   entry uses the password "SecretExemplumKey", the maximum number
#   of workshops is 3 and the maximum number of workers is 7.
#
#   ORIGIN = http://exemplum.eu, ThisIsTheSharedSecret, 3, 7
#
#   IMPORTANT NOTE!
#   You should select a secret password that is not easy to guess for
#   outsiders, so pick a long password. You only have to configure it
#   once (in both client and server configuration) so there is no need
#   to make this password easy for you to remember, as long as the computer
#   can remember it. You are problably OK when  you simply add a handful
#   of plain words for a total length of say 25 characters, e.g. 
#   "CorrectHorseBatteryStaple" or a quasi-random string like 
#   "aHR0cDovL20ueGtjZC5jb20vOTM2".


# DEBUG
#
#   Format: DEBUG = level
#
#   with
#
#   level      debug level
#
#   The debug level must be a number between 0 and 7.
#   The default level is 6 (LOG_INFO) and the other
#   realistic option is 7 (LOG_DEBUG). If you set this
#   value to a value lower than 3 the server will not
#   log nothing. The recommend value is 6 (LOG_INFO).
#
#   The default value for DEBUG is 6 (LOG_INFO).
#
DEBUG = 6


# SERVER_ADDRESS
#
#   Format: SERVER_ADDRESS = ip-address
#
#   with
#
#   ip-address the IP-address to which the server will be listening.
#
#   This IP-address can be one of the IP-addresses of your server,
#   or the special value 0.0.0.0 indicating that the server must listen
#   to all available interfaces.
#
#   The default value for SERVER_ADDRESS is 0.0.0.0.
#
SERVER_ADDRESS = 0.0.0.0


# SERVER_PORT
#
#    Format SERVER_PORT = port-number
#
#    with
#
#    port-number the number of the port to listen to
#
#    This port-number can be any available portnumber above 1024
#    (if the server will be running under your own user account)
#    or even a port under 1024 if it is running as root.
#
#   The default value for SERVER_PORT is 8008.
#
SERVER_PORT = 8008

# LOG2SYSLOG
#
#   Format: LOG2SYSLOG = flag
#
#   with
#
#   flag indicating whether to log to syslog (flag=1) or stderr (flag-0)
#
#   Default value is 1 (log to syslog).
#
LOG2SYSLOG = 1

# MARK_TIME
#
#   Format: MARK_TIME = interval
#
#   with
#
#   interval the number of seconds between MARK-messages
#
#   This configures the time between logging a MARK-message
#   as an indication of the server still being alive. Also,
#   whenever a MARK-message is output the server checks to
#   see if the configuration file crewserver.conf has changed
#   since the last time the server checked it. If that is the
#   case, the configuration file is re-read and any changed
#   parameters are processed if possible.
#
#   Note: some parameters can not be changed while the server
#   is running, notably SERVER_ADDRESS and SERVER_PORT and
#   LOG2SYSLOG. You can change the values but any changes are
#   discarded when the configuration file is re-read at MARK-time.
#
#   Default value is 900 seconds (15 minutes)
MARK_TIME = 900

# MAX_DELTA
#
#  Format: MAX_DELTA = time-window
#
#  with
#
#  time-window a time interval in seconds
#
#  This parameter is used to limit the validity of authentication
#  of users. Because the time on the webserver and the socket
#  server may differ just a little bit, and because it may take
#  some time for a websocket request reaching the server, the
#  necessary token has to have a certain time during which it
#  is considered valid. After this time has passed, the token
#  is no longer valid. This makes it impossible to trick the
#  socket server using a captured token in a replay-attack.
#
#  The default value for this time window is 120 seconds (2 minutes)
#
MAX_DELTA = 120


# Final note
#
# The server periodically emits a MARK message.
# Whenever this event occurs the server also re-reads this
# configuration file. That implies that eventually the
# changed configuration will reach the server. This means
# that you can add (or delete) origins and that the 
# websocket server will follow.
#
# EOF

4.3.3 Init script

[root@jh root]# touch crew
[root@jh root]# chmod 700 crew
[root@jh root]# chown root.root crew
[root@jh root]# vi crew

With your favorite text editor, copy and paste the script in the file.

#!/bin/bash
#

# From http://wiki.squeak.org/swiki/124.
# Modified for ServerAtSchool by Dirk Schouten
# <dirk (at) websiteatschool  (dot) eu> 2013-06-06

# This shell script takes care of starting and stopping CREW server.

# chkconfig: 345 99 10
# description: Control the CREW server: crewserver.php
# processname: crew
# file: crewserver.php
# config: crewserver.conf 
# pidfile: /var/spool/


CREW_CMD="/home/userdata/home/users/freddie/crewserver/crewserver.php"
PROG="CREW"

if [ -f /etc/init.d/functions ]; then
     . /etc/init.d/functions
elif [ -f /etc/rc.d/init.d/functions ]; then
    . /etc/rc.d/init.d/functions
else
    exit 0
fi

. /etc/sysconfig/network

[ ${NETWORKING} = "no" ] && exit 0

RETVAL=0

start() {
    echo -n "Starting $PROG server: "
    $CREW_CMD &
    RETVAL=$?
    [ $RETVAL -eq 0 ] && success || failure
    [ $RETVAL -eq 0 ] && touch /var/lock/subsys/creditor
    echo
    return $RETVAL
}

stop() {
    echo -n $"Stopping $PROG server: "
    killproc $CREW_CMD 
    RETVAL=$?
    [ $RETVAL -eq 0 ] && rm -f /var/lock/subsys/creditor
    echo
    return $RETVAL
}

case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    restart)
        stop
        start
        ;;
    *)
        echo "Usage: $0 {start|stop|restart}"
        exit 1
        ;;
esac

exit $RETVAL
#eof

Move the file to /etc/rc.d/init.d/ or the place where the rc files reside on your system.
Run chkconfig to create the appropriate symbolic links in the various /etc/rc*.d directories and set runlevels. Finally, check your work.

[root@jh init.d]# chkconfig --add crew
 init.d]# chkconfig --level 345 crew on
[root@jh init.d]# chkconfig --list crew
crew        0:off   1:off   2:off   3:on    4:on    5:on    6:off

And start the server:

[root@jh init.d]# service crew start
Starting CREW server:          [  OK  ]
[root@jh init.d]#

4.3.4 /var/log/messages

=======================================================================
EXAMPLE 1

A successfull intern session.

Jun 24 18:10:01 jh crew: crewserver.php shutdown succeeded
Jun 24 18:10:27 jh crew:  succeeded
Jun 24 18:10:27 jh crewserver[21701]: starting server: CREW-server 0.90.5
Jun 24 18:10:27 jh crewserver[21701]: This program is free software: you can redistribute it and/or modify it under
Jun 24 18:10:27 jh crewserver[21701]: the terms of the GNU Affero General Public License version 3 as published by
Jun 24 18:10:27 jh crewserver[21701]: the Free Software Foundation supplemented with the Additional Terms, as set
Jun 24 18:10:27 jh crewserver[21701]: forth in the License Agreement for Website@School (see license.html and about.html).
Jun 24 18:10:27 jh crewserver[21701]: crewserver.conf:134: setting server address to 0.0.0.0
Jun 24 18:10:27 jh crewserver[21701]: crewserver.conf:151: setting server port to 8008
Jun 24 18:10:27 jh crewserver[21701]: crewserver.conf:163: setting log destination to syslog
Jun 24 18:10:27 jh crewserver[21701]: crewserver.conf: origins: 2 added, 0 modified, 0 unchanged, 0 deleted
Jun 24 18:10:27 jh crewserver[21701]: server address  = 0.0.0.0
Jun 24 18:10:27 jh crewserver[21701]: server port     = 8008
Jun 24 18:10:27 jh crewserver[21701]: log destination = syslog
Jun 24 18:10:27 jh crewserver[21701]: debug-level     = 6
Jun 24 18:10:27 jh crewserver[21701]: maximum delta   = 120 s
Jun 24 18:10:27 jh crewserver[21701]: mark-interval   = 900 s
Jun 24 18:10:27 jh crewserver[21701]: currently serving 2 origin(s)
Jun 24 18:10:27 jh crewserver[21701]: logmessages go to syslog
Jun 24 18:10:27 jh crewserver[21701]: initialising socket for listening 0.0.0.0:8008: success (id=#0)
Jun 24 18:10:27 jh crewserver[21701]: waiting for connections
Jun 24 18:10:40 jh crewserver[21701]: new client #1: 172.17.2.36:51756 [172.17.2.1:8008]
Jun 24 18:10:50 jh crewserver[21701]: new client #2: 172.17.2.34:43409 [172.17.2.1:8008]
Jun 24 18:10:59 jh crewserver[21701]: new client #3: 172.17.2.240:57791 [172.17.2.1:8008]
Jun 24 18:11:49 jh crewserver[21701]: removing client #2 (herbert) from workshop #1
Jun 24 18:11:54 jh crewserver[21701]: new client #4: 172.17.2.34:43417 [172.17.2.1:8008]
Jun 24 18:12:25 jh crewserver[21701]: removing client #4 (herbert) from workshop #1
Jun 24 18:12:35 jh crewserver[21701]: removing client #3 (honorine) from workshop #1
Jun 24 18:12:43 jh crewserver[21701]: removing client #1 (catherine) from workshop #1
Jun 24 18:12:43 jh crewserver[21701]: removing empty workshop #1

Conclusion: works perfectly.
======================================================================

EXAMPLE 2
successfull extern session with MacBook Pro with Firefox v. 21.0.

Jun 25 15:03:40 jh crewserver[21701]: new client #20: 80.101.xxx.xx:54932 [10.0.0.150:8008]
Jun 25 15:03:40 jh crewserver[21701]: new client #21: 80.101.xxx:xx:54934 [10.0.0.150:8008]
Jun 25 15:03:58 jh crewserver[21701]: new client #22: 172.17.2.36:43717 [172.17.2.1:8008]
Jun 25 15:08:35 jh crewserver[21701]: removing client #22 (name1) from workshop #12
Jun 25 15:08:41 jh crewserver[21701]: removing client #20 (name1) from workshop #12
Jun 25 15:08:41 jh crewserver[21701]: removing empty workshop #12

Conclusion: works perfectly.
=======================================================================

EXAMPLE 3

The same Macbook Pro wiht Safari v. 6.0.5
Jun 25 15:14:01 jh crewserver[21701]: new client #23: 172.17.2.36:43722 [172.17.2.1:8008]

whereafter ... nothing

The connection could not be established. 
Conclusion: the browser is guilty. A complaint from many Mac users.
=======================================================================

4.3.5 Help!

Subject: Unable to connect to CREW
To: H.H.Grønbech <gronbech@dolphins.org< 
From: Freddie Frinton >sysadmin@exemplum.eu<

Dear,
It seems impossible for you to work at your 
home/organisation with the Exemplum Primary Schools 
CREW page.
With this mail and your help, we will try to locate the 
problem. Sit behind your computer and have a telephone or 
Skype at hand.

1. You MUST use a recent Firefox browser version.
   Write down the version number under 'Help' 
   and 'About Firefox'

2. You MUST have Javascript enabled in Firefox.
   You MUST have popup windowns enabled in Firefox.
   Look for 'Edit', Preferences and Content.

3. Now surf to http://www.websockets.org/echo.html
   Question: What do you see under the words: 'Try it 
out'? 

--In red color-------------------------------------------
X Uh-oh, the browser you're using doesn't have 
native support for WebSocket. That means you can't run 
this demo.
---------------------------------------------------------

or

--In green color------------------------------------------
V This browser supports websockets
----------------------------------------------------------

-If 'X', you must at least upgrade your browser. Call or
 mail us so we can send you details on how to do this.

-If 'V', go on with the connection test:

4. Connection
a. Look for the [Connect] button.
b. Press it. 
c. In the Log window (on the right side of the 
browser screen) you see: CONNECTED.

4. Write
a. Put your cursor in the Message field, where it says 
'Rock it with HTML5 Websocket'.
b. Type something.
c. Click the [Send] button.
d. Your text should appear in the Log.

Pick up the telephone and call us. Do not yet do the 
next steps. Together we will do the next tests. We can read 
our logfiles and perhaps find something.

5. With your webbrowser, surf to
   http://theschoolserver.org 
   Please tell us what you see in the browser.

6. Now add ':8008' to http://schoolserver.org 
   Omit the quotes ' '.
   The line should now look like:

   http://schoolserver.org:8008
   
   Now press [Enter] on your keyboard.
   Please tell us what you see in the browser.

7. If asked, press F5 on your keyboard so we can 
observe if and/or how your request reaches the school 
server.

Hopefully we can locate the problem and solve it, so 
you can participate in the workshop.

With kind regards,
Exemplum Primary School
Systems administrator
Freddie Frinton

If 1, 2, 3, 4 and 5 succeed and 6 fails, probably the users router must be enabled to send traffic to the servers IP address with port forwarding in the router.

4.4 "After x I got y"

Please report a bug at the address below.

(top)