| TERMS AND PRIVACY: WebTools Copyright 
        (c) 2001, Julian Lishev, Sofia 2001. All rights reserved.This code is free software; you can use it, redistribute it and/or modify 
        it, but WITHOUT ANY WARRANTY, under the same terms as Perl itself.
  Please 
        keep structure of package and don't modify file names because you may 
        have problems with next version of this package! Also you can maintain 
        follow rules:You can't add additional variables into 'config.pl' file: 
        Please create your own config file for your private needs. (You can place 
        your own config files into 'conf' directory)
 You 
        can't add functions into package libs and modules: 
        Please create your own! (You can place your own libs and modules into 
        'libs/additionals' and 'modules/additionals' respectively)
   READ THIS! IT IS EXTREAMLY IMPORTANT:   Do 
        NOT discard this document! You must read all this INSTALL.HTML completely. 
        It exaplain all problems generally in Web/CGI programming and particular 
        in WebTools installation. This file relate not only with installation 
        tips but with common security problems and holes! Don't let yourself be 
        misled with simple "make" installation how it described below, 
        but take care about directories, files, permissions, apache's configuration 
        and OS specific.Note: You can install this package 
        ONLY one time and after that you can run different scripts via webtools, 
        so it is extreamly important to install package properly (now I can install 
        package in few minutes, but you should read all information in this document 
        and spend time in installation!)
 REQUIREMENTS: Perl (Perl 
        5.005_03 or later should work),Unix/Linux or Windows 9x/NT/XP
 
 Recomended:
 Perl 5.6,
 Unix/Linux OS,
 MySQL server
 
 Prerequirements:
 Only DBI 
        (for SQL access, respectively for Session/Users support)
 
 If you want to use MySQL you also need: MySQL 
        module
 For 
        MS-Access you need DBD-ODBC
 
 If you haven't SQL server you can use our build in FLAT DB (based on DBD::Sprite)
 
 INSTALL NOTES: First 
        of all you must have webtools package. It must be packed into one tar.gz 
        file.Please copy this .gz file into some directory and run follow commands:
 tar -zxvf 
        WebTools-1.26.tar.gzcd WebTools-1.26
 perl Makefile.PL makemake install
 make permissions
 make clean
 If you 
        are under Win, you must use 'nmake'. In this case please change 'make' 
        with 'nmake''nmake' you can download from ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe 
        (about 50kb). You don't need VC++ to run nmake!
 
 When you run command: perl Makefile.pl, you 
        will be asked to specify full path to your future webtools directory. 
        This directory must be into your cgi-bin directory!
 On my private server it is:
 /var/www/htdocs/cgi-bin/webtools
 but on 
        my Win system it is: c:/Apache/cgi-bin/webtools (Please 
        realize that you need HTTP access to your process.cgi 
        script!)If you don't know where is your cgi-bin directory, you still can install 
        package...just choose another directory! (after installation you must 
        move your installed package to your cgi-bin directory and if needed, change 
        owner of installed webtools and its permissions mode).
 After 
        successful 'make' you must check whether evrything is OK!Go to your webtools directory and check file mode of process.cgi it must 
        be: 0755
 Also it must be owned by your user (you don't need root access to install 
        this package!)
 NOTE: 
        You may have big problems depending of your OS and security settings! 
        To void this problem you must be very attentive:  - You 
        have only one real script: process.cgi, so it must be able to read and 
        write your files! So you must chmod to 0755. If Apache server don't change 
        user of script to your user, YOU must insure that process.cgi never will 
        try to read/write on directories where it has not access!To insure this you must know very well structure of Webtools module!
 webtools  
         ----- 
        conf|
 +---- 
        db
 |
 +---- 
        drivers
 |
 +---- 
        htmls
 |
 +---- 
        jhtmls
 |
 +---- 
        libs
 |
 +---- 
        logs
 |
 +---- 
        mail
 |
 +---- 
         modules
 |
 /tmp OR  +---- tmp
 
 For 'conf','drivers','htmls','jhtmls','libs','modules' 
        directories you need only 'read' access.
 For 'db' directory you need 'read' 
        access (and 'write' if you use DB FLAT - 
        default)
 For 'logs','mail' you need 'read' 
        and 'write' access (default these directories 
        are not used)
 You need also full access to 'tmp' directory 
        (your system directory or your own)
 Now let 
        see some examples:-------------------------------------------------------------------------------------------------
 CASE 1:  You are some good user(july) 
        on some good free host(newald.proscriptum.com) :-)))
 Let 'july' user has home directory:  /home/july 
        (we use virtual host: july.newald.proscriptum.com)
 His full cgi-bin directory is: /home/july/public_html/cgi-bin
 So  his webtools directory can be: /home/july/public_html/cgi-bin/webtools
 Now we can upload WebTools-1.26.tar.gz to our home 
        directory and after that to install script.
 After installation our process.cgi has permission mode set to 0755, directories 
        have permission modes: 0755 and any other files: 0444
 Features:
 - Our host is virtual, so Apache change user to 'july' when we start process.cgi!
 In other words we are ready to configure package whitout any hidden traps!
 Evrything is ok, so let run script: perl -c process.cgi
 
 -------------------------------------------------------------------------------------------------
 CASE 2:  You are some user (and 
        you has not virtual host) under Open BSD OS.
 User: snm
 Server: www.jozefina.bg
 User home directory: /home/snm
 His full cgi-bin directory: /home/snm/http/cgi-bin
 So his webtools directory can be: /home/snm/http/cgi-bin/webtools 
        ,
 please install package into this directory!
 Now let suppose that your scripts running with Apache's user (i.e. Apache 
        can't write into your directories when they has 755 permissions!). That 
        can be a problem, we realy need to write into db, 
        logs, mail and 
        tmp directories, so we must chmod these directories 
        to 0777 (BUT THIS IS 
        UNSECURE). To decide problem we must create these directories in 
        our home directory, for example:
 /home/snm/webtools/db
 /home/snm/webtools/logs
 /home/snm/webtools/mail
 /home/snm/webtools/tmp
 then we can chmod to 0777 these directories! 
        (other user can't read/write 'snm' directory, 
        so they can't access and these directories too :))
 After this you MUST move files from original(installed) directories to 
        directories we've just created (preserve attributes/permissions when files 
        are moved). Ok, is evrything done? Actualy not at all, you also need to 
        edit "config.pl". Please run 'pico' or some other editor and 
        change path to new location of db, logs, 
        mail and tmp 
        directories! (or 
        use install.cgi to modify config.pl file!)
 
 --------------------------------------------------------------------------------------------------
 CASE 3:  You have 
        root access! Well is not a good idea 
        to install webtools with root access! You 
        can login with some other user and install 
        package in directory you want and chown/chmod 
        if need (using root). With root access you can install package on way 
        you want and can resolve problems very fast (if you want you can run your 
        scripts with 'www' user and so on...). You 
        can create directories (db,logs,mail, tmp 
        ...) into some private directory (where nobady 
        except Apache can read/write)...
 NOTE: Please be very careful when install 
        any scripts/modules with root access. You bring responsibilty for your 
        actions!
 --------------------------------------------------------------------------------------------------
   SECURITY 
        SETTINGS:
 Before 
        you can go life in web you have to check security settings of your web 
        server!Here we suppose that you haven't root access, so you can't make any changes 
        to server if any security fixes are required.
 
 - First of all you have to check ability of externel user to access your 
        directories:
 (If you are owner of web server and you are the only one user on it e.i. 
        no body else can access remotely) you can close your eyes and leave this 
        check unperformed. Other else you have to check whether other user can 
        "cd" your directory. If that is possible you need to fix that 
        (contact your system administrator and ask him to protect your directory 
        of unauthorized access!)
 
 - Secondry you need to check ability of web users 
        to access and/or read your datas and/or scripts:
 Immediatly go to your "webtools/htmls" directory and "vdir"(or 
        "ls -l") this direcory. It should contain file "env.html" 
        and it shoultd be with permission: 644 (or 
        444) depending of your OS defaults. These 
        "htmls" actualy are embedded Perl files, so 
        it is extreamly important these files (htmls) to be unaccessable and unreadable 
        from Web interface i.e. line like this: http://your_server/cgi-bin/webtools/htmls/env.html 
        should return NOT html page, it MUST return "Internal 
        Server Error" because Apache must interpret these files as 
        scripts!!! If that is not true, you have to set other 
        extension for all files in webtools/htmls (.whtml 
        , .cgihtml , .htm 
        or .cgi are supported) That mean, that you 
        need to correct all files that access these ".html" files (and 
        given examples too). Other solution (when you have access to server) is 
        to forbid ".html" to be read in cgi-bin directory (you need 
        to edit httpd.conf -> please read Apache's documentation to learn how 
        to do that).
 NOTE: You can configure config.pl so extensions .whtml, .cgihtml and so 
        on to be treated as .html!!!
 
 - Finnaly solution (and in many cases the best):
 You can install webtools into ../cgi-bin/webtools and after that you can 
        move all directories and files in your "secure" home directory 
        where no body except you can read/write these files! Ofcource you must 
        leave at least "process.cgi" in 
        your web based cgi-bin/webtools directory and "conf" 
        directory too, after these operations you must 
        edit your config.pl file and mark changes of new webtools directory structure 
        (you should edit section "[PATHS]" 
        in config.pl). That is all but don't forgot to set variable $check_module_functions 
        = "on" (that is internal build 
        way to check your configuration!)
 NOTE: Please preserve permissions of directories and files in.
 NOTE: Apache's should handle (in httpd.conf) 
        .cgi and .pl 
        file with AddHandler!
 Example: AddHandler cgi-script .cgi .pl
 AFTER 
        INSTALLATION:
 
 - Before you can be able to run any srcipt (and examples) you must 
        configure your 'config.pl' file!
 For example of configuration please read HELP.doc (found into 'docs' directory)
 
 - If evrything is configured properly, then go into telnet(console) and 
        cd to your webtools 
        directory.
 Execute 
        follow line: perl -c process.cgi
 Evrything must be "OK" before you can go ahead. Now open one 
        browser's window and type follow url: www.your_host.com/~your_user/cgi-bin/webtools/process.cgi
 where:
 ~your_user is your 
        user name (remove it if you have your own server/virtual host)
 cgi-bin/webtools 
        is your http based webtools directory and
 process.cgi is your 
        base (only one) script!
 
 Into browser's window you will see your current configuration. Please 
        check it for problems/errors.
 Clear them all and then set variable $check_module_functions to 'off'
 Now you are ready to lear webtools and run all examples into docs/examples 
        directory!
 
 
 INSTALL.CGI 
        (WEB BASED CONFIGURATOR)
 
 At versioin 1.16 of WebTools, proscriptum.com released new feature for 
        easy making of WebTools configuration. This new feature allow remote configure 
        of config.pl file via Web interface i.e. you can make different adjustment 
        to almost every aspect of WebTools configuration. So at this point I will 
        recommend that script for configuration purposes instead of manual edit 
        of config.pl. Also with "install.cgi" you have unique chance 
        to create structure of MySQL and/or Flat DB without any additional work. 
        (for MS Access you still have to do manual work)!
 
 Get started:
 First 
        of all you need to insure that install.cgi has proper permissions mode 
        (755 i.e. must be executable and install.cgi must be able to write/read 
        ./conf/config.pl and ./db/ directory)!
 
 I have to explain: install.cgi need to write/rewrite config.pl file so 
        please set needed permissions for conf directory and for config.pl file! 
        Also install.cgi need to create files into database directory (./db/)
 
 At last install.cgi must have correct shebang (default it is: /usr/bin/perl) 
        This rule is important for install.cgi on the same way as it is important 
        for process.cgi So it is not a bad idea if you change shebang on these 
        two scripts at once (of course do it in case of wrong Perl location!)
 
 For advanced web programmers I will mention that install.cgi script is 
        not accessable on default (security restriction). So if you want to use 
        it, then you have to edit install.cgi (see first paragraph of script):
 - Set $install_script_available to '1' to enable script.
 - Set proper Admin user and respective password for script access!
 
 When you have done with WebTools configuration set again variable $install_script_available 
        to '0'! That will keep "hackers" away from your server! :-)
 
 Work with install.cgi is absolutely clear. Just run script on that way 
        and enjoy :-)
 http://www.yourserver.com/cgi-bin/webtools/install.cgi
 
 #-----------------------------------------------------------------------------------------# Step by Step Installation example:
 #-----------------------------------------------------------------------------------------
 tar 
        -zxvf WebTools-1.26.tar.gzcd WebTools-1.26
 perl Makefile.pl
 > 
        /usr/local/apache/cgi-bin/webtools/
 make
 make install
 make permissions
 make clean
 cd ..
 rm -rf WebTools-1.26
 cd /usr/local/apache/cgi-bin/webtools
 ls -l -a
 perl -c process.cgi     # Must be "ok"
 lynx www.your_server.com/cgi-bin/webtools/process.cgi
 # Should see webtools in check mode...see your current 
        configuration and edit where is needful!
 pico conf/config.pl (or use install.cgi to 
        modify config.pl file!)
 Edit where 
        is needful...
 lynx www.your_server.com/cgi-bin/webtools/process.cgi 
            #Check again ...ok?
 pico conf/config.pl (or use install.cgi to modify config.pl file!)
 Edit:
 $check_module_functions = 'off'; 
            # Now evrything is ok, so you could set "off" 
        value!
 lynx www.your_server.com/cgi-bin/webtools/process.cgi?file=env.html
 
 # If you want to configure properly your DataBase 
        driver with webtools please go to docs/
 # directory to find out how!
 
 #With line above you call simple script example...
 #----------------------------------------- END -------------------------------------------
 AUTHOR:
 Julian 
        Lishev,
 e-mail: julian@proscriptum.com
 |