Author: Marc SCHAEFER <schaefer@alphanet.ch>
Software: Minimal voicemail system (mvm) version 2.0
$Id: README,v 1.3 1999/03/07 10:56:40 schaefer Exp $

# DISCLAIMER
#    No warranty, either expressed or implied.
# COPYRIGHT
#    Fully protected under Berne Convention, use authorized except
#    if you make money from this use (contact me before).

PRIMARY DISTRIBUTION SITE:
   http://www-internal.alphanet.ch/archives/local/alphanet/mvm/

1.  What is this thing, anyway ?

Hi and welcome to the minimal voicemail system. This is a shell script
and some utilities (also shell scripts) developped under Linux and
RISCos in order to run a rather simple but scalable voicemail system.

You can look in the file SPEC to see what the final goal is. This
README file is only an introduction how to set up the voicemail system
on your Linux computer (as I assume that noone else has RISCos anymore).

NOTE: I have abandonned RISCos as a development plateform in 1996.  I
currently use Linux 2.0.35 (test/production). I am using a ZyXEL 2864I
which answer X.75 ISDN, V34 modem, fax and voice/mvm (as it runs with
ZyXEL's multi-MSN firmware it is able, with proper vgetty patches to
mgetty 1.1.20, to discriminate the called numbers. In my case, I run
the general mvm on a number and my own answerbox on the second. More
details in section 5.2.1). I also had success on the ZyXEL 1496 and
2864, and someone reported success on some USR derivates.

You need a voice modem (e.g ZyXEL series) supported by vgetty and a
moderatly fast computer (generating voice online needs some CPU/FPU).

Please also look at the CHANGES file.

2.  Installation

2.1 Pre-requisites

2.1.1 English voice message generation

Messages are generated automatically (at installation time, and also
for dynamic messages within the system). Even if you use the French
language number generator (adds_on/french*, asked at installation time),
you still need this.

Option 1 is to install rsynth binary, or old rsynth + patch.
Option 2 is to use unpatched but pre-installed rsynth-2.0 and
specify it at installation time.
Option 3 (using another synthesis system, such as Festival or MBROLA
is currently unsupported).

Note that option 1 and 2 are public domain, and thus also usable
in a commercial environment. MBROLA and Festival are not. Moreover,
MBROLA doesn't comme with source.

2.2 Initial setup

First, log as root and type the command
   ./setup.sh

This will create /usr/lib/mgetty and /usr/spool/voice. It will not
alter anything else on your system. The diskspace needed is less than
1 megabyte. Also, the setup script will make a softlink from
/etc/mvm_definitions.sh to the actual place (usually
/usr/lib/mgetty/mvm_definitions.sh) so that programs using the
definitions and the low level mvm library can find it.

WARNING: if your config files are already in /usr/lib/mgetty, they
will be erased !

The installation script will ask you things to configure the
scripts. Full fonctionnality needs to to pre-install rsynth (english
text-to-speach) and vgetty.

I also expect a recent mgetty (at least 1.1.7), older vgetty have
different pvf utils and thus won't work.

This release has been tested with
   ZyXEL 1496, Linux 2.0.27, mgetty 1.1.7

Previous releases have been tested with
   ZyXEL 2864I and non I
   USR Robotics Sportser Vi 33600 (033-6.1.5/1.2.5)

2.2 Generic vgetty/mgetty in /etc/inittab
 
When installed, you can launch vgetty manually or in /etc/inittab (do
not forget the /sbin/init q). Play with the arguments as you like.

s1:456:respawn:/usr/lib/mgetty/vgetty -x 10000 -s 38400 -p "(vulcan-ttyS0) login: " ttyS0

3.  Needed files

  File/Directory                 Used for          Created by    Using
  /usr/lib/mgetty/mgetty.config                    setup.sh      text editor
  /usr/lib/mgetty/voice.conf                       setup.sh      same
* /usr/lib/mgetty/vgetty                           USER          make voice
  /usr/lib/mgetty/randomize                        setup.sh      gcc
