The Penguin Greetings Administrators' Guide

Set the -M option to whatever number of maximum backends you desire. There are other options that can be set using this command line interface. The -g option creates a pgreet group of interpreters, and allows SpeedyCGI to spawn interpreters in a coordinated fashion. See the SpeedyCGI documentation if you need more flexibility than what is provided below.

Penguin Greetings provides access to the SpeedyCGI module options that can be changed at runtime. This is accomplished by the following configuration variables:

Variable	Description
Timeout	Number of seconds to allow script to remain idle before shutting it down.
MaxRuns	Number of requests to allow before restarting script. This is intended to prevent Perl memory leaks from eventually consuming sizable system resources.

The demonstration website has on its login "splash" screen some basic information on the status of SpeedyCGI if running. A sample of this information is provided below:

Penguin Greetings (version: 0.9.9-dev) has served 1679 cards on <www.canebas.org> as of Sat May 7 13:23:41 2005
Running in the following server environment: Embperl/2.0rc3 Apache/2.0.53 (Unix) mod_perl/1.999.21 Perl/v5.8.6

Also running as a SpeedyCGI interpreter.
This process (PID: 15880) has processed 409 requests since Wed Apr 27 09:46:38 2005

This is provided by three global variables that are transferred to Embperl via the $trans hash. Those variables are:

Variable	Description
SpeedyCGI	Boolean that if true indicates that pgreet.pl.scgi is indeed running as a SpeedyCGI persistent server. The two variables below are only defined this this variable is set to true.
StartTime	The UNIX time at which the persistent process started. This can be converted using the Perl localtime function or what-not.
Invocations	The number of CGI requests processed by this particular process.

See the Penguin Greeting Content Developers' Guide for more information on how to access and display these variables.

The SpeedyCGI system has some performance limitations that should be kept in mind:

If a request comes in when all existing SpeedyCGI processes are busy, SpeedyCGI will spawn another process. On a server with "bursty ecard requests," this could result in spawning Maxbackends processes even if the load demands do not justify having so many processes devoted to Penguin Greetings. It may be necessary to reduce the number of Maxbackends in order to obtain reasonable server performance.
Unfortunately, there is no way to have one process remain persistent while having any secondary processes die after a "reasonable period." For this reason, it may be better to keep the Timeout reasonably short (less than a day or even an hour) and risk having some users pay the overhead of launching a new SpeedyCGI process to avoid having several SpeedyCGI processes running idle without the user demand to justify them.
In my experience, the loading of the CGI version of Penguin Greetings has been acceptably fast when running only a single ecard site. On lightly loaded servers with few Penguin Greeting users (such as may be seen for a private server) there may be little practical benefit to using SpeedyCGI. However, servers running multiple sites will quickly benefit from the caching features of Penguin Greetings under SpeedyCGI. Servers running multiple websites using both Embperl and HTML::Mason may particularly benefit from using SpeedyCGI.

Rough benchmarks suggest that SpeedyCGI improves the performance of Penguin Greetings by a factor of 10 while reducing the load on the system by over half. Even sending more than one request a second did not cause SpeedyCGI to spawn more than 3 interpreters suggesting that SpeedyCGI versions of Penguin Greetings will be well behaved even under heavy use.

New to version 0.9.7 is caching of configuration file information for secondary as well as primary ecard sites. This greatly speeds up the loading of secondary ecard site pages, but this means that configuration files cannot be changed without updating the SpeedyCGI daemon. Version 0.9.7 of pgreet.pl.scgi uses the reload_config configuration variable to periodically reload it's configuration files anytime it is involved and the default configuration has not been reloaded in reload_config minutes. See the application daemon configuration section for more information. You can also send a SigHUP signal to the SpeedyCGI processes (again like the application daemon) to force the processes to reload. Perhaps the quickest way to do this is to use killall as follows:

killall -HUP speedy_backend

Of course some way of having proper permission to do this (like sudo) will be needed.

[Table of Contents]

Included in the Penguin Greetings distribution is a sample standby template: pgreet_standby. Using Embperl, it implements code to provide a time when Penguin Greetings will be available again for users to access the ecard system. This is done by specifying a second file which, if it exists, is included in a statement concerning when Penguin Greetings will once again be available. That file is "hard coded" in the template to /home/agent-workspace/pgreet/pgreet_down_til, so localize appropriately. This file should contain the text of the date and time when the server should be available again (something like the output of UNIX date: Fri Jun 13 16:25:02 PDT 2003).

