----------UDG2.TXT ESSENTIAL READING -----------

Last revised May 23 1993
Written by rossl@westmead.health.su.oz.au

As long as you comply with certain conditions set out at the end of this
document, you do not have to pay any money to use the software in this
UDG kit. In fact it is not possible to legally use this software if any fee
was paid for it other than with the written consent of the author. 

If you do decide to use this software, although you are under no
obligation to do so, you are cordially invited to send me some email with
it. There is always the possibility of a new version coming along and I'll
try and notify users and sites who inform me of their existence. I can't do
that unless I know who you are.

NONE of the material in this UDG kit has been released into the public
domain. This material is original work and all rights are retained by the
author (Copyright, (c) Dr Ross Lazarus, 1992). Please see the section on
Legal matters at the end of this documentation before distributing,
installing or using any of these materials since you must agree to comply
with certain conditions in order to gain your free licence to these
copyright materials.
 
---Background - Waffle 1.65, PMail and the Internet---

Waffle is a shareware Bulletin Board System (BBS) available for both
DOS and UNIX machines, which uses the Unix to Unix Communications
Protocol (UUCP) to transfer mail and other files. It can easily be set up to
talk to a friendly Unix box for mail transfer and allows dial in users
access to a functional BBS. If the host Unix box is on the Internet, then
you can readily manage sending and receiving your internet mail through
Waffle on a DOS machine. 

Even though Waffle is a fine piece of software, it is not as easy to use or
as "friendly" as the Pegasus email (PMail) package for Novell networks.
Moreover, Waffle is designed to work as a normal BBS accessed over a
telephone line, not a Novell network. 

Fortunately, PMail provides a User Defined Gateway (UDG) facility
which makes it possible to use it as the mailer front end and Waffle as the
mail transporter. Thus you can have the best of both worlds - connection
to the approximately 750,000 machines currently on the internet (as at
August 1992) and a friendly mail front end which runs on Novell network
DOS workstations. 

For connected internetworks of Novell file servers, this UDG offers
substantial cost savings through the use of a single Waffle UUCP gateway
serving all users on any workstations on any of the connected file servers.
PMail installations with MHS already have such a facility, however, this
UDG kit allows the rest of us to gain the same benefits without the
additional expense of purchasing MHS - Lookout Novell !!!. 

In fact, one reason I wrote this UDG kit was to avoid the cost of buying
MHS. For $30, you can register Waffle. This kit and PMail don't cost
anything. Anyone who wishes to is quite welcome to send me the change
which should be about $1470 per site based on Australian MHS prices. 

Note that although PMail for the Mac is available, this UDG package is
NOT available for the Mac, so Mac users will have to wait for someone
to write them a UDG. The source is in Turbo Pascal and I use the 5.5
compiler (it still works!). It might be ported, but not by me.

Note also that this document will NOT help you to get Waffle working -
there's more than enough documentation in the Waffle distribution for you
to do that without my help. If you can't get Waffle working, you won't
have any use for this UDG kit and you'd be wasting your time reading
any further until you've fixed Waffle. Comp.bbs.Waffle is a VERY good
newsgroup if you're having Waffle problems. Please don't hassle me with
Waffle installation or care and feeding problems.

------------------------Basics----------------------

This file and the accompanying software may be of use to Pegasus users
wishing to install Waffle 1.65 as a UDG. The documentation and material
in UDG.ZIP which is part of the distribution kit for PMail 2.3R2 describe
how to attach version 1.64 of Waffle to PMail. The mailbox structure
used by Waffle has been changed for version 1.65 which was released on
10 August 1992 or so.

This new mailbox structure is based on mail folders, each kept in a single
mail file (each potentially containing multiple messages delimited by 4
ascii  characters) together with a separate index file with message
lengths and pointers to the boundaries of each individual message. This
means that the mail on a busy system will be stored much more efficiently
in terms of DOS file allocation units. 

Aside from this, if you're happy with Waffle 1.64, there is no compelling
reason to upgrade as far as I know. The new documentation lists hundreds
of things which have been fixed, but it's entirely possible that none of
them have had or will have any effect on you if your current Waffle
works well. 

However, if you're unable to resist the urge to run the latest and greatest
or if you're about to embark on a new installation, read on.

PMail supervisors wishing to add UUCP connectivity using Waffle
version 1.65 will need to read this documentation and use the
accompanying "glue" programs - one of which converts outgoing mail
items into files in the Waffle spool directory while the other is a mail
delivery agent (MDA) responsible for splitting the new format Waffle
mailboxes into individual pieces of PMail compatible mail in the
recipient's netware mail directory. 

