=================================================================================
PalMail 0.98 -- a frontend for Voice/FAX messages.
=================================================================================

This is a beta release of PalMail. It works fine for me, but
there may be lots of bugs. Please use it at your own risk.

PalMail neads at least the libraries and include-files for tcl-7.4/tkX-4.0
(with tclX-7.4) or greater (no nead for tclX).
They are not required if you use the precompiled binary version.
It uses (and includes) ET 1.7.2 (Embedded Tk) by D. Richard Hipp.
If you compile it statically, you won't need the tcl/tk files during runtime.
I have tested this program with linux 2.0 and mgetty-0.98 on a Creatix LC144VF.
I can't tell anything about other modems. If you have problems, patches or
suggestions, please send mail to <Tim.Bandelow@Materna.DE>.

=================================================================================

Copyleft  (C) 1995-1997 Tim Bandelow <Tim.Bandelow@Materna.DE>
                        Sven Palme   <palme@elphy.irz.hu-berlin.de>

PalMail was originally based on an old version of faxview by Ralph Schleicher
Copyright (C) 1994,1995 Ralph Schleicher <rs@purple.UL.BaWue.DE>

Some parts are loosely based on XTeXShell, Version 0.91 (21.2.94)
Copyright (C) 1994      Michael Hofmann <hofmann@mzdmza.zdv.uni-mainz.de>

Some parts are loosely based on xtem_texmenu, Version 4.16
Copyright (C) 1994      G.Lamprecht, W.Lotz, R.Weibezahn; LRW c/o Uni Bremen

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

=================================================================================
Installation:
=================================================================================

1. First install mgetty / vgetty and any other tools you may need, e.g.:
   - viewfax  (from mgetty/frontends/X11/viewfax-2.4) to view fax pages
   - g32pbm   (from mgetty/tools)        to convert fax pages to pbm
   - pbmtolps (from the netpbm package)  to convert pbm files to postscript
   - g3tolj   (from mgetty/contrib)      to print fax pages on HP PCL printers
   - g3hack   (from mgetty/frontends/X11/viewfax-2.4) to crop outgoing fax pages
   - pbm2g3   (from mgetty/tools)        to convert pbm to fax pages
   - many other tools from the netpbm package to create fax pages
2. Every user who is allowed to use PalMail should have an entry in '/etc/group':
     phone::17:user1,user2,user3
   If you don't bother about security, you may leave this step out and choose
   the default group of your users in the next steps.
3. Check the first section of the Makefile.
4. Type 'make' to create 'PalMail', 'PalMail.cfg', 'PalMail.man',
   'ata' and 'do_faxrunq'.
   If it fails, try GNU make.
5. Look through PalMail.cfg.
   You may enter your favorite programs for
   - do_View_?_command      (view a fax)
   - do_Print_?_command     (print a fax)
   - do_Play_command?       (play a voice message)
   - do_StopPlay_command?   (stop playing a voice message)
   - do_Record_command?     (record a voice message)
   - do_StopRecord_command? (stop recording a voice message)
   Also check the filenames to conform with your installation of mgetty / vgetty.
   The chosen group (Step 2) should conform with 'file_grp' in PalMail.cfg.
6. Type 'make install' as root.

=================================================================================
Some useful hints:
=================================================================================

Before running this program, you should look at the write-permissions
of some of the files and directories it uses. PalMail can only modify or
delete files, if the user running it has write-permission or belongs to
a group with write-permission.
These files/directories are by default:

* The directories for spooling incoming and outgoing faxes and voice-messages:
  - /var/spool/fax/incoming
  - /var/spool/fax/outgoing
  - /var/spool/voice/incoming
  - /var/spool/voice/messages
* The list of greeting messages:
    /var/spool/voice/messages/Index
* The log-file for zplay / vm (may be called differently at your installation)
    /var/log/vm.log

All these files should belong to a special group (e.g. 'modem' or 'phone')
and have write permission for the owner and the group.
My spool directory for faxes looks as follows:

$ ls -l /var/spool/fax/
total 3
-rw-r--r--   1 root     root          238 Oct 20 20:53 acct.log
drwxrwx---   2 root     phone        1024 Oct 21 14:29 incoming/
drwxrwx---   2 root     phone        1024 Oct 20 20:54 outgoing/

This is achieved by:
  chmod 770 DIRNAME     ||    chmod 660 FILENAME
  chgrp phone DIRNAME   ||    chgrp phone FILENAME

Every user who is allowed to use PalMail should have an entry in '/etc/group'
as described in the installation instructions.

=================================================================================

The command 'Pick Up' (Ring-mode) is useful if you pick up the phone manually
and recognize a fax or a modem on the other end of the line.
Then you can press 'Pick Up' and your modem should take over.
It would only work, if you invoke PalMail as root, since it has to send
vgetty a 'kill -SIGUSR1'.
For this reason a simple C-program is provided which can be run SUID.
It does some security checking, so I think it is save to use it.
If you still consider this a security-hole, change the variable
ATA_MODE to 0750 in the Makefile before installation.

This command didn't work for me with vgetty 0.23 :-(
It works with mgetty and with vgetty >= 0.50.

=================================================================================

'Faxrunq' (FaxOUT-mode) would only work, if you invoke PalMail as root,
since it uses faxrunq.
For this reason a simple C-program is provided which can be run SUID.
If you consider this a security-hole, change the variable
FAXRUNQ_MODE to 0750 in the Makefile before installation.

=================================================================================

PalMail scans the mgetty/vgetty logfile to display some basic information
about connections and phone rings.
Normally the L_AUDIT lines (containing "#####") of the
mgetty logfile are scanned to find the necessary information.
At least loglevel 2 is required.
If you want to display/play incoming faxes/messages directly from the
Ring-mode you need a loglevel of at least 4, because the filenames are
not stored in the L_AUDIT lines.
Because the scanning takes some time if the
logfile is huge, you may want to shorten it in regular intervals.
Use the provided script 'tail_log' as a starting point.
It can be invoked manually by root or via cron.
Don't use the command sequence 'tail FILE > FILE.tmp ; mv FILE.tmp FILE'
while mgetty is running. This would confuse mgetty.

=================================================================================
