UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

Name
     umdss - Unix Mail Delivery SubSystem

Syntax
     umdss [ site ]
     umdss -q
     umdss -v

Description
     Command line option -q queries umdss to report information on traffic
     pending for each site, including live connections. The -v option displays
     the umdss version and copyright information. With no arguments, umdss
     prepares for a remote site to log in and begin a session. With a site
     argument, umdss begins a session for a site that has just been polled
     (originate mode) and is connected. (Polling is not part of the umdss
     software).


     Introduction

     This document describes the umdss program that runs on UNIX computers,
     providing a compatible mail exchange interface with ProLine systems. It
     is organized into the following sections:

     o About UMDSS
     o How it Works
     o Account Installation
     o Installing UMDSS
     o File Permissions and Directories
     o ProLine Site Installation
     o Transporting Mail
     o Transporting Mail with Shell Scripts
     o Transporting News
     o For the ProLine Administrator
     o Logfile
     o Job and Session Reports


     About UMDSS

     Umdss is a simple mail exchange program. It implements the Mail Delivery
     Subsystem (MDSS) protocol designed in 1985 by Morgan Davis and Bill Blue
     for the purpose of simplifying the exchange of mail and news with
     microcomputers, like the Apple II.

     Here are some of umdss's features:

     o Mimics UUCP in many ways.
     o Maintains site lock (LCK) files.
     o Updates session ``.Status'' files.
     o Includes a uustat-like function (the -q option).
     o Integrates with the local mail system (works best with smail 3.x).
     o Maintains a detailed log file.
     o Includes a large packet protocol (mdx) for 90-95% transfer efficiency.
     o Supports non-batched external protocols as well (e.g. sx/rx).

Revised 16 May 1994                    1                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     o Compatible with high-speed modems and ports.

     Note that umdss is simply a mail tranportation utility. It does not
     possess the ability to dial a remote host, connect, and login. A separate
     utility could accomplish this, then invoke umdss (with the name of the
     site being called as an argument).


     How It Works

     A ProLine system dials into the UNIX machine to login as ``umdss''. This
     runs the umdss program (with no arguments). The ProLine system is
     initially the master, commanding the UNIX machine (the slave) to receive
     mail (if there is any). When all mail is sent, the two machines reverse
     roles; the UNIX side becomes master, and ProLine, the slave. Again, the
     master commands the slave to receive mail (if there is any).

     When a letter is sent, umdss calls upon an external file transfer program
     to transmit the file. Umdss deletes each file successfully sent, and
     places an entry in the umdsslog file.

     Likewise, when a letter is received, umdss runs a transfer utility to
     receive the file, then mails it through rmail. When rmail is done, umdss
     logs the reception of the letter.

     Among other things, log entries show the site, date, time, size and
     recipient of each letter. (See the ``Logfile'' section for more details).

     Finally, when all mail is exchanged, both machines disconnect.


     Account Installation

     The first step is to create an account with the following attributes:

     Login:         umdss
     Password:      whatever
     Home:          /usr/local/lib/umdss
     Shell:         /usr/local/lib/umdss/umdss
     Aging:         Disabled -- the account should never expire.

     While you're at it, set up a mail alias so that any incoming messages
     addressed to ``umdss'' (i.e. bounces from the net) are sent to a
     legitimate administrative account.

     You should include umdss in the same group as ``uucp''.


     Installing UMDSS

     The umdss package, normally distrbuted as a compressed tar file, includes
     C source code, utilities, and support files for running umdss on a UNIX
     computer.