Note that it may be possible to use filter.c (supplied in udg.zip in the
distribution kit for PMail 2.3(R2). However, the program described here
(PegWaf.EXE) offers some advantages, including the ability to deliver
outgoing spool files to a gateway on a remote server (assuming you have
more than one novell netware file server sharing the same physical
network cable). It also writes outgoing spool files with numeric names -
Waffle's uuq does not like filenames containing hex digits which is what
PMail uses for container files. Finally, it adds a line in the xqt file to
indicate who the requester is to the remote system. In general, you would
be best advised to use it.

In fact, both of the programs in this UDG kit (PegWaf.EXE and
WafPeg.EXE) have a built in capacity to deliver to remote servers so a
single Waffle gateway can serve users on any number of individual Novell
servers as long as these are all directly connected. All of this without the
expense of MHS ! 

Getting this remote gateway capacity to function is very simple but it is
strongly recommended that you get your Waffle gateway working properly
for users on the same server as the gateway before installing the UDG
software on remote servers !

Here is how mail flows when the PMail UDG is working with Waffle
1.65

a)--PMail-> UDG-> PegWaf.EXE----> spooled outgoing uucp files
     (user sends                        |
     new mail)                          |
                                        V
                                    Your Waffle <--> host system(s)
                                        |
                                        V
b)----PMail <------WafPeg.EXE <--New mail in Waffle mailboxes
     (user receives
     incoming new mail
     and is notified)

Path (a) is followed whenever a user sends mail to a non local address.
The outgoing UUCP spool files can be on a different server than the one
PMail was invoked from. PMail searches the UDG's (defined in
PMGATE.SYS) for the first one able to handle SMTP mail and uses that
UDG definition. A sample definition for a Waffle gateway is shown
below. It calls PegWaf with a number of required parameters which
control the preparation of UUCP compatible data and control files in the
relevant spool directory - note that PegWaf must be able to locate the
Waffle STATIC file in order to find some of the Waffle setup values it
needs.

Path (b) is followed when new Waffle mail arrives via UUCP. Ideally,
WafPeg should be executed after uuxqt following any poll since uuxqt
may have written new Waffle mail files. The "new mail" files can be
delivered to a user on a remote server as long as the MDA is given a
userid and password which allow Create and Scan (and Write for Netware
2.x) access to sys:mail. Note that the Scan right is needed to check for the
subatomic sized possibility that a file of the same name as the one WafPeg
will randomly generate already exists (for the mathematically oriented,
without Scan rights, a piece of NEW mail has about a 1 in (2^32 - 1)
chance of overwriting an already existing unread piece of mail since
WafPeg generates new filenames from TurboPascal "random" long
integers). The recipient will be notified that new mail has arrived via the
gateway if they are currently logged in. Files are created using the PMail
convention of 8 random hex characters + '.CNM', so the next time the
user runs PMail, they'll find the new mail.

----------------Preparing for UDG Installation-------------------

To run a reliable uucp link for PMail, you'll need :-

a) a dedicated, reliable pc with a few Mb of spare hard disk capacity,
which can be left turned on 24 hours a day waiting for incoming calls.
Most organizations have had computers for long enough for some old
XT's or even AT's to have started accumulating in dusty storerooms. As
long as they boot and run quite reliably, their actual velocity doesn't much
matter (except to BBS users !).

If you want to be able to run a reliable mail system or a BBS, then clearly
this machine cannot be used for much else. Alternatively, if you're game,
Waffle can probably be coaxed to run under OS/2, Desqview or
something heavy duty like that so you can share the PC during work
hours. A fast machine with lots of RAM may well offer that possibility.

b) a dedicated telephone line and modem so Waffle can receive and make
calls.

c) an installed and working copy of Waffle 1.65 - available from Simtel
via anonymous ftp in the Waffle directory as waf165.zip as at August
1992. Note that Waffle is shareware and the $40 registration fee should be
sent to the author if you decide to use it after a reasonable evaluation
period. (PMail and this UDG kit are free software. Conditions of use and
distribution of this UDG kit are set out below and PMails conditions of
use are set out in the PMail distribution kit)

d) a working copy of the Pegasus mailer - available from all sorts of
places via anonymous ftp including splicer.cba.hawaii.edu in the pegasus
directory as PMail235.exe as at February 1993.

e) an internet connected host. This will usually be a *nix box willing to
modify their sendmail.cf or whatever in order to route incoming mail and
happy to give you a uucp account and password. There are a number of
commercial organizations now offering this service for a modest fee if you
can't find an academic host. It would be possible to connect to any
number of other Waffle BBS's if you just need an email connection
between distant components of an enterprise and don't need internet email.

f) hardcopy of this documentation which you have studied carefully. This
UDG kit is as simple to install as I could make it, but there are an awful
lot of things which need to be right for it to work. Many of these are
documented here. Some you may need to nut out for yourself.

