##################################################################
# BOARDMASTER - VERSION 1.6	
#	by Aristotle Vathis 
#	http://www.beholder.net
##################################################################
# COPYRIGHT NOTICE                                                           
#
# Copyright Aristotle Vathis  Beholder.Net (http://www.beholder.net)
#                                                                            
# BoardMaster may be used and modified free of charge by anyone so long as      
# this copyright notice and the comments above remain intact.  By using this 
# code you agree to indemnify Aristotle Vathis from any liability that might arise from it's use. 
# Selling the code for this program without prior written consent is expressly forbidden.  
#                                                                            
# Obtain permission before redistributing this software over the Internet or 
# in any other medium.  In all cases copyright and header must remain intact.
# 
##################################################################

##################################################################
# IMPORTANT NOTE:
#
# You are allowed to have as many banners & advertisers you want on the forum pages/messages.
# However, under the freeware licence, you're NOT ALLOWED to SELL or RENT the hosted Boardmaster forums 
# to third parties on your website, for obvious reasons. 
# This would require you to purchase a special licence - contact us for more details.
#
##################################################################

Boardmaster can be installed either in your /cgi-bin or in any other /directory (the latter is preferred)
Please follow the instructions step by step to ensure a painless and fast installation.


INSTALLATION:
--------------------------


1. The "xxxxx" extension & parameter ($id_unique): 	

The directory "user_data_xxxxx" and the file "bm_config_xxxxx.txt" contain this extension in their names.
FOR SECURITY REASONS YOU MUST MANUALLY CHANGE "xxxxx" TO ANY ARBITRARY CHARACTERS YOU'D LIKE.
No information is being encrypted (passwords/usernames) and this will ensure no-one (especially those that already have a BM copy, 
or know the filenames being used) can have access to the files containing "sensitive" information. (You can ofcourse chmod the 
bm_config and /user_data directory so that they are not accessible through the browser).

Choose any alphanumeric characters and replace "xxxxx" in the "user_data_xxxxx" and "bm_config_xxxxx.txt" names

MANUALLY EDIT "bm_config_xxxxx.txt" and change as well the 

	$id_unique = "xxxxx";
	$dir_passwords = "user_data_xxxxx"; 
	
to match the sequence you've choosen.
YOU MUST EDIT ALL SCRIPTS so that the 

	require "bm_config_xxxxx.txt";

command (found at the top of each script) points to the right file.You must replace all "xxxxx" 's  with the SAME SEQUENCE (CASE SENSITIVE too !). 
eg if you choose to replace "xxxxx" with "a1b34" then you should have:
(eg "/user_data_a1b34" , "bm_config_a1b34.txt" , require "bm_config_a1b34.txt"; and $id_unique = "a1b34").

DO NOT FORGET TO PROTECT the main /forums directory from users browsing it, by inserting an index.html file in it.
(by default, most servers check to see if an index. file exists and serve that, otherwise, they simply display the contents of the dir
and ie in this case, the user_data_xxxxx directory as well - which you are trying to keep to yourself).



2. The PERL header

