1.
Introduction
1.1 Assumptions
1.2 NOTICE!
1.3 Features and limitations
1.4 Backgrounds
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.6 "After x I got y"
CREW
(Collaborative Remote Educational Workshop) is a browser-based, real-time
collaborative editor (RTCE), allowing several people to simultaneously edit the same
text file.
This chapter elaborates
on other chapters. We assume you have at least done the Guided Tour of the Website@School Users' Guide.
For
pupils and teachers working in CREW is easy. However, setting up CREW is not
a piece of cake. If you are unfamiliar with securely opening one, and
only one! port on the schools firewall, with installing software on a
production server and configuring files, please seek help at 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.
Features in no specific order:
- 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)
Limitations:
- 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.
CREW is based on: a. the Websocket
protocol, a rather new (2011-now) web technology, b. on HTML5, the latest
(2012-now) markup standard for web content, as well as c. on Javascript
(1999?), a well-known programming language to control the browser,
communicate asynchronously and alter the document content that is
displayed.
CREW skins are created with 4.2.2. Bazaar Style Style, our own (2011) implementation of CSS
Cascading Style Sheets, (1996) a language used for describing
the look and formatting of a document written in a markup language. It is
designed primarily to enable the separation of document content from document
presentation. This separation can improve content accessibility.
The Basic Multilanguage Plane (BMP)
contains characters for almost all modern languages, and a large number of
special characters. A primary objective for the BMP is to support the
unification of prior character sets as well as characters for writing. Most
of the allocated code points in the BMP are used to encode Chinese, Japanese,
and Korean (CJK) characters.
(top)
In this
paragraph we assume that
- you have read and done the Guided Tour,
- 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.
NOTICE:
Adding a page supposes that you have sufficient permissions to add a page.
This is specially important for non-webmasters like pupils and teachers who
often have limited permissions. These permissions are set in the Account Manager, most times by the
webmaster Wilhelmina Bladergroen.
In the Page Manager, select the Area or section and click on the
Add a page link to enter the Add a
page dialogue:
![[ CREW add page and module ]](workshop/workshop_CREW_module_add.png)
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.
In
this part only the Header and Introduction are discussed:
![[ CREW page configuration header and intro ]](workshop/workshop_CREW_page_configuration_header+intro.png)
workshop_CREW_page_configuration_header+intro.png
in the Menu the link Content is selected.
NOTICE:
Here, with the options, World and
Authenticated, only the visibility, i.e the
read permissions for the viewers of this page can be set.
![[ CREW page configuration visibility: world + authenticated ]](workshop/workshop_CREW_page_configuration_visibility_world+authenticated.png)
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.
![[ CREW page configuration page visibility: individueals ]](workshop/workshop_CREW_page_configuration_visibility_individuals.png)
workshop_CREW_page_configuration_visibility_individuals.png
Explanation:
Example
In the Account Manager Wilhelmina has given Herbert Spencer permissions: his
Admin permissions on Basic and Page Manager. His
Page Manager permissions were set to Sectionmaster
(so he can add pages) for the Area 'Pupils of Grade 8'. Herbert
creates the page, sets the Visibility on Individuals ( because he thinks that
work in progress should not be visible to the world or people with an
account) and sees:
![[ CREW page configuration page visibility: individueals, herberts view ]](workshop/workshop_CREW_page_configuration_visibility_individuals-herbert.png)
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.
In this paragraph we
show you the results of the possible settings in the CREW configuration page.
For the Dolphins project Wilhelmina has set the page permissions as
follows:
![[ CREW page configuration page visibility: individueals, wilhelmina's view ]](workshop/workshop_CREW_page_dolphins_perms_set-wblade.png)
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.
![[ CREW webpage: for anonymous visitor: no access ]](workshop/workshop_page_conf_visib=individ_pub-area=anon_visitor.png)
workshop_page_conf_visib=individ_pub-area=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.
![[ CREW webpage: for visitor with login account: header, intro, text ]](workshop/workshop_page_conf_visib=individ_pub_area=read_perms.png)
workshop_page_conf_visib=individ_pub_area=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.
![[ CREW webpage: for visitor with read+ write permissions: status message, header, intro, text, skins droopdown menu, edit button ]](workshop/workshop_page_conf_visib=individ_pub_area=read+write_perms.png)
workshop_page_conf_visib=individ_pub_area=read+write_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.
NOTICE:
Even when the visibility is set to World or Authenticated, the Skin and
[Edit] button are not available. This is a security feature, preventing
anonymous or unauthenticated users to enter the CREW page.
Select skin and press the
[Edit] button to enter the CREW editor:
![[ CREW editor: skin base ]](workshop/workshop_CREW_skin_base_catherine.png)
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:
-
Chat pane: The chat can be used to send messages about
the text, thus keeping the text clean.
Herbert has also entered the CREW page and gives his input. He uses the
LowVision skin:
![[ CREW editor: skin lowvision ]](workshop/workshop_CREW_skin_lowvision_herbert.png)
workshop_CREW_skin_lowvision_herbert.png
And Honorine uses the RedGreyBlue skin:
![[ CREW editor: skin redgreyblue ]](workshop/workshop_CREW_skin_redgrayblue_onorine.png)
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:
![[ CREW page after saving: status message, header, intro, text, skins dropdown menu, edit button ]](workshop/workshop_CREW_page_dolpins_savedby_catherine.png)
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.
We
created CREW to be used with the Firefox browser. Reason: CREW then functions
on Linux, Mac, FreeBSD, HPUX, Windows and many others.
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:
![[ Firefox popup window: Firefox prevents this site from opening a popup window, button: Preferences ]](workshop/workshop_CREW_popup_disabled.png)
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.
The advanced
options also apply to this module. In particular it means that you can use
Bazaar Style Style (BSS) to get rid of aweful colors that mismatch with the
school site or with the pictures on the page.
More about the background of BSS can be found in chapter Viewpoints, paragraph 4. On form and content.
More on the practical work can be found in Configuration Manager,
paragraph 3.4
Configure theme 'Theme Name' for area n. The other advanced
options are discussed in chapter Page Manager, paragraph 3.3 Advanced: edit advanced properties of page nn.
(top)
The webmaster
Wilhelmina Bladergroen, has to do a simple task before anyone can do anything
with CREW: configure the CREW module. Do not worry, the values below are
given to you by the systems administrator, the person who installed the CREW
server.
Go to the Module
Manager and, in the Menu, select the Workshop (CREW) module. The link becomes underlined. The
parameters below need to be set correctly, otherwise it is not possible to
use CREW:
![[ CREW module configuration ]](workshop/workshop_module_configuration.png)
workshop_module_configruation.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
Most times you will have received these parameters from a systems
administrator.
Before handing over
CREW to users who trust their valuable collaborative efforts to their
browsers, it's a sensible idea to test CREW.
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:
![[ CREW webpage test: anonymous visitor ]](workshop/workshop_CREW_test_anon_visitor.png)
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:
![[ CREW webpage test: authenticated visitor ]](workshop/workshop_CREW_test_auth_visitor.png)
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:
![[ CREW webpage test: viisitor with read + write permissions, empty text field ]](workshop/workshop_CREW_test_auth+read-write_visitor.png)
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:
![[ CREW webpage test: viisitor with read + write permissions, text added ]](workshop/workshop_CREW_test_auth+read-write_visitor_edited.png)
workshop_CREW_test_auth+read-write_visitor_edited.png
Now either she or Herbert can create a CREW page for the Dolphins
project.
Wilhelmina doesn't forget to set the test area to inactive.
(top)
For the schools systems
administrator, having root access to 'his' server, the installation
of the CREW websocket server is quite straightforward; please go directly to
paragraph 4.3 Server installation.
To facilitate schools using ServerAtSchool we provide extra
information about servers and ports, their firewall and an init script; please
read on.
Before the
installation can take place, there are a few questions to answer.
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.
There are hundreds types
of firewalls, so it's impossible to give a prescription. In general, when
using the CREW server on port 8008, the firewall must allow inbound TCP
traffic from all unprivileged ports for new and established connection to
initiate a connection to port 8008. And the firewall must enable outbound
traffic, i.e. answers from your server on port 8008, just for established
connections.
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
After unzipping
you will find the following files and directory:
[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]#
|
Below is the
readme.txt, copied from the crewserver.zip.
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]
|
Below is the crewserver-example.conf file. The line
that minimally MUST be edited in the file is around line 80:
# ORIGIN = http://exemplum.eu, ThisIsTheSharedSecret, 3, 7.
# 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
|
Some hints on
making an init script. For most of you known stuff.
[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
# <schoutdi@knoware.nl>. 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]#
|
Below
examples, cut from /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.
=======================================================================
|
A user called/mailed.
Here is our answer, maybe it serves you. The test can only be executed when
you are absolutely sure that your side (server, firewall, ports)
cannot be the problem.
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.
Please
reprort a bug at the address below.
(top)
Author: Dirk Schouten <schoutdi (at) knoware (dot) nl>
Last updated: 2013-07-02