Both Pegasus and Waffle MUST be installed and working independently
and correctly before you even think about installing the UDG. The UDG
will not fix something that's broken. 

Firstly, David Harris's Pegasus package must be working - this is
probably the easiest piece of network software you'll ever install ! Use
GUIDE.EXE which comes with the PMail distribution kit and send Dave
Harris the current fee for manuals - the manuals are very well put together
and will make life much easier for users and network supervisors. If you
have a wierd Netware setup (eg your mail directory other than in the
standard SYS:MAIL directory) then you will have to ensure that this
gateway is told where to deliver mail (see below). On the whole, the
normal defaults which Netware uses are quite sensible and you should use
them unless you have some very good reason not to - the default values
used in this UDG package are based on normal Netware defaults.

This version now offers standalone operation. Please see the section on
standalone operation at the end of this document.

Secondly, you need a working Waffle. There's plenty of documentation in
the Waffle distribution dealing with Waffle installation, care and feeding.
So there's no need for me to repeat any of it here. Suffice it to say that
DOS.DOC, NETWORK.DOC and MANUAL.DOC should be read
several times ! Assuming that you can get Waffle to answer the phone and
assuming you can get it to deliver and receive mail via your host, then
you're ready for the next step. It is vital to follow the instructions in
UPGRADE.DOC if you are upgrading to 1.65 from a previous version
since there are many changes to your control files. 

In order to connect to Pegasus, Waffle needs to be installed on a network
workstation. The exact location of the various Waffle directories and files
is configurable, but the "static" file (which contains information about the
node name and directories in use) and the spool directories (which is
where uucico will look for control and data files to be sent to your Unix
host) MUST be on the file server hard disk - otherwise the UDG software
will NOT be able to read the static file when invoked from other
workstations and PMail will not be able to write outgoing mail to the
spool directories ! 

All other Waffle files could be installed on the gateway workstation's hard
disk - this would improve security somewhat but makes it impossible to
adjust static file and other settings from a remote workstation during
installation. On the whole it is easier if Waffle is setup to run from the
server in my experience. A stock standard Waffle installation is preferred
- just replace C: with F: throughout the static file and life will be easier
since the components of this gateway use the standard Waffle defaults.
Remember to use the -d (create and write to subdirectories) option of
pkunzip when you unpack waf165.zip !

For testing purposes, remember you can use Waffle in local mode -
Waffle LOCAL 
from the gateway machine console - this will only work when you've got
the path and static file environment variable set up correctly. Once you're
logged in, you can send mail to yourself which will go out via uucp to
your host and come back to you if you use your own full internet address
(including your domain) as the destination - this fools Waffle into thinking
that the mail is not for local delivery. While this may sound like a stupid
thing to do, it's the best way to test your uucp link without annoying other
people with test messages. If you can't get mail to make a round trip via
your internet host then there's no point in proceeding with the UDG
installation.

Waffle will normally operate 24 hours a day on a dedicated workstation.
This workstation MUST be able to reboot if you use a watchdog to reboot
on loss of carrier (a Good_Idea !). Since this will happen frequently, the
workstation autoexec MUST somehow log the workstation in to the
network with a userid which has all necessary access to the Waffle
directories. 

Now you could do this with a userid which has no password. You could
also experience Very_Bad_Things as a result of unauthorised access to
your mail and worse if you do this. Better to use keyfake or something in
the workstation autoexec. It is also possible to pipe the userid and login
from a dos text file (eg after loading ipx and netx, use

f:\login\login < c:\secret\login.txt 

in the autoexec.bat file, where c:\secret\login.txt has the userid on the first
line and the password on the second line). At least then the hacker has to
have physical access to the gateway machine to find out the password....
If none of this makes any sense, go find someone who might know
enough about netware, security and dos to do all of this for you.

Of course, the other thing to watch out for is broadcast messages ! If
some turkey broadcasts a "hello" message to everyone, your gateway will
freeze unless you have issued a
castoff all
command in it's autoexec.bat. This is most important if you want your
gateway to work 24 hours a day without intervention ! It's also worth
logging in as the gateway, running PMail and setting the extended
preference so the gateway "user" REFUSES to accept any mail - no one's
ever going to read it !

Do yourself a favour. DO NOT proceed with the UDG installation until
Waffle is able to reboot without manual intervention and deliver and
receive mail sucessfully to and from your host machine!. 

On my gateway, I have an automatic reboot every morning at 1 am by
scheduling reboot.com to clean up in case something odd has happened.

