The Penguin Greetings Administrators' Guide

Edouard Lagache

Copyright © 2003-2005 (Penguin Greetings 1.0.0 edition)

A introduction to configuring and operating the Penguin Greetings web-based ecards system.

Table of Contents:

  1. Overview of Penguin Greetings
  2. Penguin Greetings Legalese
  3. Configuring Penguin Greetings
  4. Using PgreetConfTest to check configuration files
  5. Creating Databases and starting Penguin Greetings
  6. Configuring to use a SMTP server
  7. Using Penguin Greetings with SpeedyCGI.
  8. Setting up access control
  9. Penguin Greetings Standby Mode
  10. Managing secondary ecard sites
  11. Localization/Internationalization support
  12. Configuration of the application daemon
  13. Scheduling the dates when card categories are displayed
  14. Using Mason with Penguin Greetings
  15. Upgrading from previous versions
  16. Troubleshooting

Overview of Penguin Greetings

Penguin Greetings is a Perl CGI based system for implementing web-based ecards.  It is also a complete "drop in" ecards solution for any web site which includes 240+ ecards for many occasions that are similar in style and taste to Apple's iCards content.   Penguin Greetings uses HTML templates that contain embedded Perl expressions to represent the cards and the web-pages that users need to fill out in order to send an ecard.  Penguin Greetings is able to send MIME multipart HTML messages, so users with rich-text supporting email clients can read their cards directly.  Penguin Greetings also supports ecard scheduling so that cards can be sent on a special day such as someone's birthday.

In order to accomplish this, Penguin Greetings uses two Perl programs as shown on the diagram below:

Penguin Greetings schematic
Division of labor in Penguin Greetings

The Perl CGI script: runs under the control of the web server and handles all the interaction with the user via a normal web interface.  However, does not do any permanent operations.  All of its work is left as temporary files which are processed by the pgreetd daemon.  The daemon is essential in order to email cards at later date.  The pgreetd daemon handles the housekeeping chores of mailing the cards either immediately or on the day requested and maintaining the Berkeley DBM databases while allowing the CGI script only read access to that data for security reasons.  The daemon avoid issues related to changing user id and associated pitfalls and provides a security screen that can be easily configurable.  The daemon is also easily configured to change the load imposed on the server. 

The Perl CGI script can now be run as a persistent server by using the SpeedyCGI application.  This avoids the overhead of launching Perl with each new request and allows for greater control of how Penguin Greetings is executed on the server.

Penguin Greetings Legalese

Penguin Greetings is copyright © Edouard Lagache, 2003-2005. Penguin Greetings is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit:

The artistic content included with this software is also copyright © Edouard Lagache, 2003-2005. It is released under the Design Science License. For more information, see the DSL.txt file included with the software or visit:

Powered by Penguin Greetings web badge

If you use Penguin Greetings in your own web cards application.  Please give credit were credit is due by displaying the following web badge or something equivalent on your web site:

Powered by Penguin Greetings

There are now quite a few different badges included in Penguin Greetings with the various secondary ecard sites, so take a look if you want something different.  Better still, if you make a nicer web badge, please share it with me so that I can spread the wealth! :-)

[Table of Contents]

Configuring Penguin Greetings

The installer provided with 0.9.0 of Penguin Greetings now localizes the configuration files enough so that (hopefully :-)) the application will start without further intervention.  However, Penguin Greetings is a complex program with many options that can be configured.  Fortunately, the configuration file is in a relatively standard format (similar to the Apache web server) and has extensive comments.  A copy of it is included below for reference. 

# File: pgreet.conf
#                 Main configuration file for
#                ** PENGUIN GREETINGS (pgreet) **
# A Perl CGI-based web card application for LINUX and probably any
# other UNIX system supporting standard Perl extensions.
#     Edouard Lagache,, April 2005
#     For Penguin Greetings 0.9.9 release
# The pgreet system uses the Perl Config::General module for
# reading in configuration file information.  The file format
# is the same as for the Apache web server.  The general
# configuration module contains information for both the
# CGI script and the system daemon.  These are kept in
# separate categories for simplicity of management.
# $Id: pgreet.conf,v 1.31 2004/04/10 20:29:32 elagache Exp $

