Owner's Manual: Administration

1. Cardshop Stats, Reports and Extracted e-mail Addresses
2. Finding Cards with Number
3. Finding Cards without Number
4. ASAP/QUEUE mail delivery
5. Storing large amounts of card datafiles
6. Cron job parameters

1. Cardshop Stats

   Cardshop stats are accessible via web browser from http://yourdomain/$ROOT_DIR/stats/ . It is highly advisable to password-protect the whole stats directory.

   Do not change ownership/permissions of files in $STATS_DIR. You can see all stats via the web-interface and you don't need to edit a single file within $STATS_DIR.

   Counter stats are updated in real time. Element usage reports are updated daily according to cron settings (usually at night time when the load on server is low).

   All raw datafiles are stored in $STATS_DIR/logs. Datafiles are in plain text format, delimiter character is pipe. Files can be easily imported into many spreadsheet programs.

   All email addresses extracted from sent cards are accumulated in $STATS_DIR/logs/mail.dat - plain text file, one address per line.

   Back to top or index

2. Finding Cards with Number

   At the bottom of the stats center page (accessible from http://yourdomain/$ROOT_DIR/stats/) there is a form for easy card checkup. When you pick up the card this way no pickup notice is sent, no counter is updated.

   When viewing a card "as datafile" you can see some tracking info about card sender and card recipient (date, IP and user agent).

   Viewing card "as is" shows card exactly as seen by the recipient. This feature is very handy when verifying visitors' complaints about something not seen or heard.

   Back to top or index

3. Finding Cards without Number

   Sometimes you have to find a card without knowing the exact ticket number. It is possible. You have to use telnet login for that purpose.

   Important! If you are about to ask what telnet is - skip reading any of the remaining part of administration section completely. It is of no use for you yet. Teaching the basics of webserver administration is not something that is included in this software license and you have to learn them elsewhere yourself.

   The cards are stored in $CARDS_URL in subdirectories which correspond to months and days. For example a card which has to be sent on Jan 10th will be stored in $CARDS_URL/01/10 subdirectory.

   The name of the cards datafile can be defined by taking the first 4 digits from the card number. For detailed info how a card number is formed please refer to system generated variables.

   If you need to find a card by for example email address and you know it has been sent on Jan 10th you type from the shell prompt:

   fgrep -i 'email' $CARDS_URL/01/10/*
   email can be sender or recipient
   
   Example:
   cd /usr/sites/aw/www/platinum5/cards/03/
   grep -i jjOYSWORLD5@aol.com */*
   
       
    Or course you should replace $CARDS_URL with the actual path 
         (refer to global configuration file magics.cfg). and targetemail 
         with a real query string. 
       
    The first column in results output will give you a card datafile number 
         (datafile). You can reconstruct the actual card number 
         as: MMDDdatafile. 
       
    Back to top or index 
       
     

4. ASAP/QUEUE e-mail delivery

   You don't really need this feature unless you are running a high traffic cardshop. When your traffic goes over 10.000 cards daily you can return to this paragraph.

   The global config file magics.cfg contains the parameter MODE. By default it is set to ASAP. In this mode email notifications about sent or received card are sent immediately after the request is submitted.

   However in event of high traffic when the number of requests submitted within some short time interval is compatible to the max number of processes that your server can handle gracefully, the load can be normalized by changing this parameter to QUEUE.

   In QUEUE mode the email notifications are send at scheduled intervals (by default - hourly). The intervals are set by cronjobs.

   The changes between ASAP and QUEUE mode are instant. You can balance load using this switch quite effectively.

   Back to top or index

5. Storing large amounts of card datafiles

   This section can be useful if you maintain a high traffic site (10.000 cards a day and up) and want to store cards for long time intervals (months).

   Most UNIX systems are compiled by default with comparatively low number of file descriptors (inodes) available. High traffic cardshops with cards stored for 60-90 days can get over the inodes limit in few months. It will result in server's inability to create new files and therefore to complete crash.

   The solution is to create several new filesystems to use for example for storing monthly card datafiles (e.g. $CARDS_DIR/01/ - for January). This is something you should consider beforehand when setting up a dedicated server or adding a new harddrive. Consult with your sysadmin about this issue.

   Back to top or index

6. Cron job parameters

   The source file for cron job cron.tab is usually stored in $STATS_DIR. The typical syntax is below:

   15 0,6,12,15,18,21,22,23 * * * $QUEUE_DIR/sendlater.v5.sh 2>&1
   45 * * * * $QUEUE_DIR/sendnow.v5.sh 2>&1
   1 0 * * * $STATS_DIR/later.v5.sh
   25 0 * * * cd $STATS_DIR; ./make_report.sh > make_report.log 2>&1
   25 3 * * * cd $STATS_DIR; ./cardadmin.sh >> cardadmin.log
   

   Admin shell scripts invoked by cron perform the following tasks:

   1. sendlater.v5.sh

   Processes the queue of e-mail notifications scheduled to be sent later. Writes logfile into $QUEUE_DIR.

   2. sendnow.v5.sh

   Processes the queue of e-mails produced by multi-send feature or all current e-mails when the cardshop is running in QUEUE mode. Writes logfile into $QUEUE_DIR.

   3. later.v5.sh

   Updates later.txt

   4. make_report.sh

   Prepares datafiles for element stats.

   5. cardadmin.sh

   Runs old cards cleanup.

   You can change the cron schedule for all scripts except later.v5.sh IF you know what you are doing. We strongly advise against running make_report.sh at any time other than night time, when traffic is usually low. It's the most resource intense script especially on high traffic sites.

   Back to top or index