One additional problem - every user of the UDG MUST HAVE a
subdirectory under the Waffle USER directory for incoming mail. If mail
arrives for a user who DOES NOT have a USER directory, it will be
bounced back to the sender and a message will appear in the BOUNCES
file in the \Waffle\admin directory. A simple program (makeuse.exe)
which makes the required subdirectories is provided with this UDG kit. It
will find your Waffle static file and make a directory for every netware
userid it finds in the bindery. This program should be run periodically -
the Waffle schedule file is a perfect place to run this from - arrange for it
to every morning at 2 am by adding a line like

00 02 * * * makeuse >> f:\Waffle\admin\udg.log

to your \Waffle\system\schedule file.

If you have users on remote servers, then you will have to make sure that
the supervisor on each of those remote servers tells you when a new user
is added to their bindery. Name clashes will be a problem and some
mechanism needs to be set in place to prevent two users on any group of
connected servers having the same userid. Although it is possible to
forward mail from Waffle to a different name on a remote server, all
netware userid's MUST be different to keep the from: lines different - this
could be subverted by using the "Default reply-to:" option of the extended
preferences menu of PMail but my advice is to keep it simple by keeping
names different.

--------------------Informing PMail about your UDG----------------------

PMail has to be told about the existence of a User Defined Gateway or it
won't ever try to invoke it. You do this using the pconfig program which
comes with PMail.

Copy PegWaf.EXE to any convenient network directory which is on every
users search path - eg sys:public, and flag it share read only. Read the file
UDG.TXT which comes with the PMail distribution in the UDG.ZIP file.
There are a number of minor changes which must be made to the UDG
setup described there. In particular, you will NOT need to use a
SENDMAIL.CF to change PMail's main menu since all Waffle UDG
tasks will be automated in this installation and your users never even need
know that the gateway exists - it's operation is totally transparent when
this UDG kit is correctly installed.

The UDG definition screen is accessed by selecting "User defined
gateway" from the main menu of PCONFIG - you MUST be supervisor
equivalent to run this PMail utility, and you should run it from the
directory where the pmail.exe file which your users will be using is
located (probably sys:public). 

Waffle 1.65 seems to get confused when dealing with control and other
file names longer than 4 characters,  so use only "~d.wom" as the
"Filename Format" rather than "~d~d.wom". In fact, uuq gets confused
when spool file names contain anything other than numerals and shows
(null) instead of sender details. 

Here is a working example

Gateway name:            Waffle
New mail path:             
Is ^ a program to run?:  N
New mail search mask:      
Outgoing mail path:      z:\mail\~b
Run for outgoing mail:PegWaf ~c ~t GMU MAIL XXX
Filename format:         ~d.WOM
Run to validate address: 
Reply address format:    ~n@[yourhost.yourdomain]
Accepts SMTP addresses?: Y
Simple message headers?: N
UUencode attachments?:   Y
Burst messages?:         Y
Strip GW name?:          Y
Check new mail every 0 seconds.

Note that mail replies will be sent to the user's Netware userid by the
value in the "Reply address format:" line - of course you should substitute
your own host and domain here (!). There is an 8 character limit implicit
in this setup because the users Netware userid is used as the name of a
Waffle user directory and DOS only permits 8 character directory names
(ignoring the 3 character extension since dots in internet addresses have
special meaning). If you have users with names longer than 8 characters,
they should probably be changed (other than SUPERVISOR !). If
necessary, this could be changed to ~8@yourhost.yourdomain which
gives the first 8 characters of the Netware userid.

I use the drive letter z: because all of my drive mappings are done in the
system login script using "map ins" - so z: is a very safe bet as long as it
hasn't been "map root"ed. You may choose another drive letter, but be
warned - every UDG user MUST be able to find the nominated path
somehow. I had problems with some workstations which used a lastdrive
statement so that k: became the default first network drive instead of f:.
Your mileage may vary...

The "Run for outgoing mail:" is the most complex line. In the example
above, as long as PegWaf is on the current path (you must have put
PegWaf.exe somewhere like sys:public where everyone should already
have mapped access to) it will run PegWaf with 5 parameters - the first
two are mandatory, the last 3 are optional and only used for remote
gateway delivery :-

1) "~c" will be replaced with the name of the temporary "container file"
written by PMail when PegWaf is called - this is the mail text with rfc822
headers, ready to go. PMail converts all of the letters which are preceded
by a tilde (~) into things it knows about.

2) "~t" is replaced with an rfc822 "To:" address - the address to which
the mail is to be delivered

3) "GMU" in the example is an optional parameter - the name of the
netware server to which the Waffle gateway is attached.

4) "MAIL" in the example is the userid to use when delivering spool files
to the gateway workstation

5) "XXX" in the example is the password to use for that userid