###  Directory and URL defaults

    # Server hostname (for virtual servers and whatnot)
    hostname = ""

    # Path to server's cgi-bin directory
    cgidir = "/home/httpd/cgi-bin"
    # URL to server's cgi-bin directory
    cgiurl = ""

    # Path to image files.
    imagedir = "/home/httpd/htdocs/pgreet/images"

    # URL to images on server
    imageurl = ""

    # Path to directory where dbm databases are stored
    datadir = "/home/agent-workspace/pgreet/data"

    # Path to configuration files
    confdir = "/home/agent-workspace/pgreet/conf"

    # Path to HTML templates
    templatedir = "/home/httpd/htdocs/pgreet/templates"

    # Path to temporary files (usually: /tmp directory)
    tmpdir = "/tmp"

    # Directory to cards waiting to be sent at a later date
    scheduled_mail_queue = "/home/agent-workspace/pgreet/card_queue"

###  Filenames

    # name of file containing htpasswd styled passwords (if needed)
    htpasswd_file = ".htpasswd"

    # Name of dbm file with used login names for looking up cards.
    card_name_db = "NameList.db"

    # Name of dbm file with login/password hashes.
    name_passwd_db = "NamePass.db"

    # Name of dbm file with actual card data.
    card_data_db = "CardData.db"

    # Prefix for files containing CGI state.
    state_file_prefix = "pgreet-state"

    # Prefix for swap files for database data.
    data_file_prefix = "pgreet-data"

    # User email access file (be careful with this file!)
    user_access = "user_access.txt"

    # Pgreetd log filename
    pgreet_log_file = "/var/log/pgreet.log"

    # HTML template suffix
    template_suffix = "tpl.html"

    # Default template for servers without login restrictions
    default_template = "default"

    # Default template for servers with login restrictions
    default_login = "default_login"

    # Template to be used to report miscellaneous errors
    default_error = "general_error"

    # Configuration file with card information
    cards_conf = "cards.conf"

    # Path to standby mode flag filename
    standby_mode =  "/home/agent-workspace/pgreet/pgreet_on_standby"

    # Template to display in case Penguin Greetings is in standby mode
    standby_template = "pgreet_standby"

    # Default site parameters for Object-Oriented version of Embperl
        object_addpath = "/home/httpd/htdocs/pgreet"
        object_base = "pgreet_template.epl"
        appname = "PgDefault"
        bypass_object = "Text_email.tpl.html"

### Misc CGI script settings.
    # Is Penguin Greetings available only to login/password users?
#    login_only = 1

    # Allow encoding of card number and password in URL.
    # (turn off - if you want users to come to your central page)
    allow_quick_views = 1

### User and group to be used to send email (IMPORTANT!)
    # User ID for user to send email if not overridden.
    pgreet_uid = PgreetUID

    # Group ID for files to be sent later for email.
    pgreet_gid = PgreetGID

    # Prevent users from inserting any HTML tags in their messages
    no_html_tags = 1

### SpeedyCGI Parameters
    # Script Timeout
    Timeout = 604800

    # Max Runs - number of times script can be used before reloading.
    MaxRuns = 10000

### SMTP server parameters
        # SMTP Server
        Host = "localhost"

        # SMTP identification string
        Hello = ""

        # SMTP LocalAddr and LocalPort
        LocalAddr = ""
        LocalPort = ""

        # SMTP Timeout
        SMTP_Timeout = 120

### Days ecards are kept on server.
    cards_remain = "forever"

### Additional user ecard websites
#    <User_Pgreets>
        # Edouard Lagache's personal card sites
#        elagache = ~/.pgreet/conf/pgreet.conf

        # The Penguin Greeting - Camel Collection secondary site
#        PgCamel = /home/agent-workspace/PgCamel/conf/PgCamel.conf

        # The Penguin Greeting - Holy Card secondary site (en-us)
#        PgSaint!en-us = /home/agent-workspace/PgSaint/en-us/conf/PgSaint.conf
        # The Penguin Greeting - Holy Card secondary site (fr-fr)
#        PgSaint!fr-fr = /home/agent-workspace/PgSaint/fr-fr/conf/PgSaint.conf

        # The Penguin Greetings - Christmas secondary ecard site (en-us)
#        PgXmas!en-us = /home/agent-workspace/PgXmas/en-us/conf/PgXmas.conf
        # The Penguin Greetings - Christmas secondary ecard site (fr-fr)
#        PgXmas!fr-fr = /home/agent-workspace/PgXmas/fr-fr/conf/PgXmas.conf

        # The Penguin Greetings - CA Poppy secondary ecard site (en-us)
