FAQs (Frequently Asked Questions)
Installation
System requirements - what software and hardware I need to run it successfully?
How to install this software? - read README.TXT
Structure and Performance of this Software
Usage terms: read LICENSE.TXT
What I have to know if I write extension modules for this software? Tips.
Installation
[
top ] Q: System
requirements - what software and hardware I need to run it
successfully?
- web hosting account that allows cgi scripts, perl version 5, FTP or Telnet
access. Should work on any OS.
[
top ] Q: What is
mod_perl and how to install it?
mod_perl is a module for
Apache web server which can make perl
cgi-scripts run up to 20 times faster than in the standard CGI mode. This
is possible thanks to its property to compile the script only once and cache
it in the RAM. Download and install it as recommended by its documentation.
[
top ] Q: What is
FastCGI and how to install it?
FastCGI is a very similar to mod_perl
technology but is available not only for Apache web server and is not
limited only to Perl scripts. To use it you need FastCGI enabled web server
and Perl. There is a module for Apache which will enable the FastCGI mode.
Also Perl needs FCGI.pm module. Look in their documentation to find
out how to install it.
Structure and Performance of this Software
[ top ] Q: Files, directories and their purpose.
Directories:
DBPUB1/STD - perl modules with relatively standard
functionality (could be used in other projects too)
DBPUB1/NAVG - perl navigation modules specific for the
current project
DBPUB1/NAVG/en - perl navigation modules specific for
English language (default)
..... - and more languages
DBPUB1/ADMIN - perl modules used by the administration
script: admin.cgi
data - data files
docs - documentation
logs - log files
tests - some test scripts which can confirm the perl version
for certain standard locations
templates/admin - html template files for the admin.cgi
script
templates/en - html template files in English
(default)
templates/de - html template files in German
..... - and more languages: it=Italian, sp=Spanish, pt=Portuguese,
bg=Bulgarian, fr=French. Please note than not all of these templates might
be provided.
Files:
admin/admin.cgi - your Admin Panel; (Tip: protect
the admin directory with http access password)
x.cgi - standard cgi script wrapper
nph-x.cgi - nph-cgi script wrapper
nph-x-no-header.cgi - nph-cgi script wrapper (will not
return full http response header)
x.fcgi - FastCGI script wrapper
DBPUB1/STD/Parameters.pm - your parameters (updatable
via Admin Panel)
DBPUB1/NAVG/Sample.pm - use this module as a template
if you write extensions to this software
[ top
] Q: How this software works?
When you call the script(for example: x.cgi) from browser the
web server will execute the script. You should pass to the script the following
parameters:
NAVG - the navigation destination. The script will use
its value as a perl module name from DBPUB1/NAVG directory. The requested
module is designed as a object with a method run() which implements the main
work for this request. If no NAVG value is passed the module Main.pm is used
by default.
lng - which language we use. Possible values: en,
sp, it, bg ... and whatever subdirectories are available under NAVG
directory. If no value is provided english language (en) is considered.
For example calling http://.../x.cgi?NAVG=Sample&lng=de
will produce the output programmed by the DBPUB1/NAVG/Sample.pm module
and will use german language related templates(from templates/de
directory).
[ top
] Q: What is a nph-script?
NPH(Non-Parsed-Header) script means that the web server will not buffer
the cgi script output. It is used usually when we have to receive from the
script streamed data rather an immediately generated html response. To run
it this way use either nph-x.cgi or nph-x-no-header.cgi
[ top
] Q: How to improve the performance? Some test
results.
- run it as FastCGI application or under mod_perl
(Apache::Registry mode)
- to find out how much CPU seconds your script requires
use either the Chatologica HTTP Benchmark test utility or if you run it in
plain cgi mode open x.cgi file, look in the comments at bottom
of the file and uncomment the correspondent part of code which will show
on the screen the CPU usage in seconds. Use this information to monitor the
CPU usage especially if you write custom extensions to this software.
- use latest versions of Apache, mod_perl and FastCGI
- install Apache::DBI perl module. It will make database
connections persistent under mod_perl.
- if you notice that the swap memory space is used on your
server add some more RAM.
- mod_perl and FastCGI as memory hungry technologies. Using
proxy servers for these interfaces may reduce the RAM usage but with cost
of few CPU milliseconds per request.
Below are some performance test results made on the following
platform:
CPU: AMD K6-2/300Mhz, RAM: 128MB 8ns, EIDE, Linux RedHat 6.0, perl v.5.00503,
Apache v1.3.9, mod_perl v1.21, mod_fastcgi v2.2.2; Tested with Chatologica
HTTP Benchmark test utility v1.0
Compilation Times
Standard Perl modules: | Compilation time: |
CGI.pm | 118 ms |
CGI/Carp.pm | 67 ms |
lib.pm | 63 ms |
vars.pm | 10 ms |
diagnostics.pm | 520 ms |
strict.pm | 6 ms |
IO/File.pm | 160 ms |
FCGI.pm | 350 ms |
Exporter.pm | 30 ms |
DBI.pm | 210 ms |
DBD/mysql.pm + DBI.pm | 250 ms |
Optimized Chatologica Perl modules: (used as replacements of the standard Perl modules) |
|
CGI_Parser.pm (replaces the standard CGI.pm) | 8 ms |
MyCarp.pm (replaces the standard Carp.pm) | 4 ms |
More curious CPU times: | |
spawning a Perl interpreter to execute a perl script | 27 ms |
compilation of 1KB Perl code | 3 ms |
compilation of 1KB PHP3 code | 2 ms |
processing of one plain html page of 5KB (Apache 1.3.6) | 8 ms |
processing of one plain html page of 5KB (Apache 1.3.9) | 5 ms |
"File not Found" Error | 4 ms |
Navigation Destination Tests
URI/execution time |
FastCGI mode |
mod_perl |
mod_perl |
plain CGI mode |
x.cgi?NAVG=Sample |
15 ms |
15 ms |
20 ms |
76 ms |
x.cgi?NAVG=Sample |
+3.5 ms |
+3.5 ms |
+3.5 ms |
+3.5 ms |
x.cgi?NAVG=Sample |
+17 ms |
+17 ms |
+17 ms |
+17 ms |
DataBase Tests
Database |
FastCGI mode |
mod_perl |
mod_perl |
plain CGI mode |
Flat-file (1000 records) |
540 ms |
500 ms |
520 ms |
620 ms |
Flat-file (1000 records) |
340 ms |
340 ms |
360 ms |
480 ms |
Flat-file (10,000 records) |
3600 ms |
3600 ms |
3600 ms |
3700 ms |
Flat-file (10,000 records) |
2420 ms |
2260 ms |
2400 ms |
2530 ms |
MySQL (18,000 records) |
160 ms |
160 ms |
180 ms |
520 ms |
MySQL(18,000 records) |
153 ms |
163 ms |
Usage and Customization
[ top ]
Q: Can I rename files and
directories?
Generally spoken it's not recommended because this software may fail to find
some of its components if you rename them. However feel free to rename any
of the script file names: admin/admin.cgi, x.cgi, nph-x.cgi, ....
For example if your system do recognize only .pl files as perl scripts you
can rename x.cgi to myscript.pl. This software would work without
problems with the changed script name. It's not recommended to remove the
nph- prefix in the nph-script filenames because for some web servers it is
the only mark the a script have to function as a NPH.
[ top ]
Q: How to make my own design? Templates
usage.
Use the Templates Manager in Admin Panel to edit/delete/create your html
template files. As a principle we insert in any template special strings
like $out{'my_data_field_1'} which will be replaced with dynamically
generated html stuff during the execution of the script. These strings
$out{'key1'}, $out{'key2'} , $out{'key3'}, ... are in fact elements
of Perl hash variable %out which we use to store in these dynamically
generated html codes. If you wish to add some more dynamic data within this
template have it produced in the %out hash in the correspondent perl
module and then put the correspondent $out{'my_new_data_key'} string
in the template. Major strings that wish use in almost every html templates
are:
$out{'script_url'} - url to the current script (usually
used within the <FORM> tags)
$out{'nph_script_url'} - url to the current script but
with nph- prefix (usually used within the <FORM> tags)
$out{'lng'} - current language we use (used to promote
it between different script invocation by same user)
To find which $out{...} strings are allowed by a template open its original
version and look through for $out occurrences. A smart way to do this is
to use the "Find" function of your Notepad or WordPad.
Some standard template files:
header.htm - html code that we show at the beginning
of each page
footer - html code that we show at the end of each
page
notice.htm - custom error/warning message shown to client
[ top ]
Q: How to use it in multilanguage
mode?
Call the script with additional parameter lng. Possible values are
the two-character directory names under your templates directory.
it=Italian, sp=Spanish, pt=Portuguese, bg=Bulgarian, fr=French,
en=English(default), de=German.
Example: Call http://..../x.cgi?lng=fr will show you a page in french. As
well You can add your own languages adding the corresponded directories under
NAVG and templates. To create a template for this language
get the correspondent template file from the default templates/en
directory, translate and save it through the Templates Manager. You may need
to write and language specific perl modules under NAVG too. It is possible
when you request a page with language different than the default (en) to
see blank page. This is because there is no template created for this language
or there is a problem with reading the template file.
[ top ]
Q: How to add banners?
Just copy and paste the html code of the banners in your templates. Also
a good idea is to put it in the header.htm or in the footer.htm
file in you wish to edit only one file. There is a special string
$out{'random'} which have random values from 1 to 100. You can use
it within your LinkExchange or SmartClicks banner exchange html code to make
more effective random distribution of the banners through the pages. To set
different interval of random numbers modify eval_template() procedure
in DBPUB1::STD::Templater module.
[ top ]
Q: How to use it in mod_perl or FastCGI mode?
Examples.
Here is an example of my test platform on one Linux machine. I ran 3 Apache
web servers this manner:
- 1st is a plain Apache web server running on port 80 and serving
static objects as html files and images. It use mod_proxy and mod_rewrite
modules.
- 2nd is a mod_perl enabled Apache server running on port 8080. It
can serve requests to the cgi scripts for optimal performance. It is configured
to work this way:
http://localhost:8080/registry/x.cgi - it runs the script
under Apache::Registry mode
http://localhost:8080/perlrun/x.cgi - it works through
Apache::PerlRun handler
http://localhost:8080/cgi-bin/x.cgi - runs in standard
cgi mode
- 3rd is a FastCGI enabled Apache server running on port 7777. It
is configured to work this way:
http://localhost:7777/cgi-bin/x.fcgi - it runs the script
as dynamic FastCGI application
http://localhost:7777/cgi-bin/x.cgi - it runs the script
in standard cgi mode
I have configured the 1st Apache server to work as proxy server for
the cgi script requests to the 2nd and 3rd web servers in order to hide the
port numbers in the urls. Now I can run the x.cgi script in 4 modes
just by changing the path to script in the url:
http://localhost/registry/x.cgi - runs the script under
mod_perl (Apache::Registry mode)
http://localhost/perlrun/x.cgi - runs the script under
mod_perl (Apache::PerlRun mode)
http://localhost/fastcgi/x.cgi - runs in FastCGI mode
http://localhost/cgi-bin/x.cgi - runs in standard cgi
mode
I have configured the 1st Apache to do this proxing through adding
the following lines in httpd.conf file in Apache's conf
directory:
RewriteEngine on
ProxyRequests on
ProxyReceiveBufferSize 65535
RewriteLogLevel 0
RewriteRule ^/(perlrun/.*)$ http://localhost:8080/$1 [proxy]
RewriteRule ^/(registry/.*)$ http://localhost:8080/$1 [proxy]
RewriteRule ^/fastcgi/(.*)$ http://localhost:7777/cgi-bin/$1 [proxy]
RewriteRule ^proxy:.* - [F]
NoCache *
This will work only if You enabled Apache's mod_rewrite and
mod_proxy modules.
Note: Run the software under mod_perl only in one of its two modes
because switching from Registry to PerlRun mode and back may produce "Undefined
Apache::Perl handler" error.
[ top ]
Q: How to extend this software
functionality?
Write additional perl modules under DBPUB1/NAVG/ directory. Use Sample.pm
file as a template. It is a kind of object with method run() which must implement
the actual work for this new extension module. For example it may produce
some html components based on the input and some data. Have stored this in
a %out hash. Also make template file(s) with similar name which will
be used for the html response. Examine the current modules in your DBPUB1/NAVG/
directory to use them as examples.
[ top ]
Q: What I have to know if I write extension modules
for this software? Tips.
To preserve the compatibility with mod_perl and FastCGI and
keep this software flexible, pay attention on the following items:
- always write the extensions as perl modules with protected
namespaces
- use strict pragma with your code
- test the script with perl warnings On. Just add -w switch
in the first line of the script. Example: #!/usr/bin/perl -w
Remove the -w switch in the production release.
- do not export scalars from your modules. Apache::PerlRun may
not remember the exported values (probably a bug)
- do not use exit() or die() functions. Under FastCGI this will
terminate the application defeating the whole idea of running the cgi script
as a persistent process. Instead use FCGI->finish to exit from the request
but not from the application.
- limit the usage of various standard Perl modules in order
to have this software run fastly as well in plain cgi mode. Use the Chatologica's
optimized replacements or try to make your own optimized modules if possible.
[ top ]
Q: How to password protect my admin
directory?
Here are instructions for Apache web server. Upload to your admin directory
in ASCII mode a file .htaccess like this one:
AuthUserFile
/usr/home/chatologica/www/cgi-bin/myscript/admin/.htpasswd
AuthGroupFile /dev/null
AuthName "Admin Panel"
AuthType Basic
<Limit GET POST>
require valid-user
</Limit>
You have similar file in some of your directories. Use the list command:
ls -la to see it. Replace the sample path above:
/usr/home/chatologica/www/cgi-bin/myscript/admin/.htpasswd
with the full path to your own admin directory. Then from shell
prompt type the command:
htpasswd -c .htpasswd administrator
This will create a password file .htpasswd and will ask you to enter
a password for username administrator. Enter the password and then
when you access http://.../admin/admin.cgi you will get a message box on
the screen asking to enter username/password pair. Enter your username
(administrator in this example) and the password and you will
access your Admin Panel.
Troubleshooting
[ top
] Q: Error message: "Forbidden. You do not have
right to access this file." or what file permissions I have to
set?
This error indicates that the web server user (usually nobody) do
not have permission to read or execute the requested file. Set world 'read'
and/or 'execute' permission to avoid this problem. Look at README.TXT to
see which are the right file permissions that you have to set in order to
run successfully this software.
[ top
] Q: Error message: "Internal Server Error" and
some suggestions how to fix similar problems.
This error indicates that the script has not produced valid output. Check
the following:
your perl is version 5
the file is uploaded in ASCII mode
it does not have syntax errors, use: perl -c the_file.pl to check
look in the web server error log to see what errors are registered there, may be there is a missing perl module
check if all files are uploaded properly in full (100%)
[ top
] Q: "core" file - what is this?
This is so called 'core dump' and happens during memory faults. The operating
system writes down the current state of memory in a file named 'core'
and kills the failed process. Happens if something in the data or code area
of the process gets corrupted, read/write access outside the process area,
very fast forks making the operating system confused, low resources.
Don't worry to delete this file from your hard drive.
[ top
] Q: MySQL connection error.
This is caused usually if you run it in mod_perl + Apache::DBI mode
which makes the database connection persistent. If there is no database requests
for a certain time the MySQL may close the connection because of inactivity
timeout. To avoid this error setup MySQL with higher idle timeout threshold.
For example 72 hours should work.
[ top
] Q: "Undefined subroutine Apache::Registry::handler"
error.
I noticed this error when switch multiple times between Apache::PerlRun and
Apache::Registry modes. The cure is to run this script only in one of these
modes. However if you get this error just restart the mod_perl enabled web
server.