UNIX TPC Distribution Installation and Setup


Phil - your stuff in this section

     First, you *must* be using HylaFAX version 4.0pl1 or later.

     Make sure that your /var/spool/fax/etc/dialrules is set to adjust
     IDDD phone numbers for local use.  This is important because the
     tpcmailer.pl script will pass a complete IDDD phone number to the
     sendfax program, e.g., +14159682510 (even though your fax modem is
     in the +1-415 prefix).  For an example of a dialrules file that
     does the right thing, look at /var/spool/fax/etc/dialrules.sf-ba

   
     Now you can install it:

        # perl Configure



Notes on Accounting and Settlement

     If you need accounting summaries for settlement, then additional
     support is available.

     For each job, two lines will be added to a file called ACCT: a QUED
     line and a status line.

     The QUED line contains this information:
        - msgid of job
        - fax number
        - file used for advertisement (if any)

     The status line usually starts with "DONE", and contains this information:
        - msgid of job
        - e-mail address
        - transmission time
        - file used for acknowledgement (if any)


  Advertisements (tpcmailer.pl)

     Advertisements are placed in the ADVDIR directory.  Each file
     therein should be a postscript file which will be used to start the
     cover-sheet.

        NB: this file should print on ONLY the bottom third of the sheet,
            the remainder will be imaged with other information.

     To associate an advertisement with a telephone prefix, name the
     file according to the prefix, e.g.,

        +1415968

     That is, all files have the name

        +codeprefix

     where "code" is the IDDD country code and "prefix" is the starting
     digits.  The file named "+" is the default file, which needn't be
     present.  As usual, longest match wins.

     If you want to have more than one advertisement per prefix, then
     create a directory named

        +codeprefix

     and put the advertisements in there, starting each file name with a
     letter or digit, e.g.,

        +1415968/capriccio1

     and the advertisements will be used in round-robbin fashion.

        NB: these files must be writable for round-robbin handling to work!

     The SRCDIR directory is used to keep track of advertising accounts.
     For each account, create a subdirectory (use whatever name you
     like).  For each different advertisement under ADVDIR which belongs
     to this account, link it under the account's subdirectory (again,
     use whatever name you like).

     For example, suppose you had an account for a restaurant called
     Capriccio, and they had two advertisements, one for +1415968 and
     the other for +1415.  You'd create the directory

        SRCDIR/capriccio/

     and then link the files

        ADVDIR/+1415968 to SRCDIR/capriccio/adv.1
        ADVDIR/+1415    to SRCDIR/capriccio/adv.2

     It is the files under SRCDIR which will be used for settlement
     purposes.


  Acknowledgements (notify.tpc.sh)

     Acknowledgemtns are placed in the ACKDIR directory.  Each file
     therein should be a ascii file which will be used at the end of the
     acknowledgement.

     To associate an acknowledgement with a domain suffix, name the
     file according to the suffix, e.g.,

        yoyodyne.com

     or

        mtview.ca.us

     The file named "root" is the default file, which needn't be
     present.  As usual, longest match wins.

     If you want to have more than one acknowledgement per suffix, then
     create a directory named as the suffix, and put the
     acknowledgements in there, starting each file name with a letter or
     digit, e.g.,

        yoyodyne.com/capriccio1

     and the acknowledgements will be used in round-robbin fashion.

        NB: these files must be writable for round-robbin handling to work!

     Again, the SRCDIR directory is used to keep track of advertising
     accounts.  For each account, create a subdirectory (use whatever
     name you like).  For each different acknowledgement under ACKDIR
     which belongs to this account, link it under the account's
     subdirectory (again, use whatever name you like).

     For example, suppose you had an account for a restaurant called
     Capriccio, and they had two acknowledements, one for yoyodyne.com and
     the other for mtview.ca.us.  You'd create the directory

        SRCDIR/capriccio/

     and then link the files

        ACKDIR/yoyodyne.com  to SRCDIR/capriccio/ack.1
        ACKDIR/mtview.ca.us  to SRCDIR/capriccio/ack.2

     It is the files under SRCDIR which will be used for settlement
     purposes.

     When billing statements are sent, the tpcstmt.sh script (described
     later) needs to know what e-mail address to use for each
     advertising account.  Create a file called "contact" in each
     account's subdirectory for this purpose, e.g.,

        echo "franco@capriccio.los-altos.ca.us" > SRCDIR/capriccio/contact

     In addition, create a file called "balance" which contains the
     debit balance of the advertising account, e.g.,

        echo "1000.00 dollars" > SRCDIR/capriccio/balance


  Tracking (tpctrack.sh)

     The tpctrack.sh script is used to track what's going on.  Without
     any arguments, it prints the current contents of the accounting
     file, e.g.,

        % tpctrack.sh < /var/tpc/acct
         destination   source                   time advertise acknowledge
        +14159682510  mrose@dbc.mtview.ca.us   1:13 dbc/adv.1 dbc/ack.1
        +14159682510  mrose@dbc.mtview.ca.us   1:09 dbc/adv.1 dbc/ack.1

     With arguments, it indicates that information about a specific
     advertisting account, i.e.,

        % tpctrack.sh account numprf numsuf < /var/tpc/acct

     where "account" is the advertising account, "numprf" is how many
     digits should be used for summarizing telephone destinations, and
     "numsuf" is how many domains should be used for summarizing e-mail
     destinations, e.g.,

        % tpctrack.sh dbc 6 2 < /var/tpc/acct
        dbc/adv.1 sent to +1415             6 times
        dbc/ack.1 sent to           ca.us    6 times

     The tpctrack.sh script is called automatically by the billing
     script, tpcstmt.sh, described now...


  Statements (tpcstmt.sh)

        NB: at present, billing is calculated only for advertisements,
            not acknowledgements

     First, create the file STMDIR/tariff which contains charging
     information.  Each line of this file has the form:

        TARIFF 1/1 +codeprefix  cost-for-1st-min cost-for-additional-min

     e.g.,

        TARIFF 1.1 +1408364 04 01

     which says calls to prefix "1-408364" are charged at 4 cents for the
     first minute and 1 cent for each minute thereafter.

     If your charging model is different than this, you'll have to
     modify tpcstmt.sh.base accordingly and re-install,



  Putting it all together

     Let's assume you already have the system running and you want to
     activate accounting and settlement.

     Earlier, when you did

        # make install

     all of the necessary directories and files were created.  So:

     1. Decide how often you want to get a tracking statement.  Run
     the tpctrack.sh script accordingly under crontab, e.g.,

        # cat > /var/tpc/4daily.cron
        : run this script through /bin/sh

        /var/tpc/tpctrack.sh < /var/tpc/acct | \
            /usr/lib/sendmail faxmaster -subject "TPC tracking"
        ^D

        # chmod +x /var/tpc/4daily.cron

        # crontab -e daemon
        0 0,4,8,12,16,20 * * * /var/tpc/4daily.cron


     2. Create the tariff file

        # vi /var/tpc/stmt/tariff


     3. Set up advertising accounts.  For each account:

        - create a subdirectory under /var/tpc/srcs, e.g.,

                /var/tpc/srcs/capriccio

        - create one or more advertisements there, e.g.,
    
                /var/tpc/srcs/capriccio/adv.1
                /var/tpc/srcs/capriccio/adv.2

          and/or create one or more acknowledgements there, e.g.,

                /var/tpc/srcs/capriccio/ack.1
                /var/tpc/srcs/capriccio/ack.2

        - create a "contact" file containing the e-mail address to use
          for the advertising account, e.g.,

                /var/tpc/srcs/capriccio/contact

        - if you're going to do billing, create a "balance" file
          containing the initial debit balance of the advertising account,
          e.g.,

                /var/tpc/srcs/capriccio/balance

        - link the advertisements/acknowledgements into the appropriate
          areas, e.g.,

                # cd /var/tpc/srcs
                # ln capriccio/adv.1 ../advs/+1415968
                # ln capriccio/adv.2 ../advs/+1415
                # ln capriccio/ack.1 ../acks/yoyodyne.com
                # ln capriccio/ack.2 ../acks/mtview.ca.us


     4. Decide how often you want to generate billing statements.
        Once a week is probably good, e.g.,

        # crontab -e daemon
        0 6 * * 1 /var/tpc/tpcstmt.sh