#        PgPoppy!en-us = /home/agent-workspace/PgPoppy/en-us/conf/PgPoppy.conf
        # The Penguin Greetings - CA Poppy secondary ecard site (fr-fr)
#        PgPoppy!fr-fr = /home/agent-workspace/PgPoppy/fr-fr/conf/PgPoppy.conf

        # The Penguin Greetings - 4 seasons secondary ecard site (en-us)
#        Pg4Seasons!en-us = /home/agent-workspace/Pg4Seasons/en-us/conf/Pg4Seasons.conf
        # The Penguin Greetings - 4 seasons secondary ecard site (fr-fr)
#        Pg4Seasons!fr-fr = /home/agent-workspace/Pg4Seasons/fr-fr/conf/Pg4Seasons.conf

        # The Penguin Greetings - Sights of Seattle ecard site (en-us)
#        PgSeattle!en-us = /home/agent-workspace/PgSeattle/en-us/conf/PgSeattle.conf
        # The Penguin Greetings - Sights of Seattle ecard site (fr-fr)
#        PgSeattle!fr-fr = /home/agent-workspace/PgSeattle/fr-fr/conf/PgSeattle.conf
#    </User_Pgreets>

### Localization for websites
    <Localize PgXmas>
        default = PgXmas!en-us
        en-us = PgXmas!en-us
        fr-fr = PgXmas!fr-fr

    <Localize PgSaint>
        default = PgSaint!en-us
        en-us = PgSaint!en-us
        fr-fr = PgSaint!fr-fr

    <Localize PgPoppy>
        default = PgPoppy!en-us
        en-us = PgPoppy!en-us
        fr-fr = PgPoppy!fr-fr

    <Localize Pg4Seasons>
        default = Pg4Seasons!en-us
        en-us = Pg4Seasons!en-us
        fr-fr = Pg4Seasons!fr-fr

    <Localize PgSeattle>
        default = PgSeattle!en-us
        en-us = PgSeattle!en-us
#        fr-fr = PgSeattle!fr-fr

########### Parameters below here unlikely to need changing. ############

### Daemon performance tuning parameters.
    # Period to pause between sending cards created today (in seconds)
    today_pause = 5

    # Period to pause between sending earlier scheduled cards (in seconds)
    batch_pause = 30

    # Hour during the day to send queued cards (24 hour format.)
    batch_send_hour = 2

    # Number of minutes to wait before deleting a CGI state file.
    delete_state = 60

    # Number of seconds between deleting old state files
    # 600 seconds = 10 minutes.
    flush_pause = 600

    # Hour during the day to purge old cards from databases
    purge_db_hour = 4

    # Period to pause between purging old cards in databases (in seconds)
    purge_pause = 120

    # Period in minutes between reloading configuration files
    # 360 minutes = 6 hours.
    reload_config = 360

### Misc daemon parameters

    # Path and format of PID file for Initialization of Daemon
    PID_path = "/var/run"
    PID_file = ""

A number of the configuration parameters can be of interest.  On the CGI script side 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.  See the section below on access control for more information on setting up htpasswd file and user_access.  New to version 0.8.8 is direct access to the SMTP server of your choice see the section below for SMTP configuration options.  The option 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 potential advertising that the recipient sees. This option makes the most sense for personal sites or private ISPs running Penguin Greetings.  The system daemon: pgreetd also has some special options.  For example, pgreetd has extensive logging facilities. The command line option pgreet_log_file sets the location of the log file.  pgreetd is set up for operation on LINUX systems. It may be necessary to adjust the location of PID files and related parameters on other UNIX systems. pgreetd also has a number of parameters to adjust when files are processed. These can be adjusted to reduce the wait before cards are processed.  For more information on the SpeedyCGI configuration parameters, see the section below on running Penguin Greetings as a SpeedyCGI server.

One configuration variable absolutely has to be correct:  default_error.  This is the name of the template that is used to report an error.  If this template is missing and there is any error, then there is no way for errors to be reported.  Penguin Greetings will go into an infinite recursion trying to find some way to report each error which in turn generates another error.  Since there is no obvious way to report an error when the mechanism to report an error is itself broken, it is hereby declared that an infinite recursion is the mechanism by which Penguin Greetings will seek to get the attention of the system administrator and therefore (since it is now documented) it is a feature - not a bug!

  [Table of Contents]

