==============================================================================
palmail 1.0 -- a frontend for Voice/FAX messages.
==============================================================================

This is palmail, a user interface to mgetty/vgetty.
It handles incoming and outgoing fax and voice message
and provides a tiny voice mailbox.

This release of palmail 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.5/tk-4.1
or greater.
It also uses (and includes) ET 8.0b6 (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.2.14 and mgetty-1.1.21 on a
Creatix LC144VF modem.
I can't tell anything about other modems. If you have problems, patches or
suggestions, please send mail to <Tim@Bandelow-net.de>.

The latest version is available at http://www.bandelow-net.de/palmail.html

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

Copyleft  (C) 1995-2000 Tim Bandelow <Tim@Bandelow-net.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
   - g3tolj   (from mgetty/contrib)      to print fax pages on HP PCL printers
   - pbm2g3   (from mgetty/tools)        to convert pbm to fax pages
   - pbmtolps (from the netpbm package)  to convert pbm files to postscript
   - some 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'
   and the other programs
   If it fails, try GNU make.
5. Type 'make install' as root.
6. Check the permissions of the mgetty files as described below
7. To use the supplied dtmf script, enter its name "vg_dtmf"
   as dtmf_program into vgetty's voice.conf.
   Your secred code for remote pickup should be placed into
   "/var/spool/voice/.code" .
8. Record the required voice messages using palmail:
   - A standard greeting message with arbitrary name.
   - Messages for the dtmf script (recorded in VocOUT mode):
      "no_new_messages":
       Played if there are no new messages.
      "incorrect":
       Played if a wrong dtmf code was entered.
      "get_code":
       Request to enter a dtmf code.
      "enter_message":
       This one is played after sending all private messages.
       At this time the caller may record a new message.
      "get_command":
       After playing all new messages the caller has the possibility
       to hear them again by typing "1".
   - An optional "alert" message for the dtmf script.
     This must be recorded in the DTMF mode.
9. If you like a spoken date and time played before each new
   message during remote pickup in the dtmf script, fit
   one of the supplied speakdate scripts to your need and copy
   it as "speakdate.sh" with execute permissions to the
   /var/spool/voice directory.
   You will need an appropriate TTS system for this to work.

==============================================================================
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 mgetty/vgetty
    /var/log/vgetty.*

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 install do_pickup SUID, 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
PICKUP_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.sh' 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.

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