How to make a public web message board
by Agner Fog 1999. www.agner.org/software/msgbrd1
Contents:
1. What is a web message board
2. Advantages of this board
3. System requirements
4. Things to check
5. Setting up the files
6. Customizing the files
7. Using the board
8. Using the moderation tool
9. Support for search engines
10. Maintenance
11. Making backup
12. Filelist
13. Troubleshooting
14. Manual installation
15. Help and support
1. What is a web message board
===============================
A web message board is a web site for public discussion and sharing of news
about a particular topic. Anybody can post a message and anybody can read it.
A message board differs from a mailing list in that you don't have to subscribe.
It differs from a Usenet newsgroup in that improper messages can be removed.
2. Advantages of this board
============================
This message board system has several advantages over other available systems:
* Protected against errors, for example in case two messages are posted
simultaneously.
* A separate index for each thread avoids the problem of the index
being clogged up by very long threads. A main index contains a list of
threads, and an unthreaded index lists all messages for the purpose of
searching.
* Special indexes for old and deleted messages.
* Accepts html code in messages. The user can edit his/her message in an
html editor if he/she wants formatting or special features. Potentially
damaging html codes are removed automatically.
* A message preview allows the user to see if the message looks as intended,
check it for errors, and edit it again if necessary.
* The system allows several web message boards for different topics on the
same site.
* Automatic daily backup of the main index. A script for backup of all
messages is also available.
* A special moderation tool makes the moderator's job easy. It is possible
to expire, delete or edit messages from a web browser. The webmaster can
control passwords and access rights for several moderators.
* A test board provides a safe place for moderators and users to experiment
without disturbing anybody else.
* Handicap-friendly (conforms with W3C Web Content Accessibility Guidelines)
3. System requirements
=======================
You must have a basic knowledge of the internet, HTML and UNIX commands to
be able to install and use this program.
Before you sign up for an account at an internet service provider you
should check if it provides what you need:
Operating system: LINUX, UNIX, or similar.
Other operating systems are sure to cause you trouble.
Own cgi-bin directory: The service must provide you with your own cgi-bin
directory. This means that you are allowed to run your own programs on the
server.
Server-side includes (SSI or shtml): Recommended, but not necessary.
Disk space: Make sure you get enough disk space. You should reserve at least
10 MB for each message board, and more if you expect many messages or very
long messages.
4. Things to check
===================
Telnet login:
You should be able to get a UNIX command line by a telnet or secure shell login.
Home directory:
If you don't know what the name of your home directory is try the commands:
cd ~
pwd
Web root directory:
This is the directory you see when you access your site through a web browser
without specifying any subdirectory. For example, your home directory may be
/home/YOURNAME/ and your web directory may be /home/YOURNAME/public_html/.
In some systems the web directory is the same as the home directory. This is
not desirable because all your files will be accessible by http.
cgi-bin directory:
You should have a cgi-bin directory, preferably as a subdirectory to your
web root directory. If it is anywhere else or has a different name then make
a symbolic link to it from the web root directory using the command
ln -s CGI-BIN-DIRNAME cgi-bin
If there is no cgi-bin directory then you may not be allowed to have one.
Server side includes:
Check if your system supports server side includes and filenames ending
in '.shtml'. If files ending in .shtml are not shown as HTML files in a
web browser, then use '.htm' or '.html'.
Domain name:
You may have your own virtual domain of the type www.YOURNAME.com,
or a subdomain of the type YOURNAME.SERVICEPROVIDERSNAME.com,
or only a subdirectory of the type www.SERVICEPROVIDERSNAME.com/~YOURNAME
In the latter case you may not be able to control the way search engines like
AltaVista index your files (see below).
Decide the name of your message board. You may want more than one message
board if you want to cover very different topics.
5. Setting up the files
========================
Make a directory named boardsetup somewhere on your server.
Transfer the file msgbrd.zip by ftp in binary mode to the boardsetup directory.
Log in by telnet and go to the boardsetup directory using the cd command.
Unzip the archive with the command:
unzip msgbrd.zip
Edit the file makeboard to specify the desired directories, colors, and other
options in the section 'Specify parameters:'.
Make a test message board with the command
. makeboard test 'Test message board'
This will make a test message board with all the necessary files and
directories.
Test the test message board with a web browser at http://YOURURL/test
where YOURURL is the URL to your web root directory.
Fix any problems as described below.
When everything works then you can make a new web message board with
the command:
. makeboard DIRNAME 'TITLE'
where DIRNAME is the name you want for the directory holding the message board,
preferably a short name consisting of only small letters.
TITLE is the title as you want it to appear on the message board.
Repeat the command if you want more message boards.
6. Customizing the files
=========================
Filename extensions:
--------------------
If filenames ending in .shtml are not shown as html then change the line
export EXT1=shtml
to
export EXT1=htm
in the file makeboard, and run it again, or if you have root access:
setup the system to accept .shtml.
The message board system is taking advantage of a secondary effect of the
.shtml files: Most web browsers will reload files with extionsion .shtml
rather then showing cached versions when following a link to such a file.
This is used for index files such that the user can see that the index has
been updated after a message has been added.
If you don't use filenames with extension .shtml then the FAQ should tell
users to press the reload button when looking at an index file after posting
a message.
Logos:
------
It is recommended that you make a logo for your message board. Message boards
tend to look the same, and the logo tells the user which message board he/she
is looking at. This is particularly useful if you have more than one message
board at the same site. You may also have special logos for old and deleted
messages.
The logos all have the same filename (m.gif) but stored in different
directories. Each logo is stored in the same directory as the html files it
is intended for:
logo for main index: BOARDDIR/m.gif
logo for normal messages: BOARDDIR/messages/m.gif (possibly identical)
logo for expired messages: BOARDDIR/old/m.gif
logo for deleted messages: BOARDDIR/deleted/m.gif
The makeboard script puts default logos in all directories for you. It is
recommended that you replace them with your own logos.
The file sizes for the logos should preferably not be bigger than a few kb.
If you don't want logos then change the line
export LOGO='m.gif'
to
export LOGO=''
in the file makeboard
Colors
------
You can change the colors of messages and indexes by editing the appropriate
lines in the file makeboard.
Style sheet
-----------
You may change the font and other styles by editing the file s.css.
If you don't want to use style sheets than change the line
$style_sheet = 's.css';
to
$style_sheet = '';
in the files msgbrd.cgi and moderate.cgi and remove references to it in all
faq and index files.
Time zone
---------
The scripts are programmed to show time as Greenwich Mean Time (GMT) because
the message board may have users all over the world. If you prefer local time
then change the line
export GMT=1
to
export GMT=0
in the file makeboard.
Maximum message size
--------------------
This is specified in the line
$maxsize = 30000; # max message size in bytes
in the file msgbrd.cgi.
Edit the FAQ
------------
The file faq.htm contains directions to the users of your message board.
You have to edit this file to include a description of the purpose of your
message board and directions for what type of messages are appropriate or
inappropriate.
You may also include links to your home page and to other message boards and
other ressources on the web relevant to your topic.
Language
--------
You may translate the file faq.htm to a different language. However, if
you also want links and messages generated by the board script to be in
a different language then you have to be a good programmer. Note that the
scripts recognize certain text patterns in indexes and in head and tail
of messages in order to update links. If you change the language of these
texts then you have to make sure that the scripts can recognize these.
How to edit files
-----------------
Don't edit with Frontpage!
The Frontpage editor will destroy hidden codes in index files and message
files. These codes are necessary for the system to work.
It is recommended that you use an ASCII text editor for editing the index
files and the script files (*.cgi).
To edit messages use only the moderation tool.
If you edit the script files (msgbrd.cgi and moderate.cgi) on a PC then make
sure you transfer them by ftp in ASCII mode. Other files may be transferred
in binary mode.
7. Using the board
===================
The message board is accessed with a web browser at an URL like
www.YOURDOMAIN.com/BOARDDIR
You don't have to specify the name of the index file. Click on faq for
directions. Try the test board first www.YOURDOMAIN.com/test
8. Using the moderation tool
=============================
You should check the message board regularly for inappropriate messages.
You may assign this job to one or more moderators. A special moderation
tool allows the moderators to expire, delete, or edit messages.
The moderation tool is accessed with a web browser at the URL
www.YOURDOMAIN.com/cgi-bin/moderate.cgi
Click on help and read the instructions carefully (the help message is
stored in the file boardsetup/modhelp.htm)
The moderation tool will update all indexes and links according to the
changes you make. It is therefore important that you don't use any other
method to delete or edit messages.
Assigning passwords to moderators
---------------------------------
There must be at least one moderator (possibly you). The list of moderators,
their passwords and access rights are stored in the file moderators.txt.
For each moderator add a line in moderators.txt. The line should look like this:
Felicia, xq67j, topic1, topic2, test
where Felicia is the login name of the moderator, xq67j is her password, and
topic1, topic2 and test are the directory names of the boards she is allowed
to moderate. Note that all moderators must have access to the test board.
To give access to all topics, write
Felicia, xq67j, all
How to hide the password file
-----------------------------
There are different ways to prevent outsiders from reading the file
moderators.txt, depending on the system setup:
Method 1:
If your web root directory is different from your home directory then
place the file moderators.txt in the latter, or in any other directory not
accessible by http. The path and filename is specified in the line
export UPWF=$HOME/moderators.txt
in the file makeboard.
Method 2:
Change the access rights to the file moderators.txt with the command
chmod 600 moderators.txt
This works only if cgi scripts have the same access rights as you.
To check the access rights of cgi scripts: look at any message file generated
by the message board system. If the owner is your name then the cgi script
has the same rights as you. If the owner is nobody then it has not.
You may change these rights by the command (?):
chmod 4755 cgi-bin/moderate.cgi
If it still doesn't work then change the attributes back with the commands
chmod 666 moderators.txt
chmod 0755 cgi-bin/moderate.cgi
and use another method.
Method 3:
As a last resort, make the file appear to be a program or script so that
it will generate an error if somebody attempts to read it by http:
rename the file moderators.txt to moderators.cgi and change the line
export UPWF=$HOME/moderators.txt
to
export UPWF=$HOME/moderators.cgi
in the file makeboard.
9. Support for search engines
==============================
The file robots.txt in your web root directory tells search engines to
stay away from all files in the old and deleted directories.
You may edit this file if there are more files you don't want the search
engines to find.
If your web URL is of the form
www.SERVICEPROVIDERSNAME.com/~YOURNAME
or
www.SERVICEPROVIDERSNAME.com/YOURNAME
then the robots.txt may not be recognized by search engines.
You may want to specify the way your message board is presented to anybody
who finds it in a search engine like AltaVista by editing the line
in the file index.shtml. Similarly, you may add keywords by editing the line
10. Maintenance
===============
It is recommended that you make backup at regular intervals. See below.
You may check from time to time how much disk space your message board is
using and remove old messages to free disk space. You must use the moderation
tool for this, don't just delete message files. Please click on help on
the moderation page for instructions.
If you want to edit any message, use the moderation tool.
If you want to edit the index file to embellish the layout then use an
ASCII editor.
Don't edit any index or message file with Frontpage! The Frontpage editor
will change some hidden codes that are necessary for the message board
scripts to work. It may be possible to use another HTML editor (or an old
version of Frontpage) but at your own risk. You have to check with an
ASCII editor if the hidden codes are intact.
Check the file error.log in the home directory. This is a log of all errors.
You may delete it when it becomes too big.
Also, check the file moderate.log in the home directory. This is a log of
all moderation actions. delete if too big
11. Making backup
=================
Run the script ./backup in the boardsetup directory. This will make or
update the file bbackup.zip. Transfer this file by ftp in binary
mode to the computer where you want to store the backup.
The archive bbackup.zip contains all messages, index files, scripts, etc.
12. Filelist
============
Files in directory boardsetup used permanently:
boardlist.txt directory names of all message boards
modhelp.htm instructions for moderators
Files in directory boardsetup used during setup or when adding a new topic:
msgbrd.zip distribution file
readme.txt this text
makeboard script for making new message boards
backup script for making backup of all messages
bbackup.zip backup archive made by backup script
msgbrd.cgi main script for message board. copied to directory cgi-bin
moderate.cgi moderation tool. copied to directory cgi-bin
counter.cgi ssi counter script. moved to directory cgi-bin/counters
index.shtml template for main index
dindex.shtml template for index of deleted messages
oindex.shtml template for index of old messages
uindex.shtml template for unthreaded index
faq.htm template for frequently asked questions
s.css style sheets. copied to board base directory
message.gif default logo for index files and normal messages
old.gif default logo for expired messages
deleted.gif default logo for deleted messages
test.gif default logo for test board
Files in directory cgi-bin:
msgbrd.cgi main script for message board.
moderate.cgi moderation tool
Files in directory cgi-bin/counters (if server side includes):
counter.cgi ssi counter script
*.shtml access counters for each main index
Files in each board directory BOARDDIR:
index.shtml main index
dindex.shtml index of deleted messages
oindex.shtml index of old messages
uindex.shtml unthreaded index
faq.htm frequently asked questions: instructions to users
t.dat thread counter
s.css style sheets for all messages and indexes
m.gif logo shown on index files
Files in directory BOARDDIR/messages:
m.gif logo shown on normal messages
xxx-1.shtml first message in thread xxx. Includes thread index
xxx-yyy.htm message number yyy in thread xxx
Files in directory BOARDDIR/old:
m.gif logo shown on expired messages
backupxx.htm backup of main index for day of month xx
xxx-1.shtml old message
xxx-yyy.htm old message
Files in directory BOARDDIR/deleted:
m.gif logo shown on deleted messages
xxx-1.shtml deleted message
xxx-yyy.htm deleted message
Files in home directory:
moderators.txt list of moderators with passwords and access rights
error.log log of all errors. delete if too big
moderate.log log of all moderation actions. delete if too big
Files in web root directory:
robots.txt instructions for search engines
13. Troubleshooting
===================
Installation script won't run
-----------------------------
See instructions below on manual installation.
Perl scripts (*.cgi) won't run
------------------------------
Make sure they are executable: chmod 755 *.cgi
If you have edited a perl script on a PC, make sure you upload it by
ftp in ASCII mode.
Check if the scripts have the right path to perl:
On the command line write
whereis perl
Check that the path to perl specified after #! in the first line of
msgbrd.cgi and moderate.cgi corresponds to the path you get with the
command: whereis perl
The index file index.shtml is corrupted or empty
------------------------------------------------
Find the latest backup in the BOARDDIR/old directory and copy it to
BOARDDIR/index.shtml
14. Manual installation
=======================
Make a directory for each messageboard (here called BOARDDIR).
Make three subdirectories BOARDDIR/messages, BOARDDIR/old, and
BOARDDIR/deleted. Make write access to these directories.
Copy the following files to each BOARDDIR:
index.shtml, uindex.shtml, oindex.shtml, dindex.shtml, faq.htm, m.gif, s.css.
Make an empty file named t.dat in each BOARDDIR.
Make write access to all files in BOARDDIR except faq.htm, m.gif, s.css.
Put a copy of m.gif and s.css in each of BOARDDIR/messages, BOARDDIR/old, and
BOARDDIR/deleted. The logo files m.gif may be different.
Edit BOARDDIR/index.shtml and make the following changes:
Insert title, description and keywords.
Edit the line