Using PgreetConfTest to check configuration files

New to version 0.9.1 is a systematic sanity check of Penguin Greetings configuration files (both primary and secondary.)  These checks are performed by the Penguin Greetings daemon pgreetd, to avoid additional overhead for the CGI application.  Any errors through are reported in a very terse way and will at the very least cause cards not to be processed and at worst will cause the daemon to terminate.

To make sure that your configuration files meet the requirements of Penguin Greetings, use the PgreetConfTest utility.  This command-line tool runs exactly the same tests as the daemon, but provides much more informative diagnostics as a result.  The syntax of PgreetConfTest is fairly obvious:

PgreetConfTest [-v] Configuration_file.conf

PgreetConfTest makes no interpolation for where the filename should be located, so you must provide a UNIX path to the file if necessary.  The -v option provides an output of the configuration variables as a Perl data structure via the Perl module Data::Dumper.

The output from PgreetConfTest detailed and precise as illustrated by the sample output below: [94]% PgreetConfTest utils/test_pgreet.conf
Penguin Greeting conf file testing tool version: 0.9.1

Error in configuration file - details below

- SMTP_Timeout
    Numerical value is less than allowed for this parameter
- pgreet_gid
    Numerical value is less than allowed for this parameter
- cgidir
    Directory does not exist on this system
- pgreet_uid
    Numerical value is less than allowed for this parameter

For more information on PgreetConfTest see its man page.
  [Table of Contents]

Creating Databases and starting Penguin Greetings

New to version 0.8.8 is a separate utility to initialize the databases used by Penguin Greetings.  Before actually actually using the primary or any secondary ecard sites, you must create the databases with the following command:

sudo PgreetDBinit path_to_your_pgreet_data_directory

The PgreetDBinit utility must be run as root (via sudo or whatnot) so that it can set the file permissions correctly.  Note the path above must be complete (including the final directory data in the path.)  There are some options of PgreetDBinit that can be used to customize your installation.  See the PgreetDBinit man page for more details.

  [Table of Contents]

Configuring to use a SMTP server

New to version 0.8.8 is direct use of the SMTP server of your choice by Penguin Greetings.  This allows a commercial site to route all email through one mail server or hobbyists to run Penguin Greetings on a web server without the additional hassles of providing a local MTA. 

The Penguin Greetings SMTP client services is provided via the Net::SMTP Perl module and all of the configuration parameters come from there.  All  SMTP configuration information is  stored in a  group of  pgreet.conf parameters known as SMTP_server.  The available parameters are as follows:

Hostname of the server to use.  Penguin Greetings ships with this set to localhost, although the installer will prompt you for an alternative.
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.
The local address to use to connect to server (optional)
The local port to use (default is 25)
The period to wait before assuming a timeout (default 120 seconds)

The defaults should be reasonable for most servers.

  [Table of Contents]

Setting up access control

Penguin Greetings supports access restriction as can be seen on the primary demonstration ecard site.   While Penguin Greetings is no longer "shipped" in this way to simply initial installation, it is highly recommended that you enable access restriction unless you intend to run a public ecard server.   In order to permit users to connect you need to create a htpasswd formatted file that is specified by the configuration file variable:  htpasswd_file, and is located in your configuration file directory.  Penguin Greetings is shipped assuming the file is named .htpasswd.  You can create this file with the htpasswd utility that comes with the Apache web server.  You can get documentation on htpasswd using the man page that comes with the installation or you can look at the documentation online.

Briefly, the procedure to create an htpasswd file is as follows: assuming you are in your pgreet user agent conf directory, you can create the a new .htpasswd file with the following command:

htpasswd -c .htpasswd

This must be done as super-user or root so use sudo or equivalent.  To add users the command is:

htpasswd .htpasswd newuser

Once more, this must be done as root.   You'll be asked to assign a password to this user in the same routine as the standard UNIX passwd command.  Repeat this procedure for all the users you wish to give access to Penguin Greetings on your machine.

If you are running Penguin Greetings on a secure server and intend it for personal use of your email account users, there is one more convenience that you may wish to enable.  As noted above, the configuration variable user_access can be set to point to a simple plain-text file of login names on your server which are allowed to send penguin greetings under their own email address (login) names instead of the generic pgreet agent email.   Penguin Greetings is shipped expecting to find the file user_access.txt in your conf directory as well.  The file format is simply a list of login names one name per line.  Warning, this is a dangerous option - Use at your own risk!

  [Table of Contents]

