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