5.12.97

			Manage The Site Yourself
			________________________



			Table of Contents:
			_________________

	1.0 Introduction


	2.0 Convenience and flexibility


	3.0 Installing 
 	  3.1 Overview
	  3.2 FS vs URL abbreviations' concepts: 
	  3.3 Installation Steps:
	    3.3.0 Fetching and Uncompressing:
	    3.3.1 Configure the tool to make it work on your server:
	    3.3.2 Modifying the html template files for your web-site
	    3.3.3  User Authentication Tutorial:
	    3.3.4 Creating the starting point of the web site:

	4.0 Running 


	5.0 Security Issues
	  5.1 Securing the created site from ordinary users making 
		accidental "bad" things
	  5.2 Securing the tool from malicious users
	  5.3 Making any of your cgi tools more secure	

	6.0 Trouble-shooting


	7.0 Extended features
	7.1.0 what's new script

	8.0 Implementation

__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________



	1.0 Introduction
	________________

    Manage The Site Yourself (SiteManager) - A Tool to allow people without 
web-site building skills (read: without knowing UNIX/NT OS, HTML) build it 
by few mouse clicks. It should be a good tool for the project management,
where many people have to insert different documents, so every one can do
it. No need for a dedicated person to insert documents into the web tree. 

    The SiteManager tool lets you administrate your web pages' content
from your web browser. It has the following features: 

     1. Uploading any files from the computer you invoked the browser from, 
	linking them on the way to index.html in the directory you have 
	chosen to call the script from.

     2. Creating sub directories, with building of the index.html in that
	new directory on the fly and link to call the SiteManager. The script 
	supports unlimited nested subdirectories

     3. Creating links to other docs on the web.

     4. Updating the existent files with new ones updating the link if the 
	file's name has been changed.

     5. Updating the titles of the links to files and directories.

     6. Deleting files, directories and links, while unlinking them from 
	index.html. Safe delete: the files and dirs aren't actually deleted 
	but moved to the ./trash directory in the root of the project, so no 
	disaster may happen to your files in case someone accidently or on 
	purpose deleted your important files


__________________________________________________________________________

	2.0 Convenience and flexibility
	_______________________________

    Easy to install: Installation can be done by the user or at the
system level.(Refer to sec. 3.0 Installing) 

    How SiteManager is different from other existent packages: It does
almost the same thing (like your favorite file manager does) but the best
part of it, that your final wish is to have all documents to be linked,
so other users can use their browser to surf your site. And SiteManager
release you from these chores. Just upload files, create directories, add
links, modify or delete them all new linking , link modifications and
unlinking is done be the tool.

    Easy to use: Call the script by following the link at the bottom of
each index.html, and you are two clicks far from accomplishing one of the
tasks listed above (Refer to sec. 4.0 Running ) 



__________________________________________________________________________

	3.0 Installing
	______________


    3.1 Overview

To help you to see the whole picture, I draw the following file's
structure of how your site should look with cgi area + tool and docs area +
 your site. It may vary form server to server but it helps to see where are
different files belong to.
 


		-- server's root dir --
			  ||
  	--------- path to your cgi area ----------
	     |				       |
    	    docs   	 	  	    cgi-bin 
    	     |				       |
 ------- the-root-of-the-site ----------      ------ sitemanager tools ---
| |   |	    |	     |	   | ||||     |		    	      |	  |   |
| |   |  index.html  Subdir1 	   -- SubdirN_    sitemanager.cgi |   |
| |whatsnew.html    _|   |	      |       |		whatsnew.cgi  |
|trash dir	   |	 |	      |       |			more-tools
images dir    index.html Subdir1.1  index.html SubdirN.1
		          | | | |		  ||||
	=====================================================
	====== 		Your site is grows here        ======
	=====================================================


    3.2 FS vs URL abbreviations' concepts: 

	Important: We have two concepts here in Site Manager. 

    1.  Directory or file on your FileSystem (server) when you work on 
	plain Unix do "cd" and other things - I'll refer to it as FS

    2.	  Directory or file as URL (Universal Resource Locator) when you 
	access it by your browser with http://... format - I'll refer to 
	it as URL


    3.3 Installation Steps:

    3.3.0 Fetching and Uncompressing:

	Choose the place on your cgi-bin area you want to put the tool in.
	copy the sitemanager.tar.gz there and change to that directory 
	(lets say it is /home/httpd/cgi-bin/tools, that directory should 
	already exist)

	% cp sitemanager.tar.gz /home/httpd/cgi-bin/tools
	% cd /home/httpd/cgi-bin/tools

	Then uncompress and extract the files:
	
	% gzip -d sitemanager.tar.gz
	% tar -xvf sitemanager.tar

	Now you will see a new directory 'sitemanager' created:
	Go there:

	% cd sitemanager

    3.3.1 Configure the tool to make it work on your server:

    	Configure the ./conf/sitemanager.cfg file: 