* /usr/lib/mgetty/say                              setup.sh      gcc (rsynth)
  /usr/spool/voice               mvm               setup.sh      same
  /usr/spool/voice/main/commands mvm, dynamic menu
                                 system            setup.sh      same or mvm
                                                               menu editor
  /usr/spool/voice/messages/*    mvm prompts       setup.sh      generate.sh
                                                                and MESSAGES
                                                                file and
                                                                rsynth and
                                                                pvftools
  /usr/spool/voice/mailboxes
  /usr/spool/voice/menu_items_types		   setup.sh

Files marked with a (*) MUST be obtained separately because they are
not part of this software. They won't be installed by setup.sh
randomize source is given in adds_on/randomize.

If you have a library of Sun AU (or au.gz) files, you can use it
when setup.sh asks for a ``random library file path''.

If you did not install rsynth, or if you did not hack it to write to a
file named tmp in the current dir, use the one in the primary
distribution site (directory linux_binaries/, only ix86 Linux).

4.  Known bugs

Playing does not stop immediately when typing a hotkey. If typed
too fast, hotkeys can be missed, especially with some modems.

5.  How to use this.

5.1 Basic operation

The password for the voicemail operator (code 0) is 42, of course.
Change it :-) (vi /usr/spool/voice/mailboxes/0/.password).
And then chmod 700 /usr/spool/voice/ (is done by install script).

Then dial your number, just after the modem answers (it will NOT play
the normal modem handshake) and *before* two seconds, send any DTMF
(if you selected unconditionnal as an answer method while running
setup.sh, you won't need to type a DTMF). You should hear the welcome
message. Wait til the end of the message, and follow the
directions. At the main menu, you can use * to identify yourself (code
0, then #, then another message, then 42, then #).

[ the above paragraph is for VOICE_MODE=normal, see the setup script ]

Main menu commands are described in /usr/spool/voice/main/commands.
Types are explained in /usr/spool/voice/menu_item_types.

The menu editor consists of the following commands:
        1 adds an item (can be a goto_menu, then asks owner,
          or any type asked from a list)
        2 removes an item (can be a goto_menu, the system will then
          ask if removing the branch is asked)
        3 tests the menu
        4 edit the welcome file
        * cancel changes
        # accept changes and back

For the menu editor to work, the file menu_item_types must be
installed in /usr/spool/voice. Version 1.0 did not install this file
automatically, this one does.

5.2 Enhanced modes

5.2.1 Multi-MSN discrimination and multiple mvm instances

mvm can be configured to recognize the called (not caller) ID and
launch a different instance. Basically, we set the mvm root directory.
This can be used to implement different independant voice mails, or
special functions such as an automatic answerer. This was only tested
with ISDN, however, and with the ZyXEL 2864I. Please refer to
the ZyXEL 2864I documentation for how to enable multi-MSN mode.

For this to work, as of current versions, you need mgetty-1.1.20
(released in january 1999), plus the vgetty specific patches
you will found at
   http://www-internal.alphanet.ch/~schaefer/vgetty/global_patches/10021999/

Please look first at http://www-internal.alphanet.ch/~schaefer/vgetty.html
for the latest vgetty news.

With this patch installed, you will be able to use, for example, the
following cnd_program (use cnd-program /usr/lib/mgetty/filter_msn.sh
and msn-list 8414081 8414037 8414013 8414014, assuming those are
the numbers that calle_d_ it returns).

---- cut
#! /bin/sh
# very simple MSN filtering (BOOLEAN)
# NOTES
#    - Arguments
#      <program> <tty> <CallerID> <Name> <dist-ring-nr.> <Called Nr.>

CND_SCRIPT_ACCEPT_CALL=0
CND_SCRIPT_IGNORE_CALL=257
CND_SCRIPT_REJECT_CALL=258
CND_SCRIPT_MORE_RINGS_NEEDED=259
CND_SCRIPT_LET_IT_RING=260

if [ $# != 5 ]; then
   exit $CND_SCRIPT_REJECT_CALL
fi

case $4 in
   1) exit $CND_SCRIPT_ACCEPT_CALL;;
      # 8414081, accept fax/modem (and also X.75)
   2) exit $CND_SCRIPT_ACCEPT_CALL;;
      # 8414037, accept X.75 (and also fax/modem).
   3) exit $CND_SCRIPT_ACCEPT_CALL;;
      # 8414013
#   4) if [ $RING_COUNT -lt 5 ]; then
#          exit $CND_SCRIPT_MORE_RINGS_NEEDED
#       else
#          exit $CND_SCRIPT_ACCEPT_CALL
#       fi;;
#      # 8414014
esac

exit $CND_SCRIPT_IGNORE_CALL

---- cut

Now, when the calls happens, vgetty will run and will launch the
voice script (call_program /usr/lib/mgetty/mvm_discriminate.sh)
which is were we do the mvm instanciation (and also go modem/fax
or voice).

---- cut
#! /bin/sh

case $CALLED_ID in
   8414013) exec /usr/lib/mgetty/mvm_vgetty_script.sh;;
   8414037) export MVM_INSTANCE=8414037
            export SELECTED_LANGUAGE=NO_ASK
            exec /usr/lib/mgetty/mvm_vgetty_script.sh;;
esac

exit 3
---- cut

This will launch modem/fax on any other number than 8414013 and
8414037. 8414013 will launch a standard mvm, and 8414037 will launch
a special version of mvm with no language asking. Moreover,
the files will be in /usr/spool/voice/instances/8414037/ instead
of being in /usr/spool/voice. To implement a simple
answering machine, create a /usr/spool/voice/instances/8414037/
hierarchy with:

total 4
drwxr-xr-x   4 root     root         1024 Dec 29 11:59 .
drwxr-xr-x   3 root     root         1024 Dec 29 11:56 ..
lrwxrwxrwx   1 root     root           11 Dec 29 11:56 areas -> ../../areas
lrwxrwxrwx   1 root     root           14 Dec 29 11:57 incoming -> ../../incoming
lrwxrwxrwx   1 root     root           15 Dec 29 11:56 mailboxes -> ../../mailboxes
drwxr-xr-x   2 root     root         1024 Dec 29 11:58 main
lrwxrwxrwx   1 root     root           22 Dec 29 11:56 menu_items_types -> ../../menu_items_types
drwxr-xr-x   2 root     root         1024 Dec 29 12:05 messages
lrwxrwxrwx   1 root     root           13 Dec 29 11:56 scripts -> ../../scripts

So, basically, just messages and main are NOT common. 

vulcan:/usr/spool/voice/instances/8414037 # ls -la messages
total 22
drwxr-xr-x   2 root     root         1024 Dec 29 12:05 .
drwxr-xr-x   4 root     root         1024 Dec 29 11:59 ..
lrwxrwxrwx   1 root     root           33 Dec 29 12:04 leave_message -> ../../../messages/leave_message.1
lrwxrwxrwx   1 root     root           33 Dec 29 11:59 leave_message.1 -> ../../../messages/leave_message.1
-rw-r--r--   1 root     root        19163 Dec 29 12:05 welcome_here

Basically we have an introduction file (welcome_here), and the standard
``leave a message after the beep'' message.

vulcan:/usr/spool/voice/instances/8414037 # ls -la main
total 3
drwxr-xr-x   2 root     root         1024 Dec 29 11:58 .
drwxr-xr-x   4 root     root         1024 Dec 29 11:59 ..
-rw-r--r--   1 root     root           20 Dec 29 11:36 direct_command_exec

The content of this file is:

message_to_operator

which is the menu_item_type for leaving a message.

NB: this assumes mvm's spool was set to /usr/spool/voice, and
it also assumes that you configured mgetty in /usr/lib/mgetty.

5.2.2 Fax forwarding

Although fax forwarding is not technically completely implemented,
there are already some features there. The idea is to be able to
call a number, give a few DTMF (e.g. access code, user identification,
etc), and then send a fax. That fax will be routed according to the
previously given number.

More documentation is in add_ons/fax/README

5.2.3 WWW gateway

WWW gateway is a separate package, available also from the
primary distribution site.

6.  SECURITY ISSUES

NOTES
   - Log files (/var/log/vgetty.ttySx and /tmp/mvm*) should NOT be kept
     world-readable.
   - Data files (/usr/spool/voice) should not be accessible except by
     root, especially the mailboxes subdirectory (contains passwords and
     private messages).
   - Do not forget to change /usr/spool/voice/mailboxes/0/.password
BUGS
   - The system should not run under UID root.
TODO

7.  Final comments

CURRENTLY IMPLEMENTED:
   - modem/fax or voice detection (based on a human input or called
     MSN) and X.75 support.
   - multiple languages support
   - user identification, new user creation, access levels,
     passwords
   - voice-mailboxes for each user. Send, delete, reply functions
   - dynamic menu system (editable online).
   - tree and menu edition
   - hotkeys (also multiple keys at once)
   - mail to voicemail text speach generation (adds_on/mail_to_voice)
   - voicemail to WWW
   - remaining messages notification (e-mail)
   - new message notification/copying/forwarding (e-mail)
   - fax forwarding (mostly)

CURRENTLY NOT IMPLEMENTED:
   SEE CHANGES FILE, section TODO












