
   mail2fax.pl Readme
   
  What is mail2fax.pl ?
  
   mail2fax.pl is a perl script that implements a gateway between email
   and FAX. It translates an email - which has to be in a certain email
   format - into a FAX file and feeds it into the FAX spool program.
   
  Requirements
  
   The main requirement for mail2fax.pl is perl. It is tested under
   version 4.036. It also requires a program to spool a FAX too. It also
   requires a mailer that is capable to accept a pre-formatted mail
   message at its standard input. 
   
  Installation
  
   To install the package you have to copy the mail2fax.pl and
   mail2fax.rc files into certain directories. You also should install a
   new user called faxadmin that handles all FAX requests. It might also
   be a good idea to install a mail filter to process only certain mails.
   
   
    mail2fax.pl
    
   To install mail2fax.pl copy it to any directory in your search path. A
   good place is /usr/local/bin. 
   
    mail2fax.rc
    
   Copy the configuration file mail2fax.rc into any directory - but make
   sure that you adapt the location of it in mail2fax.pl (see "In
   mail2fax.pl"). A good place is /usr/local/etc. 
   
    faxadmin
    
   For a simple but efficient managing of all FAX requests you should
   install a new user called "faxadmin". If for any reason you can not do
   that (e.g. you don't have root privileges) you should at least install
   the mail filter. 
   
    .procmailrc
    
   Optionally you can install a filter program to only process mail
   messages that satisfy specific criteria. The distribution contains a
   template for a filter rule using procmail. If you don't have procmail
   but the filter program from the "elm" package (or any other filter
   program) you can use that. Otherwise just add at least a file named
   ".forward" into the home directory of the account that handles FAX
   requests:
   "|/usr/local/bin/mail2fax.pl" #faxadmin"
   
    Test Mail
    
   The distribution also contains a test mail message that let you try
   out the whole setup. For a trial run you should set the Debug option.
   
  Configuration
  
   In order to use mail2fax.pl you have to go through a few steps of
   configuration. 
   
    In mail2fax.pl
    
   Edit mail2fax.pl - somewhere in the top few lines of the script you
   will find a line that reads:
   $ConfFile = "mail2fax.rc"
   Change that to reflect the location of the configuration that you
   chose in the installation. 
   
    In mail2fax.rc
    
   This is the main configuration file for mail2fax.pl. In here you
   define several items that control the behaviour of the script itself. 
   
      =FaxSpool=
      
   This entry defines the program that the script will use to spool a
   FAX. It requires a certain invocation syntax:
   faxspool -D 'Recipient' -f 'email-address' FaxNo FaxFile
   This happens to be the exact syntax of the faxspool program from the
   package mgetty+sendfax. If you use any other package you might have to
   write a little script that emulates the faxspool script of
   mgetty+sendfax ... 
   
      =Mailer=
      
   This entry defines the program that the script uses to send a mail
   message back to the requestor of the FAX. It has to accept a
   pre-formatted mail message at its standard input:
   sendmail -t 
   
      =Billing=
      
   This entry switches the billing on of off. A value of "0" will disable
   this feature, any value > "0" will enable it.
   
   Billing is implemented in a pay-ahead fashion. That means, that any
   user has to buy a certain amount of units up-front. These credits will
   then be recorded in the mail2fax.rc (see "Remaining credits"). Every
   time that a FAX is requested to be sent the cost of the Fax will be
   subtracted from the remaining credits. If the credits are not
   sufficient the FAX will be rejected and the requestor will be notified
   via email. 
   
      =Debug=
      
   This entry enables an internal DEBUG mode. A value of "0" will disable
   this feature, any value > "0" will enable it. This is for testing
   purposes only and should normally be set to "0" since it will not
   actually spool the FAX. 
   
      =Unknown=
      
   This entry defines the name of the recipient if it is not specified in
   the email. By default this name is "unknown".
   
      =FaxAdmin=
      
   This entry defines the account that handles the FAX administration. By
   default this name is "faxadmin".
   
      =Zone=x
      
   These entries define the cost per complete FAX (not per page!) per
   telephone zone. There are 6 zones that allow a flexible price
   structure. Each zone definition contains two items:
   
    1. Zone prefix
       This item is a string that let you define a prefix of the FAX
       number. If the FAX number contains this prefix the associated cost
       is attached for this FAX.
       The search for the correct zone is from Zone 2 through 6 - thus
       making the FAX at least as expensive as Zone 1.
       
       Example:
       =Zone=4 1 defines any FAX number starting with "1" as a zone 4
       number. 
    2. Zone cost
       This item defines the associated cost for each zone in units. Each
       unit is normally a 1/100 of the currency in your country.
       
       Example:
       =Zone=4 1 100 defines the cost for zone 4 as 100 units (~ $1.00)
       
   
   
      =User=
      
   These entries define the user id, password, a discount multiplier, and
   the remaining credits for each registered user. It is the FAX
   administrator's responsibility to create these entries by hand. The
   following four items make up one entry:
   
   
    1. User ID
       This item is the ID of a registered user. It is checked against
       the field "Fax-User:" in the email message. If the IDs do not
       exactly match the FAX will be rejected and the requestor will be
       notified via email. 
    2. Password
       This item is the password of a registered user. It is checked
       against the field "Fax-Pass:" in the email message. If the
       passwords do not exactly match the FAX will be rejected and the
       requestor will be notified via email. 
    3. Discount multiplier
       This item is the an optional discount multiplier for a registered
       user. It allows you to specify whether a user has to pay full
       price for a FAX (value "1"), a fraction of it (value between "0"
       and "1"), or even nothing (value "0"). This multiplier is used in
       the calculation of the cost for the FAX in such a way that the
       zone cost is multiplied with this factor. 
    4. Remaining credits
       This item reflect the remaining credits for a registered user.
       Initially this value has to be entered by the FAX maintainer. As
       FAXes are requested their cost is subtracted from this amount and
       automatically updated.
       Whenever the user buys another chunk of credits the FAX maintainer
       has to update this value.
       
   
   
  Email format
  
   Any FAX requesting email must follow a strict format. It must contain
   at least the following four header lines, one empty line, and one line
   of FAX message in the body of the email message. The four header lines
   must be written exactly like they appear below (incl. lower and upper
   case).
   
   
    1. Fax-To:
       This line must contain a valid FAX number. It also determines the
       cost of the FAX if billing is on. 
    2. Fax-To:
       This line should contain the name of the intended recipient of the
       FAX. It can be left blank - in this value of the option =Unknown=
       is used. 
    3. Fax-User:
       This line specifies the user ID of the requestor. It is compared
       against the user ID in mail2fax.rc. 
    4. Fax-Pass:
       This line specifies the password of the requestor. It is compared
       against the password in mail2fax.rc.
    5. FAX Message
       The actual FAX message must follow the FAX header and has to be
       separated from them by an empty line. It's end is found at the
       first line starting with "--".
       
  FAX status notification
  
   The FAX requestor will be notified by email whether the FAX could be
   spooled or not. He/she will also be notified via email about the tries
   to send the FAX.
   
    Successful request
    
   The FAX requestor will be notified via email if the FAX was
   successfully spooled. This message will contain the FAX number and FAX
   recipient. If billing is on the message will also contain the cost for
   this FAX as well as the remaining credits.
   
    Unsuccessful request
    
   The FAX requestor will be notified via email if the FAX could not be
   spooled. This message will contain a detailed reasoning for the
   failure. In this case the requestor will not be billed for the FAX.
   
    FAX send status
    
   Depending on the FAX system you are using the FAX requestor might be
   notified via email about any try to send the FAX. The "mgetty+sendfax"
   package does that. If the FAX could not be sent the requestor should
   notify the FAX administrator about that fact so the originally
   subtracted credits can be refunded.
   
  User Administration
  
   The User Administration must still be done manually. Fortunately it
   does not involve too many steps.
   
    Register a new user
    
   To register a new user the FAX administrator has to insert a new
   =User= entry into the mail2fx.rc file. The password should be
   negotiated between the FAX administrator and the new user in some way
   (e.g. the FAX administrator could assign it to the new user). The new
   user would have to buy a certain number of credits up front (e.g.
   through sending a check) if the billing option is on.
   
    Update the credits for a registered user
    
   If the billing option is on the remaining credits will automatically
   be updated when a FAX is spooled. If the credits run too low the FAX
   requestor will be notified via mail with a copy to the FAX
   administrator. The user then has to buy additional credits in order to
   maintain his/her status as a registered user.
   
    Remove a user
    
   To remove a user the FAX administrator can either comment out the
   corresponding entry in mail2fx.rc file or remove it altogether.
   
  Legalese
  
   This software is (c) Copyright 1995 Thomas Bullinger. There is no
   explicit or implicit warranty that it will suit your purposes. Even
   though this software has been thouroughly tested the author does not
   accept any responsibility for possible damages.
   The software itself is coverd by the GNU Copying license.
