pgreet.pl.(s)cgi - Penguin Greetings CGI web application
The pgreet.pl.cgi script handles all
interactions with the web user for the Penguin Greetings ecards
system. It is run as a CGI script from a web server. There is a
variant of this script pgreet.pl.scgi that runs in
a SpeedyCGI environment that is created by modifying two lines
via a sed script. Both versions are documented
here and are referred to as pgreet.pl.(s)cgi.
These scripts process template files to create the HTML content
viewed by the user. It then collects the data and stores it in
temporary state files between CGI calls. When a card has
finally been assembled, it generates two files: a MIME email
message file to be either sent immediately or scheduled for
later sending and a data file which is to be stored in Berkeley
DBM files. The pgreet.pl.(s)cgi depends on the
pgreetd daemon to handle all processing of files
from a temporary status to permanent resolution.
Penguin Greetings requires Perl 5.8.x or later to be
installed. It uses additions to the standard Perl library that
were not included before 5.8. In addition, Penguin Greetings
requires the following Perl libraries be installed:
Log::Dispatch, CGI,
CGI::Carp, MIME::Lite,
Apache::Htpasswd, Date:Pcalc,
Config::General, Embperl,
Digest::MD5, String::Checker, and
I18N::AcceptLanguage. In order to use SpeedyCGI,
the SpeedyCGI package is also required including the associated
Perl module CGI::SpeedyCGI. There are also a set
of Perl libraries written specifically to support Penguin
Greetings (Pgreet) that are included with the
Penguin Greetings distribution. All these modules are available
from CPAN (http://www.cpan.org) and as of version 0.9.0 can be
automatically installed by the Penguin Greetings installer
Install.PL.
Penguin Greetings can use HTML::Mason in
addition to or instead of Embperl as the embedded
Perl framework for template files. This is not installed by
Install.PL but can be installed using the usual
Perl module installation tools. The demonstration ecard site:
Savoring the sights of Seattle (PgSeattle) uses
HTML::Mason templates. Three of the four secondary
ecard sites that are Localized for France/French take advantage
of Locale::Maketext module that has been included
in the most recent versions of Perl 5.8.x. To run those
secondary sites this module is required, although Penguin
Greetings is itself agnostic to any particular localization
strategy.
pgreet.pl.(s)cgi simply needs to be copied into
your cgi-bin directory of your web server in order to
work. Penguin Greetings comes with an installer script:
Install.PL that will to the necessary copying and
setting of ownership and permissions. There is one line in the
program that must be localized to your server. That is the line
specifying the path to the configuration file. As of version
0.9.0 this automatically set by Install.PL, but
could require readjustment.
It is recommended that the layout of files for Penguin
Greetings be set up as noted in the Penguin Greetings
Installation Guide. You should have a directory in your web
server HTML files for templates and card images and a directory
owned by the pgreet user for data and
configuration files. You must create a pgreet user
on your server. It is this pseudo-user that will be used to
email cards unless the email as user feature is enabled.
You must set the following items in the pgreet.conf
configuration file correctly for pgreet.pl.(s)cgi
to work correctly: cgidir, cgiurl,
imagedir, imageurl,
datadir, confdir,
templatedir, tmpdir,
card_conf, and default_template.
These should be left at ``reasonable'' values by the installer
but may need tweeking. In addition the following options should
be set as you desire: login_only forces Penguin
Greetings to only allow users in the file
htpasswd_file to connect to this server and only
if they supply the correct login and password.
user_access is a file containing names of email
users on this server who have permission to send out ecards
under their own email address instead of the pgreet user name.
This poses additional security risks, so do not enable this
feature unless your server is well secured by other means.
allow_quick_views changes the way URLs are encoded
on the emails sent to recipients. This encodes the login and
password of the card in the URL so that double-clicking on the
card immediately brings up the card. This is more pleasant for
the recipient by reducing one step for her/him. However, this
reduces the screens that the recipient visits and in turn
reduces the amount of advertising that the recipient sees. This
option makes the most sense for personal sites or private ISPs
running Penguin Greetings. For more details on the
configuration options, see the Penguin Greetings installation
guide.
The data structures for the ecards to be served is stored in
a file defined by the configuration variable
card_conf. The structure of this file is dependent
on how content developers set up their web site. For more
information on how to set up content for Penguin Greetings see
the Penguin Greetings content developers' guide.
If you choose to use this script with SpeedyCGI, there are
some additional options to consider that are fully described in
the SpeedyCGI documentation. Unfortunately, not all the options
can be defined at runtime. SpeedyCGI changes the launch script
from /usr/bin/perl to /usr/bin/speedy and
uses this change to specify additional command line options. As
``shipped,'' pgreet.pl.scgi sets two of these
options: Maxbackends and group via
the following command line:
#!/usr/bin/speedy -- -M20 -gpgreet
The Maxbackends option limits the number of
persistent Perl interpreters that can be spawned by SpeedyCGI.
The group sets up a pgreet group so that SpeedyCGI
can coordinate similar Penguin Greeting processes. In addition,
There are two configuration file options that can be set to
further tune the performance of the persistent Perl
interpreter. Timeout is the number of seconds to
allow a persistent Perl interpreter to run before shutting down
due to lack of activity. MaxRuns is the number of
requests to be processed before restarting the interpreter.
These parameters are in the pgreet.conf file and are
set like any other configuration parameter.
pgreetd daemon, Pgreet Perl module
library, SpeedyCGI
Copyright (c) 2003-2005 Edouard Lagache
This software is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html
No known bugs in pgreet.pl.(s)cgi at this time
Edouard Lagache <pgreetdev@canebas.org>
1.0.0