Using Penguin Greetings with SpeedyCGI

New to version 0.8.2 is support for the SpeedyCGI utility for keeping a persistent Perl interpreter running Penguin Greetings.  To use SpeedyCGI you must download and install the SpeedyCGI utilities that are available at:  The new 0.9.0 installer will install the Perl components of SpeedyCGI, but may not provide a complete installation of other components (depending on your setup.)  SpeedyCGI will work with any web server but includes an Apache module which will further improve performance with that server.

Once you have installed SpeedyCGI you'll need to configure it for use Penguin Greetings.  If you are using Apache, you'll need a set of configuration settings analogous to the following:

#### SpeedyCGI Configuration ####

LoadModule speedycgi_module modules/
# Limit backends to 10
SpeedyMaxBackends 10
# Use the scgi suffix for Speedy CGI
AddHandler speedycgi-script .scgi

After loading the module, the SpeedyMaxBackends limits the number of SpeedyCGI backends that can be running at the same time to 10.  This is important to set to avoid potential denial of service attacks.  The next line requires Apache process all files with the .scgi suffix with SpeedyCGI.  The .scgi suffix is arbitrary.

Unfortunately, there is no other way to set the SpeedyCGI MaxBackends except on the command line.  As a precaution, has this capped at 20.  Should you need to change this value for whatever reason, edit the file, and change the top line which looks like:

#!/usr/bin/speedy -- -M20 -gpgreet

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:

Number of seconds to allow script to remain idle before shutting it down. 
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 <> 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:

Boolean that if true indicates that is indeed running as a SpeedyCGI persistent server.  The two variables below are only defined this this variable is set to true.
The UNIX time at which the persistent process started.  This can be converted using the Perl localtime function or what-not.
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:
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 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]

Penguin Greetings Standby Mode

There may be times when you wish to "turn off" Penguin Greetings (for example for database maintenance,) but do not wish to have users get a error message when trying to access Penguin Greetings.  New to version 0.8.3 is support for a "standby mode."  In this mode, Penguin Greetings will display a special template indicating that the program is not available.  If the templates shipped with Penguin Greetings are used (or similar templates are implemented,) it is possible to advise users when Penguin Greetings will be again available.

The Penguin Greetings Standby mode is implemented through a temporary file whose path is specified by the configuration file variable: standby_mode.  If that file exists, then Penguin Greetings will load the template by the configuration file variable: standby_template.  As is true elsewhere in Penguin Greetings, the template pointed to standby_template by may contain any valid HTML and/or Embperl.  See the Penguin Greetings content developers' guide for more details on how such templates may be constructed.

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).

To put Penguin Greetings into standby mode, simply touch the file that has the path pointed to by standby_mode.  To add a time when Penguin Greetings will be available, simply create a file at the path pointed to by the template with the date and time when the server will be available again.  If you don't provide such a file, the pgreet_standby template will provide a message that doesn't specify any expected return to availability time.  To take Penguin Greetings out of Standby mode, simply delete the file(s) and Penguin Greetings will automatically resume normal operation on the next request.

  [Table of Contents]

Managing secondary ecard sites.

New to version 0.8.8 is support for secondary ecard sites running off of the same CGI-application and daemon.  This allows ISPs to provide ecard services to multiple customers or individual users without the overhead of multiple CGI-applications or daemons.  Secondary sites are much like the primary sites and require a similar arrangement of configuration, database, and HTML directories.  Each site in the present arrangement is stored in its own set of DBM files stored in a separate directory for each user.  This is likely to change when relational database support is provided for Penguin Greetings, but the present arrangement has the advantage of keeping the ecard resources completely independent of SQL database resources.  For commercial sites this may always be the best arrangement particularly if ecards are added to a customer site as a "perk" and the client does not want the hassle or complication of having their ecards interacting with their other relational database resources.

There are examples of six secondary Penguin Greetings ecard sites included in the source distribution:
  1. PgCamel - The Penguin Greetings Camel Collection
  2. PgSaint - The Penguin Greetings Holy cards Collection
  3. PgXmas - The Penguin Greetings Christmas card Collection
  4. PgPoppy - The Penguin Greetings California Poppy Collection
  5. Pg4Seasons - The Penguin Greetings Four Seasons Collection.
  6. PgSeattle - Savoring the sights of Seattle Collection (Implemented using HTML::Mason)
