@(#) DEFAULT.ins 2.1 90/01/22 13:01:05

This document briefly describes how to set up  a  PC-mail  system
that uses the default PC-mail UUCP software to exchange mail with
its UNIX host. The examples given apply to `old' UNIX UUCP;  your
file names and formats may vary.

THE UNIX SIDE OF THE CONNECTION

The PC-mail programs will need a UNIX host to  exchange  messages
with.  This  automatically gives access to other networks. I sug-
gest the following strategy:

 - Get a UUCP login, say, `uuxyz' on a  UNIX  system.  This  will
also  become  the  UUCP-node  name of the PC. Sometimes, the UNIX
UUCP software will refuse  to  work  with  arbitrary  (uid,  gid)
values; during the initial handshake messages, it will reply with
RLOGIN instead of ROK. On these systems, the (uid, gid) values of
your  UUCP  login  should be small numbers, probably in the range
1-100.

The UUCP systems file (/usr/lib/uucp/L.sys)  should  be  extended
with an entry for the `uuxyz' host, e.g.

    uuxyz Passive

On some systems one has to specify `Never' instead of  `Passive'.
It  may  also  be  necessary  to update the UUCP permissions file
(/usr/lib/uucp/USERFILE).

 - Have all mail for user `uuxyz' forwarded to  `uuxyz!somebody'.
With Berkeley UNIX, this can be achieved by placing  the  address
`uuxyz!somebody'  in the file ~uuxyz/.forward; with System-V UNIX
one may have to put the text `Forward to uuxyz!somebody'  in  the
file  /usr/mail/uuxyz,  which  should  be read/writeable by group
mail. Alternatively, you can ask the UNIX system administrator to
define  an  alias  that  maps  `uuxyz' to `uuxyz!somebody' if the
local mailer supports aliases.

In the above examples, `somebody' is a name that  can  be  freely
chosen;  it  will  not  be used by the PC. Of course, mail can be
forwarded to `uuxyz!somebody' from other accounts as well.

The result of all this is that you can send mail to any  user  on
the  UNIX  host by just specifying her login name; your mail will
appear to come from the user `uuxyz' on the UNIX host. The  UUCP-
node  name of your PC will not appear in mail headers. People can
send mail to you by specifying `uuxyz' on the  UNIX  host.  Since
the  host name of the PC does not appear in mail headers there is
no need to register the PC in, e.g., the UUCP maps.

As a minimum, the UNIX host should support the standard UUCP  `g'
protocol.  This  protocol  was developed for eight-bit data paths
across  dial-up  links  (modems).  Unfortunately,  more  advanced
networks eat up XON/XOFF and other control characters. This  must
be the price of progress.

To handle  non-transparent  networks  I  have  written  a  simple
start/stop  `k'  protocol.  It  has  been in use on the Eindhoven
University Sytek network since 1986 and is part  of  the  PC-mail
distribution.  If  you're really desperate (and have UNIX source)
build this  protocol  into  the  uucico  program  by  adding  the
following line to struct Proto Ptbl[] in the file cntrl.c:

    'k', kturnon, krdmsg, kwrmsg, krddata, kwrdata, kturnoff,

and linking the uucico objects with kio.c  kp.h  kphys.c  kpres.c
and ktrans.c.

THE PC SIDE OF THE CONNECTION

A warning for MS-DOS users: TSR programs may interfere  with  the
operation of the dial-up and file transfer program.

To up bring PC-mail, copy the appropriate makefile.whatever  file
to  makefile  and  edit it (there are template makefiles for UNIX
and MS-DOS).  The MS-DOS makefile is for a  UNIX-compatible  make
utility  posted  to usenet near the end of 1986. There is a batch
command file (DEFAULT.bat) for those who  do  not  have  a  unix-
compatible make utility. The make  utility  provided  with  early
releases of MicroSoft C is definitely not UNIX compatible.

Saying `make' should produce five programs:

 - mail, the menu-driven user interface
 - cmail, a program that checks if there is new mail
 - smail, a program that queues messages for  transmission  after
          doing alias substitution on mail addresses
 - nmail, extracts "From" and "Subject" info from new mail
 - cico, the program that performs dialups and file transfers

Under MS-DOS, the cico program has to be compiled with the  small
memory  model; in order to handle mail messages larger than about
10 kbyte, the mail user interface program should be compiled with
the large memory model.

The programs access a common data base in the  form  of  a  spool
directory with setup file, logfile and message files.  Optionally
there may be  header  and  trailer  files  to  generate  template
messages.  There should be no other files in the spool directory,
to avoid confusion. The spool  directory  should  be  created  by
hand; the PC-mail programs will not do that.

You will have to set some environment  variables  before  running
the mail program.

 - MAILDIR, the location of your mail data base directory
 - EDITOR, the name of your favourite editor program
 - PATH, in order locate the PC-mail executables, and your editor

It is advised to use absolute path names that include  the  drive
name.  The  editor  command  may be an MS-DOS batch file; in that
case you should include the '.bat' suffix in the command name.

The following two environment variables are optional.

 - MAILPRN, the name of a file, if printer output should not go to 
	the default printer.
 - MAILCMD, a command that is executed  on  exit  from  the  mail
        program. If this is an MS-DOS batch file you should include
	the '.bat' suffix in the command name.

At our site, these two variables  are  used  to  collect  printer
output  in  one  file, and to send it to a networked printer upon
exit from the program.

Make sure that the limit on the number of  open  files  is  large
enough  (20  or  so).  On  MS-DOS, this is handled by a line with
`files=20' in the CONFIG.SYS file.

On MS-DOS, the mail user interface requires the ANSI.SYS  driver.
The CONFIG.SYS file should specify a line with "device=ansi.sys".

Run the interactive mail program and choose  the  setup  command.

All entries must be filled or the cico program (for  dial-up  and
file  transfer)  will  complain. On MS-DOS systems, only the com1
port is supported (see the file comport.asm). I am not interested
in  80*86  assembly-language programming; you will have hack your
own com2 support.

The first item in the setup is not used by the dial-up and  file-
transfer program.

Here  is  my  setup  (some names changed) for getting through the
horrible port selector of our local university network (it  needs
to  receive  up  to  nine carriage returns in order to detect the
baud rate of a dial-up call, can you believe it):

    ignore_header_lines: received message-id
    communications_port: com1
    baud_rate:           2400
    remote_host_name:    eutwc1
    login_name:          uutest
    dialup_sequence:     atz\r OK atdt0,455215\r CONNECT \r \0 \r \0 \r 
    \0 \r \0 \0 \r \0 \r \0 \r \0 \r \0 \r \0 \r ease: abc\r ease: def\r 
    hoice:-\0-hoice: 1\r lled: b076\r CLOSED \r
    disconnect_sequence: \0

The dial-up sequence requires some explanation. Basically it is a
list of words separated by whitespace:

    send1 expect1 send2 expect2 (and so on)

The first word is sent to the comm. port. The program  will  wait
until  it receives the second word. Then it sends the third word.
And so on. There is a retry facility, similar to the one in  real
UUCP or later versions of Kermit, that works as follows:  instead
of an expect string you can  specify  an  alternate  sequence  as
words separated by hyphen characters:

    expect-altsend1-altexpect1-altsend2-altexpect2 (and so on)

If the "expect" string  is  not  received,  the  first  alternate
"send"  string  is  sent, and the program waits until it receives
the first alternate "expect" string. If that  fails,  the  second
alternate "send" string is sent and so on. The alternate sequence
is terminated until an (alternate) expect succeeds or  until  the
alternate sequence is exhausted, or due to time out.

Note  that  carriage-return  characters  are  not   automatically
appended  to  "send" strings. In order to specify these and other
control characters in send/expect  strings  I  have  stolen  some
escape sequences from the C programming language, and added some:

    \f          formfeed
    \n          linefeed
    \r          carriage return
    \s          blank
    \t          tab
    \\          backslash
    \nnn        octal code for a character

In  order to send or expect an empty string, use the \0 sequence.
Empty "send" strings introduce brief delays.  An  empty  "expect"
string always succeeds.

The following "send" strings are given special treatment:

    BREAK	causes a null character to be sent
    EOT		causes a Control-D character to be sent

The dial-up sequence specified in the setup file should terminate
when  the  UNIX host is about to display its "login:" prompt; the
remainder of the dialup sequence  is  wired  into  the  software.
This, and having (PC node name) equal to (UUCP login name) are to
prevent fraud. If You  have  problems  with  this  approach,  you
should edit the file "connect.c".

Thus, assuming a Hayes-compatible  modem,  your  dialup  sequence
could be as simple as:

    atz\r OK atdt123456\r CONNECT

When this dialup sequence succeeds, the  program  continues  with
its built-in sequence:

    ogin: your_uucp_login\r ssword: your_uucp_password\r

The disconnect sequence uses the same  escape  sequences  as  the
dial-up  sequence,  but does not use the send/expect protocol. In
the example above, the disconnect  sequence  is  a  null  string,
which happens to be the default.

In order to test your dial-up  sequence  you  can  run  the  cico
program by hand, for example:

    cico -d 9 -p your_uucp_password

This  will  produce  a  lot  of  debugging  output.  Setting  the
debugging  level  to  less  than  9 reduces verbosity. Level 4 is
sufficient to monitor the dial-up and login sequence.

ALIAS DATABASE

The user can define aliases for (groups of) mail  addresses.  The
alias data base is a text file with on each line:

    alias replacement_part

The alias should be a single word; words are separated by blanks,
tabs  or  commas.  The replacement part may be one or more words.
Whenever the smail (mail spooler) program recognizes an alias, it
is  replaced by the `replacement part'. Aliases may be defined in
terms of other aliases; the order in which  they  appear  in  the
alias data base is not important (except when an alias is defined
more than once; the program remembers only the last definition of
an alias). The alias expansion software is smart enough to detect
infinite loops and to suppress multiple occurrances of  the  same
recipient. Alias substitution is not case-sensitive.

BATCH-MODE OPERATION

The cmail program can be run from a batch file  (say,  each  time
the  PC is turned on), to contact the UNIX host, and to report if
there is new mail. Also, you may want to auto-execute  the  cmail
command  when  exiting from the interactive mail shell (using the
MAILCMD environment variable described  above).  See  the  manual
page in the cmail.c source.

TEMPLATE FILES

The user can provide message templates with standard  header  and
trailer  lines.  If  the  file  "header"  is  present in the mail
directory, its contents will be  included  at  the  beginning  of
every  mail  message created by the user. Similarly, the contents
of a file "trailer" will be included at the end of mail messages.
The "header" and "trailer" files should be ordinary text files.