--------------------------

 Configure the following variables to suite your site's configuration


	$server - the URL Directory of the script (don't include the name
	 of the script)
$server ="http://www.stas.com/cgi-bin/sitemanager/";


	$docs - the URL Directory where your documents' root is sitting ,
	actually the root of your site as you access it by http://...
$docs = "http://www.stas.com/sitemanager/";


	$cgi_dir - Location of Directory of the script on your filesystem  
$cgi_dir="/home/httpd/cgi-bin/sitemanager/";


	$docs_dir - Location of Directory where your documents' root is 
	sitting on your filesystem
$docs_dir="/home/httpd/docs/sitemanager/";


	$manager_email - the email of the sitemanager (don't forget to 
	put \@ instead of @)
$manager_email = 'you\@yourmachine.com';


	$manager_name - The full name of the manager
$manager_name = 'Your name';


	$whatsnew - If you want to use the whatsnew.cgi script (ref to sec. 
	7.1.0 what's new script) specify its location, if you put it in the 
	same place with sitemanager.cgi it
	should be $whatsnew="$cgi_dir/whatsnew.cgi"; If not change it to the
	proper location in the filesystem


	$dir_mode - Directory Creation MODE -- it  override the umask value
$dir_mode="00750";      # 00750 == rwxr-x---


	$manage_lockfile - The name and location of the lock file
$manage_lockfile="/tmp/.sitemanager.lock";


	$trash - Trash Directory location - I did it:
$trash = "$docs_dir/trash";
	Note you have to create that directory by hand
% mkdir $docs_dir/trash      - replace $docs_dir with the value from above

	$script - the path to the script the main script we do it relative to
	the server cgi-bin location. Change it only if you change the name of
	the cgi tool
$script="$server/sitemanager.cgi"; 


	$tail_file and $head_file are templates for the new files building
	Don't change these too
$head_file="./tmpl/head.html";
$tail_file="./tmpl/tail.html";

	Ok now we will use a few images in our application. Most of the servers
	don't allow to put images under cgi-bin directories. So your must put
	it under your docs location We need only a few images to distinguish
	between files, links and dirs and a few other so move them to the
	proper place
% cd $cgi_dir       -- to the root of the sitemanger in cgi-bin area ($cgi_dir)
% mv images $docs_dir  -- to the root of the sitemanger in docs area

	$img_root - URL of the Image's root
$img_root="$docs/images";

	Here we will specify full Img tags. They include full URL as defined in
	$img_root. If you want to provide images from your own. put them in 
	images directory in the docs root and modify the following tree values

	$img_file - Image to represent files (the leaves)
$img_file="<IMG SRC=\"$img_root/pingreen.gif\" BORDER=0 ALT=\"Link\">";

	$img_dir - Image to represent dirs (the nodes)
$img_dir="<IMG SRC=\"$img_root/pinpurpl.gif\" BORDER=0 ALT=\"Dir\">";


	$img_link - Image to represent links (interconnections)
$img_link="<IMG SRC=\"$img_root/blue_tri.gif\" BORDER=0 ALT=\"Dir\">";


You have finished to configure the tool


--------------------------

    3.3.2 Modifying the html template files for your web-site

3.3.2.0	You have to template files to change to fit your needs: head.html and 
	tail.html So you will want to modify them, add your graphics, pointers 
	and etc.


3.3.2.1 Carefully change the ./tmpl/head.html. It's a header which will 
	be added for each new index.html in each new directory you create. 
	The things you MUST leave UNTOUCHED are:

	<HTML>
	<HEAD>
	<TITLE>
	<!-- INSERT TITLE -->
	</TITLE>  
	</HEAD>
	[... snip]
	<!--PARENT-->
	<!--SEARCH-->
	<!--HOME-->
	<!--MAP-->
	[... snip]
	<!-- Please, Be informed that you are not allowed to change nothing
	in the structure of this document. Only links and files! Do not
	add or remove anything handy. Only thru the script !!! If you
	do so you can destroy the script's sensitive codes and nothing
	will work properly -->
	[... snip]
	<!-- INSERT TITLE -->
	[... snip]
	<!------------------------ END OF HEADER ----------------------------->
             ||
	     ||	
	The last line MUST BE the LAST line of the HEADER.[== head.html]

3.3.2.2 Change "./tmpl/tail.html" but be careful since it includes script's 
	sensitive pieces of code. 
	The TAIL [tail.html]  must start from this line:

	<!------------------------ START OF TAIL ------------------------------>

	Don't change the following line:
	<A HREF="CGI-SCRIPT?UPDATE=START&UPLOAD_DIR=CURRENT_DIR">

3.3.2.3 Now check if "sitemanager.cgi" mode are OK. Httpd should be able to 
	execute it. Generally you have to make it -rwxr-x---
	with "chmod 0750 filename". The best choice is to make it 
	-rwx------ so no one could fiddle with it. (chmod 0700)
	but check whether you can do it. 
	  The first thing to check what is the right priority to set is 
	to run my test script which shows you the environment variables. 
	  First run it from the command line "./test/test.cgi" and see 
	whether you have no errors. You do have perl, right? But may be 
	it's located in a different place -- so change the first line of 
	the script to reflect it. Try "which perl" or "whereis perl" to 
	find out its location. Did you do "chmod 0750 ./test/test.cgi"
	  Next point your browser to 
  	http://your.host/path/to/your/cgi_dir/test/test.cgi . But first 
	make sure it is executable (chmod 0750 ./test/test.cgi). If it 
	properly works set the same mode for the sitemanager.cgi and you 
	can move on.
	If it's still not working: Did you put it under cgi-bin directory
	or one of its subdirs ? If not you better do it first, and then 
	try again. If you still have a problems contact you sysadmin
	for the help.

	  After the test.cgi worked OK, set the same access rights to 
	./sitemanager.cgi, run it from command line , If it's OK - move on   

3.3.3   Now you must be concerned of security problems that might arise, please
	refer to [sec 5.0 Security Issues] how to setup a security stuff (theory) 
	and then continue with User Authentication Tutorial: to finish the 
	setup of the cgi tool


    User Authentication Tutorial:

 First, create a hidden subdirectory in your cgi-bin area:
 Type at your shell prompt:
% mkdir .admin; 
% cd .admin 
to create and move into auth's directory.

Next, password protect this new directory. You can do this if you're
using the Apache or NCSA web servers. Use any text editor to create a
file there called .htaccess containing

    AuthUserFile /path-to-sitemanger-cgi-dir/.htpasswd
    AuthGroupFile /dev/null
    AuthName SiteMgr
    AuthType Basic
    
    <Limit GET POST>
    allow from your-domain.com
    require user foo
    </Limit>

    On the first line, substitute the absolute file system path to a file
called .htpasswd in any directory in which you have write permissions and
which is also readable by the web server. However, it should not be in
the server's document root (where it might be displayed to anyone by the
server) so do not specify a directory within your web pages. Further
below, specify your own domain in place of 'your-domain.com'. On the next
to last line, in place of 'foo', substitute a user name of your own
choosing. 