Revised 16 May 1994                    2                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     Follow these steps to install the UMDSS package (it is assumed that you
     have sufficient access to create directories and accounts on the system):

     1.   Uncompress umdss.tar.Z (e.g. uncompress umdss.tar.Z)

     2.   Change directories to /usr/local/lib (e.g. cd /usr/local/lib). (The
          recommended location is in the /usr/local/lib hierarchy. This
          location is used throughout this document).

     3.   Unarchive the tar file (e.g. tar xvf umdss.tar). Older versions of
          tar may require the ``o'' option to create the extracted files using
          your group ID information.

     The /usr/local/lib directory now includes the umdss directory which
     contains the following files:

     README                  This document in plain text format
     README.mdx              Plain text MDX documentation
     README.ps               This document in PostScript format
     idfile.sample           Sample ID file
     promail*                Mail grabbing script
     promail.bsd*            Mail grabbing script for BSD
     query.proline*          Sample smail query script
     smroute                 Sample smail routers entry
     smtrans                 Sample smail transports entry
     src/                    Source code directory with Makefile

     To build the umdss utility programs, change directories to ``src''. The
     source code has been written to be compatible with most popular systems
     (XENIX, SCO UNIX, Interactive UNIX, and BSD systems). However, some
     tweaks may be necessary to accomodate your system.

     Before building the executables, take a look at the ``config.h'' file.
     You will want to read the introductory comments and make changes to it as
     required by your system.

     When ready, issue the ``make'' command. This begins the compilation
     process on the source files, and if all goes well, three programs are
     created: umdss, mdx, and upmail. If any errors are reported, you will
     have to do some debugging, or enlist a guru to get it to build for your
     system.

     To place the executables in the right spot (the parent directory), use
     ``make install''. To quickly remove the ``.o'' files, use ``make clean''
     (or ``make Clean'' with a capital C to remove the redundant executables
     and object files). Then change directories to ``..'' to put you back in
     /usr/local/lib/umdss.


     File Permissions and Directories

     Make sure that /usr/local/lib/umdss and its files are owned by umdss and
     are in the right group with appropriate permission modes.



