rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/OSK/TELECOM/OSKBox.lzh/read.me

Text File | 1993-04-25 | 14KB | 263 lines

4/25/93

Here is source code for a mailbox system I call the OSKbox that I've
been running for over 4 years on my Hazelwood Uniquad 20x (68020
system).  Note that I say "mailbox system" instead of "program," because
this is a system consisting of several cooperative programs.  Here is an
abbreviated cast of characters:

  "host" runs in the background detached from any terminals and
  communicates with a TNC via WA8DED host mode.  One task running
  "host" is required for each packet port.  "host" communicates with
  other programs via pipes.

  "mailbox" is the primary user interface to the mail system.  It can be
  run from any terminal (in fact, "mailbox" can't tell the difference
  between a terminal and a user on a TNC), but is usually forked by "host"
  in response to a user connection on a packet port.

  "msgproc" is executed in the background every time a new message arrives
  at the BBS.  It checks for forwarding loops, missing address parts, and
  can be told to modify selected message fields or place messages on hold.

  "cron" is a program that also runs in the background detached from any
  terminals and executes a schedule of things to do, specifically
  maintenance programs that the mailbox needs done from time to time.  A
  couple of those things are...

  "forward" does what it says: initiates packet connections to other BBSs
  and passes messages to them.  It can also request a reverse forward from
  other BBSs.

  "beacon" makes up a string of text describing pending mail for local
  users for broadcast as a UI frame via "host".

There are more programs, but you get the idea.  Functionality is added
by writing new programs that interface with the rest of the system,
rather than incrementally growing a single monolithic program.  Note
that no terminals need be dedicated to the packet BBS, you are free to
continue to use your OSK computer for other purposes while the BBS is
running.  (Provided, of course, that you have sufficient memory.)  You
also retain the ability to make outgoing connections via the hostube
program without shutting down the BBS.  You can also have dial-in ports
to give hams who aren't on packet access to the mailbox.  (Very handy
for remote sysop operations.)

Note that a mailbox is only one possible packet application.  Using
the host program, just about any kind of application program can be
hooked up to packet.  If you get any neat ideas, pass them on.


73, eric

Eric Williams
5860 Clinton Ave.
Richmond, CA 94805
Home: 510-237-9909    Work: 510-524-3950    Fax: [phone]
Packet: WD6CMU @ WD6CMU.#NOCAL.CA.USA.NA  Internet: [e-mail]

                    ***** GETTING STARTED *****

Documentation is admittedly sparse.  Look in MAILBOX/CC/DOCS and
MAILBOX/HELP.  If you get stuck, drop me a note and I'll write up
something that fills in the gaps.