After this file is created, at your shell prompt, type

% htpasswd -c /path-to-sitemanager-cgi-dir/.htpasswd foo
     
to create the password file, but substitute the file system path and a
user name in place of 'foo'. You'll be asked to type a password for the
user you specified. If your system can't find the htpasswd program, ask
your system administrator where it is. (It can be found in the source of
the Apache web server.) 


 Test the password protection:

   Before copying SiteManager to this directory, test the password
protection. Point your browser to the url of this .admin directory, for
example, http://www.yoursite.com/path-to-sitemanager-cgi-dir/ If your
browser asks you to supply a user name and password, the directory is
protected. Try mistyping the user name and password you just created. You
should receive an authorization error. Then type them correctly. You may
then receive a file not found error; don't worry about that. If these
things don't happen, then don't proceed. Ask your system administrator
how to protect a web directory. 

    3.3.4 Creating the starting point of the web site:

.	To start using the tool you need to create the first page, you 
	do so by running the script as you have specified in the config 
	file http://yourhost/pathtoyourcgi/sitemanager.cgi
	You will get a page with explanations, You have to fill 2 fields 
	in the form: 

	1. The FS Directory of your first page,(Important: that directory 
		must exist!, If not create it before you press submit)

	2. The URL of the sitemanager script (you will get the location 
		you have called it from as a default )

 	After submitting to the script you will receive your initial page,
 	as a response, go to the Menu->Save, and save it in the FS Directory 
	of your first page as you filled in the form before while naming it 
	index.html
	And your installation process should be finished

	Just click on "Manage the Site Yourself" link and start adding
	a new directories and fields.