Notes on Denial of Access

     If you want to prevent certain (ab)users from having access,
     you can create the NOACCESS file.  Each line of this file contains
     a regular expression to match a mailbox, e.g.,

        ^root@
        ^daemon@
        @dbc.mtview.ca.us$
        ^mrose@fernwood.mpk.ca.us$

     This file is maintained by hand, and is generally empty.

     However, if you are running the accounting and settlement tools,
     you can also have additional files, each corresponding to a
     particular denial of access policy.  For these additional files,
     each line is of the form "local@domain", e.g.,

        mrose@fernwood.mpk.ca.us

     At present, there is an automatic facility to generate a file based
     on one policy.

     The script tpcdeny0.pl implements "Policy 0", which has three
     parameters: number of uses (N), number of minutes (M), period of
     duration (P).  If, during P, a mailbox accesses a remote printer
     server more than N times, or this usage exceeds M minutes, then the
     mailbox is not allowed to access the services for the remainder of
     the period.
     
        NB: the "Policy 0" database is reset automatically by tpcstmt;
            as such, you should run tpcstmt on a regular basis.  This
            basis determines the period of duration parameter, P.

     You should run tpcdeny0.pl fairly often, e.g., once an hour, as in

        # crontab -e daemon
        30 * * * * /var/tpc/tpcdeny0.pl 100 250 week

     which says that any user can access the service up to 100 times, or
     for up to 250 minutes, which ever comes first.


/mtr


Mr. Arlington Hewes