All these sites but the first include a French translation.  Four of these sites (PgXmas, PgPoppy, Pg4Seasons, and PgSeattle) require the installation of Locale::Maketext (see below.) You can view these sites in action by going to the Penguin Greeting demonstration page.  The configuration files, templates and images (or symbolic links to the images) are located in the card_site directory of the source code distribution.  There is a simpleminded bourne shell script that will copy the files to directories for a sample installation.  The installation syntax is:

sudo ./ SiteName Owner Group .../Path_to_data_config_directory .../Path_to_web_data_directory

There is nothing intelligent about this script.  It does not in particular edit the configuration files to point to your own directories in your file-system.  This must be done by hand.  Also, you cannot use it to replace the primary ecard site with one of the secondary sites.  Sorry, if you would like to run one of the secondary sites as your primary site, you'll need to reconcile the configuration files from the primary and secondary sites "by hand."  The script needs to be run as root to set the file permissions. 

If you wish to install all the components of of any of the  object-oriented secondary ecard site (any site beside PgCamel) you can use the installer that comes with version 0.9.8 of Penguin Greetings.  This installer is like it's simpler ancestor and uses for installing the two languages included with each object-oriented site.  Like than ancestor, it doesn't update the configuration files, it simply copies files to the right location on your disk in a simple-minded way.  The arguments are essentially the same as for

sudo ./ SiteName Owner Group .../Path_to_data_config_directory .../Path_to_web_data_directory

Note that because this script installs the two languages automatically, the paths on your server won't quite be the same.  This is illustrated by a sample call on the development <> server shown below.  The script will create the  required Pg4Seasons directories and associated en-us and fr-fr subdirectories, unlike the example creation of the PgSaint directory above with

sudo ./ Pg4Seasons pg4seasons pgreet \
                           /home/agent-workspace /home/httpd/htdocs/pgreet

Note that all the object-oriented secondary ecard sites (but PgSaint) use Locale::Maketext to handle localization  This is not installed by the Penguin Greetings Installer (Install.PL)   The Locale::Maketext module is now included in recent versions of Perl 5.8 (such as 5.8.6) or you can install the module for an earlier version of Perl using something like the Perl CPAN installer as illustrated below:

perl -MCPAN -e 'install Locale::Maketext'

Secondary ecard sites are accessed by an additional CGI state variable site.  Penguin Greetings automatically retains the choice of site once one is selected.  So to enter into an example site one would only need to specify the site when first involving Penguin Greetings as in:

The secondary ecard scheme depends on a primary Penguin Greetings configuration.  This is necessary because the CGI-application and daemon use a common set of directories for the exchange of all data for all sites managed by Penguin Greetings.  In the primary configuration file (see above) secondary sites are configured with the User_Pgreets option:

### Additional user ecard websites
        # Edouard Lagache's personal card sites
        elagache = "~/.pgreet/conf/pgreet.conf
        # The Penguin Greeting - Camel Collection secondary site
        PgCamel = "/home/agent-workspace/PgCamel/conf/PgCamel.conf"
        # The Penguin Greeting - Holy Card secondary site
        PgSaint = "/home/agent-workspace/PgSaint/conf/PgSaint.conf"

Penguin Greetings system for defining secondary sites is direct.  It expects to find a configuration file exactly in the same format as the primary type associated with a given name.  When it receives a request with the following additional CGI variable site set to some name, it looks to see if the site specified exists, if so, it then looks up the site configuration information in that configuration file and proceeds to function from there.

Penguin Greetings makes one allowance for the sake of UNIX user integrity, if the path to the configuration file includes a tilde '~' and the site name is a known user on the system, then the path to the Penguin Greetings is evaluated assuming the tilde refers to that user's home directory.  This allows administrators to allow conventional UNIX shell users to have their own secondary ecard sites.

A secondary ecard site is much like a primary one.  See the six example ecard sites included in the distribution and the Penguin Greetings Content Developers Guide for more details.  A secondary configuration file for the PgCamel secondary site is provided below: 