Sending cards that users have created today:

The application daemon will process cards which have been created today every today_pause seconds. All cards waiting to be processed are processed at this time to avoid building up a backlog of cards to process. The default setting is to process cards to be sent today today every 5 seconds.

Removing state files created by users using the CGI application:

The application daemon deletes old state files in the same way it handles cards to be send today. All the state files that are older than delete_state minutes are deleted every flush_pause seconds. The default setting is to delete all state files that are more than 60 minutes old every 600 seconds (10 minutes.) This is a rapid process that should not put too much load on the system.

Sending cards scheduled to be emailed today but written earlier in time:

A time of day must be selected for sending out cards that have been scheduled by users for this day. Since the exact time isn't important, the configuration file variable: batch_send_hour only specified the hour when cards will start to be sent out. Only one card is sent per batch_pause seconds (actually daemon event loops.) This means at the default batch_pause setting of 30 seconds, that no more than 32 cards can be sent per hour. This should be adequate for all but very high usage servers. The default_send_hour is set to 2 am. International users perhaps should be warned that indeed the send hour is the local time of the server - not their recipient.

Purging database files of old cards:

Version 0.9.7 implements purging of cards that have been in the databases more than cards_remain days. A value of 0 is interpreted as never removing old cards. Since a string will evaluate as 0, all the default configuration files has the value of cards_remain set to "forever" as a mnemonic. As with sending batch cards, the hour when databases are processed can be set by the configuration variable: purge_db_hour (default 4 am.) As a precaution, the application daemon will first create a backup copy of every database file with the traditional suffix .bak. This backup file is created every day at purge_db_hour whether or not a site has specified that ecards are to be purged. This precaution provides administrators with built-in line of defense against database corruption. As the process of purging records is disk-intensive, the default pause value between processing ecard sites (purge_pause)is 120 seconds (event loop cycles.) During these two minutes, other activities such as sending cards waiting to be processed will occur.

Periodic reloading of configuration file information:

Since version 0.9.7 of Penguin Greetings caches configuration information, there is a setting to periodically reload the configuration information from disk. The default setting of reload_config is 360 minutes or 6 hours. Since this is not a particularly CPU intensive task (the CGI version of application does this on every request,) there is no way to completely turn off this reloading. However, if performance is critical, this parameter could be set to make this action very infrequent (weekly, monthly, or even less frequent.) Systems with users who will be independently maintaining their ecard sites probably should have the reload_config set to a short value so that system administrators need not manually reload configuration files for users.

[Table of Contents]

Scheduling the dates when card categories are displayed

Some card categories are seasonal. New to version 0.9.9 of Penguin Greetings is a way to set the dates when card categories are displayed in advance. As much as it would be desirable to have a system that required essentially no human intervention, it turns out that this is alas all but impossible because these dates are not fixed in some straightforward rule-based way, particularly when one seeks to provide support for international holidays. The holiday that caused me to abandon any generalized scheduling scheme was Mother's day: which is celebrated on the second Sunday in May for the United States and Canada, but is celebrated on the last Sunday of May for France (unless Pentecost occurs that Sunday ... S-S-Simple, isn't it!??

)

To avoid a hopelessly tangled ruled-based scheme for scheduling when card categories are displayed, a simple calendar-year based scheme was implemented at the Embperl layer for the default ecard site. The advantage of this is that it can be easily altered by content developers to meet their needs. A few Perl subroutines are used in this implementation that are stored in the file: shared_templates/schedule_categories.pl and are used in the template: templates/categories.tpl.html. Developers should look at those files for details on adapting this scheme for their own uses.

Administrators using this feature can schedule when card categories are displayed and will need to update this yearly. This setting can be found in the conf/cards.conf file and has the following format.

# Provide dates when categories should be displayed in a given year
<categories_schedule>
    New_Year = "12/26/2005-01/02/2006"
    St_Patrick = "03/05/2006-03/19/2006"
    Easter = "04/01/2006-04/18/2006"
    Mothers_day = "04/13/2005-05/10/2005"
    Fathers_day = "06/05/2005-06/21/2005"
    Halloween = "10/16/2005-11/03/2005"
    Thanksgiving = "11/06/2005-11/28/2005"
    Christmas = "11/19/2005-12/27/2005"
</categories_schedule>