Note that if you do need to configure the UDG on your server to deliver
outgoing files to a remote server, the userid and password you configure
MUST work on the gateway server ! More importantly, make sure that
the remote server supervisor sets that user's account details so the
password cannot be changed by the user and does not require to be altered
after a fixed period. The account only needs minimal privileges as detailed
below.

One minor gotcha is that the UDG definition screen only allows a limited
number of characters (about 50 from memory). If you need a longer
command line, you might need to call a batch file. Remember to copy
PegWaf.EXE to a directory that all your users can read - sys:public is a
good spot for it.

------------Installing PegWaf - the User Defined Gateway------------

The PegWaf program behaves something like Brendan Murray's original
filter.c but adds an organisation line (if an organ: is defined in Waffle's
static file). It also knows how to work out the date/time and can get the
current user's name from the bindery so these do not need to be supplied
in the UDG definition. In addition, it will return outgoing mail if it is
unable to write the uucp files to the spool directory - this is only likely to
happen if the remote server on which the gateway lives is unreachable for
any reason and will probably never happen if your gateway is on the same
server as you are sending mail from. 

Note that in the example above, PegWaf will assume that the remote
Waffle static file is on \Waffle\system\static (the Waffle installation
default). If it has been set up differently, you can add the full netware
path to the server name (eg
GMU/SYS:WOFFLE\STRANGE\FUNNY\STATIC). Why anyone might
do this I do not know, but you can do it if you insist although I can't
guarantee that it will work since I have not tested it properly. There is a
limit of 127 characters or so in DOS command lines and you must be
careful not to exceed this count with what is passed to PegWaf. In fact the
limit for this line in the UDG definition screen is even shorter - you may
have to use a batch file here. If you don't know what I'm talking about
then you should probably find someone who understands DOS better than
you do.

If the gateway is on a workstation attached to your home server, you
should NOT use parameters 3, 4 or 5. Instead, PegWaf will look for the
dos environment variable "Waffle" which must contain the path to your
Waffle static file. Since Waffle will not work without this, it will probably
already be set on the gateway.  The default is "\Waffle\system\static". If
you have used something different, you will have to adjust your system
login script to include a line which sets this parameter at login - eg

dos set Waffle=f:\woffle\strange\funny\static

If a remote server name is supplied, but no userid or password then
PegWaf will attempt to deliver spool files logging in as "GUEST" with no
password.

For PegWaf to be able to deliver spool files, all users on the same server
as the gateway must gain the following minimal access rights in addition
to whatever else they need (the login userid and password passed to
PegWaf on the command line must grant these on the gateway server if
you have gateway users who normally log in to remote servers since
PegWaf will login to the gateway using this userid to deliver spool files)

1) Read, Open and Scan rights to the directory containing the Waffle static
file - this should normally be f:\Waffle\system\

2) Create, Scan (and for Netware 2.x, Write) rights to the spool directory
named in the static file - this should normally be f:\Waffle\spool\

3) Create (and for Netware 2.x, Write) rights to the home server mail
directory in case mail has to be returned - if the spool files cannot be
written on the remote gateway spool directory for some reason. This will
normally be f:\mail\

The easiest way to do this is to add these privileges to the group
EVERYONE if they are not already there, and add them to the special
login remote gateway users will be using. If your gateway is on a remote
server, the PegWaf access login MUST have access to both the static file
and the spool directory as described above or it will not be able to deliver
spool files, but making it a member of group everyone is NOT
recommended - it should have absolutely minimal priveleges to minimise
the consequences of hostile intrusion. One good method is to use the same
userid as your internetwork uses for PMail mail delivery - just add the
few extra priveleges needed for gateway operation.

----------Installing WafPeg - the Mail Delivery Agent---------------

When mail comes in to your gateway via Waffle, it is normally left in a
file called MAILBOX.F in the user's subdirectory of the \Waffle\user
directory (assuming you are using the defaults). To get it delivered in a
form that PMail can use, it must be processed with WafPeg. This program
should be executed anytime uuxqt is called - normally you should add a
call to WafPeg to 3 batch files which are part of the Waffle installation
and are usually found in the \Waffle\bin directory - poll.bat, uushell.bat
and run.bat. It is vital that WafPeg be executed after any Waffle activity
in which mail may have arrived - otherwise incoming mail will languish in
Waffle mailboxes. Mail can come from an outgoing poll or an incoming
call, so adjust those batch files accordingly.

A sample poll.bat file might look like :-

-------------------cut here-------------------------
rem poll.bat for Waffle
uucico -sany -r3
f:\Waffle\bin\WafPeg /nf:\mail /uguest /pguestpassword
-------------------cut here--------------------------

A sample uushell.bat file might look like :-