# File: PgCamel.conf
#                 Main configuration file for
#        ** PENGUIN GREETINGS (pgreet) Camel Collection**
# This is a sample configuration file for a secondary pgreet ecard
# web site to be used with Penguin Greetings.  Penguin Greeting is
# a Perl CGI-based web card application for LINUX and probably any
# other UNIX system supporting standard Perl extensions.
#     Edouard Lagache,, June 2003
#     For Penguin Greetings 0.8.8 release
# The pgreet system uses the Perl Config::General module for
# reading in configuration file information.  The file format
# is the same as for the Apache web server.  The general
# configuration module contains information for both the
# CGI script and the system daemon.  These are kept in
# separate categories for simplicity of management.
# $Id: pgreet_install_guide.html,v 1.19 2003/07/17 21:25:33 elagache Exp $

###  Directory and URL defaults

    # Path to image files.
    imagedir = "/home/httpd/htdocs/pgreet/PgCamel/images"

    # URL to images on server
    imageurl = ""

    # Path to directory where dbm databases are stored
    datadir = "/home/agent-workspace/PgCamel/data"

    # Path to configuration files
    confdir = "/home/agent-workspace/PgCamel/conf"

    # Path to HTML templates
    templatedir = "/home/httpd/htdocs/pgreet/PgCamel/templates"

### Misc CGI script settings.
    # Is Penguin Greetings available only to login/password users?
    login_only = 0

    # Allow encoding of card number and password in URL.
    # (turn off - if you want users to come to your central page)
    allow_quick_views = 1

    # Prevent users from inserting any HTML tags in their messages
    no_html_tags = 1

However, not all the parameters that can be specified in the primary site configuration can be included in secondary site configuration files.  In particular, you may not set the values of the following configuration variables: PID_file, PID_path, batch_pause, tmpdir, today_pause, data_file_prefix, state_file_prefix, delete_state, scheduled_email_queue, pgreet_uid, pgreet_gid, SMTP_server, user_access, User_Pgreets, flush_pause, purge_db_hour, purge_pause or  reload_config.  These parameters effect the server-wide operation of Penguin Greetings and can only be set once.

The same administration scheme used for the primary Penguin Greetings ecard site apply nicely to any secondary site.  While creating a separate UNIX user for each site isn't necessary, it may be convenient.  The same issues about how to divide up the configuration files, data files, and HTML templates apply. Once a directory setup has been completed, you may initialize the databases for the secondary ecard site using the PgreetDBinit utility described above.   See the Penguin Greetings Content Developers Guide for more details in setting up secondary ecard sites.

Penguin Greetings 0.9.5 allows for secondary ecard sites to be assigned to particular language/nation localization.  Each of these sites are independent from each other and will have their own configuration and database files.  One possible scheme for managing the files is to keep each set of files in a subdirectory named by the language/nation suffix.  So in the PgXmas site,  The configuration and data for the English/U.S. site is stored under a directory like: /home/agent-workspace/PgXmas/en-us and the French/France site is stored under: /home/agent-workspace/PgXmas/fr-fr.  In the same way, the images and templates for the U.S. site are stored under: /home/httpd/htdocs/pgreet/PgXmas/en-us  and the French site is stored under: /home/httpd/htdocs/pgreet/PgXmas/fr-fr.  See the example sites under the card_sites directory of the source code distribution for more details.

  [Table of Contents]

Localization/Internationalization support

New to version 0.9.5 of Penguin Greetings is support for multiple languages and automatic selection of a localized site based on the HTTP_ACCEPT_LANGUAGE browser environmental variable.  The present implementation is for secondary ecard sites only and is a straightforward extension of that concept.  Each language is implemented a distinct secondary ecard site.  The primary configuration file should continue contain an entry for every site needed to support the languages desired as shown in the example below:

### Additional user ecard websites
        # Edouard Lagache's personal card sites
#        elagache = ~/.pgreet/conf/pgreet.conf
        # The Penguin Greeting - Camel Collection secondary site
        PgCamel = /home/agent-workspace/PgCamel/conf/PgCamel.conf
        # The Penguin Greeting - Holy Card secondary site (en-us)
        PgSaint!en-us = /home/agent-workspace/PgSaint/en-us/conf/PgSaint.conf
        # The Penguin Greeting - Holy Card secondary site (fr-fr)
        PgSaint!fr-fr = /home/agent-workspace/PgSaint/fr-fr/conf/PgSaint.conf
        # The Penguin Greetings - Christmas secondary ecard site (en-us)
        PgXmas!en-us = /home/agent-workspace/PgXmas/en-us/conf/PgXmas.conf
        # The Penguin Greetings - Christmas secondary ecard site (fr-fr)
        PgXmas!fr-fr = /home/agent-workspace/PgXmas/fr-fr/conf/PgXmas.conf