__________________________________________________________________________

	4.0 Usage
	___________

  The usage is very simple:
	When you saved the first page, point your browser to that index.html
	file you have just saved by http://yourserver/yourpathtosite/index.html
	You will get almost empty page (Or anything you have modified in the 
	head.html and tail.html). Find a link called 'Manage the Site Yourself' 
	at the page's bottom. Follow it.
	You will get a new page with a few forms to upload file, create directory,
	create link, update file and delete directory/file/link. Go to the form 
	of the task you want to perform, and follow the instructions written inside
	the form. The rest should be intuitive and explained in place.
	Now you are ready to fill your site with your content
 
.	So any time you want to modify something, click on "Manage the Site 
	Yourself" link and do whatever you need.

	That's all folks!



__________________________________________________________________________

	5.0 Security Issues
	___________________

    5.1 Securing the created site from ordinary users making accidental "bad" things

    As I said before, SiteManager In each directory creates index.html
file and works with it. I have worried that you can't upload files named
index.html so you will not overwrite the existent index.html and breaking
the web structure by doing so. 

    If you try to upload a new file and other file with the same name
already exist you will be not allowed to perform that task and you will
receive an error message alerting you about the problem, and directing
you to rename the file you try to upload or delete the already stored
file in first place. The same thing holds for directory management. Note,
that it will not prevent from you to update the old file with the new one
(with the same name) in case you use Update option. 

    5.2 Securing the tool/site from malicious users

    SiteManager will only browse directories in or below its own parent
directory, which it assumes is the top web directory for your site.
(Refer to sec. 3.0 Installing )

    SiteManager will accept form data only from itself, by checking the
HTTP_REFERER variable (it generates its own web forms). If the referring
form is not itself, it will not process any form data submitted and will
return only the default web page indexing the top of your site (the
parent directory of SiteManager's directory). This helps to prevent 
arbitrary form data from being submitted, either with method POST through
an alien form or with method GET and the query string or path info.. 

One option is to use server's security mechanism (.htaccess) (Ref. to
sec.  3.3.2.4 User Authentication Tutorial) 

Other is to write your own routine to check login and password of each user 
and maintain the database of these.

    5.3 Making any of your cgi tools more secure

    The issues surrounding modification of others' web files can be
solved by using <A HREF="http://www.umr.edu/~cgiwrap/"> CGIWrap</A>. The
link leads to more information.

__________________________________________________________________________

	6.0 Trouble-shooting
	____________________



Q1. My Directories aren't being created or Files Aren't being Uploaded?
	You probably have a problem with main site's directory access mode,
	it must be writable by your cgi script, probably you need to do 
	chmod 0700 dir 		# -rwx------
	or  
	chmod 0770 dir		# -rwxrwx---
Q2. When I remove files/dirs they aren't moved to trash dir ?
	Read the Q1 and change the trash's dir mode

__________________________________________________________________________

	7.0 Extended features
	_____________________


     7.1.0 what's new module

    Any time you add some document using SiteManager, it updates
the "What's new page" to include the pointer to the updated document,
when the update occurred and a link to directory where the modification 
has occured.

    The new items are getting added at the top $limits specifies how many
 items to keep

    If you do delete or update while the link is still on the list -- list 
reflects these changes too

use Whatsnew; 

whatsnew( $action , $group_dir , $link_url , $link_title , $dir_url , 
		$dir_title ); 


	FULL DESCRIPTION 

    This module updates the specified $list="$base/$group_dir/$filename" 
file, when some changes are done to the web site. When you add files
call whatsnew() subroutine of this packagewith $action ='add' when you
remove some file call it with $action ='delete'

    The idea to have a html file with special format (I made it a table
structure), which is updated automatically when some change to your WWW
site is done Just add a short piece of code to the function that
changes the site to run this script, or run it manually in case you are
the one who perform the changes. You can specify a limit of the links
to keep in that file ($limit var in ./setup/whatsnew.cfg)

    Modify the ./setup/whatsnew.cfg file. Set $base to the root of your