-------------------cut here-------------------------
rem uushell.bat for Waffle
rem called whenever a uucp login occurs
rem since the appropriate error level is set by a fixed
rem shell command for all uucp users
uucico -r0
uuxqt
f:\Waffle\bin\WafPeg /nf:\mail /uguest /pguestpassword
-------------------cut here--------------------------

A good place to put WafPeg.EXE is in the Waffle\bin directory - this
must be on the gateway machine's path for Waffle to work anyway, so
copy it there. Normal network users do not need to be able to access this
file.

Note that the normal operation of WafPeg.EXE assumes that there is a
Waffle User directory corresponding to every PMail user and that this
directory has the same name as the PMail user's Netware userid. For this
reason, your Netware userid's MUST be limited to 8 characters
maximum. It is possible to deliver Waffle mail to a different Netware
userid using the FORWARD.P file described below. If you have dial in
users, be sure that there is no Netware userid in your bindery which
matches their Waffle userids so that WafPeg leaves their mailboxes alone !

Like the companion program PegWaf.EXE, WafPeg.EXE can deliver mail
to remote servers. This activity is invoked by a special file in a user's
Waffle directory called FORWARD.P - each line may contain a
servername/username for delivery of PMail compatible mail items and
may contain comment lines starting with a hash - for example

-----------cut here---------------
# sample forward.p file
# this will force delivery of Waffle mail for
# ross to remote server gmu with a copy to secretary on server other
GMU/ROSS
OTHER/SECRETARY
-----------cut here---------------

If this file is found in the Waffle user directory for Ross on the gateway
machine (eg REMOTE/SYS:Waffle\USER\ROSS), the MDA will attempt
to login to GMU using the userid and password supplied on the command
line and will search the GMU bindery for user ROSS and deliver mail to
that user's netware mail directory on GMU. Of course for this to work,
the WafPeg userid and password must grant appropriate access to the
users remote home server and for this to work, WafPeg must have been
invoked with a username and password to use when delivering mail to
remote servers.

The parameters for WafPeg are preceded by a dash or a slash and a single
(upper or lower case) letter. Legal values and their actions are :-

-H = print some help text and stop - any other parameters are ignored

-? = same as -H

-N[netware mail directory] = directory to use for netware mail delivery,
default is f:\mail. For this to work, the Waffle workstation must be logged
in to the local server and have appropriate drives mapped. Since the
workstation may need to reboot without manual intervention, you have the
option of setting up the workstation to use a netware userid which has no
password (a Very_Bad_Thing) or using some kind of keyboard stuffer to
automate the login - keyfake from pc_magazine works well - available
SOMEWHERE on Simtel !

-U[remote server userid] = user id to use when logging in to remote
servers for mail drop off - the default is GUEST

-P[remote server password] = password to use when logging in to remote
servers for mail delivery - the default is no password.

-D = run in DEBUG mode. Be warned. When this option is invoked,
mailboxes are processed but NOT deleted. As a result, mail items will be
resent as often as you run in debug mode. Use this mode ONLY when
testing and remember to kill old mailbox.f files manually after each run.

When it is invoked, WafPeg finds the Waffle static file using the dos
environment variable Waffle. This MUST be set for Waffle to run on the
gateway and since WafPeg is only ever run by the gateway workstation,
this should not be a problem. It then locates the Waffle user directory and
examines each subdirectory in turn looking for a new mailbox. Waffle
new mail is always stored in mailbox.f .

If one is found, is exploded into individual mail items and dropped into
the netware mail subdirectory corresponding to the user's hexadecimal id
number as obtained from the netware bindery - unless a FORWARD.P
file is found, in which case WafPeg attempts to login to the nominated
server to deliver mail to the nominated user's netware mail directory. If it
succeeds in delivering any mail, WafPeg tries to notify the user that new
mail has arrived via the gateway and then deletes the new mailbox unless
being run in debug mode.

A log of activity is written to stdout and this may be redirected into a log
file - in fact it is strongly recommended that you do this - eg
WafPeg -nF:\MAIL >> F:\Waffle\ADMIN\WMDA.LOG
Those double angle brackets (>>) tell DOS to APPEND the log output
to the named file - if it does not yet exist, it will be created.


---------------Advanced Features-------------------

Due to lack of compliance with RFC822, cc:mail does very naughty
things to mail being forwarded. It adds something like @aaEXTERNAL
to the From: field which causes havoc. I know as little as I possibly can
get away with about cc:mail since as far as I can tell, it's an expensive
mistake, especially compared to PMail. Nevertheless, some sites use it
and I had to sort the above problem out for some of my users receiving
forwarded mail from there. So any outgoing address (the To: line)
processed by PegWaf which has @aaEXTERNAL at the end has that stuff
chopped off. It solved my problems here - if it gives you grief, please let
me know.