This scheme works quite simply. If a category is enabled and the current date is in between the date interval listed in the scheduling string, the category is displayed, otherwise the category is removed from the list of categories to display. The format for date intervals is self-evident with the caveat that this is the American calendar date style (MM/DD/YYYY.) However, this can be easily changed in the Perl template code if desired. As noted in the example above, it is probably wise to schedule categories to be displayed a few days after a given holiday for those inevitable "belated greetings."

[Table of Contents]

Using Mason with Penguin Greetings

New to version 0.9.9 of Penguin Greetings is support for using HTML::Mason instead of, or in addition to, Embperl in ecard templates. Implementing sites using Mason is covered in the Penguin Greetings content developers guide. Using Mason from a system-administration point of view is straightforward but there are a few issues.

The Penguin Greetings Installer does not install HTML::Mason as part of the collection of Perl modules since it isn't necessary to get the primary site running (as it uses Embperl.) Any technique to install a Perl module can be used, but the simplest is to the Perl CPAN installer as illustrated below:

perl -MCPAN -e 'install HTML::Mason'

Penguin Greetings uses wrappers in it's own Pgreet Perl libraries and the Perl autouse pragma to load either embedded Perl in HTML solution on an only as needed basis. Administrators need not make any configuration changes should their environment use only Embperl or Mason. At the same time, a single CGI or SpeedyCGI application can handle any number of Penguin Greetings ecard sites even if some sites use Embperl and others Mason. The demonstration site on canebas.org has been operating in this way since the PgSeattle site was first developed March 2005.

Mason requires a data directory for it's own object caching feature. This directory is specified for Mason version of Penguin Greetings in the <Mason_Object> configuration setting group in the site configuration file as shown below:

    # Parameters for HTML::Mason
    <Mason_Object>
        comp_root = "/home/httpd/htdocs/pgreet/PgSeattle"
        data_dir = "/var/cache/pgreet/mason-data"
        bypass_object = "Text_email.mtpl.html"
    </Mason_Object>

The arrangement of the Mason component tree should be mostly a matter of the content developer; however, Mason requires a data directory to store cache and object information. It is advisable to create a separate cache directory for Penguin Greetings , independent of any other Mason cache directory (in the example above /var/cache/pgreet/mason-data.) Since Penguin Greetings creates it's own calling environment for the Mason interpreter, this will avoid any potential conflicts with other Mason environments running on the same server.

[Table of Contents]

Upgrading from previous versions

Overview:

Penguin Greetings 1.0.0 is identical to the release candidate 0.9.9.

Penguin Greetings 0.9.9 adds support for HTML::Mason in addition to Embperl for the templates used in the program. A new secondary ecard site: Savoring the sights of Seattle (PgSeattle) is implemented with Mason and included with this release. See the Penguin Greetings content developers guide for more details on using Mason specifically with Penguin Greetings. All other sites have received facelifts and/or expansion including the default site. A new shared templates framework has been created in Embperl to simplify the creation of ecard sites. A new localization scheme has been implemented for four of the six of the secondary ecard sites (PgXmas, PgPoppy, Pg4Seasons, and PgSeattle) using the Perl module Locale::Maketext. There is now support in the Embperl layer for automatically displaying card categories between a configurable set of dates.

Users who are upgrading previous versions of Penguin Greetings can update using their previous installer.cache without difficulty. Ecard sites created under previous versions of Penguin Greetings will run unchanged. However, some of the enhancements included in this new release may warrant site updating.

Note: The new Perl modules used in this release are not automatically installed by Install.PL as they are not needed by the primary ecard site. If you wish to use the upgraded/new secondary ecard sites that take advantage of the HTML::Mason and/or Locale::Maketext modules, you'll need to install them as described above.

Penguin Greetings 0.9.8 provides a new demonstration site ecard site (Four Seasons) that shows off the programming capabilities of Embperl (and Embperl::Object.) Only one minor change was made to the ecard engine: it is now possible to specify which card names exist in a given site and have Penguin Greetings produce a standard error (error number 40) in reply. Existing ecard sites will run without modification, but to take advantage of the new error handling, a new configuration list (array) is needed and templates to handle general errors need to now provide text for an error number 40. See the Penguin Greetings content developers guide for more details.

Penguin Greetings 0.9.7 adds support for object-oriented web sites using Embperl::Object. See the Penguin Greetings content developers' guide for more details. The application daemon pgreetd has been recoded to make operation more straightforward and purging old ecards is now supported. See the daemon configuration section for more details. In particular the old and awkward configuration variable flush_on_cycle has been replaced by a far more intuitive flush_pause variable. Users will need to update customized configuration files appropriately. Users who use Install.PL exclusively to upgrade should not be effected.