First thing that needs to be done is to convert your TNC(s) to WA8DED
host mode firmware.  This is available for the TNC-1 (put those old,
dusty TNCs to work!), TNC-2 (and clones) and PK-88.  Check out the
MAILBOX/FILES/WA8DED directory, code and documentation are stored there.
(I'm missing the PK-88 version, let me know if you need it and I'll
track it down.)  Burn a ROM with your version and plug it in.  WA8DED has
a terminal mode that is very usable (some prefer it to the TAPR
interface), and, more importantly, a computer-literate host mode that
OSKbox requires.  (I'd also like to support AEA host mode, but don't have
any hardware.  If you'd like to take on the project, let me know.)

The next thing is to set up your disk directories.  I've set up this
floppy in approximately the same configuration as my hard disk.  The
MAILBOX/startup file contains the boot-up procedure I use for my
particular configuration, and I've also included a couple of sample
forward and distribution files.  If you have extra memory, you may want
to store your forwarding tables and bulletin distribution lists on RAM
disk to speed up execution.  If so, you need to modify the DISDIR and
FWDIR #define's in mailbox.h, then add to your startup procedure to copy
the files to RAM from disk.

Next, you need to customize the code and compile it.  Customization
consists mainly of modifying mailbox.h.  The relevant #define's are:

  HOME     Place where the mail directory file, user directory file,
           info file, HELP directory, etc. live.

  DISDIR   Place where distribution list files (*.dis) live.

  FWDIR    Place where forward files (*.fwd) live.

  MYCALL   Your callsign.

  MYHADDR  Your hierarchical address in the BBS network.

  MYZIP    Your zipcode.

  MYQTH    Optional field that shows up in your forwarding header.
           (Keep it short, lest ye be flamed by your brother sysop!)

  BANNER   Identifying line that shows up when people connect.

  UTC      Number of hours from GMT to local time.  (Yes, this means you
           re-compile twice a year for daylight saving's time.  It's a crock,
           but I haven't come up with a better system yet.)

Then take a look at the makefile to make sure it is compatible with your
machine, then use it to compile the programs in MAILBOX/CC.  (I've also
thrown in some orbit calculation programs in MAILBOX/SAT.  The program
sun.c will have to be customized with your latitude, longitude,
altitude, and GMT time difference.)

Next task is to build the mail directory file.  This file is held in
memory during mailbox execution and is about 178K, so I would recommend a
minimum of 1MB to run the system.  (Alternatively, you can reduce memory
requirements by reducing the value of MAXMAIL.  Re-compile *everything* if
you change this!)  Go to your HOME directory (defined above) and run
makemail, redirecting output to mail_dir ("makemail >mail_dir").  The
resulting file will be loaded into memory when mbinit is run in your
startup procedure.

Next, get your forward and distribution files set up.  Look at the ones
I provided for examples.  Throw together an info file (brag about how
great your system is) and maybe a motd (Message Of The Day) file.  Then
change MISC/crontab to schedule forwarding and other things the way you
want.  Customize your startup file, and let 'er rip!  You can probably
leave the hold.lst and bidclean.lst files for when you are up and
running and have a better idea of what local conditions are like.

                     *****  RANDOM NOTES *****

To help shut the BBS down, I've written a program called quit, which
will send a signal #2 to the specified process(es).  This signal will
cause mailbox tasks to force their users to log off, shut down host
tasks in an orderly manner, and make cron stop.  (It should also make
forward coast to a stop, but it doesn't seem to always work.) If you
have time for a graceful shut-down, quit cron and then create a text
file named "down" in the FWDIR directory.  This will cause anyone
connecting (acutally, any non-sysop) to receive the contents of the file
(which can explain the reason for going down, when you'll be back up,
etc.), followed by an immediate disconnect.  When all the mailbox,
forward, etc.  tasks have come to a halt, quit the host tasks and turn
the system off.

When you run mbinit, the mail directory file is loaded into memory and
the directory locking events are created.  The mailbox system will not
run without these things being done, but mbinit will not run correctly
if either one already exist.  Therefore, it might be possible to end up
in a situation where you have to clean out the old mailbox stuff in
order to re-initialize the system.  Aside from cycling power, this can
be done with a few utilities.  The standard unlink program can be
repeatedly called on mail_dir until the link count goes to zero and the
module goes away.  There are no standard utilities for dealing with
system events, so I wrote a few: evstat, evsig, evulink and evdel.
evstat will tell you what the events currently look like.  evdel will
delete events, but only if their link count is already zero.  evulink
will decrement the link count so you can reach that state.  When
everything is cleaned out, mbinit can be run to re-initialize the memory
structures.

evsig can be used to signal an event, possibly unlocking the mail
directory module from a dead program.  Use this with care!  If you
generate a superfluous signal, there is no way to fix it except to reset
everything and start over.  The existing programs should never need this
unless there is a physical glitch in your system.

Even though OSKbox uses 32 bits to represent message numbers, other
systems in the network are not capable of handling numbers over 65535.
When you approach this number, re-numbering becomes necessary.  Go to
your HOME directory, shut down cron and all the ports, make a back-up of
your mail_dir file, and run renumber.  Redirect the output from renumber
to a file (eg: "renumber >mail_dir.xref), this is a list of old message
numbers versus new ones, so you can match them up in the log file if
need be.  Run the mailbox locally and make sure everything looks OK,
then bring the ports and cron back up.

The log file gets appended to every time something significant happens.
One problem with the OS-9 file system is that files that get
incrementally expanded eventually get so fragmented that their block
table fills up and you can't add any more to it.  To prevent this from
happening, you'll see a line in the crontab file that periodically
copies the log file to a temporary file, deletes the original, and
renames the temp file.  This should clean up the worst of the
fragmentation and keep the log file alive.  The same thing happens to
the user file when cleanup runs.


                ***** THE FINE ART OF SYSOPING *****

Since OSK users tend to be on the fringe of "normal" computer hobyists,
I thought it might be appropriate to suggest some aspects of operating a
packet BBS that they might not be aware of.

The most important thing you should keep in mind about running a packet
BBS is that, more than any other aspect of amateur radio, it is a
cooperative effort.  A packet BBS that operates in isolation is a
contradiction in terms, and the only way you are going to do anything
useful with OSKbox is with the cooperation of your fellow sysops.  If
there is a local organization of sysops, join it.  Cultivate your
relationship with your fellow sysops and never, NEVER let yourself get
into emotional feuds with them.  After all, it's only a hobby, and life
has enough things in it to get upset over that really count.

Always keep your forwarding header short.  Make yourself available to
your users and other sysops.  Try to read your mail at least once a day
and *answer* it.  Give other sysops your phone numbers.  (Nothing is
more frustrating than to try and contact another sysop about a mutual
problem, only to be responded to by un-answered mail or un-returned
phone calls.)  Keep your forward files up to date and deal swiftly
with forwarding loops, stuck mail, incorrect addresses, etc.  Keep your
radios, TNCs and computer operating reliably.  Lots of people think they
want to be a sysop until they find out how much real work it can be.

The second most important thing to remember is that you exist to serve
your users.  The messages you pass mean nothing if there is nobody who
wants to use your box to read them.  Operate your box appropriately,
making rules of operation for your users that enhance the usability of
the box rather than reducing it.

Users can also be a pain -- they ask stupid questions, send stupid
christmas card pictures, give incorrect commands, type messages with no
carriage returns, give wrong addresses and then complain about delivery
times, and expect the system to be smart enough to compensate for the
fact that they are too lazy to read the help messages.  Most of the
time, the problems are educational, and all that is needed is a friendly
suggestion and some detailed instructions.  Your local sysop
organization probably has some kind of educational program that can use
your help.  A maxim I find useful is Hanlon's razor:

Never attribute to malice that which is adequately explained by stupidity.

99% of the time, education is all that is needed, but there *are* some
people who either don't give a damn or are actively seeking to disrupt
things and you might just run into one.  When that happens and you are
in danger of experiencing significant system problems (don't sweat the
small stuff), CALMLY lay down the law, tell him what you expect of him
and what he can expect of you.  If he doesn't comply, shut him out with
the PNG (Personna Non Gratta) flag in the user file, forget about him,
and go back to work.  If he or anyone else disputes your actions, flood
them with the copious evidence of the PNG's crimes you've collected up
to this point, and stand by your decision.  In the final analysis, it's
*your* station, and you have the right to eject whoever you want, but
temper this with the knowledge that you operate within a network and
that you want to show your actions are reasonable.


***********************************************************************

Things added since 7/11/92:

o Moved message file deletion out of loop in cleanup to reduce window
  of vulnerability during directory shuffel.

o Added msgproc for message processing.  Generalized message field
  modification description (hold.lst file).

o Fixed bug in forward that caused cycle abort if timeout occured while
  waiting for first prompt from target BBS.