Be warned that this software breaks one of the UDG rules and writes
some warnings to the screen when PegWaf is run - it does this to make it
PERFECTLY clear to UDG users that their mail has been queued for a
gateway to send out. Pressing a key will speed up the disappearance of the
message which persists for no more than 5 seconds. I've had requests to
remove this screen - if it really bugs you, let me know.

I have added one feature to mimic Waffle's optional storing of a copy of
all outgoing mail. This can be made to work by setting the outbox option
(see the docs) just like the inbox option can be controlled (see the rmail
docs). This can be useful for snooping I suppose and certainly useful for
checking out a new system. Anyway, it's now there.

If you add a parameter to your Waffle static file (named pw.outbox),
PegWaf will add a copy of any outgoing mail item to a mailbox by that
name and will also keep a similarly named index file up to date in the
same directory. Any file extension you give will be ignored ! For
example, if you add

pw.outbox: f:\Waffle\spool\outbox\outbox

to your Waffle static file, assuming the outbox directory exists under your
spool directory, PegWaf will make a mailbox called outbox.f and an index
file called outbox.i and keep them up to date with a copy of any mail
going out through your gateway if it has appropriate rights to do so.
Therein lies the rub.

For this to work, any user calling PegWaf MUST have just about ALL
rights to the nominated directory - since it needs to read and write the
index and mail files. So group everyone needs this right for local users to
be able to call PegWaf with enough access to this file and the remote
gateway login needs these rights.

As a result, if you get this option working, any boy or girl einstein on
your (inter)network with half a brain will be inevitable be able to read
everyone's outgoing mail if they've a mind to do so. This is FAR from
ideal ! Still, you can do it if that doesn't bother you. One trick you could
do is create a dummy user called say "ispy" under the Waffle user
directory, give everyone and the PegWaf remote login all rights to that
directory, make your outbox f:\Waffle\user\ispy\mailbox and then add a
forward.p file so all of ispy's mail gets routinely forwarded to someone
such as the supervisor. But this is getting ridiculous.

---------------Known Problems---------------------

PegWaf does NOT know how to handle bang paths for your smarthost. It
dumbly assumes that the name of the smart host PRECEEDS the first
exclamation mark. Note that the smarthost parameter is found in your
Waffle static file and that domain names (names with . in them) are NOT
permitted. Remember, spool files will be placed in a subdirectory of your
spool directory - the name of that subdirectory will be your smarthost
name truncated to 8 characters if necessary. Anyone who wants to tell me
how to handle bang paths is welcome to email me. There's nothing in
RFC822 about them.

The Waffle scheduler can easily get very confused and crazy if the real
time clock on the gateway workstation gets out of synchronization with
that on the server - since time stamps start getting older or newer than
they should be. Solution ? - automatically reboot the workstation every
morning or run the netware settime utility regularly. I prefer the automatic
reboot (a schedule entry runs reboot.com every morning at 1am) as it
starts the gateway cleanly every day.

PegWaf needs a drive to use for mapping to a remote server if you need
to use a gateway on a remote server. I've chosen P: and if you have
problems mapping to a remote server, double check that P: is not already
mapped somewhere else.

I recently had intermittent problems with getting PegWaf to work on a
few workstations. When pegwaf failed (due to low memory or strange
drive mappings) - the container (.wom) files were left lying in the sender's
mail directories and the sender was not aware that the mail had failed to
get out the gateway. So I wrote a utility called udgdemon which accepts as
a parameter the path to the root of the directory where pmail writes those
temporary container files (sys:mail/[user hex id] in the example given
above) and which converts any orphaned .wom files into new mail with an
explanation prepended. This at least warns the sender to resend the items.
It should be run as part of your scheduled waffle events for maximum
safety.

--------Bug reports, problems and help--------------

Please report program bugs directly to me at
rossl@gmu.wh.su.edu.au

Discussion of problems and requests for help may be directed to me at the
above address. Please DO NOT bug either David Harris or Tom Dell,
neither of whom had anything to do with this package other than indirectly
by writing fine software !

--------------STANDALONE operation----------------

As of the release of February 1993, this package now attempts to support
stand alone operation. Be warned and advised - I've never needed to use
this - I've made some simple (!) changes which might work but you will
be beta testing - please feed back any problems immediately you find them
and I'll try and fix them. My simple testing suggests that it basically
should work and I'd be grateful for feedback - positive or negative.

It detects standalone mode if there is no netware shell available. This will
be the case on a standalone PC or Lantastic or netware lite. If you are
perverse enough to want standalone mode while hooked up to a network
then you'll need to reboot your machine and NOT load netx. If netx is
there, you'll get network mode.