To improve performance, Penguin Greetings now transparently caches contents of primary and secondary site configuration files. This means that changes to the configuration files will not be reflected in either the application daemon or the SpeedyCGI web application. The application daemon will reload configuration files when given a SigHUP signal and will periodically reload the configuration files based on the reload_config configuration variable. The SpeedyCGI application must be restarted in order to have it reload the configuration information; however, as noted in the section on SpeedyCGI, sending a SigHUP signal will have that effect.

Penguin Greetings 0.9.6 was never released except for the Perl modules Pgreet which a minor but annoying bug which created temporary files not in the system temporary directory. The bug was fixed in 0.9.7 of the Pgreet module.

Penguin Greetings 0.9.5 adds support for localization/internationalization. See the section on localization for more details. A new CPAN module has been added to the requirements: I18N::AcceptLanguage to support localization. This module will be automatically installed by the installer if not already on your system. The installer cache from any release from 0.9.0 on will work fine with this release. No changes are necessary to any existing Penguin Greetings ecard sites, although obviously some changes would be needed to take advantage of the new localization functionality. The Install.PL cache file is compatible with the 0.9.2 and 0.9.1 file and can be used to update the application without having to reenter all your settings.

Penguin Greetings 0.9.x series has quite a few changes from the previous 0.8.x releases. If you are upgrading for anything earlier than 0.9.0, please consult the upgrade sections for the versions in between as Penguin Greetings continues to evolve rapidly.

[Table of Contents]

Troubleshooting and additional hints

Penguin Greetings has been running now for years on my personal web server and has been extremely reliable and trouble-free. However just in case, here are a few issues and trouble-shooting hints.

Unless you are really bold (or overworked) leave the --verbose command line option on pgreetd. This turns on a great deal of additional information about what pgreetd is doing.
Penguin Greetings is very simple-minded about how it processes temporary state files. It uses the filename prefix to tell it what sort of file it is attempting to process. The prefixes can be changed but perhaps this is not wise once the program is running. If you have a system failure and have trouble restarting, you can diagnose which files have been left unprocessed by the filename prefix.
It is possible to "jump-start" pgreetd to process all cards immediately by restarting the daemon. When debugging, run the CGI script before starting the daemon. The CGI script doesn't need the daemon to work and that allows you to divide the possible sources of error.
Under development is a multi-use tool for managing the Berkeley DBM files associated with Penguin Greetings PgreetDButil. It can be found in the util directory of the source distribution and installed if desired in any bin directory. It can be used to manually purge a ecard site of old cards for those who prefer to do this on a "as needed" basis. It also has an option to create a record-by-record copy of databases which will compact and reorganize the structure of the DBM files. For more information on using the PgreetDButil tool see it's man page included in the Penguin Greetings documentation.
There is a quick script BerkDB2text.pl which will open a Berkeley DBM file and dump its contents to standard output that you can use to look if your databases are being corrupted. There is the converse script text2BerkDB.pl that can be used to assemble a file that has been dumped to text. It is possible (as a desperate last-resort) to disassemble, edit, and reassemble a database file this way.

Here are a few helpful hints:

Create a mail alias or forward the email sent to the user pgreet so that email that bounces back to the user agent doesn't pile up on your server in an unread email box.
Create a server script alias to make it easier for your users to find pgreet.pl.cgi. On Apache I use the following configuration file line: ScriptAlias /pgreet.cgi "/home/httpd/cgi-bin/pgreet.pl.cgi"
Starting with version 0.8.3 of Penguin Greetings, there is a card category called: Recently added cards. This is intended to allow administrators and prospective users to see which are the latest cards in the current release. If you do not want that category (or any category or card shown for that matter,) you can simply comment out the category/card in the file cards.conf file. See the Penguin Greetings Content Developers' Guide for more details on managing the cards.conf file.

[Table of Contents]

Parameter	Description
Host	Hostname of the server to use. Penguin Greetings ships with this set to localhost, although the installer will prompt you for an alternative.
Hello	SMTP requires that you identify yourself. This option specifies a string to pass as your mail domain. If not given a guess will be taken.
LocalAddr	The local address to use to connect to server (optional)
LocalPort	The local port to use (default is 25)
SMTP_Timeout	The period to wait before assuming a timeout (default 120 seconds)