site (e.g. http://www.nowhere.com/home/, $filename="whatsnew.shtml"  to
call that file './tmpl/whatsnew.html'. Copy the template
./tmpl/whatsnew.html file to the path you want and modify it to suite
your needs. (As you keep reading you will learn how to specify multiply
files.)

    In your script you call whatsnew() with $group_dir variable. It
helps you to specify the related path between $base and $filename. so
you can modify $filename in different directories. (e.g if $group_dir
named 'users/new' you will get $list=``$base/ $group_dir /$filename''
=> http://www.nowhere.com/home/users/new/whatsnew.html)

    $limit -- says how many links to keep in that file. The algorithm
is of FIFO. The oldest link will be sweeped out when the $limit will be
exceeded. New links are added at the top! 

    Locking -- if someone else tries to modify the same file you are
working on, he will have to wait till the running program will leave
the critical section and release the lock. (the same works for
applications). 

__________________________________________________________________________

	8.0 Implementation
	_________________

    The script has been written in perl5. All the interface has been
done in HTML3.x Note that file uploading is possible only in Netscape >
1.0 only today. But I guess no one use Netscape <= 1 anymore... 

    The script is called by pressing the link on each of the html pages
of the site The link knows to pass the filesystem path of the directory
where the index.html file is located. Scripts go to that index.html
file, reads it in , parses it to learn link->title pairs, then return
to user the form with 5 forms to choose from. 

3 Forms which aren't related to the old content:

    New Document Upload
	Allows you to browse the filesystem to choose the file, 
	to specify the title of the file and submit button to upload it
	While uploading the file and saves it in the directory it was 
	called from and updates index.html to point to this new file

    New Directory Create 
	Allows you to choose the name of the directory to be created
	and its title. When pressing submit script creates the new 
	directory and link it to the index.html. After it creates new 
	index.html by using head.html and tail.html templates, and inserting 
	on the fly the new title as new page's title and creates a link
	to sitemanager while setting the updaload dir variable.

    New Link Creation
	The same as New Document Upload, But nothing is saved, the link 
	is only inserted to index.html. In the form user types both link's
	title and the real link including 'http://', 'ftp://' or whatever 
	is suitable

3 Forms which dependant on the existant content

    Link's Title Change
	Form allows you to select one of the items linked to index.html 
	you called the script from. Once you choose the title you can 
	modify its name by typing  a new name in the input window and 
	pressing submit. Script locates the item in the index.html and 
	perform the inplace modification


    Document Update
	Here you do opposite to the "Link's title change" -- you keep the
	title of the item the same but you modify it's content by choosing
	a new file to upload. So you stay with old link but a new content
	This option especially usefull when doing updates to the same 
	document. Script goes to index.html locates the old item by comparing
	to old link->url pair, deletes the item from the index.html and the 
	old file from filesystem. Then performs 'New Document Upload'
	You can see this operation as aggregation of two actions: 
	Swap A by B  <=> as Delete A + Upload B
	And that's the way script works

    Link+Document Delete
	This option allows to select an item to be destroyed. User only 
	chooses the item and press submit. If the item to be destroyed
	is a link only index.html is modified. If it's a directory or file
	it's virtually deleted -- to be on the safe side it's moved to
	trash directory so this action is not so destructive as it looks 
	like

    3 first actions based on adding a link to index.html file. Script only
looks for <!--INSERT HERE--> Tag in html cod and pushs the item before the
tag.

    3 last actions in addition based on retrieving the existent items.
The action is performed by keeping each item in one line and they are 
separated one from another by another empty line. So first script reads
all the lines inside the array. It knows to skip the header and tail by 
locating special tags : END OF HEADER and START OF TAIL

So each index.html looks like:

<HTML>

Header stuff

<!------------------------ END OF HEADER -----------------------------> 

Item1

Item2

...

ItemN

<!--INSERT HERE-->

<!------------------------ START OF TAIL ------------------------------>

Tail Stuff

</HTML>


    Back to items' parsing... After having all the items extracted we need 
to extract the url->titles pairs which is done by simple perl pattern 
matching /<A HREF="(.*)">(.*)<\/A>/i (i=case insensitive) after that we have 
the link in $1 and the title in $2

That's all!

After each of these 6 actions script returns the status of the performed 
action with link to the index.html or to the script.

__________________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________


 LocalWords:  SiteManager html docs dirs sec dir cgi sitemanager Subdir SubdirN
 LocalWords:  whatsnew HREF Httpd perl whereis chmod http URL mkdir cd htaccess
 LocalWords:  htpasswd com foo url admin www yoursite Ref NT FS gz httpd gzip
 LocalWords:  xvf cfg rwxr rwx subdirs auth's NCSA AuthUserFile sitemanger dev
 LocalWords:  AuthGroupFile AuthName SiteMgr AuthType config yourhost REFERER
 LocalWords:  pathtoyourcgi yourserver yourpathtosite SiteManager's umr edu
 LocalWords:  cgiwrap CGIWrap rwxrwx trash's