Revised 16 May 1994                    3                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     Now you must make the umdss spool directory. This is the directory into
     which outgoing mail is stored for each ProLine system (each site gets its
     own directory). The recommended directory is /usr/spool/umdss, should be
     owned by umdss and be in the uucp group. Individual site directories will
     be created automatically by umdss, or by the local mail system, so the
     directory should allow for creation of additional directories by umdss.

     Verify that ``idfile'' has appropriate permissions set so that it can be
     read only by umdss.

     Umdss creates lock files (e.g. LCK..pro-site) in the appropriate
     directory where UUCP stores its lock files. Make sure umdss has the
     ability to write to this directory.

     Before you can send mail to a ProLine site, inform the UNIX mail system
     of the site's existence, ensuring that the system never dials the ProLine
     site. This involves editing the Systems (or L.sys) file and paths
     database. The procedure may differ among brands of UNIX.


     ProLine Site Installaton

     Perform the following steps for each ProLine site that will have access
     to the umdss account:

     Add an entry into the ``idfile'' (or edit the sample entry provided if
     this is your first time). The format of the idfile is as follows:

          pro-site;password;send-command;receive-command

     Pro-site is the name of the ProLine site (e.g. pro-apple2). Password is a
     security code that the ProLine site sends to verify its identity. The
     send-command and receive-command items are command lines that invoke the
     external protocol programs to exchange mail. Example:

          pro-sol;morgan;mdx -L -s %s;mdx -L -r %s

     This example shows that the mdx program is used for both sending and
     receiving. The %s characters indicate where the protocol program expects
     a filename. (See the ``README.mdx'' file for details on using mdx's
     options).

     Note: The mdx program is invoked via the C function system(). Some UNIX
     implementations do not include the current directory in the executable
     search path. You may have to add ``./'' (e.g. ``./mdx'') for mdx to be
     found and executed by system().

     The ``idfile'' may include comments where desired. Comments follow the
     pound-sign (#) character.


     Transporting Mail

     If the UNIX host is running a smart mailer, like smail version 3.x or
     newer, it can be told to deposit messages directly into ProLine site

Revised 16 May 1994                    4                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     directories. This is done by integrating the upmail transport program
     with smail. It takes a little work to get it set up, but it is far more
     efficient to use than any other scheme.

     You should be familiar with smail's transport and routing feature. The
     ``transports'' file is used to tell smail how to call a transport program
     like upmail. (Umdss comes with a sample entry for the transports file in
     ``smtrans''.)

     The ``routers'' file tells smail how to recognize which sites use a
     particular transport. Two entries are needed so that smail can locate
     directly connected ProLine sites as well as any ProLine sites found in a
     ``paths.pro'' database containing the paths to known ProLine systems. (A
     sample routers entry can be found in ``smroute''.)

     Smail uses a query script to find out which router to use when delivering
     mail. (Umdss comes with a sample shell script named ``query.proline''.)
     By default, this script reads the umdss idfile to match directly
     connected ProLine systems (this means the idfile must be able to be read
     by smail). A more secure and more efficient scheme is to create a list of
     directly connected sites in the script's ``for'' loop. The drawback to
     this approach is that you need to remember to edit the script each time
     you add or remove a directly connected site.

     A working example is described as follows: two routers are designated to
     any sites that begin with ``pro-''. They test the addresses before local
     and paths matching for regular traffic. The first one looks for exact
     matches (first hop) using the query.proline script. This script scans
     umdss's idfile for names that are directly connected to the host. If that
     fails, the next test uses a sorted paths-formatted database and lookup to
     resolve any path that involves a ProLine site.

     (That database is made by using grep, searching for ``<tab>pro-'' in the
     master paths database and saving the results to paths.pro. The reason for
     this is so that any target ProLine site can be recognized and use the
     upmail transport, rather than the uux transport that would be used if
     there was a match in paths, which is the next test if this one fails.)

     Obviously, the logic utilized to make this all work (with gateway
     resolution) would vary dramatically according to the mail transport. You
     may also need to make adjustments to the sample files if your directories
     differ.


     Transporting Mail with Shell Scripts

     If the UNIX host doesn't have a flexible mailer, like the kind described
     above, the umdss package includes a shell script called ``promail'' (and
     ``promail.bsd'' for use on BSD systems). Promail is run by either
     ``root'' or ``uucp'' to move mail in a ProLine site's UUCP directory
     (e.g., /usr/spool/uucp/pro-site) into the spool directory where umdss
     expects it (/usr/spool/umdss/pro-site). Control and execution files are
     deleted, and only the actual data files (those containing mail) are moved
     out of the UUCP area, into the umdss spool area for the corresponding
     site.

Revised 16 May 1994                    5                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     If you have to use the shell scripts, add an entry in a crontab file to
     execute ``promail'' (or ``promail.bsd'') as often as traffic demands. The
     script should be run via root or uucp, and requires at least one
     argument: the name of the ProLine site. Example:

     20 * * * * /bin/su -c "/usr/umdss/promail pro-site" >/dev/null 2>&1

     Older UNIX systems may impose a length restriction on site names. If this
     is the case with your system, and the site you're adding has a name that
     exceeds the limit, add a second name argument: the truncated version of
     the ProLine site's name. For example, if the site is called pro-apple2,
     and your machine imposes an eight character restriction, give
     ``pro-appl'' as the second argument.

     Modern UNIX systems can accomodate all ProLine site names which are
     usually less than 12 characters, but never exceed 15.


     Transporting News

     The cnews program makes it easy to send uncompressed news batches through
     the mail system to a ProLine site. Be sure that the batches are NOT
     compressed and that they are sent via mail (not deposited directly into
     the ProLine site directories). The batches should be addressed to the
     ProLine site's rnews account (e.g., pro-site!rnews).


     For the ProLine Administrator

     UNIX administrators will want to pass this information onto sites that
     will poll it:

     The ProLine administrator should take appropriate steps to connect with
     the UNIX machine by invoking its mdss program with options that agree
     with the protocol being used on the UNIX system. If mdx is used with the
     -L (4K XMODEM) option, the ProLine site will invoke mdss with ``-x TLX''
     after connecting. This tells it to enable text (newline) conversion,
     large 4K packets, and standard XMODEM.

     A typical L.sys entry for ProLine systems might look like this:

     unix-host Any 9600 593-7305|593-6481 local
             \[in:]2-^M;-[in:]5 umdss \[rd:] whatever
             \[id:] pro-site;password
             \!"mdss -x TLX unix-host"

     If the ProLine system is running CS 2.7a or newer, news articles to be
     posted to the net should be addressed to rnews (e.g. rnews@host).
     Otherwise, the UNIX administrator may want to set up some aliases that
     redirect e-mail letters into specific newsgroups. Again, this is very
     easy to do with cnews.





Revised 16 May 1994                    6                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     Logfile

     Umdss maintains a log file of all messages received and sent, including
     connect and disconnect information. (NOTE: Umdss can only create the log
     file if the umdss home directory is owned by umdss, or if a mdsslog file
     is manually created with proper permissions set).

     Here is a sample section from the umdsslog file:

     pro-sol 8/30-10:28 C i1F 38400
     pro-sol 8/30-10:28 R 1636 pro-palmtree.socal.com!mporter
     pro-sol 8/30-10:28 R 734 miavx1.acs.muohio.edu!tfschmidt
     pro-sol 8/30-10:29 R 2041 pnet01!crash!excalibur.cb.att.com!mlg
     pro-sol 8/30-10:29 S 4656 rnews
     pro-sol 8/30-10:29 S 1914 mdavis
     pro-sol 8/30-10:29 S 1563 rnews
     pro-sol 8/30-10:29 S 3407 mdavis
     pro-sol 8/30-10:29 H S#4,11540 R#3,4411 i1F 38400

     Each entry begins with the site's name and the current date and time.
     Entry codes are:

     C    Connection (showing the port and speed)

     R    Receive (with byte count and target address)

     S    Send (with byte count and target address)

     H    Hangup (showing transfer summaries, port, and speed)

     *    ALERT or ERROR message

     ?    Debugging message

     The H entry shows the number of files (and total bytes) sent after the
     S#, and the number of files received (and total bytes) after the R#.

     The umdsslog file can grow quickly, depending on traffic, and requires
     occassional attention. Using grep to find lines containing ``*'' is
     useful for quickly spotting errors.


     Jobs and Session Reports

     The -q option reports current information about all ProLine sites
     serviced by umdss:

     Site            Jobs Kilobytes Last Access TTY Session
     =============== ==== ========= =========== === =======
     pro-acsd           7     12.30 09/17-06:50 i1A success
     pro-amber          4    165.12 09/19-15:55 i1D success
     pro-angmar         4      7.29 09/19-00:24 i1G success
     pro-beagle         0      0.00 09/19-16:14 i1D success
     pro-calgary        5      8.23 09/19-02:43 i1D success
     pro-carolina       6     35.99 09/19-17:25 i1D TALKING Received 5 (250K)

Revised 16 May 1994                    7                     Printed 25 May 94


UMDSS(NET)                 ProLine Reference Manual                 UMDSS(NET)

     pro-nbs            3      7.56 09/19-14:36 i1F success
     pro-nsdapple       3     21.18 09/19-14:55 i1E success
     pro-party          1     25.15 09/19-16:00 i1E success
     pro-sat           10    142.68 09/19-04:04 i1D success
     pro-sol           34    149.33 09/19-17:19 i1M TALKING
     =============== ==== ========= =========== === =======
                       77    574.81

     The -q option will report FAILED sessions as well as bogus lock (LCK)
     files that would otherwise indicate active sessions. Bogus locks can
     occur if umdss terminates abnormally, but they won't prevent subsequent
     sessions from starting up.

Notes
     The umdss project is continually evolving as new UNIX systems implement
     it. Comments are appreciated on the software (and documentation) and any
     suggestions for making it work better.

     If you make changes to the source code, be sure to enclose them within
     conditional directives. Do not change any of the existing code. Send your
     changes to mdavis@crash.cts.com so they can be included in the next
     official distribution.

Files
     /usr/local/lib/umdss/ - umdss's home,
     /usr/local/lib/umdss/idfile - site id file,
     /usr/local/lib/umdss/umdsslog - logfile,
     /usr/local/lib/umdss/src/ - source code directory,
     /usr/spool/umdss/ - site spool directories,
     /usr/spool/umdss/.Status/ - contains site's status files

See Also (ProLine)
     intro(NET), poll(NET), scan(NET), sendmail(C)

See Also (Unix)
     cnews(C), smail(C)

Authors
     Morgan Davis (mdavis@cts.com) and Bill Blue (bblue@cts.com)

Revised 16 May 1994                    8                     Printed 25 May 94