You MUST make sure the perl header in ALL SCRIPTS is the right one for your server 
(eg #! /usr/bin/perl or #! /usr/bin/perl5.004 , whatever) 



3. full UNIX paths

***NOTE*** : the "bm_config_xxxxx.txt" and "cookies.lib" files MUST BE INSTALLED IN THE DIRECTORY CONTAINING THE SCRIPTS

If you decide to install the scripts in /cgi-bin (and the rest of the files to another directory, eg /forums), you MUST insert
the full unix path to those directories. To get the right paths, you can telnet to the server and use the "pwd" command.
There are two parameters you must edit in this case: (NOTE: "/" is required at the end)

$scripts_dir = "/home/beholder/www/cgi-bin/";		# full unix path to the scripts directory 
$threads_dir = "/home/beholder/www/forums/";		# full unix path to the main directory eg /forums .ie directory containing forums.shtml

AVOID INSTALLING /forums INSIDE /cgi-bin (eg /cgi-bin/forums). The properties of the /cgi-bin directory might be such that will give you errors
when trying to access simple html files ("you dont have permission to view this file", SSI problems, etc).
If you need to install *.cgi files in /cgi-bin, use , for example, the following kind of structure:

scripts in 	"/root/cgi-bin"
html files in 	"/root/forums"		(AVOID "/root/cgi-bin/forums")
graphics in 	"/root/forums/graphics"	
users' data in 	"/root/forums/user_data_xxxxx"



4. The Admin Password 

For security reasons, in order to run some scripts, you need to authenticate first.
You need to manuallly edit the scripts: bm_config.cgi, bm_moderate.cgi, boardmaster.cgi, bm_creator.cgi & bm_moderate.cgi
At the top you'll find:

	$authenticate_admin = "userpass"; 
	
change "userpass" to the desired value (no spaces or wild characters).



5. UPLOADING 

You must upload files in ASCII mode (most ftp clients, upload *.cgi and *.txt files by default in ASCII mode).

"cookie.lib" must be placed in the same directory as the scripts. 

You must create a new directory that will host the neccessary files and directories (CHMOD the directory if needed).
eg /forums (CASE SENSITIVE)
*.cgi files can be installed in the same directory, or in /cgi-bin if so required by the server.
One instance of Boardmaster, can support an unlimited number of forums.

*** NOTE *** : FOR EACH NEW FORUM YOU CREATE , YOU MUST CREATE MANUALLY (AND CHMOD) TWO DIRECTORIES (CASE SENSITIVE) FIRST:
eg /forums/FORUM1/
and /forums/FORUM1/messages/



6. CHMODing the files

You MUST chmod the *.cgi files to 755 (or in some cases, depending on server software & configuration, to 777)
and all the rest of the files AND directories (*.txt, *.shtml) at least to 664 (so that the scripts are ALLOWED TO WRITE/RE-WRITE on them).
New files created by the scripts must have a CHMOD of 664 at least, so they can be re-written - this is completely 
dependent on server configuration. In most cases you dont have to worry about it, but we've seen cases with writing problems 'cause 
of CHMOD problems (by default at 644, scripts not allowed to rewrite - ownership problems).

(to chmod files you can use your ftp client (option to "chmod" or "file properties" or "change file attributes") or you can telnet and use the command
eg "CHMOD 0755 *.cgi" etc).



7. Call "BM_CONFIG.CGI" through your browser

This script will allow you to edit almost all parameters.

NOTE: All main thread pages are pre-made (ie not made on-the-fly). The advantage is you get FAST loading pages, but there is a price you have to pay for this...
namely, you can not with ease change these parameters later on (scripts that will do mass replacements in html files are in development, and will be available soon).
Any changes you make after creating the forum, will not neccessarily affect already created forums/messages.
You may have to reset the forum and re-create it.

You can use the "BM_COLORS.CGI" script to test the look of the forum, before you create it.
MAKE SURE you get the COLORS right. You dont really have to worry about the rest of the parameters - do not modify anything unless 
you are certain the default values (as seen at www.beholder.net/forums/forums.shtml pages) do not match your personal taste.

***NOTE***: if at any point you get an internal serrver error message, after running bm_config.cgi, restore bm_config_xxxxx.txt with the default 
one contained in the zip package (please avoid entering non-legible characters/values in the forms).



8. Call "BM_CREATOR.CGI" through your browser.

This script will create all necessary files for each new forum you create.
YOU MUST FIRST CREATE YOURSELVES THE /NEWFORUM DIRECTORY in eg /forums that will host the new files,
and the /NEWFORUM/messages directory (/messages is CASE SENSITIVE - keep it lower case)

Then enter the neccesary parameters in the forms presented by the script and press CREATE.
The script will create a number of files - you may need to CHMOD these files, depending on your server configuration, 
so that the other scripts are allowed to write on them.



9. The script should be running fine now.
Make sure the chmod properties of the new files that have just been created are such that the scripts can write on them.

***NOTE*** : At all times, make sure you have enough free space on the server, otherwise, you'll be forced to reset the forums !
This may sound silly, but reality has a different opinion...


The scripts contain error messages that will point you to the right direction, if any arise.






HOW TO CREATE A NEW FORUM
---------------------------------------------------------
YOU MUST FIRST CREATE YOURSELVES THE /NEWFORUMX DIRECTORY in eg /forums that will host the new files (ie /forums/NEWFORUM )
and the /NEWFORUM/messages directory (/messages is CASE SENSITIVE as well - keep it lower case)
CHMOD these directories properly, so that the scripts are allowed to write in them.

Call "BM_CREATOR.CGI" through your browser. This script will create all necessary files for each new forum you want to add.
Then enter the neccesary parameters in the forms presented by the script and press CREATE.


DELETING MESSAGES 
-----------------------------------------------------------
For administrators: 
To delete messages, simply choose EDIT (edit icon, inside the message), then check the delete box, 
and at the password field enter the admin's "username=password".

To delete users, you must manually (for the time being) edit the x.txt file (where x is the first letter of the username)
found in the /user_data_xxxxx directory.

ADMINISTRATORS
-----------------------------------------------------------
To add administrators, simply edit "administrators_xxxxx.txt" file in each /Forum directory, and insert the additional usernames/passwords you want.
The file "administrators.txt" is only used for diplay purposes.

BANNING USERS
-----------------------------------------------------------
If registration is "ON", BM will log the IP and ISP of the user upon registration.
If you decide to ban a user, simply edit "banned.txt" found in the /user_data_xxxxx directory, and insert the IP & ISP of the user.


GRAPHICS
-----------------------------------------------------------
Two (2) Graphics sets are included in the package : graphics for white and black backgounds.
The "/graphics" directory must be in the same directory as the forums.shtml file 
( eg if shtml files installed in www.mydomain.com/forums/, graphics should be at www.mydomain.com/forums/graphics/ )


MODERATION
------------------------------------------------------------
Call "bm_config.cgi" through your browser, and change the MODERATION to ON.
First choose an admin password and edit the top of the script "bm_moderate.cgi"
($admin_passsword = "...";). 
Upload, chmod, and simply call the script through your browser. You must then enter your password and choose the board to moderate.
A list with all messages awaiting approval will be displayed. More than that, you can MASS edit titles, and the messages itself !

There are three radio boxes there: ADD/DELETE/HOLD If you check on ADD, messages will be approved, DELETE will erase
the message, and HOLD will leave it as is, on hold, for later approval.

Once you're ready, just click on "MOVE MESSAGES". Another page will be display, with a link to "Click here to apply changes to ForumX".
You MUST follow this link, before any changes appear on the main threads. Then you must simply repeat the process for each forum you may have...


SERVER SIDE INCLUDES
-----------------------------------------------------------
All html pages have the extension *.shtml
Server must support SSI for *.shtml - if not you can change the server configuration to add *.shtml (or do it the hard way - not recommended: 
ie mass replacement/rename of files & scripts: ".shtml" ---> ".html")



TROUBLESHOOTING
----------------------------------------------------------
The scripts have error messages that will point you to the right direction, if any problems arise. 
Please have in mind the following:

1. Most problems arise due to users forgeting to CHMOD directories and/or files. 
2. Commonly, people get the full unix paths wrong - to get the right paths , you can use telnet and the "pwd" command.
3. You can always telnet to you server and use the "perl -cw scriptname.cgi" (to check syntax) or even "perl -d scriptname.cgi" 
(debug) to get usefull info (press 'n' at the first prompt, then keep pressing 'enter').
4. Use the forums on Beholder.net to seek assistance. Always use the search engine first, or head to the FAQ section.
	
5. I am painfully aware that minor (or not) bugs do exist. Moreover, some features are yet inactive. I'm trying to fix things round and improve the script...
The board has been extensilvely tested with AUTHENTICATE set to "ON" (ie registration & authentication needed). 



PLEASE, let me know if you install Boardmaster on your website. I like to see my work in action... 	
Feel free to send me any comments/suggestions you may have.

Aristotle Vathis

http://www.beholder.net


##################################################################
# COPYRIGHT NOTICE                                                           
#
# Copyright Aristotle Vathis  Beholder.Net (http://www.beholder.net)
#                                                                            
# BoardMaster may be used and modified free of charge by anyone so long as      
# this copyright notice and the comments above remain intact.  By using this 
# code you agree to indemnify Aristotle Vathis from any liability that might arise from it's use. 
# Selling the code for this program without prior written consent is expressly forbidden.  
#                                                                            
# Obtain permission before redistributing this software over the Internet or 
# in any other medium.  In all cases copyright and header must remain intact.
# 
##################################################################