This might be coaxed to work on non-Netware LAN's and of course on
stand alone PC's. You still need a working Waffle and you still need to
get PMail working for whatever your setup is. The gateway certainly
won't work otherwise. PMail needs a pmuser dos environment variable set
in the autoexec.bat file with something like
set PMUSER=yourname

PegWaf makes use of the pmuser dos environment variable to get the
current user's name. From this it constructs the return address as
[username]@[your Waffle host name]
for outgoing mail. PegWaf in standalone mode will refuse to work if this
environment variable is not set. 

WafPeg constructs the destination directory for .cnm files (incoming mail
from Waffle for PMail) based on the -n "Netware mail directory"
parameter on the WafPeg command line (eg -nc:\incoming). To this is
added the Waffle user name (which is the name of the Waffle\user
directory where the Waffle mail was found. 

In other words, WafPeg works in promiscuous mode, distributing mail
from Waffle to users of the same name in PMail mail directories. This
behaviour can be radically altered by use of the -a (All Mail to pmuser)
parameter. When the -a parameter is used, if the pmuser environment
variable is set, ALL INCOMING MAIL FOUND IN ANY Waffle USER
DIRECTORY IS CONVERTED TO PMail FORMAT IN THE PMUSER
SUBDIRECTORY OF THE "NETWARE" MAIL DIRECTORY. 

The mail directory is controlled with the -n parameter but defaults to the
Waffle user directory in standalone mode.

So if you have several Waffle users with mail on a standalone machine,
and you use c:\PMail as the directory under which each person finds their
new PMail files, run WafPeg with a command line like this :-
WafPeg -nc:\PMail
and Waffle incoming mail from the file mailbox.f in \Waffle\user\jim will
be left in PMail format in c:\PMail\jim.

If PMUSER is set to JOHN and you add the -a parameter, Waffle
incoming mail from ANY Waffle user directory will end up in
c:\PMail\john

This may seem like bizarre behaviour, but it's the only way I could think
of coping with the possibility that several users might share a standalone
machine. Alternatively one person might use several aliases on a
standalone machine (!) in which case the -a parameter should be used....

Thanks to Todd Booth for several suggestions and much help with
debugging the standalone mode.

--------Conditions of use, legal stuff--------------

The names PMail, Waffle, PegWaf and WafPeg might be registered trade
marks or something for all I know. I assume that David Harris and Tom
Dell aren't going to sue me for using the names of their packages (PMail
is registered for sure !). Anyone using the words WafPeg or PegWaf
should have their mouths washed out with soap unless they say "excuse
me" immediately.

The author will grant to any person or organization a licence to use the
software and documentation which make up this UDG kit provided that
the following 5 specific conditions are complied with :- 

1) No specific fee may be charged for distribution or copying of these
materials. Distribution through a fee charging network (such as a cd-rom,
telephone or other telecommunications system) is permitted provided that
no charge other than the usual agreed fee for such a service is incurred by
the recipient as a result of the distribution. 

2) No fee of any kind may be charged by any person or organization in
relation to the installation or use of any of these copyright materials.
Consultants and others proposing to charge fees for providing materials
and associated services (such as installation) may only do so after
negotiating an appropriate fee and obtaining the written consent of the
author from the address below. 

3) In using these materials, the user agrees to accept all responsibility for
all damages whether direct or consequential arising from the use of these
materials. The user must be made to understand that these copyright
materials are made available with no guarantee or warranty of any kind
from the copyright holder. 

4) The installer and user agree to accept all responsibility for damages and
costs incurred directly or indirectly as a result of installation or
distribution of these materials.

5) No alteration whatsoever may be made to any of the contents of this kit
in the process of reproduction, distribution or use. The kit may be
repackaged provided only that all of the contents of this kit reappear in
their original form when unpackaged.

In other words, this UDG kit, comprising this documentation and
accompanying software, are free. They are supplied on an as is basis with
no guarantee of fitness for purpose of any kind. You use it at your own
peril. If anything of yours breaks as a consequence of copying, installating
or using of any of the components of this package, your only guarantee is
that you still own all the pieces. Remember, you get what you pay for.

This kit may be freely copied and reproduced provided it is not modified
in any way and provided it is copied or reproduced in it's entirety. The
documentation and software which comprise this package remain the
copyright property of the author and the author reserves the right to
prosecute for breach of copyright if any of the above conditions of use are
violated. Please notify the author if you become aware of any violation of
these conditions.

Ross Lazarus
may 1993

email:    rossl@gmu.wh.su.edu.au
mail:     29 Francis St 
          Bondi NSW 2026
          Australia

Tel:      (+61 2) 633 7946