The name convention for localized secondary ecard sites is a unique identifier (for example above PgXmas or PgSaint,) followed by the language and nation code, separated by an exclamation point.  The information needed to select a site given a language and country is provided in the configuration file via the new Localize parameter as shown below:

### Localization for websites
    <Localize PgXmas>
        default = PgXmas!en-us
        en-us = PgXmas!en-us
        fr-fr = PgXmas!fr-fr

    <Localize PgSaint>
        default = PgSaint!en-us
        en-us = PgSaint!en-us
        fr-fr = PgSaint!fr-fr

The Localize configuration parameter allows you to associate secondary sites with language/nation combinations.  A default is provided in case a user attempts to connect to the site who's preferred languages aren't included your available translations.  Always provide a default entry to insure that a user isn't prevented with a "non-existent ecard site error."

Penguin Greetings uses something of a "hot potato" strategy to eliminate localization issues.  The language independent way to choose a secondary ecard site is to use the same site CGI parameter used to choose a secondary site, but to only provide the language independent prefix.  So for example to select the PgSaint secondary site, the right URL for would be:

Once Penguin Greetings has determined that the user matches say the French language and nation of France, every succeeding call to the program to create the card is made with the site: PgSaint!fr-fr.  This is done to prevent any risk of the language being changed in mid ecard creation and to insure that person viewing the card sees the card in the language the user created it in.  Because people who deal with computers and languages frequently are multi-lingual, it is highly recommended that you provide explicit links to the various languages that your site supports using the full name of the sites (including the language information, e.g.: PgSaint!en-us, PgSaint!fr-fr)  This allows an American user to explicitly choose the French site in order to send a card in French, overriding their browser settings for the purposes of sending the card.  See the PgSaint, PgXmas PgPoppy, Pg4Seasons, and PgSeattle secondary ecard sites for examples on how to implement multi-lingual ecard sites using Penguin Greetings.

Installing these multi-lingual sites is slightly different than installing a standard secondary ecard site.  However the same installer can be used.  Assuming you use the convention of keeping language specific information in subdirectories by their language/nation tags the following secondary ecard site installer command will install these language sites into the correct directories:

sudo ./ PgSaint-fr-fr PgSaint pgreet /home/agent-workspace/PgSaint/fr-fr  \

Adjust this command appropriately to your local file structure.

Note that the actual process for localizing files is left up to you the content developer.  New to version-0.9.9 of Penguin Greetings are examples of localization using the Perl standard library module Locale::Maketext.  See the Penguin Greetings Content Developers Guide for more information in implementing multilingual ecard sites.

[Table of Contents]

Configuration of the application daemon

New to version 0.9.7 is a more rational scheme for scheduling events within the application daemon.  There is a one second event loop within the daemon, so events can be set to occur on human time scales - thereby eliminating the old flush_on_cycle configuration variable.

The daemon performs five activities whose actions can be scheduled and/or tuned:

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.

The application daemon now will process the SigHUP signal correctly and reload configuration files without restarting the daemon completely.  This can be done using the usual kill command (and relatives) and can also be done using the System-V initialization script provided in the distribution provided that your LINUX systems provides the requisite bash init functions.  The command in that case is (using sudo here:)

sudo /etc/rc.d/init.d/pgreetd reload
Reloading (SigHUP) Penguin Greetings daemon (pgreetd):     [  OK  ]

While commercial sites will most likely want to enable periodic purging of old ecards, non-commercial users may prefer to having cards not automatically purged.  For such users the PgreetDButil tool which can be found in the utils directory may be used to manually remove old cards whenever the administrator desires.  This tool is still under development and is not installed in any bin directory by default; however, it uses exactly the same Perl object library to purge old cards as the application daemon (Pgreet::DaemonUtils) and therefore is perfectly trustworthy.  For more information on using the PgreetDButil tool see it's man page included in the Penguin Greetings documentation.

[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/ 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
    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"

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 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
        comp_root = "/home/httpd/htdocs/pgreet/PgSeattle"
        data_dir = "/var/cache/pgreet/mason-data"
        bypass_object = "Text_email.mtpl.html"

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


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.

Here are a few helpful hints:
  [Table of Contents]